Files

T

wandering1 a275539c17 docs(全仓): 内容页黄金 47 → 53 的当前态同步——含钩子显示名，登记簿口径另笔

task-9 让内容页黄金从 47 涨到 53（通讯设置页六态），本笔只做**当前态陈述**的同步；真值全部本轮实测：
`simulator/tests/ref/*.bin` = **53**；`git diff 31ca4a1f..HEAD` 对该目录 = **
6 个新增、零修改** ⇒ 存量 47 张
逐字节未变（这条是关键：新增页不该让旧页重生成，否则回归基线就失去意义）。

**四类命中各走各路，这是本笔的全部难点**（分类比替换重要得多）：
· 当前态 → 改，25 处页数，落在 16 只文件（AGENTS、钩子显示名、导航器 docstring、`lvgl-simulator` s
kill、
  门禁索引与 `ui-golden` 详解、UI 自动化流程、内容页架构、页面补齐规划与扩充方案、数据供给、自动化测
  试流程、覆盖率口径、测试开发标准流程、模拟器两份 README）；
· 变更记录历史行 → **一条不动**，另在其下一行插入当日「47 → 53」新行 6 条（含判据与零漂移证据）；
· **同数不同义 → 不动**：覆盖率口径里的「47 个 .c」「47 = 13+5+29」、ram_report 的表行号 47、`#47-D`
  诊断号、LSI 47kHz、47,360 栈字数、像素哈希 3476/3474 —— 一并替换就会毁掉六个不相干的事实；
· 带日期戳 / 自declare 冻结的快照 → 不臆改（数据供给篇那句上一笔已加「当时」，页面补齐规划里那张
  「2026-10-25 复核…剩 21 叶」的表自带「完成即冻结不回改」声明）。

复扫残留当前态 47 = **0**。⚠ 顺手纠一条**会教错方法**的陈旧：naive 计数 `grep -c '#page='` 上一笔写的是
22，现在真值是 **23**（文件头示例行也算一次）——旧文档里那个 22 **恰好等于新的正确 bound 数**，不改的话,
下一个人用错算法还能碰巧对上，比错更糟。

⚠ `AGENTS.md` 里本次有两件事同行相邻（本笔的内容页 53 页 + 批次三那句 `TC-*` 停发），**分两句说明**：
前者是计数同步，后者是昨天那条「批次三不坐」裁定的入口文案，二者不是同一件事。

钩子显示名改在 `.pre-commit-config.yaml`（47 → 53）。**这条必须与代码同批入库**：配置脏而未 stage 时
pre-commit 会直接报错挡住全仓任何提交（今天已实测两次），所以本笔先落它，把后面几笔的路清开。

自查：`check_doc_links --all` rc=0（203 篇）、`check_ids --strict` rc=0 且不可判定绝对
数 **979 未变**（新增
文本里的提交号与 `#page=comm` 没推高它）、`gen_task_table --check` 0、`check_bom_drift`
 0、18 只文件 noBOM /
LF / U+FFFD=0；行数变动 +49/−47 全部可归属（插 6、删 2、并 1），其余为 1:1 等行替换。登记簿销项与叶数
（`UI补齐.md` + `docs/任务规划/README.md`）**不在本笔** —— 那是口径变更不是计数同步。

2026-10-27 13:54:05 +08:00

4.6 KiB

Raw Blame History

name, description, whenToUse

name	description	whenToUse
lvgl-simulator	LVGL PC 模拟器构建/运行/自检入口：build_sim.bat 自动探测本机 VS、lvgl_sim.exe 无头截图与自检开关（--screenshot/--keys/--standby/--cfgtest/--logtest/--idle）、三套回归脚本、两份 lv_conf.h 同步门禁、构建报错速查（SDL2/lv_conf 找不到、全黑、键盘无响应）。	需要构建或运行模拟器、无头截图出图、跑模拟器自检或 UI 回归、修改 simulator/ 目录代码或 simulator/lv_conf.h、排查模拟器构建/运行异常时。UI 改动后的完整回归走 ui-verify skill。

LVGL PC 模拟器（simulator/）

PC 上编译运行与 MCU 同一份 UI 源码（CMake + MSVC + SDL2，x64，160×160 I1 单色），免烧录。 目录架构 / 完整坑与 FAQ → simulator/README.md；首次部署（SDL2 SDK）→ docs/UI设计/LVGL模拟器部署与使用说明.md。本 skill 只放操作入口。

