# agent.md — 项目开发需求与进度管理

> 按 `C:\Users\Lenovo\.zcode\AGENTS.md`（用户级默认指令·默认工作约定）维护：
> 记录项目约定与开发进度——已完成功能清单、已提出但尚未实现的计划——随开发持续更新。
> 工程约束与构建规程在各工具 `AGENTS.md`；使用说明在根与各工具 README。
> 内容以仓库工件为准，每次完成开发或有新需求提出后同步更新本文。

## 1. 项目定位与约定

- 本仓库是**全部调试工具的收纳仓**（起家于 **LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板**
  调试配套）。原名 `LT8619C_Debug_Tools`，2026-09-28 更名 `HW-Debug-Tools`：Gitea 已改名
  （旧地址自动重定向）、本地目录与 remote 同步更名；Gitea Release 同日清理为各已发布工具
  仅保留最新版（DLPilot v0.4.0 / EDID-Viewer v0.1.0 / SerialMate v0.1.0），
  旧 release 删除但 tag 与提交历史保留。服务上游固件仓 `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）+ 电源检查。
  - **EDID-viewer**：Windows 显示器 EDID 只读查看器（Fluent UI）。
  - **SerialMate**：RS485/串口调试助手，帧格式（包头/板ID/LEN/CRC）可定制，
    默认兼容 DLPilot 光机协议；payload 字符串/HEX 显示、4 通道曲线、payload
    自动包装发送。
  - **I2C-Lab**（2026-10-02 新启，即 §3.5 三合一需求落地）：I2C 总线监控调试台。
    阶段一=纯被动监控：RP2040 probe 固件（pico-sdk C，PIO 边沿捕获 + 核1 实时
    解码 + USB CDC `=`/`!` 命令行，250MHz）+ PC GUI（Fluent，事务流/地址过滤/
    CSV/逻辑分析仪式波形快照/演示模式）。主机读写（复活 I2C-Inject 择机注入）
    与从机模拟在路线图。解码语义权威 `I2C-Lab/src/i2cdec.py`。
  - **I2C-Inject**：RP2040 固件 + PC GUI，demo 板 I2C 总线择机注入读写寄存器。
    **2026-09-25 起暂停开发**，代码与固件保留备查；**2026-10-02 起后续开发并入
    I2C-Lab**（接线/回显约定与解码算法已继承过去）。
- 子模块引用：`gd32e230f8_firmware_merge_tool/`（2026-09-30 接入，git submodule 指向
  `hulk/gd32e230f8_firmware_merge_tool`）——GD32E230 APP/BL 合成补齐
  （`_UPDATE.bin`/`_BL.bin`）+ DAPLink Flash GUI 烧录。代码、版本与发布均在原仓库
  独立管理，本仓只锁指针；新克隆 `git submodule update --init` 拉取，跟进上游
  `git submodule update --remote gd32e230f8_firmware_merge_tool` 后随本仓提交新指针。
- 镜像约定：`EDID-viewer` 主目录（`E:\Hulk-Coding\HW-Debug-Tools\EDID-viewer`）
  改动后需 robocopy /MIR 同步到 `E:\Hulk-Coding\LT8619C\_Debug\_Tools\EDID-viewer`
  （排除 .venv/build/__pycache__/.git，zip 不同步）。
- 图标约定（2026-10-10 立）：全部工具共用 **logo 家族版式**（512 黑底 + 工具色圆角块
  + 上行域词黑字/下行角色词白字，Arial Bold 146px 基准自适应；颜色不参与家族识别，
  现分配橙 `#FF9900`×4、绿 `#00C878`×2、青 `#00C8D7`×1，紫 `#A78BFA` 暂未分配）；软件内按钮只用
  FluentIcon 白名单、文本内用单色 Unicode 符号（→ ← ⚠ ⏳ ⚙）。**唯一权威 `icons/`**：
  约定文档 `icons/README.md` + 统一生成器 `icons/make_icon.py`（含 `--check`
  复现校验与 `--preview` 家族预览图；各工具内旧 make_ico 脚本保留作历史对照，不再维护）。
