From e18e52ef7e2512b6686ba1ff4e2ec1d58b7b9aee Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Fri, 30 Oct 2026 17:26:05 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E8=8A=AF=E7=89=87=E6=89=8B=E5=86=8C/?= =?UTF-8?q?=E9=85=8D=E5=9B=BE=E6=B5=81=E7=A8=8B):=20=E5=89=A5=2016=20?= =?UTF-8?q?=E5=A4=84=E4=BB=8E=E6=9C=AA=E5=85=A5=E5=BA=93=E7=9A=84=E6=AD=BB?= =?UTF-8?q?=E5=9B=BE=E5=BC=95=E7=94=A8=EF=BC=8CSVG=E2=86=92PNG=20=E6=94=B9?= =?UTF-8?q?=E6=88=90=20headless=20=E5=AE=9E=E6=B5=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 两条存量收口（genlist 交付报告点名的那两条，用户裁定「收这两条」）。 一、docs/芯片手册/TPAFE5160.md：16 处 `![](images/.jpg)` 的图 从未随文档入库——13 篇手册共 701 处引用，只有这篇缺；这些引用是 ad154b2f 把转录稿连正文一起入库时就带着的，16 个 hash 在全库 git 历史里一处都没有，与 a6cdebde 那次删 1069 张孤儿图片无关（那批里 一张都不包含）。本仓未入库厂商 PDF，无从重新提取，故剥成统一标记 并在文件头留痕：图题（`Figure N.` / 小节名）与紧邻 `
` 的 文字描述都保留，要看图按图题查手册对应页；补图须先装 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，未碰代码与生成器。 --- .dsh/skills/draw-diagram/SKILL.md | 4 ++-- docs/架构设计/图形绘制流程.md | 35 ++++++++++++++++++++---------- docs/芯片手册/TPAFE5160.md | 36 +++++++++++++++++-------------- 3 files changed, 46 insertions(+), 29 deletions(-) diff --git a/.dsh/skills/draw-diagram/SKILL.md b/.dsh/skills/draw-diagram/SKILL.md index fab9ff32..ea5c716b 100644 --- a/.dsh/skills/draw-diagram/SKILL.md +++ b/.dsh/skills/draw-diagram/SKILL.md @@ -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 为准，规范条文以该文档为归属。 diff --git a/docs/架构设计/图形绘制流程.md b/docs/架构设计/图形绘制流程.md index cbb22178..534fb37b 100644 --- a/docs/架构设计/图形绘制流程.md +++ b/docs/架构设计/图形绘制流程.md @@ -90,7 +90,9 @@ & '.venv\Scripts\python.exe' tools/arch_diagram/gen_frame_svg.py ``` 成功输出 `OK <字节> bytes, canvas x -> <路径>`。脚本内置 `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=, --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 <脚本> ` 全过（无乱码 / 行尾空白 / 编码 OK）。 diff --git a/docs/芯片手册/TPAFE5160.md b/docs/芯片手册/TPAFE5160.md index 6a5985fa..56509334 100644 --- a/docs/芯片手册/TPAFE5160.md +++ b/docs/芯片手册/TPAFE5160.md @@ -1,5 +1,9 @@ # 16-Bit, 8-Channel, Simultaneous Sampling ADC with Bipolar Inputs +> **本仓转录留痕（2026-10-30）**：本文由厂商 TPAFE5160 数据手册转录而来（本仓**未入库**该 PDF）。转录时正文里留了 16 处 `![](images/.jpg)`，但这些图片**从未随文档入库**（`docs/芯片手册/images/` 里从来没有这些 hash，与 `a6cdebde` 那次「清理芯片手册孤儿图片」也无关——那笔删的 1069 张里一张都不包含）。现已剥成下面的标记，**图题（`Figure N.` / 小节名）与紧邻`
` 里的文字描述都还在**，要看图按图题查厂商手册对应页即可。 +> +> 要补图必须从 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) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
flowchart @@ -113,7 +117,7 @@ Revision History ## Pin Configuration and Functions -![](images/2aeac05f6d00f0027a9c2e6424449079d7a39a39f2bd6ffad63e39265066bdef.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -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) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
flowchart @@ -271,7 +275,7 @@ graph LR Figure 1. CONVST Timing-Reading After a Conversion -![](images/1d86c3b520eb44528610b7cc420279851cd5fd4d70a7789894d9ae21c278099c.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
flowchart @@ -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) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -319,7 +323,7 @@ V8
Figure 3. Parallel Mode, Separate CS and RD Pulses -![](images/e4c998e58453c5f862866d953ac1e8da6de4b497a7140586ea5abc631c5e785d.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -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) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -367,7 +371,7 @@ t29 Figure 5. Serial Read Operation (Channel 1) -![](images/e05c428f982b37656361ac07897016ea34d2e2eb7abe8c40ecde80503a89558c.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -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) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
natural_image @@ -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) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
natural_image @@ -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)
-![](images/2cdaafaa6a256fbc8cd6edba7b762af379531acb481fc31a71fd939ac81b38d1.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -691,7 +695,7 @@ LQFP10x10-64 Package Outline Dimensions QP5(LQFP10X10-64-A) -![](images/9ce7a4caaa2788c2c2561d9e7d69c3d74fccea3315ea0ee307ae562847d01c1b.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -705,7 +709,7 @@ E1 E
-![](images/a1b45902cfbba60871cce6181733e1b136e588a028df9303c8f8c6fd40b237f3.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image @@ -719,7 +723,7 @@ METAL SECTION N-N -![](images/f69b0c5e472b09735358baad95d78c77abc6caffba1dec62b7946792623e25af.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
natural_image @@ -727,9 +731,9 @@ SECTION N-N Pure electrical circuit lines without any symbols
-![](images/c42cbf274e4b9daea53dd9192a21043b96bfd4820fc19d1793a23e96be4851ce.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）* -![](images/8b28c815d6a32e3c1f1c7ced71fb8ccb1eb0e1794ad7a8529b5c410ecb696b53.jpg) +*（手册配图未入库：按上方图题查厂商数据手册对应页）*
text_image