creating-mermaid-diagrams

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）——它无需浏览器。

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

curl --version  # Just need curl

工作流

1. 检查依赖项 — 运行 mmdc --version 并确认已安装无头 Chrome（仅通过 --version 检查并不代表导出可用）；如果任一项缺失，则改用 Kroki
2. 选择图表类型 — 从下表中选择
3. 生成 — 将 .mmd 文件写入磁盘
4. 验证 — 运行验证（导出前必须执行）
5. 导出 — 使用 mmdc 或 Kroki API 生成 PNG/SVG/PDF
6. 自检（视觉） — 查看导出的 PNG，并修复自动布局无法避免的可读性 / 布局问题（标签被裁切、内容过于拥挤、方向错误），然后重新验证并导出。最多进行 2 轮；如果没有视觉能力，则跳过。请参阅下方的自检（视觉）。
7. 审核循环 — 向用户展示图像，根据请求对 .mmd 进行最小修改，然后重新导出，直到获批（安全上限为 5 轮）。请参阅下方的审核循环。
8. 报告 — 告知用户输出文件的路径

验证（必需）

未经验证，绝不导出图表。

# Validate with mmdc (local)
mmdc -i diagram.mmd -o /tmp/test.png 2>&1

# Validate with Kroki (if mmdc unavailable)
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"

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

常见验证错误：

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

mmdc 报错 Could not find Chrome（或 puppeteer）是环境配置问题，而非图表错误——.mmd 可能完全有效。请安装浏览器（参阅前置条件），或改用 Kroki 验证，而不是“修复”正确的语法。

自检（视觉）

上述验证只能证明语法合法，并不能说明渲染出的图表是否易读。导出后，使用 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 微调。

图表类型

类型	关键字	适用场景
流程图	flowchart TD/LR	流程、管线、决策
时序图	sequenceDiagram	API 调用、消息传递
类图	classDiagram	OOP 模型、数据结构
ER 图	erDiagram	数据库架构
状态图	stateDiagram-v2	状态机、生命周期
甘特图	gantt	项目时间线
饼图	pie	比例
Git 图	gitGraph	分支策略
C4 上下文图	C4Context	高层架构
思维导图	mindmap	主题拆解
用户旅程图	journey	用户体验流程

语法参考

流程图：参见 reference/FLOWCHART.md 时序图：参见 reference/SEQUENCE.md 类图和 ER 图：参见 reference/CLASS-ER.md 其他类型：参见 reference/OTHER-TYPES.md

示例

示例 1：API 身份验证流程

用户提示词：

创建一个 JWT 身份验证时序图

生成的 .mmd：

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

输出文件： auth-flow.mmd + auth-flow.png

---

示例 2：微服务架构

用户提示词：

绘制一个电子商务微服务架构

生成的 .mmd：

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end

  GW[API Gateway]

  subgraph Services
    US[User Service]
    OS[Order Service]
    PS[Product Service]
    PAY[Payment Service]
  end

  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    PDB[(Product DB)]
    REDIS[(Redis Cache)]
  end

  M & W --> GW
  GW --> US & OS & PS & PAY
  US --> UDB
  OS --> ODB
  PS --> PDB
  PAY --> REDIS

输出文件： ecommerce-arch.mmd + ecommerce-arch.png

---

示例 3：订单状态机

用户提示词：

展示订单生命周期状态

生成的 .mmd：

stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

输出文件： order-states.mmd + order-states.png

导出命令

选项 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 等）

适用场景：

• 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"