openakita/skills@pretty-mermaid

# Pretty Mermaid — 专业 Mermaid 图表生成

## When to Use

- 用户要求创建流程图、架构图、时序图、类图、状态图、ER 图、C4 架构图或甘特图
- 需要将图表渲染为 SVG 或 ASCII 文本输出
- 需要批量生成多张图表
- 用户要求使用特定主题或配色方案
- 需要可复用的图表模板

---

## Prerequisites

### 必需工具

| 工具 | 用途 | 安装方式 |
|------|------|---------|
| Node.js ≥ 18 | 运行 Mermaid CLI | 系统预装或 `nvm install 18` |
| `@mermaid-js/mermaid-cli` | 渲染 SVG/PNG | `npm install -g @mermaid-js/mermaid-cli` |

### 可选工具

| 工具 | 用途 | 安装方式 |
|------|------|---------|
| `monodraw` (macOS) | ASCII 图表编辑 | App Store |
| `graph-easy` | ASCII 渲染 | `cpan Graph::Easy` |

### 验证安装

```bash
mmdc --version
```

如果 `mmdc` 不可用，回退到纯 Mermaid 代码块输出，让用户在支持 Mermaid 的编辑器或浏览器中预览。

---

## Instructions

### 核心工作流

1. **理解需求** — 明确图表类型、数据来源、目标受众
2. **选择图表类型** — 根据场景匹配最合适的 Mermaid 图表
3. **选择主题** — 根据使用场景选择配色方案
4. **编写 Mermaid 代码** — 遵循可读性最佳实践
5. **渲染输出** — 按指定格式输出 SVG、PNG 或 ASCII
6. **校验与优化** — 检查语法、布局、可读性

### 图表类型选择指南

| 场景 | 推荐图表 | Mermaid 关键字 |
|------|---------|---------------|
| 业务流程、审批流 | 流程图 | `flowchart TD/LR` |
| API 调用、服务交互 | 时序图 | `sequenceDiagram` |
| 代码结构、OOP 设计 | 类图 | `classDiagram` |
| 生命周期、状态机 | 状态图 | `stateDiagram-v2` |
| 数据库设计 | ER 图 | `erDiagram` |
| 系统架构、微服务 | C4 架构图 | `C4Context/C4Container/C4Component` |
| 项目排期、里程碑 | 甘特图 | `gantt` |
| Git 分支策略 | Git 图 | `gitGraph` |
| 思维导图、脑暴 | 思维导图 | `mindmap` |
| 时间线 | 时间线 | `timeline` |

---

## Workflows

### Workflow 1: 单张图表生成

**步骤 1 — 收集信息**

向用户确认以下内容（如未提供则使用默认值）：

| 参数 | 默认值 | 可选值 |
|------|--------|-------|
| 图表类型 | flowchart | 见上方选择指南 |
| 方向 | TD（上到下） | TD, LR, RL, BT |
| 主题 | default | default, dark, forest, neutral, base |
| 输出格式 | Mermaid 代码块 | svg, png, ascii, mermaid |
| 主题方案 | Tokyo Night | Tokyo Night, Dracula, GitHub Light, Nord, Solarized |

**步骤 2 — 编写 Mermaid 代码**

遵循以下规范：

```
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1b26', 'primaryTextColor': '#a9b1d6', 'primaryBorderColor': '#7aa2f7', 'lineColor': '#565f89', 'secondaryColor': '#24283b', 'tertiaryColor': '#1a1b26' }}}%%
flowchart TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E
```

**步骤 3 — 渲染（如需 SVG/PNG）**

将 Mermaid 代码写入临时 `.mmd` 文件，然后调用：

```bash
mmdc -i diagram.mmd -o diagram.svg -t dark -b transparent
mmdc -i diagram.mmd -o diagram.png -t dark -b white -w 1200
```

**步骤 4 — 输出**

