Pretty Mermaid — 专业 Mermaid 图表生成

When to Use

• 用户要求创建流程图、架构图、时序图、类图、状态图、ER 图、C4 架构图或甘特图
• 需要将图表渲染为 SVG 或 ASCII 文本输出
• 需要批量生成多张图表
• 用户要求使用特定主题或配色方案
• 需要可复用的图表模板

---

Prerequisites

必需工具

工具	用途	安装方式
Node.js ≥ 18	运行 Mermaid CLI	系统预装或 nvm install 18
@mermaid-js/mermaid-cli	渲染 SVG/PNG	npm install -g @mermaid-js/mermaid-cli

可选工具

工具	用途	安装方式
monodraw (macOS)	ASCII 图表编辑	App Store
graph-easy	ASCII 渲染	cpan Graph::Easy

验证安装

mmdc --version

如果 mmdc 不可用，回退到纯 Mermaid 代码块输出，让用户在支持 Mermaid 的编辑器或浏览器中预览。

---

Instructions

核心工作流

1. 理解需求 — 明确图表类型、数据来源、目标受众
2. 选择图表类型 — 根据场景匹配最合适的 Mermaid 图表
3. 选择主题 — 根据使用场景选择配色方案
4. 编写 Mermaid 代码 — 遵循可读性最佳实践
5. 渲染输出 — 按指定格式输出 SVG、PNG 或 ASCII
6. 校验与优化 — 检查语法、布局、可读性

图表类型选择指南

场景	推荐图表	Mermaid 关键字
业务流程、审批流	流程图	flowchart TD/LR
API 调用、服务交互	时序图	sequenceDiagram
代码结构、OOP 设计	类图	classDiagram
生命周期、状态机	状态图	stateDiagram-v2
数据库设计	ER 图	erDiagram
系统架构、微服务	C4 架构图	C4Context/C4Container/C4Component
项目排期、里程碑	甘特图	gantt
Git 分支策略	Git 图	gitGraph
思维导图、脑暴	思维导图	mindmap
时间线	时间线	timeline

---

Workflows

Workflow 1: 单张图表生成

步骤 1 — 收集信息

向用户确认以下内容（如未提供则使用默认值）：

参数	默认值	可选值
图表类型	flowchart	见上方选择指南
方向	TD（上到下）	TD, LR, RL, BT
主题	default	default, dark, forest, neutral, base
输出格式	Mermaid 代码块	svg, png, ascii, mermaid
主题方案	Tokyo Night	Tokyo Night, Dracula, GitHub Light, Nord, Solarized

步骤 2 — 编写 Mermaid 代码

遵循以下规范：

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1b26', 'primaryTextColor': '#a9b1d6', 'primaryBorderColor': '#7aa2f7', 'lineColor': '#565f89', 'secondaryColor': '#24283b', 'tertiaryColor': '#1a1b26' }}}%%
flowchart TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E

步骤 3 — 渲染（如需 SVG/PNG）

将 Mermaid 代码写入临时 .mmd 文件，然后调用：

mmdc -i diagram.mmd -o diagram.svg -t dark -b transparent
mmdc -i diagram.mmd -o diagram.png -t dark -b white -w 1200

步骤 4 — 输出

返回渲染后的文件路径，或直接在消息中嵌入 Mermaid 代码块。

---

Workflow 2: 批量图表生成

适用于一次性生成多张相关图表（如系统设计文档）。

步骤 1 — 收集所有图表的需求列表

步骤 2 — 创建批处理配置：

{
  "theme": "tokyo-night",
  "outputDir": "./diagrams",
  "outputFormat": "svg",
  "diagrams": [
    {
      "name": "system-overview",
      "type": "C4Context",
      "title": "系统总览"
    },
    {
      "name": "api-sequence",
      "type": "sequenceDiagram",
      "title": "API 调用时序"
    },
    {
      "name": "data-model",
      "type": "erDiagram",
      "title": "数据模型"
    }
  ]
}

步骤 3 — 逐一生成 Mermaid 代码并渲染

步骤 4 — 返回所有图表的路径和预览

---

Workflow 3: ASCII 图表输出

当用户需要纯文本图表（用于 CLI、日志、README 等场景）：

方法 A — 手动 ASCII 绘制

对于简单图表，直接使用字符绘制：

┌─────────┐     ┌─────────┐     ┌─────────┐
│  Client  │────▶│  Server │────▶│Database │
└─────────┘     └─────────┘     └─────────┘
                     │
                     ▼
                ┌─────────┐
                │  Cache  │
                └─────────┘

方法 B — 使用 graph-easy 转换

echo "[ Client ] -> [ Server ] -> [ Database ]" | graph-easy --as=ascii

---

主题配置

