Files

T

wandering1 88601422c3 docs(文档规范): 清空壳变更记录节，例外清单改成可复跑口径

17 篇文档的变更记录（含修订记录、带编号与中文序号标题）节里只剩一句
「不再记流水账」的占位话，整节删掉，连带它前面的分隔线。
仍保留真台账的只有 5 篇（看门狗 / 配置文件设计 / RAM 预算台账 /
内容页架构 / 本地工具路径方案），外加 scripts/archive 归档区。

份数口径改成可复跑的普查：文档规范 §5.1 补自查命令，
stale-doc-count-sweep 的速查表与陷阱各加一条——只 grep 裸标题会漏
带编号与中文序号的两种写法，实测 5 篇只数得出 3 篇，差点据此把
全仓正确的份数改错。

门禁：逐篇与全量 check_doc_links 除 simulator/SDL2 联接假红外 0 问题；
skill-size rc=0；表格列数与字节体检相对 HEAD 零新增问题。

2026-10-29 21:21:59 +08:00

7.0 KiB

Raw Blame History

`font-charset` — UI 字符集差集（防"缺字显示白框"）

一句话：本仓唯一中文字体是子集字体；UI 字符串用了没进字体的汉字，上机就是空白方框，没有日志、没有报错。本门把"改了 UI 文案要重跑字体生成链"这条约定机械化。

配置：entry: python scripts/check_font_charset.py、pass_filenames: false、 files: 覆盖 Drivers/BSP/UI/、App/task/ui_task.(c|h)、ui_cn_chars.txt、tools/font_gen/。
生成链（四步，见 font-regen skill）：UI 源码 →extract_cn.py→ ui_cn_chars.txt →make_font.py→ ui_font_cn_12.c。

1. 它在查什么（两段链条，缺一环即白框）

段	比对	不满足时
A	必需字符集（源码在用 ∪ `KEEP_EXTRA` 保留字） vs `ui_cn_chars.txt`	必需而 txt 无 → GAP FAIL（字体必然缺字形）；txt 有但非必需 → 告警不拦（只费 Flash）；`--strict` 升级为 FAIL
B	`ui_cn_chars.txt` vs `ui_font_cn_12.c` 的 cmap	txt 有而字体无 → GAP FAIL（转换器对缺字形/低码位会静默丢字）

A 通过 + B 通过 ⟹ 字体覆盖"源码在用"与"刻意保留"的每一个字。 KEEP_EXTRA 的存在理由：防止将来 extract_cn.py 按"源码已不用"静默删掉已落盘记录里还在用的字（这条路径的实际形态与实测数字见 §6.1）。

单一规则源：本脚本不自创第二套"从源码里找汉字"的规则，而是复用 tools/font_gen/extract_cn.py 的 SCAN 清单与 collect() 状态机（跳过注释与字符常量、只取双引号字符串）。两处各写一套解析，就会出现"门禁说够、生成器说不够"。
典型报错形态：[GAP] 字体缺字 1 个（在字符集、不在 ui_font_cn_12.c 的 cmap -> lv_font_conv 静默丢字，上机白框），并点名码位（含 U+ 码点）。

2. 为什么要它

生成期的 verify_coverage() 只校验"txt ⊆ 字体 cmap"，管不到"源码用到的字有没有进 txt"；改了 UI 字符串却忘跑生成链时，此前提交期没有任何门禁能拦——只能靠肉眼截图发现白框。
有牙实测（首次落地）：注入都打在临时副本上（用 --chars / --font 覆盖，不碰仓库文件）： ① 从字符集清单里删掉一个符号 → 第一段链条 FAIL 并点名该码位；② 从字体副本里删掉同一码位 → 第二段链条 FAIL。两段各测一次才算证明链条闭合。

3. 触发面

只跑改动的 .c/.h（types: [c]）。

4. 报错怎么读 / 单独跑

& '.venv\Scripts\python.exe' scripts/check_font_charset.py --strict（严格档：冗余字也拦）； --chars / --font 换输入用于测脚本自己。
修法是重跑生成链（font-regen skill 四步），不是把字从 UI 里删掉凑绿。

5. 好处

把一种"上机才知道、且完全没有日志"的显示缺陷压到提交前；
KEEP_EXTRA 用"逐条带理由"的形式沉淀，避免将来被无声删掉。

