mermaid-diagrams

Mermaid 图表

概述

Mermaid 是一款基于 JavaScript 的图表工具，可将受 Markdown 启发的文本定义渲染为 SVG 图表。它支持在 Markdown 文件中直接绘制流程图、时序图、ER 图、类图、状态图、甘特图、饼图、思维导图和 Git 图。

**适用场景：**记录系统架构、可视化数据模型、说明请求流程、创建项目时间线，以及在 GitHub/GitLab README 或文档站点中嵌入图表。

**不适用场景：**需要像素级精确的设计模型、交互式仪表板，或需要自定义插画或超出层级／关系结构的复杂空间布局的图表。

快速参考

图表	声明	要点
流程图	flowchart TD	方向：TB、TD、BT、RL、LR。支持子图
时序图	sequenceDiagram	参与者、消息、循环、alt/opt/par 块
ER 图	erDiagram	鸟爪表示法、PK/FK/UK 属性
类图	classDiagram	UML 关系、可见性修饰符、注释
状态图	stateDiagram-v2	状态转换、复合状态、分叉／汇合、选择
甘特图	gantt	分区、带日期／时长的任务、里程碑
饼图	pie	带数值的标签，可选标题
思维导图	mindmap	基于缩进的层级结构、多种节点形状
Git 图	gitGraph	提交、分支、合并、拣选提交、标签
架构图	architecture-beta	分组中的服务、定向边（T/B/L/R）
块图	block-beta	列布局、块箭头、嵌套块
时间线	timeline	含事件的时间段、用于分组的分区
桑基图	sankey-beta	节点间的流量、类似 CSV 的数据格式
XY 图表	xychart-beta	带 x/y 轴的柱状图和折线图
象限图	quadrantChart	带标签坐标轴和数据点的四象限图
看板	kanban	带任务卡片、负责人和优先级的列
数据包图	packet-beta	带位范围字段的网络数据包结构
需求图	requirementDiagram	需求、元素和验证链接
C4 图	C4Context	C4 模型：上下文、容器、组件、部署

常见错误

错误	正确写法
使用 graph 而不是 flowchart	使用 flowchart 表示子图边和较新的功能
序列中的箭头后缺少空格	Alice->>Bob: msg，而不是 Alice->>Bob:msg
ER 图中的基数顺序错误	先写左侧基数，再写连线，最后写右侧基数
在子图/循环/alt 后忘记写 end	每个块关键字都必须有对应的 end
将保留字用作节点 ID	将保留字括在引号中，或使用别名
代码块未指定语言标签	始终使用 ```mermaid 作为语言说明符
混用 v1 和 v2 状态图语法	对当前功能始终使用 stateDiagram-v2
标签中有特殊字符但未加引号	将包含特殊字符的标签括在双引号中
甘特图中缺少 dateFormat	定义任务前始终声明 dateFormat
思维导图使用制表符而非空格	思维导图缩进必须使用空格，不能使用制表符

委派

• 图表发现与探索：使用 Explore Agent 在代码库中查找现有图表
• 图表审查：使用 Task Agent 对照代码验证图表准确性
• 架构文档：使用 code-reviewer Agent 检查文档质量

参考资料

• 流程图：节点、边、子图、方向和样式
• 序列图：参与者、消息、激活和控制流
• 实体关系图：实体、属性和基数
• 类图：类、方法、关系和注释
• 其他图表：甘特图、饼图、思维导图、状态图和 Git 图
• 架构图、块图、时间线图、Sankey 图、XY 图表、象限图、看板图、数据包图、需求图和 C4 图