mermaid-skill

Mermaid 图表

生成 .mmd 文本文件，并使用 mmdc（本地）或 Kroki API（无需安装）导出为 PNG/SVG/PDF。

主要优势： 基于文本的语法，支持完全自动布局——无需 x/y 坐标。

何时使用 / 何时不要使用

适用于： 需要自动布局的代码化图表（流程图、时序图、类图、状态图、ER 图、甘特图、思维导图、架构图）——文本源文件存储在 git 中，并嵌入 Markdown。

不要用于此类场景——请改用：

• 需要像素级精确放置、自定义布局、品牌图标或大量样式 → drawio。
• 手绘 / 草图风格 → excalidraw 或 tldraw。
• 自由形式的白板或徒手笔画 → tldraw。
• 严格、传统的 UML 表示法 → plantuml。

前置条件

选项 A：本地（mmdc）——还需要无头 Chrome（mmdc 通过 Puppeteer 渲染）

npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell   # required — mmdc has no bundled browser
mmdc --version

即使没有安装 Chrome，mmdc --version 也能成功，但之后每次导出都会失败并显示 Could not find Chrome。请安装上面的浏览器（或将 PUPPETEER_EXECUTABLE_PATH 设置为系统 Chrome 的路径）。如果无法安装，请使用 Kroki（选项 B）——它不需要浏览器。

CI / Docker： 在容器中，mmdc 会因 Running as root without --no-sandbox 崩溃。请传入随附的 puppeteer 配置（参见 scripts/puppeteer-config.json）：

mmdc -p scripts/puppeteer-config.json -i diagram.mmd -o diagram.png

选项 B：Kroki API（无需安装）

curl --version  # Just need curl

工作流

1. 检查依赖项——通过 Kroki 验证（只需要 curl）；仅在需要本地导出（PNG 质量 / PDF）时，检查 mmdc --version 和无头 Chrome
2. 选择图表类型——从下表中选择
3. 生成——将 .mmd 文件写入磁盘
4. 验证——优先使用 Kroki（参见“验证”；导出前必须执行）
5. 导出——使用 mmdc 或 Kroki API 生成 PNG/SVG/PDF
6. 自检（视觉）——查看导出的 PNG，并修复自动布局无法避免的可读性 / 布局问题（标签被裁切、过于拥挤、方向错误），然后重新验证并导出。最多 2 轮；如果无法进行视觉检查，则跳过。参见下文的自检（视觉）。
7. 审查循环——向用户展示图像，根据请求对 .mmd 进行最小修改，然后重新导出，直到获得批准（安全上限为 5 轮）。参见下文的审查循环。
8. 报告——告知用户输出文件路径

验证（必需）

未先验证图表前，绝不要导出。

验证时优先使用 Kroki——它不需要浏览器，也完全避开了 Could not find Chrome 的问题。仅在离线时使用 mmdc 验证。

# Validate with Kroki (preferred — no browser needed)
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

# Validate with mmdc (offline fallback — requires headless Chrome)
mmdc -i diagram.mmd -o /tmp/test.svg 2>&1

# If error, fix the .mmd file and validate again
# Only proceed to export after validation passes

常见验证错误：

• 标签中含有特殊字符，但未加引号
• 箭头语法错误（时序图使用 ->>，流程图使用 -->）
• 时序图中存在未声明的参与者

mmdc 报错 Could not find Chrome（或 puppeteer 相关错误）属于环境配置问题，而不是图表错误——.mmd 可能完全有效。请通过 Kroki 验证，而不要试图“修复”正确的语法。

自检（视觉）

**零成本预检：**在花费视觉调用之前，读取 PNG 的尺寸（在 macOS 上使用 sips -g pixelWidth -g pixelHeight diagram.png，其他系统使用 file diagram.png）。长宽比极端（较长边 > 较短边的 8 倍）属于“方向错误”缺陷——无需使用视觉能力，直接修正。

上述验证只能证明语法合法，并不能说明渲染后的图表是否易读。导出后，使用 Agent 的视觉能力读取 PNG，捕捉自动布局无法避免的问题。Mermaid 会自行安排所有元素的位置，因此此处的问题与内容和可读性有关，而非元素重叠：

检查项	检查内容	修复方法
标签截断	节点 / 边文本被裁剪或截断	缩短标签，或使用 <br/> 换行
排布拥挤、难以阅读	节点过多、挤在一起；线条交错	翻转方向（TD↔LR）、拆分为多个 subgraph，或减少节点
方向 / 长宽比错误	图表太宽或太高，难以阅读	更改 flowchart TD↔LR（或在 class/state 中设置 direction）
边线杂乱	多条边交叉，难以追踪	调整节点声明顺序，让相连节点彼此相邻；使用 subgraph 分组
图表类型错误	类型不适合内容（例如，用流程图表示时间线）	切换类型（gantt、sequenceDiagram、stateDiagram-v2 等）
对比度不足	文本与节点填充色混在一起	调整 classDef / 主题，使文本与填充色形成对比

• 最多进行 2 轮自检——如果修复 2 次后问题仍然存在，也要展示给用户。
• 每次修复后都要重新验证（语法）并重新导出。
• 如果无法使用视觉能力，则跳过自检，直接展示 PNG。

审阅流程

自检后，展示导出的图像并收集反馈。针对每项请求进行最小限度的 .mmd 修改，然后重新验证并导出：

