HW-Debug-Tools/EDID-viewer/AGENTS.md

EDID Viewer — 开发需求与进度

基本环境

• 主项目位置：E:\Hulk-Coding\LT8619C_Debug_Tools\EDID-viewer；为兼容此前约定，已同步镜像到 E:\Hulk-Coding\LT8619C\_Debug\_Tools\EDID-viewer。
• Windows 10/11 x64；Python 3.14；PySide6 6.11.2（Qt 官方 Python 绑定）；PySide6-Fluent-Widgets 1.11.3。
• 使用项目 .venv；依赖见 requirements.txt；GUI 入口为 src/main.py（版本号在 src/main.py 的 APP_VERSION）。
• 独立工具，不依赖、不修改 LT8619C 固件或 DLPilot 工程。

工程结构与流水线（对齐 DLPilot 三区约定）

• 三区目录：src/ 人写代码（main / edid / windows_edid / theme / test_edid + 打包流水线）；assets/ 图标与生成脚本（可再生）；release/ 交付（EDID-Viewer.exe 入库 + README）。
• 打包单文件 exe：python src/build_exe.py（spec 由脚本生成到 src/build/，不入库；原 viewer.spec 的 ICU 排除逻辑已内置其中）。--debug 附带带控制台变体。
• 发布：python src/package_release.py <版本> 组装 release/EDID-Viewer-v*-win64.zip（zip 不入库，只上传 Gitea Release）；上传用 python src/publish_gitea.py <zip>，token 走环境变量 GITEA_TOKEN。
• 解析测试：cd src && python -m unittest（9 项，改 edid.py 后必跑）。

任务目标

1. 枚举 Windows 活动显示设备并读取 EDID 原始块。
2. 查看厂家代码、产品编号、名称、序列号、生产日期、分辨率和详细时序。
3. 展示 CTA 扩展、HDMI、音频、HDR、色彩能力和校验结果。
4. 支持离线 BIN/HEX 导入、BIN 和 JSON 报告导出。
5. Light / Dark / 跟随系统主题，持久化用户选择并响应系统主题变化。
6. 图标参考 DLPilot 黑底、橙色标签、白字，使用 EDID / Viewer 独立标识。

• Fluent 主题包含 dark1（蓝色）和 dark2（青色），两者均为显式深色模式；选中态文字必须保持高对比度。
• Fluent Widgets 版本已采用顶部操作区、下方信息卡片和分组页签；后续布局调整需保持信息层级清晰。

Fluent Widgets 版本

• 界面使用 PySide6-Fluent-Widgets 的 CardWidget、ComboBox、PrimaryPushButton、PlainTextEdit 和 TreeWidget；顶部操作区、下方信息卡片和分组页签。
• Fluent 主题只负责表现层；EDID 解析、Windows WMI 读取、导入导出和线程边界不改变。
• 主题切换必须三件套同步（与 DLPilot app_fluent.py 同一方案）：setTheme 之外，QPalette + 应用级 QSS 统一 QMainWindow 背景、原生 QTabWidget/QStatusBar 表面色，DWM 属性 20/35/36 切换原生标题栏深浅。只调 setTheme 会导致 Light 模式下窗口背景、页签和标题栏仍是系统深色。
• 窗口截图验证可用 validation\capture-window.ps1（按进程窗口矩形截屏，注意全屏窗口会遮挡）。

实现与边界

• 只读 Windows WMI 显示驱动提供的 EDID；不写 EDID、不更改分辨率或显示拓扑。
• Windows/驱动可能缓存或覆盖 EDID；不能声称数据是实时 DDC 总线抓取。
• HDMI、DP、内屏均列出，连接类型来自 WmiMonitorConnectionParams，未知则如实标注。
• 无法读取的设备、缺失扩展、未知数据块和无效校验必须明确展示，不猜测。
• EDID 表示接收端声明能力，不能证明当前链路色深、HDR、HDCP 或真实带宽。
• 解析器与 UI、Windows 读取分离；读取在后台线程完成。
• 添加解析边界/错误数据测试。打包后验证实际可见窗口、缩放、刷新和导入导出流程。
• 第一版不完整解码 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 与高级色彩数据解析。
• 与实际输出时序和桥接芯片寄存器联合诊断。