mermaid-diagram

Mermaid 图表创建器

生成 .mmd 文件（或在文档中嵌入内容时，在 .md 文件中使用带围栏的 ```mermaid 代码块）。

参考文件（按需加载）

文件	加载时机……
references/types/<type>.md	选择图表类型后（步骤 6）。包含该类型的完整语法、示例、布局提示、换行规则和常见问题。
references/syntax-pitfalls.md	渲染失败或需要调试语法时。涵盖引号规则、<br> 兼容性对照表（第 9 节）、保留字和常见错误。
references/mermaid-theme.md	唯一的主题文件。 深色／浅色模式配色指南、classDef 语义样式方案（trigger、success、error、ai、decision），以及各图表类型的支持说明。
references/render_mermaid.sh	渲染脚本。通过 bash 调用，而非读取。请参阅下方的“渲染与验证”。
references/examples/	经过验证的 .mmd 示例（architecture.mmd、sequence-api.mmd）。可供参考，或用于对照已验证的模式检查语法。

自定义

若要自定义品牌样式，请编辑 references/mermaid-theme.md——这是所有主题设置（语义节点样式和深色／浅色模式配色指南）的唯一事实来源。

---

核心理念

图表应该提出论证，而非单纯展示。

图表不是经过排版的文本。它是一种视觉论证，能够展示文字本身无法表达的关系、因果和流程。形状本身就应该体现含义。

同构测试：如果移除所有文本，仅凭结构能否传达概念？如果不能，就重新设计。

教育测试：有人能否从图表中学到具体内容，还是图表只是在给方框贴标签？好的图表能传授知识——它会展示实际格式、真实事件名称和具体示例。

不佳（单纯展示）	良好（提出论证）
5 个带标签的同等方框	每个概念的形状都与其行为相呼应
卡片网格布局	视觉结构与概念结构相匹配
用图标装饰文本	形状本身就体现含义
所有内容都用相同的容器	不同概念使用不同的视觉表达方式

---

设计流程

步骤 0：评估深度和受众

在开始之前，先确定此图表需要达到的详细程度：

• 简单／概念性：抽象形状、标签和关系。适用于解释思维模型、受众已了解细节，或概念本身就是抽象概念的情况。
• 全面／技术性：具体示例、代码片段和真实数据。适用于绘制真实系统、创建教育内容或展示技术集成方式的情况。

简单图表	全面图表
通用标签：“输入” → “处理” → “输出”	展示输入／输出的实际形式
命名方框：“API”、“数据库”、“客户端”	命名方框 + 实际请求／响应
“事件”或“消息”标签	规范中的真实事件／消息名称
约 30 秒即可讲解	约 2–3 分钟的教学内容
读者了解结构	读者了解结构和细节

根据受众匹配信息密度：

受众	节点数	详细程度
高管／概览	5–7	高层级方框，无属性
技术文档	10–15	子图、边标签、证据材料
深度参考	15–20，然后拆分	完整属性、注释、配套文件

当同一系统需要面向不同受众时，应分别创建图表，而不是试图用一张图表满足所有人的需求。

步骤 1：调研（仅适用于综合图表）

绘制任何技术图表之前，先调研实际规范。

如果要绘制协议、API 或框架的图表：

1. 查找实际的 JSON／数据格式
2. 找到真实的事件名称、方法名称或 API 端点
3. 弄清各部分实际如何连接
4. 使用真实术语，而非通用占位符

错误：「协议」→「前端」
正确：「AG-UI 流式传输事件（RUN_STARTED、STATE_DELTA、A2UI_UPDATE）」→「CopilotKit 通过 createA2UIMessageRenderer() 渲染」

步骤 2：深入理解

阅读内容。针对每个概念，思考：

• 这个概念做什么？（而不是它是什么）
• 各个概念之间有什么关系？
• 核心的转换或流程是什么？
• 人们需要看到什么才能理解它？（而不只是阅读相关内容）

步骤 3：将概念映射到模式

针对每个概念，找到能反映其行为的视觉模式：

如果概念……	使用此模式
产生多个输出	扇出（单个节点，多条出边）
将多个输入合并为一个	汇聚（多个节点指向一个目标）
具有层级／嵌套结构	树（思维导图或子图嵌套）
是一系列步骤	时间线（时间线图或序列图）
持续循环或改进	螺旋／循环（状态自转换或回边）
将输入转换为输出	流水线（流程图管道）
比较两件事	并排对比（并行子图）
分为多个阶段	间隔／分隔（子图边界）

步骤 4：确保多样性

对于包含多个概念的图表：每个主要概念都必须使用不同的视觉模式。不要使用千篇一律的卡片或网格。

步骤 5：勾勒流程

编写语法之前，先在脑海中梳理视线在图表中的移动路径。图表应呈现清晰的视觉故事。

步骤 6：生成 Mermaid 语法

1. 使用下方的决策矩阵选择图表类型，然后加载 references/types/<chosen-type>.md 以查看完整语法。
2. 编写语法——以 %% 注释块开头，注明图表类型并描述各个部分。
3. 使用有意义的节点 ID（不要用 A、B、C——应使用 authService、dbWrite、userInput）。
4. 添加 classDef 以进行语义样式设置（trigger、success、error、ai、decision）——从 references/mermaid-theme.md（第 2 节）中选取。遵循第 1 节中的颜色选择指南，确保兼容深色／浅色模式。
5. 输出格式：默认创建 .mmd 文件。用户说“嵌入”“添加到文档”“在 README 中”，或目标为 .md 文件时，使用带围栏的 ```mermaid 代码块。

