mermaid-graph-writer

Mermaid 图表编写器

编写准确、结构清晰的 Mermaid 图表。根据内容选择最合适的图表类型，使用正确的语法，并生成既便于人类阅读（渲染后），也便于 Agent 理解（文本 DSL）的图表。

---

适用场景

✅ 适用于：

• 根据描述或数据创建任意 Mermaid 图表
• 为可视化需求选择合适的图表类型
• 将文字版决策树重构为 Mermaid 流程图
• 建模系统架构、协议、状态机和数据模型
• 将时间相关知识编码为时间线图

❌ 不适用于：

• 将 Mermaid 渲染或导出为 PNG/SVG/PDF（使用 mermaid-graph-renderer）
• ASCII 艺术字或 Unicode 方框图（使用 diagramming-expert）
• 基于 GUI 的设计工具（如 Figma）

---

图表类型选择

flowchart TD
  A{What are you modeling?} -->|Branching logic| B[flowchart]
  A -->|Request/response over time| C[sequenceDiagram]
  A -->|States and transitions| D[stateDiagram-v2]
  A -->|Entities and relationships| E[erDiagram]
  A -->|Chronological evolution| F[timeline]
  A -->|Concept hierarchy| G[mindmap]
  A -->|Time-sequenced tasks| H[gantt]
  A -->|Proportions| I[pie]
  A -->|2-axis comparison| J[quadrantChart]
  A -->|Branch/merge history| K[gitGraph]
  A -->|Type hierarchy / OO| L[classDiagram]
  A -->|User experience steps| M[journey]
  A -->|Quantity flows| N[sankey-beta]
  A -->|Numeric data| O[xychart-beta]
  A -->|System components| P[block-beta]
  A -->|Infrastructure| Q[architecture-beta]
  A -->|Task board| R[kanban]
  A -->|Requirements traceability| S[requirementDiagram]
  A -->|System context / containers| T[C4Context]
  A -->|Protocol packets / headers| U[packet-beta]
  A -->|Multi-axis comparison| V[radar]
  A -->|Hierarchical proportions| W[treemap]
  A -->|Code-style sequences| X[zenuml]

快速参考

内容	类型	方向
决策树 / 流程	flowchart TD	决策使用自上而下，流程使用 LR
API 协议 / Agent 通信	sequenceDiagram	始终垂直（隐式）
生命周期 / 状态机	stateDiagram-v2	自动布局
数据库 / 数据模型	erDiagram	自动布局
“何时发生了什么变化”	timeline	按时间顺序水平排列
分类体系 / 头脑风暴	mindmap	从根节点向外辐射
项目进度安排	gantt	水平时间线
类别占比	pie	圆形
投入与影响	quadrantChart	二维散点图
Git 分支策略	gitGraph	水平排列
类 / 接口层级结构	classDiagram	自动布局
带满意度的用户流程	journey	水平分段
类别间流量	sankey-beta	从左向右流动
柱状图 / 折线图	xychart-beta	标准坐标轴
系统模块布局	block-beta	基于网格
云 / 基础设施拓扑	architecture-beta	服务分组
任务状态列	kanban	基于列
需求可追溯性	requirementDiagram	自动布局
系统上下文 / 容器	C4Context / C4Container	分层（5 个子类型）
协议数据包 / 标头	packet-beta	水平位布局
多轴评分	radar	放射状坐标轴
层级占比	treemap	嵌套矩形
代码风格序列	zenuml	垂直（插件）

---

深入了解流程图（最常见）

方向

• TD / TB — 自上而下（最适合决策树）
• LR — 从左到右（最适合流程、流水线）
• BT — 自下而上（较少使用，适用于依赖关系图）
• RL — 从右到左（较少使用）

节点形状

[text]       Rectangle (default action)
(text)       Rounded rectangle (soft step)
{text}       Diamond (decision/condition)
([text])     Stadium/pill (start/end)
[[text]]     Subroutine (subprocess)
[(text)]     Cylinder (database/storage)
((text))     Circle (event/trigger)
>text]       Flag (async/signal)
{{text}}     Hexagon (preparation)
[/text/]     Parallelogram (input/output)
[\text\]     Reverse parallelogram
[/text\]     Trapezoid
[\text/]     Reverse trapezoid