- 发布约定：源码与打包产物（exe、运行配置）入库；发布 zip 不入库，只上传 Gitea Release。

## 2. 开发进度（已完成功能清单）

### 2.1 DLPilot — 最新发布 v0.4.3（2026-10-13）
- 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 覆盖）；远端标签与附件已核对。
- **v0.4.3（2026-10-13）**：修复长会话越跑越卡/命令无响应——收发日志手工
  cursor 裁剪用实例级枚举访问，PySide6 6.11 必抛 AttributeError 且异常打断
  `_poll_dlpc` 队列消费（FilmForge 同案）；改 `setMaximumBlockCount(500)`
  环形裁剪 + 逐事件兜底 + 新增 `selftest_log.py` 回归。tag `DLPilot-v0.4.3`
  指向 `c91b4aa`。详见 `DLPilot/AGENTS.md` §9。

### 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 字节）已核对。

### 2.3 SerialMate — v0.1.0（2026-09-27，首版）
- **更名**：原名 SerialAssistant（目录/exe/文档/配置同步更名；旧配置
  serial_assistant.json 首次启动自动迁移为 serial_mate.json；更名时的图标为
  波形+RS485 母题，后统一为家族版式，见 §2.6）。用户确认 "SerialMate 吧"（2026-09-27）。
- **已发布**：commit d133906 推送 main 并打 tag `SerialMate-v0.1.0`，
  Release 附件 `SerialMate-v0.1.0-win64.zip`（63.7 MB）已上传核对。
- 协议：**帧构成令牌序列可定制**（`HDR ID LEN PAYLOAD CRC` + 十六进制字面量
  同步头，收发共用布局仅包头分方向；支持字段换序/无板ID/多字节同步头，LEN
  口径 payload 长度/到帧尾/整帧三种）、5 种 CRC 算法 × 3 种覆盖范围，默认与
  DLPilot 光机 RS485 协议一致（D5/B5/01/SUM8/不含包头）；增量解析前缀逐位
  对齐 + CRC 失败逐字节重同步；自测 64 项全 PASS（DLPilot 实测帧向量 +
  CRC 标准校验值 + 布局换序/LEN 口径向量 + 布局模糊往返）。
- 链路：串口参数热切换、半双工友好发送队列（未连接丢弃）、解析/透传双模式
  热切、`loop://` 虚拟回环自检 13 项全 PASS（组帧→发送→接收→解析→曲线提取）。
- GUI（PySide6-Fluent-Widgets，用户指定沿用 Qt 方案）：帧构成/LEN 口径可视化
  编辑，payload 字符串/HEX 切换（半透明底色高亮）、原始帧 hex、时间戳、日志
  保存；4 通道曲线（三种提取 + 倍率，**弹窗独立**：时间窗滑笔回看、纵轴刻度、
  悬停读值、暂停渲染/自动Y/滚轮缩放/拖动 Y 轴）；发送自动包装（输入 payload
  自动组帧，`/` 分隔多条依次发）、HEX 直发、周期发送、组帧实时预览、历史
  回溯、回车发送；主题跟随系统；标题栏版本号 + 关于弹窗 + 图标（波形 RS485）。
- 板型档案（2026-09-27 实机反馈追加）：不同板子的"协议参数+命令预设表"存为
  命名档案（board_profiles.json，不入库，首次运行生成默认 DLPilot 板型），
  发送卡一键切换/新建/存为/删除/表格编辑/重载。
- 发布：SerialMate.exe 已入库（随帧构成功能重建），zip/Release 未发布
  （待用户验收后走 package_release + publish_gitea）。
- **v0.1.1（2026-10-13）发布**：接收路径修复（时间戳改 link 线程到达时刻打戳、
  接收日志批量插入+5000 行上限+积压折叠、通道配置缓存），详见
  `SerialMate/ISSUE_rx_timestamp_and_lag.md` 与其 AGENTS.md §7。tag
  `SerialMate-v0.1.1` 指向 `7a236a6`，Release 附件
  `SerialMate-v0.1.1-win64.zip`（63.6 MB）。

