Files

T

wandering1 4a4ad6bc5f chore(全仓): @build/@test 旧文档别名清退为技能调用名

现状口径：/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名，
不是 shell 命令；「名 + 命令行参数」的命令形态改为可执行体
run_boot_test.py 的真实调用。

- AGENTS.md：别名说明重写为「技能调用名不是 shell 命令」，两条目改
  「编译（/keil-build）」「串口回归（/serial-boot-test）」
- keil-build / serial-boot-test 两 skill 调用名与示例同步；task-worktree
  方案文档去掉 @build/@test 惯例从句；@task 保留（不在点名范围）
- 123 文件现状陈述全改；台架捕获、变更记录/时间线、rename 映射输入
  等 41 行历史证据保留旧名
- gen_memory_svg.py 6 处措辞随改，3 张 SVG 产物同批重跑
- 顺手补并行方案同行漏网计数 51→52 钩子

验证：提交期快钩子对 123 文件实跑全 Passed；check_doc_links --all
rc=0（3038 处、无法判定 0）；check_mermaid --all rc=0；YAML 解析 52
钩子不变；skill-size rc=0；py_compile 全过；字节卫生零漂移。

2026-10-30 13:03:12 +08:00

11 KiB

Raw Blame History

name, description, whenToUse, version

name	description	whenToUse	version
id-family-semantic-migration	编号族整族清退/停发 playbook：把一个编号族（字母+数字如保护功能号 L1-x~L5-x、网络条目号 F-、登记簿旧号 N-x、台架阶段裸形 T1~T3、用例号 TC-，或中文前缀「卡」+ 数字这类门禁语料里没有机器识别面的族）在全仓代码注释、测试、活文档与门禁配置里改成语义短语（含销项删行与逐号换算表入档），或把「不清退」裁定写成硬口径入档。触发语：清退某族编号、编号改成语义名或语义短语、还有多少号可清、残留多少、批次二/批次三/批次五、「卡 0」「卡 0b」「卡 1~12」、销项删行并去除相关编号、id-check 报悬空引用或不可判定超限、不可判定引用绝对数涨点、「这一族不做了」。	用于整族处理：先判这一族有没有机器识别面 → 清点存量 → 逐族分类 → 分批派单清退 → 收口 → 回写 docs/编号规范.md 对应节。单条待办行销项并写 void 别名用 ledger-row-retire-void-id；某个事实数（页数、叶数、钩子数）变了要同步全仓用 stale-doc-count-sweep；单个文件改名或挪目录用 scripts/rename_ref.py；跑 HEAD 版对照组用 task-worktree 的净室 worktree。这四类不由本技能覆盖，但「涨点归因」一节会用到净室 worktree。	1.1.0

编号族清退成语义标识

2026-10-29 用户裁定：全族一律停发（含 docs/编号规范.md §4.1 那五个存量族）——本 playbook 的「停发」分支默认已成立，现在唯一还需要决策的是要不要清退存量（全仓改语义 + 销项删行 + 逐号换算表入档）。

动手前先判这一族有没有「机器识别面」——它决定计数口径的来源与落地去处，两条路的做法正好相反：

族形态	计数口径来源	改名手段	`scripts/archive/id_gate/id_aliases.json`
字母+数字，且在 `scripts/archive/id_gate/check_ids.py` 语料内（`id_registry.json` 有族、族 pattern 能匹配它）	门禁自身计数（`ck.refs` / `ck.stats` / 报告行）	`scripts/rename_ids.py`（映射表 + 显式 scope + 默认干跑）	要登记：死号 `void`、转短语 `retired-to-phrase`
中文前缀（「卡」+ 数字）、纯散文里的号、圈号 ①②③	自建带标签正则扫描器（门禁看不见它，2026-10-28 退役前的 id-check 全库报告与本族无关；两道门禁现都已退役（2026-10-28 / 2026-10-29），要普查形态就手工跑归档脚本 scripts/archive/id_gate/check_ids_new.py --range）	逐处替换 + 断言命中数（`rename_ids.py` 靠族 pattern 驱动，这里用不上）	刻意不登记：登记了机器也看不见，只多一张没人核的表；停发只靠规范 + 评审

