fix: v0.4.3 修复长会话越跑越卡/命令无响应——日志手工 cursor 裁剪在 PySide6 6.11 必抛异常且打断 _poll_dlpc 消费；改 setMaximumBlockCount(500) 环形裁剪+逐事件兜底；新增 selftest_log 回归；重打包

- Gitea 仓库已改名（旧地址自动重定向），git remote 同步更新

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "gd32e230f8_firmware_merge_tool"]
+	path = gd32e230f8_firmware_merge_tool
+	url = https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool.git

DLPilot/AGENTS.md

@@ -42,6 +42,8 @@ DLPilot/
 | `src/config.py` | 运行目录定位(BASE_DIR)与 pattern_slots.json 读写(slots/area/serial 三键) |
 | `src/dlpc_rs485.py` | 光机 RS485 协议模块: 帧构造/增量解析/译码表/预设命令/串口线程(DLPC485) |
 | `src/selftest_rs485.py` | 光机协议自检(对照上游实测帧向量, 无硬件回归, 改协议代码后必跑) |
+| `src/selftest_theme.py` | 主题切换回归(离屏, swatch 底色/渲染像素/标题字号, 改样式后必跑) |
+| `src/selftest_log.py` | 收发日志上限与队列消费回归(离屏, 改 _dlpc_log/_poll_dlpc 后必跑) |
 | `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 文件名） |
@@ -92,6 +94,13 @@ DLPilot/
     五卡（显示器/模式/EDID 信息/测试图案/hex），右列光机五卡（串口/数据/电源/命令/滑条），
     支持的模式和 EDID 信息默认折叠；顶栏 Dark/Light/System 切换。Light/Dark 同时更新
     Fluent 主题、Qt 调色板、容器样式与 Windows DWM 标题栏，勿只调用 setTheme。
+    **fluent 控件的自定义样式禁止直接 setStyleSheet**：setTheme 会用库自带 qss 重刷全部
+    已注册控件，直写样式随之丢失（v0.4.0 swatch 丢底色的根因）。须走
+    `setCustomStyleSheet(控件, lightQss, darkQss)`（qss 需覆盖 hover/pressed/disabled 态，
+    否则悬停瞬间被自带态样式盖回）；仅 PushButton 等无 themeChanged 钩子的控件可幸存。
+    FluentLabelBase 系（StrongBodyLabel 等）例外：其 setTextColor 在每次切主题时整体重写
+    自定义槽，任何 setCustomStyleSheet 都会被冲掉——字号等改用 QFont（自带 label.qss 无
+    font-size 规则，QFont 不会被冲）。RGB swatch 底色回归测试见 selftest_theme.py。
     PD 协议成功显示绿色，FPDO 仍独立判定。打包必须收集 `qfluentwidgets` 资源，并加入 Windows 系统 `icuuc.dll`，否则 QtCore 可能被其它 ICU DLL 解析失败。
 
 ## 4. 领域语义（测试值都有含义，勿"顺手改"）
@@ -155,6 +164,9 @@ python publish_gitea.py ../release/DLPilot-v<版本>-win64.zip --replace --insec
 - GUI 与 hdmi_source.ps1 各自独立实现显示器枚举，行为可能微差（GUI 与 `-List` 序号一致，
   但与"设置"面板序号无保证）；多屏操作前先确认序号；
 - `pattern_slots.json` 兼容两种历史格式，写出只写新格式（详见 §3.11）；
+- `--seconds` 冒烟在已有 DLPilot 实例（含用户开着的 exe）运行时会"挂起"：run_gui
+  检测到单实例互斥后弹模态框等点击。无头验证改用直启 `App(5)` 的等效脚本，或先关实例；
+  重打包同理——build_exe.py 会 taskkill 同名进程，等于替用户关掉开着的实例；
 - 旧版 `app_gui.py` 仅保留作历史对照，当前入口使用 `app_fluent.py`；新增或修改界面时
   应遵循 PySide6-Fluent-Widgets 的控件和 Qt 布局，不要把旧版 CustomTkinter 依赖带回入口。
 
@@ -162,12 +174,16 @@ python publish_gitea.py ../release/DLPilot-v<版本>-win64.zip --replace --insec
 
 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` —— 投图链路；
