Skip to content

xinetzone/SpecWeave / .agents/skills/mermaid-cmd

mermaid-cmd

Verified

当用户提到'mermaid'、'流程图'、'时序图'、'状态图'、'画个图'、'图表'、'架构图'、'思维导图'、'ER图'、'类图'、'甘特图'、'饼图'、'UML图'、'可视化流程'、'画流程图'、'mermaid图'、'可视化'、'流程可视化'时,必须使用此技能。提供标准化的Mermaid图表创建、检查、修复流程,引导完成从设计→编码→检查→修复→验证→交付的完整闭环。不要手写Mermaid代码绕过本Skill——本Skill封装了安全编码六规则、模板选择、自动检查修复流程,确保图表质量可预测。

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触发词同时命中时:

  1. T2 > T1 > T0:强信号优先加载
  2. 同级按最近使用:LRU缓存优先(最近用过的Skill优先,减少重复加载)
  3. 同级无缓存按L0优先级:ONBOARDING.md路由表默认顺序
  4. 多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验证多环境渲染。四角色分工协作才能确保复杂图表质量。

4.5 知识面与操作面分离(加载分层)

本 Skill 依据「技能知识操作分离」模式(见 skill-knowledge-operation-separation.md),将能力分为两个可独立加载的面:

面内容加载时机工具依赖
知识面安全编码六规则(§6)、语法 Gotchas(§9)、模板(templates/mermaid-templates/)编写/创建图表(纯写作任务)无(纯参考,不触发脚本执行)
操作面check-mermaid.py 检查/修复脚本(§5 步骤4)检查/修复已有图表需脚本执行(python)

加载路由:

  • 用户意图 = 创建/编写图表 → 仅加载知识面(六规则+模板),不调用检查脚本、不暴露执行工具
  • 用户意图 = 检查/修复图表 → 加载操作面(check-mermaid.py)
  • 组合意图(编写+检查)→ 先知识面后操作面

为什么分离? 纯写作任务(用户只想写一段 Mermaid)只需要语法规则和模板,加载检查脚本调用方式会占用上下文并暴露不必要的执行工具。参照 jira-skill:jira-syntax(纯知识,无 allowed-tools)与 jira-communication(操作脚本)独立分发,实现上下文隔离与权限收窄。

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安全编码六规则(必背)

  • 禁止空行:代码块内不能有空行,空行可能导致解析中断
  • 文本加引号:含中文、空格、特殊字符(@#≥≤+)的节点/标签文本必须用双引号包裹
  • 避免列表触发:文本不要以 - 、* 、+ 、1. 开头,会触发Markdown列表解析
  • 文本保持单行:需要分隔时使用空格,不使用 <br/> 或 \n
  • subgraph安全格式:使用 subgraph EN_ID ["中文标题"] 格式,不要直接用中文ID
  • 边标签格式:箭头标签使用 -->| "标签" | 格式,中文标签加引号

完整规则说明和正反例见L2文档 mermaid-safe-coding-rules.md。

7. 安全检查清单(Mermaid质量门)

  • 创建前已评估复杂度,确定使用正确方案(快速/检查/协作)
  • 已选择合适的图表类型(参考决策树)
  • 简单图表已基于模板起步,而非从零开始
  • 代码遵循安全编码六规则(空行/引号/列表/换行/subgraph/边标签)
  • 已运行 check-mermaid.py 检查,无error级问题
  • 中文/空格文本均已加双引号
  • 复杂图表(>20节点)已触发team-mermaid团队协作
  • 插入目标文档后链接有效,索引已更新(如需要)

8. 执行日志(CMD-LOG)

执行mermaid命令集时,必须按 CMD-LOG规范 输出结构化日志:

⚠️ 铁律一(🔴强制):S0 CMD_START 必须是命令集执行后的第一条输出,禁止在CMD_START之前输出任何其他内容(包括调试信息、中间结果)。违反将导致日志链路断裂,CI步骤19(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. 关键参考

参考层级路径何时查阅
完整命令文档(RACI/参数/约束/步骤)L2commands/mermaid.md每次使用必读
CMD-LOG日志规范L2cmd-log-specification.md日志格式、事件定义
安全编码六规则L2mermaid-safe-coding-rules.md编写代码时必读
Mermaid模板目录L2templates/mermaid-templates/创建新图表时选择模板
Mermaid检查脚本L2scripts/lib/checks/mermaid.py语法检查与自动修复
触发词匹配调试器L1工具scripts/trigger_matcher.py调试T0/T1/T2信号匹配过程,输出详细日志
team-mermaid专项团队L2teams/mermaid-team.md复杂图表协作
渐进式披露架构L2capabilities/ARCHITECTURE.md理解三层架构设计

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图表生成/检查/修复/协作全流程,封装安全编码六规则和自动检查修复。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall