mermaid-diagram

Files (7)

• SKILL.md
• openai.yaml · agents/
• check_mermaid.py · scripts/
• offline_mermaid_check.cjs · scripts/
• LICENSE · vendor/mermaid/
• VERSION · vendor/mermaid/
• mermaid.min.js · vendor/mermaid/

SKILL.md (first lines)

# 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。任一图无法编译时返回非零退出码。

```bash
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 图均通过内置编译器的离线校验，并完成必要的本地预览检查。

From pi-ixel/Awesome-Agent-Workflow, MIT.

More from pi-ixel/Awesome-Agent-Workflow