wandering1
a92baa269e
道F task-22 commit 2/2（F1 票收尾）。素材 = 2026-10-25 最终主干 1a624b1（含看门狗 v1.5 按位分账 + F3 推流心跳边界）上的两轮 30min 判据轮；serial-assistant live 日志 按字节偏移切片（不 clear、行边界对齐），gz 前置 ASCII 头行记录偏移窗/负载定义/ v1.1 判据结论。原 megawin 16:18-16:48 摘录因 @test clear 轮转灭失（全盘无副本， lead 核定非事故），归档位按裁改存这两只（v1.1 判据下的达标基线 + 残留真信号）。 轮①（:7003 relisten_stress 单独 30min，2200 connect/close 零拒绝）= PASS： stall=0；MISS 758 条 NET 缺席=0（旧 12 条 NET 参与组合消失达成）；uisn 在途峰 103ms / uis 完成峰 183ms / UI 周期最坏 254ms——F2 复合零误报 + F3 阻塞型治愈的 定案样本。sha256 前 16 = 383dd291f37c6a5d（gz 165KB / raw 1.87MB）。 轮②（e02_probe 单独 30min，50 掉线窗）= FAIL（如实申报，零放水）：stall=8 = 3 事件（20:06:05/20:16:54/20:20:30；mask=0x1E7 纯 UI×7 + 0x167 UI+I104×1，h= 环全部 >=8 连窗真申报）；饿死型证据链：每样本点 uisn=0 + mg=217/262 + 拖点在 feed/port 墙钟而非推流段——「reconcile 突发饿死 uiTask」登记行与 E-27/28 批 3 的直接立项 证据（lead 裁定单列，处置方向 = 优先级矩阵复核 / reconcile 突发分片让路两条）。 全窗无 IWDG 复位。sha256 前 16 = b44eb3371c25e04c（gz 79KB / raw 0.75MB）。 README §3 表首两行沿用 B6/B7 验收轮先例（第三列放判据摘要）+ 表后存档说明行 （判读证据存档 != [STACK] 水位快照；判据口径指针 §7.2/工具名）。 【配套门禁修复（越界申报，因果耦合）】id-check 对二进制工件按文本 errors=replace 扫描：gz 乱码流随机拼出「字母-数字」形态伪编号，把无关存量顶成校验 1 台账外新账 （本 gz 入库实测拦下提交；png 属同类侥幸未撞形态）。iter_files 增加二进制嗅探跳过 （gzip 魔数或头 2KB 含 NUL → binary_skipped），与 noise_literals/盲区同口径； docs/门禁说明/id-check.md §6 第 9 条 + 变更记录同步。教训自含：修复说明里引用噪声 示例本身会被再扫一遍——文档措辞只描述形态不举例（本次真实返工一次）。 scripts/check_ids.py 可写工具面，非登记簿/单写者文件；.pre-commit-config.yaml 未动。 【门禁】本树补跑 @build 0/0 落 .map；--all-files 48 绿 0 红；uvprojx UV4 抖动未入库； 登记簿双销项 + 新语义行 = lead 单写，本提交不碰 docs/任务规划/**。
门禁逐项说明（每种门禁一篇）
这一目录回答一个问题：提交时那 49 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
- 配置事实源：
.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. 索引（49 个 hook → 26 篇 + 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 状态 + 内容页 18 页黄金参考图比对 | 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. 现状与下一步
- 本目录 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"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。