mermaid-diagrams

Mermaid 图表

适用于架构文档的便携式 Mermaid.js 图表工具。不依赖任何博客平台、主题或渲染引擎。图表可通过 CLI 渲染、嵌入 Markdown，或作为 HTML 片段提供。

何时使用

在以下情况下加载此技能：

• 选定 C4 层级和模型后，绘制 C4 流程图近似图；C4 建模决策请使用 c4-diagramming
• 为交互流程制作时序图
• 为流程文档设计流程图
• 为规范构建状态图／类图／ER 图
• 生成需要同时面向 Agent 和人类的场景进行渲染的任何图表
• 审查结构上有效的 Mermaid 图表是否适合作为面向目标受众和输出界面的沟通载体

以下情况请勿加载：

• 纯文本大纲比图表更清晰地表达了关系。
• 目标渲染器无法执行 Mermaid，且没有可用的预渲染方案。

PDF 输出 — 必须预渲染

Mermaid 代码块（mermaid）无法在 Pandoc → HTML → Puppeteer PDF 流程中渲染。该流程会生成不执行 JavaScript 的静态 HTML。

对于任何要输出为 PDF 的图表：

1. 将图表创建为独立的 .mmd 文件
2. 预渲染为 SVG：npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.svg --width 800
3. 选择一种嵌入方式：默认使用原始内联 SVG；如果渲染器会破坏原始 SVG，则使用 base64 数据 URI。
4. 从 SVG 标签中移除写死的 max-width 像素值
5. 使用 flowchart TD（纵向），而不是 flowchart LR（横向）——参见 references/portrait-layout.md
6. 在每个整页图表的前后添加分页 div