-5. `python hdmi_gui.py --dump` —— EDID 解算不抛异常；
-6. `python hdmi_gui.py --dlpc-cmd M999`（不带 --port）—— 应明确报错而非崩溃（无硬件时的优雅降级）；
-7. `python build_exe.py` → 双击 release/DLPilot.exe 确认图标/双栏布局/投图/光机区渲染；
-8. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。
+3. `python selftest_theme.py` —— 主题切换回归（改 app_fluent.py 涉及样式/主题后必跑；
+   离屏渲染，Dark/Light 往返后校验 swatch 底色样式与渲染像素、标题字号）；
+3b. `python selftest_log.py` —— 收发日志上限/队列消费回归（改 `_dlpc_log`/`_poll_dlpc`
+   后必跑；600 行封顶 500、坏条目不中断 drain）；
+4. `python hdmi_gui.py --seconds 5` —— GUI 冒烟（自动开关）；
+5. `python hdmi_gui.py --test-pattern Checker --area 800x600 --seconds 3` —— 投图链路；
+6. `python hdmi_gui.py --dump` —— EDID 解算不抛异常；
+7. `python hdmi_gui.py --dlpc-cmd M999`（不带 --port）—— 应明确报错而非崩溃（无硬件时的优雅降级）；
+8. `python build_exe.py` → 双击 release/DLPilot.exe 确认图标/双栏布局/投图/光机区渲染；
+9. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。
 
 ## 8. v0.4.0 进度记录（2026-09-24）
 
@@ -180,3 +196,62 @@ python publish_gitea.py ../release/DLPilot-v<版本>-win64.zip --replace --insec
   发布使用仓库预置配置，临时打包后恢复本机文件。
 - 关联动态：EDID-Viewer 已于 2026-09-25 从本工具的"源端 EDID 查看"需求独立成工具
   入库并发布 v0.1.0，与本目录无代码共享；I2C-Inject 已标记暂停开发（详见根 `agent.md`）。
