mermaid-diagrams-expert

Mermaid 图表专家

目的

当结构、关系、顺序或架构用图示表达会更清晰时，为软件文档创建易于维护的 Mermaid 图表：流程图、时序图、类图、ER 图、C4 图、架构图、状态图、git 图、甘特图、图表、看板图、数据包图、维恩图和石川图。使用对版本敏感或处于测试阶段的语法前，先确认目标渲染器和 Mermaid 版本。根据所选图表类型加载所需参考资料。

核心原则

1. 只有当读者需要理解关系、顺序、状态、拓扑、分支或依赖关系时，才使用图表。简单事实用文字说明更好。
2. Mermaid 语法具有可移植性，渲染器的行为则不然。将目标渲染器视为兼容性约束。
3. 先建模，再设置样式。首先确定节点、边、标签、方向和边界。
4. 使用对版本敏感的语法前，先确认目标渲染器和版本。
5. 如果没有可用的渲染器，应说明图表未经渲染，而不是暗示已检查。
6. 图表应保持精简易读。实体数量达到约 10 到 15 个时，应拆分图表，而不是缩小字体。
7. 切勿将专有架构、凭据或个人数据发送到在线渲染器。
8. 图表标签或周边文档中不得使用 em dash。

授权模型

用户指令	授权范围
“画出这个图”	为指定结构生成 Mermaid 代码块
“在 README 中添加图表”	添加图表以及文件所需的周边说明
“检查能否渲染”	如果已有渲染器，则进行渲染
“安装 Mermaid CLI 并检查”	单独授权安装该工具
“把这个放到在线编辑器中”	只有在说明要发送的内容后才可执行，且绝不能用于机密内容

安装渲染器、图标包或 Docker 会改变环境，需单独授权。不得擅自设置这些工具来验证图表。

步骤 0：判断图表是否值得使用

只有当读者需要理解关系、顺序、状态、拓扑、分支或依赖关系时，才使用图表。不要强行用图表表达简单事实，文字说明会更清楚。

对于持久化文档，应将目标渲染器视为兼容性约束。

步骤 1：选择图表类型

阅读 references/diagram-type-selection.md。根据所建模的结构选择合适的图表：

结构	首选类型
流程或决策树	流程图
随时间变化的交互	时序图
领域对象及其关系	类图或 ER 图
服务架构	C4 图或架构图
云端和部署拓扑	架构图
生命周期	状态图
仓库历史记录	Git 图
带依赖关系的日程安排	甘特图
简单比例	饼图或 xychart
工作阶段和交接	看板图
按位范围划分的数据包布局	数据包图
集合重叠	维恩图
因果关系	石川图
层次结构或头脑风暴	思维导图、矩形树图或时间线

只有在专用图表的语义能帮助读者理解时，才使用它。对于维恩图、石川图、看板图、数据包图、雷达图、矩形树图、思维导图、时间线、用户旅程图和桑基图，请先阅读 references/new-diagrams.md。

步骤 2：确认兼容性

如果图表将保存在仓库中，请确定目标渲染器和 Mermaid 版本。如果渲染器未知，应避免使用已知对版本敏感的语法，并说明所采用的假设。

使用测试版语法、较新的指令、主题或图标包前，请阅读 references/renderer-adapters.md。对于持久化文档中的测试版图表类型，必须明确指定备用方案或固定版本。

步骤 3：先建模，再设置样式

首先定义节点、边、标签、方向和边界。标签应简短且含义明确。使用子图或 C4 边界明确标出归属和系统边界。

在结构正确之前，尽量减少样式设置。只有在纯文本形式下关系已足够清晰后，才添加颜色和布局。

步骤 4：验证

根据需要阅读 references/validation-and-rendering.md、references/security.md 和图表类型参考。检查：

• 语法能否通过目标渲染器解析；
• 标签是否明确无歧义，并在需要时加引号；
• 方向和边的语义是否正确；
• ID 是否稳定且唯一；
• 特殊字符是否已安全加引号；
• 对于生命周期较长的文档，测试版语法是否有回退方案或固定版本；
• 图表在预期尺寸下是否易于阅读；
• 是否嵌入了机密、凭据或个人数据。

如果有可用的渲染器，请进行渲染测试。否则执行静态语法检查，并明确标注结果未经渲染。

步骤 5：按目标位置交付

对于聊天，提供 Mermaid 代码块，并在有用时附上简短说明。对于 README、Wiki 或 PR 内容，保留完全一致的围栏代码块及任何必要的周边说明。

故障处理

图表无法渲染或目标环境拒绝时：

1. 报告实际的解析器或渲染器错误，而不是描述预期外观；
2. 对照相关参考检查图表类型关键字，因为拼写错误会导致明确报错，而非降级处理；
3. 检查配置和主题选项名称，因为无法识别的选项通常会被静默忽略，导致图表看似渲染成功，实际却未应用预期样式；
4. 通过拆分图表来简化，而不是缩小文本；
5. 如果目标渲染器不支持所需功能，请说明这一点，并提供广泛支持的语法；
6. 如果图表只经过检查而未渲染，绝不要声称它已渲染。

正常退出且生成了输出文件，表示语法已通过解析。其他情况都意味着应先修复问题，再将图表作为成品提交。

反面模式

• 假定各个平台对 Mermaid 的支持完全相同。
• 不检查渲染器及版本支持情况，就使用新语法或测试版语法。
• 在生命周期较长的文档中使用测试版图表，却不提供回退方案或固定版本。
• 把每个段落都转换成图表。
• 在节点中塞入过多文字。
• 在示例中嵌入机密、凭据或真实个人数据。
• 图表只经过检查而未渲染，却声称它已渲染。
• 凭记忆编造关键字、配置键或版本支持情况。
• 在文档中使用长破折号。

捆绑参考资料

加载 references/diagram-type-selection.md、所选图表类型的参考资料，以及请求的语法所需的任何高级功能参考资料：

• references/diagram-type-selection.md：根据建模对象选择合适图表类型的决策指南。
• references/flowcharts.md：流程图语法、结构和常见模式。
• references/sequence-diagrams.md：时序图语法、角色／参与者模式和常见惯例。
• references/class-diagrams.md：类图语法、关系和常见模式。
• references/erd-diagrams.md：ER 图语法、基数和常见模式。
• references/c4-diagrams.md：C4 模型语法、上下文／容器／组件边界和常见模式。
• references/architecture-diagrams.md：架构图语法、云端／部署拓扑和常见模式。
• references/misc-diagrams.md：状态图、Git 图、甘特图以及饼图／条形图。
• references/new-diagrams.md：看板图、分组图、维恩图、鱼骨图、雷达图、树状图、思维导图、时间线、旅程图、桑基图和其他专用类型，以及版本最低要求和 Beta 规则。
• references/security.md：机密信息、个人数据、注入风险和安全验证边界。
• references/advanced-features.md：较新的语法、指令、主题和版本相关功能。
• references/renderer-adapters.md：目标渲染器和版本兼容性检查。
• references/validation-and-rendering.md：交付前如何验证图表、常见问题、导出选项，以及图表可直接渲染的位置。
• references/proactive-trigger.md：何时在未收到请求时主动使用图表，以及何时应保持克制。
• references/verification-and-failure.md：验证和故障处理的通用原则。