STM32F4-Base/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.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 语料内，口径 = 自建扫描器」。

2. 销项删行前先核证据属主（这是删行的唯一许可证）：

   • 先取历史口径：git log --oneline -20 -- <文档>、git show <rev>:<文档> | sed -n '/^## 5/,/^## 6/p' 找回被删的卡表与当初「完成即销项删行 / 标 ✅ 保留行」的理由；
   • 核对判据与实测记录已完整沉淀进属主章节（实测：「已知电压注入验证」六项判据全 PASS、斜率 6544.2 码/V、偏差 −0.14 % 全在 docs/硬件平台/ADC通道映射说明.md §8.1，执行侧在 docs/测试说明/ADC前端注入验证流程.md）；
   • 删的是任务规划侧的行与结论块，不是证据本体；被代码头注释指称的设计约束章节（§2~§4 那类）原样保留，只删已完成记录；
   • 该行若当初是被「代码头注释按号引用」当例外保住的（实测 App/task/adc_task.c 的 v3.3 修订行按卡号当口径出处），必须先把引用侧改成语义短语，例外才成立撤销，并在规范里写明撤销理由（上一笔「完成即保留行」的例外就是这么随引用侧改动被撤掉的）；
   • 删完逐行通读被改小节，报行数变化，不留孤立残句（实测 J7 dropped line 234 len=639、J13 闭环结论块 6 行删除并注明证据属主）。

3. 自建带标签正则扫描脚本——四条硬规矩，全是实测返工换来的：

   • 脚本落文件（ci-artifacts/scan_ka_refs.py）再跑，不用 bash heredoc（heredoc 里的 \s 被多层引号咬坏：SyntaxWarning: invalid escape sequence + 语法错）；
   • 正则一律 raw 字符串、汉字写 \uXXXX：KA = r"\u5361"。非 raw 串里 "\b" 会先被 Python 解成退格符（0x08）→ 正则静默失配且不报错；"\s" 只是警告还能跑，"\b" 是真错；
   • 排除 .git（连同 .venv、ci-artifacts、__pycache__、node_modules）——实测扫进 .git/COMMIT_MSG_*.txt，一堆 GBK 乱码历史被当成残留，越清越多；
   • 报告写 UTF-8 文件（ci-artifacts/ka_refs.txt）再本地解析，别靠控制台输出（Windows 控制台按 GBK 渲染中文 = 乱码）；判乱码统计 EF BF BD 字节数，别信终端渲染。

   # -*- coding: utf-8 -*-
   """扫描中文前缀任务卡号与同期形似噪声号；报告写 UTF-8 文件。"""
   import io, os, re
   KA = r"\u5361"                                    # 卡
   PATS = [("CARD_ANY", re.compile(KA + r"\s*[0-9]")),
           ("KA0B",     re.compile(KA + r"\s*0b")),
           ("KA12",     re.compile(KA + r"\s*12")),
           ("M4",       re.compile(r"\bM4\b")),
           ("M5",       re.compile(r"\bM5\b")),
           ("M6",       re.compile(r"\bM6\b"))]
   SKIP = {".git", ".venv", "ci-artifacts", "__pycache__", "node_modules"}
   out = io.open("ci-artifacts/ka_refs.txt", "w", encoding="utf-8")
   for root, dirs, names in os.walk("."):
       dirs[:] = [d for d in dirs if d not in SKIP]
       for n in names:
           p = os.path.join(root, n)
           try:
               txt = io.open(p, encoding="utf-8", errors="ignore").read()
           except OSError:
               continue
           for i, line in enumerate(txt.splitlines(), 1):
               for tag, rx in PATS:
                   if rx.search(line):
                       out.write("===== %s\n" % p)   # 同一行可命中多标签 → 按标签分别计数
                       out.write("%d [%s] %s\n" % (i, tag, line.strip()[:200]))
   out.close()
   

   末尾打 TOTAL_SITES / FILES / SCANNED / 各标签计数；带标签才拆得开噪声（同一行可同时命中 CARD_ANY 与 KA12）。

4. 该族与形似噪声号分开计数，各自给分母：一遍扫描出 TOTAL_SITES 420 FILES 85 SCANNED 1025，必须再拆成卡族 288 处 / 56 文件 与 里程碑噪声 132 处 / 44 文件（M4/M5/M6 大片落在 docs/芯片手册/ 参考手册与料号上下文里）。两套数字各自给分母——「420 处待改」是错的：把 132 处噪声算进清退范围就会去改芯片手册原文。噪声侧一律保持原样，是否清退等用户单独裁定，不要顺手做。

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「已停发的族」表加一行，三列齐全，第三列直写「⚠ 这一族从来没有机器面：中文前缀不进任何编号语料（族 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 + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，不登记别名；
   • 要机械化怎么办：得先给「中文前缀 + 数字」设计候选形态，属追溯机制改造，按 §7.3 单独开卡，别夹在清退批里顺手做。

8. 替换后三道二次清洗（缺一必留疤，全部实测过）：

   git grep -c -F '端子 / 子板变比确认' -- . ; git grep -c -F '端子/子板变比确认' -- .   # 先数各形态再归一
   git grep -nE '卡[ ]*[0-9]' -- . ; echo "rc=$?"                                        # 裸跑读 rc；1 = 归零
   

   • 同句重复短语：编号位置补上的语义短语与原句已有短语撞车 → 扫「同一行里同一短语出现 ≥2 次」（实测 12 行，如 .pre-commit-config.yaml:401「运行参数段（「数据可信」运行参数段交付）」、App/algo/README.md:110「遥测快照发布（L2 发布侧，「数据可信」遥测快照发布）」）→ 改法是把括号里的引用降级成不含该短语的写法（「道D 交付项」「波次」「该点 DoD 原句」），逐处断言命中 = 1，别删信息；
   • 空格与引号形态归一：同一语义短语可能有 端子 / 子板变比确认 与 端子/子板变比确认 两种形态 → 先 git grep -c -F 分别数（实测带空格 8 处），再整文件归一，归一后复扫到 0（残留常藏在表格单元格里，逐行打印定位）；引号形态同理；
   • 固定正则复扫：卡[ ]*[0-9] 全仓无输出。⚠ 判 rc 时不要把命令接在 | head 之后再读 $?（那拿到的是 head 的 0，会把「还有残留」读成「已归零」）。

9. 收尾复跑 + 清中间产物：check_ids.py（plain 与 --strict）、check_doc_links.py --all、bom 与乱码两道（pre-commit run bom-guard --files <改过的文件>、pre-commit run no-mojibake --files <改过的文件>）、git diff --check；纯注释/纯文档改动不算免编译——仍跑一次 @build 取「0 错误 0 警告」且 Program Size 与改前同数（本回合真跑，引用历史提交正文自报的四个数不算），受影响的主机组单测照跑。最后删掉 spec 与全部扫描中间产物，别往 ci-artifacts/ 再堆 log/txt。