From f8d795c387d7dbdbaae2da249ad48206cca3ae38 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Thu, 29 Oct 2026 20:53:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E7=BC=96=E5=8F=B7=E8=A7=84=E8=8C=83):=20?= =?UTF-8?q?=E6=8C=89=E6=9C=BA=E5=99=A8=E9=9D=A2=E9=80=80=E5=BD=B9=E6=94=B9?= =?UTF-8?q?=E5=86=99=E8=A7=84=E8=8C=83=E6=AD=A3=E6=96=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 依据（逐条回配置核实）：三处配置里 id_registry / check_ids / id_known_backlog 命中数全为 0，没有任何活物再读编号登记； check_test_traceability.py 存在但没被任何配置跑；变更记录例外 清单实测只剩 5 篇。 改写要点：TC 框把「registry 带游标所以允许发」改成裁定留痕并 明写别把不报错读成允许发号；删掉探针行与自相矛盾的 7 行； §4.1.1 四处现在时（已冻结 / 越游标即拦 / 发号口已关闭 / 校验 错误级）改历史口径，中文前缀族改成「从来没有机器面」；§4.3 点明冻结前缀是档案不是闸门；§5.1 三步改成「族落在 §4.1 之 内 → 属主登记处写定义行 → 才允许引用」；§5.5 删掉「门禁已 豁免」口气并不再复述份数；§8 标题改「一道也没有」；§8.5 由 退役路线流水表整体替换为「手工普查与恢复机器面」（两条归档 命令 + 恢复成本三步 + 退役理由与 WAVE00 误拦），§8 / §8.5 编号刻意保留以免外部引用断链。 指针同步：AGENTS.md 与配置注释里的「§8.5 路线」改成新节名； id-family-semantic-migration 的 SKILL.md 与两份 reference 把 §9 事实源指针改指归档、把「门禁咬不到」措辞改成「连归档扫描 工具都咬不到」。 校验：本篇逐篇 check_doc_links --sections-strict rc=0（60 处 引用 / 58 可判定 97 % / 无法判定 0）；check_skill_size rc=0； 表格列数 0 处不一致；无 BOM / CR / 乱码 / 行尾空格，单 LF 收尾； YAML 解析钩子声明数仍 51（配置只改注释）。 --- .../id-family-semantic-migration/SKILL.md | 4 +- .../reference/steps-alpha-numeric-family.md | 10 +- .../reference/steps-chinese-prefix-family.md | 8 +- .pre-commit-config.yaml | 2 +- AGENTS.md | 2 +- docs/编号规范.md | 138 ++++++++++-------- 6 files changed, 87 insertions(+), 77 deletions(-) diff --git a/.dsh/skills/id-family-semantic-migration/SKILL.md b/.dsh/skills/id-family-semantic-migration/SKILL.md index 3b04a4ae..4237d6eb 100644 --- a/.dsh/skills/id-family-semantic-migration/SKILL.md +++ b/.dsh/skills/id-family-semantic-migration/SKILL.md @@ -48,9 +48,9 @@ version: 1.1.0 14. 裁定「不做」也要写成可执行硬口径入档 > 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-alpha-numeric-family.md](reference/steps-alpha-numeric-family.md)。动手前先读那篇。 -## Steps（中文前缀族：门禁咬不到的那一路） +## Steps（中文前缀族：连归档扫描工具都咬不到的那一路） -1. 先确认门禁咬不到，并把这句话写进交付 +1. 先确认连归档扫描工具也咬不到（两道编号门禁 2026-10-28 / 29 已退役，"咬不咬"从此只是工具层面的事），并把这句话写进交付 2. 销项删行前先核证据属主 3. 自建带标签正则扫描脚本 4. 该族与形似噪声号分开计数，各自给分母 diff --git a/.dsh/skills/id-family-semantic-migration/reference/steps-alpha-numeric-family.md b/.dsh/skills/id-family-semantic-migration/reference/steps-alpha-numeric-family.md index d9e1c61c..82ba2c49 100644 --- a/.dsh/skills/id-family-semantic-migration/reference/steps-alpha-numeric-family.md +++ b/.dsh/skills/id-family-semantic-migration/reference/steps-alpha-numeric-family.md @@ -2,7 +2,7 @@ > 本文由 id-family-semantic-migration 的 SKILL.md「Steps（字母+数字族：门禁看得见的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。 -1. **确认范围与定调**：先按开头的表判识别面（无识别面 → 走下一节）；再读 `docs/编号规范.md` §4.1（族总表，穷举）、§4.1.1（已停发栏），存量与批次见 `scripts/archive/id_gate/编号治理历史.md` §9，明确本族属主登记处（`owner_docs_glob`）与判据「有脚本按字面量匹配它」。清退 = 全仓改语义；停发 = 游标冻结、只减不增。 +1. **确认范围与定调**：先按开头的表判识别面（无识别面 → 走下一节）；再读 `docs/编号规范.md` §4.1（族总表，穷举）、§4.1.1（已停发栏），存量与批次见 `scripts/archive/id_gate/编号治理历史.md` §9，明确本族属主登记处（`owner_docs_glob`）与判据「有脚本按字面量匹配它」。清退 = 全仓改语义；停发 = 在规范表里写死不再新增引用（`id_registry.json` 的游标冻结只是裁定留痕，2026-10-29 起无机器读者）。 2. **按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数**。`Checker.refs` 是 **dict（字面量 → 文件集合）不是方法**，`ck.refs(fam)` 这种写法会 `TypeError`；站点数门禁不直接给，用族正则重扫它自己的语料： ```python import sys; sys.path.insert(0, "scripts") @@ -38,7 +38,7 @@ p.write_text(t, encoding='utf-8') ``` **token 取最小形态**：文档里被反引号/加粗包住的号，替换单位取反引号形（```T4```）而**不含 `**` 标记**（第 225 行是 `**裸形 `T4`**`，按「裸形 `T4`」替就命中 0）。讲编号的文档改成**形态描述**（如「字母 T 紧跟数字 4」）能把不可判定绝对数还回余量：实测 4 处 → 982 降到 978，且 lesson 不丢。 -8. **同步更新门禁侧配置**：`check_ids` 的 `excluded_paths` 与噪声表按第 3 步的分类结果改，使剩余命中不再是「假编号」；新测试套件发号的悬空引用要先定**定义位**： +8. **同步更新归档扫描器的配置**：`check_ids` 的 `excluded_paths` 与噪声表按第 3 步的分类结果改，使剩余命中不再是「假编号」；新测试套件发号的悬空引用要先定**定义位**： - 定义位**只能落一处**——注册表族（`scripts/archive/id_gate/id_registry.json`）或该套件说明文档，**两处并存比没有定义位更坏**；文档真写出来了（含判据与上板清单）就以文档为准、**撤族**； - 要建族就照现有同类族克隆（`pattern` / `digit_width` / `owner_docs_glob` / `scope` / `cursor`），别自造字段； - **抬游标前先确认游标是字符串形态**（`'cursor': 'TC-UIDATA-026'`）——整型比较会静默不生效（实测踩坑），用字符串解析或正则取序号再比。 @@ -58,9 +58,9 @@ ./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --strict 2>&1 | tail -1 # [OK] 校验 1~6 无错误 ``` 报告「字面量 8787→8299→7828」「不可判定绝对数 1161→984→982→978（上限 1166）」「可判定比例 88.14%（基线 86.0%，容差 0.1pp）」。**绝对数与比例两根线都要报**：把可判定引用改成散文会稀释比值，所以另有不可判定绝对数上限。涨点归因见「净室归因」一节。 -13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏、§9 存量表与批次结果表（只减不增）、§9 清点数字按最终实测同步；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。 +13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏；存量表与批次结果表在 `scripts/archive/id_gate/编号治理历史.md` §9（只减不增、清点数字按最终实测同步）；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。 14. **裁定「不做」也要写成可执行硬口径入档**（不是只划掉一行——「不做」最容易被读成「那还可以继续发号」）： - §4.1.1「已停发」栏新增该族一行：**游标冻结、现存号只减不增、新用例改用语义化测试函数名 + 文档表格行名**，并写清与「允许继续发号」栏为何不打脸； - - §9.1 批次段落写明裁定原文与理由（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**； + - 批次段落写明裁定原文与理由（归档 `scripts/archive/id_gate/编号治理历史.md` §9.1——§9 一族的事实源已在归档篇，规范正文只留口径）（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**； - 全文核「等你裁定 / 需你裁定」悬空表述残留数归 0； - - 无机器识别面的族落地面不同（§4.1.1 一行 + §9.3 换算表 + 叙述同步三处），见下一节第 7 步。 + - 无机器识别面的族落地面不同（`docs/编号规范.md` §4.1.1 一行 + 归档 `编号治理历史.md` §9.3 换算表 + 叙述同步三处），见下一节第 7 步。 diff --git a/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md b/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md index 1d07ce7f..c6aa16e3 100644 --- a/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md +++ b/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md @@ -1,8 +1,8 @@ -# Steps（中文前缀族：门禁咬不到的那一路）（自 SKILL.md 外置） +# Steps（中文前缀族：连归档扫描工具都咬不到的那一路）（自 SKILL.md 外置） > 本文由 id-family-semantic-migration 的 SKILL.md「Steps（中文前缀族：门禁咬不到的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。 -1. **先确认门禁咬不到，并把这句话写进交付**：`scripts/archive/id_gate/check_ids.py` 的族 pattern 是拉丁形态、中文前缀不进语料 → **id-check 的 refs / 可判定比例 / 悬空引用与本族无关**；报告开头写「本族不在 check_ids 语料内，口径 = 自建扫描器」。 +1. **先确认连归档扫描工具也咬不到，并把这句话写进交付**（两道编号门禁已退役，机器面整体消失）：`scripts/archive/id_gate/check_ids.py` 的族 pattern 是拉丁形态、中文前缀不进语料 → **id-check 的 refs / 可判定比例 / 悬空引用与本族无关**；报告开头写「本族不在 check_ids 语料内，口径 = 自建扫描器」。 2. **销项删行前先核证据属主**（这是删行的唯一许可证）： - 先取历史口径：`git log --oneline -20 -- <文档>`、`git show :<文档> | sed -n '/^## 5/,/^## 6/p'` 找回被删的卡表与当初「完成即销项删行 / 标 ✅ 保留行」的理由； - 核对判据与实测记录**已完整沉淀进属主章节**（实测：「已知电压注入验证」六项判据全 PASS、斜率 6544.2 码/V、偏差 −0.14 % 全在 `docs/硬件平台/ADC通道映射说明.md` §8.1，执行侧在 `docs/测试说明/ADC前端注入验证流程.md`）； @@ -48,8 +48,8 @@ 5. **派单前写一份 spec 文件**（`ci-artifacts/card_retire_spec.md`），作为各道唯一口径来源，含五块：① 背景与**用户裁定原文**；② 逐号映射表（旧号形态 → 语义短语 → 属主出处）；③ 措辞规则（补短语时括号怎么降级、动不动字符串字面量、生成器归属、悬空引用怎么判）；④ 硬约束（BOM 原样补回、行尾由 `.gitattributes` 写死、冻结历史行与原始证据不回改、代码头注释引用的设计约束章节保留、带 BOM 文件名单）；⑤ 自检与交付格式（逐文件命中数、删了哪几行、残留数、门禁复跑结果）。`send_message` 只发路径 + 关键裁定，长中文正文不要整段塞进消息（一次串多条长消息会撑爆 120s，发出 1 条后 abort，剩余未发）。 6. **逐处替换断言命中数**（同第 7 步的 `rep(tag, old, new, want)`），且 `old` 串**从原文取、不凭记忆敲**：本仓中文引号与 ASCII 双引号混用（实测某文档里的「中文引号」其实是 ASCII `"`），凭印象写 `old` 必 `got=0`；断言抛错后先 `git status --porcelain=v1 -- <文件>` 自证文件未被别道改动，再回读该行真身重跑。删行类改动单独记 tag 并打印删了几行、行号与原行长度。多道并行时同一文件常被别道改过：`edit` 报 `file changed since it was read` → 重新 `read` 再改；报 `ReplaceFileW EIO (Win32 1175)` → 先自证文件字节完好（BOM / CRLF / `EF BF BD` 三项）再重试同一笔，不要顺手改内容。 7. **落地位置写死（这一族只有这几条兜）**： - - `docs/编号规范.md` **§4.1.1「已停发的族」表加一行**，三列齐全，第三列直写「⚠ **机器面空白**：中文前缀不进 `scripts/archive/id_gate/check_ids.py` 语料 → 门禁咬不到，只有本表 + §9.3 + 评审三条兜；`id_aliases.json` 刻意不登记（登记了机器也看不见，只多一张没人核的表）」； - - `docs/编号规范.md` **§9.3 逐号换算表**（旧号形态 → 语义短语 → 现行口径出处；本族实测 14 行 = 0、0b、1~12）+ §9 批次段落（裁定原文与逐号结论都落在正文），**写明旧号永久作废、不得重新取走**； + - `docs/编号规范.md` **§4.1.1「已停发的族」表加一行**，三列齐全，第三列直写「⚠ **这一族从来没有机器面**：中文前缀不进任何编号语料（族 pattern 全是拉丁形态），而两道编号门禁已于 2026-10-28 / 29 退役 → 只有本表 + 归档换算表 + 评审三条兜；`id_aliases.json` 刻意不登记（没有机器读者，登记等于多一张没人核的表）」； + - `scripts/archive/id_gate/编号治理历史.md` **§9.3 逐号换算表**（旧号形态 → 语义短语 → 现行口径出处；本族实测 14 行 = 0、0b、1~12）+ 同篇 §9 批次段落（裁定原文与逐号结论都落在归档正文），**写明旧号永久作废、不得重新取走**； - 表内**把形态写成「卡」+ 数字而不复述字面量**：规范本身是门禁语料，复述字面量会把「讲规则的文档」变成自己的引用站点； - **同步叙述**：`AGENTS.md`「文档与图形」的销项条目、`docs/README.md`（例：`数据可信.md = 三项阻塞任务` → 两项）、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零； - **与有识别面族的判别写进同一张表**：能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，**不登记别名**； diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c7f863bc..f6d32632 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -683,7 +683,7 @@ repos: # 14) 编号门禁（2026-10-28 上线只查新增行那一道；2026-10-29 用户裁定**整体退役**，钩子已摘） # 退役后编号形态没有机器面：判据回到 docs/编号规范.md §1 三句自问 + §4.1 族总表 + 评审。 # 脚本移入 scripts/archive/id_gate/check_ids_new.py（手工可跑，--self-test 保留），留档说明 - # → docs/门禁说明/id-check-new.md；两步路线 → docs/编号规范.md §8.5。 + # → docs/门禁说明/id-check-new.md；手工普查与恢复机器面 → docs/编号规范.md §8.5。 # ⚠ 计数口径：本条摘除使 YAML 解析条目 52 → **51**，须与 AGENTS.md 的「共 N 个钩子」、 # docs/门禁说明/README.md §2 标题三数同源同批改（自查命令见该条；别在注释里写数钩子的字面量）。 diff --git a/AGENTS.md b/AGENTS.md index d595e806..7473cbc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,7 +93,7 @@ ## 提交门禁（pre-commit） -- 任一失败即拦截，共 **51 个钩子**（**口径 = YAML 解析后的 hook 条目数**：自查命令与「声明 / 文档 / 实跑」三数同源核对见 `docs/门禁说明/README.md` §2 首条——⚠ 直接 grep 配置里的声明行会多算一条**注释掉的**候选钩子（比口径多 1），不是口径；**配置注释里也别复述那个 grep 字面量**，它会让文本计数再虚高 1（2026-10-27 实测踩过）；加一条钩子就同批改 AGENTS 与门禁索引两处计数。2026-10-25 道E 连加 `bom-guard` / `setview-check` / `uinav-selftest` 三条，2026-10-26 加 `generated-fresh` 一条，2026-10-27 加 `nested-comment` 一条；2026-10-28 加 `id-check-new` 一条并同批退役 `id-check`（口径 52 → 51：编号门禁换牙——新的只查新增行、零语料，旧的八项全库校验连语料一起移入 `scripts/archive/id_gate/`，路线见 `docs/编号规范.md` §8.5）；2026-10-29 加 `skill-size` 一条（51 → 52），同日按用户裁定**退役 `id-check-new`**（52 → **51**：只查新增行的编号门禁整体退场，脚本与白名单一起移入 `scripts/archive/id_gate/`，编号形态此后无机器面，留档 `docs/门禁说明/id-check-new.md`）；**每种门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）→ `docs/门禁说明/README.md` 索引**；通用机制与整体口径 → `docs/代码规范/pre-commit使用说明.md`）：通用 5 + `gitlint` + `cppcheck` / `test-cppcheck` + `no-mojibake` + `coding-standard` + 文档三件套 `doc-links` / `task-table` / `mem-numbers` + `lv-conf-sync`（两份 `lv_conf.h` 特性子集一致）+ `cubemx-survival` + `bom-guard` / `setview-check` / `uinav-selftest`（2026-10-25 道E 那三条：前半句的加钩流水里有它们、逐项枚举里漏了，补上后本行各项相加才等于 51）+ 主机侧单测 **22 根专属钩子**（`-unit-test` 后缀 = 有独立 `files:` 触发面、需要秒级归因的那个子集；2026-10-25 增补 adc-cal / prot-dim / vol-idle-sync / ui-data / meas / run-par 六根）——**这是口径不是缺口**：`test/host/` 实测 44 套带 `run_unit_test.py`，其余 **22 套**（含 `test/host/ui_sink` 与录波三套）没有专属钩子，但每次 CI / `scripts/ci_local.py` 都被 `test-coverage` 总闸全量真跑并守基线回退，**失败照样拦**，只是归因落在总闸输出上；**没有专属钩子 ≠ 没被跑**，22 套台账与补钩子的判据 → `docs/门禁说明/host-unit-tests.md` §6 第 4 条。**Lead 裁定 2026-10-27：不补第 23 根**——读「这套跑没跑」去看总闸输出，别数钩子（原写「23 个 / 含 ui-sink 七个」是双重错：既把 22 说成 23，又宣称 ui-sink 有钩子——配置历史里 `ui-sink-unit-test` 从未存在）+ `test-coverage`（**覆盖率总闸**：跑全部 44 套并守基线回退；缺 mscoverage 组件时按用户裁定 **FAIL**、不 skip，2026-10-24）+ `test-suite-switch` + `registration-check`（双端注册反向校验 + UI 页面描述符表接线，登记簿条目「rs485_task 白名单缺口」）+ `generated-fresh`（**生成器幂等性**：把 `tools/menu_gen/gen_menu.py`、中文字库链、`tools/arch_diagram/gen_*.py` 拷进**系统临时目录**重跑，与工作区**逐字节**必须一致——钩子只读、不写仓库也不 stash 别人在飞的改动；实证 `0f7b5a87` 改了模板文字没重跑生成物，接线前实测另有 5 张 `docs/images/` 配图已漂 → 钉成只减不增基线，**业务生成物零豁免面** → `docs/门禁说明/generated-fresh.md`）+ `nested-comment`（**块注释嵌套**：注释体内再出现 /* 会被 ARMCC 报 9-D，且**按包含者数量刷屏**、只在重编译该 TU 时才暴露；本仓诱因就是「在注释里写作用域/通配路径」，改法是写全目录或用尖括号 ；接线当日实扫 403 个 .c/.h，新发 0、存量 2 处（`test/host/common/` 两份假件头）钉只减不增基线 → `docs/门禁说明/nested-comment.md`）+ `skill-size`（**SKILL.md 不超插件写侧上限 65536 字节**：dsh-mnemon 只在写侧校验、加载侧不查，超限技能照常可读却每次「生成草案」被拒、永久卡在「生成中」；另查 `reference/` 指针悬空与 BOM → `docs/门禁说明/skill-size.md`）+ `mem-budget`（RAM 92% 预算门禁，登记簿条目「缩堆迁 CCM 后半（暂缓）」）+ `font-charset`（UI 字符集差集检查，防缺字白框）+ `ui-golden`（UI 像素回归，菜单 8 状态 + 内容页 66 张黄金参考）+ `layer-deps`（**分层方向**：`Drivers/BSP/**` 不得 include `App/**` 的头；存量 3 条基线只减不增（2026-10-25 记录 reader 注入削掉 UI 记录 3 条边，6→3））+ `bsp-err`（**BSP 错误码与超时命名约定**：公开 API 不得拿 `HAL_StatusTypeDef`/`bool` 当错误通道、`*_TIMEOUT` 宏不得取负值、非 void 须写「返回值：」、**返回错误码的函数不得裸丢弃返回值**（须接住或显式 `(void)`；实测编译器与 cppcheck 都不报这类，只有这条会响）；约定正文 `Drivers/BSP/bsp_err.h`，存量基线只减不增（2026-10-23 首清点 19 条 → 已还 18；`consume-result` 上线又暴露 37 条存量丢弃 → **现 38 条**））。**提交期实跑 48 根**（2026-10-28 用户裁定）：`cppcheck` / `test-cppcheck` / `test-coverage` 三根带 `stages: [manual]`——实测合计 ~165 s = 一次带代码提交耗时的三分之二，提交期只跑快的那些；这三根由**远端 CI** 强制（`.gitea/workflows/ci.yml` 的「手动阶段门禁」步，逐根 `--hook-stage manual`）与 `scripts/ci_local.py` 的 manual 段，本地手工复跑 `python -m pre_commit run --all-files --hook-stage manual `（一次只能一个 id） +- 任一失败即拦截，共 **51 个钩子**（**口径 = YAML 解析后的 hook 条目数**：自查命令与「声明 / 文档 / 实跑」三数同源核对见 `docs/门禁说明/README.md` §2 首条——⚠ 直接 grep 配置里的声明行会多算一条**注释掉的**候选钩子（比口径多 1），不是口径；**配置注释里也别复述那个 grep 字面量**，它会让文本计数再虚高 1（2026-10-27 实测踩过）；加一条钩子就同批改 AGENTS 与门禁索引两处计数。2026-10-25 道E 连加 `bom-guard` / `setview-check` / `uinav-selftest` 三条，2026-10-26 加 `generated-fresh` 一条，2026-10-27 加 `nested-comment` 一条；2026-10-28 加 `id-check-new` 一条并同批退役 `id-check`（口径 52 → 51：编号门禁换牙——新的只查新增行、零语料，旧的八项全库校验连语料一起移入 `scripts/archive/id_gate/`，手工普查与恢复机器面见 `docs/编号规范.md` §8.5）；2026-10-29 加 `skill-size` 一条（51 → 52），同日按用户裁定**退役 `id-check-new`**（52 → **51**：只查新增行的编号门禁整体退场，脚本与白名单一起移入 `scripts/archive/id_gate/`，编号形态此后无机器面，留档 `docs/门禁说明/id-check-new.md`）；**每种门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）→ `docs/门禁说明/README.md` 索引**；通用机制与整体口径 → `docs/代码规范/pre-commit使用说明.md`）：通用 5 + `gitlint` + `cppcheck` / `test-cppcheck` + `no-mojibake` + `coding-standard` + 文档三件套 `doc-links` / `task-table` / `mem-numbers` + `lv-conf-sync`（两份 `lv_conf.h` 特性子集一致）+ `cubemx-survival` + `bom-guard` / `setview-check` / `uinav-selftest`（2026-10-25 道E 那三条：前半句的加钩流水里有它们、逐项枚举里漏了，补上后本行各项相加才等于 51）+ 主机侧单测 **22 根专属钩子**（`-unit-test` 后缀 = 有独立 `files:` 触发面、需要秒级归因的那个子集；2026-10-25 增补 adc-cal / prot-dim / vol-idle-sync / ui-data / meas / run-par 六根）——**这是口径不是缺口**：`test/host/` 实测 44 套带 `run_unit_test.py`，其余 **22 套**（含 `test/host/ui_sink` 与录波三套）没有专属钩子，但每次 CI / `scripts/ci_local.py` 都被 `test-coverage` 总闸全量真跑并守基线回退，**失败照样拦**，只是归因落在总闸输出上；**没有专属钩子 ≠ 没被跑**，22 套台账与补钩子的判据 → `docs/门禁说明/host-unit-tests.md` §6 第 4 条。**Lead 裁定 2026-10-27：不补第 23 根**——读「这套跑没跑」去看总闸输出，别数钩子（原写「23 个 / 含 ui-sink 七个」是双重错：既把 22 说成 23，又宣称 ui-sink 有钩子——配置历史里 `ui-sink-unit-test` 从未存在）+ `test-coverage`（**覆盖率总闸**：跑全部 44 套并守基线回退；缺 mscoverage 组件时按用户裁定 **FAIL**、不 skip，2026-10-24）+ `test-suite-switch` + `registration-check`（双端注册反向校验 + UI 页面描述符表接线，登记簿条目「rs485_task 白名单缺口」）+ `generated-fresh`（**生成器幂等性**：把 `tools/menu_gen/gen_menu.py`、中文字库链、`tools/arch_diagram/gen_*.py` 拷进**系统临时目录**重跑，与工作区**逐字节**必须一致——钩子只读、不写仓库也不 stash 别人在飞的改动；实证 `0f7b5a87` 改了模板文字没重跑生成物，接线前实测另有 5 张 `docs/images/` 配图已漂 → 钉成只减不增基线，**业务生成物零豁免面** → `docs/门禁说明/generated-fresh.md`）+ `nested-comment`（**块注释嵌套**：注释体内再出现 /* 会被 ARMCC 报 9-D，且**按包含者数量刷屏**、只在重编译该 TU 时才暴露；本仓诱因就是「在注释里写作用域/通配路径」，改法是写全目录或用尖括号 ；接线当日实扫 403 个 .c/.h，新发 0、存量 2 处（`test/host/common/` 两份假件头）钉只减不增基线 → `docs/门禁说明/nested-comment.md`）+ `skill-size`（**SKILL.md 不超插件写侧上限 65536 字节**：dsh-mnemon 只在写侧校验、加载侧不查，超限技能照常可读却每次「生成草案」被拒、永久卡在「生成中」；另查 `reference/` 指针悬空与 BOM → `docs/门禁说明/skill-size.md`）+ `mem-budget`（RAM 92% 预算门禁，登记簿条目「缩堆迁 CCM 后半（暂缓）」）+ `font-charset`（UI 字符集差集检查，防缺字白框）+ `ui-golden`（UI 像素回归，菜单 8 状态 + 内容页 66 张黄金参考）+ `layer-deps`（**分层方向**：`Drivers/BSP/**` 不得 include `App/**` 的头；存量 3 条基线只减不增（2026-10-25 记录 reader 注入削掉 UI 记录 3 条边，6→3））+ `bsp-err`（**BSP 错误码与超时命名约定**：公开 API 不得拿 `HAL_StatusTypeDef`/`bool` 当错误通道、`*_TIMEOUT` 宏不得取负值、非 void 须写「返回值：」、**返回错误码的函数不得裸丢弃返回值**（须接住或显式 `(void)`；实测编译器与 cppcheck 都不报这类，只有这条会响）；约定正文 `Drivers/BSP/bsp_err.h`，存量基线只减不增（2026-10-23 首清点 19 条 → 已还 18；`consume-result` 上线又暴露 37 条存量丢弃 → **现 38 条**））。**提交期实跑 48 根**（2026-10-28 用户裁定）：`cppcheck` / `test-cppcheck` / `test-coverage` 三根带 `stages: [manual]`——实测合计 ~165 s = 一次带代码提交耗时的三分之二，提交期只跑快的那些；这三根由**远端 CI** 强制（`.gitea/workflows/ci.yml` 的「手动阶段门禁」步，逐根 `--hook-stage manual`）与 `scripts/ci_local.py` 的 manual 段，本地手工复跑 `python -m pre_commit run --all-files --hook-stage manual `（一次只能一个 id） - **范围 = 项目代码**：第三方（`Lib/`、`Middlewares/`、CMSIS、HAL、`lftpd`、`dhara`、`MDK-ARM`）排除；`cppcheck`/`coding-standard` 另排除 `test/`，规范检查再排除 CubeMX 生成的 `Src/`/`Inc/`。**`simulator/` 已纳入全部钩子**（2026-10-11）——生成物只靠 `.gitignore` 挡，**不在 `exclude` 里写目录名**（教训见 `docs/代码规范/pre-commit使用说明.md` §5.5） - ⚠ **pre-commit 4.x 已移除 `always: true`**（实测对 `local` 钩子只告警 `Unexpected key(s)` 并跳过）→ 想"总是跑"的钩子**必须让 `files:` 覆盖到所有会触发它的文件**，没有兜底开关 - **改写型钩子（`trailing-whitespace` + `end-of-file-fixer`）豁免 CubeMX/Keil 生成文件**（配置里 YAML 锚点 `&cubemx-generated`）；⚠ **只读检查不受影响**：`cppcheck` / 乱码 / `cubemx-survival` / `task-table` / `mem-numbers` 仍覆盖 `Src/`、`Inc/` diff --git a/docs/编号规范.md b/docs/编号规范.md index cd10264a..60791783 100644 --- a/docs/编号规范.md +++ b/docs/编号规范.md @@ -12,15 +12,15 @@ > **本文就是唯一事实源**：两道编号门禁已分别于 2026-10-28（全库八项校验）与 2026-10-29（只查新增行） > 退役，脚本、两张前缀白名单与族语料都在 `scripts/archive/id_gate/`，**不再进提交门禁**。 > 形态判据只剩本文 §1 的三句自问 + §4.1 族总表 + 人工评审；留档 `docs/门禁说明/id-check-new.md` -> 与 `docs/门禁说明/id-check.md`，路线见 §8.5。归档脚本随时可手工普查形态（`--range A..B`）。 +> 与 `docs/门禁说明/id-check.md`，手工普查命令与恢复机器面的成本见 §8.5。归档脚本随时能重扫一批改动的形态（`--range A..B`）。 --- -> **本文范围**：这里只留**现在还生效**的口径。跳号的节（`编号治理历史.md` §2 八条原则 / `编号治理历史.md` §4.2 / `编号治理历史.md` §4.5 / `编号治理历史.md` §6 模块码表 / -> `编号治理历史.md` §7 改号与迁移 / `编号治理历史.md` §8.1 基线 / `编号治理历史.md` §8.3 批次 / `编号治理历史.md` §8.4 台账 / `编号治理历史.md` §9 存量清点与换算表）是编号治理的**过程记录**， -> 2026-10-28 已整体移入 `scripts/archive/id_gate/编号治理历史.md`——要查历史判据、批次流水、 -> 「数据可信」任务卡号换算表，去那里；**改现在的做法只看本文**。 -> 节号沿用旧编号，故意不重排：外部文档与脚本引的是 `§4.1` / `§8.5` 这些号，重排等于制造一批假链接。 +> **本文范围**：这里只留**现在还生效**的口径。编号治理的**过程记录**（八条设计原则、基线数字、批次流水、 +> 存量清点与逐号换算表）2026-10-28 已整体移入 `scripts/archive/id_gate/编号治理历史.md`，下文简称 +> **`编号治理历史.md`**；它的节号沿用旧编号、故意不重排（外部文档与脚本引的是 `§4.1` / `§8.5` 这类号， +> 重排等于制造一批假链接）。要查历史判据、批次流水、「数据可信」任务卡号换算表，去那篇； +> **改现在的做法只看本文**。 ## 1. 决定要不要发号之前，先问三句 @@ -78,43 +78,43 @@ | `FR-*` | 需求 | `docs/产品需求/产品需求设计文档.md` §5 | 需求↔测试追溯 | | `CODE-RULE-` | 代码规范条款 | `scripts/check_coding_standard.py` | 门禁按条款号报错并统计存量 | | `MENU-STATE-` | UI 状态机键 | `simulator/tests/check_menu_rows.py` | 像素回归脚本按它取状态行 | -| `P-` | **本文的设计原则** | 本文 `编号治理历史.md` §2 | 就是本文自己的条目 | +| `P-` | 编号治理的设计原则 | `scripts/archive/id_gate/编号治理历史.md` §2（2026-10-28 随沿革归档，本文不再列条目） | **只读存量**：原则已归档，新写条目按 §3.3 写语义短语，不再配 P 号 | > ⚠ **「批次三不做了」只有一层意思：不去清这个族，同时把它的发号口关死。** 它**不是**「TC 族维持原状、 > 新用例照旧配号」——维持原状的是**存量号**，关掉的是**发号口**。三条对照，防止往任何一边读过头： > > - ❌「不做 = 维持原状 = 还能发」——**错**。新用例一律用**语义化测试函数名 + 文档用例表的行名**（§3.3）， > 不再配 TC 号；指认**既有**用例仍可引用现存号（旧号只读，不是许可新配）。 -> - ❌「停发 = 这族要废了，顺手清掉、把号腾出来复用」——**也错**。现存号与它在 `scripts/archive/id_gate/id_registry.json` -> 里的登记，是 `check_test_traceability.py` 与 44 套 `run_unit_test.py` **按字面量读的追溯把手**， -> 清它等于换机制（`编号治理历史.md` §9.1）；号不回收、不复用是 §1 的硬规矩。 -> - ❌「registry 里 TC 族还带着活游标，所以门禁允许我发」——**不成立：这条缺口已于 2026-10-27 同日关掉**。 -> 37 个 TC 类族现在**全部** `frozen: true`，其中 **34 个 `TC-HOST-*` 子族的 `cursor` 冻结在裁定日该套件存量 -> 最高号**（5 个游标低于存量的已抬到水位：`TC-PROTELEM-013→015`、`TC-SYSLOG-108→137`、`TC-ADCHEALTH-011→023`、 -> `TC-ADCCAL-017→023`、`TC-I104SRV-041→053`；**游标必须是字符串形态**，整型比较会静默不生效）→ 在套件 -> 登记处写一个比游标更高的 TC 号就是 §8 第 5 项「冻结族越游标」**错误级**，而 `id_known_backlog.json` 台账 -> 0 条指纹 → 增量拦截等于全量拦提交。探针实测（`check_ids` 的 Checker `_check_frozen`）：在 `TC-PROTSET-` -> 段存量最高号之上再加一号 → 命中 1 条校验 5；写存量最高号本身 → 零误伤。 -> **还剩一处空白，别把这条机械化读成无死角**：主族 `TC`（没有专属子族的模块码，如 `TC-ADCIN-*`）的 `cursor` -> 仍为 `null`——一个游标表达不了每个模块码的水位，写全族最高号反而放行低号，所以按空白登记（探针实测： -> 给无专属子族的模块码（如 `TC-ADCIN-` 段）写一个新号，门禁不响）。这一面由三条兜：① §8 校验 3——新号没进属主登记处 = 悬空引用（错误级）； -> ② `编号治理历史.md` §9.1 末段的**冻结水位**（只减不增，涨了就要问「这号是谁在停发之后发的」）；③ 评审。**所以给这些模块 -> 补号，即使在文档表格里一并补了定义行，一样违反本裁定。** 要把这面也钉死（按模块码克隆子族，或给族级加 -> 字面量上限）与「真要清退」同属追溯机制改造，按 `编号治理历史.md` §7.3 单独开卡，别夹在本批里顺手做。 -> - **唯一的重启入口**：先由用户裁定 → 再回到本节把族放回上面那 7 行、并指出按它做字面量匹配的脚本 → +> - ❌「停发 = 这族要废了，顺手清掉、把号腾出来复用」——**也错**。现存号是用例输出行名与追溯脚本 +> `scripts/check_test_traceability.py` 认的把手（该脚本 2026-10-29 实测**只手工跑**：不在任何钩子、 +> `scripts/ci_local.py` 与远端 CI 里），清它等于换机制（`编号治理历史.md` §9.1）；号不回收、不复用是 §1 的硬规矩。 +> - ❌「`id_registry.json` 里 TC 族带着游标，所以那边允许我发」——**不成立**。37 个 TC 类族 2026-10-27 全部 +> 登记 `frozen: true`，34 个 `TC-HOST-*` 子族的游标钉在当日各套件存量最高号（5 个低于存量的抬到水位： +> `TC-PROTELEM-013→015`、`TC-SYSLOG-108→137`、`TC-ADCHEALTH-011→023`、`TC-ADCCAL-017→023`、 +> `TC-I104SRV-041→053`；**游标必须是字符串形态**，整型比较会静默不生效）。那是那次裁定的**登记留痕**： +> 两道编号门禁退役后没有任何东西再读这份登记，写一个比游标更高的 TC 号不会再有机器反应，拦它的只有 +> 本节与评审——**别把"不报错"读成"允许发号"**。 +> - **已知空白面（当年登记时就写着，不是新发现）**：主族 `TC`（没有专属子族的模块码，如 `TC-ADCIN-` 段） +> 的 `cursor` 为 `null`——一个游标表达不了每个模块码的水位，写全族最高号反而放行低号。机器面在的时候它 +> 就不响，现在连那层壳都没有：**给这类模块码补号，即使在文档表格里一并补了定义行，一样违反本裁定**， +> 评审要专门盯这一面。要把死角钉死（按模块码克隆子族，或给族级加字面量上限）与「真要清退」同属追溯 +> 机制改造，按 `编号治理历史.md` §7.3 单独开卡，别夹在别的批里顺手做。 +> - **唯一的重启入口**：先由用户裁定 → 再回到本节把族放回上面那 5 行、并指出按它做字面量匹配的脚本 → > 才谈得上发号。顺序倒过来就是 `编号治理历史.md` §1.2 那四类事故的由来。 -**已停发、存量待清**（一律**不得再新增引用**；下表除 `TC-*` 外，登记未删只是为了让历史行不报「未登记前缀」， -清点见 `编号治理历史.md` §9.1。`TC-*` 是这一栏的**特例**：登记与现存号都要留着，它是机器把手而不是待清对象，见 `编号治理历史.md` §9.1 批次三）： +**已停发、存量待清**（一律**不得再新增引用**；下表除 `TC-*` 外，`id_registry.json` 里剩的登记只是归档普查的 +语料残留，**不再当"登记处"读**——那份登记自 2026-10-28 起没有机器读者。清点见 `编号治理历史.md` §9.1。 +`TC-*` 是这一栏的**特例**：登记与现存号都要留着，现存号仍被追溯脚本按字面量读，不是待清对象 +（见 `编号治理历史.md` §9.1 批次三）： | 族 | 状态 | 依据 | |---|---|---| -| `TC-*` | **保留现存号、即日停发（机器已冻结）**：34 个 `TC-HOST-*` 子族 `frozen: true`、游标钉在 2026-10-27 存量水位，越游标即 §8 校验 5 错误级；现存号只减不增，新用例改用语义化测试函数名 + 文档表格行名（主族 `TC` 的空白面见上方框） | 用户裁定 2026-10-27「批次三，不坐」；本族是 §4.1 判据唯一真被脚本按字面量读的族，清它等于换追溯机制，详见 `编号治理历史.md` §9.1 批次三 | +| `TC-*` | **保留现存号、即日停发**：`id_registry.json` 里 37 个 TC 类族登记 `frozen: true`、34 个 `TC-HOST-*` 子族游标钉在 2026-10-27 存量水位（**该登记 2026-10-29 起无机器读者，只是裁定留痕**）；现存号只减不增，新用例改用语义化测试函数名 + 文档表格行名（主族 `TC` 的空白面见上方框） | 用户裁定 2026-10-27「批次三，不坐」；本族是 §4.1 判据唯一真被脚本按字面量读的族，清它等于换追溯机制，详见 `编号治理历史.md` §9.1 批次三 | | 族 | 形态 | 存量 | 为什么该清 | |---|---|---|---| -| `L-` | 保护功能号 | **批次二已整族转功能名，即日停发**：活引用 0，只剩一处**原始串口日志**（冻结证据、永久保留）与本文/技能文档的形态举例；属主文档表首格写功能名，不再配号 | 用户 2026-10-27 定调「语义标识是最好的」+ 本轮指令「把能清的族清掉一批」；探针（Checker _check_dangling）：写一个新号（字母 L + 段号 + 连字符 + 两位数、从未定义过的形态）→ §8 校验 3 悬空引用**错误级** → 发号口已机器关闭。**不冻结数值游标**：L1/L2/…各段最高号不同，单一数字游标反而放行低号 | -| `F--` | 网络设计条目 | **批次一已转「`编号治理历史.md` §7 条目名」，即日停发**：代码与测试侧 0 处；属主文档 `编号治理历史.md` §7 编号列 13 条仅作历史对照（定义行不算引用） | 同上；探针：写一个新号（F 前缀 + 模块码 + 从未出现过的序号）→ 校验 3 **错误级**；引用旧号命中小写别名表 retired-to-phrase = **只读**，不构成发号许可 | +| `L-` | 保护功能号 | **批次二已整族转功能名，即日停发**：活引用 0，只剩一处**原始串口日志**（冻结证据、永久保留）与本文/技能文档的形态举例；属主文档表首格写功能名，不再配号 | 用户 2026-10-27 定调「语义标识是最好的」+ 本轮指令「把能清的族清掉一批」；发号口此前由"悬空引用"校验关着，**2026-10-29 起只由本表与评审关**。**数值游标不冻结**：L1/L2/…各段最高号不同，单一数字游标反而放行低号 | +| `F--` | 网络设计条目 | **批次一已转「`编号治理历史.md` §7 条目名」，即日停发**：代码与测试侧 0 处；属主文档 `编号治理历史.md` §7 编号列 13 条仅作历史对照（定义行不算引用） | 同上；引用旧号命中别名表 `retired-to-phrase` = **只读**，不构成发号许可 | | `N-*` | 登记簿 `N-` | 4 处 / 3 个字面量 | 登记簿已于 2026-10-26 全面改语义短语，残留的是漏网的旧引用 | | `TM-*` | 阶段/里程碑 `TM--` | 1 处 | 阶段号本就属 §3.3 明令不许写号的那类 | | `T-TEST` | 台架阶段 **裸形**（字母 T 紧跟一位数字） | 活引用 0（批次一清零；余下是本文自述与技能文档的形态举例） | 裸形最危险（同字母多义），且改「台架阶段一」即可 | @@ -130,36 +130,41 @@ |---|---|---| | 登记簿 `N-x` / `S-x` / `T-x`、专项 `A-x`、已删报告的 UI 簇 `U1~U5`（2026-10-26 方案 B） | 语义短语——**登记簿表首格本身就是短语**，如「双转换器无共同采样触发」「CI 远端闭环未验证」 | `scripts/archive/id_gate/id_aliases.json` 标 `retired-to-phrase` | | 网络设计条目 `F-NET/F-DRV/F-MS-`（12 个，2026-10-27 批次一） | 「`编号治理历史.md` §7 + 条目名」短语，如 `（`编号治理历史.md` §7「全局读即清搁浅事件」）`；条目名的权威清单 = `docs/网络/网络自愈架构设计.md` `编号治理历史.md` §7「条目名」列；那个 DRV 段孤儿号按本节末句**删号留事实**、未补定义 | `scripts/archive/id_gate/id_aliases.json` 标 `retired-to-phrase`（13 条）＋属主文档 `编号治理历史.md` §7 编号列仅作历史对照 | -| 「数据可信」任务卡号（中文前缀「卡」+ 数字，形态见 `编号治理历史.md` §9.3；2026-10-27 批次五） | §5 表的**标识列直接写任务名**（「端子/子板变比确认」「两点标定与精度验收」），代码注释与文档写语义短语（「标定折算落地」「未标定闭锁」「遥测快照发布」…）；**逐号换算表见本文 `编号治理历史.md` §9.3** | ⚠ **机器面空白**：中文前缀不进 `scripts/archive/id_gate/check_ids.py` 语料（族 pattern 全是拉丁形态）→ 门禁咬不到，今天只有本表 + `编号治理历史.md` §9.3 + 评审三条兜；`id_aliases.json` 刻意不登记（登记了机器也看不见，只多一张没人核的表） | +| 「数据可信」任务卡号（中文前缀「卡」+ 数字，形态见 `编号治理历史.md` §9.3；2026-10-27 批次五） | §5 表的**标识列直接写任务名**（「端子/子板变比确认」「两点标定与精度验收」），代码注释与文档写语义短语（「标定折算落地」「未标定闭锁」「遥测快照发布」…）；**逐号换算表见本文 `编号治理历史.md` §9.3** | ⚠ **这一族从来没有机器面**：两道门禁的语料族 pattern 全是拉丁形态，中文前缀本就不在其中，何况两道都已退役 → 只有本表 + `编号治理历史.md` §9.3 + 评审三条兜；`id_aliases.json` 刻意不登记（没有机器读者，登记等于多一张没人核的表） | | 测试验证层级号（`L0`、`L0.5`、`L1~L3` 这一族，**注意与 UI 设计令牌层 L0、硬件位号 L1~L3、采集链旧层名等同形族无关**；2026-10-28 批次六） | 文档与 CI 步骤名写语义名（静态门禁 / 主机侧纯逻辑单测 / 板端测试套件 / 主机侧回归 / 人工目检）；ASCII 短码（static / preflight / commitmsg / size / host-unit / coverage）**只进**日志标签、命令行旗标、CI job id、日志文件名 | ⚠ **同形族警示**：逐号换算表与判族表见 `scripts/archive/id_gate/编号治理历史.md` §10 与 §10.1（撞族六个，动手前先判族）；本族虽是拉丁形态但**门禁咬不到**——两道编号门禁已退役（全库校验 2026-10-28、新增行检查 2026-10-29），停发只靠本表 + 归档换算表 + 评审 | | `E-xx` 审计发现、`P0-x`~`P3-x` 审计条目、报告六族 `D/R/F/N/U/S`、复审残号 `S1~S14`/`A-x`/`B1~B10`/`T-x`、模拟器差距 `H-x`/`L-x`、`TM-*` 阶段号、`DP-*`、`gen`/`round`/会话临时号 | 写条目本身（"原子快照取数"、"队头阻塞"、"台架日志代次 288"、"第 3 轮台架"） | 别名表标 `void`；**部分死号故意不进别名表**，好让门禁继续咬残留引用 | | 规范曾规划却从未启用的前缀族（`DEF`/`WI`/`DR`/`OQ`/`RSK`/`GAP`/`SC`/`GEN`/`MS`/`UL`/`LAT`/`CS` 等） | 同上，写事实 | 无定义，本就不该存在 | -> 想知道某个号还活着吗：跑 `scripts/archive/id_gate/check_ids.py --top 0`，或直接查 `id_aliases.json`——命中 `void` / -> `retired-to-phrase` 就是死号。**看到查不到的号，正确动作是删号留事实，不是补一个定义。** +> 想知道某个号还活着吗：查 `id_aliases.json`（命中 `void` / `retired-to-phrase` 就是死号），或手工跑 +> `scripts/archive/id_gate/check_ids.py --top 0`——**报告制，不影响任何退出码**。**看到查不到的号， +> 正确动作是删号留事实，不是补一个定义。** ### 4.3 冻结前缀（历史快照，正文不回改） -族还在注册表里、但属主登记处已删的：**只为让冻结历史行不报"未登记前缀"而保留登记**，游标一律冻结， -不得新增、不得复用。 +族还在 `scripts/archive/id_gate/id_registry.json` 里、属主登记处已删的那批：登记留着只为让归档普查 +不报"未登记前缀"，游标一律冻结，**不得新增、不得复用**。⚠ 2026-10-29 起这份登记**没有机器读者**， +它是档案不是闸门——别指望写一个冻结族的号会有人来拦。 -### 4.4 这些**不是**编号——别顺手清，也别当门禁漏洞 +### 4.4 这些**不是**编号——别顺手清 元器件位号 `U1`/`C12`/`R3`/`L5`/`D7`（硬件语料按目录整体排除）、数学与协议记号（`N-1`、测频的正序与 负序分量 `S1`/`S2`、`SHA-256`、`RS-485`、`ADC1_IN14`、手册页码）、活表代号 `E0~E19`（网络自愈 §5.2， **无连字符**，与死号 `E-nn` 只差一个连字符）、Socket 状态组合 `U1~U15`（网络自愈 §1.1）、档位词 `P0~P3`。 判据只有一条：**带连字符、且能在属主登记表查到定义**才叫编号；查不到的就是普通文本，不是「漏登记的号」。 -> 2026-10-27 补两条实测口径：① **元器件位号目录整体排除**——`tools/netlist_semantics/` 是硬件知识库 -> （字母 T 紧跟数字在那里是网络变压器位号），已进 `id_registry.json` 的 `excluded_paths`，与 `docs/硬件平台/` 同口径； -> ② **唯一已知误判**：`docs/算法/傅氏算法详解.md` 里的数学记号 `N-1`（「一个周波 N 个点」的求和上界）会被 -> `N-x` 族命中，属可判定引用、不影响两根护栏，**不清**——清了反而破坏公式。 +> 两条口径来自当年的语料审计，今天判"是不是编号"照它想：① **元器件位号整目录排除**—— +> `tools/netlist_semantics/` 是硬件知识库（字母 T 紧跟数字在那里是网络变压器位号），与 `docs/硬件平台/` +> 同口径（归档普查把它写在 `id_registry.json` 的 `excluded_paths`）；② **唯一已知误判**： +> `docs/算法/傅氏算法详解.md` 里的数学记号 `N-1`（「一个周波 N 个点」的求和上界）形似 `N-x` 族， +> 属可判定的普通文本，**不清**——清了反而破坏公式。 ## 5. 分配、引用、销项 ### 5.1 新增编号 -先过 §1 三问。确实要发号：① 在 `id_registry.json` 确认族与游标 ② 在属主登记处写定义行 ③ 才允许在 -别处引用。**没有属主登记处的号不许存在**——门禁的校验 3 就是照这句实现的。 -**族不在 §4.1 那 5 行之内的，第 ① 步就该走不通**（`TC-*` 已停发：即使在 registry 里查得到它、游标还是活的， -也不构成"能发号"的理由，见 §4.1 末框）。 +先过 §1 三问。确实要发号：① 族必须落在 §4.1 那 5 行之内（**表外一律不发**）② 在属主登记处写定义行 +③ 才允许在别处引用。**没有属主登记处的号不许存在**——这句原先由八项校验的"悬空引用"实现，该校验 +2026-10-28 退役，现在它是纸面规矩，只有评审在执行。 +`scripts/archive/id_gate/id_registry.json` 的族与游标登记**只在恢复机器面时才动**（§8.5）：没有脚本读它， +写进去也拦不住任何人——**别把"registry 里查得到"当成发号许可**（`TC-*` 正是这一类：停发与登记并存， +许可只来自 §4.1 那张表）。 ### 5.3 代码注释 **优先写短语**（`FTP 鉴权`、`监听生命周期模块化`），别写字母号；确需引用活号时必须带属主文档名。 @@ -168,7 +173,13 @@ ### 5.5 销项与归档 删登记行 + **同步清掉全仓引用**（清引用是销项的一部分，不是"以后再说"）+ 别名表标 `void`。 -冻结的历史（变更记录行、`[示例]` / `[计划]` 行）不回改，门禁对它们已豁免。**现状补充**：2026-10-28 起新文档一律不再设「变更记录」节（`docs/文档规范.md` §5.1），所以这条冻结规则只对**仍保留变更记录表的 5 篇**（同一份清单）与 `scripts/archive/id_gate/` 下的归档文档生效——不是「以后还能往变更记录里写」的理由。**唯一例外**（用户裁定 2026-10-28）：这类行里**已停发 / 作废族的示例编号**可改成形态描述（写成「字母紧跟数字」这类说法）——改的是示例的写法，不是历史事实；**保留现存号**族的游标数字与硬件位号举例不在例外内，形态化等于毁证据。 +冻结的历史（`[示例]` / `[计划]` 行、仍保留变更记录表的文档）不回改。**2026-10-28 起新文档一律不再设 +「变更记录」节**（`docs/文档规范.md` §5.1——例外清单以那一节为准，本文不复制份数，抄一份就会漂一次）。 +所以"冻结历史行"只对清单里的文档与 `scripts/archive/id_gate/` 下的归档文档生效，不是「以后还能往变更 +记录里写」的理由。**唯一例外**（用户裁定 2026-10-28）：这类行里**已停发 / 作废族的示例编号**可改成形态 +描述（写成「字母紧跟数字」这类说法）——改的是示例的写法，不是历史事实；**保留现存号**族的游标数字与 +硬件位号举例不在例外内，形态化等于毁证据。原先那句「门禁对它们已豁免」随门禁一起失效： +现在没有任何门禁会去看这些行。 ### 5.7 语义标识的登记与别名 短语就是登记处的行名，不需要别名表；**只有"号转短语"**时才在别名表留一条 `retired-to-phrase`， @@ -176,33 +187,31 @@ --- -## 8. 门禁（2026-10-29 起：一道也没有） +## 8. 机器面：2026-10-29 起一道也没有 **现行没有编号门禁**：2026-10-29 用户裁定把最后那道只查新增行的 `id-check-new` 也摘了（钩子口径 52 → 51，脚本与白名单移入 `scripts/archive/id_gate/check_ids_new.py`，留档 `docs/门禁说明/id-check-new.md`， 理由与手工跑法都在那篇）。判据回到本文 §1 三句自问、§4.1 族总表与人工评审。 -本节以下（`编号治理历史.md` §8.1~`编号治理历史.md` §8.4）是**已退役**的全库语料审计（`id-check`，八项校验）的留档： -脚本与两份语料已整体移入 `scripts/archive/id_gate/`，不再进提交门禁， -只在你手工复查「存量编号现状」时才跑。退役理由与判据替换见 §8.5； -八项校验一句话版（历史口径）：① 未登记前缀 ② 形态不合规 ③ 悬空引用 ④ 重复定义 -⑤ 冻结族越游标 ⑥ 编号未紧邻文档名 ⑦ 孤儿条目（告警）⑧ 可判定比例 + 两根护栏。 +全库八项校验（未登记前缀 / 形态不合规 / 悬空引用 / 重复定义 / 冻结族越游标 / 未紧邻文档名 / 孤儿告警 / +可判定比例 + 两根护栏）2026-10-28 退役：它查过什么、为什么退、当年清点数字 → `docs/门禁说明/id-check.md` +与 `scripts/archive/id_gate/编号治理历史.md`。**本文不抄第二份口径**——那份口径已经数错过一次了。 -### 8.5 门禁退役路线（2026-10-28 裁定，2026-10-29 收口） +### 8.5 手工普查与恢复机器面 -目标不是"关掉检查"，而是把成本从**养 99 族语料**降到**禁止新编号**，最后一步是承认连这点机器面 -也不划算（2026-10-29 用户裁定）。四步，每步可独立回滚： +**没有门禁不等于没有工具**，两份脚本都还在，随时能跑（它们退成了工具，不是消失了）： -| 步 | 内容 | 状态 | -|---|---|---| -| ① | 两根护栏（比例基线 / 不可判定绝对数上限）**转报告制**：照打数字，不再影响退出码 | **已完成 2026-10-28** | -| ② | 用 **diff 级新号拦截**替换语料审计：只看新增行里命中"字母+数字"形态、且不在白名单里的字面量，FAIL 并提示改成语义短语；白名单 = 前缀级两张表（活族 11 + 器件/协议/点号约 90），基本不增长 | **已完成 2026-10-28**（脚本 + 钩子 `id-check-new`，与 `id-check` **双跑观察期**；脚本今在 `scripts/archive/id_gate/check_ids_new.py`，详解 `docs/门禁说明/id-check-new.md`） | -| ③ | 退役语料：99 族语料＋脚本整体移入 `scripts/archive/id_gate/`（保留可复现性，不再进提交门禁）；`check_ids.py` 降为手工报告工具，钩子摘除（口径 52 → 51） | **已完成 2026-10-28**（用户裁定跳过观察期直接做；当时 `id-check-new` 是唯一现役编号门禁） | -| ④ | 退役最后那道新增行拦截：钩子摘除（口径 52 → 51）、脚本与两张白名单移入 `scripts/archive/id_gate/`；此后**编号形态无机器面** | **已完成 2026-10-29**（用户裁定；留档 `docs/门禁说明/id-check-new.md`，含拦下过什么与为什么退） | +```text +scripts/archive/id_gate/check_ids_new.py --range A..B # 只看一段提交的新增行里有没有自造形态 +scripts/archive/id_gate/check_ids.py --top 0 # 全库存量普查（报告制，不影响退出码） +``` -**④ 之后没有任何机械牙**：别把"门禁不响了"读成"可以随便写号"——自造前缀在评审里照样扎眼， -而 `scripts/archive/id_gate/check_ids_new.py --range A..B` 随时能把一批改动重扫一遍（它退成了工具， -不是消失了）。要恢复机器面也便宜：把脚本放回 `scripts/` 并重新挂一条钩子（口径 +1，同批改三处计数）。 +- **恢复机器面的成本**：把脚本放回 `scripts/`、在 `.pre-commit-config.yaml` 重挂一条钩子、口径 +1， + 并同批改 `AGENTS.md` 与 `docs/门禁说明/README.md` 两处计数——三处一起做，只挂钩子会在别人提交里露馅。 +- **为什么走到"一道也没有"**：2026-10-28 退全库八项校验（99 族语料养不起，成本落在每次碰文档的提交上）， + 2026-10-29 退最后那道新增行拦截（用户裁定：它咬形态不咬语义，白名单本身成了维护面）。两道各自拦下过 + 什么、退役当日那次误拦（录波段文件名 `WAVE00.BIN`）→ `docs/门禁说明/id-check-new.md` 与 + `docs/门禁说明/id-check.md`；四步流水与当时的探针数字 → `scripts/archive/id_gate/编号治理历史.md`。 --- @@ -213,8 +222,9 @@ - 想给文档内步骤或测试阶段发号 → 不许，写「步骤 3」「阶段 7」（§3.3）。 - 想新增前缀族 → 先回答"哪个脚本要按字面量匹配它"（§4.1）；答不出就别建。 - 要改号 → `scripts/rename_ids.py` + `编号治理历史.md` §7.3 五步。 -- 编号形态拿不准 → 本文 §1 三句自问；两道门禁的历史与手工跑法 → `docs/门禁说明/id-check.md`、 - `docs/门禁说明/id-check-new.md`。 +- 编号形态拿不准 → 本文 §1 三句自问 + §4.1 那张表；**没有任何机器会替你兜**。两道门禁的历史与退役理由 → + `docs/门禁说明/id-check.md`、`docs/门禁说明/id-check-new.md`。 +- 想让机器帮你扫一批改动，或要恢复机器面 → §8.5。 ---