+
+## 9. v0.4.0 后修复记录
+
+- 2026-09-28 修复"切换 Light 后 R/G/B hex 按钮底色丢失、切回 Dark 也不恢复"：根因是
+  fluent 控件直接 `setStyleSheet` 的自定义样式在 `setTheme` 时被库重刷的自带 qss 整体
+  覆盖（任何方向的切换都会丢，非 Light 特有）。swatch 改走 `setCustomStyleSheet`（qss
+  覆盖 hover/pressed/disabled 态），同病的顶栏标题 24px 字号改用 QFont（FluentLabelBase
+  的自定义槽被库的 setTextColor 每次切主题重写，见 §3.12）。新增 `src/selftest_theme.py`
+  离屏回归（样式表存活 + 渲染像素比对），本次验证：compileall / selftest_rs485 /
+  selftest_theme / GUI 冒烟全部通过。
+- 2026-09-28 以 v0.4.1 重新打包：APP_VERSION → 0.4.1，`build_exe.py` 生成新
+  release/DLPilot.exe（67.1 MB，exe `--seconds 5` 定时退出冒烟 exit 0），按 §8 约定
+  临时还原预置 pattern_slots.json 后 `package_release.py 0.4.1` 生成
+  `DLPilot-v0.4.1-win64.zip`（66.8 MB，zip 内为预置 COM15 配置，本机 COM5 运行态
+  已还原未入库）。Gitea Release 已发布：tag `DLPilot-v0.4.1` 指向提交 `62b325c`
+  （源码+exe+文档同一提交），资产 `DLPilot-v0.4.1-win64.zip`（66.8 MB），
+  https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases/tag/DLPilot-v0.4.1 。
+  发布说明用 --notes-file 传入（内置 DEFAULT_NOTES 模板还是 v0.1.0 旧内容，下次
+  发布记得先写说明文件）。
+- 2026-09-28 第二修："串口未选/选错点连接后窗口被拉长、刷新按钮够不到"。根因：
+  pyserial 原始异常串（`could not open port '': FileNotFoundError...`）整段塞进
+  状态 BodyLabel，QLabel 不换行时最小宽度=整行文本宽，把右列参数行最小宽度撑爆。
+  三层修复：①`_dlpc_toggle` 空串口直接短提示返回（不再先写 SERIAL_CFG/save_slots
+  再 open——旧代码这顺序还会把本机串口记忆覆写成空串，本机 COM5 记忆即这样丢失过，
+  已手工修回）；②dlpc_rs485 open 失败消息分类为短提示（被占用/不存在/其它），
+  完整异常改走 on_event 进收发日志；③`lbl_dlpc_st.setWordWrap(True)` 兜底。
+  验证：compileall / selftest_rs485 ALL PASS / 离屏断言（空串口提示、长文本下标签
+  最小宽度<300 可换行）/ GUI 冒烟 / 新 exe `--seconds 5` exit 0；v0.4.1 exe（15:05）
+  与 zip 均已用该修复重打。
+- 2026-09-28 v0.4.2 两处 UI 小修：①"串口数据 · 收发日志"卡的"清空"按钮原本自占
+  一行（_card 的标题行是独立 row，按钮行加在其下），与标题错位且多占一行高度——
+  `_card()` 增加 `trailing` 参数把按钮并入标题行右端；②v0.4.0 fluent 重写把旧版
+  app_gui.py 光机命令卡首行的快捷按钮排（开光机/关光机/查版本/软件重启/开TEC/
+  关TEC/TEC33.0°C）整行丢失，开/关光机只能走预设下拉——本次按旧版排布原样恢复，
+  位于电流行与预设行之间（命令直发 `_dlpc_send`，无新增协议逻辑）。
+  验证：compileall / selftest_rs485 / selftest_theme ALL PASS；离屏渲染断言"清空"
+  与标题垂直中心差 0px、7 个快捷按钮齐全；真实桌面冒烟 exit 0。APP_VERSION → 0.4.2
+  并重打包。v0.4.2 已发布：tag `DLPilot-v0.4.2` 指向提交 `7bd9943`（源码+exe+文档
+  同一提交），资产 `DLPilot-v0.4.2-win64.zip`（66.8 MB，zip 内为预置 COM15 配置，
+  本机 COM5 运行态已还原未入库），
+  https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases/tag/DLPilot-v0.4.2 。
+  本次发布说明已用 --notes-file 传入（临时文件，未入库）。
+- 2026-10-13 v0.4.3 修复"长会话越跑越卡、命令点了没反应"（FilmForge 同案）：
+  根因是 `_dlpc_log` 的手工 textCursor 裁剪用了**实例级枚举访问**
+  （`cursor.Start`/`cursor.BlockUnderCursor`），PySide6 6.11 移除该形式，收发日志
+  超 500 行后每次追加必抛 AttributeError；异常又逃出 `_poll_dlpc` 的 drain 循环
+  （旧 try 只捕获 queue.Empty），每 tick 最多消费到第一条 event，`_dlpc_log_q`
+  棘轮积压、日志裁剪/自动滚动全失效；电源自检/功率检测序列在 `_pd_step_next()`
+  之前的 `_dlpc_log` 调用处被打断，`_pd_seq` 永不清空，后续所有手动命令被
+  "序列进行中"拦截直到断开重连。整改：①改用 `setMaximumBlockCount(500)` 环形
+  裁剪（O(1)，不依赖枚举写法）；②`_poll_dlpc` 改逐事件兜底 try/except，单条异常
+  只打栈放弃该条、不再中断本轮消费；③新增 `selftest_log.py` 回归（600 行封顶 +
+  坏条目 drain 不中断）。验证：compileall / selftest_rs485 / selftest_theme /
+  selftest_log ALL PASS；GUI 冒烟 exit 0；`--dump` / `--dlpc-cmd`（无串口）正常。
+  APP_VERSION → 0.4.3 重打包（67.1 MB），按 §8 约定临时还原预置 pattern_slots.json
+  后 `package_release.py 0.4.3` 生成 `DLPilot-v0.4.3-win64.zip`（66.8 MB，zip 内
+  为预置 COM15 配置，本机 COM5 运行态已还原未入库）。遗留（未随本版处理）：
+  `dlpc_rs485.py` 的 `except OSError` 把写超时（SerialTimeoutException）与设备
+  拔出混判，一次转换器停滞即断链误报"设备拔出"。

DLPilot/src/app_fluent.py

@@ -13,6 +13,7 @@ import queue
 import re
 import sys
 import time
+import traceback
 
 # PyInstaller keeps Shiboken's ABI DLLs in a sibling directory.  Register both
 # Qt and Shiboken before importing QtCore; this is required by one-file builds
@@ -52,7 +53,8 @@ from PySide6.QtWidgets import (
 )
 from qfluentwidgets import (
     BodyLabel, CardWidget, ComboBox, LineEdit, PlainTextEdit,
-    PrimaryPushButton, PushButton, Slider, StrongBodyLabel, Theme, setTheme,
+    PrimaryPushButton, PushButton, Slider, StrongBodyLabel, Theme,
+    setCustomStyleSheet, setTheme,
 )
 
 import config
@@ -62,7 +64,7 @@ import edid_parse
 import patterns
 
 APP_NAME = "DLPilot"
-APP_VERSION = "0.4.0"
+APP_VERSION = "0.4.3"
 REPO_URL = "https://gitea.hulk.wang/hulk/HW-Debug-Tools"
 MONO = QFont("Consolas", 10)
 CHIP_IDLE = "#666666"
@@ -209,7 +211,7 @@ class App(QMainWindow):
         button.clicked.connect(callback)
         return button
 
