mermaid-charts（Mermaid charts 效率）

Mermaid Diagram 画图技能

使用 Mermaid 语法生成各类图表（流程图、时序图、甘特图、饼图等），支持 PNG 和 HTML 两种输出格式。

输出格式

格式一：PNG 图片（推荐用于分享/嵌入）

mmdc -i input.mmd -o output.png -w <宽度> -H <高度> -b <背景色> -t <主题>

工作流程：

1. 将 mermaid 代码写入 .mmd 文件
2. 执行 mmdc 命令生成 PNG
3. 检查输出图片尺寸和宽高比

格式二：HTML 文件（推荐用于交互/修改）

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Mermaid Diagram</title>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true, theme: 'default' });
  </script>
</head>
<body>
  <pre class="mermaid">
    <!-- 在此处粘贴 mermaid 代码 -->
  </pre>
</body>
</html>

❗ 布局与排版规范（必读）

宽高比控制原则

方向选择指南

各图表推荐画布尺寸

图表类型详解

1. Flowchart（流程图）

使用场景： 业务流程、决策树、系统架构、算法步骤

语法模板：

flowchart TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作A]
    B -->|否| D[执行操作B]
    C --> E[结束]
    D --> E

节点形状：

连线类型：

完整示例：

flowchart TD
    A([开始]) --> B[/输入数据/]
    B --> C{数据有效?}
    C -->|有效| D[处理数据]
    C -->|无效| E[显示错误]
    E --> B
    D --> F[(保存到数据库)]
    F --> G([结束])

推荐尺寸： -w 800 -H 600（TD 方向），-w 1000 -H 500（LR 方向）

⚠️ 常见陷阱：

• end 是保留字，作为节点文字需用引号包裹：A["end"]
• 节点 ID 不要用中文，文字标签可以用中文
• 嵌套节点可能导致解析错误

2. Sequence Diagram（时序图）

使用场景： API 调用流程、微服务交互、协议握手、系统通信

语法模板：

sequenceDiagram
    participant A as 客户端
    participant B as 服务器
    participant C as 数据库
    A->>B: 发送请求
    B->>C: 查询数据
    C-->>B: 返回结果
    B-->>A: 响应数据

消息类型：

高级功能：

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant DB as 数据库

    U->>S: 登录请求
    activate S
    S->>DB: 验证用户
    activate DB
    DB-->>S: 验证通过
    deactivate DB

    alt 验证成功
        S-->>U: 返回 Token
    else 验证失败
        S-->>U: 返回 401
    end
    deactivate S

    Note over U,S: 后续请求需携带 Token

    loop 每隔5分钟
        U->>S: 心跳检查
        S-->>U: OK
    end

关键语法：

• activate/deactivate — 激活条（显示处理中）
• alt/else/end — 条件分支
• loop/end — 循环
• par/and/end — 并行处理
• Note over A,B: — 跨参与者的备注
• rect rgb(200,220,255)/end — 高亮区域

推荐尺寸： -w 800 -H 600（≤5 参与者），-w 1200 -H 600（>5 参与者）

⚠️ 常见陷阱：

• end 是保留字，用引号包裹：participant E as "End Service"
• 参与者过多（>8）会导致横向过宽，考虑拆分

3. Class Diagram（类图）

使用场景： 面向对象设计、系统架构、数据模型

语法模板：

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    class Cat {
        +purr() void
    }
    Animal <|-- Dog
    Animal <|-- Cat

关系类型：

可见性修饰符：

完整示例：

classDiagram
    class Vehicle {
        <<abstract>>
        +String brand
        +int speed
        +start() void
        +stop() void
    }
    class Car {
        +int doors
        +openTrunk() void
    }
    class Motorcycle {
        +bool hasSidecar
    }
    class Engine {
        +int horsepower
        +String fuelType
    }

    Vehicle <|-- Car
    Vehicle <|-- Motorcycle
    Car *-- Engine : has
    Motorcycle *-- Engine : has

推荐尺寸： -w 1000 -H 700

4. State Diagram（状态图）

使用场景： 状态机、对象生命周期、协议状态

语法模板：

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : 收到请求
    Processing --> Success : 处理成功
    Processing --> Error : 处理失败
    Success --> [*]
    Error --> Idle : 重试

