Mermaid Charts 全图表画图技能

使用 Mermaid 语法生成流程图、时序图、类图等多种图表，支持输出 PNG 和交互型 HTML 格式。

Install

openclaw skills install @harrot90-code/mermaid-charts

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
`-c`	JSON 配置文件	无

工作流程：

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

格式二：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 节点)	800	600	标准 4:3
Flowchart (LR, ≤6 节点)	1000	500	横向 2:1
Flowchart (大型 >10 节点)	1200	800	加大画布
Sequence Diagram (≤5 参与者)	800	600	标准
Sequence Diagram (>5 参与者)	1200	600	加宽
Class Diagram	1000	700	略宽
State Diagram	800	600	标准
ER Diagram	1000	700	略宽
Gantt Chart (≤10 任务)	1000	500	横向 2:1
Gantt Chart (>10 任务)	1200	700	加高
Pie Chart	700	700	1:1 正方形
Mindmap	1000	700	略宽
Timeline (≤5 时期)	1000	500	横向
Timeline (>5 时期)	1200	600	加宽
Git Graph	1000	500	横向
Sankey Diagram	1000	600	略宽
XY Chart	800	600	标准 4:3
Quadrant Chart	700	700	1:1 正方形
User Journey	1000	500	横向
Block Diagram	800	600	标准

图表类型详解

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 --> max`	X 轴数值范围
`y-axis "title" min --> max`	Y 轴范围
`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
  }
}

⚠️ 通用注意事项

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