-    def _card(self, title, parent):
+    def _card(self, title, parent, trailing=None):
         card = CardWidget(parent)
         layout = QVBoxLayout(card)
         layout.setContentsMargins(14, 12, 14, 14)
@@ -217,6 +219,8 @@ class App(QMainWindow):
         row = QHBoxLayout()
         row.addWidget(StrongBodyLabel(title, card))
         row.addStretch(1)
+        if trailing is not None:
+            row.addWidget(trailing)
         layout.addLayout(row)
         return card, layout
 
@@ -266,7 +270,12 @@ class App(QMainWindow):
         outer.setSpacing(12)
         header = QHBoxLayout()
         title = StrongBodyLabel("DLPilot", root)
-        title.setStyleSheet("font-size: 24px; font-weight: 700;")
+        # 标题字号走 QFont：FluentLabelBase 在每次主题切换时会用自带的颜色规则
+        # 重写自定义 qss 槽，setStyleSheet/setCustomStyleSheet 写的字号都会被冲掉
+        title_font = title.font()
+        title_font.setPixelSize(24)
+        title_font.setBold(True)
+        title.setFont(title_font)
         header.addWidget(title)
         header.addWidget(BodyLabel("EDID · 测试图案 · RS485 光机控制", root))
         header.addStretch(1)
@@ -355,7 +364,13 @@ class App(QMainWindow):
             row.addWidget(BodyLabel(f"{channel}: 0x", card))
             for label, color in items:
                 button = PushButton(label, card)
-                button.setStyleSheet(f"PushButton {{ background: {color}; color: {'black' if color == '#00FF00' else 'white'}; }}")
+                # fluent 控件的样式须走 setCustomStyleSheet：直接 setStyleSheet 的内容
+                # 会在 setTheme 时被库重刷的自带 qss 冲掉；且须覆盖 hover/pressed 态，
+                # 否则悬停瞬间底色仍会被自带态样式盖回
+                fg = 'black' if color == '#00FF00' else 'white'
+                qss = ("PushButton, PushButton:hover, PushButton:pressed, "
+                       f"PushButton:disabled {{ background-color: {color}; color: {fg}; border: none; }}")
+                setCustomStyleSheet(button, qss, qss)
                 button.clicked.connect(lambda checked=False, c=color: self._show_solid(c))
                 row.addWidget(button)
             row.addStretch(1)
@@ -414,18 +429,22 @@ class App(QMainWindow):
             setattr(self, attr, combo)
             params.addWidget(combo)
         self.lbl_dlpc_st = BodyLabel("未连接", card)
+        # 状态标签允许换行兜底: 任何长错误串都不得撑大参数行最小宽度(否则窗口拉长,
+        # 刷新/连接按钮被挤出可视区)
+        self.lbl_dlpc_st.setWordWrap(True)
         params.addWidget(self.lbl_dlpc_st)
         params.addStretch(1)
         body.addLayout(params)
         layout.addWidget(card)
 
-        card, body = self._card("串口数据 · 收发日志（译码 + 原始 hex）", self)
-        row = QHBoxLayout()
-        row.addStretch(1)
-        row.addWidget(self._button("清空", self._dlpc_clear))
-        body.addLayout(row)
+        card, body = self._card("串口数据 · 收发日志（译码 + 原始 hex）", self,
+                                trailing=self._button("清空", self._dlpc_clear))
         self.txt_dlpc = self._text()
         self.txt_dlpc.setMinimumHeight(230)
+        # 收发日志环形裁剪: 超 500 行自动丢最旧(O(1))。勿改回 textCursor 手工裁剪——
+        # PySide6 6.11 移除实例级枚举访问, cursor.Start 必抛 AttributeError 且异常会
+        # 打断 _poll_dlpc 的队列消费(事件棘轮积压), 回归见 selftest_log.py
+        self.txt_dlpc.document().setMaximumBlockCount(500)
         body.addWidget(self.txt_dlpc)
         self._dlpc_log("帧格式: D5 01 LEN <命令> CRC / B5 TYPE LEN <payload> CRC")
         layout.addWidget(card)
@@ -457,6 +476,14 @@ class App(QMainWindow):
         row.addStretch(1)
         row.addWidget(self._button("查电流", self._query_current))
         body.addLayout(row)
+        # 快捷命令行: v0.4.0 重写时从旧版 app_gui.py 丢失, 开关光机等一发命令
+        # 不应只能走预设下拉
+        quick = QHBoxLayout()
+        for name, cmd in (("开光机", "M730S0"), ("关光机", "M730S1"), ("查版本", "M999"),
+                          ("软件重启", "M888"), ("开TEC", "M7S0"), ("关TEC", "M7S1"),
+                          ("TEC33.0°C", "M8S330")):
+            quick.addWidget(self._button(name, lambda checked=False, c=cmd: self._dlpc_send(c)))
+        body.addLayout(quick)
         preset_row = QHBoxLayout()
         self._dlpc_presets = [(n, cmd) for n, cmd, _ in dlpc_rs485.PRESETS]
         self.cbo_dlpc_cmd = ComboBox(card)
