feat(DLPilot): v0.4.0 — PySide6-Fluent-Widgets UI and Light theme

DLPilot/AGENTS.md

@@ -8,7 +8,7 @@
 
 仓库 `LT8619C_Debug_Tools` 是 LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板的**调试上位机工具集**，
 上游主仓库（固件）为 `hulk/LT8619C_DLPC3421_HDMI`（同 Gitea 实例 `gitea.hulk.wang`），
-本仓库本机路径 `E:\Hulk-Coding\LT8619C_DLPC3421_HDMI`。
+上游固件本机路径 `E:\Hulk-Coding\LT8619C_DLPC3421_HDMI`；工具仓库路径 `E:\Hulk-Coding\LT8619C_Debug_Tools`。
 DLPilot 工作在两端：HDMI **源端**（PC 显卡侧，EDID/分辨率/图案）与**光机控制端**
 （RS485 → 板载 GD32E230 网关 → DLPC3421）。寄存器语义判读基线（0x606E 位交换 /
 0x606D 整组顺序）与光机协议规程都在上游仓库 `doc/architecture/` 与 `protocols.md`，不在本仓库。
@@ -34,15 +34,15 @@ DLPilot/
 
 | 文件 | 角色 |
 |---|---|
-| `src/hdmi_gui.py` | 入口: argparse 命令行分发(--dump/--edid-fields/--test-pattern/--dlpc-cmd/--seconds), GUI 委托 app_gui |
-| `src/app_gui.py` | CustomTkinter 主界面: 双栏仪表盘(左 HDMI 源端五卡/右 光机四卡), 光强/定时快捷滑条 |
+| `src/hdmi_gui.py` | 入口: argparse 命令行分发(--dump/--edid-fields/--test-pattern/--dlpc-cmd/--seconds), GUI 委托 app_fluent |
+| `src/app_fluent.py` | PySide6-Fluent-Widgets 主界面: 双栏仪表盘(左 HDMI 源端五卡/右 光机五卡), 光强/定时快捷滑条 |
 | `src/display_win.py` | Win32 显示器枚举/分辨率切换/智能拓扑(纯 ctypes) |
 | `src/edid_parse.py` | EDID 1.4/CEA-861 解析(纯标准库, 上游 lt8619c_edid.c 以此为参考解码器) |
 | `src/patterns.py` | 测试图案全屏投屏窗口(tkinter, ESC 退出, 测试卡区域 1:1 居中) |
 | `src/config.py` | 运行目录定位(BASE_DIR)与 pattern_slots.json 读写(slots/area/serial 三键) |
 | `src/dlpc_rs485.py` | 光机 RS485 协议模块: 帧构造/增量解析/译码表/预设命令/串口线程(DLPC485) |
 | `src/selftest_rs485.py` | 光机协议自检(对照上游实测帧向量, 无硬件回归, 改协议代码后必跑) |
-| `src/build_exe.py` | PyInstaller 打包 → `release/DLPilot.exe`（onefile/noconsole, 内嵌图标+pyserial+customtkinter） |
+| `src/build_exe.py` | PyInstaller 打包 → `release/DLPilot.exe`（onefile/noconsole, 内嵌图标+pyserial+PySide6-Fluent-Widgets） |
 | `src/package_release.py` | 复制图案到 release/(平铺) → `release/DLPilot-v<ver>-win64.zip`（校验栏位引用完整性; release/ 与 zip 内容一致） |
 | `src/publish_gitea.py` | 建/复用 Gitea Release 并上传 zip（tag 默认取 zip 文件名） |
 | `src/hdmi_source.ps1/.bat` | 独立 PowerShell 命令行工具（自包含，与 GUI 无代码共享） |
@@ -51,17 +51,18 @@ DLPilot/
 | `src/la_wave_analyzer*.py` | 逻辑分析仪 CSV 波形判读（2/3 通道，40MHz 像素时钟假设） |
 | `src/logos/make_ico.py` | svg/png → ico（写在其自身目录） |
 | `release/pattern_slots.json` | 预置栏位：西门子星/波带片/综合测试卡，area=640x360；`serial` 键记忆光机串口 |