返回渲染后的文件路径，或直接在消息中嵌入 Mermaid 代码块。

---

### Workflow 2: 批量图表生成

适用于一次性生成多张相关图表（如系统设计文档）。

**步骤 1** — 收集所有图表的需求列表

**步骤 2** — 创建批处理配置：

```json
{
  "theme": "tokyo-night",
  "outputDir": "./diagrams",
  "outputFormat": "svg",
  "diagrams": [
    {
      "name": "system-overview",
      "type": "C4Context",
      "title": "系统总览"
    },
    {
      "name": "api-sequence",
      "type": "sequenceDiagram",
      "title": "API 调用时序"
    },
    {
      "name": "data-model",
      "type": "erDiagram",
      "title": "数据模型"
    }
  ]
}
```

**步骤 3** — 逐一生成 Mermaid 代码并渲染

**步骤 4** — 返回所有图表的路径和预览

---

### Workflow 3: ASCII 图表输出

当用户需要纯文本图表（用于 CLI、日志、README 等场景）：

**方法 A — 手动 ASCII 绘制**

对于简单图表，直接使用字符绘制：

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│  Client  │────▶│  Server │────▶│Database │
└─────────┘     └─────────┘     └─────────┘
                     │
                     ▼
                ┌─────────┐
                │  Cache  │
                └─────────┘
```

**方法 B — 使用 graph-easy 转换**

```bash
echo "[ Client ] -> [ Server ] -> [ Database ]" | graph-easy --as=ascii
```

---

## 主题配置

### Tokyo Night（默认）

```
%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#1a1b26',
  'primaryTextColor': '#a9b1d6',
  'primaryBorderColor': '#7aa2f7',
  'lineColor': '#565f89',
  'secondaryColor': '#24283b',
  'tertiaryColor': '#414868',
  'noteBkgColor': '#1a1b26',
  'noteTextColor': '#c0caf5',
  'noteBorderColor': '#7aa2f7'
}}}%%
```

### Dracula

```
%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#282a36',
  'primaryTextColor': '#f8f8f2',
  'primaryBorderColor': '#bd93f9',
  'lineColor': '#6272a4',
  'secondaryColor': '#44475a',
  'tertiaryColor': '#383a59',
  'noteBkgColor': '#282a36',
  'noteTextColor': '#f8f8f2',
  'noteBorderColor': '#ff79c6'
}}}%%
```

### GitHub Light

```
%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#ffffff',
  'primaryTextColor': '#24292f',
  'primaryBorderColor': '#d0d7de',
  'lineColor': '#656d76',
  'secondaryColor': '#f6f8fa',
  'tertiaryColor': '#eaeef2',
  'noteBkgColor': '#ddf4ff',
  'noteTextColor': '#24292f',
  'noteBorderColor': '#54aeff'
}}}%%
```

### Nord

```
%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#2e3440',
  'primaryTextColor': '#eceff4',
  'primaryBorderColor': '#88c0d0',
  'lineColor': '#4c566a',
  'secondaryColor': '#3b4252',
  'tertiaryColor': '#434c5e',
  'noteBkgColor': '#2e3440',
  'noteTextColor': '#eceff4',
  'noteBorderColor': '#81a1c1'
}}}%%
```

### Solarized

```
%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#002b36',
  'primaryTextColor': '#839496',
  'primaryBorderColor': '#268bd2',
  'lineColor': '#586e75',
  'secondaryColor': '#073642',
  'tertiaryColor': '#073642',
  'noteBkgColor': '#002b36',
  'noteTextColor': '#93a1a1',
  'noteBorderColor': '#2aa198'
}}}%%
```

---

## 模板库

### 模板 1: 微服务架构（C4 Container）

```mermaid
C4Container
    title 微服务系统架构

    Person(user, "用户", "通过浏览器或移动端访问系统")

    System_Boundary(system, "核心系统") {
        Container(web, "Web 前端", "React", "用户界面")
        Container(gateway, "API 网关", "Kong/Nginx", "路由、限流、鉴权")
        Container(auth, "认证服务", "Go", "JWT 签发与验证")
        Container(biz, "业务服务", "Python", "核心业务逻辑")
        Container(notify, "通知服务", "Node.js", "邮件/短信/推送")
        ContainerDb(db, "主数据库", "PostgreSQL", "业务数据存储")
        ContainerDb(cache, "缓存", "Redis", "会话与热数据缓存")
        ContainerQueue(mq, "消息队列", "RabbitMQ", "异步任务处理")
    }

    Rel(user, web, "使用", "HTTPS")
    Rel(web, gateway, "API 调用", "HTTPS")
    Rel(gateway, auth, "鉴权", "gRPC")
    Rel(gateway, biz, "业务请求", "gRPC")
    Rel(biz, db, "读写", "TCP")
    Rel(biz, cache, "缓存", "TCP")
    Rel(biz, mq, "发布消息", "AMQP")
    Rel(mq, notify, "消费消息", "AMQP")