构建与运行（仓库根执行）

& "simulator\build_sim.bat"              # 增量构建；vswhere 自动探测本机 VS（16/17/18），勿写死生成器
& "simulator\build_sim.bat" -Clean       # 全量重建（遇到奇怪问题先加它）
.\simulator\build\Debug\lvgl_sim.exe     # 窗口模式：↑↓←→ / Enter / Esc（纯键盘，无鼠标）

⚠ 窗口模式默认 60 s 空闲自动退出（防挂后台），--idle <秒> 覆盖。

无头自检（退出码 0=PASS / 非 0=FAIL）

命令（在 `simulator\build\Debug\` 下或用全路径）	用途
`lvgl_sim.exe --screenshot shot.bin`	离屏渲染首帧 → `simulator/i1_to_png.py` 转 PNG 目检
`lvgl_sim.exe --keys "ud" shot.bin`	注入键序后截图：`u`=↑ `d`=↓ `l`=← `r`=→ `e`=Enter `s`=Esc（`main.c` 实锤）
`lvgl_sim.exe --standby shot.bin`	待机页截图
`lvgl_sim.exe --cfgtest`	配置引擎闭环：加载→轮询→外部改文件重载→外科式保存回验。临时用当前 CWD 的 `sim_config.ini`，跑完无论成败一律删除（旧行为连 PASS 路径也会留一份 4000 B 伪造档 → 之后每次运行都被加载 → 引擎按设计拒写超长文档 → 网口设置页保存行变 `ERR`，把像素回归带偏）
`lvgl_sim.exe --logtest`	syslog 后端闭环（定长记录/时间戳/轮转）

⚠ 模拟器按当前工作目录读写 sim_config.ini：目录里残留一份配置就会改变页面内容。simulator/tests/ 两套回归因此一律在空临时目录里跑（cwd=tmp）；手工跑 --keys/--screenshot 做对比时，也要先确认当前目录没有 sim_config.ini，否则"复现不了别人的 FAIL"。

UI 改动回归 → 用 `ui-verify` skill（勿在此零散手跑）

5 步门禁 = 构建 → check_menu_rows.py（菜单 8 状态像素 + 池基线）→ check_content_pages.py（文本断言 + 53 页黄金参考 + 往返池）→ @build → coding-standard。 RemoDispBus 推流回归单独跑：.venv\Scripts\python.exe simulator/tests/check_remo_sink.py。黄金参考 tests/ref/ 是本地生成物不入库：换机后先 check_content_pages.py --update 生成，再 regen_ref_png.py 出目检 PNG。

两条铁律

改 simulator/lv_conf.h 触发 lv-conf-sync 门禁：它与 MCU 端 Lib/lv_conf.h 必须保持同一特性子集（按生效值比对，未定义取 lv_conf_internal.h 兜底）；四类判定与端专属白名单 → docs/门禁说明/lv-conf-sync.md；顶层 exclude 的教训 → docs/代码规范/pre-commit使用说明.md §5.5
模拟器代码与固件同标准受检（cppcheck / coding-standard / 乱码 / 改写型钩子 / doc-links 全覆盖 simulator/）；改动触及 sim/ 任何后端，必须同步在 docs/测试说明/模拟器差距清单.md 登记一行——模拟器跑过 ≠ 真机跑过

构建/运行报错速查（详解 `simulator/README.md`「四、已知坑（构建/运行）」）

现象	根因
找不到 `SDL2/SDL.h`	LVGL SDL 驱动写死该路径，头文件须有 `include/SDL2/` 副本（仓库已内置）
找不到 `lv_conf.h`	`LV_CONF_DIR`/`SDL2_INCLUDE_DIR` 必须在 `add_subdirectory(lvgl)` 之前定义
窗口全黑	mono 主题未生效 / 缺 `lv_refr_now(NULL)` / 重复喂 tick（SDL 驱动内部已 `lv_tick_set_cb`）
画面正常但按键全无效	主循环不得调 `SDL_PollEvent`——LVGL SDL 驱动内部 5ms 定时器统一分发，先轮询会抢光事件
中文显示空白	子集字体缺字 → `font-regen` skill 重生成 `ui_font_cn_12`
新加 UI `.c` 一端编不过	双端注册（uvprojx + CMakeLists）→ `new-source-file` skill

4.6 KiB Raw Blame History Unescape Escape