wandering1
db9f256fd0
- test/board/ch395f_test.h：f3 轮台架记录追加——VERDICT PASS， task stall 468→14（net 类 431→0，掩码复活实锤），余 13 条为 netTask 自挂起前喂一次 vs 精确匹配判据的语义打架 + 1 条 uiTask 瞬态 + 1 条设计内 P2 留痕；lead 裁决不放宽超集判定 - 主机单测覆盖率口径.md：中间产物路径 L80 与坑 12 重写为 %TEMP%/dtu_host/<工作树哈希>/ 分家 + runs 独占（adabb6a 落地， 旧固定共享名作废；判据正文指向 harness 顶部） - 并行任务工作树方案.md §5 表：单测产物一行——不需要锁但必须 按树分家（对照 build/bench 真独占） - 门禁说明/cubemx-survival.md §6：新增第 7 条「基线漏项=静默不检」 （net-msgq-adopt 实证，--write 后抽查新增条目） - 门禁说明/id-check.md §5：拦下过真事追加——P1-10 注释裸编号被 校验 6 拦（紧邻写法在 C 注释同样生效）
9.5 KiB
9.5 KiB
id-check — 编号门禁（实体编号的八项校验）
一句话：它管**"号"这个东西不许野生**——每个编号必须属于一个已登记的族、形态合法、 有定义处、有人引用、引用它的时候说清是哪篇文档的号。 规范正文 =
docs/编号规范.md（§4 前缀总表、§8 门禁），本门禁是那八项的机械执行。
- 配置：
entry: python scripts/check_ids.py --strict，pass_filenames: false，files:覆盖.md/.c/.h/.py/.yaml/.json/.txt与配置文件本身。 - 两份数据源（不是脚本里写死的）：
scripts/id_registry.json（族 → 形态正则 / 属主登记处 / 是否冻结 / 游标 / 作用域 / 级别）、scripts/id_aliases.json（旧字面量 → 现行字面量）。
1. 它在查什么
| 校验 | 内容 | 级别 |
|---|---|---|
| 1 | 出现未登记前缀（自造编号） | 错误 |
| 2 | 形态不合规：缺连字符的裸形（模块字母直接跟数字）、族名与数字之间空一格的空格形、中文形、补零位数不对、档位词带后缀、缺模块码 | 错误 |
| 3 | 悬空引用：引用了查无定义且不在别名表的号 | 错误 |
| 4 | 重复定义：同一字面量被两个属主各定义一次 | 错误 |
| 5 | 冻结族越游标：已冻结的族里出现游标之外的新号 | 错误 |
| 6 | 引用未紧邻文档名：文档内编号（各文档自己的风险表等）裸引 | 错误 |
| 7 | 孤儿条目：定义了但全库无人引用 | 告警（不拦） |
| 8 | 打印编号引用可判定比例，只许涨不许跌（跌破 id_registry.json 里的基线即失败） |
恒生效 |
"定义"的机械判据是：该字面量出现在它所属族的"属主登记处"文档里。不依赖表格行首之类 容易漂移的形态。副作用要知道：把号写进属主文档的任何位置都算定义。
2. 为什么要它
- 本仓同时存在
N-xx/N-x/TC-*/E-xx/TRAP-*/D10/U12等几十族编号，历史上出过 真事故：登记簿销项删行后号被复用（撞号）、引用指向已被删的号（悬空）、同一字面量两个 属主（重复定义）。规范 §1 把成因写得很直白：连字符与补零偷偷承载语义。 - 本次实测拦下过我自己两次：一次是"字母加数字"自造号（校验 1），一次是引用某个跨文档 编号时没紧邻文档名（校验 6）——两次都是提交前门直接报，说明它在真起作用。
- 校验 8 是唯一的"趋势"闸门：它不要求号变少，只要求解释能力不许退化（新增不可判定的字面量会让比例下跌 → 失败）。
owner_docs≠ 定义集（2026-10-25 起）：族可以"有登记处"却"没有定义位"。判可判定只看owner_docs是否解析出真实文件；而悬空（校验 3）/ 撞号（校验 4）/ 裸形（校验 2）/ 紧邻（校验 6） 一律只看_def_owners。两者仅在一种情形下不同：snapshot_only族的登记处挂在规范正文 （docs/编号规范.md§4.5 那种冻结存档表）。规范里混着大量写法示例（N-99、S1、N-31）， 若拿它当定义集会立刻误伤——实测裸形S1被判成S-1漏连字符 238 条、表里S-3与登记簿 S-3 被判重复定义。所以这类族的_def_owners为空，等价于"属主已删、只有存档"。 代价要认清：这类族的号不会再被校验 3 兜住，新增引用只能靠别名表或人工核。
3. 触发面
- 扫描面以 git 清单为准。当前一次实跑：696 个文件、编号字面量 10410 处。
- 排除：
Lib/、Middlewares/、HAL/CMSIS、docs/芯片手册/、docs/硬件平台/。 最后一个是关键：硬件文档里的元器件位号U1/C12/R3/L5/D7与我们的编号字面 同形，不整体排除就会大量误报（脚本里另有一套位号识别，但仍没有解除这两个目录的语料排除）。 - 已声明的"同号不同义"族对（
docs/编号规范.md§4.3）：实跑 583 个字面量走collides_with白名单，不计入校验 4。
4. 报错怎么读
[FAIL] 编号门禁·增量拦截：N 类台账之外的错误级问题（新引入的债）
+2 [校验1] <文件> <字面量>
→ 改引用/补登记处；确属该欠的债要在台账写 reason（默认禁止顺手加）
- 单独跑：
& '.venv\Scripts\python.exe' scripts/check_ids.py --strict --verbose（--verbose带修法，--top 30多打，--only 1,3,5只跑指定校验）。 - 常用旗标：
--strict（钩子用的档位）、--verbose、--write-backlog/--prune-backlog（重建 / 收紧台账）、--update-baseline（把当前可判定比例写回id_registry.json，只许涨）、--no-trace。 - 存量在
scripts/id_known_backlog.json（按指纹豁免，实跑 640 处在册）。
5. 好处
-
拦下过真事（2026-10-25 追加）：
docs/任务规划/测试与架构专项.mdP1-10 的返工提交被 校验 6 拦下 4 处——C 注释里裸写编号、未紧邻属主文档名；改成「条目属主docs/任务规划/测试与架构专项.mdP1-10」即过。 实证紧邻写法在代码注释里同样是硬约束，不是只约束 Markdown。 -
把"编号卫生"从人脑记忆变成机器判定：销项只做一半、引用写错文档、自造号，都会在提交时被点名。
-
台账机制让存量不阻塞日常工作，同时"无台账外新账"这句话是可验证的承诺。
6. 限制与盲区（这一节请当正文读）
- 绿灯不等于编号都合法：门禁是【增量拦截】——存量 640 处按台账豁免。它保证的是 "没变差"，不是"干净"。
collides_with白名单挡事故、不挡可读性。已声明同号不同义的族对不再报——于是 "新造一个和已有裸形撞车的代号"可以一路绿灯。这正是本门禁今天照不出来的东西： 我自己造的四个字母数字代号在被改名前，没有任何一条校验会响（同形多义已被声明为已知事实）。 结论：编号可读性要人管，docs/门禁说明/bsp-err.md§6 那条就是这个教训的落点。- 实跑有 867 处"裸形盲区"：形态太像普通词/数字组合的字面量识别不出来，等于不在管辖内。
- 校验 7（孤儿）只告警不拦提交：定义完一直没人引用的号会长期存在而门禁不响。
- "定义"的判据是"出现在属主登记处文档里"，不校验语义：写进错的属主文档、或写成一句 否定（"该号从未存在"）也算定义——批量改名工具最阴的失效模式就是"字面改对、意思改错"。
- 登记表类文件不得当引用语料（
id_registry.json、id_aliases.json、id_known_backlog.json、scripts/rename_maps/里必然写着旧的非法形态），否则第一次提交就被自家审计表当"新账"拦下。 - 校验 8 只许涨不许跌：好处是防退化，代价是顺手写一个未登记族的号就会红，哪怕与本次改动无关。
- 它不懂"这个号该不该存在"。新增一族编号是否合理，仍是
docs/编号规范.md的人工判断。
- 裸形多义是显式承认的盲区（
docs/编号规范.md§1 与 §4.4）：同一个裸形字母在本仓可能同时是风险号、 档位、层号、元器件位号。所以裸形族只在属主登记处文档内判"越游标"，文档外降级处理。本目录bsp-err.md§6 记的那件事正是这个洞的产物。 - 本钩子顺带收编
scripts/check_test_traceability.py（TC 用例双向追溯），它不是独立钩子； 改 TC 相关正则时两个脚本要一起看（历史上批量改名后就出现过正则上界没跟上、整批号不再被匹配）。 - 有牙实测的做法：把假编号注入临时档（
git add -N进索引，跑完git rm --cached并删除， 保证git status干净），看它是否被点名。 --update-baseline只许涨：可判定比例下跌时拒绝写入——防止用抬基线掩盖退化。
7. 豁免与台账口径
- 存量：
scripts/id_known_backlog.json（指纹级）；只减不增，收紧用--prune-backlog。 - 别名：
scripts/id_aliases.json（旧字面量 → 现行字面量）——号改名走scripts/rename_ids.py， 它会显式写别名条目，绝不全局查找替换。 - 比例基线：
id_registry.json的decidable_ratio_baseline（实跑当前 84.02%，基线 84.0%、容差 0.1pp）。
8. 改这个门禁本身
- 改族定义 = 改
scripts/id_registry.json，改完必须看编号字面量总数有没有变小： 历史上两次批量改名后，识别正则的上界没跟着放宽，整批号不再被匹配（等于静默放行）。 - 不要为了绿而往台账加 reason；确实该欠的债要写清楚原因（默认禁止顺手加）。
- 台账文件自身不是语料（见 §6 第 6 条），改动它之后要单跑一次确认没有自循环新账。
9. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-25 | 补「owner_docs ≠ 定义集」口径（§2 末条）：snapshot_only 族的登记处挂在规范正文时，_def_owners 为空 → 只恢复可判定、不参与悬空/撞号/裸形/紧邻。基线 82.6% → 84.0%（删《项目审查与优化建议报告》+ 补登 11 条已死号别名后重打，实测 84.02%、696 文件 / 10410 字面量） |
| 2026-10-23 | 首篇逐项文档（数据为当日实跑：551 文件 / 8868 字面量 / 台账 640 处 / 可判定 82.85%） |