code-to-diagram

SKILL.md

---
name: "code-to-diagram"
description: "分析源代码逻辑，生成 Mermaid 流程图或 SVG 架构图并渲染为 PNG 图片。支持 15 种主题、5 种视觉风格、语义图形体系和 40+ 产品图标。"
version: "2.0.0"
tags: ["diagram", "mermaid", "svg", "flowchart", "visualization", "code-analysis", "architecture", "beautiful-mermaid"]
bindShells: ["ClaudeCode"]
---

# Code-to-Diagram Skill

分析指定目录或文件的源代码，提取控制流 / 数据流逻辑，输出两个文件：

1. **Markdown 文档**（`.md`）：包含图表源码
2. **渲染后的 PNG 图片**（高清）

支持两种渲染引擎：

| 引擎 | 输入 | 渲染方式 | 适用场景 |
|------|------|----------|----------|
| **Mermaid**（默认） | `.mmd` | beautiful-mermaid → SVG → rsvg-convert → PNG | 流程图、时序图、类图、状态图、ER 图、XY 图 |
| **SVG** | `.svg` | rsvg-convert → PNG | 架构图、AI 系统图、需要品牌图标或定制风格的图表 |

> Mermaid 引擎默认使用 [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) 渲染，提供 15 种精美主题。
> 不支持的图表类型（gantt、mindmap、pie、journey、gitgraph）自动回退到 mmdc。

---

## 第一步 —— 读取并分析代码

使用 `Read`、`Glob`、`Grep` 工具理解代码结构，识别主要逻辑模式。

---

## 第二步 —— 选择引擎

### 使用 Mermaid 引擎

- 标准流程图、时序图、类图、状态图、ER 图、XY 图表
- 用户未要求特定视觉风格
- 快速、美观的主题化图表

### 使用 SVG 引擎

- 架构图需要产品图标（OpenAI、AWS、PostgreSQL 等）
- AI/Agent 系统图需要语义图形（六边形 Agent、圆柱向量库等）
- 用户要求特定风格（dark-terminal、blueprint、glassmorphism 等）
- 需要精细布局控制

---

## 第三步 A —— Mermaid 路径

### 生成 Mermaid 源码

根据分析结果编写 Mermaid 图表源码。

| 代码模式 | 推荐 Mermaid 图表类型 |
|---------|----------------------|
| 状态机 / 工作流 | `flowchart TD` 或 `stateDiagram-v2` |
| 类继承关系 | `classDiagram` |
| 接口 / 消息传递 | `sequenceDiagram` |
| 实体关系 | `erDiagram` |
| 简单流程 | `flowchart LR` |
| 系统架构 / 分层架构 | `flowchart TB` + `subgraph` |
| 微服务架构 | `flowchart TB` + `subgraph` 或 `C4Container` |
| 数据趋势 / 图表 | `xychart-beta` |

**语言规则**：节点标签、连线说明**必须使用中文**。代码标识符保留原文。

**换行规则**：节点文本中使用 `<br/>` 而非 `\n`。

### 选择主题

15 个内置主题，根据场景推荐：

| 主题 | 类型 | 推荐场景 |
|------|------|----------|
| `github-dark`（默认） | 暗色 | GitHub README、技术文档 |
| `github-light` | 亮色 | 明亮文档、演示文稿 |
| `tokyo-night` | 暗色 | 优雅暗色、博客 |
| `tokyo-night-storm` | 暗色 | Tokyo Night 变体 |
| `tokyo-night-light` | 亮色 | Tokyo Night 亮色 |
| `catppuccin-mocha` | 暗色 | 温暖暗色 |
| `catppuccin-latte` | 亮色 | 温暖亮色 |
| `nord` | 暗色 | 冷色调、北欧风 |
| `nord-light` | 亮色 | 冷色调亮色 |
| `dracula` | 暗色 | 经典暗色 |
| `one-dark` | 暗色 | VS Code 风格 |
| `solarized-dark` | 暗色 | 经典 Solarized |
| `solarized-light` | 亮色 | 经典 Solarized 亮色 |
| `zinc-dark` | 暗色 | 极简暗色 |
| `zinc-light` | 亮色 | 极简亮色 |

