介绍
# Diagram Generator
## 概述
通过创建结构化的 JSON 描述并将文件生成委托给 `mcp-diagram-generator` MCP 服务器，来生成和编辑多种格式（drawio、mermaid、excalidraw）的图表。
> **联系信息** 如果您遇到任何问题，请通过 [[email protected]](mailto:[email protected]) 联系 **AlkaidY**。
## 先决条件检查
**重要提示**：此技能需要安装并配置 `mcp-diagram-generator` MCP 服务器。
### 快速验证
在使用此技能之前，请检查您是否可以访问以下工具以验证 MCP 服务器是否可用： - `mcp__mcp-diagram-generator__get_config` - `mcp__mcp-diagram-generator__generate_diagram` - `mcp__mcp-diagram-generator__init_config`
如果这些工具**不可用**，您需要先配置 MCP 服务器（见下文）。
### 安装与配置
**选项 1：使用 npx（推荐 - 自动下载包）**
将以下内容添加到您的 Claude Code 配置文件中：
- **全局配置** (`~/.claude.json`) 适用于所有项目，或 - **项目配置** (`.claude.json`) 适用于特定项目
```json { "mcpServers": { "mcp-diagram-generator": { "command": "npx", "args": ["-y", "mcp-diagram-generator"] } } } ```
添加此配置后： 1. 重启 Claude Code 2. MCP 服务器将在首次使用时通过 npx 自动下载 3. 无需手动安装
**选项 2：本地开发（面向开发者）**
如果您正在本地开发 MCP 服务器：
```json { "mcpServers": { "mcp-diagram-generator": { "command": "node", "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"] } } } ```
### 验证步骤
配置完成后，验证其是否正常工作：
1. 检查配置：调用 `get_config()` 工具 2. 如果成功，您将看到当前路径和初始化状态 3. 如果工具不存在，请检查您的配置文件语法
### 常见问题
**问题**：“Tool not found”（工具未找到）错误 - **解决方案**：未配置 MCP 服务器。请按照上述安装步骤操作。
**问题**：配置看起来正确但工具仍然不可用 - **解决方案**：重启 Claude Code 以重新加载 MCP 服务器配置
## 快速开始
### 首次使用
首次使用时，MCP 服务器将自动： 1. 创建默认配置文件 (`.diagram-config.json`) 2. 如果默认输出目录不存在，则创建它们 3. 使用合理的默认值：`diagrams/{format}/`
您可以随时使用 `init_config` 工具自定义路径。
### 基本用法
**简单示例** - 只需提供图表规范，让服务器处理其余部分：
``` User: "创建一个网络拓扑图" ```
技能将： 1. 生成 JSON 规范 2. 仅使用 `diagram_spec` 参数调用 `generate_diagram` 3. 服务器自动创建目录并保存到 `diagrams/{format}/{title}-{date}.{ext}`
## 工作流
### 第 1 步：理解需求
从用户的自然语言中提取： - **图表类型**：流程图、时序图、类图、ER 图、思维导图、架构图、网络拓扑 - **内容**：节点、关系、嵌套结构（针对网络拓扑） - **样式/主题**：如果提到（例如“简洁风格”、“详细”） - **输出偏好**：特定的文件名？自定义路径？
### 第 2 步：选择格式
使用 [format-selection-guide.md](references/format-selection-guide.md) 进行决定：
| 格式 | 最适用于 | |--------|----------| | **drawio** | 复杂图表、具有嵌套容器的网络拓扑、精细的样式控制、手动编辑 | | **mermaid** | 快速生成、代码友好、版本控制、文档 | | **excalidraw** | 手绘风格、创意/图表灵活性、非正式草图 |
### 第 3 步：生成结构化 JSON
按照 [JSON Schema](references/json-schema-guide.md) 创建 JSON 描述。关键结构：
```json { "format": "drawio", "title": "diagram name", "elements": [ { "id": "unique-id", "type": "container|node|edge", "name": "display name", "level": "environment|datacenter|zone|device", // for network topology "style": {...}, "geometry": {...}, "children": [...] // for nested containers } ] } ```
**重要提示**：为所有元素使用唯一的 ID。对于嵌套结构，请维护父子关系。
### 第 4 步：调用 MCP 服务器
**选项 A：使用默认值（推荐）**
```json { "diagram_spec": <the JSON object created above> // output_path is optional - server will use configured default // filename is optional - server will auto-generate based on title and date } ```
MCP 服务器将： - 验证 JSON 模式 - 生成相应的 XML/JSON/markdown - 如有必要，自动创建输出目录 - 保存到配置的默认路径（例如 `diagrams/drawio/network-topology-2025-02-03.drawio`）
**选项 B：指定自定义路径**
```json { "diagram_spec": <the JSON object>, "output_path": "custom/path/to/diagram.drawio", "filename": "my-custom-name" // optional, overrides auto-generated filename } ```
**选项 C：仅提供文件名，使用默认目录**
```json { "diagram_spec": <the JSON object>, "filename": "my-diagram.drawio" // Saves to diagrams/{format}/my-diagram.drawio } ```
### 第 5 步：编辑现有图表
1. **读取现有文件** 以了解结构 2. **解析** 图表（如果可用，请使用 MCP 工具，或读取原始文件） 3. 根据用户的更改请求 **修改** JSON 描述 4. **生成** 新图表（覆盖或创建新文件）
## 配置管理
### 初始化配置
**使用默认值初始化：** ``` Call: init_config() Result: Creates .diagram-config.json with default paths ```
**使用自定义路径初始化：** ``` Call: init_config({ paths: { drawio: "output/diagrams/drawio", mermaid: "output/diagrams/mermaid", excalidraw: "output/diagrams/excalidraw" } }) ```
### 查看当前配置
``` Call: get_config() Returns: Current paths and initialization status ```
### 更新单个路径
``` Call: set_output_path({ format: "drawio", path: "custom/drawio-path" }) ```
## 支持的图表类型
### 流程图 - 简单的流程、决策树 - 使用 **mermaid** 进行快速输出 - 使用 **drawio** 处理具有多个分支的复杂布局
### 时序图 - 显示组件随时间变化的交互 - **推荐使用 mermaid**（原生支持） - 如果需要自定义样式，请使用 **drawio**
### 类图 - 显示类、方法、关系 - **推荐使用 mermaid**（紧凑、标准 UML） - 对于包含许多类的详细图表，请使用 **drawio**
### ER 图 - 数据库模式、实体关系 - **推荐使用 mermaid** - 对于具有许多关系的复杂模式，请使用 **drawio**
### 思维导图 - 分层思想、头脑风暴 - **推荐使用 mermaid**（原生支持） - 使用 **excalidraw** 获取创意/手绘风格
### 架构图 - 系统架构、组件关系 - 对于复杂系统，**推荐使用 drawio** - 用于高层概览的 **mermaid**
### 网络拓扑 - 网络环境、数据中心、区域、设备 - **必须使用 drawio**（4 层嵌套：环境 → 数据中心 → 区域 → 设备） - 有关模式，请参阅 [network-topology-examples.md](references/network-topology-examples.md)
## 网络拓扑特别说明
网络拓扑图需要 4 层分层结构：
``` Environment (level="environment") └── Datacenter (level="datacenter") └── Zone (level="zone") └── Device (type="node") ```
**样式约定**： - **环境**：`fillColor: #e1d5e7`，`strokeColor: #9673a6`（紫色） - **数据中心**：`fillColor: #d5e8d4`，`strokeColor: #82b366`（绿色） - **区域**：`fillColor: #fff2cc`，`strokeColor: #d6b656`（黄色） - **设备**：基于设备类型（路由器、交换机、防火墙等）
**设备类型和样式**： - 路由器：`strokeColor: #607D8B`（蓝灰色） - 交换机：`strokeColor: #4CAF50`（绿色） - 防火墙：`strokeColor: #F44336`（红色） - PC/服务器：`strokeColor: #607D8B`（蓝灰色）
## 常见模式
### 模式 1：简单流程图 (Mermaid)
用户：“画一个用户登录流程图，包含登录验证、重定向、错误处理”
生成 JSON： ```json { "format": "mermaid", "title": "用户登录流程", "elements": [ {"type": "node", "id": "start", "name": "开始", "geometry": {"x": 0, "y": 0}}, {"type": "node", "id": "login", "name": "输入用户名密码", "geometry": {"x": 0, "y": 100}}, {"type": "node", "id": "validate", "name": "验证", "geometry": {"x": 0, "y": 200}}, {"type": "node", "id": "success", "name": "登录成功", "geometry": {"x": -100, "y": 300}}, {"type": "node", "id": "error", "name": "显示错误", "geometry": {"x": 100, "y": 300}}, {"type": "edge", "source": "start", "target": "login"}, {"type": "edge", "source": "login", "target": "validate"}, {"type": "edge", "source": "validate", "target": "success", "label": "成功"}, {"type": "edge", "source": "validate", "target": "error", "label": "失败"} ] } ```
调用 MCP： ``` generate_diagram({ diagram_spec: <above JSON>, format: "mermaid" // No output_path needed - auto-saves to diagrams/mermaid/ }) ```
### 模式 2：网络拓扑 (Drawio)
用户：“创建一个网络拓扑图，包含省中心机房（上联区、汇聚区、终端区），连接到生产网”
使用嵌套容器生成 JSON（有关详细信息，请参阅 [json-schema-guide.md](references/json-schema-guide.md)）。
调用 MCP： ``` generate_diagram({ diagram_spec: <network topology JSON>, filename: "省中心网络拓扑" // Optional, for custom filename }) ```
## 资源
### references/ - **format-selection-guide.md**：何时使用 drawio、mermaid 或 excalidraw - **json-schema-guide.md**：包含所有图表类型示例的完整 JSON 模式 - **network-topology-examples.md**：网络拓扑模式的示例 JSON
### assets/ - 无需模板 - MCP 服务器处理所有生成工作
### scripts/ - 未使用 - 所有生成工作均委托给 MCP 服务器
## 故障排除
### MCP 服务器设置
如果 `mcp-diagram-generator` 不可用，您需要安装它。
**选项 1：使用 npx（推荐）**
添加到您的 Claude Code/OpenCode 设置中：
```json { "mcpServers": { "diagram-generator": { "command": "npx", "args": ["-y", "mcp-diagram-generator"] } } } ```
**选项 2：本地开发**
1. 安装依赖项：`cd mcp-diagram-generator && npm install` 2. 构建：`npm run build` 3. 使用本地路径进行配置： ```json { "mcpServers": { "diagram-generator": { "command": "node", "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"] } } } ```
### 无效的 JSON 模式
如果 MCP 服务器返回验证错误： 1. 检查 [json-schema-guide.md](references/json-schema-guide.md) 2. 验证所有必填字段是否存在 3. 确保所有 ID 都是唯一的 4. 检查父子关系
### 目录未找到
**旧行为**：如果目录不存在则报错 **新行为**：目录会自动创建 ✅
如果您仍然看到目录错误： 1. 检查项目目录的写入权限 2. 使用 `get_config()` 验证配置 3. 使用 `init_config()` 重新初始化
### 文件扩展名错误
服务器会根据格式自动使用正确的扩展名： - drawio → `.drawio` - mermaid → `.md` - excalidraw → `.excalidraw`
您无需在 filename 参数中指定扩展名。
### 嵌套容器问题（网络拓扑）
- 验证 `level` 字段与层级结构（环境/数据中心/区域）匹配 - 检查子元素中的 `parent` ID 是否正确 - 确保几何坐标是相对于父容器的
## 最佳实践
### 1. 使用默认路径
让服务器管理输出路径以保持一致性：
```json { "diagram_spec": <spec> // Don't specify output_path unless necessary } ```
### 2. 提供描述性标题
标题用于自动生成的文件名：
```json { "title": "生产环境网络拓扑-亦庄与西五环", // Generates: 生产环境网络拓扑-亦庄与西五环-2025-02-03.drawio } ```
### 3. 使用配置设置自定义路径
与其每次都指定 output_path，不如一次性配置：
``` First time: init_config({ paths: { drawio: "custom/path" } }) After that: Just use generate_diagram() without output_path ```
### 4. 故障排除时检查配置
``` get_config() // Shows all paths and status ```