docs: 清理全仓变更记录流水（43 篇整节删 / 23 篇留一行 / 5 篇保留）
用户裁定：文档只写现状，历史流水一律删掉，过程查 git log。 - 43 篇「变更记录 / 修订记录」整节删除：继电保护规划 12.6 KB、产品 需求 11.8 KB、项目部署环境 5.5 KB、BSD Socket 指南 5.3 KB、架构 总览 5.0 KB、实机测试实施指南 3.8 KB 等 - 23 篇别处仍有指向：只留节名 + 一行「本文件不再记流水账，过程查 git log」，节号与锚点不位移（doc-links 不因此断链） - 5 篇整表保留（被当唯一证据 / 活台账引用）：看门狗设计说明、配置 文件设计说明、RAM预算台账、内容页架构、本地工具路径环境变量方案 - 规范同步：文档规范 §5.1 改新裁定；测试文档模板规范删示例节与 登记句；测试开发标准流程 / UI 两篇 / 实机测试实施指南 / 四篇单测 说明 / 并行任务工作树方案 / 编号规范 的「登记变更记录」改「写进 正文」 - 技能同步：stale-doc-count-sweep / ui-verify / id-family 三个 SKILL 正文不再要求追加流水行（顺带消掉 SKILL.md:121「产品需求 §12」 失效引用） - 修 5 处悬空指针：采样有效性校验目录锚点、BSD 指南「文末变更 记录」、docs/README 过期描述、网络自愈架构两处指向面 72 篇文档净减 600 余行；check_doc_links --all --sections-strict 可判 定比例 61% → 78%、失效引用 0；静态门禁 passed=50 failed=0；gitlint 10 条历史提交信息 0 failed。 未提交他人在飞改动：.dsh/skills/keil-build/*（%SystemDrive% 守卫）。
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: id-family-semantic-migration
|
||||
description: 编号族整族清退/停发 playbook：把一个编号族（字母+数字如保护功能号 L1-x~L5-x、网络条目号 F-*、登记簿旧号 N-x、台架阶段裸形 T1~T3、用例号 TC-*，或中文前缀「卡」+ 数字这类门禁语料里**没有机器识别面**的族）在全仓代码注释、测试、活文档与门禁配置里改成语义短语（含销项删行与逐号换算表入档），或把「不清退」裁定写成硬口径入档。触发语：清退某族编号、编号改成语义名或语义短语、还有多少号可清、残留多少、批次二/批次三/批次五、「卡 0」「卡 0b」「卡 1~12」、销项删行并去除相关编号、id-check 报悬空引用或不可判定超限、不可判定引用绝对数涨点、「这一族不做了」。
|
||||
whenToUse: 用于**整族**处理：先判这一族有没有机器识别面 → 清点存量 → 逐族分类 → 分批派单清退 → 收口 → 回写 docs/编号规范.md 与变更记录。单条待办行销项并写 void 别名用 ledger-row-retire-void-id；某个事实数（页数、叶数、钩子数）变了要同步全仓用 stale-doc-count-sweep；单个文件改名或挪目录用 scripts/rename_ref.py；跑 HEAD 版对照组用 task-worktree 的净室 worktree。这四类不由本技能覆盖，但「涨点归因」一节会用到净室 worktree。
|
||||
whenToUse: 用于**整族**处理：先判这一族有没有机器识别面 → 清点存量 → 逐族分类 → 分批派单清退 → 收口 → 回写 docs/编号规范.md 对应节。单条待办行销项并写 void 别名用 ledger-row-retire-void-id；某个事实数（页数、叶数、钩子数）变了要同步全仓用 stale-doc-count-sweep；单个文件改名或挪目录用 scripts/rename_ref.py；跑 HEAD 版对照组用 task-worktree 的净室 worktree。这四类不由本技能覆盖，但「涨点归因」一节会用到净室 worktree。
|
||||
version: 1.1.0
|
||||
---
|
||||
|
||||
@@ -88,7 +88,7 @@ version: 1.1.0
|
||||
./.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 清点数字按最终实测同步；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。变更记录加一行（含用户裁定原文）。
|
||||
13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏、§9 存量表与批次结果表（只减不增）、§9 清点数字按最终实测同步；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。
|
||||
14. **裁定「不做」也要写成可执行硬口径入档**（不是只划掉一行——「不做」最容易被读成「那还可以继续发号」）：
|
||||
- §4.1.1「已停发」栏新增该族一行：**游标冻结、现存号只减不增、新用例改用语义化测试函数名 + 文档表格行名**，并写清与「允许继续发号」栏为何不打脸；
|
||||
- §9.1 批次段落写明裁定原文与理由（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**；
|
||||
@@ -144,7 +144,7 @@ version: 1.1.0
|
||||
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` **§9.3 逐号换算表**（旧号形态 → 语义短语 → 现行口径出处；本族实测 14 行 = 0、0b、1~12）+ §9 批次段落（裁定原文与逐号结论都落在正文），**写明旧号永久作废、不得重新取走**；
|
||||
- 表内**把形态写成「卡」+ 数字而不复述字面量**：规范本身是门禁语料，复述字面量会把「讲规则的文档」变成自己的引用站点；
|
||||
- **同步叙述**：`AGENTS.md`「文档与图形」的销项条目、`docs/README.md`（例：`数据可信.md = 三项阻塞任务` → 两项）、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零；
|
||||
- **与有识别面族的判别写进同一张表**：能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，**不登记别名**；
|
||||
@@ -206,8 +206,8 @@ version: 1.1.0
|
||||
4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应（只在动过生成器时适用）；`check_doc_links.py --all` 通过。
|
||||
5. `@build`：`BUILD=0`、0 错 0 警、`Program Size` 与改前同数（零行为改动证据，**本回合真跑**）；相关主机组（如 `net_socket 457/457`）全绿。
|
||||
6. 真实 pre-commit 钩子全绿（如 `passed=33 failed=0`）；提交笔内不含他道文件。
|
||||
7. 规范与台账已回写并复跑核数：自己先前写进规范的清点数字要么按最终实测改对，要么标明为动手前基线；「等你裁定」残留 = 0；「不做」裁定已在 §4.1.1 + §9.1 + 变更记录三处落地。
|
||||
8. **无识别面族**：`git grep -nE '卡[ ]*[0-9]' -- .` 无输出（裸跑读 rc）；自建扫描器的站点/文件数与提交正文一致；交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由；§4.1.1 停发行 + §9.3 换算表 + 变更记录三处齐全，换算表行数 = 该族字面量数（实测 14），且写明旧号永久作废、不得重新取走。
|
||||
7. 规范与台账已回写并复跑核数：自己先前写进规范的清点数字要么按最终实测改对，要么标明为动手前基线；「等你裁定」残留 = 0；「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地（原「变更记录」那一处已随 2026-10-28 清流水退场）。
|
||||
8. **无识别面族**：`git grep -nE '卡[ ]*[0-9]' -- .` 无输出（裸跑读 rc）；自建扫描器的站点/文件数与提交正文一致；交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由；§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全，换算表行数 = 该族字面量数（实测 14），且写明旧号永久作废、不得重新取走。
|
||||
9. **二次清洗三道各有实测数**：同句重复短语 0 行、各空格形态先计数后归一（复扫 0）、固定正则残留 0；被代码头注释引用的设计约束章节仍在（`git diff` 里没被动过）。
|
||||
10. **叙述同步**：`AGENTS.md` / `docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md` 里旧口径（「三项」「卡 N」类）实测归零；`ci-artifacts/` 里本次 spec 与中间产物已删。
|
||||
11. 门禁复跑清单齐：`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`@build` 或受影响单测——**每个数字标明是本回合实测**。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: stale-doc-count-sweep
|
||||
description: 全仓陈旧计数同步 playbook——某个事实数（黄金参考页数/张数、菜单树叶数与已绑叶数、字库字数与字形数、提交钩子数等）变了之后：每个数先剔伪命中再双源互证定真值 → 全形态全命中面扫描（含 .pre-commit 钩子显示名与 .dsh/skills 正文）→ 逐条分类（当前态改 / 变更记录只追加当日新行 / 同数不同义不动 / 带日期戳的测量只加「当时」/ 数字对但口径描述错另起一笔）→ 每处先读现文再字面替换并断言命中数 → 全文通读核对各小节 → 提交后再按全部旧形态复扫归零 → 跑门禁分笔提交。
|
||||
description: 全仓陈旧计数同步 playbook——某个事实数（黄金参考页数/张数、菜单树叶数与已绑叶数、字库字数与字形数、提交钩子数等）变了之后：每个数先剔伪命中再双源互证定真值 → 全形态全命中面扫描（含 .pre-commit 钩子显示名与 .dsh/skills 正文）→ 逐条分类（当前态改 / 历史行冻结（2026-10-28 起只剩保留变更记录的 5 篇） / 同数不同义不动 / 带日期戳的测量只加「当时」/ 数字对但口径描述错另起一笔）→ 每处先读现文再字面替换并断言命中数 → 全文通读核对各小节 → 提交后再按全部旧形态复扫归零 → 跑门禁分笔提交。
|
||||
whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「同步一下 / 全仓改一遍 / 这个页数（张数、叶数、字形数、钩子数）不对」、怀疑某个数是伪命中或口径错了（含 notdef 吗、含 ASCII 吗、是张数还是页数）、发现文档数字与实测不符、或同一份文档两节数字/顺序对不上要先核口径时。
|
||||
---
|
||||
|
||||
@@ -54,7 +54,7 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「
|
||||
| 类别 | 判定 | 动作 |
|
||||
|---|---|---|
|
||||
| 当前态陈述 | 描述「现在是多少」 | 改成实测真值 |
|
||||
| 变更记录历史行 | 形如「47 → 53 页」的当日事实 | **原样冻结不回改**；在该文件 §变更记录**追加当日新行**（本仓变更记录表按日期升序 → 新行是**末行**，不是表顶；含判据与实测来源） |
|
||||
| 变更记录历史行 | 形如「47 → 53 页」的当日事实 | **原样冻结不回改**——但这条**只适用于保留变更记录的 5 篇**（台账 / 被别处当唯一证据出处的文档，清单 → `docs/文档规范.md` §5.1）；其余文档的变更记录节已于 2026-10-28 整节删除，**不再追加任何流水行**，数字同步只改**当前态** |
|
||||
| 同数不同义 | `最坏路径 < 40KB` 这类内存/绘制缓冲红线 | **不动**，并在结论里写明「为什么不动」 |
|
||||
| 带日期戳的测量 | 「2026-10-26 实跑 …覆盖当时 40 页中的」 | **不臆改新数**，只补「当时」两字锁口径；新数留待下次实跑回填 |
|
||||
| 数字对但**口径描述错** | 数没错、句子把口径讲错了（实测：写「218 字（含 ASCII/符号，共 313 字形）」，而 `ui_cn_chars.txt` 的 218 个码点**全为非 ASCII**） | **另起一笔只改口径的提交**（`6daa01ae`），不与数字同步混笔；这类命中在任何数字 diff 里都看不见，只能把口径句逐句读一遍 |
|
||||
@@ -118,8 +118,8 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「
|
||||
- **张数与页数互相冒充**：一个 12 行分页页第 2 页要单独拍一张，于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算，别互相顶替。
|
||||
- **只扫 docs/**：漏 `.pre-commit-config.yaml` 钩子 `name:` 显示名里的页数、AGENTS.md 钩子清单、`.dsh/skills/*/SKILL.md` 自带的计数与脚本路径（skill 正文也是命中面：font-regen 的 179/274 本窗最后才改）。
|
||||
- **提交完就收工**：第 7 步的提交后复扫才是把漏网当前态（架构总览 §3）揪出来的那一步；漏了它，仓库里就留下一行「当前态写旧数」直到别人再扫。
|
||||
- **变更记录新行插到表顶**：本仓三份文档（产品需求 §12、架构总览 §10、`docs/门禁说明/ui-golden.md`）的变更记录都按日期升序 → 新行**追加为末行**。插表顶会把首行「初版」挤成第二行，读起来像被改过序。
|
||||
- **历史行被当陈旧值改掉**：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是加当日新行。**历史行被写坏**时按无反引号兜底写法整行重写，别用同样写法再改一遍。
|
||||
- **去已删掉变更记录的文档里「补一行流水」**：2026-10-28 起全仓只有 **5 篇**保留变更记录表（清单 → `docs/文档规范.md` §5.1），计数同步**只改当前态**、过程交给 `git log`，别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行，历史坑照旧：它们的表按日期**升序** → 新行**追加为末行**，插表顶会把首行「初版」挤成第二行。
|
||||
- **历史行被当陈旧值改掉**：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是**只改当前态那几处**、历史行一个字不动（保留变更记录的 5 篇要写台账也只追加、不回改）。**历史行被写坏**时按无反引号兜底写法整行重写，别用同样写法再改一遍。
|
||||
- **照抄用户给的数**：用户说「从 40 扩到 47」也要自己数 `ref/*.bin`；数出来不一定是 47。
|
||||
- **把节点行当叶子数**：42 是 `ui_menu_tree.txt` 的节点行数、33 才是叶子；不读文件头规则就数错（实测把错数写进两份文档，下一轮才自查出来）。
|
||||
- **整文件正则批处理**：第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处 `assert count == expect`。
|
||||
@@ -140,7 +140,7 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「
|
||||
- [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过（无半落地；报错时已 `git diff --stat` 确认零写入）
|
||||
- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、AGENTS.md、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`，逐条在改动清单里出现
|
||||
- [ ] 被改文件已全文通读，同文档各小节与配套 README/清单的顺序、计数、完成状态一致；口径闭合（如 `未绑 = 待做 + 不做`）
|
||||
- [ ] 变更记录：历史行原文未动，只新增当日一行（升为末行）；钩子一增一减写成同一行的两个阶段
|
||||
- [ ] 变更记录：**保留的 5 篇**历史行原文未动；其余文档本轮**零新增流水行**（当前态改完即止）；钩子一增一减这类过程细节写进提交正文，不写进文档
|
||||
- [ ] **提交后**又按全部旧形态复扫一次，当前态残留 = **0**，每条剩余命中都能归类（历史行 / 误报 / 已加「当时」）；发现的漏网当前态已单独补一笔
|
||||
- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过（N 个文档）」；`ci_local.py` / `pre-commit` 全绿（RC=0、`failed=0`）；BOM 与原文件一致、无 `EF BF BD`
|
||||
- [ ] 分笔提交完成，回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由
|
||||
|
||||
@@ -31,7 +31,7 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|
||||
|---|---|---|
|
||||
| 内容页 FAIL，且**有意**改了该页视觉 | 预期变化 | 先肉眼确认新效果正确（窗口模式或 `i1_to_png.py` 出图对照 mockup），再 `.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update` 刷参考，`git diff` 检查 ref/ 变化后随代码提交 |
|
||||
| 内容页 FAIL，但**未**有意改视觉 | bug（缺字/几何漂移/样式回归） | 修代码；**禁止**刷参考掩盖 |
|
||||
| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 在流程文档变更记录登记 |
|
||||
| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 把新值与它的实测来源写进 `docs/UI设计/UI_自动化测试流程.md` 正文常量表（2026-10-28 起不再记流水，见 `docs/文档规范.md` §5.1） |
|
||||
| 菜单回归失败 | 结构断言（白带占比/边框/往返一致） | 按脚本打印的未过断言清单逐项修代码，无参考文件可刷 |
|
||||
|
||||
## 池水位门禁常量（在脚本头部）
|
||||
|
||||
Reference in New Issue
Block a user