Files
STM32F4-Base/.dsh/skills/stale-doc-count-sweep/reference/steps.md
T
wandering1 e4981aa2f6 refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
2026-11-16 19:38:27 +08:00

9.8 KiB
Raw Blame History

Steps(自 SKILL.md 外置)

本文由 stale-doc-count-sweep 的 SKILL.md「Steps」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。

  1. 实测真值:先剔伪命中,再双源互证(不抄用户口述、不抄另一处文档)。逐数走上面那张表;两个来源对不上时先找分歧根因(把全部命中逐条打印出来看),不要取第一个、不要取平均,并在结论里写明分歧与取舍(实测:菜单 #page= 计数 29 对 注册表 28,根因是头部注释示例行)。

    cd "<repo>"
    ls simulator/tests/ref/shot_*.bin | wc -l                     # 张数(判据 = 入库实数)
    awk '/^PAGES = \[/,/^\]/' simulator/tests/check_content_pages.py | grep -cE '^ *\("'   # 页数(第二个来源,两者必须一致)
    grep -n '#page=' ui_menu_tree.txt | head -3                    # 先看首条是不是注释示例行,再定叶数
    grep -rn 'UI_PAGE_MAP_COUNT' Drivers/BSP/UI/ui_page_registry.h  # 已绑叶数(生成物)
    grep -c '\.bitmap_index' Drivers/BSP/UI/ui_font_cn_12.c         # 314 = 含 notdef;字形 = 该数 - 1
    & '.venv\Scripts\python.exe' -c "import yaml;d=yaml.safe_load(open('.pre-commit-config.yaml',encoding='utf-8'));print(sum(len(r['hooks']) for r in d['repos']))"   # 钩子数口径
    

    ⚠ 权威脚本输出乱码时(check_font_charset.py 在 GBK 代码页下整行打印成 U+FFFD 替换字符串 + : PASS,数字全读不出来),改为直接数源文件里符号出现次数(.bitmap_index / .range_start / 码点唯一化)——不许臆读乱码,也不许因此退回去抄文档里的旧数。

  2. 全形态 + 全命中面扫描。一个数一次列出它全部历史形态,别只扫当前旧值:本轮 = 122/217、179/274、185/280、47 → 53、53 → 60、PAGES = 53、UI_PAGE_MAP_COUNT = 22、已绑 22 叶、未绑 11、内容页 53 页。

    grep -rn --include=*.md --include=*.py --include=*.yaml --include=*.txt --include=*.c --include=*.h \
      -E '122 唯一字|217 字形|179 汉字|274 字形|185 唯一字|280 字形|47 → 53|53 → 60|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22|已绑 22|未绑 11' . \
      | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
    

    命中面比「文档」宽,至少包含:docs/**、AGENTS.md(入口级计数:提交门禁节的钩子数等)、.pre-commit-config.yaml(钩子 name: 显示名内嵌页数:name: UI 像素回归(菜单 8 状态 + 内容页 60 页 黄金参考) 就是命中点)、scripts/*.py、simulator/**/README.md、以及 .dsh/skills/*/SKILL.md(本窗 font-regen 正文自带 179/274 计数,直到 step 150 才发现;编号门禁退役那轮 id-family-semantic-migration、task-worktree 两个 skill 正文与 scripts/README.md 同样是引用面)。

    先列出 文件:行:全文,判定前必须看整行——cut -c1-120 会截掉后半句(那里常写着日期戳或口径)。

  3. 逐条分类,五类各走各的路(本 playbook 的核心,别用一条规则套全部命中):

    类别 判定 动作
    当前态陈述 描述「现在是多少」 改成实测真值
    变更记录历史行 形如「47 → 53 页」的当日事实 原样冻结不回改——但这条只适用于保留变更记录的 5 篇真台账(台账 / 被别处当唯一证据出处的文档,清单 → docs/文档规范.md §5.1)与 scripts/archive/ 归档;其余文档没有变更记录节,不再追加任何流水行,数字同步只改当前态
    同数不同义 最坏路径 < 40KB 这类内存/绘制缓冲红线 不动,并在结论里写明「为什么不动」
    带日期戳的测量 「2026-10-26 实跑 …覆盖当时 40 页中的」 不臆改新数,只补「当时」两字锁口径;新数留待下次实跑回填
    数字对但口径描述错 数没错、句子把口径讲错了(实测:写「218 字(含 ASCII/符号,共 313 字形)」,而 ui_cn_chars.txt 的 218 个码点全为非 ASCII) 另起一笔只改口径的提交(6daa01ae),不与数字同步混笔;这类命中在任何数字 diff 里都看不见,只能把口径句逐句读一遍

    拿不准就回到第 2 步把整行打印出来再判;判错历史行 = 把当天事实改成假账。

  4. 每处先读现文,再逐条字面替换并断言命中数(弃用整文件正则批处理)。本窗两度返工都是没先读现文:step 45 断言 HIT 0 抛错(目标串与现文不一致),step 44 是脚本语法错。脚本写成临时文件再跑(内嵌 heredoc/模板字符串里的反引号会截断整脚本),按字节替换以保 BOM 与行尾不动:

    import pathlib, sys
    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
    JOBS = [  # (文件, old, new, 期望命中数)
        ('README.md', '内容页 53 页黄金参考', '内容页 60 页黄金参考', 1),  # 历史实例:当时该文件里确有这一行
        ('.pre-commit-config.yaml', '内容页 53 页 黄金参考', '内容页 60 页 黄金参考', 1),
        ('docs/架构设计/项目架构总览.md', '122 字/217 字形', '218 字/313 字形', 1),
        ('docs/UI设计/UI_自动化测试流程.md', '文本断言 **310 条**、覆盖 40 页中的', '文本断言 **310 条**、覆盖当时 40 页中的', 1),
    ]
    for path, old, new, expect in JOBS:
        p = pathlib.Path(path); raw = p.read_bytes()
        o, n = old.encode('utf-8'), new.encode('utf-8')
        got = raw.count(o)
        assert got == expect, f'{path}: 命中 {got},期望 {expect}(未写入)'
        assert o != n, f'{path}: old 与 new 相同'
        p.write_bytes(raw.replace(o, n))
        print(f'OK {path}: {old} -> {new} x{got}')
    

    每行打印 old -> new xN,收口时这串输出就是「改了哪几处」的账。脚本报错/没编译过,先 git diff --stat 确认零写入再换写法(不要在半落地状态上叠改)。

    • 反引号:TS 侧先用可见占位符(如 ~TB~)写文本,落盘前再还原成真反引号 —— const BT = String.fromCharCode(96); const q = s => s.split(TOKEN).join(BT)(本窗实测:直接把带反引号的串塞进模板字符串/heredoc,整批零落地或把变更记录行写坏)。用 tools.edit 批量改时同样先 await tools.read 现文再传 old_string;批量里若某条 old_string 与 new_string 相同会报 must differ —— 只有该条作废、其余已落盘,别整批重跑。
    • 历史行被写坏(反引号及紧随其后的字符经工具传递被吞 → 变更记录行只剩半行、尾部出现 ?? 这类残迹):立刻按无反引号兜底写法整行重写——裸词 accident / oper / alarm / start / yk、页面绑定写成不带反引号的 #page=——而不是拿同样带反引号的串再改一遍(实测连返工三次:step 81→82→83→85)。
  5. 一笔只装一类事。数字同步一笔(cbb4fdb8:11 处 + 变更记录一行);口径更正另起一笔(6daa01ae);提交后复扫逮到的漏网当前态再补独立一笔(11d60057)。钩子一增一减写成一个当日行的两个阶段(51 → 52 加 id-check-new、随即 52 → 51 摘 id-check),别写两行互相打脸。提交说明如实写(「先认一笔自己的错:上一笔的未绑 21 叶是探针错」),别把口径修正包装成「补充说明」。

  6. 被改文件全文通读,核对其余小节——不是只看 diff。同一文档内互相引用的小节必须一致(本窗产品需求:§2.4 立项未排、§5.14 FR-SOE-3、§8.2 绑定现状、§8.3 已绑分页表、§9.1 差距表、§9.2 顺序表六处同时引用这四个数;当窗口的 docs/任务规划/README.md 就同时有两处表引用同一批数,后来合成一张)。若发现上一笔自己写进文档的数口径就错了,明确认错并改正,同时把可复核的重算方法写进文档(「按缩进判叶子:有更深缩进后继者即非叶子」),防止再错。

  7. 提交后再复扫一遍(收尾硬步骤,不许省,也不许只在提交前扫)。按第 2 步的全部旧形态整仓再扫一次,逐条分类为 当前态 / 历史行 / 同数不同义:本窗 cbb4fdb8 提交后复扫得 14 条命中,12 条以上都在变更记录历史行(47 → 53、53 → 60、122/217 冻结),唯一残留的当前态命中是 docs/架构设计/项目架构总览.md §3「界面层」那行 → 单独补一笔 11d60057。说不出归属的就是漏改。

    grep -rn -E '22 叶|未绑 11|11 叶|53 页|122 唯一字|217 字形|185 唯一字|280 字形|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22' \
      . | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
    
  8. 跑门禁、分笔提交(git commit 属 Ask first,须用户明确指示后再做):

    & '.venv\Scripts\python.exe' scripts/check_doc_links.py --all --sections-strict   # 期望「文档路径检查通过(N 个文档)」
    & '\.venv\Scripts\python.exe' scripts/archive/id_gate/check_ids_new.py --range A..B   # 编号形态普查(两道门禁 2026-10-28 / 2026-10-29 都已退役,不再是提交钩子)
    & '.venv\Scripts\python.exe' scripts/ci_local.py                                    # 或 pre-commit run --files <被改文件>
    

    PowerShell 形态把 ./.venv/Scripts/python.exe 换成 & '.venv\Scripts\python.exe'。提交信息一律 git commit -F <UTF-8 无 BOM 文件>,别用 -m(中文长标题易超 100 字符、终端代码页会转码);标题 ≤100、正文每行 ≤80(实测把正文压到 66/78 字符才过 gitlint)。