STM32F4-Base/docs/编号规范.md

编号规范：默认不用编号

一句话：语义标识是唯一形态，编号一律停发。 2026-10-29 用户裁定：任何族都不再新增编号， 连 §4.1 那五个「有脚本按字面量匹配」的存量族也一样——既有号只读引用，族里新增内容写语义行名（§3.3）。 §4.1.1 另列更早停发、存量待清的族（清点见 编号治理历史.md §9.1）。

这条不是洁癖，是用户 2026-10-27 的明确要求：「不要用字母加数字的编号，简直太难以理解了，语义标识是最好的」， 2026-10-29 又收一句：「啥号都不发」。 依据也很硬：规划 / 待办 / 审计 / 差距 / 阶段这些给人看的东西，历史上全发过号，也全都变成了没人认得的代号。 2026-10-26 起两批清理把编号字面量从 10,956 压到 8,230 处，2026-10-27 复测为 7,828 处（编号治理历史.md §8.1 有口径说明）； 而清掉的号里绝大多数从来没被任何脚本读过一次。沿革与教训留在 编号治理历史.md §8.3 与 git log，正文不复述。

本文就是唯一事实源：两道编号门禁已分别于 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）。

---

0. 2026-11-02 用户裁定：人读文档清退存量编号

新口径：人读文档里不再出现字母+数字编号，一律写语义短语。 此前「停发但不清理存量」的做法 从本节起作废——用户明确要求把编号删掉，因为它们同形多义、读者只能靠查表才能看懂。

本批先清退两类：

• 任务/批次类短号（如 B0～B10、批 2）；
• 残留的分层叫法（如 L0/L0.5/L1/L2/L3/L2.5）。

后续批次继续清退审计、报告、差距、阶段、复审等编号族；判据仍是「人读的文档写短语，机器读的键才留号」。

例外（不要误删）：

• 脚本按字面量读取的机器键：TC-*（测试用例追溯）、CODE-RULE-*（代码规范门禁）、 MENU-STATE-*（UI 像素回归）、TRAP-*（陷阱台账）、FR-*（需求追溯）；
• 硬件位号/网名/引脚名（U5.B10、PB12、A4:94:B6:... 等）、协议号（IEC 104、RS-485、2404）、 版本号（V0.1/V0.2）、文件路径与原始日志；
• 冻结的历史证据（docs/测试说明/测试数据/、历史串口日志）不回改，避免破坏取证。

清理时绝不全局查找替换：同一裸形字面量可能同时是任务号、引脚名、MAC 地址或图节点 ID； 必须先判族、再限定 scope，每处断言命中数。

存量清点与逐号换算表）2026-10-28 已整体移入 scripts/archive/id_gate/编号治理历史.md，下文简称 编号治理历史.md；它的节号沿用旧编号、故意不重排（外部文档与脚本引的是 §4.1 / §8.5 这类号， 重排等于制造一批假链接）。要查历史判据、批次流水、「数据可信」任务卡号换算表，去那篇； 改现在的做法只看本文。

1. 默认答案：不发号

2026-10-29 用户裁定：新条目一律不配编号。 这里原本是三句自问（「有脚本按字面量匹配就允许发」）， 现在这条路也关掉了——判「能不能发号」不再看形态，答案恒为否。剩下的只是既有号怎么用：

场景	怎么做
想给新需求 / 新踩坑 / 新用例 / 新待办配个号	不发，写语义行名（§3.3）；登记表那一行的行名就是标识
新东西确实要被脚本按字面量匹配（比如新的回归脚本键）	先问用户（Ask first）。批下来才算例外，顺序见 §4.1 末条
现有文档或登记表里已经能指代这件事	引用它，别再发第二个号指同一件事
碰到查不到定义的号	删号留事实，不是补一个定义（§10）

三条硬规矩（管既有号的引用与处置）：

• 号不承载语义：严重度、优先级、模块名、轮次都不写进号里。事实一变，号就开始撒谎。
• 号不回收、不复用：销项 = 删登记行 + 清掉所有引用 + 别名表标 void（§5.5）。历史上"销掉的号被 重新取走"撞过两次。
• 引用必须带语义：号旁边要有人话，裸号不许独担信息（读者不该被迫查表才看懂一句话）。