@@ -733,9 +760,12 @@ class App(QMainWindow):
     def _query_lamp(self): self._tl_order.append('LAMP'); self._dlpc_send('M202')
 
     def _poll_dlpc(self):
-        try:
-            while True:
+        while True:
+            try:
                 kind, value = self._dlpc_log_q.get_nowait()
+            except queue.Empty:
+                break
+            try:
                 if kind == 'status':
                     self.lbl_dlpc_st.setText(value)
                     if value.startswith(('已断开', '串口丢失')): self._serial_reset_state()
@@ -744,15 +774,16 @@ class App(QMainWindow):
                 elif kind == 'pdframe': self._pd_step_done(value.type_code == 0xF0, value)
                 elif kind == 'pwrframe': self._pwr_step_done(value)
                 else: self._dlpc_log(value)
-        except queue.Empty: pass
+            except Exception:
+                # 单条事件处理异常只打栈放弃该条, 不得中断本轮消费——否则积压随事件流
+                # 单调增长(v0.4.3 前日志裁剪异常即此路径, 显示延迟越跑越大)
+                traceback.print_exc()
         connected = self.dlpc.is_connected()
         if connected != self._dlpc_connected:
             self._dlpc_connected = connected; self.btn_dlpc.setText("断开" if connected else "连接")
 
     def _dlpc_log(self, line):
         self.txt_dlpc.appendPlainText(time.strftime('%H:%M:%S  ') + line)
-        if self.txt_dlpc.blockCount() > 500:
-            cursor = self.txt_dlpc.textCursor(); cursor.movePosition(cursor.Start); cursor.select(cursor.BlockUnderCursor); cursor.removeSelectedText(); cursor.deleteChar()
         self.txt_dlpc.verticalScrollBar().setValue(self.txt_dlpc.verticalScrollBar().maximum())
 
     def _dlpc_clear(self): self.txt_dlpc.clear()
@@ -770,6 +801,7 @@ class App(QMainWindow):
     def _dlpc_toggle(self):
         if self.dlpc.is_connected(): self.dlpc.close(); self._serial_reset_state(); return
         port = self._dlpc_selected_port()
+        if not port: self.lbl_dlpc_st.setText('未选择串口，请先选择或刷新'); return
         try: baud, bytesize, stopbits = int(self.cbo_baud.currentText()), int(self.cbo_databits.currentText()), int(self.cbo_stopbits.currentText())
         except ValueError: self.lbl_dlpc_st.setText("串口参数非法"); return
         parity = self.cbo_parity.currentText()[:1] or 'N'; config.SERIAL_CFG.update(port=port, baud=baud, bytesize=bytesize, parity=parity, stopbits=stopbits); config.save_slots(self.slots, self.cbo_area.currentText()); self.dlpc.open(port, baud, bytesize=bytesize, parity=parity, stopbits=stopbits)

DLPilot/src/dlpc_rs485.py

@@ -326,11 +326,19 @@ class DLPC485:
                         self.ser = None
                         with self._lock:
                             self._target = None
-                        et = str(e)
-                        if 'PermissionError' in repr(e) or '拒绝访问' in et \
-                                or 'Access is denied' in et:
-                            et += '（串口被占用: 检查串口助手/另一个本工具实例）'
-                        self.on_status(f'连接失败: {et}')
+                        blob = str(e) + repr(e)
+                        if 'PermissionError' in blob or '拒绝访问' in blob \
+                                or 'Access is denied' in blob:
+                            hint = '串口被占用（串口助手/另一实例?）'
+                        elif 'FileNotFoundError' in blob or '找不到指定的' in blob \
+                                or 'No such file' in blob:
+                            hint = '串口不存在，请刷新后重选'
+                        else:
+                            hint = '无法打开，详情见日志'
+                        # 状态标签只放短提示(长异常串会撑爆参数行把窗口拉长),
+                        # 完整异常走 on_event 进收发日志
+                        self.on_status(f'连接失败: {hint}')
+                        self.on_event(f'连接失败: {e!r}')
             if self.ser is not None:
                 try:
                     item = None

DLPilot/src/selftest_log.py

