Mermaid Diagram 画图技能#

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

---

输出格式#

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

bash

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

参数说明默认值-i输入 .mmd 文件必填-o输出文件（ .png / .svg / .pdf）必填-w页面宽度（像素）800-H页面高度（像素）600-b背景色（ transparent, white, #F0F0F0）white``-t主题（ default, forest, dark, neutral）default``-s缩放比例1-cJSON 配置文件无

工作流程：

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

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

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>

---

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

宽高比控制原则#

原则说明避免极端比例宽高比不超过 3:1 或 1:3流程图方向选择节点 ≤6 个横向用 LR，≥7 个纵向用 TD控制单层节点数同一层级不超过 5-6 个节点复杂图表拆分超过 15 个节点考虑拆成多张图

方向选择指南#

方向关键字适用场景上→下TD / TB层级结构、决策树、组织架构左→右LR流程/管道、时间线式流程下→上BT自底向上的构建过程右→左RL回溯/反向流程

各图表推荐画布尺寸#

图表类型推荐宽度推荐高度说明Flowchart (TD, ≤8 节点)800600标准 4:3Flowchart (LR, ≤6 节点)1000500横向 2:1Flowchart (大型 >10 节点)1200800加大画布Sequence Diagram (≤5 参与者)800600标准Sequence Diagram (>5 参与者)1200600加宽Class Diagram1000700略宽State Diagram800600标准ER Diagram1000700略宽Gantt Chart (≤10 任务)1000500横向 2:1Gantt Chart (>10 任务)1200700加高Pie Chart7007001:1 正方形Mindmap1000700略宽Timeline (≤5 时期)1000500横向Timeline (>5 时期)1200600加宽Git Graph1000500横向Sankey Diagram1000600略宽XY Chart800600标准 4:3Quadrant Chart7007001:1 正方形User Journey1000500横向Block Diagram800600标准

---

图表类型详解#

---

1. Flowchart（流程图）#

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

语法模板：

Rendering diagram...

节点形状：

语法形状用途A[文本]矩形普通步骤A(文本)圆角矩形普通步骤（柔和）A{文本}菱形条件判断A((文本))圆形起止点A([文本])体育场形起止点（替代）A[[文本]]子程序子流程调用A[(文本)]圆柱体数据库A>文本]旗帜形标记/信号A{{文本}}六边形准备/条件A[/文本/]平行四边形输入/输出

连线类型：

语法说明-->带箭头实线---无箭头实线-.->带箭头虚线==>带箭头粗线--文字-->带标签的线`-->文字

完整示例：

Rendering diagram...

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

⚠️ 常见陷阱：

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

---

2. Sequence Diagram（时序图）#

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

语法模板：

Rendering diagram...

消息类型：

语法说明->无箭头实线-->无箭头虚线->>带箭头实线-->>带箭头虚线-x带叉实线（失败）--x带叉虚线-)带开放箭头实线（异步）--)带开放箭头虚线

高级功能：

Rendering diagram...

关键语法：

• 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（类图）#

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

语法模板：

Rendering diagram...

关系类型：

语法关系说明<|--继承实线三角箭头*--组合实线实心菱形o--聚合实线空心菱形-->关联实线箭头..>依赖虚线箭头<|..实现虚线三角箭头--链接实线

可见性修饰符：

符号含义+public-private#protected~package/internal

完整示例：

Rendering diagram...

推荐尺寸： -w 1000 -H 700

---

4. State Diagram（状态图）#

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

语法模板：

Rendering diagram...

高级功能：

Rendering diagram...

关键语法：

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

推荐尺寸： -w 800 -H 600

---

5. Entity Relationship Diagram（ER 图）#

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

语法模板：

Rendering diagram...

关系符号：

左侧右侧含义||``||恰好一个||``o{零或多个||``|{一或多个o|``o{零或一对零或多

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

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

推荐尺寸： -w 1000 -H 700

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

---

6. Gantt Chart（甘特图）#

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

语法模板：

Rendering diagram...

任务标签：

标签说明done已完成（灰色）active进行中（蓝色）crit关键路径（红色）milestone里程碑（菱形标记）

日期格式：

格式说明YYYY-MM-DD标准日期after taskID在某任务之后10d持续 10 天5h持续 5 小时

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

⚠️ 常见陷阱：

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

---

7. Pie Chart（饼图）#

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

语法模板：

Rendering diagram...

关键语法：

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

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

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

---

8. Mindmap（思维导图）#

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

语法模板：

Rendering diagram...

节点形状：

语法形状id默认（矩形）id[文字]方形id(文字)圆角矩形id((文字))圆形id))文字((爆炸形（Bang）id)文字(云朵形id{{文字}}六边形

关键规则：

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

推荐尺寸： -w 1000 -H 700

⚠️ 常见陷阱：

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

---

9. Timeline（时间线）#

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

语法模板：

Rendering diagram...

分组语法：

Rendering diagram...

关键规则：

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

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

---

10. Git Graph（Git 图）#

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

语法模板：

Rendering diagram...

关键命令：

命令说明commit提交（可选 id: "msg" type: NORMAL/REVERSE/HIGHLIGHT）branch name创建并切换分支checkout name切换分支（也可用 switch）merge name合并分支commit tag:"v1.0"带标签的提交

推荐尺寸： -w 1000 -H 500

---

11. Sankey Diagram（桑基图）#

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

语法模板：

Rendering diagram...

关键规则：

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

推荐尺寸： -w 1000 -H 600

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

---

12. XY Chart（XY 图表）#

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

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

Rendering diagram...

语法要素：

元素说明xychart-beta声明（可加 horizontal）title "标题"标题x-axis [cat1, cat2, ...]X 轴分类x-axis "title" min --> maxX 轴数值范围y-axis "title" min --> maxY 轴范围bar [数据]柱状图数据line [数据]折线图数据

推荐尺寸： -w 800 -H 600

---

13. Block Diagram（块图）#

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

语法模板：

Rendering diagram...

关键语法：

语法说明columns N设置列数A["文字"]普通块A("文字")圆角块A(("文字"))圆形块A{{"文字"}}六边形块space空占位A --> B连线A:N块跨 N 列

推荐尺寸： -w 800 -H 600

⚠️ 实验性功能

---

14. Quadrant Chart（象限图）#

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

语法模板：

Rendering diagram...

关键语法：

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

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

---

15. User Journey（用户旅程图）#

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

语法模板：

Rendering diagram...

关键语法：

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

推荐尺寸： -w 1000 -H 500

---

主题配置#

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

主题说明适用场景default默认蓝色调通用forest绿色调自然/环保主题dark暗色背景暗色文档/演示neutral黑白灰正式文档/打印

Frontmatter 方式设置主题：

Rendering diagram...

---

复杂图表拆分策略#

情况策略流程图节点 >15按阶段拆成 2-3 张子流程图时序图参与者 >8按场景拆分（如登录流程、数据流程）类图类 >10按模块/包拆分ER 图实体 >8按业务域拆分思维导图 >4 层按主分支拆成独立思维导图

---

快速参考：mmdc 常用命令#

bash

# 基本 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）：

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，语法可能变化