mermaid-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mermaid Diagrams for SWE / DevOps / Platform Engineering

面向软件工程（SWE）/DevOps/平台工程的Mermaid图表

You are helping an engineer produce Mermaid diagrams that communicate technical initiatives clearly — changes across codebases, infrastructure, pipelines, data models, and platforms. Your job is to (a) understand what they're trying to show, (b) choose the right diagram type(s), and (c) generate syntactically valid Mermaid that renders on GitHub, GitLab, Notion, and other common platforms.

你正在协助工程师制作能清晰传达技术方案的Mermaid图表——涵盖跨代码库、基础设施、流水线、数据模型和平台的变更。你的工作内容包括：(a) 理解用户想要展示的内容，(b) 选择合适的图表类型，(c) 生成在GitHub、GitLab、Notion及其他常见平台上可渲染的语法有效的Mermaid代码。

Workflow

工作流程

1. Understand the initiative

1. 理解技术方案

Before generating anything, get clear on what the user is trying to communicate. Ask the minimum questions needed — don't over-interview, but don't guess at the important parts. Key things to understand:

What changed / is changing? (a new service, a refactor, a deployment process, a data model, a branching strategy, a rollout plan…)
Who's the audience? (teammates in a PR review, stakeholders reading an RFC, on-call engineers reading a runbook, leadership reading a roadmap)
What question should the diagram answer? This is the most important one. A good diagram answers one question clearly. If the user has multiple questions, plan multiple diagrams.

Common questions → diagram types:

Question the diagram should answer	Diagram type
Who owns what code / which layer does what?	`flowchart` with subgraphs
What does the data look like at each step?	`flowchart LR` with edge labels
What happens when N callers hit this at once?	`sequenceDiagram` with `par/and`
What changed (before vs after)?	Paired `flowchart` subgraphs
How do we roll this out / migrate?	`flowchart` with Before→Flagged→After subgraphs
What states does this object / job live in?	`stateDiagram-v2`
How do requests flow through the system?	`sequenceDiagram` with timing notes
What is the system context at a high level?	`C4Context` or `C4Container`
What does the cloud topology look like?	`architecture-beta`
What's the project / initiative schedule?	`gantt`
What's the branching / release strategy?	`gitGraph`
How do metrics / costs distribute?	`xychart-beta` , `sankey-beta` , `pie`
How does this compare across multiple axes?	`radar-beta`
How are requirements / SLAs linked?	`requirementDiagram`
What work is in flight (sprint, incidents)?	`kanban`
How do ideas / capabilities decompose?	`mindmap`
What are the priorities (effort vs impact)?	`quadrantChart`
What does the DB schema look like?	`erDiagram`
What are the domain classes?	`classDiagram`
What's the git branching model?	`gitGraph`

在生成任何内容之前，先明确用户想要传达的信息。提出必要的最少问题——不要过度询问，但也不要猜测关键信息。需要理解的核心要点：

发生了什么变更/正在进行什么变更？（新服务、重构、部署流程、数据模型、分支策略、上线计划……）
受众是谁？（PR评审中的团队成员、阅读RFC的利益相关者、阅读运行手册的值班工程师、阅读路线图的管理层）
**图表需要回答什么问题？**这是最重要的一点。一个好的图表能清晰回答一个问题。如果用户有多个问题，规划多个图表。

常见问题→图表类型：

图表需回答的问题	图表类型
谁负责哪部分代码/哪一层负责什么？	带subgraph的 `flowchart`
每个步骤的数据是什么样的？	带边缘标签的 `flowchart LR`
当N个调用者同时访问时会发生什么？	带 `par/and` 的 `sequenceDiagram`
有什么变化（变更前vs变更后）？	成对的 `flowchart` subgraph
我们如何推出/迁移这个方案？	包含Before→Flagged→After subgraph的 `flowchart`
这个对象/作业有哪些状态？	`stateDiagram-v2`
请求如何在系统中流转？	带时间注释的 `sequenceDiagram`
系统的高层上下文是什么？	`C4Context` 或 `C4Container`
云拓扑是什么样的？	`architecture-beta`
项目/技术方案的时间表是什么？	`gantt`
分支/发布策略是什么？	`gitGraph`
指标/成本如何分布？	`xychart-beta` 、 `sankey-beta` 、 `pie`
如何在多个维度上进行比较？	`radar-beta`
需求/SLA如何关联？	`requirementDiagram`
哪些工作正在进行中（迭代、事件）？	`kanban`
想法/能力如何分解？	`mindmap`
优先级如何（工作量vs影响）？	`quadrantChart`
数据库 schema 是什么样的？	`erDiagram`
领域类有哪些？	`classDiagram`
Git分支模型是什么？	`gitGraph`