@@ -0,0 +1,70 @@
+# coding: utf-8
+"""收发日志上限与队列消费回归自检（无窗口, 离屏渲染）。
+
+背景: v0.4.3 之前收发日志用 textCursor 手工裁剪, 其中 `cursor.Start` /
+`cursor.BlockUnderCursor` 是实例级枚举访问 —— PySide6 6.11 移除了该形式,
+日志一旦超过 500 行, 每次 _dlpc_log 追加后必抛 AttributeError; 且异常会
+逃出 _poll_dlpc 的 drain 循环（旧 try 只捕获 queue.Empty）, 每 tick 最多
+消费到第一条 event, `_dlpc_log_q` 棘轮积压、日志裁剪与自动滚动全部失效,
+电源自检/功率检测序列还会被异常打断在启动处（之后所有命令被"序列进行中"
+拦截）。v0.4.3 改为 setMaximumBlockCount 环形裁剪 + 逐事件异常兜底。
+
+本测试保证:
+  1. 连续追加 600 行日志不抛异常, document().blockCount() 环形封顶 500, 末行在;
+  2. 单条异常事件（模拟未来引入的坏数据）不中断 _poll_dlpc 本轮队列消费
+     —— 其后的事件仍全部入日志、队列清空。
+
+运行: python selftest_log.py  （依赖 PySide6-Fluent-Widgets 与 pyserial ——
+串口卡构建后 txt_dlpc 才存在）
+"""
+import os
+import sys
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from PySide6.QtWidgets import QApplication
+from qfluentwidgets import Theme, setTheme
+
+import app_fluent
+import dlpc_rs485
+
+
+def check_cap(win):
+    for i in range(600):
+        win._dlpc_log(f"cap-line-{i}")
+    blocks = win.txt_dlpc.document().blockCount()
+    has_last = "cap-line-599" in win.txt_dlpc.toPlainText()
+    print(f"  追加 600 行: blockCount={blocks}(封顶 500), 末行在: {has_last}")
+    return blocks <= 500 and has_last
+
+
+def check_drain_resilience(win):
+    win._timer.stop()                                  # 排除 80ms 轮询定时器干扰
+    win._dlpc_log_q.put(("pdframe", "poison-not-a-frame"))   # 该条分发必抛异常
+    win._dlpc_log_q.put(("event", "after-poison-1"))
+    win._dlpc_log_q.put(("event", "after-poison-2"))
+    win._poll_dlpc()                                   # 单次手动驱动(不进事件循环)
+    left = win._dlpc_log_q.qsize()
+    text = win.txt_dlpc.toPlainText()
+    drained = left == 0 and "after-poison-1" in text and "after-poison-2" in text
+    print(f"  坏条目后消费不中断: 残留队列={left}, 后续事件全部写入: {drained}")
+    return drained
+
+
+def main():
+    if not dlpc_rs485.HAS_SERIAL:
+        print("FAILED 缺少 pyserial: 串口卡未构建, txt_dlpc 不存在")
+        return 1
+    app = QApplication.instance() or QApplication(sys.argv)
+    setTheme(Theme.AUTO)
+    win = app_fluent.App(0)
+    passed = check_cap(win)
+    passed &= check_drain_resilience(win)
+    win.close()
+    print("ALL PASS" if passed else "FAILED")
+    return 0 if passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

DLPilot/src/selftest_theme.py

