wandering1
e4d70f9fcb
证据源 = 主树 ci-artifacts/archify/architecture-dtu-overview-20261030-095132/ evidence.md §11。该目录不入库，故把每条的判据与实测源抄进正文，别让证据只活在 一台机器上。处置口径：能改的改成与代码同源，核实后确认文档没问题的明确写「不改」。 判停点与就绪屏障（条 1、条 3） - AGENTS 原写 `protect_task.c:98` 直接停走判据：`:98` 是 `s_prev_cal_lock` 变量， 判停点是 `App/task/protect_task.c:268 if (adc_cal_prot_blocked() != 0u)`， 判定本体在标定层 `adc_cal_prot_blocked()`、protectTask 只是消费者 → 改引用， 同步 `ui_task.c:240` 页面注释与 `docs/任务规划/数据可信.md` 的同一处行号。 - `SYS_EVT_FTP_READY` 有生产者（`Src/freertos.c:490`，注释自陈预留）无消费者； `SYS_EVT_TIMESYNC_READY` 全仓无生产者也无消费者（只有定义与测试桩）。 AGENTS、`sys_events.h` 位注释、屏障配图（生成器 + 产物）三处从「四个就绪位 并列」改成「bit0/bit1 在用 + bit2/bit3 预留」，并指向 `docs/架构设计/项目启动顺序管理.md` §3.2 的逐位对照表。ftpTask 实际等的是 `NET|STORAGE`（`Src/freertos.c:477-479`，WaitAll|NoClear，100 ms 分片喂狗）。 /log 不是「三本」（条 5） - `App/log/sys_log_mcu.c` 的 `s_paths[]` = run / selftest / accid / alarm / start / oper / yk 七本 64B 定长文本 + `soe.log`（64B 定长二进制）+ `wdev.log` （变长取证行，`App/fs/vol_lock` 侧投，不走定长格式）。 → AGENTS 两处、总览 §2.1 与 §4 的「三本」改成「七本 + SOE（+ wdev 取证行）」。 主机单测 44 套 → 47 套（条 2，两把机器尺互证） - `scripts/check_test_coverage.py --list` 打印 47 行；`ls -d test/host/*/` = 48 个 一级目录，唯一没有 `run_unit_test.py` 的是 `common/` ⇒ 47 套。 - 差额三名 = 屏板链路套件：`sb_proto`、`sb_link`（2026-10-29 入库）、 `sb_led_map`（2026-10-30 入库）。专属钩子仍是 22 根 ⇒ 无专属钩子的从 22 套变 25 套。 - 同步面：AGENTS、`docs/门禁说明/README.md`、`host-unit-tests.md` §6 台账（名单补 三名）、`docs/代码规范/pre-commit使用说明.md`、`主机单测覆盖率口径.md`（含耗时句）、 `scripts/README.md`、总览目录树、`.pre-commit-config.yaml` 三处注释、 `test/host/sys_log_mcu/sys_log_mcu_test.c` 一处注释。 - 带日期戳的历史测量值按纪律冻结不动：28 套、41 套 ~105 s、40 套/18 套那三处。 本仓 LVGL 版本（条 6） - vendored 版本 = `Lib/lvgl/lv_version.h:9-11` 的 9.3.0；总览两处「LVGL v9.2」与 `gen_arch_svg.py` 图内文字改 v9.3 并重跑产物（脚本与产物同一笔，`generated-fresh` 逐字节核）。 - **刻意不动**：`docs/内存管理/RAM使用分析与优化方案.md` 两处「LVGL v9.2 文档」+ GitHub `release/v9.2` 分支 URL ——那是对外游某分支文档的引用，不是本仓版本声明。 触发口径与栈值（条 4、7、9、10） - ADC 映射 §1「ADC1 为软件触发」是旧口径：`Src/adc.c:53` 实为 `ADC_EXTERNALTRIGCONV_T3_TRGO` → 改成 TIM3 TRGO，并补一句「TIM3 与 TPAFE 的 CONVST 之间没有硬件耦合，仍不构成共同采样触发」，缺陷结论本身不变。 - 同文档 adcTask 栈 512 → 640 words（`Src/freertos.c:159 .stack_size = 640 * 4`）。 - `docs/UI设计/UI_设计架构.md` 的 uiTask 栈「16384 words」是单位错： 实为 4096 words = 16384 B（`Src/freertos.c:218`），顺手补上行号。 - `App/app/app_main.c:197` 注释「DE = PD0」陈旧：`:198` 实传 `ST_DIR4_*` （V0.1 实板 PA15，V0.0 才是 PD0）→ 注释改指 V0.1 网表报告的引脚迁移表。 - 两处已退役编号 `N-18`（ADC 映射、V0.1 网表报告）换成登记簿条目名 「双转换器无共同采样触发」。 核实后确认「文档没问题」的三条（条 8、12、13） - 黄金参考「菜单 8 状态 + 内容页 66 张」：`simulator/tests/ref/` 实测 66 个 `shot_*.bin`，与 `ui-golden` 钩子显示名一致 → 不改。 - `App/task/rs485_task.c` 存在但 `Src/freertos.c` 不创建它（grep 无 rs485）： AGENTS 与总览都已写明「尚未接线 / 暂缓」，图侧画成「实现待接线」→ 不改。 - 104 端口 `:2404` 是工厂默认、可经 `/config.ini` `[comm]` 改 → 总览索引表补 「默认」二字；「uiTask 10 ms 节拍」核实 = `ui_tokens.h:65 UI_TASK_TICK_MS 10` ✓。 并行勘查会话的同族发现（它扫「文档声明数 vs 真值」，逐处独立复验后采纳 3 处） - `App/protocol/iec104/iec104_link.h` 头注释写「端口：TCP 2404（§1.5 B0 定义）」， 同文件下方已写「服务端口真源已迁 [comm] 段」= 自相矛盾 → 补「工厂默认」并指回 [comm] 与「下次重 bind 即生效」。 - `scripts/gen_task_table.py` 的 iec104Task 描述「:2404 监听」→「工厂默认 :2404 监听」，`--write` 重生成 README 任务表（AGENTS 表无描述列，实测未被改写）。 - `App/log/README.md` 五行写入点行号全漂：事故 181→188、告警 184→191、启动 176→183（`App/task/protect_task.c`）；操作 `iec104_pts.c` 574/602→582/610、 `default_task.c` 242→266、`sys_log_mcu.c` 646→682；遥控 573/576/582/586/596/ 598/609 → 581/584/590/594/604/606/617（宿主 `sim_syslog.c:245` 原值正确、未动）。 - **撤销一条**：我早先记的「`docs/算法/继电保护功能复现规划.md:225` 声称记录本已 有消费者」与原文不符——:225 实为规划表里「动作/SOE 记录 | 复用 `sys_log`」一行， 属能力复用口径、不是当前态断言 → 不改。教训：**改引用前逐处读现文，别照自己 上一轮的笔记盲替**（这条比改中的每一处都值钱）。 - 同一批勘查还报了约 12 处「`2404` 缺『工厂默认』限定词」（AGENTS、`App/protocol/ README.md`、`Src/freertos.c` 注释、5 篇 docs、`test/host` 工具，含一张配图生成器 要连产物同批重跑）与 `测试开发标准流程.md`「像素层 60 内容页」、 `.pre-commit-config.yaml` uinav 注释「快检档 18 张黄金参考」（后者写时为真、 描述的却是钩子现有行为）：**本笔刻意不做**，另开任务空间处理——那批要同时动 AGENTS.md 与 `.pre-commit-config.yaml` 两处单写者面，与并行会话撞车的代价更高。 - 端口生效语义（用户裁定 2026-10-30）：产品基线写「公共地址与端口可配…改后需重启 生效」，代码 `App/task/iec104_serv.c` 是「ca 改后要重启；port 下次重 bind 才生效」 ——裁定**按代码语义要改**处理（改了端口应立刻重 bind），属固件行为变更，另开任务 且需真机验证；`.serialtest/config.json` 写死 `i104: listening on 2404` 必检锚点 是同题（现场改端口会让串口回归假失败），一并留给那条任务。 自查（任务树内） - `check_doc_links.py --sections-strict`：12 个改动 .md 逐个 rc=0； `check_mermaid.py` 改动 .md 全 rc=0；`check_generated_fresh.py` PASS （25 个生成器 / 21 一致 / 4 存量基线）；`check_nested_comment.py --all` PASS （449 文件，新发 0、存量 2）；`check_bom_drift.py --all` 99 个名单文件无漂移。 - 编译：`.dsh/skills/keil-build` 退出码 0（0 错误 0 警告）， Program Size Code=246720 RO=29836 RW=2052 ZI=149708 —— 与本树凭证同码， 证明这批改的确实只有注释与文档。 - 字节体检：23 个文件无 CR / U+FFFD / 行尾空格 / 缺末行换行；`ui_task.c` 被编辑后 丢的 3 字节 BOM 已补回（bom-guard 复验通过）；5 处「三连空行」逐文件与 HEAD 比对确认是存量（Python 生成器的 PEP8 双空行与个别 C 文件原有空行）。 - 一次性工具 `ci-artifacts/fix_docs2.py`：断言式规则表，按文件读一次、在演化文本上 逐条替换、一次写盘。第一版写成「每条规则各自从启动时快照起算」，同一文件后一条 把前一条整体覆盖，只有每文件最后一条活下来——靠「改完再全仓复扫旧形态」当场抓到， 这条判据本身已值得写进流程。 - 待办：`git add` 后需重跑 `ram_baseline.py --update`（体积凭证按 git 索引内容生成， 未 staged 的文件不在凭证里，`check_size_gate.py --local` 现在因此报红）。 - 未 commit、未 push（AGENTS.md 边界：提交属 Ask first）。
17 KiB
17 KiB
门禁逐项说明（每种门禁一篇）
本目录逐项说明各门禁：声明的 52 个钩子到底在干什么、拦谁、放谁、什么时候会骗人——其中 3 根慢钩子带
stages: [manual]，一次git commit只实跑 49 根（口径见下条）。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
- 配置事实源：
.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； 2026-10-28：51 → 52 加id-check-new、随即 52 → 51 摘掉id-check（退役全库语料审计）；2026-10-29：51 → 52 加skill-size（SKILL.md 写侧上限与 reference 指针，详见skill-size.md）； 同日 52 → 51 退役id-check-new——只查新增行的编号门禁整体退场，脚本与白名单移入scripts/archive/id_gate/，此后编号形态没有机器面（留档id-check-new.md）； 2026-10-30：51 → 52 加mermaid-syntax（mermaid 围栏内确定性语法：坏图渲染失败靠肉眼才逮过， 详见mermaid-syntax.md））。 ⚠ 别用grep -c去数配置里的声明行：该文件里有一条注释掉的候选钩子（clang-format，第 65 行）， 文本 grep 会多算 1（当前口径 52 会数成 53）——「声明比文档多 1 / 实跑又少一档」这种三个数不同源的争执就是这么来的。真要 grep， 用锚定行首缩进的模式（它天然跳过以 # 开头的注释行）2026-10-28 实测直接得 51（当时口径）、 2026-10-30 复测得 52，均与 YAML 口径一致； 会多算 1（比口径多 1）的是不锚定行首、按子串匹配声明行的写法（那条被注释掉的候选也被它算进去）。 ⚠ 反过来的坑也真踩过（2026-10-27）：在配置注释里复述那个 grep 字面量，会让文本 grep 再虚高 1—— 数数只认 YAML 解析，注释与文档里都别写出那个字面量（docs/门禁说明/nested-comment.md§8 记了现场）。 实跑侧口径：scripts/ci_local.py的静态门禁汇总行[SUMMARY] …: pre-commit hooks -- passed=A failed=B skipped=C（方括号里那一段是层级名，脚本输出与文档层的语义名正分头迁移 → 抓这行按passed=字段匹配，别把层级名前缀写死进字面量，否则会 grep 不到而误判「没有实跑数」），A+B+C= pre-commit 阶段的钩子数（48 = 52 − 3 根stages: [manual]−gitlint；2026-10-30 加mermaid-syntax前该式子右侧是 51/47），再加gitlint1 条（它声明在本配置的repo: jorisroovers/gitlint条目、stages: [commit-msg]（第 70 行），--hook-stage commit的枚举不含它——2026-10-30 实测：--hook-stage commit枚举 47 行 /manual枚举 50 行 / YAML 解析声明 51（加本钩后 48/51/52）， 47 + 3 + 1 = 51，差的那个就是gitlint；旧说法「gitlint 声明在上游清单、本配置里查不到」已于当日随stages:接线作废） → 48 + 1 = 49 = 一次git commit实跑的钩子数；再加 3 根 manual 阶段的慢钩子才是声明数 52，三数同源（2026-10-29 加skill-size之前这四个数是 51 / 47 / 48；2026-10-30 加mermaid-syntax后是 52 / 48 / 49）。 枚举自查（不执行任何钩子，SKIP列全部 id）：SKIP=<全部 id> -m pre_commit run --all-files --hook-stage commit输出 47 行、--hook-stage manual输出 50 行（47 常规 + 3 慢的）。 - 三根慢钩子在 manual 阶段：
cppcheck、test-cppcheck、test-coverage带stages: [manual]→git commit阶段不跑（实测三根合计约 165 s，占一次带代码提交耗时的约三分之二），只在远端 CI 的「手动阶段门禁」步 （.gitea/workflows/ci.yml，逐根--hook-stage manual）与scripts/ci_local.py的 manual 段里跑。 本地手工复跑：& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual <hook-id>（一次只能给一个 id，多 id 实测报unrecognized arguments）。声明数仍是 52，变的是「提交期实跑几根」。 - 通用机制（三个阶段 =
pre-commit/commit-msg/manual、stash 陷阱、always已废、增量拦截三段式、旧 §2.x 查号表）：docs/代码规范/pre-commit使用说明.md§2。 - 快速自查（不等提交）：
& '.venv\Scripts\python.exe' scripts/ci_local.py（静态段 48 根 + manual 段三根 + 提交信息门禁 + 体积门禁 + 主机侧纯逻辑单测；manual 段默认跑）。
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、mermaid-syntax（基线为空，先例是已退役的 id-check-new「零语料」；唯一排除面 = 外部资料目录，见其专篇 §7）、22 个主机单测、官方 5 个、gitlint |
只能改代码或改文档；不要找豁免开关 |
| 增量拦截 | 规则恒生效，但存量钉在基线/台账里，只许减不许增 | layer-deps（3 条，2026-10-25 还清 UI 记录 3 条）、bsp-err（38 条）、generated-fresh（5 处 docs/images/ 配图存量，脚本内 BASELINE）、nested-comment（2 处主机侧假件头，test/host/common/，脚本内 BASELINE） |
报错先分清是新增还是存量搬家：--verbose 看归类，--prune 看已还清 |
| 只查新增 | 只看本次改动的增量，没有存量基线，也没有台账 | id-check-newscripts/archive/id_gate/；这一姿态已无现役门禁） |
手工复查时才谈得上：改成语义短语（门禁不再跑，行内 [编号豁免] 也随之失效） |
⚠ 增量拦截最容易误会的一点：绿灯不等于没问题，只等于"没有比上次更差"。 每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。
2. 索引（52 个 hook → 30 篇，其中 2 篇是已退役门禁的留档 + 1 根只有本表指针（专篇待补）+ 1 根详解在 docs/测试说明/）
带
stages: [manual]的三根（cppcheck/test-cppcheck/test-coverage）提交期不跑，只在远端 CI 的 「手动阶段门禁」步与scripts/ci_local.py的 manual 段跑；下表对应两行的「文档」列已标注。
| 门禁文档 | 覆盖的 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 |
已退役（2026-10-28）：全库语料的八项校验，留档备查；接班件也在下一行 | 在时有：几乎所有文本文件 | 已写（退役留档） |
id-check-new.md |
~id-check-new |
已退役（2026-10-29，用户裁定）：只查新增行的编号门禁，留档备查（含退役理由与手工跑法）；编号形态此后无机器面 | 在时有：任意 md/c/h/py/yaml/txt | 已写（退役留档） |
doc-links.md |
doc-links |
文档里的路径引用是否存在；--sections-strict 另查章节号是否还存在 |
任意 .md |
已写 |
mermaid-syntax.md |
mermaid-syntax |
```mermaid 围栏内确定性语法：图类型头 / -. 直接跟管道 / subgraph 与 sequence 块的 end 配对 |
任意 .md（docs/芯片手册/ 等与 doc-links 同排除面） |
已写 |
cppcheck.md |
cppcheck、test-cppcheck |
静态分析（真机侧与 test/ 侧两套范围与抑制项） |
C/H 源文件 | 已写（stages: [manual]） |
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（第三方与生成物除外） |
已写 |
skill-size.md |
skill-size |
SKILL.md 不超插件写侧上限 65536 字节（只在写侧校验、加载侧不查：超限的技能照常能读、每次「生成草案」却被拒、永久卡在「生成中」）+ reference/ 指针不悬空 + 不带 BOM |
.dsh/skills/**（filenames 只当触发，判定始终全树扫） |
已写 |
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 重生成会不会把定制静默抹掉（人工目检审计兜底） | .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 状态 + 内容页 66 张黄金参考图比对 | 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 |
覆盖率总闸：跑全部 47 套主机单测 + 已覆盖行只增不减的回退台账 | App/、Drivers/BSP/、test/host/、脚本与基线 |
已写（在 docs/测试说明/；stages: [manual]） |
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. 现状与下一步
- 本目录 30 篇已全部成文（2026-10-30 加
mermaid-syntax一篇 → 30；2026-10-29 加skill-size一篇 → 29；2026-10-27 实测当时 27 篇；2026-10-28 当时复核：docs/门禁说明/下除 README 外 28 篇，与上表「文档」列 一一对应——「有页无行」与「有行无页」两个差集都是空集；一行覆盖多个 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"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。