The BOM gate claimed to stop BOMs from being stripped, but it only ever inspected files that were already tracked AND already had a BOM. A new file under a BOM-listed directory could be born without one and never be noticed, because the scan never returned it and, even if it had, the "no HEAD version" branch skipped it. Editing a listed file and losing its BOM is a real accident that already happened once; creating one without a BOM was the same accident with no safety net at all. Measured before and after on the same untracked file with no BOM: before: checked 101 files, no drift, exit 0 after: FAIL, names the file, exit 1 The count of 101 was itself the symptom: with one more file present the honest number is 102. The old code was not "silently passing a clean tree", it was not looking. The scan now includes untracked files, and a listed file with no HEAD version must carry a BOM. Files that are tracked without a BOM keep their historical pass so this does not flood existing code with failures; instead the two that were listed but had no BOM were given one so the list means what it says. That exposed a conflict nobody had hit yet. The font file is generated, and the generator rewrites it from scratch on every run, so a hand-added BOM survived until the next regeneration and then vanished. The BOM gate and the generated-fresh gate could not both pass. The generator now puts the BOM back as its last step, idempotently, so the two gates agree and the whole UI directory keeps its uniform encoding. Font content is untouched: everything after the first three bytes is byte-identical. The menu generator gains a real read-only mode. It previously had no options at all and always rewrote its outputs; the arrows it printed were accurate. That made it easy to mistake for a checker, since an unchanged tree produces identical bytes and looks untouched. --check now reports up to date or stale without writing anything, and the registration tables are checked the same way. Default behaviour and output are unchanged. The telemetry page header no longer restates the board's input hardware facts. They live in the IOBOARD README, which is where the board's electrical behaviour belongs; the page keeps only what it alone can say: that the output rows show the shadow register rather than contact feedback, why an invalid sample draws -- instead of 分, and that these twelve rows are not in the point table. One fact, one place. The team rule for experiments now requires the file hash, the located line number, and both runs. A report once cited a line number that did not exist in the final file, which left no way to confirm which version had actually been tested.
tools/menu_gen/ — 菜单代码生成
从菜单树定义生成 UI 菜单的 C 代码,保证菜单结构与页面注册一致、避免手写遗漏。
脚本一览
| 脚本 | 作用 |
|---|---|
gen_menu.py |
读取菜单树定义(见 ui_menu_tree.txt)→ 生成菜单代码 |
使用方式
两种模式,写不写盘是唯一区别;两者的生成/注册逻辑共用同一段代码(plan_prune +
plan_sync 只算不写,写盘模式再落盘),所以"检查说的"与"写入做的"不可能漂移。
写入模式(默认,不带参数)
& '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py
重写 4 个生成物(ui_menu_tab.c/.h、ui_page_registry.c/.h)+ 同步双端注册
(MDK-ARM/STM32F407-Demo.uvprojx、simulator/CMakeLists.txt)。
输出里的箭头行(-> Drivers/BSP/UI/ui_menu_tab.h 等)表示文件确实被重写了——
注意重写不代表内容变了:内容相同时字节不变、git status 也就没有 diff。
什么时候用:改了 ui_menu_tree.txt 或增删页面实例后,这是唯一会刷新生成物的途径。
只读模式(--check)
& '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py --check
只报告"工作区生成物是否已与 ui_menu_tree.txt 同步",一次写操作都不发生,
也不建临时文件;双端注册同样只比对不写入。退出码即结论:
| 情形 | 输出 | 退出码 |
|---|---|---|
| 已同步 | [OK] up-to-date: 4 个生成物与双端注册均与 ui_menu_tree.txt 一致 |
0 |
| 有漂移 | 每个待刷新文件一行 [STALE] would rewrite <路径> (原因),末行给总数 |
1 |
[STALE] 行刻意不使用箭头符号——那个符号在只读场景里会被误读成"已经写过了"。
差异摘要会给出首个不同的行号,或"需删 N 条死引用 / 需补 N 条注册",便于直接定位。
什么时候用:改完菜单树、提交前想确认"我这笔改动是否已经重跑过生成器", 或 review 别人的菜单改动时。它不替代强制门禁——见下节。
与 check_generated_fresh.py 的分工
scripts/check_generated_fresh.py(pre-commit 钩子「生成器幂等性」)把生成器拷到临时目录
重跑再逐字节比对,是强制的红绿门禁,保证"生成物比生成器旧"必 FAIL。
--check 是给人看差异的:门禁只说红或绿,--check 说差在哪个文件、第几行、缺哪条注册。
日常改菜单用 --check 自查,提交时由门禁兜底,两者都要在。
菜单树输入的权威副本:仓库根 ui_menu_tree.txt。
⚠️ 注意
- 生成产物勿手改(会被下次生成覆盖);要改菜单结构改定义源后重跑
- 中文字符串字面量须为纯 ASCII 安全(见
docs/文档规范.md§2 编码铁律)——生成后的文案 如需汉字,须配套重跑字体生成(tools/font_gen/)
相关文档
docs/UI设计/菜单页面设计.mddocs/UI设计/内容页架构.md