证据材料（综合图表）

加入具体示例，以证明准确性并帮助读者学习：

• 序列图中的注释，用于展示数据载荷和消息格式。
• 使用 <br> 的多行节点标签，作为简洁的内联证据。
• 子图标题，用于标注区域。
• 对于无法放入节点文本的大型载荷或代码片段，提供配套的 .md 文件。

核心原则：展示事物的实际样貌，而不只是名称。

多层缩放（综合图表）

力求同时呈现三个缩放层级：

1. 概览流程——简化展示完整管道（Input → Processing → Output）
2. 分区边界——使用带标签的子图对相关组件进行分组（按职责、阶段或团队）
3. 分区内的细节——各分区中的证据材料和具体示例

拆分大型图表

• 节点数达到约 20 个时，拆分为多个图表。
• 对于复杂系统：每一层使用一个 .mmd 文件（Context → Container → Component）。
• 将密集的子图拆分到单独的文件中，并在说明文字中相互引用。

步骤 7：渲染与验证

运行渲染脚本并验证输出。请参阅下方的渲染与验证部分。

---

图表类型决策矩阵

快速查阅：将你需要的视觉模式与最合适的图表类型匹配，然后打开对应的参考文件。

视觉模式	最合适的图表类型	参考文件
扇出（一对多）	流程图	references/types/flowchart.md
汇聚（多对一）	流程图	references/types/flowchart.md
步骤／交互序列	序列图	references/types/sequence.md
层级／树	思维导图	references/types/mindmap.md
状态机／生命周期	状态图	references/types/state.md
对象结构／关系	类图	references/types/class.md
系统架构／上下文	C4 图	references/types/c4.md
时间线／有序事件	时间线图	references/types/timeline.md
螺旋／循环（环路）	状态图或流程图	references/types/state.md references/types/flowchart.md
并排比较	流程图（并行子图）	references/types/flowchart.md
数据架构／实体关系	ER 图	references/types/er-diagram.md
流量／资源分配	桑基图	references/types/sankey.md

排除的图表类型

请勿使用以下类型——它们缺乏结构化论证能力，或用途过于专门：

类型	排除原因
饼图	仅展示简单百分比；缺乏结构化论证能力
甘特图	专用于项目排期，不适合概念映射
Git 图	仅用于可视化 Git 分支
XY 图	用于定量数据制图，而非结构化图表绘制
用户旅程图	用途过于具体；通常用序列图表示效果更好

---

渲染与验证（强制要求）

渲染方法：

bash .claude/skills/mermaid-diagram-skill/references/render_mermaid.sh <path.mmd> [output.png]

首次运行时会通过 npx 下载 mmdc，可能需要约 30 秒。

迭代流程：

1. 编写 Mermaid 语法。
2. 运行渲染脚本。 3a. 如果 mmdc 因语法错误而失败：阅读错误消息并修复语法。对于最常见的问题，请参阅 references/syntax-pitfalls.md（通常是：特殊字符未加引号、关键字错误、缺少 end）。 3b. 如果 mmdc 成功：查看 PNG 并评估布局。
3. 如果布局不佳：重新组织结构——调整节点/边的声明顺序以改变布局，切换 rankDir（TD ↔ LR），添加或移除子图。
4. 重新渲染 → 重复以上步骤，直到布局能清晰传达概念。

