docs(芯片手册/配图流程): 剥 16 处从未入库的死图引用,SVG→PNG 改成 headless 实测

两条存量收口(genlist 交付报告点名的那两条,用户裁定「收这两条」)。

一、docs/芯片手册/TPAFE5160.md:16 处 `![](images/<sha256>.jpg)` 的图
从未随文档入库——13 篇手册共 701 处引用,只有这篇缺;这些引用是
ad154b2f 把转录稿连正文一起入库时就带着的,16 个 hash 在全库 git
历史里一处都没有,与 a6cdebde 那次删 1069 张孤儿图片无关(那批里
一张都不包含)。本仓未入库厂商 PDF,无从重新提取,故剥成统一标记
并在文件头留痕:图题(`Figure N.` / 小节名)与紧邻 `<details>` 的
文字描述都保留,要看图按图题查手册对应页;补图须先装 git-lfs
(`*.jpg` 走 LFS 跟踪)。`doc-links` 对 `docs/芯片手册/` 整体豁免,
这类死链门禁永不报,自查方法是数标记行(应为 16)。

二、docs/架构设计/图形绘制流程.md:§3.1 第 4 步与 §四 原先写的
「浏览器打开 SVG」与「给 `.venv` 装 cairosvg 转 PNG」在本机走不通
(cairosvg 不在 `.venv` 也不在 `requirements.txt`,`rsvg-convert` /
`inkscape` / `magick` 都不存在),改成 headless Edge/Chrome 全路径
调用,并把两条实测坑写死:`--screenshot` 必须给绝对 Windows 路径、
`--window-size` 要跟画布一致。PNG 不入库的口径按 `.gitignore` 里
实际那三条目录规则列出,不再笼统写成「已含 `*.png`」。

`draw-diagram` skill 侧同步:撤掉「口径未与权威文档同步」那条挂账
说明,陷阱条目改指已对齐的命令,并写明改渲染命令时文档与 skill 两处
一起改(命令只在 §四 详述,skill 留判据指针)。

自查:`check_doc_links --sections-strict` 三篇 rc=0;skill-size
18841/65536 安全;`check_generated_fresh` PASS(26 生成器 / 22 一致
/ 4 存量基线);`check_mermaid --all`、`check_bom_drift --all` 均
rc=0;三篇字节卫生干净(LF / 无 BOM / 无 U+FFFD / 无行尾空格 /
末行单 LF)。本笔纯文档与 skill,未碰代码与生成器。
This commit is contained in:
2026-10-30 17:26:05 +08:00
parent 48becbfa48
commit e18e52ef7e
3 changed files with 46 additions and 29 deletions
+2 -2
View File
@@ -190,7 +190,7 @@ sha1sum docs/images/<主题>.svg
## 陷阱(本窗实测)
- **照着现文 / `docs/架构设计/图形绘制流程.md` §四 跑 `pip install cairosvg` 或 `rsvg-convert`**:这台机器上没有(前者 `ModuleNotFoundError`、后者根本没有这个命令)→ 先按 §三探测,改用 headless Chrome/Edge。**别在没渲染出 PNG 的情况下声称"已目检"。**
- **想装渲染器再转 PNG**:`cairosvg` 不在 `.venv`(`ModuleNotFoundError`)、`requirements.txt` 里也没有,`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge(权威命令在 `docs/架构设计/图形绘制流程.md` §四,2026-10-30 已同步成这套,别再往回写)。**没真渲染出 PNG 的情况下不要声称"已目检"。**
- **`--screenshot=ci-artifacts/ladder.png`(相对路径)** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`,PNG 压根没落盘;换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因(实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句),排查时两条都排。
- **只做预检 + 缩略目检就收工(大图)**:`check_fit` 归零、PNG 看着干净,仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签;大图必须走 §三b 的解析式审计。
- **只做预检就收工**:`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见;反过来只目检不预检,脚注溢出就得靠眼睛反复量。**两者都要 0**。
@@ -208,4 +208,4 @@ sha1sum docs/images/<主题>.svg
- [ ] 引用它的 `.md` 相对路径正确(根目录 `images/`,子目录 `../images/`);`tools/arch_diagram/README.md`「产物清单」已加行,「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对(**别抄旧行号**,行号一漂整列就废)。
- [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存;`pre-commit run --files …` 全过(无乱码 / 行尾空白 / 编码 OK)。
> **TODO(口径未与权威文档同步)**:`docs/架构设计/图形绘制流程.md` §3.1 第 4 步「目检:浏览器打开 SVG」与 §四「给 `.venv` 装 cairosvg 转 PNG」在 Windows 上按本 skill 的实测是走不通的。该文档是规范归属(AGENTS.md:同一事实只在一处详述),采纳 §三 / §五 时应把这两段同步过去;目前两处不一致,**做图以本 skill 的实测命令为准,规范条文以该文档为归属**。
> **与规范文档的分工(2026-10-30 已对齐)**:`docs/架构设计/图形绘制流程.md` 是规范归属(AGENTS.md:同一事实只在一处详述),本 skill 是执行侧。该文档 §3.1 第 4 步与 §四 原先写的「浏览器打开 SVG / 给 `.venv` 装 cairosvg 转 PNG」在本机走不通,已同步成 headless Edge/Chrome 那套(命令只在 §四 详述,本 skill §三 留判据指针);**改渲染命令时两处一起改**——做图判据以本 skill 为准,规范条文以该文档为归属。