怎么判（三条，任一为否即无识别面）：① grep -nE '"name"|"pattern"' scripts/archive/id_gate/id_registry.json，没有任何族 pattern 能匹配该形态；② ./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --top 0 的任何校验里找不到它；③ registry 的 blind_spots 已明写不判（圈号与正常列举无法机械区分、裸形同字母多义只在属主登记处判）。实测：「卡」+ 数字没有族（中文形态只有 malformed 里 陷阱 ?[0-9] 那条禁令，管的是陷阱编号不是卡号），该族真实站点 288 处 / 56 文件，而门禁对它贡献 0。

判错的代价是双向的：拿门禁计数当中文字面量族的口径 → 得出「0 处待改」的假归零；给无识别面的族登记别名 → 制造「有机器兜底」的错觉，真正生效的两条（§4.1.1 停发行、§9.3 换算表）反而没人写。

其余铁律照旧：不要凭 grep 估数、不要凭印象决定改哪几处、不要把「不做」只划掉一行。

口径：三套计数都要挑明，先问再比

口径	怎么数	用途
门禁 refs（去重）	`ck.refs`：字面量 → 文件集合，只记属主登记处文档之外的引用	门禁趋势、批次验收线
逐行站点	按族正则重扫 `ck.iter_files()` 语料，含属主文档的定义行	排工作量、拆单
自建扫描器站点	无识别面族：带标签正则全仓 walk（排除 `.git`）	该族唯一口径，不能拿 id-check 输出代替

实测例：保护功能号一族「字面量 28 / 站点 184 / 文件 58」（ck.refs）与队友报的「219 站点 / 38 文件」并存且都对。队友报任何合并数（指纹、站点数）之前先问口径，不要拿自己的数去否他的数。每个数字标明是本回合实测、动手前基线还是沿用昨日值；形似噪声号另立分母（中文族一节第 4 步），绝不与待清族合并成一个总数。

Steps（字母+数字族：门禁看得见的那一路）

确认范围与定调
按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数
逐族先分类再动手
映射表由属主文档生成
按写域拆道并行派单
门禁配置注释也是本族写入面
每处替换断言命中数
同步更新门禁侧配置
生成器文本改动必须同笔重跑产物
核队友交付
分笔提交走真实 pre-commit 钩子
收口只认门禁自身计数
回写 docs/编号规范.md
裁定「不做」也要写成可执行硬口径入档

本节全文（逐字搬移、未改写，含命令与实测数字）→ steps-alpha-numeric-family.md。动手前先读那篇。

Steps（中文前缀族：连归档扫描工具都咬不到的那一路）

先确认连归档扫描工具也咬不到（两道编号门禁 2026-10-28 / 29 已退役，"咬不咬"从此只是工具层面的事），并把这句话写进交付
销项删行前先核证据属主
自建带标签正则扫描脚本
该族与形似噪声号分开计数，各自给分母
派单前写一份 spec 文件
逐处替换断言命中数
落地位置写死（这一族只有这几条兜）
替换后三道二次清洗
收尾复跑 + 清中间产物

本节全文（逐字搬移、未改写，含命令与实测数字）→ steps-chinese-prefix-family.md。动手前先读那篇。

不可判定引用绝对数涨点的净室归因

「不可判定引用绝对数」比今日低点涨了 N 处时：

