mermaid-diagram

name	mermaid-diagram
version	2.3.2.0
description	为 Markdown 和技术文档选择、编写、审视并离线编译验证 Mermaid 图。当前任务涉及流程、时序、状态、依赖或数据关系，且图比文字或表格更利于理解和评审时使用；不用于装饰文档或替代本应精确定义的契约。

Mermaid Diagram

用图降低关系理解成本，而不是增加文档体积。先确定图要回答的评审问题；如果一句话、短列表或表格更清楚，就不画图。

选择图型

• flowchart：步骤、判断、分支、失败与回退。
• sequenceDiagram：多个参与者之间有时间顺序的调用、消息和响应。
• stateDiagram-v2：对象生命周期、合法状态和转换条件。
• classDiagram：稳定职责、接口关系或模块内部依赖；不展开无关私有成员。
• erDiagram：实体、基数和持久化关系。

同一张图只回答一个主要问题。不要用多张图重复表达同一关系；只有不同图型回答不同评审问题时才同时保留。

编写规则

1. 只保留理解当前问题需要的参与者和关系，不画全量系统。
2. 节点使用稳定的业务、模块或职责名称，避免为画图发明私有类、函数和文件。
3. 主路径必须可走通；被设计触发的关键失败、回退或终止路径不能悬空。
4. 依赖图明确方向、职责和边界；时序图明确请求、响应及失败归属；状态图明确转换条件。
5. 展示方案变化时，用文字标注“新增、变更、移除、保持”，颜色只能辅助表达。
6. 标签简短且含义明确；含空格、标点或特殊字符的标签使用引号。优先使用广泛支持的语法，避免无必要的实验特性和 HTML。
7. 图下文字只解释图中不易表达的依据、约束或结论，不逐节点复述。

复杂图优先拆分评审问题，而不是缩小字号或堆叠更多节点。图的语法正确不代表设计正确；仍需核对它与正文、接口和数据契约是否一致。

转义与易错字符

• 节点 ID 使用简短的 ASCII 字母或数字；业务名称和自然语言放在显示标签中。含括号、冒号、斜杠、引号或箭头等语法字符的标签用双引号包裹，例如 api["GET /orders (v1)"]。
• 引号仍不足以消除歧义时，使用 Mermaid entity code，不猜测反斜杠转义：双引号写作 #quot;，# 写作 #35;；时序消息中的分号写作 #59;。
• 不转义箭头、连线等结构语法。流程图中的小写 end 改为 End；连线后的目标 ID 以 o 或 x 开头时，在连线与 ID 之间留空格，避免被识别为特殊边型。

不同图型的解析规则并不完全相同；遇到复杂文本时缩短标签或移到图下注释，并以编译结果为准。

编译验证

交付前运行 <skill-dir>/scripts/check_mermaid.py。脚本会抽取 Markdown 中全部 mermaid 代码块或读取 .mmd / .mermaid 文件，并使用 Skill 内置的 Mermaid 编译器进行语法和图型解析校验；不生成 SVG。任一图无法编译时返回非零退出码。

python <skill-dir>/scripts/check_mermaid.py docs/design.md
python <skill-dir>/scripts/check_mermaid.py diagrams/flow.mmd docs/design.md

校验必须完全离线执行：只使用 Skill 内置的固定版本 Mermaid 代码，不调用 npx、包管理器、远程渲染服务或用户另行安装的 Mermaid；图源码只在本机进程间传递。运行器会封禁常见网络 API，既不发送图内容，也不检查或下载更新。内置校验器不完整或本机运行环境不可用时直接失败，不要求用户下载依赖。

编译通过证明内置版本能够识别该图的语法和图型；如果目标编辑器提供本地预览，仍应确认文字未截断、连线没有歧义、布局没有掩盖重点。不得为预览将文档上传到在线 Mermaid 服务。

完成条件

• 图型与评审问题匹配，且确实比文字或表格更清楚。
• 范围最小充分，路径、方向、状态和边界语义完整。
• 图与正文及权威契约一致，不固定无依据的实现细节。
• 所有 Mermaid 图均通过内置编译器的离线校验，并完成必要的本地预览检查。