Tokyo Night（默认）

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#1a1b26',
  'primaryTextColor': '#a9b1d6',
  'primaryBorderColor': '#7aa2f7',
  'lineColor': '#565f89',
  'secondaryColor': '#24283b',
  'tertiaryColor': '#414868',
  'noteBkgColor': '#1a1b26',
  'noteTextColor': '#c0caf5',
  'noteBorderColor': '#7aa2f7'
}}}%%

Dracula

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#282a36',
  'primaryTextColor': '#f8f8f2',
  'primaryBorderColor': '#bd93f9',
  'lineColor': '#6272a4',
  'secondaryColor': '#44475a',
  'tertiaryColor': '#383a59',
  'noteBkgColor': '#282a36',
  'noteTextColor': '#f8f8f2',
  'noteBorderColor': '#ff79c6'
}}}%%

GitHub Light

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#ffffff',
  'primaryTextColor': '#24292f',
  'primaryBorderColor': '#d0d7de',
  'lineColor': '#656d76',
  'secondaryColor': '#f6f8fa',
  'tertiaryColor': '#eaeef2',
  'noteBkgColor': '#ddf4ff',
  'noteTextColor': '#24292f',
  'noteBorderColor': '#54aeff'
}}}%%

Nord

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#2e3440',
  'primaryTextColor': '#eceff4',
  'primaryBorderColor': '#88c0d0',
  'lineColor': '#4c566a',
  'secondaryColor': '#3b4252',
  'tertiaryColor': '#434c5e',
  'noteBkgColor': '#2e3440',
  'noteTextColor': '#eceff4',
  'noteBorderColor': '#81a1c1'
}}}%%

Solarized

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#002b36',
  'primaryTextColor': '#839496',
  'primaryBorderColor': '#268bd2',
  'lineColor': '#586e75',
  'secondaryColor': '#073642',
  'tertiaryColor': '#073642',
  'noteBkgColor': '#002b36',
  'noteTextColor': '#93a1a1',
  'noteBorderColor': '#2aa198'
}}}%%

---

模板库

模板 1: 微服务架构（C4 Container）

C4Container
    title 微服务系统架构

    Person(user, "用户", "通过浏览器或移动端访问系统")

    System_Boundary(system, "核心系统") {
        Container(web, "Web 前端", "React", "用户界面")
        Container(gateway, "API 网关", "Kong/Nginx", "路由、限流、鉴权")
        Container(auth, "认证服务", "Go", "JWT 签发与验证")
        Container(biz, "业务服务", "Python", "核心业务逻辑")
        Container(notify, "通知服务", "Node.js", "邮件/短信/推送")
        ContainerDb(db, "主数据库", "PostgreSQL", "业务数据存储")
        ContainerDb(cache, "缓存", "Redis", "会话与热数据缓存")
        ContainerQueue(mq, "消息队列", "RabbitMQ", "异步任务处理")
    }

    Rel(user, web, "使用", "HTTPS")
    Rel(web, gateway, "API 调用", "HTTPS")
    Rel(gateway, auth, "鉴权", "gRPC")
    Rel(gateway, biz, "业务请求", "gRPC")
    Rel(biz, db, "读写", "TCP")
    Rel(biz, cache, "缓存", "TCP")
    Rel(biz, mq, "发布消息", "AMQP")
    Rel(mq, notify, "消费消息", "AMQP")

模板 2: CI/CD 流水线（Flowchart）

flowchart LR
    A[代码提交] --> B[触发 CI]
    B --> C{代码检查}
    C -->|通过| D[单元测试]
    C -->|失败| Z[通知开发者]
    D -->|通过| E[构建镜像]
    D -->|失败| Z
    E --> F[推送镜像仓库]
    F --> G{环境选择}
    G -->|Staging| H[部署 Staging]
    G -->|Production| I[人工审批]
    I -->|批准| J[蓝绿部署]
    I -->|拒绝| Z
    H --> K[集成测试]
    K -->|通过| L[✅ Staging 就绪]
    K -->|失败| M[自动回滚]
    J --> N[健康检查]
    N -->|通过| O[✅ 上线成功]
    N -->|失败| P[自动回滚]

模板 3: 用户认证时序（Sequence）

sequenceDiagram
    actor U as 用户
    participant C as 客户端
    participant G as API 网关
    participant A as 认证服务
    participant D as 数据库

    U->>C: 输入用户名/密码
    C->>G: POST /api/auth/login
    G->>A: 转发认证请求
    A->>D: 查询用户记录
    D-->>A: 返回用户数据
    alt 密码正确
        A->>A: 生成 JWT Token
        A-->>G: 200 OK + Token
        G-->>C: 返回 Token
        C->>C: 存储 Token
        C-->>U: 登录成功
    else 密码错误
        A-->>G: 401 Unauthorized
        G-->>C: 认证失败
        C-->>U: 提示错误
    end

    Note over C,G: 后续请求携带 Token
    U->>C: 访问受保护资源
    C->>G: GET /api/data (Bearer Token)
    G->>A: 验证 Token
    A-->>G: Token 有效
    G->>G: 转发到业务服务