边的样式

-->          Solid arrow (main flow)
---          Solid line (association)
-.->         Dotted arrow (optional/async)
==>          Thick arrow (emphasis/critical path)
--text-->    Labeled edge
~~~          Invisible link (layout control only)

子图

flowchart TD
  subgraph Backend
    A[API] --> B[DB]
  end
  subgraph Frontend
    C[UI] --> D[State]
  end
  C -->|fetch| A

---

序列图要点

消息

->>    Solid arrow (sync request)
-->>   Dotted arrow (async response)
-)     Open arrow (async fire-and-forget)
-x     Cross (failed/rejected)

块

activate / deactivate    Lifeline activation
alt / else / end         Conditional branching
loop / end               Repetition
par / and / end          Parallel execution
critical / end           Critical section
break / end              Break-out flow
rect rgb(...)  / end     Background highlight

编号

在第一行后添加 autonumber，即可为所有消息自动编号。

---

状态图要点

[*] --> State1           Start transition
State1 --> State2        Named transition
State1 --> State2: event Labeled transition
State2 --> [*]           End transition

state State1 {          Nested states
  [*] --> SubA
  SubA --> SubB
}

state fork <<fork>>      Fork pseudostate
state join <<join>>      Join pseudostate
state choice <<choice>>  Choice pseudostate

---

ER 图要点

基数

||--||    Exactly one to exactly one
||--o{    One to zero-or-many
}o--o{    Zero-or-many to zero-or-many
||--|{    One to one-or-many

属性

erDiagram
  USER {
    int id PK
    string name
    string email UK
  }
  ORDER {
    int id PK
    int user_id FK
    date created_at
  }
  USER ||--o{ ORDER : places

---

编写原则

1. 使用描述性标签，而非代码

• ✅ A[Check if tests pass]
• ❌ A[Step 2.3]

2. 方向保持一致

为整个图表选择一个方向。不要在同一张流程图中混用 TD 和 LR。

3. 每张图最多 15 个节点

超过 15 个节点时，应拆分为多张图或使用子图。拥挤的图表还不如不画。

4. 使用子图进行分组

当图表中存在自然分组（前端 / 后端、阶段、团队）时，使用子图进行可视化分组。

5. 为所有决策边添加标签

每条从菱形（{decision}）节点出发的边都必须带有标签：

• ✅ A{Ready?} -->|Yes| B 和 A -->|No| C
• ❌ A{Ready?} --> B 和 A --> C（哪个是“是”？哪个是“否”？）

6. 使用恰当的边样式

• 主流程使用实线箭头
• 可选 / 异步路径使用点状箭头
• 关键路径或强调内容使用粗箭头
• 仅在调整布局时使用不可见连线（~~~）

---

反模式

错误的图表类型

新手：什么内容都用流程图——即使是协议、状态机和数据模型。 专家：根据内容结构选择图表类型。协议用时序图，生命周期用状态图，数据模型用 ER 图。每种图表类型都有其存在的理由，因为流程图无法很好地表达这些结构。

图表过于拥挤

新手：一个图表里有 30 个节点，边还交错在一起。 专家：拆分为概览图和细节图。使用子图。每个图表最多约 15 个节点。

决策边未标注

新手：{Decision} --> A 和 {Decision} --> B——哪个条件会导向哪里？ 专家：始终为从决策菱形引出的边标注：-->|Yes| 和 -->|No|（或 -->|Success| 和 -->|Failure| 等）。

本该用图表呈现的文字说明

新手：“首先检查 X。如果是 X，就执行 A，否则执行 B。然后，如果 A 成功，就执行 C，否则重试 A。” 专家：这就是流程图。把它画出来。正式的图形既更精确，也更易读。

---

参考资料

• references/diagram-types.md — 查阅所有 23 种 Mermaid 图表类型的完整语法、功能和示例：时间线、思维导图、象限图、桑基图、XY 图表、块图、架构图、看板、饼图、Git 图、类图、旅程图、requirementDiagram、C4（5 种子类型）、packet-beta、雷达图、矩形树图和 zenuml
• scripts/validate_mermaid.py — 验证任意文件中的 Mermaid 语法：检查图表类型声明、代码围栏是否匹配以及结构是否正确