禁止用「对提交新增行 grep 字母+数字形态」归因：git diff -U0 的加行里绝大多数文本是从旧行搬来的存量上下文（注释整段重写、表格加一列、Markdown 重新折行），形态匹配数出来的是「哪段文字最近被搬动」，不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。diff -U0 只在已定位到文件之后用来绑笔次与行号。
正解 A（首选，同一计数器相减）：在仓外 detached worktree 跑 HEAD 版（task-worktree skill 的净室测量仪；不 stash、不碰在飞工作区），两边都用同一个 check_ids.py 计数器导出 (rel, literal) 多重集（ck.findings 或 err_groups(ck)），做逐文件集合差，落差的 N 处直接指向具体文件与字面量。
正解 B（逐文件注入）：一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上，就只在注入它时出现；文件多时按 git diff --name-only 折半。
当轮跑不完就如实说：本轮未跑净室归因时，只报「现值需要重新实测」并说明需要跑净室归因，不得给出候选归因对象，不得把上一轮的现值或余量当本回合实测值报出（每个数标明来源与时刻）。
与其它交付口径冲突的差值登记为待查项（两套计数可能都对），不当场判谁对谁错。

Pitfalls

拿门禁计数当中文字面量族的口径
给无机器识别面的族登记 id_aliases.json
拿 grep 计数跟人吵口径
heredoc 里嵌 Python 正则 / 中文
扫描没排除 .git
凭记忆敲 old 串
替换后不做同句重复检测
换算表里复述字面量
| head 之后读 $?
占位符泄漏
删行前不核证据属主、不查当初为什么保留
涨点归因拿 diff 新增行 grep 形态
全局查找替换
未分类就动手
按简称匹配文件清单
复现不了队友的合并指纹就怀疑丢文件
替换 token 含
只改生成器文案不重跑产物
grep 'A|B' 空返回当文件干净
一次 run_code 串 5 × wait_agent(118000) ≈ 590s 整段 abort、进度全丢
游标整型比较静默不生效
git add 目录路径带进别道文件
amend 被 gitlint B1 拦
改「只动注释」要拿机器证据
冻结历史与原始证据不改
*.uvprojx 抖动不入库

本节全文（逐字搬移、未改写，含命令与实测数字）→ pitfalls.md。动手前先读那篇。

Verification

scripts/archive/id_gate/check_ids.py --strict 与 plain 均 rc=0（[OK] 校验 1~6 无错误），悬空引用为 0。
编号字面量与不可判定引用绝对数只降不升、不超 undecidable_total_ceiling；可判定比例不低于 id_registry.json 基线（86.0%）。
本族剩余站点复扫归零：有识别面族从 ck.refs 按族正则过滤字面量逐条打印；除冻结历史/原始证据行外无残留。
pre-commit run generated-fresh --all-files PASS + 目检 svg diff 只有文案与框宽自适应（只在动过生成器时适用）；check_doc_links.py --all 通过。
/keil-build：BUILD=0、0 错 0 警、Program Size 与改前同数（零行为改动证据，本回合真跑）；相关主机组（如 net_socket 457/457）全绿。
真实 pre-commit 钩子全绿（如 passed=33 failed=0）；提交笔内不含他道文件。
规范与台账已回写并复跑核数：自己先前写进规范的清点数字要么按最终实测改对，要么标明为动手前基线；「等你裁定」残留 = 0；「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地（原「变更记录」那一处已随 2026-10-28 清流水退场）。
无识别面族：git grep -nE '卡[ ]*[0-9]' -- . 无输出（裸跑读 rc）；自建扫描器的站点/文件数与提交正文一致；交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 id_aliases.json」的理由；§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全，换算表行数 = 该族字面量数（实测 14），且写明旧号永久作废、不得重新取走。
二次清洗三道各有实测数：同句重复短语 0 行、各空格形态先计数后归一（复扫 0）、固定正则残留 0；被代码头注释引用的设计约束章节仍在（git diff 里没被动过）。
叙述同步：AGENTS.md / docs/README.md / docs/任务规划/README.md / docs/任务规划/登记簿.md 里旧口径（「三项」「卡 N」类）实测归零；ci-artifacts/ 里本次 spec 与中间产物已删。
门禁复跑清单齐：check_ids.py plain + --strict、check_doc_links.py --all、bom-guard、no-mojibake、git diff --check、/keil-build 或受影响单测——每个数字标明是本回合实测。

11 KiB Raw Blame History Unescape Escape