3. 三种指代方式，按这个顺序挑

优先	方式	用在
① 最好	语义短语	规划 / 待办 / 缺陷 / 风险 / 决策 / 差距 / 文档内步骤与阶段——默认形态
② 其次	文档名 + 章节号	指某篇文档的某节（docs/网络/网络自愈架构设计.md §4.10，紧邻写法）
③ 最后	编号	只指 §4.1 五个存量族的既有号（只读），且必须能反查到定义；新条目不在此列

3.1 判定口诀

机器读 → 发号；人读 → 写短语。 拿不准就写短语：短语看不懂还能靠上下文猜，号看不懂只能去查表。

3.2 编号 vs 章节引用

章节引用不是编号，但同样要紧邻文档名——只写「§ + 小节号」而不写文档名，会被 doc-links 当成本文自引用而静默放过， 这是它的已知盲区，别踩。

3.3 语义标识（默认形态，怎么写）

• 一行短语就是标识：≤20 汉字、说清"是什么事"、同一登记表内不撞名（同义异写算撞名）。
• 好的例子：双转换器无共同采样触发、FTP 鉴权、写回缓存空闲 flush、队列往返基线待重验。 坏的例子：优化项 3、遗留问题、重要缺陷——换个上下文就指代不明，等于又造了个号。
• 登记处就是那张表：表首格写短语，不要再配一个字母号；跨文档引用写成 `docs/任务规划/登记簿.md` 「双转换器无共同采样触发」，同篇后续直接用短语。
• 文档内的实施步骤 / 测试阶段 / 设计原则条目写中文：「步骤 3」「阶段 7」「DMA 边界安全」， 不写 S3 / TM-… / DP-… 这种号。

---

4. 编号空间

4.1 存量族（穷举——2026-10-29 起连这五个族也不再发新号）

下表恰好 5 行，是仓库里仅剩还带编号的族：既有号继续被脚本按字面量匹配、继续被引用，但族里新增 内容不再配号（写语义行名）。「有脚本按字面量匹配它」这个旧判据自 2026-10-29 起作废——这五族的号是 历史遗留的机器把手，不是发号许可。TC-* 早两天（2026-10-27）已按同一逻辑停发，清点与来龙去脉在 编号治理历史.md §9.1 批次三。