高级功能：

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Running
        Running --> Paused : 暂停
        Paused --> Running : 继续
    }

    Active --> Inactive : 关闭
    Inactive --> Active : 启动
    Inactive --> [*]

    state fork_state <<fork>>
    Active --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> Done

    state Decision <<choice>>
    Done --> Decision
    Decision --> Success : 通过
    Decision --> Failure : 失败

关键语法：

• [*] — 起始/终止状态
• state Name { } — 复合状态（嵌套）
• <<fork>> / <<join>> — 并行分叉/汇合
• <<choice>> — 选择节点
• note right/left of State — 备注

推荐尺寸： -w 800 -H 600

5. Entity Relationship Diagram（ER 图）

使用场景： 数据库设计、数据模型、实体关系

语法模板：

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"
    CUSTOMER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        date created
        string status
    }

关系符号：

完整格式： <entity1> <relationship> <entity2> : <label>

属性语法： type name PK/FK/UK "注释"

推荐尺寸： -w 1000 -H 700

⚠️ 注意： 实体名建议大写（如 CUSTOMER），关系标签有空格需用引号

6. Gantt Chart（甘特图）

使用场景： 项目进度、任务规划、里程碑跟踪

语法模板：

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

    section 需求阶段
    需求分析        :done, req1, 2026-01-01, 10d
    需求评审        :done, req2, after req1, 3d

    section 开发阶段
    后端开发        :active, dev1, after req2, 20d
    前端开发        :dev2, after req2, 15d
    API 联调        :dev3, after dev1, 5d

    section 测试阶段
    功能测试        :test1, after dev3, 10d
    上线发布        :milestone, after test1, 0d

任务标签：

日期格式：

推荐尺寸： -w 1000 -H 500（≤10 任务），-w 1200 -H 700（>10 任务）

⚠️ 常见陷阱：

• dateFormat 和 axisFormat 要区分（输入格式 vs 显示格式）
• 任务 ID 不能有空格
• excludes weekends 可排除周末

7. Pie Chart（饼图）

使用场景： 比例分布、市场份额、资源分配

语法模板：

pie showData
    title 编程语言使用占比
    "Python" : 35
    "JavaScript" : 30
    "Java" : 20
    "Go" : 10
    "其他" : 5

关键语法：

• pie — 声明饼图
• showData — （可选）显示数值
• title — （可选）标题
• "标签" : 数值 — 数据项（数值必须 >0）

推荐尺寸： -w 700 -H 700（正方形效果最佳）

⚠️ 注意： 不支持负数值，切片按标签顺序顺时针排列

8. Mindmap（思维导图）

使用场景： 知识梳理、头脑风暴、概念拆解

语法模板：

mindmap
  root((中心主题))
    分支1
      子主题A
      子主题B
    分支2
      子主题C
        细节1
        细节2
    分支3
      子主题D

节点形状：

关键规则：

• 缩进决定层级（必须一致，建议用 2 或 4 空格）
• 根节点在第一行，无缩进
• 子节点比父节点多一级缩进

推荐尺寸： -w 1000 -H 700

⚠️ 常见陷阱：

• 缩进不一致会导致层级错乱
• 每层子节点不超过 5-6 个，否则图会过于拥挤
• 总层级不超过 4 层

9. Timeline（时间线）

使用场景： 历史事件、项目里程碑、版本发布记录

语法模板：

timeline
    title 项目发展历程
    2023 : 项目启动
         : 组建团队
    2024 : 发布 v1.0
         : 获得首批用户
    2025 : 发布 v2.0
         : 用户突破 10 万

分组语法：

timeline
    title 技术演进
    section 早期
        2020 : HTML5 普及
        2021 : 移动优先
    section 成熟期
        2022 : AI 集成
        2023 : 全面云原生

关键规则：

• 时间点 : 事件 格式
• 同一时间点多个事件用换行 + 缩进 : 事件
• section 对时间点分组

推荐尺寸： -w 1000 -H 500（≤5 时期），-w 1200 -H 600（>5 时期）

10. Git Graph（Git 图）

使用场景： Git 分支策略、版本管理流程、CI/CD 流水线

语法模板：

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    branch feature
    checkout feature
    commit
    checkout develop
    merge feature
    checkout main
    merge develop
    commit tag:"v1.0"

关键命令：

推荐尺寸： -w 1000 -H 500

11. Sankey Diagram（桑基图）

使用场景： 能量流向、资金流转、用户路径

语法模板：

sankey-beta

来源A,目标X,50
来源A,目标Y,30
来源B,目标X,20
来源B,目标Z,40
目标X,终点,70
目标Y,终点,30
目标Z,终点,40