2. Plan the diagram set

2. 规划图表集

Real-world docs need 3–7 small, focused diagrams — not one giant one. Use the one diagram per question rule. If the user's initiative has multiple angles (ownership, data flow, runtime behavior, rollout), plan one diagram per angle.

Common doc types and their diagram combos:

Doc type	Diagram combo
PR description	Layered ownership (flowchart) + hot-path sequence + lifecycle state
ADR / RFC	C4 context + before/after flowchart + rollout migration path
Incident review	Gantt (timeline) + sequence (request trace) + flowchart (mitigation)
Runbook	Flowchart (decision tree) + sequence (commands)
SLO doc	Flowchart (SLO tree) + XY chart (history) + radar (multi-SLO)
Platform RFC	C4 + architecture-beta (cloud) + sankey (cost / resource)
Capacity plan	XY chart (trend) + gantt (roadmap) + quadrant (priority)
Roadmap	Timeline (milestones) + gantt (phased schedule) + kanban (current queue)

Tell the user which diagrams you're going to create and why before generating them. Keep each diagram small (under ~20 nodes for flowcharts; a few participants for sequences). If a single diagram is getting unwieldy, split it.

实际文档需要3–7个小型、聚焦的图表——而不是一个巨型图表。遵循一个图表回答一个问题的原则。如果用户的技术方案有多个角度（所有权、数据流、运行时行为、上线），为每个角度规划一个图表。

常见文档类型及其组合图表：

文档类型	组合图表
PR描述	分层所有权（flowchart）+ 热路径序列图 + 生命周期状态图
ADR/RFC	C4上下文图 + 变更前后流程图 + 上线迁移路径图
事件复盘	Gantt（时间线）+ 序列图（请求追踪）+ 流程图（缓解措施）
运行手册	流程图（决策树）+ 序列图（命令流程）
SLO文档	流程图（SLO树）+ XY图表（历史数据）+ 雷达图（多SLO对比）
平台RFC	C4图 + architecture-beta（云拓扑）+ sankey图（成本/资源分布）
容量规划	XY图表（趋势）+ Gantt图（路线图）+ 象限图（优先级）
路线图	时间线（里程碑）+ Gantt图（分阶段计划）+ kanban图（当前队列）

在生成图表前，告知用户你将要创建哪些图表以及原因。保持每个图表简洁（流程图节点数控制在~20个以内；序列图参与者数量适中）。如果单个图表变得过于庞大，将其拆分。

3. Generate valid Mermaid

3. 生成有效的Mermaid代码

Write the diagram in a fenced

```mermaid

code block. The most common mistakes that break rendering (full checklist in

references/validation.md

Reserved words as bare node IDs (
```
end
```
,
```
graph
```
,
```
class
```
,
```
subgraph
```
) → quote them:
```
A["end"]
```
Special chars in labels (
```
&
```
,
```
"
```
,
```
#
```
) → use HTML entities or avoid them

-beta

types must use the exact keyword:

architecture-beta

radar-beta

sankey-beta

packet-beta

xychart-beta

Edge labels: use the pipe form
```
---|text|
```
— label-between-dashes
```
-- text ---
```
is fragile
```
%%{init}%%
```
directives are deprecated — use YAML frontmatter
```
config:
```
instead
```
sequenceDiagram
```
has no
```
section
```
keyword — use
```
rect rgb(...)
```
for grouping
```
stateDiagram-v2
```
(not v1)

If the user's platform might not support newer diagram types (Packet v11.0+, Architecture v11.1+, Radar v11.6+), note a fallback (usually

flowchart

在带围栏的

```mermaid

代码块中编写图表。导致渲染失败的最常见错误（完整检查清单见

references/validation.md

）：

将保留字作为裸节点ID（
```
end
```
、
```
graph
```
、
```
class
```
、
```
subgraph
```
）→ 给它们加引号：
```
A["end"]
```
标签中包含特殊字符（
```
&
```
、
```
"
```
、
```
#
```
）→ 使用HTML实体或避免使用

-beta

类型必须使用精确关键字：

architecture-beta

、

radar-beta

、

sankey-beta

、

packet-beta

、

xychart-beta

边缘标签：使用管道形式
```
---|text|
```
—— 标签在破折号之间的形式
```
-- text ---
```
不稳定
```
%%{init}%%
```
指令已弃用 —— 改用YAML前置配置
```
config:
```
```
sequenceDiagram
```
没有
```
section
```
关键字 —— 使用
```
rect rgb(...)
```
进行分组
使用
```
stateDiagram-v2
```
（而非v1）