用户请求	编辑操作
更改标签	编辑 .mmd 中的节点 / 边文本
添加 / 删除节点或边	添加或删除对应的行
更改颜色	添加 / 调整 classDef 和 class <node> <className>
更改布局方向	切换 TD↔LR（流程图），或设置 direction（class / state）
重新组织 / 分组	将相关节点放入 subgraph，或重新生成

• 每轮都覆盖同一个 diagram.mmd / diagram.png——不要创建 v1、v2 等版本。
• **安全措施：**进行 5 轮后，生成 mermaid.live 移交链接（见下一节），让用户在浏览器中微调当前图表。

Mermaid.live 移交

审阅流程结束时（用户批准或触发安全措施），生成一个一键链接，在 mermaid.live 编辑器中打开当前 .mmd，以便交互式微调：

python3 scripts/mermaid_live_link.py diagram.mmd
# -> https://mermaid.live/edit#pako:...

纯 zlib + base64（raw-deflate + URL-safe base64，与 mermaid.live 使用的编码相同），可离线运行。脚本会在打印前通过往返解码进行自检。

批处理模式（仓库调查）

当用户要求为整个仓库绘制图表（“调查这个代码库”、“绘制架构图”）时：

1. 扫描——在代码库中定位架构（SQL / ORM 模型）、API 路由，以及状态机 / 生命周期枚举
2. 提出方案——每项发现绘制一张图：架构用 ER 图、主要 API 流程用时序图、生命周期用状态图、整体服务布局用流程图；生成前与用户确认图表清单
3. 生成并导出——按照标准工作流逐张处理，并输出到同一个文件夹
4. 概览页面——将所有导出的 SVG 内嵌到一个独立的 index.html 中（含标题和每张图表对应的一个版块，不使用 CDN），供用户打开单个文件查看

批次中的每张图表都适用相同的验证和自检规则。

图表类型

类型	关键字	用途
流程图	flowchart TD/LR	流程、管道、决策
时序图	sequenceDiagram	API 调用、消息传递
类图	classDiagram	OOP 模型、数据结构
ER 图	erDiagram	数据库架构
状态图	stateDiagram-v2	状态机、生命周期
甘特图	gantt	项目时间线
饼图	pie	比例
Git 图	gitGraph	分支策略
C4 上下文图	C4Context	高层系统上下文
架构图	architecture-beta	云服务 / CI/CD 服务布局
思维导图	mindmap	主题拆解
用户旅程图	journey	用户体验流程
用例图	usecase-beta	参与者与系统交互（UML）
Cynefin 图	cynefin-beta	意义构建 / 复杂性领域
事件建模图	eventmodeling	事件驱动系统时间线
树形视图	treeView-beta	文件 / 目录层级结构
Wardley 地图	wardley-beta	业务策略 / 价值链

语法参考

流程图：参见 reference/FLOWCHART.md 时序图：参见 reference/SEQUENCE.md 类图与 ER 图：参见 reference/CLASS-ER.md 架构图：参见 reference/ARCHITECTURE.md 用例图：参见 reference/USECASE.md 其他类型：参见 reference/OTHER-TYPES.md 主题与样式：参见 reference/THEMES.md

示例

参见 reference/EXAMPLES.md，查看四个完整示例（JWT 身份验证时序图、微服务架构、订单状态机、云架构）——每个示例都包含用户提示词、生成的 .mmd 和输出文件。

导出命令

选项 1：本地导出（mmdc）

需要在本地安装 mmdc。最适合离线使用。

# PNG (recommended: 2048px wide, white background)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

# PNG with theme — valid -t values: default | dark | neutral | forest
# (`base` is NOT a valid -t value; it only works inside a %%{init: {'theme':'base'}}%% directive)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

选项 2：Kroki API（无需安装）

当 mmdc 不可用时，使用 Kroki。无需本地依赖。

# SVG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg

# PNG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

# PDF is NOT supported by Kroki for Mermaid — POSTing to /mermaid/pdf returns
# HTTP 400 ("Unsupported output format: pdf for mermaid. Must be one of png or svg").
# For PDF, use the local mmdc path instead:  mmdc -i diagram.mmd -o diagram.pdf

Kroki 的优势：

• 无需本地安装
• 任何装有 curl 的系统都能使用
• 支持 20 多种图表类型（PlantUML、GraphViz、D2 等）

适合使用 Kroki 的情况：

• mmdc 安装失败
• 快速绘制一次性图表
• 不含 Node.js 的 CI/CD 管道

常见错误

错误	修复方法
找不到 mmdc	npm install -g @mermaid-js/mermaid-cli
mmdc 报错 Could not find Chrome	安装无头浏览器：npx puppeteer browsers install chrome-headless-shell（或使用 Kroki）
Kroki 导出 PDF 时返回 HTTP 400	Kroki 对 Mermaid 仅支持 PNG/SVG；导出 PDF 请使用本地 mmdc
有效图表被 mmdc 报告为“无效”	错误源于 Chrome/puppeteer 配置失败，而不是语法错误——不要重写正确的 .mmd；请修复浏览器或通过 Kroki 验证
时序图中的箭头错误	请求使用 ->>，响应使用 -->>
标签中有特殊字符	用引号括起来：A["Label: value"]
输出为空或过小	添加 -w 2048 标志
参与者顺序错误	在顶部显式声明 participant
子图名称含空格	用引号括起来：subgraph "My Layer"