creating-mermaid-diagrams

Name: creating-mermaid-diagrams
Author: agents365-ai

github.com/agents365-ai设计与 UI974.2k 次安装2 周前更新

代码仓库

关于 creating-mermaid-diagrams

creating-mermaid-diagrams 是用于生成 Mermaid 图表的技能，面向需要把流程、架构或关系表达为图形的用户。它将文本语法写入 .mmd 文件，并可在本地或通过 Kroki 导出图像。

主要功能

01生成 Mermaid 文本图表
02支持多种图表类型
03导出 PNG、SVG 和 PDF
04使用 mmdc 或 Kroki 渲染
05导出前验证语法

适用场景

01绘制 API 调用时序图
02展示微服务架构
03描述订单状态流转

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/agents365-ai/365-skills --skill creating-mermaid-diagrams

安装后在 Claude Code 中输入/creating-mermaid-diagrams确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

reference/

CLASS-ER.md

FLOWCHART.md

OTHER-TYPES.md

SEQUENCE.md

详细介绍

Mermaid 图表

生成 .mmd 文本文件，并使用 mmdc（本地）或 Kroki API（无需安装）导出为 PNG/SVG/PDF。

主要优势：基于文本的语法，支持完全自动布局——无需指定 x/y 坐标。

前置条件

选项 A：本地（mmdc）

npm install -g @mermaid-js/mermaid-cli
mmdc --version

选项 B：Kroki API（无需安装）

curl --version  # Just need curl

工作流

检查更新（通知，不拉取）——每次对话首次使用时执行。通过 <this-skill-dir>/.last_update 将检查频率限制为每 24 小时一次；未经用户明确同意，绝不修改技能目录。
- 如果 .last_update 存在且创建时间不足 24 小时，则完全跳过此步骤。
- 否则，从上游获取最新标签：
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- 将上游标签与此技能 frontmatter 中的 metadata.version 比较。如果上游标签严格更新（按 semver 判断），用一行告知用户并询问：
  
  “此技能有更新版本：vX.Y.Z → vA.B.C。要我执行 git pull 吗？”
  
  如果用户同意，运行 git -C <this-skill-dir> pull --ff-only。无论用户是否同意，都刷新 .last_update，以免 24 小时内重复提示。
- 如果上游版本相同或更旧，则静默刷新 .last_update 并继续。
- 如果发生任何错误（离线、不是 Git 工作区——例如通过 ClawHub 安装的副本、只读路径、没有权限），则静默忽略错误并继续处理用户的任务。不要提及此错误。
检查依赖项——尝试运行 mmdc --version；如果不可用，则回退到 Kroki
选择图表类型——从下表中选择
生成——将 .mmd 文件写入磁盘
验证——运行验证（导出前必须执行）
导出——使用 mmdc 或 Kroki API 生成 PNG/SVG/PDF
报告——告知用户输出文件路径

验证（必需）

未经验证，绝不导出图表。

# Validate with mmdc (local)
mmdc -i diagram.mmd -o /tmp/test.png 2>&1

# Validate with Kroki (if mmdc unavailable)
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"

# If error, fix the .mmd file and validate again
# Only proceed to export after validation passes

常见验证错误：

含特殊字符的标签缺少引号
箭头语法错误（序列图使用 ->>，流程图使用 -->）
序列图中未声明参与者

图表类型

类型	关键字	用途
流程图	`flowchart TD/LR`	流程、管道、决策
序列图	`sequenceDiagram`	API 调用、消息传递
类图	`classDiagram`	OOP 模型、数据结构
ER 图	`erDiagram`	数据库架构
状态图	`stateDiagram-v2`	状态机、生命周期
甘特图	`gantt`	项目时间线
饼图	`pie`	占比
Git 图	`gitGraph`	分支策略
C4 上下文图	`C4Context`	高层架构
思维导图	`mindmap`	主题分解

语法参考

流程图：参见 reference/FLOWCHART.md 序列图：参见 reference/SEQUENCE.md 类图和 ER 图：参见 reference/CLASS-ER.md 其他类型：参见 reference/OTHER-TYPES.md

示例

示例 1：API 身份验证流程

用户提示词：

创建一张 JWT 身份验证序列图

生成的 .mmd：

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

输出文件：auth-flow.mmd + auth-flow.png

示例 2：微服务架构

用户提示词：

绘制电商微服务架构图

生成的 .mmd：

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end

  GW[API Gateway]

  subgraph Services
    US[User Service]
    OS[Order Service]
    PS[Product Service]
    PAY[Payment Service]
  end

  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    PDB[(Product DB)]
    REDIS[(Redis Cache)]
  end

  M & W --> GW
  GW --> US & OS & PS & PAY
  US --> UDB
  OS --> ODB
  PS --> PDB
  PAY --> REDIS

输出文件：ecommerce-arch.mmd + ecommerce-arch.png

示例 3：订单状态机

用户提示词：

展示订单生命周期状态

生成的 .mmd：

stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

输出文件：order-states.mmd + order-states.png

导出命令

选项 1：本地导出（mmdc）

需要在本地安装 mmdc。最适合离线使用。

# PNG (recommended: 2048px wide, white background)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

# PNG with theme (default | dark | neutral | forest | base)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

选项 2：Kroki API（无需安装）

当无法使用 mmdc 时，请使用 Kroki。无需本地依赖。

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

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

# PDF via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/pdf -o diagram.pdf

Kroki 的优势：

无需本地安装
任何安装了 curl 的系统均可使用
支持 20 多种图表类型（PlantUML、GraphViz、D2 等）

适用场景：

mmdc 安装失败
快速绘制一次性图表
不使用 Node.js 的 CI/CD 流水线

常见错误

错误	修正方法
找不到 `mmdc`	`npm install -g @mermaid-js/mermaid-cli`
时序图中的箭头错误	请求使用 `->>`，响应使用 `-->>`
标签中包含特殊字符	用引号括起来：`A["Label: value"]`
输出为空或过小	添加 `-w 2048` 标志
参与者顺序错误	在顶部显式声明 `participant`
子图名称中包含空格	用引号括起来：`subgraph "My Layer"`

支持 Markdown

登录后评论