-| `UI参考布局.svg/.png` | 界面布局设计稿（app_gui.py 双栏布局的规格来源, 随分支入库） |
+| `UI参考布局.svg/.png` | 界面布局设计稿（app_fluent.py 双栏布局的规格来源, 随分支入库） |
 
 ## 3. 代码不变量（改 hdmi_gui.py 必须维持）
 
-1. **依赖分层**：CLI/显示/EDID/协议/配置模块（display_win/edid_parse/patterns/config/
-   dlpc_rs485）纯标准库；customtkinter 是 GUI（app_gui）的**硬依赖**（装了才能开界面，
-   CLI 不受影响）。可选依赖仍走"try-import + HAS_* 标志 + 缺失降级"模式：Pillow、
-   pyserial——缺失时对应功能禁用/提示安装，其余功能必须照常工作。
-2. **模块边界**：hdmi_gui.py 只是入口, 不放实现; GUI 不直接碰 ctypes/winreg
-   （显示器走 display_win, EDID 走 edid_parse）; pyserial 只准在 dlpc_rs485.py 里 import
-   （hdmi_gui/app_gui 经 `dlpc_rs485.HAS_SERIAL` 与 `DLPC485` 类间接使用）。
+1. **依赖分层**：CLI/显示/EDID/协议/配置模块（display_win/edid_parse/config/
+   dlpc_rs485）纯标准库；PySide6-Fluent-Widgets 是 GUI（app_fluent）的**硬依赖**（装了
+   才能开界面，CLI 不受影响），GUI 图案窗口使用 Qt，CLI 图案窗口由 patterns.py 使用 tkinter 创建。可选依赖
+   仍走"try-import + HAS_* 标志 + 缺失降级"模式：Pillow、pyserial——缺失时对应功能
+   禁用/提示安装，其余功能必须照常工作。
+2. **模块边界**：hdmi_gui.py 只是入口, 不放实现; GUI 的显示器/EDID 访问走 display_win/edid_parse；ctypes 仅用于
+   单实例锁、Windows 标题栏与 frozen DLL 加载; pyserial 只准在 dlpc_rs485.py 里 import
+   （hdmi_gui/app_fluent 经 `dlpc_rs485.HAS_SERIAL` 与 `DLPC485` 类间接使用）。
 3. **BASE_DIR 语义**（定义在 config.py）：frozen（PyInstaller onefile）时
    `BASE_DIR=exe 所在目录`（`sys.executable`），源码运行时 `=config.py 所在目录`
    （即 src/）。所有用户数据（pattern_slots.json、自定义图片）都写/读自 BASE_DIR
@@ -80,17 +81,18 @@ DLPilot/
 9. **EDID 来源是注册表**（`HKLM\SYSTEM\CurrentControlSet\Enum\DISPLAY\...\Device Parameters\EDID`），
    不是 WMI/DDC；exe 的 noconsole 版无 stdout，`--dump/--edid-fields` 只在源码/控制台版可用。
 10. **光机串口线程回调不直接碰 GUI**：DLPC485 的 on_event/on_status 在后台线程触发，
-    必须经 `queue.Queue` + `root.after(80, …)` 轮询投递回主线程（现行 `_poll_dlpc` 模式，
+    必须经 `queue.Queue` + Qt 定时器轮询投递回主线程（现行 `_poll_dlpc` 模式，
     与 I2C-Inject 的 Injector 同源）；退出路径（关窗与 `--seconds` 自动关）都会走到
-    `App.destroy()`，在那里 `dlpc.close()` 收线程。
+    `App.closeEvent()`，在那里 `dlpc.close()` 收线程。
 11. **pattern_slots.json 格式**：`{'area', 'slots', 'serial'}` 三键共存；load 兼容旧版
     纯数组（无 area）与无 serial 键两种历史格式，save 永远写全三键。`serial` 子键为
     `{port, baud, bytesize(8/7/6/5), parity(N/E/O), stopbits(1/2)}`，旧配置缺子键按
     默认 8-N-1 补齐。