### 2.4 I2C-Inject — ⏸ 暂停开发（2026-09-25）
- 已完成：RP2040 注入器固件（MicroPython，内置 viper 总线嗅探）、PC 端 GUI、
  demo 板寄存器语义实测（0x606E bit5=镜像 D[7:0]、0x606D 整组顺序，逻辑分析仪
  双色交叉验证）。
- 状态：暂停开发，代码与固件保留备查，README 顶部有状态横幅；后续开发并入
  I2C-Lab（2026-10-02，见 §2.5/§3.5）。

### 2.5 I2C-Lab — v0.1.0 已就绪（2026-10-02，待真机验收后发布）
- **定位**：I2C 总线监控调试台（原 §3.5 三合一需求的监控阶段）；三区目录 +
  双文档对齐全仓约定；I2C-Inject 定位为留档，本工具独立续接。
- **固件**（`firmware/`，pico-sdk C，PICO_BOARD=pico）：单 PIO SM `bus_watch`
  （变沿即压 FIFO，push noblock，~40ns 分辨率）+ 核1 时间戳/解码状态机（语义
  与 i2cdec.py 一致，含 56 字节长事务截断）+ 核0 USB CDC CLI（?/v/mon/
  stats/wave/boot）；250MHz/vreg 1.15V；边沿环 16k（wave 快照，暂停换一致性）
  + 事务环 256。
- **PC 端**（`src/`）：i2cdec.py（边沿→事务/T·W 行语法/CSV/参考编码器，自测
  73 项全绿：100k/400k 往返+时间戳对齐、随机鲁棒、截断 L 标志）、probelink.py
  （行协议链路线程）、waveview.py（QPainter 波形：滚轮缩放/拖动/双击适配/
  START-STOP 刻线/事务标签）、main.py（Fluent 双栏：串口卡/监控卡/事务表/
  波形卡/固件日志 + 演示模式）、theme/config 同源；selftest_gui.py 29 项全绿；
  build/package/publish 三件套适配（发布 zip 含 UF2）。
- **构建链（本机打通并记录踩坑）**：pico-sdk 2.3.1（ghproxy 代理克隆）+
  tinyusb 0.18.0（gitee 镜像）+ Arm GNU 13.3；pioasm 宿主编译用 ziglang
  （pip 装，预置 CMakeCache 分号列表法）；UF2 用自制 make_uf2.py（objcopy→bin
  →UF2，往返自检 + 与真机 MicroPython UF2 逐字段核对一致），绕开 picotool
  的 github 依赖。
- **产物**：I2C-Lab.exe（63.8MB）+ firmware/i2c_lab.uf2/.bin 保留本地
  release/（交付物不入库，`.gitignore` 已挡，2026-10-13 起）；
  zip/Release 待真机验收后走流水线（tag `I2C-Lab-v0.1.0`）。

### 2.6 仓库级基础设施 — 图标家族约定与统一生成器（2026-10-10）
- **`icons/` 目录**：`README.md`（风格与内容约定 + 应用点总表 + 新工具接入清单）
  + `make_icon.py`（六工具统一生成器，吸收 DLPilot/EDID-viewer/SerialMate/
  I2C-Inject/FlashTool 五份分散脚本）+ `preview.png` 家族预览图。
- **复现验证**：`--check` 逐像素比对，DLPilot/EDID-viewer/SerialMate/I2C-Inject
  全 SAME（EDID 的 134/116px 历史版式以显式 override 保真）。
- **修正 I2C-Lab 图标**：第二行自 I2C-Inject 复制 SVG 后一直误为 "Inject"，
  已改 "Lab"（png/ico/svg 重生成；exe 为入库旧图，下次 build_exe 打包生效）。
- **发现待办（子模块内）**：FlashTool 图标 "FLASH" 146px 宽 485px 超出 436px
  色块（两端黑字落黑底不可见），家族自适应规则可修正，但需在其原仓库执行并提交。
