1实现原理 · 为什么它能做到
两条自带脚本接力：extract_diagrams.py 用正则从 markdown 抽出 ```mermaid 代码块并编号命名，extract-and-generate.sh 逐文件调用 mermaid-cli(mmdc) 渲染 PNG。
daymade-docs/mermaid-tools/scripts/extract_diagrams.py
mermaid_pattern = r'```mermaid\n(.*?)\n```'
extract_diagrams.py 回看上下文找最近章节标题给图命名（如 01-diagram-name.mmd）；SKILL.md 声明脚本都捆绑在 scripts/ 目录保证可移植。
渲染引擎是 mermaid-cli + 本地 Chrome：脚本以 PUPPETEER_EXECUTABLE_PATH 指到 /usr/bin/google-chrome-stable，并传 puppeteer-config.json 与 -w/-H/-s 尺寸缩放参数。
daymade-docs/mermaid-tools/scripts/extract-and-generate.sh
PUPPETEER_EXECUTABLE_PATH="$CHROME_PATH" mmdc \ -i "$mmd_file" \ -o "$diagram.png" \ --puppeteerConfigFile "$CONFIG_FILE" \ -w "$width" \ -H "$height" \ -s "$SCALE_FACTOR"
即完全本地渲染，不依赖任何在线 mermaid 服务；puppeteer-config.json 带 --no-sandbox/--disable-gpu 等容器常用参数（WSL2 定位）。
高分辨率输出靠环境变量覆盖：MERMAID_WIDTH/HEIGHT/SCALE 默认 1200×800×2，PPT/打印场景可放大到 2400×1800×4 或 SCALE=5。
daymade-docs/mermaid-tools/SKILL.md
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"
SKILL.md 'High-Resolution Output for Presentations' 节的明确示例。
smart sizing 按图名类型猜尺寸：timeline/gantt 拉宽压扁、architecture/system/caching 放大、workflow/sequence/api 加宽，默认 1200×800。
daymade-docs/mermaid-tools/SKILL.md
- **Timeline/Gantt**: 2400×400 (wide and short) - **Architecture/System/Caching**: 2400×1600 (large and detailed)
脚本用 bash 正则 [[ "$diagram" =~ timeline|gantt ]] 实现同一逻辑；命名来自 extract_diagrams.py 的上下文命名，两段配合。
依赖前置校验写进流程：mmdc/google-chrome-stable/python3 缺一即提示查 references/setup_and_troubleshooting.md（含 WSL2 的 Chrome 安装与依赖清单）。
daymade-docs/mermaid-tools/SKILL.md
1. **mermaid-cli**: `mmdc --version` 2. **Google Chrome**: `google-chrome-stable --version` 3. **Python 3**: `python3 --version`
该 reference 还教添加 Google apt 源（dl.google.com）装 Chrome——这是安装期网络动作，见 security。
运行约定是『从 scripts/ 目录执行』：脚本用 ${CLAUDE_SKILL_DIR} 定位，依赖同目录的 extract_diagrams.py 与 puppeteer-config.json 的相对位置。
daymade-docs/mermaid-tools/SKILL.md
cd "${CLAUDE_SKILL_DIR}/scripts" ./extract-and-generate.sh "<markdown_file>" "<output_directory>"
SKILL.md 反复强调（'CRITICAL: Use the bundled extract-and-generate.sh'），不 cd 会因找不到依赖而失败。
2核心能力
01从 markdown 提取全部 mermaid 代码块并按出现顺序编号（01, 02, …）
02生成 .mmd 源文件与高分辨率 .png（可调宽高/缩放比例）
03smart sizing：按图类型（timeline/architecture/workflow/…）自动选画布尺寸
04输出 PNG 校验（非空 + file 类型检查 + identify 尺寸）
05环境变量覆盖画布（MERMAID_WIDTH/HEIGHT/SCALE）适配 PPT/打印
06本地渲染隐私友好：不把图表内容发往在线服务
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | mermaid-cli (mmdc) |
| cli | Google Chrome（/usr/bin/google-chrome-stable，headless 渲染） |
| cli | python3（extract_diagrams.py） |
| network | dl.google.com（setup 参考文档：加 Chrome apt 源并 sudo apt install，一次性安装） |
| cli | file / sort -V / stat / identify(可选)（bash 工具链） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: bash scripts/extract-and-generate.sh（set -e，本地）
- 网络端点: 声明外部网络访问: 运行期无；setup 参考文档含一次性安装动作：wget dl.google.com 公钥 + sudo apt install google-chr
- 本地工作目录: 文件读写与工件输出: 在输出目录写 .mmd/.png（默认 <markdown_file 目录>/diagrams）；mkdir -p 输出目录
审计说明： 。自带本地 bash/python 脚本 + mmdc 本地渲染，运行期零网络外发、零凭证读取、零删除操作；写出的只是用户指定目录的 .mmd/.png。注意点：① 渲染 Chrome 带 --no-sandbox（容器/WSL 惯例，仍是降级项）；② 安装 Chrome 的 sudo/apt 步骤在参考文档里，属环境预置而非运行路径。
5第二遍独立确认
- [ok] 脚本三件套自包含 — extract-and-generate.sh / extract_diagrams.py / puppeteer-config.json 均在 scripts/ 且被 SKILL 逐一引用。
- [ok] mmdc 本地渲染 + PUPPETEER_EXECUTABLE_PATH — 脚本内逐字存在 'PUPPETEER_EXECUTABLE_PATH="$CHROME_PATH" mmdc -i ... --puppeteerConfigFile' 调用。
- [ok] smart sizing 逻辑一致 — SKILL.md 尺寸表与脚本 [[ "$diagram" =~ timeline|gantt ]] 等分支对应。
- [ok] PNG 校验存在 — 脚本 'test -s ... && file ... | grep -q "PNG image"' + identify 尺寸回退分支属实。
- [ok] 运行期无网络 — 三个脚本全文无 curl/wget/requests/http 调用；唯一网络在 setup 参考文档的 dl.google.com apt 安装（sudo，用户主动执行）。
- [ok] 无凭证读取 — 仅读 MERMAID_WIDTH/HEIGHT/SCALE/CLAUDE_SKILL_DIR 等路径/尺寸变量，无 token/secret/key 环境读取。
- [ok] --no-sandbox 浏览器参数 — puppeteer-config.json args 含 --no-sandbox/--disable-setuid-sandbox 等；渲染目标为本地生成的图表 HTML，输入为工作区 markdown。
- [ok] 元数据 — GitHub API：MIT / 1385 stars / pushed 2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678。
6结论
适合： 适合 WSL2/Linux 用户把带 mermaid 图的 markdown 批量出 PNG（文档、PPT、博客配图），要求已装 mmdc + Chrome；也适合需要本地渲染保密的场景。
不适合： 不适合无 Chrome/无法 sudo 安装的环境；不适合对图命名/版式有像素级定制需求的用户（尺寸旋钮有限）；非 mermaid 格式的图（plantuml 等）不在范围。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload mermaid-tools.tar.gz
sha256:
Option B · Copy Guide for Agent3b3522624bae3e65…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.