Mermaid 流程图表

要解决什么问题

在文档、评审或方案里写流程、时序、状态机或架构关系时，纯文字往往难对齐细节；手画再贴图又难版本化。Mermaid 用文本描述图表，但本地能否渲染、浏览器依赖是否齐全、源码语法哪里报错，经常在真正导出 SVG/PNG 时才暴露。

技能如何工作

本技能围绕 mmdc（Mermaid CLI） 做「先环境、再源码、再导出」的闭环，而不是堆砌语法手册。

• 首次使用前检查：会话里第一次渲染/校验前确认 mmdc 是否可用；缺失则说明需安装 @mermaid-js/mermaid-cli，并在用户明确要求且环境允许时代为安装。
• 浏览器依赖：渲染失败若指向 Puppeteer / headless Chrome，按错误引导安装浏览器依赖，或配置使用本机 Chrome，避免把环境问题误判为 Mermaid 语法错误。
• 版本策略：对比本地与 npm 发布版本；与最新版相差不超过 3 个发布版本时默认继续用本地版并简短提示；差距更大时询问是否升级，不擅自全局升级。
• 输出约定：用户指定路径则严格遵循；未指定时默认 docs/mermaid/，同时保存 .mmd 源码 与渲染结果（如 .svg）；中文短文件名，同名先确认覆盖。
• 类型与规范：按场景选流程图、时序图、状态图、类图、ER、甘特、时间线、思维导图、看板等；节点文案优先中文，标识符简短，特殊字符加引号，复杂图拆分。
• 失败处理：以 mmdc stderr 为准修源码，必要时只改必要行后重跑验证。

适用边界与注意点

技能侧重 本机 CLI 生成与排错，不替代 Mermaid 官方完整语法文档。临时 Puppeteer 配置放在系统临时目录，一般不作为交付物。公开仓库场景下勿写入隐私路径、令牌或未授权的外部项目关联信息。