139 lines
9.4 KiB
Markdown
139 lines
9.4 KiB
Markdown
# agent.md — 仓库交接档案（供后续 Agent 接手）
|
||
|
||
> **成文方式**：2026-09-20 由一次会话从 git 全部 40 次提交（6243b8c…e354423）、
|
||
> `DLPilot/AGENTS.md`、各级 README、`.zcode/plans/` 计划文件还原整理；不含任何口头
|
||
> 讨论内容，一切以仓库工件为准。
|
||
>
|
||
> **分工**：本文管"宏观脉络、决策史、待办"；工程约定/不变量/构建规程在
|
||
> `DLPilot/AGENTS.md`（**改代码前必读**）；使用说明在根与各工具 README。
|
||
|
||
## 1. 项目定位
|
||
|
||
- 本仓库是 **LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板**的调试上位机工具集，
|
||
服务上游固件仓 `hulk/LT8619C_DLPC3421_HDMI`（本机路径
|
||
`E:\Hulk-Coding\LT8619C_DLPC3421_HDMI`，同 Gitea 实例 gitea.hulk.wang）。
|
||
光机 RS485 协议**唯一权威**是上游仓 `protocols.md`，本仓不维护协议副本。
|
||
- 两个工具：
|
||
- **DLPilot**（原 HDMI-Tool）＝"3D 光固化光机调试台"：HDMI 源端（EDID/分辨率/
|
||
测试图案投屏）+ 光机控制（RS485→板上 GD32E230 网关→DLPC3421）+ 电源检查
|
||
（PD 自检/FPDO 挡位判定/功率检测）。
|
||
- **I2C-Inject**：RP2040 固件 + PC GUI，在 demo 板 I2C 总线上择机注入读写 LT8619C
|
||
寄存器（避让主控 500ms 轮询，写后读回校验）。
|
||
|
||
## 2. 当前状态快照（2026-09-20）
|
||
|
||
- `APP_VERSION = '0.3.6'`（`DLPilot/src/app_gui.py:43`）；工作树干净；
|
||
本地 main == origin/main（e354423），**全部提交已推送**。
|
||
- Gitea Releases 最新为 **v0.3.5** —— v0.3.6 已打包、已提交，**但未发布**（见 §5.1）。
|
||
- `release/DLPilot.exe` 与 `release/DLPilot-v0.3.6-win64.zip` 是 2026-09-18 15:32
|
||
同批构建，**均已包含最后的二进制载荷 hex 日志修复**（e354423），内容一致。
|
||
- `release/pattern_slots.json` 记忆的光机串口为 COM15（115200 8-N-1）。
|
||
|
||
## 3. 开发方向主线（时间线）
|
||
|
||
**阶段 0 · 寄存器语义实测期（09-03）**
|
||
I2C-Inject + HDMI-Tool 首版落库。核心成果：0x606E 位交换 / 0x606D 整组顺序两个
|
||
寄存器语义经 demo 板逻辑分析仪双色交叉实测确立（LA 波形判读脚本
|
||
`la_wave_analyzer*.py` 即为该过程产物，配套 I2C-Inject 固件内置总线嗅探）。
|
||
|
||
**阶段 1 · 工程化与发布流水线（09-10）**
|
||
确立三区目录（src 人写 / assets 可再生 / release 交付）+ 双文档（README 给人 /
|
||
AGENTS.md 给 Agent）；打通 build_exe → package_release → publish_gitea 流水线，
|
||
发布 HDMI-Tool v0.1.0。同期收录启动强制扩展显示拓扑与波形/注入脚本。
|
||
|
||
**阶段 2 · 光机 RS485 控制集成（09-11，v0.2.0）**
|
||
新增 `dlpc_rs485.py`：帧构造 `D5 01 LEN <ASCII> CRC` / 响应 `B5 TYPE LEN <payload> CRC`
|
||
（累加和校验）、增量解析、译码表、DLPC485 链路类（daemon 线程+队列+回调，
|
||
模式照搬 I2C-Inject 的 Injector）。启动拓扑从"无条件扩展"改为**智能判定**。
|
||
串口下拉显示设备描述（CH344 多口可辨）。计划文件 `.zcode/plans/plan-sess_a1d8*.md`
|
||
即此阶段方案，已完整执行。
|
||
|
||
**阶段 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 双行图标。
|
||
|
||
**阶段 4 · 体验打磨（09-14，v0.3.1/0.3.2/0.3.3）**
|
||
投屏退出语义两轮更名（"恢复桌面"→"停止投屏"→"停止测试图像"）；标题栏版本号；
|
||
清理残余 HDMI-Tool 引用与目录更名；修复 USB 拔出后同参数重连失效（掉线分支
|
||
清 `_open_key`）。
|
||
|
||
**阶段 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）。
|
||
|
||
## 4. 尝试过 / 推翻过 / 反复调过的思路（勿重蹈）
|
||
|
||
| # | 问题 | 最初做法 → 最终做法 / 教训 |
|
||
|---|---|---|
|
||
| 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 | 窗口最大化卡顿 | EDID 信息区 CTkScrollableFrame+40 余个逐行 Label，最大化时逐控件重绘 → 换 CTkTextbox 整体重排，开销低一个量级（30bc224） |
|
||
| 6 | 启动强制扩展拓扑 | 无条件 `SetDisplayConfig` 扩展会打扰用户自选拓扑（如家里"仅第二屏幕"）→ 仅当未激活显示器 EDID 厂商字节为转接板签名 `61 93`("XLS") 时才拉回（d9ecff4） |
|
||
| 7 | GUI 框架 | 原生 tkinter → CustomTkinter 双栏仪表盘（84838e3）；CTk 6.x 怪癖（ComboBox 无 textvariable、tag_config 不可用、grid/pack 不可混用）已兜底，见 AGENTS.md §6 |
|
||
| 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. 未实操 / 待办清单（接手者从这里挑活）
|
||
|
||
### 5.1 【发布缺口，一条命令的事】v0.3.6 未发布
|
||
代码、exe、zip 均已就绪并推送（§2），但 Gitea 上没有 v0.3.6 Release、也没有
|
||
DLPilot-v0.3.6 tag（本地 tag 止于 v0.3.5）。待执行：
|
||
|
||
```powershell
|
||
cd DLPilot/src
|
||
python publish_gitea.py DLPilot-v0.3.6-win64.zip --replace --insecure # 需 GITEA_TOKEN
|
||
```
|
||
|
||
（GITEA_TOKEN 已 setx 为用户级环境变量，新开会话自动继承；Release 经 API 创建时
|
||
远端会自动建 tag。）
|
||
|
||
### 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 的"更新：2026-09-11"停在旧日期，但正文内容其实已
|
||
同步到 M305/电源检查；下次改动时顺手刷新即可。
|
||
|
||
### 5.6 【明确"不做"，非待办】
|
||
- **TI 原始 I2C 命令透传不做**：GD32 网关固件只收 ASCII M 命令集（v0.2.0 计划的
|
||
显式决策）。
|
||
- **不引入 pyserial 硬依赖**：保持 try-import + HAS_* 标志 + 缺失降级的可选依赖
|
||
模式（Pillow 同理）。
|
||
|
||
## 6. 快速上手（完整规程见 DLPilot/AGENTS.md §5/§7）
|
||
|
||
```powershell
|
||
cd DLPilot/src
|
||
python -m py_compile *.py # 编译检查
|
||
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.3.7 # 组装 zip（版本号从 0.3.7 起，0.3.6 已占用）
|
||
python publish_gitea.py DLPilot-v0.3.7-win64.zip --replace --insecure
|
||
```
|
||
|
||
上游协议/寄存器语义问题先查上游仓 `protocols.md` 与 `doc/architecture/`；
|
||
本仓改动约束（目录契约、12 条代码不变量、领域测试值含义）以 `DLPilot/AGENTS.md`
|
||
为准，**其中领域语义的测试值（55/AA/FF、640x360、800x600@60）有明确用途，勿顺手改**。
|