关键规则：

• 类 CSV 格式：源,目标,数值
• 必须恰好 3 列
• 允许空行（用于视觉分隔）
• 包含逗号的文本用双引号包裹

推荐尺寸： -w 1000 -H 600

⚠️ 实验性功能： 语法可能在未来版本变化

12. XY Chart（XY 图表）

使用场景： 数据趋势、柱状图、折线图、数据对比

语法模板（柱状图 + 折线图）：

xychart-beta
    title "月度销售数据"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "销售额（万元）" 0 --> 100
    bar [30, 45, 60, 55, 70, 85]
    line [30, 45, 60, 55, 70, 85]

语法要素：

推荐尺寸： -w 800 -H 600

13. Block Diagram（块图）

使用场景： 系统架构、组件关系、层级结构

语法模板：

block-beta
    columns 3
    A["前端"] B["API 网关"] C["后端服务"]
    space D["数据库"] space

关键语法：

推荐尺寸： -w 800 -H 600

⚠️ 实验性功能

14. Quadrant Chart（象限图）

使用场景： 优先级矩阵、SWOT 分析、竞品对比

语法模板：

quadrantChart
    title 技术选型评估
    x-axis 学习成本低 --> 学习成本高
    y-axis 功能弱 --> 功能强
    quadrant-1 首选方案
    quadrant-2 值得投入
    quadrant-3 谨慎考虑
    quadrant-4 暂不推荐
    React: [0.8, 0.9]
    Vue: [0.4, 0.7]
    jQuery: [0.2, 0.3]
    Angular: [0.9, 0.8]

关键语法：

• 坐标范围 0~1
• quadrant-1 到 quadrant-4：四个象限的标签（1=右上，2=左上，3=左下，4=右下）

推荐尺寸： -w 700 -H 700（正方形）

15. User Journey（用户旅程图）

使用场景： 用户体验分析、服务蓝图、流程痛点

语法模板：

journey
    title 用户购物体验
    section 浏览
        访问首页: 5: 用户
        搜索商品: 4: 用户
        查看详情: 4: 用户
    section 购买
        加入购物车: 3: 用户
        填写地址: 2: 用户
        支付: 3: 用户, 系统
    section 售后
        等待发货: 3: 用户
        收到商品: 5: 用户

关键语法：

• 任务名: 评分: 参与者 （评分 1-5，5 最好）
• section 分段

推荐尺寸： -w 1000 -H 500

主题配置

Mermaid 内置 4 种主题，通过 mmdc -t <theme> 或 frontmatter 设置：

Frontmatter 方式设置主题：

---
config:
  theme: forest
---
flowchart TD
    A --> B

复杂图表拆分策略

快速参考：mmdc 常用命令

# 基本 PNG 生成
mmdc -i diagram.mmd -o diagram.png

# 指定尺寸和背景
mmdc -i diagram.mmd -o diagram.png -w 1000 -H 700 -b white

# 透明背景（适合嵌入深色页面）
mmdc -i diagram.mmd -o diagram.png -b transparent

# 使用深色主题
mmdc -i diagram.mmd -o diagram.png -t dark -b "#1a1a2e"

# 生成 SVG（矢量，可缩放）
mmdc -i diagram.mmd -o diagram.svg

# 生成 PDF
mmdc -i diagram.mmd -o diagram.pdf -f

# 使用配置文件
mmdc -i diagram.mmd -o diagram.png -c config.json

# 高清输出（2 倍缩放）
mmdc -i diagram.mmd -o diagram.png -s 2

配置文件示例（config.json）：

{
  "theme": "default",
  "flowchart": {
    "curve": "basis",
    "padding": 15
  },
  "sequence": {
    "actorMargin": 50,
    "messageMargin": 35
  }
}

⚠️ 通用注意事项

1. 保留字 end： 在 Flowchart 和 Sequence Diagram 中，end 可能破坏解析，用引号包裹 "end" 或 (end) / [end]
2. 特殊字符： 节点文字含 (){}[] 等符号时需用引号
3. 中文支持： 标签文字支持中文，但节点 ID 建议用英文/数字
4. 空行： 某些图表类型对空行敏感，保持代码紧凑
5. 缩进： Mindmap 和 Timeline 严格依赖缩进，必须保持一致
6. 版本差异： Sankey、XY Chart、Block Diagram 等标记为 -beta，语法可能变化