Commit Graph

2 Commits

Author SHA1 Message Date
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
wandering1 045ca7f688 docs(配图): 端到端链路鸟瞰进生成器体系,补大图碰撞审计判据
把 archify 出的交互架构图落回仓内可复现形态,避免 docs/ 里出现「没有生成器的
SVG」:

- 新生成器 tools/arch_diagram/gen_arch_endtoend_svg.py → docs/images/架构总览_
  端到端链路.svg(42 框 / 37 边 / 5 条纵带,线型分数据·命令·屏障心跳三类);
  数据全部内嵌在 .py 里(generated-fresh 只把单个 gen_*.py 拷进临时目录重跑,
  外部 JSON 输入会 rc≠0 假红),SVG 内不含时间戳/commit/绝对路径
- docs/架构设计/项目架构总览.md 新增 §1.3 挂图并写清与 §1 分层图的分工
  (那张答「谁在哪一层」,这张答「一条数据走到底穿过谁」;纵带只是列分组,
  依赖方向仍以 §1.1 表与 layer-deps 门禁为准),版本 v1.2 → v1.3
- 两处生成器清单登记:tools/arch_diagram/README.md 脚本一览、
  docs/架构设计/图形绘制流程.md 的选型表与产物对照表
- draw-diagram skill 新增 §三b(大图碰撞审计判据 + 两条几何纪律)+
  reference/svg-collision-audit.py(拷进 ci-artifacts 用,刻意不进 tools/)

本窗实测(都已写进 skill):42 框 37 边的图缩略目检看着干净,解析式审计一眼
报出 23 条——边标签文字盒压到节点框会被后画的节点白底吃掉半个字(「串行执行」
渲染成「行执行」);根因是同行两框走了「同轴加一段走廊」的通用规则,产出退化
四点折线,把标签落点推到第一半中点。修法:同轴且已对齐直接返回两点线,标签
落点改按总弧长取 50%。

零余量第二遍(用生成器自己的 Box/route/label_at 真值扫,框不膨胀不内缩)又抓到
两处近失:「TRGO 触发」「帧 B 下发」与相邻框只剩 0.7px / 1.5px,缩成「TRGO」
「帧 B」后最紧余量升到 3.5px;同一遍还纠正了审计器自己的错——`hi > y0` 误写成
`hi > x0` 凭空报 3 条穿框,差点重排三条边的走线,所以判据里加了「先验审计器
本身再信 0 条」。

自查:连跑两次产物 sha1 不变;scripts/check_generated_fresh.py rc=0(25 生成器
/ 21 一致 / 4 在只减不增基线内);碰撞审计 rc=0(0 条);生成器无 OVERFLOW;
doc-links --sections-strict 逐篇 rc=0;mermaid-syntax / nested-comment /
skill-size / bom-drift 无新发;改动文件字节体检干净;/keil-build 0 错 0 警。
2026-10-30 15:59:24 +08:00