**主题快速判断**：
- 用户说"暗色/dark/GitHub" → `github-dark`
- 用户说"亮色/light/明亮" → `github-light`
- 用户说"优雅/elegant" → `tokyo-night`
- 用户说"温暖/warm/mocha" → `catppuccin-mocha`
- 用户说"冷色/cold/北欧" → `nord`
- 用户说"紫色/dracula" → `dracula`
- 用户说"简约/minimal" → `zinc-dark` 或 `zinc-light`
- 默认 → `github-dark`

### 写入 .mmd 文件并渲染

先用 `Write` 工具将 Mermaid 源码写入 `.mmd` 文件，然后调用：

```bash
node ~/.claude/skills/code-to-diagram/scripts/code_to_diagram.js render \
  --file <路径/diagram.mmd> \
  --theme <主题名> \
  --name <输出文件基础名> \
  --output-dir <保存目录>
```

---

## 第三步 B —— SVG 路径

### 1. 选择风格

读取 `references/style-diagram-matrix.md` 快速选择风格，然后读取对应的风格参考文件：

| 风格 | 参考文件 | 适用场景 |
|------|----------|----------|
| Flat Icon（默认） | `references/style-1-flat-icon.md` | 文档、博客、演示 |
| Dark Terminal | `references/style-2-dark-terminal.md` | GitHub README、技术博客 |
| Blueprint | `references/style-3-blueprint.md` | 架构文档、RFC |
| Notion Clean | `references/style-4-notion-clean.md` | Notion 嵌入、Wiki |
| Glassmorphism | `references/style-5-glassmorphism.md` | 营销页、发布会 |

**风格快速判断**：
- 用户说"暗色/dark/terminal/GitHub" → Dark Terminal
- 用户说"蓝图/blueprint/工程" → Blueprint
- 用户说"简洁/clean/Notion" → Notion Clean
- 用户说"毛玻璃/glass/现代" → Glassmorphism
- 默认或"文档/博客" → Flat Icon

### 2. 生成 SVG

读取选定的风格参考文件和 `references/icons.md`，按照以下步骤生成 SVG：

1. 以风格参考文件中的 **SVG 模板** 为起点
2. 根据内容规划布局（节点位置、连线路径）
3. 使用 `references/icons.md` 中的 **语义图形** 表示不同类型的组件
4. 使用 **产品图标** 标识具体产品/服务
5. 使用 **箭头语义** 区分不同类型的数据流
6. 当使用 2+ 种箭头类型时，添加 **图例**
7. 所有文字标签使用中文

**关键约束**：
- **禁止 `@import url()`**——rsvg-convert 无法获取外部资源
- 字体通过内联 `<style>` 声明
- viewBox 根据实际内容调整

### 3. 写入 SVG 文件并渲染

先用 `Write` 工具将 SVG 写入 `.svg` 文件，然后调用：

```bash
node ~/.claude/skills/code-to-diagram/scripts/code_to_diagram.js render \
  --engine svg \
  --file <路径/diagram.svg> \
  --name <输出文件基础名> \
  --style <风格名> \
  --output-dir <保存目录>
```

---

## 第四步 —— 告知用户图片路径

脚本最后一行输出 JSON，包含输出文件路径：

```json
{"md":"/path/to/diagram.md","png":"/path/to/diagram.png","engine":"mermaid","theme":"tokyo-night","renderer":"beautiful-mermaid"}
```

**重要：不要使用 `Read` 工具读取 PNG 文件来内联展示图片。** PNG 图片体积大，直接读取会消耗大量上下文窗口，极易导致超限。只需将生成的文件路径告知用户即可，例如：

> 已生成图表：
> - Markdown: `/path/to/diagram.md`
> - PNG: `/path/to/diagram.png`

用户可以自行打开文件查看图片。

---

## 语义图形速查表

使用 SVG 引擎时，根据组件类型选择对应图形（详见 `references/icons.md`）：

