用途
本技能用于在编写或编辑 Markdown 文档时，借助 Mermaid 图表来阐明架构、工作流、交互、决策、状态转换等内容。其核心原则是：只有当视觉关系比文字描述更容易理解时才使用 Mermaid。
参考资料包括 mmdc-cli（用于 CLI 参数）和 examples（用于操作演示）。
主要能力
问题 → 图表类型映射
- 谁拥有/依赖谁？→ flowchart + subgraph
- 谁以什么顺序交互、产生什么结果？→ sequenceDiagram
- 决策/算法如何分支？→ flowchart
- 有哪些持久状态与转换？→ stateDiagram-v2
- 数据实体关系？→ erDiagram
- 类/接口关系？→ classDiagram
- 随时间发生了什么/计划了什么？→ timeline
注意：永远不要将静态结构（类图/ER 图）与运行时行为（时序图）合并在同一张图中。当问题混合时，应拆分图表。
缩放层级 × 典型类型
- 概览（Overview）：静态（边界）用 1 张分层边界图（UI / State / Data，每层一个具名示例）；动态（流程）用 1 张 sequenceDiagram（正常路径）；必需文本为一段目的说明 + 外部依赖表 + 一段状态摘要。
- 细节（Detail）：静态用 1 张 stateDiagram-v2 或更深的边界图；动态用 sequenceDiagram（错误路径或子流程）。
- 下钻（Drill-down）：静态用主 flowchart；动态用 erDiagram / classDiagram 引用。
注意：不要将提供者依赖图作为概览的主图——那是过度使用的 C4 组件图。应改用分层边界图替代。
使用方式
工作流
-
理解需求：解析来源、目标、缩放层级、模式，检测缺失输入。
-
SPEC 门控（仅当输入缺失时）：每个缺失输入只问一个问题，每次调用最多 4 个。
- 目标（target）：询问用户。默认：<req_dir>/diagrams/，其中 <req_dir> 是请求中函数/模块所在目录。其他有效值：内联到现有文档中。
- 缩放层级（zoom）：概览 / 细节 / 下钻（别名：Z1 / Z2 / Z3）。
- 模式（mode）：内联（默认）/ 内联+SVG / 静态（别名：R1 / R2 / R3）。
- 如果属于简单请求（≤1 个函数、≤1 个模块、无状态）或请求中已包含所有输入，则跳过。
-
规划清单（不写文件）：此步骤不要调用 Write。文件仅在步骤 5、步骤 4 批准后写入。
- 根据“问题→图表类型”为每个问题选择 Mermaid 类型。
- 决定文件名和类型（不是内容）。命名遵循缩放层级规则：
- overview.md — 目的（1 段）+ 1 张边界图 + 1 张正常路径时序图 + 外部依赖表 + 状态摘要（1 段）
- <major>.detail.md — 1 张 stateDiagram-v2 或更深的边界图 + 1 张时序图（错误路径或子流程）
- <major>-<minor>.drill.md — 主 flowchart + 引用的 erDiagram / classDiagram
- 构建清单表——名称 | 类型 | 问题——每个计划文件一行。
- 为每个文件起草 Mermaid 源码——步骤 4 预览需要。
-
确认清单（停止门控）：在用户回复前不要进入步骤 5。写入文件不可逆，因此在 Write 调用前设置停止门控。请求用户批准清单，包含：清单表（名称 | 类型 | 问题）、每个文件一段简短的 Mermaid 草稿片段。等待回复后路由：批准→进入步骤 5；调整→应用更改，回到步骤 3；拒绝→丢弃计划。
-
生成文件（仅在批准后）：仅当步骤 4 返回批准时触发。如果调整或拒绝，返回步骤 3。用 Write 写入每个文件，尽可能并行。在宣布文件完成前应用自检清单：
- 消息/Note 文本中的 ; → 使用 ;
- 没有 : 的裸箭头
- alt:/else:/opt:/loop:/par: 冒号 → 使用空格
- 块外的字面 end → 使用 (end) / [end] / "end"
- 参与者 ID 中的 @ / , / >
- %% 是注释前缀（仅独立行）
- 提供者依赖图作为概览主图——改用分层边界图
- 列出目标目录以确认所有预期文件存在后再继续。
-
预渲染安全（停止门控）：在 mmdc 之前，如果出现以下任一情况则停止并询问：目标目录未指定；需要安装 mmdc 或 Chromium（绝不自动安装）；非 SVG 格式（默认：SVG + 白色背景）；替换现有 diagrams/——确认保留文件。门控失败→内联模式（不渲染）。
7a. 渲染前须知：
- SVG 基名 = -o 词干，不是 -i。mmdc -i foo.md -o bar.md → bar-1.svg。
- -o <name>.svg 跳过转换后的 Markdown 输出。mmdc 只写 SVG——不替换 .md。
- -a <dir> 当 -a 和 -o 解析到不同目录时会使 Markdown 链接变丑。Linux：.. 段。Windows：混合斜杠/反斜杠路径。除非必须，否则跳过 -a。
7b. 配方：内联 + SVG 渲染。目标：保留 <name>.md 内联 ```mermaid 块，并预渲染 <name>-N.svg 在旁边。
cd <repo>/lib/features/<module>/diagrams
for f in *.md; do
mmdc -i "$f" -o "${f%.md}.svg"
done
在每个 <name>.md 旁边直接渲染 SVG——无需 /tmp/，无需清理。
7c. mmdc 怪癖：
- -o foo.md 会静默强制 outputFormat 为 svg。如果需要 PNG/PDF 输出，显式传递 -e png 或 -e pdf。
- -a 会用原生路径分隔符重写嵌入链接。在 Windows 上意味着反斜杠，可能破坏跨操作系统仓库中的渲染。
- 每个图表的 SVG 后缀是位置性的（-1, -2, …），不是内容寻址的。重新排序或删除源 .md 中的块会重新编号所有后续 SVG，并破坏任何缓存/外部引用。
适用场景
适用于编写或编辑需要 Mermaid 图表的 Markdown 文档，以阐明架构、工作流、交互、决策、状态转换等内容。
限制
- 仅当视觉关系比文字描述更清晰时才使用 Mermaid。
- 不要将静态结构与运行时行为合并在同一张图中。
- 不要将提供者依赖图作为概览主图。
- 写入文件前必须经过用户批准（停止门控）。
- 绝不自动安装 mmdc 或 Chromium。
- 关于收费、价格、平台等具体信息暂未提供。