wandering1
4a4ad6bc5f
现状口径：/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名， 不是 shell 命令；「名 + 命令行参数」的命令形态改为可执行体 run_boot_test.py 的真实调用。 - AGENTS.md：别名说明重写为「技能调用名不是 shell 命令」，两条目改 「编译（/keil-build）」「串口回归（/serial-boot-test）」 - keil-build / serial-boot-test 两 skill 调用名与示例同步；task-worktree 方案文档去掉 @build/@test 惯例从句；@task 保留（不在点名范围） - 123 文件现状陈述全改；台架捕获、变更记录/时间线、rename 映射输入 等 41 行历史证据保留旧名 - gen_memory_svg.py 6 处措辞随改，3 张 SVG 产物同批重跑 - 顺手补并行方案同行漏网计数 51→52 钩子 验证：提交期快钩子对 123 文件实跑全 Passed；check_doc_links --all rc=0（3038 处、无法判定 0）；check_mermaid --all rc=0；YAML 解析 52 钩子不变；skill-size rc=0；py_compile 全过；字节卫生零漂移。
55 lines
4.8 KiB
Markdown
55 lines
4.8 KiB
Markdown
---
|
||
name: lvgl-simulator
|
||
description: LVGL PC 模拟器构建/运行/自检入口：build_sim.bat 自动探测本机 VS、lvgl_sim.exe 无头截图与自检开关（--screenshot/--keys/--standby/--cfgtest/--logtest/--idle）、三套回归脚本、两份 lv_conf.h 同步门禁、构建报错速查（SDL2/lv_conf 找不到、全黑、键盘无响应）。
|
||
whenToUse: 需要构建或运行模拟器、无头截图出图、跑模拟器自检或 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 只放操作入口。**
|
||
|
||
## 构建与运行（仓库根执行）
|
||
|
||
```powershell
|
||
& "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`（文本断言 + 66 张黄金参考 + 往返池）→ `/keil-build` → `coding-standard`。
|
||
RemoDispBus 推流回归单独跑：`.venv\Scripts\python.exe simulator/tests/check_remo_sink.py`。
|
||
黄金参考 `tests/ref/*.bin` **随仓库入库**（`.gitignore` 在全仓 *.bin 兜底之后又显式反选，2026-10-22 起；缺基准 = 新克隆跑 `ui-golden` 必 FAIL）：不入库的只是派生目检图 `ref/*.png`，换机后先 `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** |
|