- **FilmForge 图标（2026-10-10）**：热压模具温控监视台（独立仓
  `E:\Hulk-Coding\FilmForge`，GD32F4 固件 + GUI 上位机）按家族版式出图——
  上行 `FILM`/下行 `Forge`、青 `#00C8D7`（取自其温度曲线/主题青，按钮 `#29F1FF`
  太亮故取深一档；与其 Dark 曲线配色常量一致），产物落在其
  `GUI/logos/filmforge.{png,ico,svg}`（`build_exe.py:30` 预留路径）；
  并在其 `GUI/app_fluent.py` 补上运行时 `setWindowIcon`（_MEIPASS/_源码双路，
  此前缺失），`selftest_gui.py` 48 项 ALL PASS。图标改动需在其原仓库提交。

## 3. 开发需求与计划（已提出、尚未实现）

### 3.1 DLPilot
- ~~【待素材】校准图案~~（已完成，2026-10-13 `bcb03e2`）：CeramixNano 系列 6 张
  校准图（黑/白/caliPoint/circle_640p/contrast/Sharpness_XY_3）二进制直存
  assets/+release/ 平铺（用户素材，无生成脚本），slots 栏位接入、
  package_release 收集规则扩展；随 v0.4.3 之后的下次发布进 zip。
- 【待真机帧·低优先】M305 回归向量是按协议推演的（selftest_rs485.py:90 起，
  0x8CA0=36000mW 为推演值）：真机功率显示已实测对接，仅剩把自测向量换成真机抓包，
  让无硬件回归更贴近真机。
- 【新需求·已确认可行（2026-09-25）】画面镜像（横/纵独立翻转，任意来源画面）：
  投影观看方向（正投/背投/吊装）需要源信号预先翻转。DLPC3421 原生支持——I2C 14h
  "写入显示图像方向"（b1=长轴翻转、b2=短轴翻转，两轴独立；15h 读回；b0 旋转仅竖排源
  且 DLPC3421 不支持）。实施分两段：
  - 上游固件（协议权威在上游仓）：`dlpc3421.h` 已定义 14h/15h 命令号但驱动未实现——
    照 `dlpc3421_set/get_mirror_lock_control` 模式补 set/get 函数，再暴露为 M 命令
    （现有 M981~M983 是只读调试命令，可续编 M984=设置/M985=读取，命名以上游为准），
    登记进 protocols.md；上电/软重启后是否自动恢复保存的方向由固件决定。
    **命名陷阱**：现有 `set/get_mirror_lock_control`（39h"镜片锁定控制"）是出厂 DMD
    接口锁定校准用，不是图像镜像，勿混用。
  - 上位机 DLPilot：`dlpc_rs485.py` 加命令封装，光机卡加"水平镜像/垂直镜像"开关并
    读回回显；用方向不对称图案（如 bw_sweep/文字图）实测确认长轴/短轴与横/纵的对应。
  - 备选（若固件暂不动）：DLPilot 自投图案/自定义图片可在 Qt 渲染时翻转（仅覆盖测试
    内容）；任意桌面内容 Windows 标准 API 只有 180°（=两轴同时），单方向翻转做不到。

### 3.2 EDID-Viewer
- EDID 对比、字节差异与固件数组导出。
- HDMI Forum VRR/ALLM/FRL/DSC、DisplayID 与高级色彩数据解析（第一版有意不解，
  保留原始块供分析）。
- 与实际输出时序和桥接芯片寄存器联合诊断。
- 实机验收缺口：HDMI 热插拔、多屏、跨屏 DPI、最大化/恢复与导入导出完整交互
  （见 `EDID-viewer/VALIDATION.md`）。

### 3.3 SerialMate
- 【待真机】光机实机收发与温度曲线实测（M201 ×0.1 提取），当前仅回环验证。
- ~~【无图标】assets/serial-mate.ico 未生成~~（已生成并随家族统一，见 §2.6）。
- 发送批处理脚本化（延时/循环/等待应答）；曲线数据导出 CSV。

### 3.4 I2C-Inject
- 并入 I2C-Lab 路线（见 §3.5）；本目录不再单列计划。