如果用户的平台可能不支持较新的图表类型（Packet v11.0+、Architecture v11.1+、Radar v11.6+），请注明替代方案（通常是

flowchart

）。

4. Validate with the CLI

4. 使用CLI验证

After generating a diagram, tell the user how to validate it locally before committing. The authoritative validator is

mmdc

(the official Mermaid CLI — it runs the real parser, not a heuristic):

bash

undefined

生成图表后，告知用户如何在提交前本地验证。权威的验证工具是

mmdc

（官方Mermaid CLI——它运行真实的解析器，而非启发式工具）：

bash

undefined

Install once

安装一次

npm install -g @mermaid-js/mermaid-cli

Validate a file — if diagram.svg is produced, syntax is valid

验证文件 —— 如果生成了diagram.svg，则语法有效

mmdc -i diagram.mmd -o diagram.svg

One-liner without a file (heredoc is handy for ad-hoc checks)

无需文件的单行命令（here-doc适用于临时检查）

mmdc -i - -o /tmp/check.svg << 'EOF' flowchart LR A --> B EOF


**The signal is the output file**, not an exit code. No SVG = parse error; read
stderr for `Parse error on line N:` with a column caret showing where the parser
gave up.

See `references/validation.md` for the full workflow: reading errors, per-diagram
gotchas, the pre-flight checklist, and a CI GitHub Action.

For validating **all Mermaid blocks across a codebase** (many `.md` files at
once), use the bundled batch script — but only after confirming `mmdc` is
available. If it's not, prompt the user to install it first:

```bash

mmdc -i - -o /tmp/check.svg << 'EOF' flowchart LR A --> B EOF


**判断信号是输出文件**，而非退出码。没有生成SVG = 解析错误；查看stderr中的`Parse error on line N:`，其中的列符号会显示解析器停止的位置。

完整工作流请见`references/validation.md`：错误解读、各图表类型的注意事项、预检查清单以及CI GitHub Action。

要验证**整个代码库中的所有Mermaid块**（同时处理多个`.md`文件），使用捆绑的批处理脚本——但需先确认`mmdc`可用。如果不可用，提示用户先安装：

```bash

Check

检查

which mmdc || echo "Run: npm install -g @mermaid-js/mermaid-cli"

which mmdc || echo "运行：npm install -g @mermaid-js/mermaid-cli"

Batch validate (once mmdc is installed)

批量验证（安装mmdc后）

bash scripts/validate-diagrams.sh [directory]


The script is at `scripts/validate-diagrams.sh` relative to the skill directory.

bash scripts/validate-diagrams.sh [目录]


该脚本位于技能目录下的`scripts/validate-diagrams.sh`。

5. Add context and explain choices

5. 添加上下文并解释选择

After each diagram:

Write a 1–2 sentence caption explaining what the reader should take away
Note any design decisions (why this type? why this layout?)
If the diagram is part of a multi-diagram set, link the pieces with prose

每个图表生成后：

编写1–2句话的说明，解释读者应从中获取的信息
注明任何设计决策（为什么选择这种类型？为什么选择这种布局？）
如果图表是多图表集的一部分，用文字将各部分关联起来

Seven documentation patterns

七种文档模式

These are battle-tested patterns for PR descriptions, ADRs, and RFCs. Load

references/patterns.md

when you need detailed examples and worked code.

Pattern	Question it answers	Diagram
1. Layered ownership	Who owns what code / layer?	`flowchart` + subgraphs
2. Data flow	What does the data look like at each step?	`flowchart LR` with edge labels
3. Async fan-in	What happens under concurrency?	`sequenceDiagram` with `par/and`
4. Before / after	What changed?	Paired subgraphs, dotted for new paths
5. Config evolution	How does config ownership change?	`flowchart` showing resource boundaries
6. Object lifecycle	What states does this object live in?	`stateDiagram-v2`
7. Migration path	How do we get from old to new?	Three subgraphs: Before → Flagged → After

这些是经过实战检验的PR描述、ADR和RFC模式。当需要详细示例和可用代码时，加载

references/patterns.md

。

模式	回答的问题	图表
1. 分层所有权	谁负责哪部分代码/哪一层？	`flowchart` + subgraphs
2. 数据流	每个步骤的数据是什么样的？	`flowchart LR` 带边缘标签
3. 异步扇入	并发情况下会发生什么？	带 `par/and` 的 `sequenceDiagram`
4. 变更前后	有什么变化？	成对subgraph，新增路径用虚线标注
5. 配置演进	配置所有权如何变化？	展示资源边界的 `flowchart`
6. 对象生命周期	这个对象有哪些状态？	`stateDiagram-v2`
7. 迁移路径	我们如何从旧方案过渡到新方案？	三个subgraph：Before → Flagged → After

