From 733847a58c3acf4d1d1f719545429f7fabb5802c Mon Sep 17 00:00:00 2001 From: hulk Date: Fri, 25 Sep 2026 01:48:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20agent=20=E6=96=87=E6=A1=A3=E4=BD=93?= =?UTF-8?q?=E7=B3=BB=E6=8C=89=E7=94=A8=E6=88=B7=E7=BA=A7=E9=BB=98=E8=AE=A4?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E7=BA=A6=E5=AE=9A=E9=87=8D=E6=95=B4=E4=B8=BA?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E9=9C=80=E6=B1=82=E4=B8=8E=E8=BF=9B=E5=BA=A6?= =?UTF-8?q?=E7=AE=A1=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DLPilot/AGENTS.md | 19 ++-- EDID-viewer/AGENTS.md | 11 +- README.md | 7 +- agent.md | 234 ++++++++++++++++++++++-------------------- 4 files changed, 148 insertions(+), 123 deletions(-) diff --git a/DLPilot/AGENTS.md b/DLPilot/AGENTS.md index f01a4dc..46ff30e 100644 --- a/DLPilot/AGENTS.md +++ b/DLPilot/AGENTS.md @@ -1,8 +1,8 @@ -# AGENTS.md — DLPilot 工程档案（供 AI/Agent 使用） +# AGENTS.md — DLPilot 工程档案（开发约束与进度） -> **本文档面向 AI/Agent**，是人类文档 [README.md](README.md) 的姊妹篇，两者不重叠： -> README 回答"这是什么、怎么用"；本文回答"代码怎么组织、怎么构建发布、改动时哪些约束不能破坏"。 -> 任何 Agent 在修改本目录代码前应先读完本文。 +> 人类文档 [README.md](README.md) 回答"这是什么、怎么用"；本文记录"代码怎么组织、 +> 怎么构建发布、改动时哪些约束不能破坏"，兼作本工具的进度记录。 +> 修改本目录代码前先读完本文。仓库整体的开发需求与进度管理见根目录 `agent.md`。 ## 1. 项目定位 @@ -169,11 +169,14 @@ python publish_gitea.py ../release/DLPilot-v<版本>-win64.zip --replace --insec 7. `python build_exe.py` → 双击 release/DLPilot.exe 确认图标/双栏布局/投图/光机区渲染； 8. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。 -## 8. v0.4.0 交接（2026-09-24） +## 8. v0.4.0 进度记录（2026-09-24） - 入口已切换 `app_fluent.py`；历史 `app_gui.py` 保留，不改其历史版本号。 - 本次验证：源码编译通过、RS485 自测 ALL PASS、Qt 离屏浅色渲染、正式 EXE 定时退出码 0。 原生桌面自动化不可用，未完成成品 Light 截图；未将硬件功能标记为本次实机验证通过。 -- 发布须将本次源码、文档、EXE 纳入同一个提交，确认远端标签指向该提交；zip 不入库。 -- `release/pattern_slots.json` 的本机串口记忆改动、外部 `EDID-viewer/` 不属于本次 UI 提交。 - 发布使用仓库预置配置，临时打包后恢复本机文件，勿将运行态配置悄悄提交。 +- 发布已将本次源码、文档、EXE 纳入同一个提交（`74b64dc`），远端标签 `DLPilot-v0.4.0` + 指向该提交、附件已核对；zip 不入库。 +- `release/pattern_slots.json` 的本机串口记忆改动属于运行态配置，勿随提交悄悄带入； + 发布使用仓库预置配置，临时打包后恢复本机文件。 +- 关联动态：EDID-Viewer 已于 2026-09-25 从本工具的"源端 EDID 查看"需求独立成工具 + 入库并发布 v0.1.0，与本目录无代码共享；I2C-Inject 已标记暂停开发（详见根 `agent.md`）。 diff --git a/EDID-viewer/AGENTS.md b/EDID-viewer/AGENTS.md index 2572b7b..af1e1a0 100644 --- a/EDID-viewer/AGENTS.md +++ b/EDID-viewer/AGENTS.md @@ -1,4 +1,4 @@ -# EDID Viewer — 环境与任务声明 +# EDID Viewer — 开发需求与进度 ## 基本环境 - 主项目位置：`E:\Hulk-Coding\LT8619C_Debug_Tools\EDID-viewer`；为兼容此前约定，已同步镜像到 `E:\Hulk-Coding\LT8619C\_Debug\_Tools\EDID-viewer`。 @@ -38,6 +38,15 @@ - 添加解析边界/错误数据测试。打包后验证实际可见窗口、缩放、刷新和导入导出流程。 - 第一版不完整解码 DisplayID、HDMI Forum VRR/DSC；保留原始块供分析。 +## 进度记录 +- **v0.1.0（2026-09-25，已发布）**：目录对齐 DLPilot 三区结构；onefile 打包 + （`src/build_exe.py` 生成 spec，剔除 PATH 上 Poppler/Conda 的版本化 ICU）；Light + 主题三件套修复（setTheme + QPalette/应用级 QSS + DWM 标题栏）；右上角"关于"； + 标签 `EDID-Viewer-v0.1.0` 与 Release 附件已核对（66,483,477 字节）。 +- 验证明细见 `VALIDATION.md`；实机验收缺口：HDMI 热插拔、多屏、跨屏 DPI、 + 最大化/恢复与导入导出完整交互流程。 +- 根目录 `agent.md` 为仓库整体的开发需求与进度管理文档。 + ## 后续建议 - EDID 对比、字节差异与固件数组导出。 - HDMI Forum VRR/ALLM/FRL/DSC、DisplayID 与高级色彩数据解析。 diff --git a/README.md b/README.md index 77db2a9..9fe1b84 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,8 @@ LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板调试配套上位机工 ## 目录结构 每个工具内统一三区：**src/ 源代码（人写）** → **assets/ 生成资产（可再生成）** → -**release/ 打包与发布产物（机器生成）**；README.md 面向使用者，AGENTS.md 面向 AI/Agent（工程约定与构建规程）。 +**release/ 打包与发布产物（机器生成）**；README.md 面向使用者，AGENTS.md 记录工程约束与开发进度， +仓库整体的开发需求与进度管理见根目录 `agent.md`。 ``` LT8619C_Debug_Tools/ @@ -32,13 +33,13 @@ LT8619C_Debug_Tools/ │ ├── assets/ # 生成的测试图案 PNG（gen_*.py 产物） │ ├── release/ # 打包 exe + 运行配置（入库）；发布 zip（不入库） │ ├── README.md # 使用说明 -│ └── AGENTS.md # AI/Agent 工程档案 +│ └── AGENTS.md # 工程档案 ├── EDID-viewer/ │ ├── src/ # 界面/解析/WMI 读取 + 打包/发布脚本 │ ├── assets/ # 图标与生成脚本 │ ├── release/ # EDID-Viewer.exe + README（入库）；发布 zip（不入库） │ ├── README.md # 使用说明 -│ └── AGENTS.md # AI/Agent 工程档案 +│ └── AGENTS.md # 工程档案 ├── I2C-Inject/ # PC 端 GUI + RP2040 固件 + 打包 exe + 图标 + README ├── LICENSE └── README.md diff --git a/agent.md b/agent.md index f4593bd..94c16d7 100644 --- a/agent.md +++ b/agent.md @@ -1,143 +1,155 @@ -# agent.md — 仓库交接档案（供后续 Agent 接手） +# agent.md — 项目开发需求与进度管理 -> **成文方式**：2026-09-20 由一次会话从 git 全部 40 次提交（6243b8c…e354423）、 -> `DLPilot/AGENTS.md`、各级 README、`.zcode/plans/` 计划文件还原整理；不含任何口头 -> 讨论内容，一切以仓库工件为准。 -> -> **分工**：本文管"宏观脉络、决策史、待办"；工程约定/不变量/构建规程在 -> `DLPilot/AGENTS.md`（**改代码前必读**）；使用说明在根与各工具 README。 +> 按 `C:\Users\Lenovo\.zcode\AGENTS.md`（用户级默认指令·默认工作约定）维护： +> 记录项目约定与开发进度——已完成功能清单、已提出但尚未实现的计划——随开发持续更新。 +> 工程约束与构建规程在各工具 `AGENTS.md`；使用说明在根与各工具 README。 +> 内容以仓库工件为准，每次完成开发或有新需求提出后同步更新本文。 -## 1. 项目定位 +## 1. 项目定位与约定 - 本仓库是 **LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板**的调试上位机工具集， 服务上游固件仓 `hulk/LT8619C_DLPC3421_HDMI`（本机路径 `E:\Hulk-Coding\LT8619C_DLPC3421_HDMI`，同 Gitea 实例 gitea.hulk.wang）。 光机 RS485 协议**唯一权威**是上游仓 `protocols.md`，本仓不维护协议副本。 -- 两个工具： +- 工具链（全仓统一）：Python 3.14；GUI 用 PySide6 + PySide6-Fluent-Widgets，解析/协议 + 模块纯标准库；PyInstaller onefile 打包；发布流水线 build_exe → package_release → + publish_gitea（`GITEA_TOKEN` 用户级环境变量；实例 TLS 间歇抽风，实际请求加 + `--insecure`，详见 `DLPilot/AGENTS.md` §5）。 +- 结构约定：每个工具三区目录（**src/ 人写 / assets/ 可再生 / release/ 交付**）+ 双文档 + （README 使用说明 / AGENTS.md 工程约束与进度）。三个工具独立开发、独立打标签发布， + Release 列表按时间倒序混排于同一页面： - **DLPilot**（原 HDMI-Tool）＝"3D 光固化光机调试台"：HDMI 源端（EDID/分辨率/ - 测试图案投屏）+ 光机控制（RS485→板上 GD32E230 网关→DLPC3421）+ 电源检查 - （PD 自检/FPDO 挡位判定/功率检测）。 - - **I2C-Inject**：RP2040 固件 + PC GUI，在 demo 板 I2C 总线上择机注入读写 LT8619C - 寄存器（避让主控 500ms 轮询，写后读回校验）。 + 测试图案投屏）+ 光机控制（RS485→GD32E230 网关→DLPC3421）+ 电源检查。 + - **EDID-viewer**：Windows 显示器 EDID 只读查看器（Fluent UI）。 + - **I2C-Inject**：RP2040 固件 + PC GUI，demo 板 I2C 总线择机注入读写寄存器。 + **2026-09-25 起暂停开发**，代码与固件保留备查。 +- 镜像约定：`EDID-viewer` 主目录（`E:\Hulk-Coding\LT8619C_Debug_Tools\EDID-viewer`） + 改动后需 robocopy /MIR 同步到 `E:\Hulk-Coding\LT8619C\_Debug\_Tools\EDID-viewer` + （排除 .venv/build/__pycache__/.git，zip 不同步）。 +- 发布约定：源码与打包产物（exe、运行配置）入库；发布 zip 不入库，只上传 Gitea Release。 -## 2. 当前状态快照（2026-09-24，v0.4.0） +## 2. 开发进度（已完成功能清单） -- 当前入口为 `DLPilot/src/app_fluent.py`，`APP_VERSION = "0.4.0"`；使用 - PySide6-Fluent-Widgets。旧 `app_gui.py` 保留作历史对照，不再由入口加载。 -- 本次发布为 `DLPilot-v0.4.0`，源码、文档与 `release/DLPilot.exe` 合并为一个提交； - zip 只上传 Gitea Release，不入库。远端完成状态以标签和附件查询为准。 -- 支持的模式、EDID 信息默认折叠；修复标题栏图标与 PD 成功状态绿色显示。 -- Light 显式同步 Qt 调色板、容器背景与 Windows 标题栏，浅灰主背景、白色卡片、深色文字； - 保留 Dark/System 切换。主题不写入用户的 `pattern_slots.json`。 -- Qt 单文件打包收集 `qfluentwidgets` 资源与系统 `icuuc.dll`，启动注册并预加载 - Qt/Shiboken DLL，避免 QtCore 导入失败。 -- 已完成源码编译、无硬件 RS485 自测（ALL PASS）、Qt 离屏浅色渲染检查和正式 EXE - 定时启动退出（exit=0）。本次原生桌面自动化接口不可用，未完成成品 Light 截图； - 不应将离屏截图等同于成品完整视觉或硬件验收。 -- 本机 `release/pattern_slots.json` 的 COM5 运行配置与 `EDID-viewer/` 未跟踪目录 - 不属于本次发布；保留本地文件，提交及发布使用仓库预置配置。 +### 2.1 DLPilot — 最新发布 v0.4.0（2026-09-24） +- HDMI 源端：EDID 查看/逐字节解析、分辨率切换、智能显示拓扑（仅拉回转接板屏）、 + 纯色/黑白/测试卡全屏投屏、自定义槽位（pattern_slots.json）。 +- 光机控制：RS485 链路（`dlpc_rs485.py` 帧协议+线程）、开关光机/设光强/TEC 控温/ + 查温度电流，串口参数化。 +- 电源检查：PD 自检（M301→M302→M303 状态机）、FPDO 挡位判定、功率检测 + （M303+M304+M305 → V/mA/W 两位小数）。 +- 界面：PySide6-Fluent-Widgets 双栏仪表盘（v0.4.0 起），Light/Dark/System 主题 + （Fluent 主题 + Qt 调色板 + QSS + DWM 标题栏三件套同步）。 +- 发布：v0.1.0（HDMI-Tool）→ v0.2.0 → v0.3.x → v0.4.0 均已上传 Gitea Release + （v0.3.6 未单独发布，功能被 v0.4.0 覆盖）；远端标签与附件已核对。 -## 3. 开发方向主线（时间线） +### 2.2 EDID-Viewer — 最新发布 v0.1.0（2026-09-25） +- 解析：EDID 1.x 基础身份/时序、CTA（音频 SAD/HDMI VSDB/CEC/HF-VSDB）、HDR 与 + 色彩能力、逐块校验与越界诊断（`edid.py` 纯标准库 + 9 项单测，含随机畸形数据 + 无崩溃检查）。 +- 数据获取：Windows WMI 只读枚举活动设备（HDMI/DP/内屏连接类型）；离线 + `.bin/.edid/.hex/.txt` 导入；BIN 与 JSON 报告导出。 +- 界面：Fluent 卡片布局、分组页签（设备与能力/时序/原始 HEX/完整 JSON）、右上角 + "关于"（v0.1.0）。 +- 主题：Light/Dark/dark1/dark2/跟随系统，三件套同步 + QSettings 持久化 + + 系统明暗变化响应。 +- 工程化：目录与发布流水线对齐 DLPilot（onefile exe 入库）；标签 + `EDID-Viewer-v0.1.0` 与 Release 附件（66,483,477 字节）已核对。 -**阶段 0 · 寄存器语义实测期（09-03）** -I2C-Inject + HDMI-Tool 首版落库。核心成果：0x606E 位交换 / 0x606D 整组顺序两个 -寄存器语义经 demo 板逻辑分析仪双色交叉实测确立（LA 波形判读脚本 -`la_wave_analyzer*.py` 即为该过程产物，配套 I2C-Inject 固件内置总线嗅探）。 +### 2.3 I2C-Inject — ⏸ 暂停开发（2026-09-25） +- 已完成：RP2040 注入器固件（MicroPython，内置 viper 总线嗅探）、PC 端 GUI、 + demo 板寄存器语义实测（0x606E bit5=镜像 D[7:0]、0x606D 整组顺序，逻辑分析仪 + 双色交叉验证）。 +- 状态：暂停开发，代码与固件保留备查，README 顶部有状态横幅。 -**阶段 1 · 工程化与发布流水线（09-10）** -确立三区目录（src 人写 / assets 可再生 / release 交付）+ 双文档（README 给人 / -AGENTS.md 给 Agent）；打通 build_exe → package_release → publish_gitea 流水线， -发布 HDMI-Tool v0.1.0。同期收录启动强制扩展显示拓扑与波形/注入脚本。 +## 3. 开发需求与计划（已提出、尚未实现） -**阶段 2 · 光机 RS485 控制集成（09-11，v0.2.0）** -新增 `dlpc_rs485.py`：帧构造 `D5 01 LEN CRC` / 响应 `B5 TYPE LEN CRC` -（累加和校验）、增量解析、译码表、DLPC485 链路类（daemon 线程+队列+回调， -模式照搬 I2C-Inject 的 Injector）。启动拓扑从"无条件扩展"改为**智能判定**。 -串口下拉显示设备描述（CH344 多口可辨）。计划文件 `.zcode/plans/plan-sess_a1d8*.md` -即此阶段方案，已完整执行。 +### 3.1 DLPilot +- 【待素材】校准图案槽位预置为空：第二排 5 个槽位为 3D 光固化测试/校准图预留 + （`file: null`）；素材到位后 assets/ → 生成脚本入库 → 更新 slots → 重新打包。 +- 【待真机帧】M305 回归向量是按协议推演的，拿到真机 M305 回包后替换 + （`selftest_rs485.py`）。 +- 【待硬件】0x606E 的 0x40/0x80 两组位交换实测：demo 板仅实测 bit5(0x20)。等转接板 + 点亮时验证；原计划用 I2C-Inject 注入，该工具已暂停——恢复实测时先解冻或改用 LA 判读。 -**阶段 3 · GUI 重构与产品化（09-12，v0.3.0）** -feature/ctk-ui 分支完成 CustomTkinter 双栏仪表盘重构（规格：`UI参考布局.svg`）； -产品更名 **HDMI-Tool → DLPilot**（3D 光固化光机调试台）；光机串口参数化（默认 -8-N-1）+ TEC 控制（M7/M8）与温度实时显示；DLP/Pilot 双行图标。 +### 3.2 EDID-Viewer +- EDID 对比、字节差异与固件数组导出。 +- HDMI Forum VRR/ALLM/FRL/DSC、DisplayID 与高级色彩数据解析（第一版有意不解， + 保留原始块供分析）。 +- 与实际输出时序和桥接芯片寄存器联合诊断。 +- 实机验收缺口：HDMI 热插拔、多屏、跨屏 DPI、最大化/恢复与导入导出完整交互 + （见 `EDID-viewer/VALIDATION.md`）。 -**阶段 4 · 体验打磨（09-14，v0.3.1/0.3.2/0.3.3）** -投屏退出语义两轮更名（"恢复桌面"→"停止投屏"→"停止测试图像"）；标题栏版本号； -清理残余 HDMI-Tool 引用与目录更名；修复 USB 拔出后同参数重连失效（掉线分支 -清 `_open_key`）。 +### 3.3 I2C-Inject +- 暂停开发期间不列计划；恢复时以其 README 现状为准，优先补 0x40/0x80 位交换实测 + （与 §3.1 第三条同源）。 -**阶段 5 · 电源检查卡（09-17~18，v0.3.4~0.3.6）** -- **电源自检**：M301(协议)→M302(挡位电流)→M303(实测电压) 三步帧驱动状态机， - FPDO 判定＝电压就近 PD 固定挡（5/9/12/15/20/28V ±5%）+ 挡位电流；12V 且 ≥3A - 绿底，挡位不符红底，无匹配 ERR（CH224Q 电压配置寄存器只写不可读，只能实测判定）。 -- **功率检测**：M303+M304+M305 三步序列 → 电压 V / 电流 mA / 功率 W（两位小数）。 -- **M30x 载荷是二进制例外**（SQ52205 实测）：大端原始值非 ASCII，必须走 - `payload_bytes()`；M303=u16 mV、M304=s16 补码 mA、M305=u32 mW（LEN=4）。 - 封装在 `payload_u16_be/payload_s16_be/payload_u32_be/format_power`。 -- 伴随一串稳定性修复（详见 §4）。 +### 3.4 明确不做（决策，非待办） +- TI 原始 I2C 命令透传不做：GD32 网关固件只收 ASCII M 命令集（v0.2.0 显式决策）。 +- DLPilot 不引入 pyserial/Pillow 硬依赖：保持 try-import + HAS_* 标志 + 缺失降级。 +- EDID-Viewer 不承诺实时 DDC 抓取：数据来自 Windows/显卡驱动，可能缓存或覆盖。 -**阶段 6 · Fluent UI 重写（09-24，v0.4.0）** -PySide6-Fluent-Widgets 替换 CustomTkinter 主界面，延续 EDID、测试图案、RS485、 -PD/功率/温度/电流及自定义槽位功能；GUI 图案窗口使用 Qt，CLI 图案仍走 tkinter。 -补齐模式/EDID 折叠、PD 成功状态颜色、图标、Light 调色板与 Qt 单文件 DLL 加载。 +## 4. 决策史：时间线与踩坑（勿重蹈） -## 4. 尝试过 / 推翻过 / 反复调过的思路（勿重蹈） +**阶段 0 · 寄存器语义实测期（09-03）**：I2C-Inject + HDMI-Tool 首版落库；0x606E +位交换 / 0x606D 整组顺序经 demo 板 LA 双色交叉实测确立（`la_wave_analyzer*.py` +即该过程产物）。 + +**阶段 1 · 工程化与发布流水线（09-10）**：确立三区目录 + 双文档；打通 +build_exe → package_release → publish_gitea，发布 HDMI-Tool v0.1.0。 + +**阶段 2 · 光机 RS485 控制集成（09-11，v0.2.0）**：新增 `dlpc_rs485.py`（帧构造/ +增量解析/译码表/DLPC485 链路类，模式照搬 I2C-Inject 的 Injector）；启动拓扑改智能判定。 + +**阶段 3 · GUI 重构与产品化（09-12，v0.3.0）**：CustomTkinter 双栏仪表盘 +（规格 `UI参考布局.svg`）；更名 HDMI-Tool → DLPilot；TEC 控制与温度实时显示。 + +**阶段 4 · 体验打磨（09-14，v0.3.1~0.3.3）**：投屏退出语义两轮更名；标题栏版本号； +修复 USB 拔出后同参数重连失效。 + +**阶段 5 · 电源检查卡（09-17~18，v0.3.4~0.3.6）**：电源自检状态机、功率检测、 +M30x 二进制载荷封装（详见踩坑 1~3、10）。 + +**阶段 6 · DLPilot Fluent UI 重写（09-24，v0.4.0）**：PySide6-Fluent-Widgets 替换 +CustomTkinter；补齐折叠、PD 状态颜色、Light 调色板与 Qt 单文件 DLL 加载。 + +**阶段 7 · EDID-Viewer 独立成工具（09-23~25，v0.1.0）**：从 DLPilot 的源端 EDID +需求独立；目录与流水线对齐；同期 I2C-Inject 标记暂停开发，根 README/agent.md +按三工具更新。 | # | 问题 | 最初做法 → 最终做法 / 教训 | |---|---|---| | 1 | 电源自检成功判定 | 先按 ASCII `ok` 前缀判成功 → 实机 M301 回包 payload=`PD` 无前缀被误判错误（9772a2b）→ **改按帧 TYPE=0xF0 译码分类**。教训：M30x 系列回包不能按文本判 | -| 2 | 功率值来源 | 先用 M303×M304 计算 P=UI 占位显示（2b7d103，"待固件功率命令"）→ 固件提供 M305 直读 u32 mW 后改为三步序列直读（9b29b6a） | -| 3 | 二进制载荷三连坑 | ① Frame.payload 解出乱码 → 用 `payload_bytes()` 取原始字节；② M305 是 LEN=4，复用双字节解析会错 → 按 kind 校验长度；③ 日志行含 NUL 导致复制被截断 → 二进制载荷日志行以 hex 展示（e354423） | +| 2 | 功率值来源 | 先用 M303×M304 计算 P=UI 占位显示（2b7d103）→ 固件提供 M305 直读 u32 mW 后改为三步序列直读（9b29b6a） | +| 3 | 二进制载荷三连坑 | ① `Frame.payload` 解出乱码 → 用 `payload_bytes()` 取原始字节；② M305 是 LEN=4，复用双字节解析会错 → 按 kind 校验长度；③ 日志行含 NUL 复制被截断 → 二进制载荷日志行以 hex 展示（e354423） | | 4 | "串口断不开" | 表象是断开逻辑 bug，实际根源是**双实例互抢串口** → 单实例锁 + 串口占用提示（e87bf14） | -| 5 | 窗口最大化卡顿 | EDID 信息区 CTkScrollableFrame+40 余个逐行 Label，最大化时逐控件重绘 → 换 CTkTextbox 整体重排，开销低一个量级（30bc224） | -| 6 | 启动强制扩展拓扑 | 无条件 `SetDisplayConfig` 扩展会打扰用户自选拓扑（如家里"仅第二屏幕"）→ 仅当未激活显示器 EDID 厂商字节为转接板签名 `61 93`("XLS") 时才拉回（d9ecff4） | -| 7 | GUI 框架 | 原生 tkinter → CustomTkinter 双栏仪表盘（84838e3）；v0.4.0 再迁移到 PySide6-Fluent-Widgets；旧 CTk 文件仅供历史对照 | -| 8 | 投屏退出按钮文案 | "恢复桌面"→"停止投屏"→"停止测试图像"（3f35ad2→b167ce3）：最终语义是关测试图窗口，与显示拓扑恢复无关 | -| 9 | USB 拔出后重连失效 | 掉线分支未清 `_open_key`，同参数重连被"参数未变"逻辑跳过 → 掉线同步清缓存（51e2f1c） | -| 10 | 电源自检卡死 | 帧路由引用未定义变量 `payload`（3f36ead），改名/重构时注意帧回调的作用域 | -| 11 | Gitea 发布 | python urllib 访问该实例间歇 `SSL: UNEXPECTED_EOF` → 必须 `--insecure`；`GET /releases/tags/{tag}` 的 assets 是纯数组而 `GET /releases/{id}` 是 `{items:[...]}`，publish_gitea.py 已兼容两种形状，勿"简化"；请求自动重试已加（f0f8073） | +| 5 | 窗口最大化卡顿 | CTkScrollableFrame+40 余个逐行 Label 最大化逐控件重绘 → 换 CTkTextbox 整体重排，开销低一个量级（30bc224） | +| 6 | 启动强制扩展拓扑 | 无条件 `SetDisplayConfig` 会打扰用户自选拓扑 → 仅当未激活显示器 EDID 厂商字节为转接板签名 `61 93`("XLS") 时才拉回（d9ecff4） | +| 7 | GUI 框架 | tkinter → CustomTkinter（84838e3）→ v0.4.0 PySide6-Fluent-Widgets；旧文件仅供历史对照 | +| 8 | 投屏退出按钮文案 | "恢复桌面"→"停止投屏"→"停止测试图像"（3f35ad2→b167ce3）：最终语义是关测试图窗口，与拓扑恢复无关 | +| 9 | USB 拔出后重连失效 | 掉线分支未清 `_open_key`，重连被"参数未变"跳过 → 掉线同步清缓存（51e2f1c） | +| 10 | 电源自检卡死 | 帧路由引用未定义变量 `payload`（3f36ead），改名/重构时注意帧回调作用域 | +| 11 | Gitea 发布 | urllib 间歇 `SSL: UNEXPECTED_EOF` → 必须 `--insecure`；`/releases/tags/{tag}` 的 assets 是纯数组而 `/releases/{id}` 是 `{items:[...]}`，publish_gitea.py 已兼容两种形状，勿"简化"；自动重试已加（f0f8073） | +| 12 | Fluent Light 主题发黑 | 只调 `setTheme` 仅刷新 Fluent 控件，QMainWindow/原生 QTabWidget/QStatusBar/标题栏仍跟系统深色 → **三件套**：setTheme + QPalette/应用级 QSS + DWM 属性 20/35/36（EDID-Viewer `theme.py`，DLPilot 同源） | +| 13 | PyInstaller 传 .spec 报错 | 给 .spec 再传 `--specpath` 报 "makespec options not valid" → spec 由 build_exe.py 生成后只传 distpath/workpath | +| 14 | onefile 冒烟"没窗口" | onefile 引导父进程 MainWindowTitle 恒为空，轮询父进程误判失败 → 按进程名找子进程窗口（EDID-Viewer 实测 ~2s 起窗） | -## 5. 未实操 / 待办清单（接手者从这里挑活） - -### 5.1 v0.4.0 发布交接 -v0.4.0 已覆盖未单独发布的 v0.3.6 功能与本次 Fluent UI 改动，无需另发 v0.3.6。 -发布时先推送代码与同提交标签，再上传 `DLPilot-v0.4.0-win64.zip`； -核对远端标签提交、附件名称/大小，并记录验证结果。若需补传，先查询资产，避免重复上传。 - -### 5.2 【待硬件】0x606E 的 0x40/0x80 两组位交换 -demo 板仅实测了 bit5(0x20)=镜像 D[7:0]；0x40/0x80 对另外两组**未单独实测**， -等自板（转接板）点亮时用 I2C-Inject 验证（见 I2C-Inject/README §3）。 - -### 5.3 【待素材】校准图案槽位预置为空 -测试图案卡第二排 5 个槽位 UI 标注"校准图案(齿轮改图)"，为 3D 光固化测试/校准图 -预留；`release/pattern_slots.json` 中这些槽位 `file: null`。拿到校准图素材后： -放 assets/ → 生成脚本入库 → 更新预置 slots → 重新打包。 - -### 5.4 【待真机帧】M305 回归向量是算法推演帧 -`selftest_rs485.py` 中 M303/M304 用真机帧，M305 向量是按协议推演的；拿到真机 -M305 回包后替换向量，使回归更实。 - -### 5.5 README 已同步 -本次已将根 README 与 DLPilot/README 的安装依赖、界面描述和日期更新到 v0.4.0。 - -### 5.6 【明确"不做"，非待办】 -- **TI 原始 I2C 命令透传不做**：GD32 网关固件只收 ASCII M 命令集（v0.2.0 计划的 - 显式决策）。 -- **不引入 pyserial 硬依赖**：保持 try-import + HAS_* 标志 + 缺失降级的可选依赖 - 模式（Pillow 同理）。 - -## 6. 快速上手（完整规程见 DLPilot/AGENTS.md §5/§7） +## 5. 快速上手（完整规程见各工具 AGENTS.md） ```powershell +# DLPilot（完整清单：DLPilot/AGENTS.md §5/§7） cd DLPilot/src -python -m compileall -q . # 编译检查 -python selftest_rs485.py # 光机协议回归（改 dlpc_rs485.py 后必跑） -python hdmi_gui.py --seconds 5 # GUI 冒烟 -python build_exe.py # 打包 → ../release/DLPilot.exe -python package_release.py 0.4.0 # 组装当前版本 zip；新版本先更新 APP_VERSION +python -m compileall -q . ; python selftest_rs485.py # 编译检查 + 光机协议回归 +python hdmi_gui.py --seconds 5 # GUI 冒烟 +python build_exe.py ; python package_release.py 0.4.0 # 打包 + 组装 zip python publish_gitea.py ../release/DLPilot-v0.4.0-win64.zip --replace --insecure + +# EDID-Viewer（完整清单：EDID-viewer/AGENTS.md） +cd EDID-viewer/src +python -m unittest # 9 项解析测试（改 edid.py 后必跑） +python build_exe.py ; python package_release.py 0.1.0 # 打包 + 组装 zip +python publish_gitea.py ../release/EDID-Viewer-v0.1.0-win64.zip --insecure ``` 上游协议/寄存器语义问题先查上游仓 `protocols.md` 与 `doc/architecture/`； -本仓改动约束（目录契约、12 条代码不变量、领域测试值含义）以 `DLPilot/AGENTS.md` -为准，**其中领域语义的测试值（55/AA/FF、640x360、800x600@60）有明确用途，勿顺手改**。 +本仓改动约束以两个工具的 AGENTS.md 为准——**其中领域语义的测试值 +（55/AA/FF、640x360、800x600@60）有明确用途，勿顺手改**。