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，未碰代码与生成器。
2026-10-30 17:26:05 +08:00
parent 48becbfa48
commit e18e52ef7e
3 changed files with 46 additions and 29 deletions
@@ -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 为准，规范条文以该文档为归属。
@@ -90,7 +90,9 @@
   & '.venv\Scripts\python.exe' tools/arch_diagram/gen_frame_svg.py
   ```
   成功输出 `OK <字节> bytes, canvas <W>x<H> -> <路径>`。脚本内置 `ElementTree.fromstring` 自检——**XML 不合法会直接抛错**，不会产出坏图。
-4. **目检**：浏览器打开 `docs/images/*.svg`，确认文字不溢出盒外、框 / 线 / 标签对齐、配色正确。
+4. **目检**：小图浏览器直接打开 `docs/images/*.svg`；要留证或回读细节，走本文 §四 的 **headless 浏览器截图**
+   （渲染命令只在那一节详述）。确认文字不溢出盒外、框 / 线 / 标签对齐、配色正确。
+   **≥20 边的大图**另跑解析式碰撞审计 → **`draw-diagram` skill** §三b（压半格这种问题眼睛看不出来）。
 5. **引用**：在对应 `.md` 里用**相对路径**：根目录下的 md 指向 `docs/images/` 下的图（形如 `![帧格式](images/RemoDispBus帧格式.svg)`）；`docs/UI设计/` 等子目录的 md 则写 `../images/` 前缀的等价写法。
 6. **提交**：脚本（源）+ 生成的 `.svg`（产物）**一起**提交（产物入库，类比生成物 `ui_menu_tab.c`）。

@@ -126,24 +128,35 @@ sequenceDiagram

 ## 四、SVG → PNG（可选）

-默认交付 **SVG**（矢量、可缩放、可 diff、可过门禁）。仅当某个**不渲染 SVG 的查看器**需要位图时再转 PNG：
+默认交付 **SVG**（矢量、可缩放、可 diff、可过门禁）。需要位图（留证、回读细节、贴进不渲染 SVG 的
+查看器）时，用**本机实测可用**的 headless 浏览器渲染：

- **最简单**：浏览器打开 `.svg` → 截图 / 另存为图片。
- **脚本化**：给 `.venv` 装 `cairosvg` 后转（`scale=2` 提高清晰度）：
-   ```powershell
-   & '.venv\Scripts\python.exe' -m pip install cairosvg
-   & '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/RemoDispBus帧格式.svg', write_to='remo.png', scale=2)"
-   ```
+```powershell
+# Edge / Chrome 都不在 PATH 上，按全路径调用（本机实测两者都在；换机先核这两个路径在不在，
+# Chrome 的那条是 C:\Program Files\Google\Chrome\Application\chrome.exe）。
+# --screenshot 必须给绝对 Windows 路径：相对路径报 `Failed to write file …(0x3)` 且 PNG 压根不落盘。
+# --window-size 要跟 SVG 画布一致：忘了改会截出大片空白或裁掉底部脚注。
+& 'C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe' --headless --disable-gpu `
+  --hide-scrollbars --window-size=<W>,<H> --virtual-time-budget=10000 `
+  --screenshot="$env:TEMP\preview.png" "file:///<仓库根绝对路径，正斜杠>/docs/images/RemoDispBus帧格式.svg"
+```

-> PNG 属**本地派生物、不入库**（与 `simulator/tests/ref/*.png` 目检图一致，`.gitignore` 已含
-> `*.png`；注意该目录下作为像素黄金参考的 `.bin` **是入库的**，别顺手一起忽略掉）。
+> **别照旧写法装 `cairosvg`**：`.venv` 里没装（`ModuleNotFoundError`）、`requirements.txt` 里也没有，
+> `rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在（2026-10-30 实测）。真要引入是**动
+> `requirements.txt` 的决定**（第三方依赖统一进那里；另注意门禁 entry 的裸 `python` 不等于 `.venv` →
+> AGENTS.md「Python 环境」），不是画图这一步的隐含前置。零工具兜底仍是「浏览器双击打开 `.svg` 用眼看」，
+> 但半格压框这类问题靠眼看不出来。
+
+> PNG 属**本地派生物、不入库**：忽略规则是 `.gitignore` 里针对目录的三条——`docs/images/*.png`（:132）、
+> `simulator/shot*.png`（:106）、`simulator/tests/ref/*.png`（:127），**不是**一条全库 `*.png`。
+> 另注意 `simulator/tests/ref/` 下作为像素黄金参考的 `.bin` **是入库的**，别顺手一起忽略掉。

 ---

 ## 五、检查清单（提交前）

 - [ ] 生成器输出 `OK … bytes`（无异常 = XML 合法）。
- [ ] 浏览器目检：文字不溢出、框 / 线 / 标签对齐、配色符合调色板。
+- [ ] 目检（小图浏览器打开；要留证走 §四 的 headless 截图）：文字不溢出、框 / 线 / 标签对齐、配色符合调色板。
 - [ ] 引用它的 `.md` 里图片**相对路径**正确（能显示）。
 - [ ] 脚本 + 产物 `.svg` **一并**暂存（产物入库）。
 - [ ] `pre-commit run --files <脚本> <svg> <md>` 全过（无乱码 / 行尾空白 / 编码 OK）。
@@ -1,5 +1,9 @@
 # 16-Bit, 8-Channel, Simultaneous Sampling ADC with Bipolar Inputs

+> **本仓转录留痕（2026-10-30）**：本文由厂商 TPAFE5160 数据手册转录而来（本仓**未入库**该 PDF）。转录时正文里留了 16 处 `![](images/<sha256>.jpg)`，但这些图片**从未随文档入库**（`docs/芯片手册/images/` 里从来没有这些 hash，与 `a6cdebde` 那次「清理芯片手册孤儿图片」也无关——那笔删的 1069 张里一张都不包含）。现已剥成下面的标记，**图题（`Figure N.` / 小节名）与紧邻`<details>` 里的文字描述都还在**，要看图按图题查厂商手册对应页即可。
+>
+> 要补图必须从 PDF 重新提取：本仓 `*.jpg` 由 **Git LFS** 跟踪（`.gitattributes`），落库前先确认本机装了 `git-lfs`；`docs/芯片手册/` 整体豁免 `doc-links`（外部资料、链接形态不受控），所以死链不会由门禁报出来——数一下本文件的标记行数即可自查（应为 16）。
+
 ## Features

 • 8 Simultaneously Sampled Inputs
@@ -33,7 +37,7 @@ The TPAFE5160 can accept ±10-V or ± 5-V true bipolar inputs with a single 5-V
 The zero-latency conversion with high performance also makes the device suitable for industrial automation and control applications.

 Typical Application Circuit
-![](images/2762ffa4db2bc51143440506cde64b960997e1a64f0903688628d389c1dc0a9d.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>flowchart</summary>
@@ -113,7 +117,7 @@ Revision History

 ## Pin Configuration and Functions

-![](images/2aeac05f6d00f0027a9c2e6424449079d7a39a39f2bd6ffad63e39265066bdef.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -251,7 +255,7 @@ All test conditions: $AV_{CC} = 5 V$ , $V_{DRIVE} = 1.7 V$ to 5.5 V, $V_{REF} =
 ## 16-Bit, 8-Channel, Simultaneous Sampling ADC with Bipolar Inputs

 Timing Diagrams
-![](images/ab9ed3131120172d9148c4c79d2214382249a502455cbe52ed18950d9dacc404.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>flowchart</summary>
@@ -271,7 +275,7 @@ graph LR

 Figure 1. CONVST Timing-Reading After a Conversion

-![](images/1d86c3b520eb44528610b7cc420279851cd5fd4d70a7789894d9ae21c278099c.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>flowchart</summary>
@@ -281,7 +285,7 @@ This diagram illustrates the timing relationships and signal flow between a syst

 Figure 2. CONVST Timing-Reading During a Conversion

-![](images/973d1c32a5a7d76853d3c30b0982a2f07c6b64dd6e97b492c94ff8a0ef94c0de.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -319,7 +323,7 @@ V8
 </details>

 Figure 3. Parallel Mode, Separate CS and RD Pulses
-![](images/e4c998e58453c5f862866d953ac1e8da6de4b497a7140586ea5abc631c5e785d.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -339,7 +343,7 @@ Figure 4. CS and RD, Linked Parallel Mode

 ## 16-Bit, 8-Channel, Simultaneous Sampling ADC with Bipolar Inputs

-![](images/684073195c572cb351c311f748a53c26dd1d8ea558bb372c334e20836006ada3.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -367,7 +371,7 @@ t29

 Figure 5. Serial Read Operation (Channel 1)

-![](images/e05c428f982b37656361ac07897016ea34d2e2eb7abe8c40ecde80503a89558c.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -650,7 +654,7 @@ Information in the following application sections is not part of the 3PEAK's com
 ## 16-Bit, 8-Channel, Simultaneous Sampling ADC with Bipolar Inputs

 Tape and Reel Information
-![](images/4749eae1dd6c621d0dbd7c811bca00b8cf3bd13593146bd28dc8bb4182d566ea.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>natural_image</summary>
@@ -660,7 +664,7 @@ Technical line drawing of a wheel with four spokes and a central hub, no text or

 D1:Reel Diameter

-![](images/c36041b46def9706b380365e508554455f46e4e3d89ee675b091679e9df03c06.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>natural_image</summary>
@@ -668,7 +672,7 @@ D1:Reel Diameter
 Pure diagram of a vertical structure with horizontal lines and a central horizontal bar, labeled W1 at the bottom (no text or symbols beyond label)
 </details>

-![](images/2cdaafaa6a256fbc8cd6edba7b762af379531acb481fc31a71fd939ac81b38d1.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -691,7 +695,7 @@ LQFP10x10-64

 Package Outline Dimensions
 QP5(LQFP10X10-64-A)
-![](images/9ce7a4caaa2788c2c2561d9e7d69c3d74fccea3315ea0ee307ae562847d01c1b.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -705,7 +709,7 @@ E1
 E
 </details>

-![](images/a1b45902cfbba60871cce6181733e1b136e588a028df9303c8f8c6fd40b237f3.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>
@@ -719,7 +723,7 @@ METAL

 SECTION N-N

-![](images/f69b0c5e472b09735358baad95d78c77abc6caffba1dec62b7946792623e25af.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>natural_image</summary>
@@ -727,9 +731,9 @@ SECTION N-N
 Pure electrical circuit lines without any symbols
 </details>

-![](images/c42cbf274e4b9daea53dd9192a21043b96bfd4820fc19d1793a23e96be4851ce.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

-![](images/8b28c815d6a32e3c1f1c7ced71fb8ccb1eb0e1794ad7a8529b5c410ecb696b53.jpg)
+*（手册配图未入库：按上方图题查厂商数据手册对应页）*

 <details>
 <summary>text_image</summary>