refactor(编号): B 层口径落地——主机侧单测认代码为属主登记处

为什么不是"补 7 篇文档"
- 实测这些号在代码目录外**零消费者**(NANDPORT 47 / PROTELEM 13 / PROTSET 11 /
  FREQ 11 / FTPAUTH 10 / SHA256 8 / SOE 7 / ADCHEALTH 11 / IEC104 23,共 141 号),
  唯一"外部引用"是 scripts/id_aliases.json 自己 → 逐号写文档等于造一份没人读、
  还要跟着代码同步改的复述层(违反"同一事实只在一处详述")

判据与注册表改动
- 新增 9 族 TC-HOST-<模块码>:class 仍为 TC(跨模块同号照旧由校验 4 抓)、
  owner_docs_glob = test/host/<目录>/*、每模块游标做号段不越界(含 IEC104 补漏:
  它上批改名前是纯数字 TC-104-*,没进当时的悬空普查所以漏建族)
- 新旗标 allow_orphans(不补该旗标会让 141 号全变孤儿告警)、
  subitem_ok(小写子项后缀母号在册即算已定义,差异仍由双向追溯如实报)
- snapshot_only:§4.3 冻结快照族不参与"定义位优先"——先试无差别生效时,已销项的
  登记簿 N-21 被审计报告同号接管,校验 6 从 266 暴涨到 1437、可判定比例假崩 68.7%,
  且提示会教人补错文档名(正是 §1.2 的 N-31 撞号制造方式),故回退并改为快照族豁免
- excluded_paths 加 scripts/id_aliases.json 与 scripts/id_registry.json:
  别名表/注册表自身不得制造引用面
- T-2 / T-3 / T-4 / T-6 入别名表标 void(2026-10-02 复审专项条目,销项只删行没清引用)

修自己的漏配(这条是 bug 修复,不是口径)
- N / S-LDG / T-LDG 族漏登记 docs/任务规划/README.md(活登记处,N-21 在其中出现 2 次),
  只登记了 docs/任务规划/登记簿.md(N-21 为 0)→ 74 处真条目被误判

数字与诚实交代
- 错误级 1318 → 711(②398 + ③44 + ⑥269);可判定比例 82.74%(基线 82.6%)
- ⚠ 其中 504 处属**口径修正**、74 处属**修 bug**,**真正变好 0 处**;已在
  docs/编号规范.md §8.1 写口径修正记录表,禁止拿 711 与 1318 直接比
- 文档:§4.1 补 TC-HOST 说明、§8.1 口径修正记录、§8.3 批 3 行、变更记录;
  pre-commit使用说明 §2.25 判定口径与最新实测同步
- 未改任何 C/H,不需 @build;提交钩子即 L0 + L0.5 全量验证
This commit is contained in:
2026-10-21 10:51:25 +08:00
parent bda7ab2b50
commit 4b9a4f4e24
5 changed files with 297 additions and 16 deletions
+25
View File
@@ -304,6 +304,19 @@ class Checker(object):
for f in fams:
if f.get("adjacent_required") and self._has_adjacent_cue(f, line, start):
return f
# **定义位优先**:号在哪个族的属主登记处真定义了,就按那个族判。
# 没有这一条,`TC-NANDPORT-007`(定义在 test/host/nand_port 的 TC-HOST 族)在别处
# 被引用时会落回通用 TC 族(属主 = docs/测试说明/),假报一片悬空。
for f in fams:
# §4.3 **冻结历史快照族不参与定族**:它的号只是当年报告的存档,不是活的属主。
# 否则 `N-21`(登记簿条目已销项)会被报告里同号的另一码事"接管",报出
# "请写《项目审查与优化建议报告》的文档名"——照做就把登记簿条目和审计报告
# 搅成一条,正是 §1.2 的 N-31/N-32 撞号制造方式(实测这么改,属主不明暴涨 392 条、
# 可判定比例假崩到 69.9%)。快照族只在**有紧邻文档名**时才被上面的线索步选中。
if f.get("snapshot_only"):
continue
if literal in self.owner_tokens[f["name"]]:
return f
for f in fams:
if f.get("check_dangling") and f["_owners"]:
return f
@@ -421,6 +434,14 @@ class Checker(object):
if alias_hit(self, literal, rel) or literal in set(fam.get("allow_missing_defs", [])):
self.stats["alias_hits"] += 1
return
if fam.get("subitem_ok"):
# 小写子项后缀(`TC-TIMESYNC-003b`):§4.1 明写「后缀只允许 -<小写字母>」,
# 是**合法形态**,母号在册就算语义可判定;逐条登记子项只会把文档写成代码复述。
# 可见性不丢——check_test_traceability.py 仍按完整字面量报 码有文档无。
base = re.sub(r"[a-z]$", "", literal)
if base != literal and base in self.defined_all:
self.stats["subitem_hits"] += 1
return
sev = fam.get("dangling_outside_owner", "error") if rel not in fam["_owners"] else "error"
self.add(3, sev, rel, lineno, literal,
"悬空引用:%s 在属主登记处(%s)查无定义,也不在别名表里(§8 校验 3)"
@@ -504,6 +525,10 @@ class Checker(object):
for fam in self.families:
if not fam.get("check_dangling") or not fam["_owners"]:
continue
if fam.get("allow_orphans"):
# 属主登记处 = 代码的族(TC-HOST-*):号定义在测试函数上、本来就只在
# 自己文件里出现,按"无人引用"报孤儿是纯噪音(118 条),显式声明不判
continue
for lit in sorted(self.owner_tokens[fam["name"]]):
outside = {r for r in self.refs.get(lit, set()) if r not in fam["_owners"]}
if not outside:
+20
View File
@@ -2668,6 +2668,26 @@
"to": "TC-IEC104-023",
"status": "renamed",
"note": "批 2:数字模块码 104 → IEC104(§6 表里本就写 I104,代码写成纯数字 104;纯数字不是模块码)(scripts/rename_ids.py 批:族 TC-IEC104)|全库生效(本批字面量已完全限定,无歧义)"
},
"T-2": {
"to": null,
"status": "void",
"note": "2026-10-02 版复审专项条目号(docs/任务规划/测试与架构专项.md 卷首声明「编号不随条目删除而回收」)。该条目已按「完成即销项」删行,仓内现存 T-1 仍在册;引用本号的 .dsh/skills 脚本与 test/ 文档属**引用未清**(§5.5 只做了一半)。本条只让门禁停止把它当自造号并如实指路:改写成语义标识(§3.3)或写全出处,**不要新发一个 T-2 号**(号不回收)"
},
"T-3": {
"to": null,
"status": "void",
"note": "2026-10-02 版复审专项条目号(docs/任务规划/测试与架构专项.md 卷首声明「编号不随条目删除而回收」)。该条目已按「完成即销项」删行,仓内现存 T-1 仍在册;引用本号的 .dsh/skills 脚本与 test/ 文档属**引用未清**(§5.5 只做了一半)。本条只让门禁停止把它当自造号并如实指路:改写成语义标识(§3.3)或写全出处,**不要新发一个 T-2 号**(号不回收)"
},
"T-4": {
"to": null,
"status": "void",
"note": "2026-10-02 版复审专项条目号(docs/任务规划/测试与架构专项.md 卷首声明「编号不随条目删除而回收」)。该条目已按「完成即销项」删行,仓内现存 T-1 仍在册;引用本号的 .dsh/skills 脚本与 test/ 文档属**引用未清**(§5.5 只做了一半)。本条只让门禁停止把它当自造号并如实指路:改写成语义标识(§3.3)或写全出处,**不要新发一个 T-2 号**(号不回收)"
},
"T-6": {
"to": null,
"status": "void",
"note": "2026-10-02 版复审专项条目号(docs/任务规划/测试与架构专项.md 卷首声明「编号不随条目删除而回收」)。该条目已按「完成即销项」删行,仓内现存 T-1 仍在册;引用本号的 .dsh/skills 脚本与 test/ 文档属**引用未清**(§5.5 只做了一半)。本条只让门禁停止把它当自造号并如实指路:改写成语义标识(§3.3)或写全出处,**不要新发一个 T-2 号**(号不回收)"
}
},
"id_aliases": {}
+234 -14
View File
@@ -207,7 +207,8 @@
"title": "登记簿条目(§4.1 在册保留;S-x/T-x 按 §7.1 并入本族)",
"pattern": "\\bN-[0-9]{1,3}[a-z]?\\b",
"owner_docs": [
"docs/任务规划/登记簿.md"
"docs/任务规划/登记簿.md",
"docs/任务规划/README.md"
],
"scope": "global",
"frozen": false,
@@ -224,7 +225,8 @@
"title": "登记簿 存储/日志管线 条目(§7.1 续号并入 N,存量冻结)",
"pattern": "\\bS-[0-9]{1,2}\\b",
"owner_docs": [
"docs/任务规划/登记簿.md"
"docs/任务规划/登记簿.md",
"docs/任务规划/README.md"
],
"scope": "global",
"frozen": true,
@@ -242,7 +244,8 @@
"pattern": "\\bT-[0-9]{1,2}\\b",
"owner_docs": [
"docs/任务规划/登记簿.md",
"docs/任务规划/测试与架构专项.md"
"docs/任务规划/测试与架构专项.md",
"docs/任务规划/README.md"
],
"scope": "global",
"frozen": true,
@@ -397,7 +400,8 @@
"指南",
"说明"
],
"module_code_note": "2026-10-20 批 2 模块码单词化后码长可达 9 位(ADCHEALTH/WATCHDOG),{0,4} 放宽到 {0,9};不放宽会让改名后的号整批从门禁眼里消失(实测漏 950 处)"
"module_code_note": "2026-10-20 批 2 模块码单词化后码长可达 9 位(ADCHEALTH/WATCHDOG),{0,4} 放宽到 {0,9};不放宽会让改名后的号整批从门禁眼里消失(实测漏 950 处)",
"subitem_ok": true
},
{
"name": "TC-UPPER",
@@ -412,7 +416,8 @@
"cursor": null,
"check_dangling": false,
"malformed": "大写后缀非法:§4.1 规定后缀只允许 -<小写字母>(§7.1 统一为小写)",
"module_code_note": "2026-10-20 批 2 模块码单词化后码长可达 9 位(ADCHEALTH/WATCHDOG),{0,4} 放宽到 {0,9};不放宽会让改名后的号整批从门禁眼里消失(实测漏 950 处)"
"module_code_note": "2026-10-20 批 2 模块码单词化后码长可达 9 位(ADCHEALTH/WATCHDOG),{0,4} 放宽到 {0,9};不放宽会让改名后的号整批从门禁眼里消失(实测漏 950 处)",
"subitem_ok": true
},
{
"name": "TC-NOMOD",
@@ -427,7 +432,8 @@
"frozen": true,
"cursor": null,
"check_dangling": false,
"malformed": "缺模块码:须写 TC-<MOD>-<nnn>(§4.1 / §6 模块码表;§7.2 列为孤儿待补文档)"
"malformed": "缺模块码:须写 TC-<MOD>-<nnn>(§4.1 / §6 模块码表;§7.2 列为孤儿待补文档)",
"subitem_ok": true
},
{
"name": "TM",
@@ -913,7 +919,9 @@
"审查"
],
"collides_with": "N",
"cursor_note": "⚠ 与登记簿 N-x 同名不同义(§4.3 / AGENTS.md 模块约定)→ 引用必须紧邻「报告」或报告文档名"
"cursor_note": "⚠ 与登记簿 N-x 同名不同义(§4.3 / AGENTS.md 模块约定)→ 引用必须紧邻「报告」或报告文档名",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "D-RPT",
@@ -933,7 +941,9 @@
"报告",
"审查"
],
"collides_with": "D"
"collides_with": "D",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "S-RPT",
@@ -952,7 +962,9 @@
"报告",
"审查"
],
"collides_with": "N"
"collides_with": "N",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "R-RPT",
@@ -971,7 +983,9 @@
"报告",
"审查"
],
"cursor_note": "实测现存至 R-9(2026-10-15 落地);§1.2 记「R1=风险、R-2=内存优化项」同字母歧义"
"cursor_note": "实测现存至 R-9(2026-10-15 落地);§1.2 记「R1=风险、R-2=内存优化项」同字母歧义",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "F-RPT",
@@ -989,7 +1003,9 @@
"adjacent_cues": [
"报告",
"审查"
]
],
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "A-AUDIT",
@@ -1010,7 +1026,9 @@
"审计",
"Trap_Records"
],
"collides_with": "A-REVIEW"
"collides_with": "A-REVIEW",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "B-AUDIT",
@@ -1031,7 +1049,9 @@
"审计",
"Trap_Records"
],
"collides_with": "B"
"collides_with": "B",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "S-REVIEW",
@@ -1112,7 +1132,9 @@
"P1 收尾",
"严重度"
],
"cursor_note": "⚠ 档位词 P0~P3 不带 -<数字> 后缀(§4.4);本族是历史审计条目,形态按 §4.3 冻结沿用,新发现改语义标识(§3.3);报告侧 P-x 属历史基线(§4.3),文档外按告警处理"
"cursor_note": "⚠ 档位词 P0~P3 不带 -<数字> 后缀(§4.4);本族是历史审计条目,形态按 §4.3 冻结沿用,新发现改语义标识(§3.3);报告侧 P-x 属历史基线(§4.3),文档外按告警处理",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走"
},
{
"name": "O-DOC",
@@ -1371,6 +1393,204 @@
"cursor_owner_only": true,
"owner_note": "属主登记处 = check_menu_rows.py 的 STATES 表(键序 → 状态);UI_自动化测试流程.md 与 simulator/README.md 是引用方",
"cursor_note": "2026-10-20 批 1 从裸形 S0~S7 单词化(原名与登记簿 S-x、代码规范条款、2026-10-02 复审专项条目四义撞形,见 §1.2)。8 态封顶:加状态先改游标"
},
{
"name": "TC-HOST-NANDPORT",
"class": "TC",
"title": "主机侧单测用例号:dhara NAND 移植层(N-21)(test/host/nand_port)",
"pattern": "\\bTC-NANDPORT-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/nand_port/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-NANDPORT-700",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-PROTSET",
"class": "TC",
"title": "主机侧单测用例号:保护定值模型 L3(test/host/prot_set)",
"pattern": "\\bTC-PROTSET-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/prot_set/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-PROTSET-011",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-PROTELEM",
"class": "TC",
"title": "主机侧单测用例号:保护元件/判据框架 L3(test/host/prot_elm)",
"pattern": "\\bTC-PROTELEM-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/prot_elm/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-PROTELEM-013",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-FREQ",
"class": "TC",
"title": "主机侧单测用例号:L2.5 测频(自适应窗)(test/host/freq)",
"pattern": "\\bTC-FREQ-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/freq/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-FREQ-011",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-FTPAUTH",
"class": "TC",
"title": "主机侧单测用例号:FTP 鉴权与锁定策略(test/host/ftp_auth)",
"pattern": "\\bTC-FTPAUTH-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/ftp_auth/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-FTPAUTH-010",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-SHA256",
"class": "TC",
"title": "主机侧单测用例号:SHA-256 摘要(口令哈希底座)(test/host/sha256)",
"pattern": "\\bTC-SHA256-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/sha256/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-SHA256-008",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-SOE",
"class": "TC",
"title": "主机侧单测用例号:SOE 事件顺序记录编解码(test/host/soe)",
"pattern": "\\bTC-SOE-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/soe/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-SOE-007",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-ADCHEALTH",
"class": "TC",
"title": "主机侧单测用例号:L1 采集有效性校验(test/host/adc_health)",
"pattern": "\\bTC-ADCHEALTH-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/adc_health/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-ADCHEALTH-011",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径(用户裁定 2026-10-21):这些号实测在代码目录外零消费者(唯一外部引用是 id_aliases.json 自己),故属主登记处 = 单测代码本身,不逐号补文档;class 仍为 TC → 跨模块同号由校验 4 抓",
"cursor_note": "游标按实测最大号收录(2026-10-21):越界即视为未登记的冒号牌"
},
{
"name": "TC-HOST-IEC104",
"class": "TC",
"title": "主机侧单测用例号:IEC 60870-5-104 协议栈(test/host/iec104)",
"pattern": "\\bTC-IEC104-[0-9]{1,4}[a-z]?\\b",
"digit_width": [
2,
4
],
"owner_docs_glob": [
"test/host/iec104/*"
],
"scope": "global",
"frozen": false,
"cursor": "TC-IEC104-023",
"cursor_owner_only": true,
"check_dangling": true,
"allow_orphans": true,
"subitem_ok": true,
"owner_note": "B 层口径同其余 TC-HOST 族;本族是 2026-10-21 补漏——上批模块码改名前它是纯数字 `TC-104-*`,未进当时的悬空普查,故漏建族",
"cursor_note": "游标按实测最大号收录(2026-10-21)"
}
],
"unmanaged_bare": {