@@ -0,0 +1,82 @@
+# coding: utf-8
+"""主题切换回归自检（无窗口, 离屏渲染）。
+
+背景: fluent 控件直接 setStyleSheet 的样式会在 setTheme 时被库重刷的自带 qss 冲掉
+（v0.4.0 RGB swatch 按钮切主题丢底色的根因）。swatch 改走 setCustomStyleSheet、
+标题字号走 QFont 后，本测试保证:
+  1. Dark -> Light -> Dark -> Light 往返后 9 个 swatch 按钮样式表仍带底色；
+  2. Light 下实际渲染出的按钮中心像素 = swatch 色值（不只样式表字符串存在）；
+  3. 标题 24px 加粗（QFont）在往返后不变。
+
+运行: python selftest_theme.py  （依赖 PySide6-Fluent-Widgets）
+"""
+import os
+import sys
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from PySide6.QtGui import QColor
+from PySide6.QtWidgets import QApplication
+from qfluentwidgets import PushButton, StrongBodyLabel, Theme, setTheme
+
+import app_fluent
+import patterns
+
+
+def check_style_sheet(win, app):
+    swatches = [b for b in win.findChildren(PushButton) if b.text() in {"55", "AA", "FF"}]
+    assert len(swatches) == 9, f"expect 9 swatch buttons, got {len(swatches)}"
+    title = [l for l in win.findChildren(StrongBodyLabel) if l.text() == "DLPilot"]
+    assert len(title) == 1, "title label not found"
+    colored = sum(1 for b in swatches if "background-color: #" in b.styleSheet())
+    f = title[0].font()
+    print(f"  swatch 样式表带底色: {colored}/9, 标题 24px 粗体: "
+          f"{f.pixelSize() == 24 and f.bold()}")
+    return colored == 9 and f.pixelSize() == 24 and f.bold()
+
+
+def check_rendered_pixel(win, app):
+    """Light 主题下逐个渲染 swatch，与目标色一致的像素须占明显多数（背景为主，
+    中心处是文字字形，不能只采单点）。"""
+    ok = True
+    for channel, items in patterns.SOLID_ROWS:
+        for label, color in items:
+            button = next(b for b in win.findChildren(PushButton)
+                          if b.text() == label and f"background-color: {color}" in b.styleSheet())
+            image = button.grab().toImage()
+            target = QColor(color)
+            total, matched = image.width() * image.height(), 0
+            for y in range(image.height()):
+                for x in range(image.width()):
+                    if image.pixelColor(x, y) == target:
+                        matched += 1
+            ratio = matched / total
+            same = ratio >= 0.2
+            ok &= same
+            if not same:
+                print(f"  渲染不符: {channel}/{label} 期望 {color} 仅占 {ratio:.0%}")
+    print(f"  Light 下渲染像素比对: {'一致' if ok else '存在偏差'}")
+    return ok
+
+
+def main():
+    app = QApplication.instance() or QApplication(sys.argv)
+    setTheme(Theme.AUTO)
+    win = app_fluent.App(0)
+    passed = True
+    for step, theme in (("初始 Dark", Theme.DARK), ("切 Light", Theme.LIGHT),
+                        ("切回 Dark", Theme.DARK), ("再切 Light", Theme.LIGHT)):
+        setTheme(theme)
+        app.processEvents()
+        print(f"[{step}]")
+        passed &= check_style_sheet(win, app)
+        if theme == Theme.LIGHT:
+            passed &= check_rendered_pixel(win, app)
+    win.close()
+    print("ALL PASS" if passed else "FAILED")
+    return 0 if passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

README.md

@@ -6,12 +6,13 @@
 
 ## 工具一览
 
