wandering1
1d39571114
动机是今天一天复发三次的同一形态：在块注释里写作用域路径，那个 `/*` 被 ARMCC 当第二次注释起点（诊断 9-D）， 而且**按包含者数量刷屏、只在重编译那个 TU 时才暴露**——本仓的诱因就是「注释里写 Drivers/BSP/UI/**」。 AGENTS 早就写了这条铁律（写全目录或用尖括号），但它一直是纯口头纪律，所以同一天还是复发三次。 新脚本 scripts/check_nested_comment.py：纯标准库、只读、五状态机（代码 / 行注释 / 块注释 / 字符串 / 字符 字面量），**只有块注释体内的 /* 才算问题**——字符串里的、行注释里的、未闭合判定都不误报。口径上刻意与钩子 的 types: [c] 对齐（403 个 .c/.h 同面），避免「手跑面 ≠ 提交面」这类我们今天就踩过的错位；零第三方依赖是 刻意的，为了让 generated-fresh 那天的解释器假红不长第二遍（实测 .venv 与机器级 C:Python314 两种解释器结论 一致）。 存量口径：全仓实扫**新发 0、存量 2 处**（test/host/common/ch395f_fake.h:7 与 fatfs_fake.h:9，同一形态 「注释里写作用域 test/host/**」）。两份假件头不参与 MCU 构建所以今天不报，一旦被 include 进板端 TU 就会 按包含者刷 9-D——属 test/ 写域，作者**没代改**，而是钉进 BASELINE 走只减不增，**其余零豁免**。 自证有一条必须写清的诚实边界：作者想「拿旧字节回放今天那三处真复发」，实测**做不到**——近 150 个提交里被 改过的 281 份 .c/.h 旧字节**零命中**，因为那三处同类从来没有一处在 HEAD 里留过字节（全靠人工编译后清掉）。 于是改测**形态**（这是能证的部分）：10 项形态电池 10/10，含把已入库的尖括号写法退回星号形态 → 命中 1 处； 另用现存两份真字节做双跑：空基线 → 2 条 [NEW] + exit 1，加基线 → exit 0，证明**基线只决定算不算新的， 不掩盖有没有**。编译器侧原文（run_par.c(267) #9-D）冻结抄进新文档 §2.1——构建日志每次 @build 被覆盖且不入库， 所以文档里刻意没写「最近一次日志里仍有」这种会过期的话。 计数三处同批：AGENTS「共 **51** 个钩子」、门禁索引「51 个 hook → 27 篇 + 1 指针 + 1 外置」、配置声明；并记 文本 grep「 - id:」= 52 的成因（第 65 行被注释掉的 clang-format 候选），收紧行首口径 = 51。作者顺带自打了 一次：在配置注释里复述了那个 grep 字面量 → 文本计数当场虚高 1，已改写并把「配置注释里别复述字面量」写进 README §2 与 AGENTS。 同笔带上 task-28 的裁定句（AGENTS 一只文件里两卡改动天然混在一起，拆开会多两次改写与一次风险）：不补第 23 根 ui-sink 专属钩子——22 根的唯一意义是秒级归因，而 ui_sink 失败面全落在 test-coverage 总闸必跑路径、 失败照样拦；读「这套跑没跑」去看总闸输出，别数钩子。 实测与本笔自查：validate-config = 0；nested-comment --selftest 4/4、--all = 403 / 新发 0 / 存量 2 → exit 0； doc-links --sections-strict（4 篇）= 0；gen_task_table --check = 0；generated-fresh PASS（5 处存量走 WARN）； check_ids --strict exit 0，**不可判定绝对数全程未被本闸吃掉**（作者开工 1,162、写完新闸与新文档仍 1,162； 现 1,156 是队友还清的）；全部改动文件 noBOM / LF / U+FFFD=0。未跑 pre-commit --all-files（只跑本闸）。 **本笔使用 --no-verify 的凭证（唯一允许的两条之一，按 MEMORY 台账例外口径）**：把本批 6 只文件单独 staged 后跑 `pre-commit run --files <这 6 只>` → **13 条 Passed / 1 条 Failed** 唯一失败的是 `mem-budget` （RAM 92% 阈值，**全树检查**）。本批**零固件源、零 .map 变更**，该红来自其他队友在飞的固件改动造成的 .map 漂移（当前树 Code=231,952 / RW=1,528 / ZI=136,264，在库台账 231,712 / 1,504 / 136,216 差 = run_par setter 与 vol_lock 计数两笔，均未提交）；台账回填由我在树能编后统一 `--write`，不在分支上跑（避免多分支同改受管表）。 gate: only mem-budget pending lead ledger backfill。字节卫生本笔自查：6 只文件均 noBOM / L F / U+FFFD=0， 新脚本纯 ASCII 输出路径无关，AGENTS 与索引两处计数与配置 YAML 解析口径 51 一致。 另收一条今天反复出现的元教训（Lead 与作者各错过一次、方向相反）：**`pre-commit run` 与 git 钩子不是同一根 探针**——config 处于 modified-unstaged 时只有后者 [ERROR] 拒绝，前者与 validate-config 都 Passed 。它与「stash 只覆盖已跟踪未暂存」「未跟踪文件永不进 stash」同族：手跑的探针不能替真提交的探针作证。
门禁逐项说明（每种门禁一篇）
这一目录回答一个问题：提交时那 51 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
- 配置事实源：
.pre-commit-config.yaml。钩子数的唯一口径 = YAML 解析后的 hook 条目数，不是文件里的文本行数。 自查（打印声明数；加/删一条钩子后，这个数要与 AGENTS.md 的「共 N 个钩子」、本目录 §2 标题同时对齐）：& '.venv\Scripts\python.exe' -c "import yaml; d=yaml.safe_load(open('.pre-commit-config.yaml', encoding='utf-8')); print(sum(len(r['hooks']) for r in d['repos']))"→ 51（2026-10-26：49 → 50 加generated-fresh；2026-10-27：50 → 51 加nested-comment）。 ⚠ 别用grep -c去数配置里的声明行：该文件里有一条注释掉的候选钩子（clang-format，第 65 行）， 文本 grep 会多算 1 = 52——「声明 52 / 文档 51 / 实跑 51」这种三个数不同源的争执就是这么来的。真要 grep， 用只认行首缩进的模式：grep -Ec "^ +- id: " .pre-commit-config.yaml（= 51）。 ⚠ 反过来的坑也真踩过（2026-10-27）：在配置注释里复述那个 grep 字面量，会让文本 grep 再虚高 1—— 数数只认 YAML 解析，注释与文档里都别写出那个字面量（docs/门禁说明/nested-comment.md§8 记了现场）。 实跑侧口径：scripts/ci_local.py的[SUMMARY] L0: pre-commit hooks -- passed=A failed=B skipped=C，A+B+C= commit 阶段的钩子数（50），再加gitlint1 条（它的 commit-msg 阶段声明写在上游仓库自带的 钩子清单里，本配置文件里查不到，见scripts/ci_local.py文件头）→ 50 + 1 = 51 = 声明数，三数同源。 - 通用机制（两阶段、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 台账）、generated-fresh（5 处 docs/images/ 配图存量，脚本内 BASELINE）、nested-comment（2 处主机侧假件头，test/host/common/，脚本内 BASELINE） |
报错先分清是新增还是存量搬家：--verbose 看归类，--prune 看已还清 |
⚠ 增量拦截最容易误会的一点：绿灯不等于没问题，只等于"没有比上次更差"。 每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。
2. 索引（51 个 hook → 27 篇 + 1 根只有本表指针（专篇待补）+ 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 |
已写 |
nested-comment.md |
nested-comment |
块注释体内再出现 /*（ARMCC 9-D 嵌套注释；诱因是注释里写路径通配） | 全仓 .c/.h（第三方与生成物除外） |
已写 |
generated-fresh.md |
generated-fresh |
生成器幂等性：把生成器重跑到系统临时目录，与工作区逐字节必须一致（不一致 = 生成物比生成器旧） | tools/**、UI 源码、ui_menu_tree.txt、ui_cn_chars.txt、docs/images/*.svg、两份注册表 |
已写 |
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 状态 + 内容页 40 页黄金参考图比对 | UI 源码、模拟器 | 已写 |
bom-guard.md |
bom-guard |
带 BOM 的文件被编辑工具剥掉 BOM（ARMCC 换解码 → 假语法错） | Drivers/BSP/UI/** 等名单内文件 |
已写 |
setview-check.md |
setview-check |
定值查看行表与 prot_set 枚举序 / g_prot_set_meta 上下限是否同一份口径 |
tools/setview_check/**、ui_w_setview.* |
已写 |
（专篇待补，档位与限度正文在 ../UI设计/UI_自动化测试流程.md §7.3） |
uinav-selftest |
板端 UI 导航器认屏快检（黄金参考帧分类；完整闭环档=合入前/上板前手工跑，快检不互替） | scripts/board_ui_nav.py、simulator/tests/ref/*.bin |
指针 |
host-unit-tests.md |
22 个 *-unit-test |
主机侧单测（同一机制 22 个实例）：逻辑层在无硬件的 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. 现状与下一步
- 本目录 27 篇已全部成文（2026-10-27 实测口径：
docs/门禁说明/下除 README 外 27 篇，与上表「文档」列 一一对应——「有页无行」与「有行无页」两个差集都是空集；一行覆盖多个 hook 的行（cppcheck+test-cppcheck、 22 个*-unit-test）按行内列举计。上一句写「23 篇」是存量误差：2026-10-25 连加bom-guard/setview-check/uinav-selftest三根、本轮加generated-fresh都没同步它（本轮前实有 25 篇）。 加钩子时的三步见下一行，第 ③ 步的计数与本目录 §2 标题、AGENTS.md 的钩子数必须同一笔改。 - 新增/改动一个门禁时的三步：① 在
.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"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。