名称： diagram-generator
描述： 生成和编辑多种类型的图表（包括 draw.io、Mermaid 和 Excalidraw）。此工具支持流程图、序列图、类图、实体关系图、思维导图、架构图和网络拓扑等常见图表类型。
自然语言创建：基于简单的文本描述创建新图表。
遗留文件支持：读取和修改现有的 .drawio、.mmd 或 Excalidraw 文件。
MCP 服务器集成：利用专用的 MCP 服务器生成文件，以最小化令牌消耗并确保一致的输出格式。
自动配置：* 默认输出路径：图表保存到项目目录下的 diagrams/{format}/ 中。
自定义：支持自定义文件路径和自动目录创建。
version： 1.1.1

图表生成器

概述

通过创建结构化的 JSON 描述，并将文件生成任务委托给 mcp-diagram-generator MCP 服务器，来生成和编辑多种格式的图表。

联系信息 如果遇到任何问题，请联系 AlkaidY：tccio2023@gmail.com。

先决条件检查

重要：此技能需要安装并配置 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) 适用于特定项目

{
  "mcpServers": {
    "mcp-diagram-generator": {
      "command": "npx",
      "args": ["-y", "mcp-diagram-generator"]
    }
  }
}

添加此配置后：
1. 重启 Claude Code
2. MCP 服务器将在首次使用时通过 npx 自动下载
3. 无需手动安装

选项 2：本地开发（适用于开发者）

如果您在本地开发 MCP 服务器：

{
  "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 工具自定义路径。

基本用法

简单示例 - 只需提供图表规范，其余由服务器处理：

用户："创建一个网络拓扑图"

技能将：
1. 生成 JSON 规范
2. 仅使用 diagram_spec 参数调用 generate_diagram
3. 服务器自动创建目录并保存到 diagrams/{format}/{title}-{date}.{ext}

工作流程

步骤 1：理解需求

从用户的自然语言中提取：
- 图表类型：流程图、序列图、类图、ER 图、思维导图、架构图、网络拓扑
- 内容：节点、关系、嵌套结构（用于网络拓扑）
- 样式/主题：如果提及（例如，"简洁风格"、"详细"）
- 输出偏好：特定文件名？自定义路径？

步骤 2：选择格式

使用 format-selection-guide.md 来决定：

步骤 3：生成结构化 JSON

按照 JSON 模式指南 创建 JSON 描述。关键结构：

{
  "format": "drawio",
  "title": "图表名称",
  "elements": [
    {
      "id": "唯一标识",
      "type": "container|node|edge",
      "name": "显示名称",
      "level": "environment|datacenter|zone|device", // 用于网络拓扑
      "style": {...},
      "geometry": {...},
      "children": [...] // 用于嵌套容器
    }
  ]
}

重要：为所有元素使用唯一 ID。对于嵌套结构，维护父子关系。

步骤 4：调用 MCP 服务器

选项 A：使用默认值（推荐）

{
  "diagram_spec": <上面创建的 JSON 对象>
  // output_path 可选 - 服务器将使用配置的默认值
  // filename 可选 - 服务器将基于标题和日期自动生成
}

MCP 服务器将：
- 验证 JSON 模式
- 生成相应的 XML/JSON/标记语言
- 自动创建输出目录（如果需要）
- 保存到配置的默认路径（例如，diagrams/drawio/network-topology-2025-02-03.drawio）

选项 B：指定自定义路径

{
  "diagram_spec": <JSON 对象>,
  "output_path": "custom/path/to/diagram.drawio",
  "filename": "my-custom-name" // 可选，覆盖自动生成的文件名
}

选项 C：仅提供文件名，使用默认目录

{
  "diagram_spec": <JSON 对象>,
  "filename": "my-diagram.drawio"
  // 保存到 diagrams/{format}/my-diagram.drawio
}

步骤 5：编辑现有图表

1. 读取现有文件以了解结构
2. 解析图表（使用 MCP 工具，或读取原始文件）
3. 修改 JSON 描述（基于用户的更改请求）
4. 生成新图表（覆盖或创建新文件）

配置管理

初始化配置

使用默认值初始化：

调用：init_config()
结果：使用默认路径创建 .diagram-config.json

使用自定义路径初始化：

调用：init_config({
  paths: {
    drawio: "output/diagrams/drawio",
    mermaid: "output/diagrams/mermaid",
    excalidraw: "output/diagrams/excalidraw"
  }
})

查看当前配置

调用：get_config()
返回：当前路径和初始化状态

更新单个路径

调用：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 了解模式

网络拓扑特别说明

网络拓扑图需要 4 级层次结构：

环境 (level="environment")
  └── 数据中心 (level="datacenter")
        └── 区域 (level="zone")
              └── 设备 (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：

{
  "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: <上面的 JSON>,
  format: "mermaid"
  // 无需 output_path - 自动保存到 diagrams/mermaid/
})

模式 2：网络拓扑 (Drawio)

用户："创建一个网络拓扑图，包含省中心机房（上联区、汇聚区、终端区），连接到生产网"

生成带嵌套容器的 JSON（详情见 json-schema-guide.md）。

调用 MCP：

generate_diagram({
  diagram_spec: <网络拓扑 JSON>,
  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 设置中：

{
  "mcpServers": {
    "diagram-generator": {
      "command": "npx",
      "args": ["-y", "mcp-diagram-generator"]
    }
  }
}

选项 2：本地开发

1. 安装依赖：cd mcp-diagram-generator && npm install
2. 构建：npm run build
3. 使用本地路径配置：

{
  "mcpServers": {
    "diagram-generator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]
    }
  }
}

无效的 JSON 模式

如果 MCP 服务器返回验证错误：
1. 检查 json-schema-guide.md
2. 验证所有必填字段是否存在
3. 确保所有 ID 唯一
4. 检查父子关系

目录未找到

旧行为：如果目录不存在则报错
新行为：目录自动创建 ✅

如果仍然看到目录错误：
1. 检查项目目录的写入权限
2. 使用 get_config() 验证配置
3. 使用 init_config() 重新初始化

文件扩展名错误

服务器根据格式自动使用正确的扩展名：
- drawio → .drawio
- mermaid → .md
- excalidraw → .excalidraw

您无需在 filename 参数中指定扩展名。

嵌套容器问题（网络拓扑）

• 验证 level 字段与层次结构匹配（environment/datacenter/zone）
• 检查子元素中的 parent ID 是否正确
• 确保几何坐标相对于父容器

最佳实践

1. 使用默认路径

让服务器管理输出路径以确保一致性：

{
  "diagram_spec": <规范>
  // 除非必要，否则不要指定 output_path
}

2. 提供描述性标题

标题用于自动生成文件名：

{
  "title": "生产环境网络拓扑-亦庄与西五环",
  // 生成：生产环境网络拓扑-亦庄与西五环-2025-02-03.drawio
}

3. 使用配置进行自定义路径

不要每次都指定 output_path，而是配置一次：

首次：init_config({ paths: { drawio: "custom/path" } })
之后：只需使用 generate_diagram() 而无需 output_path

4. 故障排除时检查配置

get_config() // 显示所有路径和状态