6. 限制与盲区

只看 C/H 源文件：types: [c]。写进 ui_menu_tree.txt（生成菜单表的文本源）里的汉字不在直接扫描面内——它靠"重新生成 UI 表 → 落到 .c → 被扫"这条间接路径生效；手工改生成物或跳过生成器时，覆盖关系可能出现空洞。
必需集来自"源码里出现的汉字"，运行期拼出来的字符串（格式化进来的字、外部配置文件里的字、记录内容回显）完全在视野外——那类白框本门照不到。
只校验码位覆盖，不校验字形是否美观/是否为所需点阵尺寸。

6.1 「按 extract 输出重写字符集」= 洗字形（实名登记的事故路径）

tools/font_gen/extract_cn.py 只认当前源码里的字符串字面量，照不出运行期数据里的字—— 典型是 2026-09 窗口固件写进 /log/selftest.log、/log/run.log 的定长 64 B 中文描述记录（跨固件持久，自检/运行记录页直接渲染 desc）。实测口径（2026-10-25）：extract 扫出 144 字，而 ui_cn_chars.txt 当时现有 183 字（2026-10-28 实测已 218 唯一字），差的 39 字全部由 KEEP_EXTRA 兜住：

逐字登记 4 字（异/常/片/芯）：出处可指到 9eb1bd63（2026-09-14 中文自检描述）与 6f51c62a（2026-09-20 串口侧改 ASCII），脚本里逐字写了理由；
成组登记 35 字（2026-10-25 道E task-15 并入）：正是本门禁「未知冗余」WARN 的全部条目（一位公分合外已年度延态总接显最月未求温状电示秒请跳载近道部配重长间闸障）。来源能确认是那批落盘记录的用字，但逐字出处已不可靠复原（文案被整体改写，指不到某个字来自哪条 commit）→ 选择整组保留并在脚本里点名成组，而不是给每个字编一条看起来可信的理由。判据：字形不可再生（删了永久白框、无日志无报错，只在渲染历史记录时暴露），保留成本约 35 字 × 27 B ≈ 1 KB RO——收益与代价不对称（同本目录"收益不抵风险"暂缓）。

事故路径：有人跑 extract_cn.py，把输出当"权威清单"直接覆盖 ui_cn_chars.txt → 39 字被静默洗掉 → 下次 font-regen 生成的字体不再有这些字形 → 现场翻到 2026-09 那批历史记录时相关行渲染成空白方块，且没有任何地方报错。

机械化拦截：KEEP_EXTRA 按"必需字"参与 A 段判定——txt 缺任一保留字直接 GAP FAIL 并逐字打印保留理由（--strict 同样 FAIL）→ "洗字形"在下一次提交就响，不靠人记性。配套流程约束：font-regen 第 3 步（重生成字体）之前必须把 KEEP_EXTRA 并回 txt。

删除前置条件（满足后才可删条目，删后下次 font-regen 自然瘦身）：确认设备上已无该窗口的落盘记录，或产品侧明确接受历史记录部分渲染空白。只删 txt/字体里的字而不删本清单 = 本门禁立刻 FAIL（刻意：清单是唯一真相源）。 4. 拉丁字母、数字、标点不在本门范围（另有字体与布局约定）。 5. --strict 不在钩子默认档位里（默认只拦 GAP）：冗余字形长期靠人自觉清理。 6. 字体文件本身若被手工编辑（不跑生成器），A/B 两段仍可能同时"通过"而与实际 cmap 不符—— 因为它读的就是生成物。

7. 豁免与基线

KEEP_EXTRA 是刻意保留清单（存量 + 理由；出处可考者逐字登记，出处不可考者成组登记，见 §6.1），性质同 registration-check 的已知缺口表；新增要写理由，删掉等于放弃保护。
没有"只减不增"的债务基线。

8. 改这个门禁本身

放宽"必需集"来源（比如不再扫某个目录）前先确认该目录的字最终确实会进生成链；
与 ui-golden 是互补关系：本门管"有没有字形"，golden 管"像素对不对"。

7.0 KiB Raw Blame History Unescape Escape

font-charset — UI 字符集差集（防"缺字显示白框"）