全部技能 / 基础工具与工作流 / mermaid-tools
基础工具与工作流 · daymade/claude-code-skills

mermaid-tools

Extracts Mermaid diagrams from markdown files and generates high-quality PNG images using bundled scripts. Activates when working with Mermaid diagrams, converting diagrams to PNG, extracting diagrams from markdown, or processing markdown files with embedded Mermaid code.

风险提醒：蓝色 · 知晓即可AI 侦查报告
作者 daymadeGitHub daymade/claude-code-skills ↗Stars 1385许可 MIT（仓库根 LICENSE；Copyright (c) 2025 daymade；GitHub API spdx MIT）commit d5c4678cb5
agent 宿主通常会约束 skill 执行权限；风险提醒为 AI 侦查观点，不构成质量或安全保证。第三方 skill 仅作拆解与展示，安装使用风险自负，版权归原作者。

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外部依赖

类型依赖
climermaid-cli (mmdc)
cliGoogle Chrome（/usr/bin/google-chrome-stable，headless 渲染）
clipython3（extract_diagrams.py）
networkdl.google.com（setup 参考文档：加 Chrome apt 源并 sudo apt install，一次性安装）
clifile / sort -V / stat / identify(可选)（bash 工具链）

4风险提醒 风险提醒：蓝色 · 知晓即可

风险提醒：蓝色 · 知晓即可
  • --no-sandbox 渲染不可信图内容 — mermaid 代码以本地 HTML 注入 Chrome（无沙箱）渲染；若 markdown 来自不可信来源，理论上有浏览器侧请求/利用面。建议只处理可信输入。
  • 环境假设偏 WSL2/Linux — Chrome 硬编码 /usr/bin/google-chrome-stable；macOS/Windows 原生需改路径或装 WSL2，参考文档亦以 WSL2 为主线。
  • 正则提取脆弱 — extract_diagrams.py 用非贪婪正则匹配 ```mermaid 块，异常围栏（如嵌套、无闭合）会导致漏提；复杂文档需人工复核输出。
  • 安装 Chrome 需要 sudo + 外部 apt 源 — setup 文档引导添加 dl.google.com 源并以 sudo 安装——环境预置动作，执行时需用户知情。
风险提醒：蓝色，知晓即可。自带本地 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结论

  • 完全本地渲染：图表内容不出机器，适合涉密/内网文档。
  • 脚本自包含 + 上下文自动命名，批量 markdown→PNG 一条命令走完。
  • 高分辨率/画布控制开放但克制（3 个 env 旋钮），适配 PPT 与打印。
  • 依赖检查前置 + 详细 WSL2 排障参考，环境问题有文档兜底。
    • 适合：适合 WSL2/Linux 用户把带 mermaid 图的 markdown 批量出 PNG（文档、PPT、博客配图），要求已装 mmdc + Chrome；也适合需要本地渲染保密的场景。
    不适合：不适合无 Chrome/无法 sudo 安装的环境；不适合对图命名/版式有像素级定制需求的用户（尺寸旋钮有限）；非 mermaid 格式的图（plantuml 等）不在范围。
    安装 agent 直装可复制
    ① 本站镜像 更新 2026-09-09
    方式 A · 人下载镜像包下载 mermaid-tools.tar.gz
    sha256: 3b3522624bae3e65…
    方式 B · JSON 格式安装指南，复制给 agent
    安装指南
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② 上游 GitHub · 原始来源
    能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗
    本页镜像锁定 commit d5c4678cb5；上游为实时仓库。
    来源信息 GitHub 原始
    作者 / 仓库daymade / daymade/claude-code-skills
    原始 GitHubdaymade/claude-code-skills ↗
    Stars1385
    最近推送2026-09-09
    本 skill commitd5c4678cb5
    许可MIT（仓库根 LICENSE；Copyright (c) 2025 daymade；GitHub API spdx MIT）
    本站信息
    收录日期2026-09-06
    分类基础工具与工作流
    侦查报告AI 侦查 · 2 遍 · 2026-09-06
    本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。
    同分类邻近
    grill-me追问访谈以打磨计划或设计grill-with-docs追问式访谈打磨计划并产出文档handoff压缩对话为交接文档给代理teach在工作区内教授用户新技能概念to-spec将对话转成规格并发布工单to-questionnaire将无法解答的决定转成他人问卷wait-what停下并重新表达上一条信息writing-for-agents为代理编写技能与指令文档