SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mermaid-skill

mermaid-skill

通用与其它

查看项目

更新于 10-15 13:41

技能介绍

用途

mermaid-skill 用于生成 Mermaid 图表并以 .mmd 文本文件保存，再导出为 PNG、SVG 或 PDF 格式。它适合「图表即代码」的场景：自动布局、文本源码可纳入 git 版本管理、可嵌入 Markdown。

主要能力

  • 生成 .mmd 文本文件并导出为 PNG/SVG/PDF
  • 导出方式二选一：本地 mmdc CLI，或 Kroki API（无需安装）
  • 支持多种图表类型，包括流程图、时序图、类图、ER 图、状态图、甘特图、饼图、Git 图、C4 上下文图、架构图、思维导图、用户旅程、用例图、Cynefin、事件建模、树视图、Wardley 地图
  • 内置验证步骤（导出前必须验证）、视觉自检、用户评审循环
  • 支持批量模式：扫描代码仓库中的 schema、API 路由、状态机等，生成一组图表并汇总为一个自包含的 index.html
  • 可生成 mermaid.live 一键交接链接，供用户在浏览器中交互式微调

使用方式

前置条件

方式 A：本地 mmdc，还需要无头 Chrome（mmdc 通过 Puppeteer 渲染）

npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell
mmdc --version

注意：即使未安装 Chrome，mmdc --version 仍会成功，但每次导出都会失败并提示 Could not find Chrome。可设置 PUPPETEER_EXECUTABLE_PATH 指向系统 Chrome。

CI / Docker 环境：容器中以 root 运行会导致 mmdc 崩溃并提示 Running as root without --no-sandbox，需传入配置：

mmdc -p scripts/puppeteer-config.json -i diagram.mmd -o diagram.png

方式 B：Kroki API，无需安装，只需 curl。

工作流程

  1. 检查依赖：通过 Kroki 验证（只需 curl）；仅在需要本地导出（PNG 质量 / PDF）时检查 mmdc --version 和无头 Chrome
  2. 选择图表类型
  3. 生成：将 .mmd 文件写入磁盘
  4. 验证：优先使用 Kroki，导出前必须验证
  5. 导出：使用 mmdc 或 Kroki API 生成 PNG/SVG/PDF
  6. 视觉自检：读取导出的 PNG，修复自动布局无法避免的可读性问题，最多 2 轮
  7. 评审循环：向用户展示图片，按请求做最小 .mmd 修改，重新导出直至通过，最多 5 轮
  8. 报告：告知用户输出文件路径

验证（必需）

切勿在未验证的情况下导出图表。优先使用 Kroki 验证：

curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

离线回退使用 mmdc：

mmdc -i diagram.mmd -o /tmp/test.svg 2>&1

常见验证错误：标签含特殊字符未加引号、箭头语法错误（时序图用 ->>，流程图用 -->）、时序图中参与者未声明。mmdc 报 Could not find Chrome 是环境问题而非图表语法问题，此时应改用 Kroki 验证。

视觉自检

导出后可使用视觉能力读取 PNG，检查自动布局无法避免的问题：标签被截断、密度过高难以阅读、方向 / 宽高比错误、连线交叉过多、图表类型不匹配、对比度过低。每轮修复后需重新验证并重新导出，最多 2 轮自检。如果无视觉能力，跳过自检直接展示 PNG。

评审循环

按用户反馈做最小修改：改标签、增删节点或边、改颜色（classDef + class）、改布局方向（TD↔LR）、重构分组（subgraph）。每轮覆盖同一个 diagram.mmd / diagram.png。5 轮后生成 mermaid.live 交接链接。

mermaid.live 交接

python3 scripts/mermaid_live_link.py diagram.mmd
# -> https://mermaid.live/edit#pako:...

使用纯 zlib + base64 编码，离线可用，脚本会先做往返解码自检。

批量模式（代码仓库调查）

  1. 扫描：定位 schema（SQL / ORM 模型）、API 路由、状态机 / 生命周期枚举
  2. 提议：每个发现对应一张图（schema 用 ER、主 API 流程用时序、生命周期用状态、整体服务布局用流程图），生成前与用户确认
  3. 生成 + 导出：对每张图运行标准流程，输出到同一文件夹
  4. 概览页：将所有 SVG 内联到单个自包含 index.html（标题 + 每图一节，无 CDN）

批量中每张图同样适用验证和自检规则。

适用场景与限制

适用：需要自动布局的图表即代码（流程图、时序图、类图、状态图、ER 图、甘特图、思维导图、架构图），文本源码可纳入 git 并嵌入 Markdown。

不适用（应改用其他工具）：像素级精确摆放、自定义布局、品牌图标或重度样式 → drawio；手绘 / 草图风格 → excalidraw 或 tldraw；自由白板或手绘笔迹 → tldraw；严格传统 UML 记法 → plantuml。

导出命令：

本地 mmdc：

mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral
mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.pdf

有效 -t 值：default | dark | neutral | forest（base 不是有效 -t 值，只能在指令中使用）。

Kroki API：

curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

Kroki 不支持 Mermaid 的 PDF 输出，POST 到 /mermaid/pdf 会返回 HTTP 400。PDF 需使用本地 mmdc。

语法参考文档：reference/FLOWCHART.md、reference/SEQUENCE.md、reference/CLASS-ER.md、reference/ARCHITECTURE.md、reference/USECASE.md、reference/OTHER-TYPES.md、reference/THEMES.md、reference/EXAMPLES.md。

暂未提供

该技能的收费情况、价格、可用平台范围、性能表现等事实暂未提供。