标签加引号规则：只要标签包含括号、逗号、@、/、<、> 或 :，始终使用 ["label text"]，而不是 [label text]。拿不准时就加引号——["My label"] 始终更安全。这一条规则可避免约 50% 的渲染失败。完整列表请参阅 references/syntax-pitfalls.md。

使用 flowchart 而非 graph：始终使用 flowchart TD（现代语法），不要使用 graph TD（旧语法）。graph 不支持子图方向等现代功能。

end 是保留字：如果节点的整个标签是 end，它会被解析为块终止符。始终为其加引号：B["end"]。

无法对元素进行像素级定位。 所有布局改进都来自声明顺序、rankDir、子图和隐藏线，而不是调整坐标。

减少线条交叉——这是自动生成图表的主要视觉质量挑战：

• 声明顺序很重要：布局引擎会根据源码顺序分配层级。按阅读顺序（从上到下或从左到右）声明节点。较早声明的节点会排在更高处或更靠左。
• 尽量减少反向边：每条指向较早节点的“反向”边都会造成交叉。对于循环，请使用状态图，或将反向边隔离在子图中。
• 在源码中将相关节点分组：让同一逻辑组中的节点在代码中相邻。分散声明 → 布局分散 → 出现交叉。
• 将子图用作布局提示：将相关节点放入 subgraph，以约束其位置并避免全局交叉。每个子图都可以定义自己的 direction（例如 direction LR），以解决过于拥挤的问题。
• 减少分支：单个节点有 5 条以上的出边会形成蜘蛛网式布局。插入分发器/分组节点以简化结构。
• 切换方向：如果仍有交叉，尝试切换到正交的 rankDir（TD ↔ LR）。仅此一项通常就能消除大部分交叉。
• 隐藏线：考虑不可见的边是否有助于约束节点位置。

何时停止：语法有效、布局能传达概念、线条交叉已尽量减少、标签没有重叠，且视觉阅读流畅。

---

质量检查清单

概念与深度（技术图表优先检查）：

1. 是否做过调研：查阅了实际规范、格式和事件名称吗？
2. 是否包含证据材料：注释、多行节点标签，以及用于大型载荷的配套 .md 文件？
3. 是否支持多层缩放：概览流程 + 分节子图 + 详细标签？
4. 是否具体而非抽象：使用了真实的 API 名称和事件名称，而不是泛泛的“处理”？
5. 是否具有教育价值：读者能从图表中学到东西吗？

图表设计： 6. 同构测试：视觉结构是否反映了概念的行为？ 7. 论证：图表是否展示了仅靠文字无法表达的内容？ 8. 多样性：每个主要概念是否采用了不同的视觉模式或节点形状？ 9. 图表类型是否经过有意选择（与决策矩阵中的概念模式相匹配）？ 10. 节点 ID 是否易读，而非单个字母？

Mermaid 专项： 11. 是否使用 classDef 进行语义样式设置（触发器、成功、错误、AI、决策）？ 12. 每个 classDef 是否都设置了 fill、stroke 和 color？（绝不能省略 color——深色／浅色模式指南请参阅 references/mermaid-theme.md 第 1 节） 13. 输出格式是否正确（.mmd 还是围栏代码块）？ 14. 是否未使用任何排除的图表类型？（排除类型：饼图、甘特图、Git 图、XY 图、用户旅程图——请参阅上方的决策矩阵） 15. 节点／边的声明顺序是否符合阅读方向（尽量减少连线交叉）？ 16. 是否有节点在没有拆分调度器的情况下连接了 5 条或更多边？ 17. 是否将反向边隔离（在状态图中处理循环，或将其限制在子图内）？

渲染验证（必做）： 18. 是否已验证语法：mmdc 运行时没有错误？ 19. 是否查看了 PNG 并检查布局？ 20. 是否没有重叠的标签或交叉的文字？ 21. 视线是否能自然地沿图表流动？ 22. 是否尽量减少了连线交叉（必要时尝试调整顺序和 rankDir）？

清理 用户对输出满意后，请删除任何临时输出文件，例如 png 或 mmd 文件。