Mermaid 制图器

将设计意图转化为 .mmd 文本，再渲染为主题化 SVG、ASCII、PNG 或 PDF。

核心优势：基于文本的语法 + 全自动布局 —— 无需指定 x/y 坐标。源码可纳入 Git 版本管理，并可直接嵌入 Markdown 文件中。

适用与不适用场景

请使用该能力的场景：以代码方式构建图表（流程图、序列图、类图、状态图、ER 图、甘特图、思维导图、C4 图等），并从同一份源码生成风格统一、主题明确或适配终端的高质量输出。

请勿使用该能力（应转至其他工具）：

• 需像素级精确定位、自定义布局、品牌图标或深度样式控制 → drawio。
• 追求手绘/草图风格 → excalidraw 或 tldraw。
• 自由白板协作或手写笔迹 → tldraw。
• 严格遵循标准 UML 规范 → plantuml。

工作流

1. 选择图表类型 —— 参见下方表格。
2. 生成 —— 将 .mmd 文件写入磁盘（可参考 assets/templates/ 中的模板快速起步）。
3. 验证 —— 导出前必须执行：使用你选定的后端进行试渲染（参见 验证 章节）。
4. 选择后端并渲染/导出 —— 主题化 SVG / ASCII / 批量处理 → beautiful-mermaid；PNG / PDF → mmdc；免安装 → Kroki（参见 渲染 章节）。
5. 自查（视觉检查） —— 查看渲染图像，修正自动布局无法规避的可读性缺陷（如文字截断、密度过高）；每次修改后均需重新验证 + 重新导出。最多执行 2 轮；若无视觉能力，可跳过此步，直接展示图像。
6. 评审循环 —— 展示图像 → 收集反馈 → 应用最小化的 .mmd 修改 → 重新验证 + 重新导出，直至获得批准（设 5 轮安全上限）。
7. 汇报 —— 向用户说明输出文件路径。

图表类型

常用模板位于 assets/templates/ 目录（含 flowchart、sequence、state、class、er、gantt、gitgraph）。

渲染

根据交付需求选择后端。完整命令行参数、安装说明与排错指南详见 RENDERING.md。

• ASCII（终端 / README 场景）：node scripts/render.mjs -i d.mmd -f ascii --use-ascii
• 批量处理 整个目录：node scripts/batch.mjs -i ./diagrams -o ./out --theme dracula -w 4
• beautiful-mermaid 仅支持输出 SVG / ASCII；PNG / PDF 请使用 mmdc。其依赖项会在首次运行时自动安装。

主题配置

beautiful-mermaid 内置 15 种主题。常用推荐：

• 深色文档 → tokyo-night ⭐ · github-dark · dracula
• 浅色文档 → github-light · zinc-light · catppuccin-latte

列出全部主题：node scripts/themes.mjs。完整主题目录、自定义调色板及选型决策树详见 THEMES.md。
mmdc 使用自身标准主题（default/dark/neutral/forest），通过 --theme 参数指定。

验证（必需步骤）

切勿在未验证前提下导出。请使用你最终选用的后端进行试渲染：

node scripts/render.mjs -i diagram.mmd -o /tmp/test.svg          # beautiful-mermaid
mmdc -i diagram.mmd -o /tmp/test.png 2>&1                        # mmdc
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

mmdc 报错 Could not find Chrome 属于环境配置问题，而非语法错误 —— 不要重写合法的 .mmd 源码；请修复浏览器环境，或改用其他后端完成验证。

自查（视觉检查）

验证仅确保语法合法，**不能保证渲染结果具备可读性**。导出后，请人工审阅图像，识别自动布局无法规避的问题（以下均为内容相关问题，非单纯重叠）：

最多执行 2 轮 自查；每次修复后均需重新验证 + 重新导出。若无视觉能力，可跳过此步，直接展示图像。

评审循环

展示图像 → 收集反馈 → 应用最小化的 .mmd 修改 → 重新验证 + 重新导出：

每轮均覆盖同名 diagram.mmd 文件及输出文件 —— 不要创建 v1、v2 等版本。超过 5 轮后，建议前往 mermaid.live 进行精细化调整。

示例

示例 1 — API 认证流程（序列图）

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-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

渲染命令：node scripts/render.mjs -i auth-flow.mmd -o auth-flow.svg --theme tokyo-night

示例 2 — 微服务架构（流程图）

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end
  GW[API Gateway]
  subgraph Services
    US[User Service]
    OS[Order Service]
    PAY[Payment Service]
  end
  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    REDIS[(Redis Cache)]
  end
  M & W --> GW
  GW --> US & OS & PAY
  US --> UDB
  OS --> ODB
  PAY --> REDIS

导出 PNG：mmdc -i ecommerce-arch.mmd -o ecommerce-arch.png -w 2048 --backgroundColor white

示例 3 — 订单生命周期（状态图）

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

README 中的 ASCII 渲染：node scripts/render.mjs -i order-states.mmd -f ascii --use-ascii

常见错误

完整后端参数与排错指南详见 RENDERING.md。