-12. **GUI = app_gui.py 双栏仪表盘**（规格：`DLPilot/UI参考布局.svg`）：左列 HDMI 源端
-    五卡（显示器/模式/EDID 信息/测试图案/hex），右列光机四卡（串口/数据/命令/滑条），
-    顶栏 Dark/Light/System 切换（ttk.Treeview 颜色随动）。打包必须 `--collect-all
-    customtkinter`（build_exe.py 已内置，勿删）——CTk 主题/字体数据缺失会让 exe 启动即崩。
+12. **GUI = app_fluent.py 双栏仪表盘**（规格：`DLPilot/UI参考布局.svg`）：左列 HDMI 源端
+    五卡（显示器/模式/EDID 信息/测试图案/hex），右列光机五卡（串口/数据/电源/命令/滑条），
+    支持的模式和 EDID 信息默认折叠；顶栏 Dark/Light/System 切换。Light/Dark 同时更新
+    Fluent 主题、Qt 调色板、容器样式与 Windows DWM 标题栏，勿只调用 setTheme。
+    PD 协议成功显示绿色，FPDO 仍独立判定。打包必须收集 `qfluentwidgets` 资源，并加入 Windows 系统 `icuuc.dll`，否则 QtCore 可能被其它 ICU DLL 解析失败。
 
 ## 4. 领域语义（测试值都有含义，勿"顺手改"）
 
@@ -128,7 +130,7 @@ python gen_bw_patterns.py ; python gen_solid_colors.py   # 仅当改了图案生
 python build_exe.py            # → ../release/DLPilot.exe（缺 PyInstaller 会自动 pip install）
 python build_exe.py --debug    # 附加带控制台的 DLPilot-console.exe（调试 --dump 用）
 python package_release.py <版本>   # → ../release/DLPilot-v<版本>-win64.zip
-python publish_gitea.py DLPilot-v<版本>-win64.zip --replace --insecure   # 上传(需 GITEA_TOKEN)
+python publish_gitea.py ../release/DLPilot-v<版本>-win64.zip --replace --insecure   # 上传(需 GITEA_TOKEN)
 ```
 
 发布约定：
@@ -153,13 +155,12 @@ python publish_gitea.py DLPilot-v<版本>-win64.zip --replace --insecure   # 上
 - GUI 与 hdmi_source.ps1 各自独立实现显示器枚举，行为可能微差（GUI 与 `-List` 序号一致，
   但与"设置"面板序号无保证）；多屏操作前先确认序号；
 - `pattern_slots.json` 兼容两种历史格式，写出只写新格式（详见 §3.11）；
-- CustomTkinter 6.x：`CTkComboBox` 不支持 `textvariable`（用 `.set()/.get()`）；`CTkTextbox`
-  的 `tag_config` 在部分版本不可用，app_gui 已 try/except 兜底为单色；同一容器内
-  grid/pack 不可混用（卡片用 grid 挂进列，卡片内部一律 pack——`_card` 返回 (卡片, 内容)）；
+- 旧版 `app_gui.py` 仅保留作历史对照，当前入口使用 `app_fluent.py`；新增或修改界面时
+  应遵循 PySide6-Fluent-Widgets 的控件和 Qt 布局，不要把旧版 CustomTkinter 依赖带回入口。
 
 ## 7. 验证清单（改完代码后）
 
-1. `python -m py_compile src/*.py` —— 全模块可编译；
+1. `python -m compileall -q src`（在 DLPilot/ 下） —— 全模块可编译；
 2. `python selftest_rs485.py` —— 光机协议回归（改 dlpc_rs485.py 后必跑，向量来自上游 protocols.md）；
 3. `python hdmi_gui.py --seconds 5` —— GUI 冒烟（自动开关）；
 4. `python hdmi_gui.py --test-pattern Checker --area 800x600 --seconds 3` —— 投图链路；
@@ -167,3 +168,12 @@ python publish_gitea.py DLPilot-v<版本>-win64.zip --replace --insecure   # 上
 6. `python hdmi_gui.py --dlpc-cmd M999`（不带 --port）—— 应明确报错而非崩溃（无硬件时的优雅降级）；
 7. `python build_exe.py` → 双击 release/DLPilot.exe 确认图标/双栏布局/投图/光机区渲染；
 8. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。
+
+## 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 提交。
+  发布使用仓库预置配置，临时打包后恢复本机文件，勿将运行态配置悄悄提交。