| 图形 | 含义 | 使用时机 |
|------|------|----------|
| 双边框圆角矩形 + ⚡ | LLM / 模型 | 大语言模型调用 |
| 六边形 | Agent / 编排器 | 自主代理、编排 |
| 圆柱体 + 内环 | 向量数据库 | Pinecone、Weaviate 等 |
| 圆柱体 | 传统数据库 | PostgreSQL、Redis 等 |
| 矩形 + ⚙ | 工具 / 函数 | API 调用、工具执行 |
| 菱形 | 决策点 | 条件判断 |
| 圆形 + 身体 | 用户 | 人类交互入口 |
| 虚线矩形 | 记忆节点 | 短期/长期记忆 |
| 水平管道 | 队列 / 消息流 | Kafka、RabbitMQ 等 |
| 小六边形 | API 网关 | 请求路由 |
| 红绿灯矩形 | 浏览器 | Web 客户端 |
| 折角矩形 | 文档 | 配置文件、日志 |

---

## 箭头语义速查表

| 类型 | 线型 | 含义 |
|------|------|------|
| 实线 2px | `stroke-width="2"` | 主数据流 |
| 虚线 1.5px | `stroke-dasharray="5,3"` | 记忆/缓存写入 |
| 点线 1.5px | `stroke-dasharray="4,2"` | 异步事件 |
| 曲线 1.5px | 贝塞尔曲线 | 反馈/循环 |

**颜色编码**：蓝=主数据流，红=错误/备选，绿=数据写入，紫=异步事件。

**规则**：使用 2+ 种箭头类型时，必须在左下角添加图例。

---

## 产品图标速查表

常用产品（完整列表见 `references/icons.md`）：

| 类别 | 产品 | 品牌色 |
|------|------|--------|
| AI/ML | OpenAI `#10A37F` · Anthropic `#D97757` · Gemini `#4285F4` · LLaMA `#0467DF` · Mistral `#FF7000` |
| RAG | LangChain `#1C3C3C` · LlamaIndex `#8B5CF6` · CrewAI `#EF4444` · Mem0 `#6366F1` |
| 向量库 | Pinecone `#1C1C2E` · Weaviate `#FA0050` · Qdrant `#DC244C` · Chroma `#FF6B35` |
| 数据库 | PostgreSQL `#336791` · MySQL `#4479A1` · MongoDB `#47A248` · Redis `#DC382D` |
| 消息队列 | Kafka `#231F20` · RabbitMQ `#FF6600` |
| 云平台 | AWS `#FF9900` · GCP `#4285F4` · Azure `#0089D6` · Docker `#2496ED` · K8s `#326CE5` |

---

## 命令行参数

```
node code_to_diagram.js render [选项]

通用选项：
  --file,       -f  <路径>      输入文件（.mmd 或 .svg）
  --content,    -c  <字符串>    Mermaid 源码（仅 mermaid 引擎）
  --name,       -n  <字符串>    输出文件基础名（默认：diagram）
  --output-dir, -o  <路径>      输出目录（默认：当前工作目录）
  --engine,     -e  <引擎>      mermaid | svg（默认：mermaid）
  --help,       -h              帮助信息

Mermaid 引擎（beautiful-mermaid，默认）：
  --theme,      -t  <主题>      15 个内置主题（默认：github-dark）
  --renderer        <渲染器>    auto | beautiful-mermaid | mmdc（默认：auto）
  --padding         <像素>      画布内边距（默认：40）
  --transparent                 透明背景
  --bg,         -b  <颜色>      自定义背景色（覆盖主题）

mmdc 回退选项：
  --width,      -W  <像素>      画布宽度（默认：2400）
  --height,     -H  <像素>      画布高度（默认：4000）
  --scale,      -s  <倍数>      缩放系数（默认：3）

SVG 引擎：
  --style       <风格>          flat-icon | dark-terminal | blueprint | notion-clean | glassmorphism
  --svg-width   <像素>          输出宽度（默认：1920）
```

---

## 依赖说明

**Mermaid 引擎**：

- **beautiful-mermaid**（主要）：`npm install`（在 `scripts/` 目录下）
- **rsvg-convert**（必需）：将 SVG 转换为 PNG
- **mmdc**（可选，仅回退时需要）：处理 gantt、mindmap、pie、journey、gitgraph

**SVG 引擎**：依赖 `rsvg-convert`（来自 librsvg）。

**安装 rsvg-convert**：

```bash
# macOS
brew install librsvg

# Debian / Ubuntu
apt-get install librsvg2-bin
```

**安装 beautiful-mermaid**：

```bash
cd ~/.claude/skills/code-to-diagram/scripts
npm install
```