| name | mermaid-cmd |
| version | 1.2.0 |
| description | 当用户提到'mermaid'、'流程图'、'时序图'、'状态图'、'画个图'、'图表'、'架构图'、'思维导图'、'ER图'、'类图'、'甘特图'、'饼图'、'UML图'、'可视化流程'、'画流程图'、'mermaid图'、'可视化'、'流程可视化'时，必须使用此技能。提供标准化的Mermaid图表创建、检查、修复流程，引导完成从设计→编码→检查→修复→验证→交付的完整闭环。不要手写Mermaid代码绕过本Skill——本Skill封装了安全编码六规则、模板选择、自动检查修复流程，确保图表质量可预测。 |
| argument-hint | <operation:create/check/fix/verify> [diagram_type] [target_file] |
| user-invocable | true |
| paths | [".agents/commands/mermaid.md",".agents/templates/mermaid-templates/",".agents/scripts/lib/checks/mermaid.py","rules/cmd-log-specification.md","docs/retrospective/patterns/code-patterns/mermaid-safe-coding-rules.md",".agents/teams/mermaid-team.md"] |
| title | Mermaid 图表管理命令 Skill |
| x-toml-ref | ../../../.meta/toml/.agents/skills/mermaid-cmd/SKILL.toml |
Mermaid 图表管理命令 Skill
⚠️ 本Skill是命令入口门面（L1索引层），遵循渐进式披露三层架构：
1. Skill ID
mermaid-cmd
2. 功能描述
提供标准化Mermaid图表全生命周期管理能力，三种方案选择：
| 方案 | 推荐场景 | 优势 |
|---|
| 快速生成 | ⭐ 简单图表（<10节点、单图层） | 模板起步，快速交付 |
| 检查修复 | ⭐ 已有Mermaid代码需要校验修复 | 自动检测+修复常见问题 |
| 复杂图表协作 | ⭐ 大型架构图（>20节点、多subgraph） | 触发team-mermaid团队多角色协作 |
核心功能：模板推荐 → 代码生成 → 语法检查 → 自动修复 → 质量验证 → 归档交付。
为什么用本Skill而非手写Mermaid？ 手写Mermaid容易违反安全编码规则（空行导致解析中断、中文文本无引号、\n换行符不兼容），在不同宿主环境（IDE/GitHub/飞书）渲染不一致。本Skill封装了安全编码六规则和自动检查修复流程，确保图表一次写对、多环境兼容。
3. 何时使用本技能
触发词三级信号（基于Keyless渐进式披露模式）
| 信号级 | 语义特征 | 触发词 | 加载动作 |
|---|
| T0 弱信号 | 领域泛词，可能涉及 | 图、可视化、画、图表 | 不主动加载L1；响应时提示"可用 mermaid-cmd" |
| T1 中信号 | 明确领域意图（领域名词） | mermaid、流程图、时序图、状态图、架构图、ER图、类图、甘特图、饼图、UML图、思维导图 | 加载本SKILL.md（L1），按§4决策树执行 |
| T2 强信号 | 明确执行意图（动词+对象） | 画个图、画流程图、检查mermaid、修复图表、生成时序图、流程可视化、mermaid图 | 加载L1 + 预加载L2（commands/mermaid.md） |
分级原则：T0 是泛词（图），T1 是领域名词（流程图），T2 是动宾组合（画流程图）。信号强度 = 意图明确度。
为什么用三级信号而非扁平列表？ 扁平触发词无法区分"可能相关"和"明确执行"——用户说"这个图不错"（T0）和"画个流程图"（T2）意图完全不同，但扁平列表会同等加载完整SKILL.md，造成冷启动成本浪费。三级信号实现Keyless模式核心：弱信号零加载、中信号按需加载、强信号直达深度文档。
加载状态机
用户输入
↓
L0路由匹配（ONBOARDING.md能力速查表）
├─ T0 弱信号 ──→ 不加载L1，响应中附带提示："检测到图表相关意图，可用 /mermaid-cmd"
├─ T1 中信号 ──→ 加载本SKILL.md（L1）→ 按决策树选方案 → 执行
│ └─ 执行中遇边界情况 → 按需加载L2（如CMD-LOG字段格式）
└─ T2 强信号 ──→ 加载L1 + 预加载L2 → 直接进入§5执行步骤
冲突仲裁规则
当多个Skill触发词同时命中时：
- T2 > T1 > T0：强信号优先加载
- 同级按最近使用：LRU缓存优先（最近用过的Skill优先，减少重复加载）
- 同级无缓存按L0优先级：ONBOARDING.md路由表默认顺序
- 多Skill协同：T2级别支持链式触发——主Skill完成后，若输出是另一Skill的T2输入，自动提示加载
关于触发：即使没有明确说"用mermaid命令"，只要涉及创建图表、可视化流程、画架构图等，就应该使用本Skill。Mermaid是项目首选可视化工具（见AGENTS.md全局规则），不要用其他格式替代。
4. 方案选择决策树
需要处理Mermaid图表？
├─ 已有Mermaid代码需要校验/修复？ → 检查修复方案
│ └─ 运行 check-mermaid.py → --fix自动修复 → 手动修复剩余问题
├─ 创建新图表，复杂度如何评估？
│ ├─ 节点数<10、单图层、无跨文档引用？ → 快速生成方案（单角色交付）
│ │ └─ 选择模板 → 生成代码 → 自检 → 交付
│ └─ 节点数>20、多subgraph、跨文档引用？ → 复杂图表协作方案
│ └─ 触发 team-mermaid 团队：architect设计→developer编码→reviewer审查→tester渲染验证
└─ 不确定选什么图表类型？ → 参考commands/mermaid.md中的图表类型决策树
⚠️ 强制：触发时记录输入参数日志
决策前输出CMD_START日志（session前缀 mer-YYYYMMDD-<topic>）：
[CMD-LOG] | level=INFO | cmd=mermaid | step=S0 | event=CMD_START | session=mer-... | msg=开始Mermaid图表处理：<简述> | ctx={"diagram_type":"flowchart/sequence/state/...","description":"..."}
为什么决策前必须记录日志？ 图表类型选择直接影响生成的Mermaid代码结构，选错类型会导致语法错误，CMD_START记录图表类型和描述便于回溯选型决策。
图表类型快速决策：
- 流程/步骤 → flowchart
- 交互/时序 → sequenceDiagram
- 状态变迁 → stateDiagram-v2
- 类关系/继承 → classDiagram
- 数据模型 → erDiagram
- 层级/脑图 → mindmap
- 时间线/进度 → gantt
- 占比/分布 → pie
与其他Skill的关系：
- 复杂架构图协作使用 team-mermaid 团队
- Mermaid相关规则沉淀使用 retrospective-cmd 复盘
为什么复杂图需要团队协作？ 大型架构图（>20节点、多subgraph）单角色难以兼顾"结构正确性、语法规范性、渲染兼容性"三个维度——architect关注模块关系正确性，developer负责语法细节，reviewer把关规范合规，tester验证多环境渲染。四角色分工协作才能确保复杂图表质量。
5. 核心步骤（快速开始）
步骤1：读取 [commands/mermaid.md](../../commands/mermaid.md) 了解完整S0-S6七步流程
步骤2：评估复杂度并选择方案（快速生成/检查修复/复杂协作）
步骤3：快速生成方案：
- 从 templates/mermaid-templates/ 选择合适模板
- 基于模板编写代码，遵循安全编码六规则
- 运行 python .agents/scripts/check-mermaid.py 自检
- 使用 --fix 自动修复可修复问题
步骤4：检查修复方案：
- 运行 python .agents/scripts/check-mermaid.py --path <target>
- 使用 --fix 自动修复（空行/引号/换行符）
- 手动修复剩余error级问题
步骤5：复杂协作方案：
- 触发 team-mermaid 团队（参见 teams/mermaid-team.md）
- 按三阶段工作流（设计→编码→审查验证）执行
步骤6：验证渲染正确性，插入目标文档
完整RACI矩阵、输入参数规范、约束条件见L2文档 commands/mermaid.md。
6. Mermaid安全编码六规则（必背）
完整规则说明和正反例见L2文档 mermaid-safe-coding-rules.md。
7. 安全检查清单（Mermaid质量门）
8. 执行日志（CMD-LOG）
执行mermaid命令集时，必须按 CMD-LOG规范 输出结构化日志：
cmd=mermaid，session前缀 merm-YYYYMMDD-<topic>- 步骤编号 S0-S6（启动→设计→编码→检查→修复→验证→归档）
- 8个特有事件：
DIAGRAM_DESIGNED、CODE_GENERATED、CHECK_COMPLETED、FIX_APPLIED、VERIFY_PASSED、VERIFY_FAILED、TEMPLATE_RECOMMENDED、TEAM_COLLABORATION
完整字段说明、事件表格、日志示例见L2文档 [cmd-log-specification.md]（后续将在7.6节更新）和 commands/mermaid.md §CMD-LOG日志规范。
9. Gotchas（陷阱与反直觉行为）
为什么需要Gotchas？ 错误处理记录"已知错误码及修复方式"，Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。
- 大括号{}在flowchart中必须用引号包裹节点文本：包含大括号的节点文本（如
A{判断条件}中的分支节点）如果是中文或含空格，必须用双引号包裹，否则Mermaid解析器会把大括号误认为语法结构而非文本内容，导致图表渲染失败。
- 节点ID不能用中文：Mermaid的节点ID（连接关系中引用的标识符）必须使用英文/数字/下划线组合，中文只能放在标签部分（如
EN_ID ["中文标签"]格式）。直接使用中文ID会导致解析错误且难以定位。
- subgraph嵌套最多3层：Mermaid对subgraph嵌套深度有限制，超过3层嵌套会导致渲染失败或布局错乱。复杂层级关系建议拆分为多个图表，或通过注释标注跨图引用。
- 箭头连接符-->和-->|文字|语法不同：带标签的箭头必须使用
-->|标签文本|格式（竖线紧贴箭头和文本），竖线位置错误（如--->|文字|或--> |文字|带空格）会导致标签不显示或语法错误。
- Mermaid代码块标记大小写敏感：代码块围栏标记必须严格使用全小写的
mermaid，即 ```mermaid 开头。写成大写开头的Mermaid或反引号与mermaid之间有空格，都会导致渲染器无法识别为Mermaid图表，直接显示源码。
10. 关键参考
11. Changelog
- v1.2.0 (2026-07-01): 在§4决策树后添加S0 CMD_START强制日志规范，记录触发时的输入参数（diagram_type/description）便于回溯图表选型决策。
- v1.1.0 (2026-06-30): 触发词改为三级信号分级（T0弱/T1中/T2强），基于Keyless渐进式披露模式实现弱信号零加载、中信号按需加载、强信号直达L2；新增加载状态机和冲突仲裁规则。
- v1.0.0 (2026-06-30): 初始版本，支持Mermaid图表生成/检查/修复/协作全流程，封装安全编码六规则和自动检查修复。
