Skill: zhouchang1988/code-to-diagram (version 2.0.0)

--- 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 ```

path: scripts/package.json
content: {
  "name": "code-to-diagram-scripts",
  "private": true,
  "type": "module",
  "dependencies": {
    "beautiful-mermaid": "^1"
  }
}


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: clean (LOW)