模板 4: 数据库 ER 图

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string username UK
        string email UK
        string password_hash
        datetime created_at
        datetime updated_at
    }
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        decimal total_amount
        string status
        datetime created_at
    }
    ORDER_ITEM }|--|| PRODUCT : references
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }
    PRODUCT ||--o{ PRODUCT_TAG : has
    PRODUCT {
        int id PK
        string name
        text description
        decimal price
        int stock
    }
    TAG ||--o{ PRODUCT_TAG : applied
    TAG {
        int id PK
        string name UK
    }
    PRODUCT_TAG {
        int product_id FK
        int tag_id FK
    }

模板 5: 项目甘特图

gantt
    title 项目开发排期
    dateFormat YYYY-MM-DD
    axisFormat %m/%d

    section 需求阶段
    需求调研           :done,    req1, 2025-01-01, 7d
    需求评审           :done,    req2, after req1, 3d
    PRD 定稿           :done,    req3, after req2, 2d

    section 设计阶段
    技术方案设计        :active,  des1, after req3, 5d
    UI/UX 设计         :         des2, after req3, 7d
    设计评审           :         des3, after des2, 2d

    section 开发阶段
    后端开发           :         dev1, after des1, 15d
    前端开发           :         dev2, after des3, 15d
    联调测试           :         dev3, after dev1, 5d

    section 发布阶段
    UAT 测试           :         rel1, after dev3, 5d
    修复 Bug           :         rel2, after rel1, 3d
    正式发布           :milestone, rel3, after rel2, 0d

---

Output Format

默认输出

直接在回复中使用 Mermaid 代码块：

```mermaid
flowchart TD
    A --> B
```

SVG 文件

mmdc -i input.mmd -o output.svg -t dark -b transparent --cssFile custom.css

PNG 文件

mmdc -i input.mmd -o output.png -t dark -b white -w 1920 -H 1080 -s 2

参数说明：

• -t 主题：default, dark, forest, neutral
• -b 背景色：transparent, white, #hex
• -w 宽度（像素）
• -H 高度（像素）
• -s 缩放倍数

ASCII 文本

直接使用字符绘制，适合嵌入代码注释、终端输出、纯文本文档。

---

Common Pitfalls

1. 节点 ID 冲突

错误：在同一图表中使用重复的节点 ID

flowchart TD
    A[登录] --> B[验证]
    A[注册] --> B[检查]

正确：使用唯一 ID

flowchart TD
    login[登录] --> validate[验证]
    register[注册] --> check[检查]

2. 特殊字符未转义

错误：节点文本包含括号、引号等

A[用户输入(name)]

正确：使用引号包裹

A["用户输入(name)"]

3. 图表过于复杂

单张图表超过 20 个节点时，考虑拆分为多张子图：

flowchart TD
    subgraph 前端
        A --> B --> C
    end
    subgraph 后端
        D --> E --> F
    end
    C --> D

4. 方向选择不当

• 层级结构（组织架构、决策树）→ TD（上到下）
• 流程/管道 → LR（左到右）
• 时间线/历史 → LR
• 请求-响应 → TD 或 LR

5. 中文乱码

渲染 SVG/PNG 时如果出现中文乱码，使用 --cssFile 指定字体：

* {
    font-family: "Microsoft YaHei", "PingFang SC", "Noto Sans CJK SC", sans-serif;
}

6. Mermaid CLI 超时

大型图表可能渲染超时，增加超时参数：

mmdc -i large-diagram.mmd -o output.svg --puppeteerConfigFile puppeteer.json

puppeteer.json:

{
  "timeout": 60000
}

7. 子图嵌套限制

Mermaid 支持子图嵌套，但过深的嵌套（超过 3 层）可能导致渲染异常。保持层级扁平化。

---

最佳实践

1. 命名规范 — 节点 ID 使用有意义的英文命名，显示文本使用中文
2. 布局控制 — 善用 subgraph 对节点分组，改善布局
3. 颜色语义 — 绿色表示成功、红色表示失败、蓝色表示进行中
4. 注释标注 — 使用 Note 添加关键说明
5. 渐进呈现 — 复杂系统先画总览再画细节，用 C4 的 Context → Container → Component 层级
6. 版本控制 — Mermaid 代码是纯文本，适合纳入 Git 管理
7. 一致性 — 同一文档中的所有图表使用相同主题配置

---

EXTEND.md 扩展

用户可在技能同目录下创建 EXTEND.md 添加自定义主题和模板，Agent 会自动合并使用。