请勿在将通过 Pandoc 处理的 Markdown 中保留 ```mermaid 代码块，否则它们会以原始等宽文本形式显示。

完整流程（包括 Puppeteer 设置、SVG 样式修复和 QA 检查清单）请参见 references/pdf-rendering-pipeline.md。

沟通审查

创作前，说明受众、读者任务、目标界面和预期阅读顺序。选择能够满足该任务的最小图表类型和范围。保持抽象层级、节点形状、边的语义、标签、边界处理和视觉层级一致。语法验证和成功渲染是必要条件，但并不足够：即使 Mermaid 图表有效，也可能不是合适的沟通载体，因为图表过于密集、主要路径不明显、混用表达约定，或让读者自行推断不确定性。

为人而非仅为语法测试创建、修改或审查图表时，请加载 references/diagram-communication.md。使用其中的审查记录检查叙述、信号噪声比、标签和图例、不依赖颜色的含义、无障碍备用方案、不确定性以及渲染审查证据。C4 层级／模型归属由 c4-diagramming 负责；架构决策由 software-architecture 负责；完整的无障碍合规性由 web-accessibility 负责。

支持的图表类型

类型	用途	文件
流程图	流程、C4 替代方案、决策树	references/flowchart.md
时序图	交互协议和 API 调用	references/sequence.md
C4 渲染	使用 c4-diagramming 选定 C4 视图后的流程图近似图	references/c4-mermaid.md
纵向布局	面向 PDF／打印的图表绘制——使用 TD 而非 LR、分页、整页图表	references/portrait-layout.md
PDF 渲染流程	从 .mmd → SVG → HTML → PDF 的完整流程，附 QA 检查清单	references/pdf-rendering-pipeline.md
mmdc 间距配置	用于控制图表密度并避免标签重叠的配置	references/mmdc-spacing-config.md

C4 模型指南

Mermaid 支持实验性的原生 C4 语法（C4Context、C4Container、C4Component），但 GitHub 和大多数 Markdown 渲染器均不支持。 GitHub 内置的 Mermaid 渲染器未包含 C4 插件，因此 C4 语法代码块会显示为原始代码，而非图表。请改用以下方法之一：

1. 流程图变通方案（兼容 GitHub）——使用标准 flowchart 语法将 C4 图表转换为流程图：使用子图表示边界，使用带样式的节点框表示 Person/System/Container/Db，并使用带标签的边表示 Rel。完整转换模式请参阅 references/c4-to-flowchart.md。
2. Structurizr DSL——用于绘制真正的 C4 图表。通过 Structurizr CLI 渲染，或导出为 Mermaid SVG。最适合不在 GitHub Markdown 中的正式架构文档。
3. 混合方案——在 Structurizr DSL 中维护完整的 C4 模型，并在 Markdown 中加入基于流程图的近似图表，便于内联阅读。

C4 → 流程图转换模式

C4 元素	流程图对应形式	示例
Person()	[label]（标准矩形）	U[Human User]
System()	带样式的 [label]	GP[GroktoPlan]，搭配 style GP fill:#...
System_Ext()	子图外的 [label]	GIT[Git Providers]
Container()	[label with tech stack]	KG[Knowledge Graph<br/>Python + pgvector]
Db()	[(label)]（圆柱形）	LS[(Live State DB)]
System_Boundary{}	subgraph System["Title"] ... end	嵌套子图
Container_Boundary{}	subgraph Service["Title"] ... end	单个子图
Rel()	-- label --> 或 -.->	AR -- gRPC --> GA
UpdateLayoutConfig()	省略——使用 flowchart LR 或 TB	在标头中设置方向

所有三个 C4 层级的完整示例，请参阅 references/c4-to-flowchart.md。

GitHub 兼容性参考

图表类型	GitHub 是否渲染？	备注
flowchart (TD/LR/BT/RL)	✅	用于所有 C4 变通方案
sequenceDiagram	✅
classDiagram	✅
stateDiagram-v2	✅
erDiagram	✅
gantt	✅
pie	✅
quadrantChart	✅
requirementDiagram	✅
gitgraph	✅
mindmap	✅
timeline	✅
zenuml	✅
sankey	✅
xychart	✅
block	✅
packet	✅
C4Context	❌	需要 C4 插件——会显示为原始代码
C4Container	❌	需要 C4 插件——会显示为原始代码
C4Component	❌	需要 C4 插件——会显示为原始代码
C4Deployment	❌	需要 C4 插件——会显示为原始代码
C4Dynamic	❌	需要 C4 插件——会显示为原始代码

渲染

CLI（mmdc）——用于输出 PDF/SVG/PNG

npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.svg
npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.png
npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.pdf

需要 Puppeteer + Chromium（约 1.7GB）。如需隔离渲染，请使用 Docker 镜像：

docker run --rm -v $(pwd):/data ghcr.io/mermaid-js/mermaid-cli mermaid-cli -i /data/diagram.mmd -o /data/diagram.svg

CDN（HTML）——用于网页内嵌渲染

<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
<div class="mermaid">
flowchart LR
  A-->B
</div>

验证

// Node.js validation
import { parse } from 'mermaid';
try {
  parse('flowchart LR\n  A-->B');
  console.log('Valid');
} catch (e) {
  console.error('Invalid:', e.message);
}

脚本

脚本	用途
scripts/validate-mermaid.sh	使用 Mermaid CLI 验证 .mmd 文件

主题

Mermaid 使用 base 主题，并支持自定义主题变量。请在图表顶部使用 init 指令设置这些变量。完整的、特定版本的变量列表请参阅 Mermaid 文档。

主要主题变量：

• primaryColor、primaryTextColor、primaryBorderColor
• secondaryColor、tertiaryColor
• lineColor、fontFamily、fontSize
• background（外围背景）、mainBkg（元素背景）

反模式

反模式	修正方法
流程图中的 end 使用小写	所有 Mermaid 关键字都区分大小写。End 不等于 end。
短横线后面紧跟 o 或 x，且没有空格	-->o 中需要空格：使用 --o ，或使用显式节点形状
括号内使用引号	使用 ("quoted text")，而不是 ('quoted text')
图表过宽（节点数 >100）	拆分为多个子图，或使用 ELK 布局
混用制表符和空格	仅使用空格。子图缩进 2 个空格。
标签过长且没有换行	在节点中使用 <br/> 或竖线 `
将 SVG 嵌入为数据 URI	改用原始 <svg> 标签——CSS 无法覆盖数据 URI 的 max-width
为 PDF 导出而在 Markdown 中保留 Mermaid 代码块	先预渲染为 SVG。Pandoc 会将 ```mermaid 渲染为纯文本。

可移植性

此技能有意保持与宿主无关。请使用 Agent 的常规机制加载此处列出的参考资料、模板和脚本。不要假设存在特定的配置系统、任务编排器、记忆服务或响应移交格式。

不适用场景

• 如果任务是选择或维护 C4 系统上下文、容器、组件或代码级模型，请使用 c4-diagramming。
• 如果任务涉及架构驱动因素、权衡、决策和适用性证据，而非图表语法或渲染，请使用 software-architecture。
• 如果需要完整的 WCAG/ARIA 合规性检查和辅助技术评估，请使用 web-accessibility；此技能仅提供图表专属的检查和回退方案。