wandering1
adeef7d21b
task/meas-snap 合入（merge 9c2653c，meas 快照层，分支树冲突由 lead 并集 手工解：id_registry 三族 UIDATA/VOLSYNC/MEAS 共存，JSON 校验过；该合并 提交按 mem 域例外 --no-verify，理由=合并树 .map 滞后，回填本笔兑现）。 task/n17-probe 合入（merge 969fc5c，drop 路径异步化 Flash +16 B/RAM 0）。 合并后 @build 0/0：Code=217,828 / RO=21,600 / RW=1,264 / ZI=132,840； RW_IRAM1 76,664 B（58.5%）、CCM 87.9% 不变。覆盖率 38/38 套件基线登记 （meas.c 入账）；凭证按最终 .map 重盖。计数：钩子 44→45、单测钩子 20→21、总闸 37→38 套（AGENTS + 门禁 README）。
门禁逐项说明（每种门禁一篇）
这一目录回答一个问题：提交时那 45 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
- 配置事实源：
.pre-commit-config.yaml（39 个- id:，2026-10-23 清点）。 - 通用机制（两阶段、stash 陷阱、
always已废、增量拦截三段式、旧 §2.x 查号表）：docs/代码规范/pre-commit使用说明.md§2。 - 快速自查（不等提交）：
& '.venv\Scripts\python.exe' scripts/ci_local.py（L0 + L0b + L0.5）。
1. 三种拦截姿态（先分清这个，报错时才知道该干什么）
| 姿态 | 含义 | 有哪些 | 失败时该做什么 |
|---|---|---|---|
| 改写型 | 不报错，直接改你的文件 | trailing-whitespace、end-of-file-fixer |
重新 git add 被改的文件再提交（它改的是工作区，不是索引） |
| 硬拦截 | 违反即失败，没有存量豁免 | cppcheck、coding-standard、doc-links、no-mojibake、mem-budget、ui-golden、font-charset、lv-conf-sync、task-table、mem-numbers、registration-check、cubemx-survival、test-suite-switch、16 个主机单测、官方 5 个、gitlint |
只能改代码或改文档；不要找豁免开关 |
| 增量拦截 | 规则恒生效，但存量钉在基线/台账里，只许减不许增 | layer-deps（3 条，2026-10-25 还清 UI 记录 3 条）、bsp-err（38 条）、id-check（scripts/id_known_backlog.json 台账） |
报错先分清是新增还是存量搬家：--verbose 看归类，--prune 看已还清 |
⚠ 增量拦截最容易误会的一点：绿灯不等于没问题，只等于"没有比上次更差"。 每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。
2. 索引（40 个 hook → 23 篇 + 1 根在 docs/测试说明/）
| 门禁文档 | 覆盖的 hook id | 一句话它在查什么 | 改了哪类文件才会跑 | 文档 |
|---|---|---|---|---|
bsp-err.md |
bsp-err |
BSP 的对外 API 面：错误通道类型、超时宏命名、必须写返回值、返回值不得裸丢弃 | Drivers/BSP/** 或门禁自身 |
已写 |
layer-deps.md |
layer-deps |
分层方向：Drivers/BSP/** 不得 include App/** |
Drivers/BSP/** |
已写 |
id-check.md |
id-check |
实体编号的八项校验（未登记前缀、裸形、重复定义、孤儿、悬空引用…） | 几乎所有文本文件 | 已写 |
doc-links.md |
doc-links |
文档里的路径引用是否存在；--sections-strict 另查章节号是否还存在 |
任意 .md |
已写 |
cppcheck.md |
cppcheck、test-cppcheck |
静态分析（真机侧与 test/ 侧两套范围与抑制项） |
C/H 源文件 | 已写 |
coding-standard.md |
coding-standard |
编码规范 V1.0 的可机械检查子集（命名、头文件保护宏、模块头注释块…） | C/H 源文件 | 已写 |
no-mojibake.md |
no-mojibake |
禁 U+FFFD——中文被按错误编码重解码后不可逆损坏的痕迹 |
全部文本 | 已写 |
mem-numbers.md |
mem-numbers |
文档里引用的 RAM/Flash 数字与最新 .map 报告是否一致（体积档） |
docs/内存管理/**、相关脚本 |
已写 |
mem-budget.md |
mem-budget |
RAM 总量红线：RW_IRAM1 / RW_CCM 超 92% 即拦 |
代码与配置改动 | 已写 |
task-table.md |
task-table |
README/AGENTS 里的任务表是否与 Src/freertos.c 一致 |
README.md、AGENTS.md、Src/freertos.c |
已写 |
registration-check.md |
registration-check |
新 .c 是否双端注册（Keil 工程 + 模拟器 CMake）；UI 页面描述符表是否接线 |
.c、.uvprojx、CMakeLists.txt |
已写 |
lv-conf-sync.md |
lv-conf-sync |
两份 lv_conf.h（MCU / 模拟器）的特性子集是否一致 |
两份 lv_conf 或脚本 | 已写 |
cubemx-survival.md |
cubemx-survival |
CubeMX 重生成会不会把定制静默抹掉（L3 审计兜底） | .ioc、Src/、Inc/ |
已写 |
test-suite-switch.md |
test-suite-switch |
板级套件开关必须互斥；全注释 = 产品构建 | test/board/test_config.h |
已写 |
font-charset.md |
font-charset |
UI 用到的汉字是否都在子集字体里（缺字 = 白框） | Drivers/BSP/UI/**、字体脚本 |
已写 |
ui-golden.md |
ui-golden |
UI 像素回归：菜单 8 状态 + 内容页 11 页黄金参考图比对 | UI 源码、模拟器 | 已写 |
host-unit-tests.md |
16 个 *-unit-test |
主机侧单测（同一机制 16 个实例）：逻辑层在无硬件的 PC 上编译并跑断言 | 各自被测模块与其测试目录 | 已写 |
详解在 ../测试说明/主机单测覆盖率口径.md（口径 / 分母 / 基线 / 盲区都在那篇，本目录不重复） |
test-coverage |
覆盖率总闸：跑全部 28 套主机单测 + 已覆盖行只增不减的回退台账 | App/、Drivers/BSP/、test/host/、脚本与基线 |
已写（在 docs/测试说明/） |
trailing-whitespace.md |
trailing-whitespace |
行尾空白（改写型；CubeMX/Keil 生成文件豁免） | 全部 | 已写 |
end-of-file-fixer.md |
end-of-file-fixer |
文件末尾必须恰好一个换行（改写型；同豁免） | 全部 | 已写 |
check-added-large-files.md |
check-added-large-files |
别把大文件（日志/镜像/二进制）误提进仓库 | 全部 | 已写 |
check-merge-conflict.md |
check-merge-conflict |
别把没解完的冲突标记（<<<<<<<）提上去 |
全部 | 已写 |
check-yaml.md |
check-yaml |
YAML 语法是否可解析（门禁配置自己坏了会静默不跑） | .yml/.yaml |
已写 |
gitlint.md |
gitlint |
提交信息规则：标题长度、正文每行 ≤80、空行要求 | 提交信息（commit-msg 阶段） | 已写 |
3. 每篇文档的固定八段
- 它在查什么——逐条判据，能对着代码复核的粒度；
- 为什么要它——它拦下过什么真事，没有它会怎样（没有真事的门禁要老实写"预防性"）；
- 触发面——
files:/exclude:/pass_filenames/ 阶段，以及看不见哪些文件； - 报错怎么读——样例输出、怎么单独跑、常见"假报警"（含 stash 陷阱）；
- 好处——它把哪件事从"口头约定"变成了机器判定；
- 限制与盲区——什么写法能骗过它、什么错它照不到、判据的启发式在哪里；
- 豁免与基线——白名单形状、在册数量、还债口径（只减不增）；
- 改门禁本身——自测怎么做、改名会波及什么（例如基线键）、为什么不许拿基线洗假阳性。
4. 现状与下一步
- 本目录 23 篇已全部成文（上表「文档」列 = 覆盖的 hook id，全部可达）。
- 新增/改动一个门禁时的三步：① 在
.pre-commit-config.yaml落地；② 在本目录照八段结构 新增或更新一篇（"限制与盲区"一节必须写真实判据的限度，不许留空）；③ 在本 README 索引加一行。 - 收敛已完成（2026-10-23）：
docs/代码规范/pre-commit使用说明.md的原 §2「各钩子规则详解」 （27 个小节、约 480 行）已删除，本节改为docs/代码规范/pre-commit使用说明.md§2 —— 只留跨钩子的 通用机制（两阶段、stash 陷阱、always已废、改写型与只读型豁免不对称、增量拦截三段式、 没有.map即跳过、配置自己坏的验收方式、新增门禁三步）与旧 §2.N → 新文档 查号表。 同一事实只留一处（docs/文档规范.md的要求）。 - 收敛时按内容重指了引用：skill 与 AGENTS 文档表、配置文件头注释、手册自己的文件清单行与 §5.5 里那句"判定见旧小节 2.8"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。