### 3.5 I2C-Lab 后续阶段（2026-10-02 起续接，监控已就绪见 §2.5）
- 【下一阶段】**主机模式**：probe 作 I2C 主机——总线扫描（scan）、读写
  （wr/rd），复活 I2C-Inject 择机注入语义（静置窗口避让主控轮询/重试/读回
  校验）；GUI 加寄存器读写卡。硬件 I2C 与嗅探 PIO 可并存（先停监控再发射，
  或 PIO 分频采样回看自身发射）。
- 【规划】**从机模拟**：RP2040 硬件 I2C 从机模式 + PC 端应答表（寄存器值/
  回调），顶替传感器验证主机驱动。
- 【监控增强】协议语义插件（LT8619C bank/寄存器注释）、触发抓取、长记录
  落盘、SMBus PEC/10bit 地址注记、波形按事务着色。
- 【待真机验收 v0.1.0】清单见 `I2C-Lab/AGENTS.md` §3（枚举/实听/注入对照/
  400kHz 波形/30min 稳定性），验收后打 tag 发布。
- 平台结论（2026-09-30 沿用）：固件 pico-sdk C（MicroPython 无从机 API、
  嗅探无法实时流式）；硬件 2× BPI-Pico-RP2040 + 2× JI2C；GP8=SDA GP9=SCL、
  USB CDC `=`/`!` 回显、挂 live 板只接 GND/SDA/SCL 不加上拉——均已落地。

### 3.6 明确不做（决策，非待办）
- **0x606E 的 0x40/0x80 位交换不再单独实测**（2026-09-25 用户确认：当前行为正常、
  符合预期，bit5 实测基线已够用；原【待硬件】项关闭）。
- TI 原始 I2C 命令透传不做：GD32 网关固件只收 ASCII M 命令集（v0.2.0 显式决策）。
- DLPilot 不引入 pyserial/Pillow 硬依赖：保持 try-import + HAS_* 标志 + 缺失降级。
- EDID-Viewer 不承诺实时 DDC 抓取：数据来自 Windows/显卡驱动，可能缓存或覆盖。

## 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） |
| 4 | "串口断不开" | 表象是断开逻辑 bug，实际根源是**双实例互抢串口** → 单实例锁 + 串口占用提示（e87bf14） |
| 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 起窗） |
| 15 | PySide6 6.11 实例级枚举访问 | 手工 cursor 裁剪 `cursor.Start` 在 6.11 必抛 AttributeError（实例级访问被移除，类级简写 `Qt.Xxx` 仍可用）；槽内异常不崩溃只静默失败，还会打断同函数后半段与外层消费循环 → 日志裁剪一律用 `setMaximumBlockCount`，队列消费逐事件兜底 try/except。DLPilot v0.4.2 中雷（v0.4.3 修），SerialMate v0.1.0 末期同案 |

## 5. 快速上手（完整规程见各工具 AGENTS.md）

```powershell
# DLPilot（完整清单：DLPilot/AGENTS.md §5/§7）
cd DLPilot/src
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

# SerialMate（完整清单：SerialMate/AGENTS.md）
cd SerialMate/src
python selftest.py ; python selftest_loop.py           # 协议回归 + 链路回环(改协议/链路后必跑)
python main.py --seconds 5                             # GUI 冒烟
python build_exe.py ; python package_release.py 0.1.0  # 打包 + 组装 zip
python publish_gitea.py ../release/SerialMate-v0.1.0-win64.zip --insecure

# I2C-Lab（完整清单：I2C-Lab/AGENTS.md）
cd I2C-Lab/src
python selftest.py ; python selftest_gui.py            # 解码回归 + GUI 结构自检(改 i2cdec/main 后必跑)
python main.py --seconds 5 --demo                      # GUI 冒烟(演示模式, 无硬件)
python build_exe.py ; python package_release.py 0.1.0  # 打包 + 组装 zip(含固件 UF2)
python publish_gitea.py ../release/I2C-Lab-v0.1.0-win64.zip --insecure
```

上游协议/寄存器语义问题先查上游仓 `protocols.md` 与 `doc/architecture/`；
本仓改动约束以两个工具的 AGENTS.md 为准——**其中领域语义的测试值
（55/AA/FF、640x360、800x600@60）有明确用途，勿顺手改**。