mermaid-diagram
为 Markdown 和技术文档选择、编写、审视并离线编译验证 Mermaid 图。当前任务涉及流程、时序、状态、依赖或数据关系,且图比文字或表格更利于理解和评审时使用;不用于装饰文档或替代本应精确定义的契约。
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 9
- Forks
- 6
01 前言 Front Matter
- name
- mermaid-diagram
- version
- 2.3.2.0
- description
- 为 Markdown 和技术文档选择、编写、审视并离线编译验证 Mermaid 图。当前任务涉及流程、时序、状态、依赖或数据关系,且图比文字或表格更利于理解和评审时使用;不用于装饰文档或替代本应精确定义的契约。
02 资源文件 3
- 参考文档agents/openai.yaml233 B
- 脚本scripts/check_mermaid.py5.4 KB
- 脚本scripts/offline_mermaid_check.cjs2.7 KB
03 SKILL.md 正文
Mermaid Diagram
用图降低关系理解成本,而不是增加文档体积。先确定图要回答的评审问题;如果一句话、短列表或表格更清楚,就不画图。
选择图型
flowchart:步骤、判断、分支、失败与回退。sequenceDiagram:多个参与者之间有时间顺序的调用、消息和响应。stateDiagram-v2:对象生命周期、合法状态和转换条件。classDiagram:稳定职责、接口关系或模块内部依赖;不展开无关私有成员。erDiagram:实体、基数和持久化关系。
同一张图只回答一个主要问题。不要用多张图重复表达同一关系;只有不同图型回答不同评审问题时才同时保留。
编写规则
- 只保留理解当前问题需要的参与者和关系,不画全量系统。
- 节点使用稳定的业务、模块或职责名称,避免为画图发明私有类、函数和文件。
- 主路径必须可走通;被设计触发的关键失败、回退或终止路径不能悬空。
- 依赖图明确方向、职责和边界;时序图明确请求、响应及失败归属;状态图明确转换条件。
- 展示方案变化时,用文字标注“新增、变更、移除、保持”,颜色只能辅助表达。
- 标签简短且含义明确;含空格、标点或特殊字符的标签使用引号。优先使用广泛支持的语法,避免无必要的实验特性和 HTML。
- 图下文字只解释图中不易表达的依据、约束或结论,不逐节点复述。
复杂图优先拆分评审问题,而不是缩小字号或堆叠更多节点。图的语法正确不代表设计正确;仍需核对它与正文、接口和数据契约是否一致。
转义与易错字符
- 节点 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 图均通过内置编译器的离线校验,并完成必要的本地预览检查。
04 同仓库更多 Skills
task-split
基于已确认的设计与测试规格,生成单文件薄任务计划 tasks-overview.md;任务只保留目标、范围、权威设计/测试引用、依赖和状态,不复制或改写设计正文。Use when the user asks for 任务拆分、开发任务规划、有序任务计划、task split,或希望把已评审设计组织为可串行调度的 T1/T2 任务。支持两种模式:严格模式以详细设计文档、测试用例设计文档和通过的模块设计门禁结果为输入;轻量模式以 dev-design.md 与 test-design.md 两份文档为输入,由调用方说明。
task-dev
实现一个明确的 T[N] 任务并把它做完:按已评审设计实现与测试,两路只读语义 Review,修复与重验,代码检查,写交接记录与候选提交信息。Use when the user asks to 实现当前 Task、执行 task-dev、继续或恢复 T1/T2 开发。支持严格模式(以模块详细设计与测试用例设计为事实来源)与轻量模式(以 dev-design.md 与 test-design.md 为事实来源)。每次只处理一个 Task,不执行 git add 或 git commit,也不自行开始下一个 Task。
sr-design
帮助开发者创建功能/模块设计文档。用户描述系统整体要做什么,你负责研究代码仓库, 确定如何调整内部结构来实现目标,并通过逐题澄清消除所有不确定细节。 文档聚焦软件架构、功能设计与模块设计,而非代码实现细节。
sr-design-gate
对 SR-design.md 进行设计质量门禁,检查需求范围、架构边界、接口与数据契约、验收闭环、风险处置、图表变更表达以及文档跨章节一致性。用于 SR 设计完成后、进入 ar-split 前判断 SR 级设计是否完整,并输出通过、不通过或阻塞结论。
repo-init
Use when the user asks for 软件实现设计/software_architect/初始化代码仓/sdd/初始化/init/更新代码仓软件架构/更新代码仓软件实现设计.
module-tobe-design
基于调用方指定的正式《模块详细设计说明书.md》及模块目录下的 `.context/详细设计上下文.md`,设计模块内与本次需求相关的 TOBE 详细方案。TOBE 是唯一可以编辑正式说明书的阶段,必须按正式大纲写入需求背景、外部依赖、整体方案、模块详细方案、对外接口、数据库/表设计、受影响模块与交互、关键契约清单和附录/三方件约束。TOBE 只负责目标设计和可测试性输入,不生成测试用例,不拆分 AICoding 任务;测试用例设计交由 `$module-test-design`,编码任务拆分交由外部 AICoding 流程。详细设计上下文记录 ASIS 证据、TOBE 推导和过程,不得替代正式说明书。不得脱离 ASIS 证据凭空设计;ASIS context 缺失或不足时必须回补 ASIS 或标记阻塞。