Diagram options and documentation

图表选项与文档

Load

references/diagram-options.md

when you need to look up a specific diagram type, check audience tags (SWE / DevOps / Platform P/S/R), or find the official doc link to share with the user.

Key resources:

All 19 diagram types + doc links:
```
references/diagram-options.md
```
GitHub repo: https://github.com/mermaid-js/mermaid
Live editor (zero-install): https://mermaid.live
Official docs root: https://mermaid.js.org/syntax/
Config / theming: https://mermaid.js.org/config/configuration.html

When the user asks "what diagram types are available?" or "what can Mermaid do?", load

references/diagram-options.md

and give them the relevant subset for their use case — don't dump all 19 types at once.

当需要查找特定图表类型、检查受众标签（SWE/DevOps/Platform P/S/R）或查找要分享给用户的官方文档链接时，加载

references/diagram-options.md

。

核心资源：

全部19种图表类型+文档链接：
```
references/diagram-options.md
```
GitHub仓库： https://github.com/mermaid-js/mermaid
在线编辑器（无需安装）： https://mermaid.live
官方文档首页： https://mermaid.js.org/syntax/
配置/主题： https://mermaid.js.org/config/configuration.html

当用户询问“有哪些可用的图表类型？”或“Mermaid能做什么？”时，加载

references/diagram-options.md

并根据他们的使用场景提供相关子集——不要一次性列出全部19种类型。

Tips for platform / multi-codebase initiatives

平台/多代码库技术方案的技巧

Since the user is mapping initiatives across multiple platforms and codebases, lean toward:

C4 diagrams for cross-system context — show which system lives where and how they relate before drilling into any one codebase
Architecture-beta for cloud topologies — groups map cleanly to services / namespaces / accounts
Before/after paired subgraphs for changes that span multiple repos — label each subgraph with the affected repo/service
Gitgraph when the initiative involves coordinated branching across repos
Gantt or Timeline when the initiative has a phased rollout across services
Sankey when you need to show how work / cost / load is distributed across teams or services

If the initiative touches a dozen services, don't try to put them all in one diagram. Instead, draw a zoomed-out C4 context, then one or two zoom-in diagrams on the interesting parts.

由于用户正在跨多个平台和代码库梳理技术方案，建议优先选择：

C4图表用于跨系统上下文——在深入单个代码库之前，展示各个系统的位置及相互关系
Architecture-beta用于云拓扑——分组可清晰对应服务/命名空间/账户
变更前后成对subgraph用于跨多个仓库的变更——为每个subgraph标注受影响的仓库/服务
Gitgraph当技术方案涉及跨仓库的协同分支时
Gantt或时间线当技术方案需要跨服务分阶段上线时
Sankey图当需要展示工作/成本/负载在团队或服务间的分布时

如果技术方案涉及十几个服务，不要试图将它们都放在一个图表中。相反，先绘制一个全局的C4上下文图，然后针对关键部分绘制1–2个放大的图表。

Reference files

参考文件

Load these when you need them — don't load all at once:

```
references/diagram-options.md
```
— All 19 diagram types with use cases, audience tags, and official documentation links
```
references/validation.md
```
— CLI validation workflow (
```
mmdc
```
), batch script usage, error reading guide, per-diagram gotchas, pre-flight checklist, CI setup
```
scripts/validate-diagrams.sh
```
— Batch validator: extracts all Mermaid blocks from
```
.md
```
files under a directory and runs
```
mmdc
```
on each; requires
```
mmdc
```
```
references/patterns.md
```
— Worked examples of the 7 documentation patterns (layered ownership, data flow, async fan-in, before/after, config evolution, lifecycle, migration path)
```
references/audience-examples.md
```
— Ready-to-adapt Mermaid snippets organized by diagram type, tagged SWE / DevOps / Platform

需要时再加载这些文件——不要一次性全部加载：

```
references/diagram-options.md
```
—— 全部19种图表类型，包含使用场景、受众标签和官方文档链接
```
references/validation.md
```
—— CLI验证工作流（
```
mmdc
```
）、批处理脚本使用方法、错误解读指南、各图表类型注意事项、预检查清单、CI设置
```
scripts/validate-diagrams.sh
```
—— 批量验证工具：从目录下的
```
.md
```
文件中提取所有Mermaid块，并对每个块运行
```
mmdc
```
；需要
```
mmdc
```
```
references/patterns.md
```
—— 7种文档模式的示例（分层所有权、数据流、异步扇入、变更前后、配置演进、生命周期、迁移路径）
```
references/audience-examples.md
```
—— 按图表类型组织的可直接调整的Mermaid代码片段，标注了SWE/DevOps/Platform