wandering1
88601422c3
17 篇文档的变更记录（含修订记录、带编号与中文序号标题）节里只剩一句 「不再记流水账」的占位话，整节删掉，连带它前面的分隔线。 仍保留真台账的只有 5 篇（看门狗 / 配置文件设计 / RAM 预算台账 / 内容页架构 / 本地工具路径方案），外加 scripts/archive 归档区。 份数口径改成可复跑的普查：文档规范 §5.1 补自查命令， stale-doc-count-sweep 的速查表与陷阱各加一条——只 grep 裸标题会漏 带编号与中文序号的两种写法，实测 5 篇只数得出 3 篇，差点据此把 全仓正确的份数改错。 门禁：逐篇与全量 check_doc_links 除 simulator/SDL2 联接假红外 0 问题； skill-size rc=0；表格列数与字节体检相对 HEAD 零新增问题。
5.0 KiB
5.0 KiB
Pitfalls（自 SKILL.md 外置）
本文由 stale-doc-count-sweep 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
- 把伪命中计进真值：
grep '#page='的首条是菜单文件头部注释里的示例行，29 里含它；真值是注册表UI_PAGE_MAP_COUNT的 28。任何「数出现次数」式计数，先打印全部命中逐条看，剔注释行/模板行/示例行。 - 字形数没剔 notdef：
.bitmap_index314 条里第 1 条是 notdef，字形数是 313；照抄 314 就把占位符当成了字形。 - 数字对但口径描述错：218 这个数两处都对，错在「含 ASCII/符号」这句口径（实测 218 个码点全为非 ASCII）。它不进任何数字 diff，只能逐句读口径句；且必须另起一笔，混进数字同步那笔会让 review 者以为只是顺手改措辞。
- 权威脚本乱码就臆读或退回抄文档：Windows 代码页下
font-charset的整行输出退化成 U+FFFD 替换字符时，改数源文件符号出现次数，别猜、别抄旧文档。 - 钩子数用
grep声明行：多算一条注释掉的候选钩子（51 变 52）；反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数，且要与 AGENTS.md、docs/门禁说明/README.md§2 标题、ci_local.py实跑 passed+failed+skipped 三数同源。 - 张数与页数互相冒充：一个 12 行分页页第 2 页要单独拍一张，于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算，别互相顶替。
- 数篇数只 grep 裸标题：
^## 变更记录漏掉## 6. 变更记录、## 九、变更记录、## 修订记录三种写法 → 篇数直接少数一半，拿这个错数去"同步"全仓就是把对的改成错的（2026-10-29 实测：5 篇真台账只数出 3 篇，改到第 10 处才发现）。普查一律grep -rn "^## " docs scripts再看标题，或直接读docs/文档规范.md§5.1 那行的例外清单。 - 只扫 docs/：漏
.pre-commit-config.yaml钩子name:显示名里的页数、AGENTS.md 钩子清单、.dsh/skills/*/SKILL.md自带的计数与脚本路径（skill 正文也是命中面：font-regen 的 179/274 本窗最后才改）。 - 提交完就收工：第 7 步的提交后复扫才是把漏网当前态（架构总览 §3）揪出来的那一步；漏了它，仓库里就留下一行「当前态写旧数」直到别人再扫。
- 去已删掉变更记录的文档里「补一行流水」：2026-10-29 起全仓只剩 5 篇真台账保留变更记录表（清单 →
docs/文档规范.md§5.1），外加scripts/archive/归档；其余文档没有这一节。计数同步只改当前态、过程交给git log，别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行，历史坑照旧：它们的表按日期升序 → 新行追加为末行，插表顶会把首行「初版」挤成第二行。 - 历史行被当陈旧值改掉：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是只改当前态那几处、历史行一个字不动（保留变更记录的 5 篇真台账要写台账也只追加、不回改）。历史行被写坏时按无反引号兜底写法整行重写，别用同样写法再改一遍。
- 照抄用户给的数：用户说「从 40 扩到 47」也要自己数
ref/*.bin；数出来不一定是 47。 - 把节点行当叶子数：42 是
ui_menu_tree.txt的节点行数、33 才是叶子；不读文件头规则就数错（实测把错数写进两份文档，下一轮才自查出来）。 - 整文件正则批处理：第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处
assert count == expect。 - 反引号截断：脚本里含
ui-golden、#page=这类反引号时，经 TS 模板字符串/内嵌 heredoc 传递会被截断，表现为「整批零落地」或「历史行写坏」。落成脚本文件再执行，或用chr(96)/String.fromCharCode(96)拼。 - 只改记得的那节：上一笔只改 §2 与开篇、漏改 §1，用户当场问出「§1 说 16 叶、§2 说剩 3 项，自相矛盾」。改完必须全文通读同一文档所有小节。
- 误报跟着改：「< 40KB」是绘制缓冲红线，与页数无关。
- 带日期戳的测量臆改新数：「2026-10-26 实跑 …覆盖 40 页」改成 47 就是把历史测量冒充现值；只加「当时」。
- 用截断的 grep 输出判定：
cut -c截掉的后半句常含日期戳/口径，据此分类必错。 - 新写文本别再造编号：两道编号门禁都已退役（全库八项校验 2026-10-28、只查新增行 2026-10-29，脚本与白名单在
scripts/archive/id_gate/），撞号不再有机器报警，只剩规范与评审——所以这批文本的形态自查要自己做（docs/编号规范.md§1 三句；要机器帮忙就手工跑scripts/archive/id_gate/check_ids_new.py --worktree）。