族	形态	属主登记处	既有号被谁读 / 新写怎么办
TRAP-*	TRAP-<域>-<nn>	docs/问题记录/*_Trap_Records.md	代码注释按号反查踩坑证词；新踩坑在域文件里写语义行名，不再顺延号段
FR-*	需求	docs/产品需求/产品需求设计文档.md §5	需求↔测试追溯的既有键；新需求用 §5 表格的行名（语义短语）指代，追溯按既有号跑存量
CODE-RULE-<nn>	代码规范条款	scripts/check_coding_standard.py	门禁按条款号报错并统计存量；新条款先问用户——脚本要按号统计，破例得由用户批
MENU-STATE-<nn>	UI 状态机键	simulator/tests/check_menu_rows.py	像素回归脚本按它取状态行；新状态同样先问用户
P-<n>	编号治理的设计原则	scripts/archive/id_gate/编号治理历史.md §2（2026-10-28 随沿革归档，本文不再列条目）	只读存量：原则已归档，新写条目按 §3.3 写语义短语

⚠ 停发只有一层意思：不去清存量号，但发号口关死。2026-10-29 起这句话适用于全部族，不只 TC-*。 维持原状的是存量号，关掉的是发号口。四条对照，防止往任何一边读过头：

• ❌「§4.1 里的族没被点名停发，所以还能发」——错。五族一样不发，新条目写语义行名（§3.3）； 指认既有需求 / 踩坑 / 用例仍可引用现存号（旧号只读，不是新配的许可）。
• ❌「停发 = 这族要废了，顺手清掉、把号腾出来复用」——也错。现存号是脚本与追溯机制认的把手 （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-ADCIN- 段）的 cursor 为 null——一个游标表达不了每个模块码的水位，写全族最高号反而放行低号。机器面在的时候它就不响， 现在连壳都没有：给这类模块码补号，即使在文档表格里一并补了定义行，一样违反裁定，评审专门盯。 要钉死它（按模块码克隆子族）与「真要清退」同属追溯机制改造，按 编号治理历史.md §7.3 单独开卡。
• 唯一的例外入口：先由用户裁定 → 再回到 §4.1 把该族写清「哪个脚本按字面量匹配它」 → 才谈得上 发号。顺序倒过来就是 编号治理历史.md §1.2 那四类事故的由来。

已停发、存量待清（§4.1 那五族 2026-10-29 起同样停发，区别只在存量保留、不去清；本表这些族连存量引用也要清掉，一律不得再新增引用；下表除 TC-* 外，id_registry.json 里剩的登记只是归档普查的 语料残留，不再当"登记处"读——那份登记自 2026-10-28 起没有机器读者。清点见 编号治理历史.md §9.1。 TC-* 是这一栏的特例：登记与现存号都要留着，现存号仍被追溯脚本按字面量读，不是待清对象 （见 编号治理历史.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<n>-<nn>	保护功能号	批次二已整族转功能名，即日停发：活引用 0，只剩一处原始串口日志（冻结证据、永久保留）与本文/技能文档的形态举例；属主文档表首格写功能名，不再配号	用户 2026-10-27 定调「语义标识是最好的」+ 本轮指令「把能清的族清掉一批」；发号口此前由"悬空引用"校验关着，2026-10-29 起只由本表与评审关。数值游标不冻结：L1/L2/…各段最高号不同，单一数字游标反而放行低号
F-<MOD>-<nn>	网络设计条目	批次一已转「编号治理历史.md §7 条目名」，即日停发：代码与测试侧 0 处；属主文档 编号治理历史.md §7 编号列 13 条仅作历史对照（定义行不算引用）	同上；引用旧号命中别名表 retired-to-phrase = 只读，不构成发号许可
N-*	登记簿 N-<nn>	4 处 / 3 个字面量	登记簿已于 2026-10-26 全面改语义短语，残留的是漏网的旧引用
TM-*	阶段/里程碑 TM-<code>-<nn>	1 处	阶段号本就属 §3.3 明令不许写号的那类
T-TEST	台架阶段 裸形（字母 T 紧跟一位数字）	活引用 0（批次一清零；余下是本文自述与技能文档的形态举例）	裸形最危险（同字母多义），且改「台架阶段一」即可
F-*	网络设计条目 F-<MOD>-<nn>	动手前 38 处 / 12 个 → 2026-10-27 批次一收口：正文 9 处（含一个从来没有定义行的 DRV 段孤儿号，删号）+ 主机侧单测注释 1 处改「条目名」，仅属主文档 编号治理历史.md §7 历史对照表留 12 条编号	代码注释按号回指设计条目，但没有任何脚本匹配它

• 新增族：2026-10-29 起一律不许，先问用户。真批下来，顺序固定：先改本文 §4.1（写清哪个脚本按字面量 匹配它）→ 再写属主文档 → 届时有机器面才动 scripts/archive/id_gate/id_registry.json → 最后才允许在别处 引用。反过来做必然造出悬空号。
• 模块码是既定缩写，事实源 = registry 的族 pattern 与属主文档标题行，别自创（编号治理历史.md §6）。

4.1.1 已停发的族（别再指，更别再"复用"这些号）

停发族	现在怎么写	旧号去哪查
登记簿 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-<nn>（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	⚠ 这一族从来没有机器面：两道门禁的语料族 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 等）	同上，写事实	无定义，本就不该存在

想知道某个号还活着吗：查 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 这些不是编号——别顺手清

元器件位号 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。 判据只有一条：带连字符、且能在属主登记表查到定义才叫编号；查不到的就是普通文本，不是「漏登记的号」。

两条口径来自当年的语料审计，今天判"是不是编号"照它想：① 元器件位号整目录排除—— tools/netlist_semantics/ 是硬件知识库（字母 T 紧跟数字在那里是网络变压器位号），与 docs/硬件平台/ 同口径（归档普查把它写在 id_registry.json 的 excluded_paths）；② 唯一已知误判： docs/算法/傅氏算法详解.md 里的数学记号 N-1（「一个周波 N 个点」的求和上界）形似 N-x 族， 属可判定的普通文本，不清——清了反而破坏公式。

5. 分配、引用、销项

5.1 新增编号：默认答案是没有

一律不发（§1、§4.1）。新条目写语义短语（§3.3），登记处的行名就是标识；引用既有号必须能反查到定义、 旁边必须带人话（§1 三条硬规矩）。唯一入口是用户裁定：某样新东西确实要被脚本按字面量匹配时先问， 批下来再按 §4.1 末条的顺序落文档。 scripts/archive/id_gate/id_registry.json 的族与游标登记只在恢复机器面时才动（§8.5）：没有脚本读它， 写进去也拦不住任何人——「registry 里查得到」从来不是发号许可，许可只来自用户裁定。

5.3 代码注释

优先写短语（FTP 鉴权、监听生命周期模块化），别写字母号；确需引用活号时必须带属主文档名。 规划 / 待办类编号禁止出现在代码里——代码的寿命比任何一张待办表都长，待办表改了行，注释就成了 永久的假引用（本仓实测：196 处这样的死引用，全是这么攒出来的）。

5.5 销项与归档

删登记行 + 同步清掉全仓引用（清引用是销项的一部分，不是"以后再说"）+ 别名表标 void。 冻结的历史（[示例] / [计划] 行、仍保留变更记录表的文档）不回改。2026-10-28 起新文档一律不再设 「变更记录」节（docs/文档规范.md §5.1——例外清单以那一节为准，本文不复制份数，抄一份就会漂一次）。 所以"冻结历史行"只对清单里的文档与 scripts/archive/id_gate/ 下的归档文档生效，不是「以后还能往变更 记录里写」的理由。唯一例外（用户裁定 2026-10-28）：这类行里已停发 / 作废族的示例编号可改成形态 描述（写成「字母紧跟数字」这类说法）——改的是示例的写法，不是历史事实；保留现存号族的游标数字与 硬件位号举例不在例外内，形态化等于毁证据。原先那句「门禁对它们已豁免」随门禁一起失效： 现在没有任何门禁会去看这些行。

5.7 语义标识的登记与别名

短语就是登记处的行名，不需要别名表；**只有"号转短语"**时才在别名表留一条 retired-to-phrase， note 写清短语，方便把残留引用找干净。

---

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 存量族表与人工评审。

全库八项校验（未登记前缀 / 形态不合规 / 悬空引用 / 重复定义 / 冻结族越游标 / 未紧邻文档名 / 孤儿告警 / 可判定比例 + 两根护栏）2026-10-28 退役：它查过什么、为什么退、当年清点数字 → docs/门禁说明/id-check.md 与 scripts/archive/id_gate/编号治理历史.md。本文不抄第二份口径——那份口径已经数错过一次了。

8.5 手工普查与恢复机器面

没有门禁不等于没有工具，两份脚本都还在，随时能跑（它们退成了工具，不是消失了）：

scripts/archive/id_gate/check_ids_new.py --range A..B   # 只看一段提交的新增行里有没有自造形态
scripts/archive/id_gate/check_ids.py --top 0            # 全库存量普查（报告制，不影响退出码）

• 恢复机器面的成本：把脚本放回 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。

---

10. 速查

• 看到一个不认识的号 → 先查 id_aliases.json 与属主登记表；查不到就删号留事实，不要补定义。
• 想给任何新条目发号（含需求 FR-*、踩坑 TRAP-*、用例 TC-*、待办与风险）→ 不许，写语义行名（§3.3 / §4.1）。
• 想知道「还有多少号可清」→ 看 编号治理历史.md §9 的存量表与三批计划。
• 想给文档内步骤或测试阶段发号 → 不许，写「步骤 3」「阶段 7」（§3.3）。
• 想新增前缀族 → 先问用户（Ask first）；「有脚本要按字面量匹配它」这个旧判据自 2026-10-29 起不再构成许可（§1）。
• 要改号 → scripts/rename_ids.py + 编号治理历史.md §7.3 五步。
• 编号形态拿不准 → 本文 §1 的默认答案 + §4.1 那张表；没有任何机器会替你兜。两道门禁的历史与退役理由 → docs/门禁说明/id-check.md、docs/门禁说明/id-check-new.md。
• 想让机器帮你扫一批改动，或要恢复机器面 → §8.5。