```

### 模板 2: CI/CD 流水线（Flowchart）

```mermaid
flowchart LR
    A[代码提交] --> B[触发 CI]
    B --> C{代码检查}
    C -->|通过| D[单元测试]
    C -->|失败| Z[通知开发者]
    D -->|通过| E[构建镜像]
    D -->|失败| Z
    E --> F[推送镜像仓库]
    F --> G{环境选择}
    G -->|Staging| H[部署 Staging]
    G -->|Production| I[人工审批]
    I -->|批准| J[蓝绿部署]
    I -->|拒绝| Z
    H --> K[集成测试]
    K -->|通过| L[✅ Staging 就绪]
    K -->|失败| M[自动回滚]
    J --> N[健康检查]
    N -->|通过| O[✅ 上线成功]
    N -->|失败| P[自动回滚]
```

### 模板 3: 用户认证时序（Sequence）

```mermaid
sequenceDiagram
    actor U as 用户
    participant C as 客户端
    participant G as API 网关
    participant A as 认证服务
    participant D as 数据库

    U->>C: 输入用户名/密码
    C->>G: POST /api/auth/login
    G->>A: 转发认证请求
    A->>D: 查询用户记录
    D-->>A: 返回用户数据
    alt 密码正确
        A->>A: 生成 JWT Token
        A-->>G: 200 OK + Token
        G-->>C: 返回 Token
        C->>C: 存储 Token
        C-->>U: 登录成功
    else 密码错误
        A-->>G: 401 Unauthorized
        G-->>C: 认证失败
        C-->>U: 提示错误
    end

    Note over C,G: 后续请求携带 Token
    U->>C: 访问受保护资源
    C->>G: GET /api/data (Bearer Token)
    G->>A: 验证 Token
    A-->>G: Token 有效
    G->>G: 转发到业务服务
```

### 模板 4: 数据库 ER 图

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string username UK
        string email UK
        string password_hash
        datetime created_at
        datetime updated_at
    }
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        decimal total_amount
        string status
        datetime created_at
    }
    ORDER_ITEM }|--|| PRODUCT : references
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }
    PRODUCT ||--o{ PRODUCT_TAG : has
    PRODUCT {
        int id PK
        string name
        text description
        decimal price
        int stock
    }
    TAG ||--o{ PRODUCT_TAG : applied
    TAG {
        int id PK
        string name UK
    }
    PRODUCT_TAG {
        int product_id FK
        int tag_id FK
    }
```

### 模板 5: 项目甘特图