-| 工具 | 用途 | 获取 |
-|---|---|---|
-| [DLPilot](DLPilot/) | HDMI 源端（EDID 查看/逐字节解析、分辨率切换、纯色与测试图案全屏投屏）+ 光机控制（RS485→GD32 网关→DLPC3421：开关光机/设光强/查温度电流） | 到 [Releases](https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases) 下 `DLPilot-vX.Y.Z-win64.zip`，解压即用；详见 [DLPilot/README.md](DLPilot/README.md) |
-| [EDID-viewer](EDID-viewer/) | Windows 显示器 EDID 只读查看器：活动设备或离线文件的厂家/序列号/分辨率时序、CTA/HDMI/音频/HDR 能力、校验诊断；BIN/HEX 导入，BIN/JSON 报告导出 | 到 [Releases](https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases) 下 `EDID-Viewer-vX.Y.Z-win64.zip`，解压即用；详见 [EDID-viewer/README.md](EDID-viewer/README.md) |
-| [SerialMate](SerialMate/) | RS485/串口调试助手：收发 + 协议包解析（帧构成令牌序列/包头/板ID/LEN口径/CRC 全可定制，默认兼容 DLPilot 光机协议）、板型档案一键切换协议参数与命令预设、payload 字符串/HEX 显示、4 通道曲线（弹窗独立、时间窗滑笔回看、悬停读值、暂停渲染）、发送框输入 payload 自动包装组帧（`/` 分隔多条）、HEX 直发与周期发送 | 到 [Releases](https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases) 下 `SerialMate-vX.Y.Z-win64.zip`，解压即用；详见 [SerialMate/README.md](SerialMate/README.md) |
-| [I2C-Inject](I2C-Inject/) | ⏸ **暂停开发**：LT8619C 寄存器在线读写（RP2040 注入器在 demo 板 I2C 总线上择机注入，避让主控轮询，写后自动读回校验）。代码与固件保留备查 | 暂不提供发布；状态与原理详见 [I2C-Inject/README.md](I2C-Inject/README.md) |
+| 图标 | 工具 | 用途 | 获取 |
+|---|---|---|---|
+| <img src="DLPilot/src/logos/logo_dlpilot.png" width="64" alt="DLPilot 图标"/> | [DLPilot](DLPilot/) | HDMI 源端（EDID 查看/逐字节解析、分辨率切换、纯色与测试图案全屏投屏）+ 光机控制（RS485→GD32 网关→DLPC3421：开关光机/设光强/查温度电流） | 到 [Releases](https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases) 下 `DLPilot-vX.Y.Z-win64.zip`，解压即用；详见 [DLPilot/README.md](DLPilot/README.md) |
+| <img src="EDID-viewer/assets/edid-viewer.png" width="64" alt="EDID-Viewer 图标"/> | [EDID-viewer](EDID-viewer/) | Windows 显示器 EDID 只读查看器：活动设备或离线文件的厂家/序列号/分辨率时序、CTA/HDMI/音频/HDR 能力、校验诊断；BIN/HEX 导入，BIN/JSON 报告导出 | 到 [Releases](https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases) 下 `EDID-Viewer-vX.Y.Z-win64.zip`，解压即用；详见 [EDID-viewer/README.md](EDID-viewer/README.md) |
+| <img src="SerialMate/assets/serial-mate.png" width="64" alt="SerialMate 图标"/> | [SerialMate](SerialMate/) | RS485/串口调试助手：收发 + 协议包解析（帧构成令牌序列/包头/板ID/LEN口径/CRC 全可定制，默认兼容 DLPilot 光机协议）、板型档案一键切换协议参数与命令预设、payload 字符串/HEX 显示、4 通道曲线（弹窗独立、时间窗滑笔回看、悬停读值、暂停渲染）、发送框输入 payload 自动包装组帧（`/` 分隔多条）、HEX 直发与周期发送 | 到 [Releases](https://gitea.hulk.wang/hulk/HW-Debug-Tools/releases) 下 `SerialMate-vX.Y.Z-win64.zip`，解压即用；详见 [SerialMate/README.md](SerialMate/README.md) |
+| <img src="I2C-Inject/logos/logo_i2c_orange.png" width="64" alt="I2C-Inject 图标"/> | [I2C-Inject](I2C-Inject/) | ⏸ **暂停开发**：LT8619C 寄存器在线读写（RP2040 注入器在 demo 板 I2C 总线上择机注入，避让主控轮询，写后自动读回校验）。代码与固件保留备查 | 暂不提供发布；状态与原理详见 [I2C-Inject/README.md](I2C-Inject/README.md) |
+| <img src="gd32e230f8_firmware_merge_tool/FlashTool/src/logos/logo_flash.png" width="64" alt="GD32 固件工具图标"/> | [gd32e230f8_firmware_merge_tool](gd32e230f8_firmware_merge_tool/) | 🔗 **子模块**（独立仓库独立管理）：GD32E230 固件工具——APP/BL 合成补齐（`_UPDATE.bin`/`_BL.bin`）+ DAPLink Flash GUI 烧录（自带 OpenOCD 工具链） | 本仓目录即快捷入口；版本更新与发布在其[原仓库](https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool)（Releases 下 zip 解压即用）；详见 [README](gd32e230f8_firmware_merge_tool/README.md) |
 
 ## 环境要求
 
@@ -50,6 +51,7 @@ HW-Debug-Tools/
 │   ├── README.md            # 使用说明
 │   └── AGENTS.md            # 工程档案
 ├── I2C-Inject/              # PC 端 GUI + RP2040 固件 + 打包 exe + 图标 + README
+├── gd32e230f8_firmware_merge_tool/  # 🔗 git 子模块 → GD32E230 固件工具（独立仓库，见下方备注）
 ├── LICENSE
 └── README.md
 ```
@@ -68,6 +70,10 @@ python publish_gitea.py <工具>-v<版本>-win64.zip --insecure    # 上传 Gite
 ## 备注
 
 - 源码与打包产物（exe、pattern_slots.json）均入库；发布 zip 不入库，只上传 Gitea Release
+- `gd32e230f8_firmware_merge_tool/` 是 git 子模块（[独立仓库](https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool)，
+  代码与发布均在其仓内管理，本仓只锁定指针）：
+  新克隆后需 `git submodule update --init` 拉取内容；
+  跟进其最新版用 `git submodule update --remote gd32e230f8_firmware_merge_tool`，随本仓提交新指针
 - 两件工具的寄存器语义（0x606E 位交换 / 0x606D 整组顺序）均经 demo 板逻辑分析仪
   双色交叉实测，过程数据与规程存于上游主仓库 `doc/architecture/`
-- 更新：2026-09-27
+- 更新：2026-09-30

agent.md

@@ -29,6 +29,11 @@
     自动包装发送。
   - **I2C-Inject**：RP2040 固件 + PC GUI，demo 板 I2C 总线择机注入读写寄存器。
     **2026-09-25 起暂停开发**，代码与固件保留备查。
+- 子模块引用：`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 不同步）。