```mermaid
gantt
    title 项目开发排期
    dateFormat YYYY-MM-DD
    axisFormat %m/%d

    section 需求阶段
    需求调研           :done,    req1, 2025-01-01, 7d
    需求评审           :done,    req2, after req1, 3d
    PRD 定稿           :done,    req3, after req2, 2d

    section 设计阶段
    技术方案设计        :active,  des1, after req3, 5d
    UI/UX 设计         :         des2, after req3, 7d
    设计评审           :         des3, after des2, 2d

    section 开发阶段
    后端开发           :         dev1, after des1, 15d
    前端开发           :         dev2, after des3, 15d
    联调测试           :         dev3, after dev1, 5d

    section 发布阶段
    UAT 测试           :         rel1, after dev3, 5d
    修复 Bug           :         rel2, after rel1, 3d
    正式发布           :milestone, rel3, after rel2, 0d
```

---

## Output Format

### 默认输出

直接在回复中使用 Mermaid 代码块：

````
```mermaid
flowchart TD
    A --> B
```
````

### SVG 文件

```bash
mmdc -i input.mmd -o output.svg -t dark -b transparent --cssFile custom.css
```

### PNG 文件

```bash
mmdc -i input.mmd -o output.png -t dark -b white -w 1920 -H 1080 -s 2
```

参数说明：
- `-t` 主题：default, dark, forest, neutral
- `-b` 背景色：transparent, white, #hex
- `-w` 宽度（像素）
- `-H` 高度（像素）
- `-s` 缩放倍数

### ASCII 文本

直接使用字符绘制，适合嵌入代码注释、终端输出、纯文本文档。

---

## Common Pitfalls

### 1. 节点 ID 冲突

**错误**：在同一图表中使用重复的节点 ID

```mermaid
flowchart TD
    A[登录] --> B[验证]
    A[注册] --> B[检查]
```

**正确**：使用唯一 ID

```mermaid
flowchart TD
    login[登录] --> validate[验证]
    register[注册] --> check[检查]
```

### 2. 特殊字符未转义

**错误**：节点文本包含括号、引号等

```
A[用户输入(name)]
```

**正确**：使用引号包裹

```
A["用户输入(name)"]
```

### 3. 图表过于复杂

单张图表超过 20 个节点时，考虑拆分为多张子图：

```mermaid
flowchart TD
    subgraph 前端
        A --> B --> C
    end
    subgraph 后端
        D --> E --> F
    end
    C --> D
```

### 4. 方向选择不当

- 层级结构（组织架构、决策树）→ **TD**（上到下）
- 流程/管道 → **LR**（左到右）
- 时间线/历史 → **LR**
- 请求-响应 → **TD** 或 **LR**

### 5. 中文乱码

渲染 SVG/PNG 时如果出现中文乱码，使用 `--cssFile` 指定字体：

```css
* {
    font-family: "Microsoft YaHei", "PingFang SC", "Noto Sans CJK SC", sans-serif;
}
```

### 6. Mermaid CLI 超时

大型图表可能渲染超时，增加超时参数：

```bash
mmdc -i large-diagram.mmd -o output.svg --puppeteerConfigFile puppeteer.json
```

`puppeteer.json`:
```json
{
  "timeout": 60000
}
```

### 7. 子图嵌套限制

Mermaid 支持子图嵌套，但过深的嵌套（超过 3 层）可能导致渲染异常。保持层级扁平化。

---

## 最佳实践

1. **命名规范** — 节点 ID 使用有意义的英文命名，显示文本使用中文
2. **布局控制** — 善用 `subgraph` 对节点分组，改善布局
3. **颜色语义** — 绿色表示成功、红色表示失败、蓝色表示进行中
4. **注释标注** — 使用 `Note` 添加关键说明
5. **渐进呈现** — 复杂系统先画总览再画细节，用 C4 的 Context → Container → Component 层级
6. **版本控制** — Mermaid 代码是纯文本，适合纳入 Git 管理
7. **一致性** — 同一文档中的所有图表使用相同主题配置

---

## EXTEND.md 扩展

用户可在技能同目录下创建 `EXTEND.md` 添加自定义主题和模板，Agent 会自动合并使用。