excalidraw-diagram-generator

Excalidraw 图表生成器

一个用于根据自然语言描述生成 Excalidraw 格式图表的技能。此技能有助于创建流程、系统、关系和想法的可视化表示，无需手动绘制。

何时使用此技能

当用户请求以下内容时使用此技能：

• “创建一个图表显示……”
• “为……制作流程图”
• “可视化……的过程”
• “绘制……的系统架构”
• “生成关于……的思维导图”
• “为……创建一个 Excalidraw 文件”
• “显示……之间的关系”
• “为……的工作流绘制图表”

支持的图表类型：

• 📊 流程图：顺序流程、工作流、决策树
• 🔗 关系图：实体关系、系统组件、依赖关系
• 🧠 思维导图：概念层次结构、头脑风暴结果、主题组织
• 🏗️ 架构图：系统设计、模块交互、数据流
• 📈 数据流图（DFD）：数据流可视化、数据转换过程
• 🏊 业务流（泳道）：跨职能工作流、基于参与者的流程流
• 📦 类图：面向对象设计、类结构和关系
• 🔄 序列图：随时间变化的对象交互、消息流
• 🗃️ ER 图：数据库实体关系、数据模型

先决条件

• 清晰的描述，说明应可视化什么
• 识别关键实体、步骤或概念
• 理解元素之间的关系或流动

分步工作流

第 1 步：理解请求

分析用户的描述以确定：

1. 图表类型（流程图、关系图、思维导图、架构图）
2. 关键元素（实体、步骤、概念）
3. 关系（流动、连接、层次结构）
4. 复杂度（元素数量）

第 2 步：选择合适的图表类型

用户意图	图表类型	示例关键词
流程、步骤、程序	流程图	“工作流”、“流程”、“步骤”、“程序”
连接、依赖关系、关联	关系图	“关系”、“连接”、“依赖关系”、“结构”
概念层次结构、头脑风暴	思维导图	“思维导图”、“概念”、“想法”、“分解”
系统设计、组件	架构图	“架构”、“系统”、“组件”、“模块”
数据流、转换过程	数据流图（DFD）	“数据流”、“数据处理”、“数据转换”
跨职能流程、参与者职责	业务流（泳道）	“业务流程”、“泳道”、“参与者”、“职责”
面向对象设计、类结构	类图	“类”、“继承”、“OOP”、“对象模型”
交互序列、消息流	序列图	“序列”、“交互”、“消息”、“时间线”
数据库设计、实体关系	ER 图	“数据库”、“实体”、“关系”、“数据模型”

第 3 步：提取结构化信息

对于流程图：

• 顺序步骤列表
• 决策点（如有）
• 起点和终点

对于关系图：

• 实体/节点（名称 + 可选描述）
• 实体之间的关系（从 → 到，带标签）

对于思维导图：

• 中心主题
• 主要分支（建议 3-6 个）
• 每个分支的子主题（可选）

对于数据流图（DFD）：

• 数据源和目标（外部实体）
• 过程（数据转换）
• 数据存储（数据库、文件）
• 数据流（箭头表示数据从左到右或从左上到右下的移动）
• 重要：不要表示过程顺序，只表示数据流

对于业务流程（泳道图）：

• 参与者/角色（部门、系统、人员）- 显示为顶部列
• 流程泳道（每个参与者下方的垂直泳道）
• 流程框（每个泳道内的活动）
• 流程箭头（连接流程框，包括跨泳道交接）

对于类图：

• 带名称的类
• 带可见性（+、-、#）的属性
• 带可见性和参数的方法
• 关系：继承（实线 + 白色三角形）、实现（虚线 + 白色三角形）、关联（实线）、依赖（虚线）、聚合（实线 + 白色菱形）、组合（实线 + 实心菱形）
• 多重性表示法（1、0..1、1..、）

对于序列图：

• 对象/参与者（在顶部水平排列）
• 生命线（从每个对象向下的垂直线）
• 消息（生命线之间的水平箭头）
• 同步消息（实线箭头）、异步消息（虚线箭头）
• 返回值（虚线箭头）
• 激活框（执行期间生命线上的矩形）
• 时间从上到下流动

对于 ER 图：

• 实体（带实体名称的矩形）
• 属性（列在实体内）
• 主键（带下划线或用 PK 标记）
• 外键（用 FK 标记）
• 关系（连接实体的线）
• 基数：1:1（一对一）、1:N（一对多）、N:M（多对多）
• 用于多对多关系的连接/关联实体（虚线矩形）

第 4 步：生成 Excalidraw JSON

创建包含适当元素的 .excalidraw 文件：

可用的元素类型：

• rectangle：用于实体、步骤、概念的框
• ellipse：用于强调的替代形状
• diamond：决策点
• arrow：方向连接
• text：标签和注释

要设置的关键属性：

• 位置：x、y 坐标
• 大小：width、height
• 样式：strokeColor、backgroundColor、fillStyle
• 字体：fontFamily: 5（Excalifont - 所有文本元素必需）
• 文本：标签的内嵌文本
• 连接：箭头的 points 数组

重要：所有文本元素必须使用 fontFamily: 5（Excalifont），以保持一致的外观。

第 5 步：格式化输出

组织完整的 Excalidraw 文件：

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    // Array of diagram elements
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

第 6 步：保存并提供说明

1. 保存为 <descriptive-name>.excalidraw
2. 告知用户如何打开：
   • 访问 https://excalidraw.com
   • 点击"Open"或拖放文件
   • 或使用 Excalidraw VS Code 扩展

最佳实践

元素数量指南

图表类型	建议数量	最大数量
流程图步骤	3-10	15
关系实体	3-8	12
思维导图分支	4-6	8
每个分支的思维导图子主题	2-4	6

布局建议

1. 起始位置：将重要元素居中，使用一致的间距
2. 间距：
   • 水平间距：元素之间 200-300px
   • 垂直间距：行之间 100-150px
3. 颜色：使用一致的配色方案
   • 主要元素：浅蓝色（#a5d8ff）
   • 次要元素：浅绿色（#b2f2bb）
   • 重要/核心：黄色（#ffd43b）
   • 警示/警告：浅红色（#ffc9c9）
4. 文字大小：16-24px 以保证可读性
5. 字体：所有文本元素始终使用 fontFamily: 5（Excalifont）
6. 箭头样式：简单流程使用直线箭头，复杂关系使用曲线箭头

复杂度管理

如果用户请求包含过多元素：

• 建议拆分为多个图表
• 优先处理主要元素
• 主动提出创建详细的子图表

示例回复：

"Your request includes 15 components. For clarity, I recommend:
1. High-level architecture diagram (6 main components)
2. Detailed diagram for each subsystem

Would you like me to start with the high-level view?"

示例提示词与回复

示例 1：简单流程图

用户：“为用户注册创建一个流程图”

Agent 生成：

1. 提取步骤：“输入邮箱” → “验证邮箱” → “设置密码” → “完成”
2. 创建包含 4 个矩形 + 3 个箭头的流程图
3. 保存为 user-registration-flow.excalidraw

示例 2：关系图

用户：“绘制 User、Post 和 Comment 实体之间的关系图”

Agent 生成：

1. 实体：User、Post、Comment
2. 关系：User → Post（“创建”）、User → Comment（“撰写”）、Post → Comment（“包含”）
3. 保存为 user-content-relationships.excalidraw

示例 3：思维导图

用户：“关于机器学习概念的思维导图”

Agent 生成：

1. 中心：“机器学习”
2. 分支：监督学习、无监督学习、强化学习、深度学习
3. 每个分支下的子主题
4. 保存为 machine-learning-mindmap.excalidraw

故障排查

问题	解决方案
元素重叠	增加坐标之间的间距
文字无法放入框内	增加框的宽度或减小字体大小
元素过多	拆分为多个图表
布局不清晰	使用网格布局（行/列）或径向布局（思维导图）
颜色不一致	根据元素类型预先定义调色板

进阶技巧

网格布局（用于关系图）

const columns = Math.ceil(Math.sqrt(entityCount));
const x = startX + (index % columns) * horizontalGap;
const y = startY + Math.floor(index / columns) * verticalGap;

径向布局（用于思维导图）

const angle = (2 * Math.PI * index) / branchCount;
const x = centerX + radius * Math.cos(angle);
const y = centerY + radius * Math.sin(angle);

自动生成的 ID

使用时间戳 + 随机字符串生成唯一 ID：

const id = Date.now().toString(36) + Math.random().toString(36).substr(2);

输出格式

始终提供：

1. ✅ 完整的 .excalidraw JSON 文件
2. 📊 所创建内容的摘要
3. 📝 元素数量
4. 💡 打开/编辑说明

示例摘要：

Created: user-workflow.excalidraw
Type: Flowchart
Elements: 7 rectangles, 6 arrows, 1 title text
Total: 14 elements

To view:
1. Visit https://excalidraw.com
2. Drag and drop user-workflow.excalidraw
3. Or use File → Open in Excalidraw VS Code extension

验证清单

在交付图表之前：

• 所有元素都有唯一 ID
• 坐标避免重叠
• 文字可读（字体大小 16+）
• 所有文本元素使用 fontFamily: 5（Excalifont）
• 箭头连接符合逻辑
• 颜色遵循一致的方案
• 文件是有效的 JSON
• 元素数量合理（为保证清晰度 <20）

图标库（可选增强）

对于专业图表（例如 AWS/GCP/Azure 架构图），你可以使用 Excalidraw 的预制图标库。这样可以提供专业、标准化的图标，而不是基本形状。

当用户请求图标时

如果用户要求 AWS/云架构图，或提到希望使用特定图标：

1. 检查库是否存在：查找 libraries/<library-name>/reference.md

2. 如果库存在：继续使用图标（见下方 AI 助手工作流）

3. 如果库不存在：回复设置说明：

   To use [AWS/GCP/Azure/etc.] architecture icons, please follow these steps:
   
   1. Visit https://libraries.excalidraw.com/
   2. Search for "[AWS Architecture Icons/etc.]" and download the .excalidrawlib file
   3. Create directory: skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
   4. Place the downloaded file in that directory
   5. Run the splitter script:
      python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
   
   This will split the library into individual icon files for efficient use.
   After setup is complete, I can create your diagram using the actual AWS/cloud icons.
   
   Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses) 
   which you can later replace with icons manually in Excalidraw.
   

用户设置说明（详细）

步骤 1：创建库目录

mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons

步骤 2：下载库

• 访问：https://libraries.excalidraw.com/
• 搜索你想要的图标集（例如，“AWS Architecture Icons”）
• 点击下载以获取 .excalidrawlib 文件
• 示例类别（可用性可能有所不同；请在网站上确认）：
  • 云服务图标
  • UI/Material 图标
  • 流程图符号

步骤 3：放置库文件

• 将下载的文件重命名为与目录名称匹配（例如，aws-architecture-icons.excalidrawlib）
• 将其移动到步骤 1 中创建的目录

步骤 4：运行拆分脚本

python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/

步骤 5：验证设置 运行脚本后，验证以下结构是否存在：

skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
  aws-architecture-icons.excalidrawlib  (original)
  reference.md                          (generated - icon lookup table)
  icons/                                (generated - individual icon files)
    API-Gateway.json
    CloudFront.json
    EC2.json
    Lambda.json
    RDS.json
    S3.json
    ...

AI 助手工作流

当 libraries/ 中有可用的图标库时：

推荐方法：使用 Python 脚本（高效且可靠）

仓库包含可自动处理图标集成的 Python 脚本：

1. 创建基础图表结构：

   • 创建具有基本布局（标题、方框、区域）的 .excalidraw 文件
   • 这会建立画布和整体结构

2. 使用 Python 脚本添加图标：

   python skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py \
     <diagram-path> <icon-name> <x> <y> [--label "Text"] [--library-path PATH]
   

   • 默认启用通过 .excalidraw.edit 进行编辑，以避免覆盖问题；传递 --no-use-edit-suffix 可禁用。

   示例：

   # Add EC2 icon at position (400, 300) with label
   python scripts/add-icon-to-diagram.py diagram.excalidraw EC2 400 300 --label "Web Server"
   
   # Add VPC icon at position (200, 150)
   python scripts/add-icon-to-diagram.py diagram.excalidraw VPC 200 150
   
   # Add icon from different library
   python scripts/add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
     --library-path libraries/gcp-icons --label "API Server"
   

3. 添加连接箭头：

   python skills/excalidraw-diagram-generator/scripts/add-arrow.py \
     <diagram-path> <from-x> <from-y> <to-x> <to-y> [--label "Text"] [--style solid|dashed|dotted] [--color HEX]
   

   • 默认启用通过 .excalidraw.edit 进行编辑，以避免覆盖问题；传递 --no-use-edit-suffix 可禁用。

   示例：

   # Simple arrow from (300, 250) to (500, 300)
   python scripts/add-arrow.py diagram.excalidraw 300 250 500 300
   
   # Arrow with label
   python scripts/add-arrow.py diagram.excalidraw 300 250 500 300 --label "HTTPS"
   
   # Dashed arrow with custom color
   python scripts/add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
   

4. 工作流摘要：

   # Step 1: Create base diagram with title and structure
   # (Create .excalidraw file with initial elements)
   
   # Step 2: Add icons with labels
   python scripts/add-icon-to-diagram.py my-diagram.excalidraw "Internet-gateway" 200 150 --label "Internet Gateway"
   python scripts/add-icon-to-diagram.py my-diagram.excalidraw VPC 250 250
   python scripts/add-icon-to-diagram.py my-diagram.excalidraw ELB 350 300 --label "Load Balancer"
   python scripts/add-icon-to-diagram.py my-diagram.excalidraw EC2 450 350 --label "EC2 Instance"
   python scripts/add-icon-to-diagram.py my-diagram.excalidraw RDS 550 400 --label "Database"
   
   # Step 3: Add connecting arrows
   python scripts/add-arrow.py my-diagram.excalidraw 250 200 300 250  # Internet → VPC
   python scripts/add-arrow.py my-diagram.excalidraw 300 300 400 300  # VPC → ELB
   python scripts/add-arrow.py my-diagram.excalidraw 400 330 500 350  # ELB → EC2
   python scripts/add-arrow.py my-diagram.excalidraw 500 380 600 400  # EC2 → RDS
   

Python 脚本方法的优势：

• ✅ 无 token 消耗：图标 JSON 数据（每个 200-1000 行）永远不会进入 AI 上下文
• ✅ 准确的转换：坐标计算以确定性方式处理
• ✅ ID 管理：自动生成 UUID 可防止冲突
• ✅ 可靠：没有坐标误算或 ID 冲突的风险
• ✅ 快速：直接操作文件，无解析开销
• ✅ 可复用：可与您提供的任何 Excalidraw 库配合使用

替代方案：手动图标集成（不推荐）

仅在 Python 脚本不可用时使用此方法：

1. 检查库：

   List directory: skills/excalidraw-diagram-generator/libraries/
   Look for subdirectories containing reference.md files
   

2. 阅读 reference.md：

   Open: libraries/<library-name>/reference.md
   This is lightweight (typically <300 lines) and lists all available icons
   

3. 查找相关图标：

   Search the reference.md table for icon names matching diagram needs
   Example: For AWS diagram with EC2, S3, Lambda → Find "EC2", "S3", "Lambda" in table
   

4. 加载特定图标数据（警告：大文件）：

   Read ONLY the needed icon files:
   - libraries/aws-architecture-icons/icons/EC2.json (200-300 lines)
   - libraries/aws-architecture-icons/icons/S3.json (200-300 lines)
   - libraries/aws-architecture-icons/icons/Lambda.json (200-300 lines)
   Note: Each icon file is 200-1000 lines - this consumes significant tokens
   

5. 提取和转换元素：

   Each icon JSON contains an "elements" array
   Calculate bounding box (min_x, min_y, max_x, max_y)
   Apply offset to all x/y coordinates
   Generate new unique IDs for all elements
   Update groupIds references
   Copy transformed elements into your diagram
   

6. 定位图标并添加连接：

   Adjust x/y coordinates to position icons correctly in the diagram
   Update IDs to ensure uniqueness across diagram
   Add connecting arrows and labels as needed
   

手动集成的挑战：

• ⚠️ 高 token 消耗（每个图标 200-1000 行 × 图标数量）
• ⚠️ 复杂的坐标转换计算
• ⚠️ 如果处理不当，存在 ID 冲突风险
• ⚠️ 对于包含许多图标的图表而言非常耗时

示例：使用图标创建 AWS 架构图

请求："创建一张包含 Internet Gateway、VPC、ELB、EC2 和 RDS 的 AWS 架构图"

推荐工作流（使用 Python 脚本）： 请求："创建一张包含 Internet Gateway、VPC、ELB、EC2 和 RDS 的 AWS 架构图"

推荐工作流（使用 Python 脚本）：

# Step 1: Create base diagram file with title
# Create my-aws-diagram.excalidraw with basic structure (title, etc.)

# Step 2: Check icon availability
# Read: libraries/aws-architecture-icons/reference.md
# Confirm icons exist: Internet-gateway, VPC, ELB, EC2, RDS

# Step 3: Add icons with Python script
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw "Internet-gateway" 150 100 --label "Internet Gateway"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw VPC 200 200
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw ELB 350 250 --label "Load Balancer"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw EC2 500 300 --label "Web Server"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw RDS 650 350 --label "Database"

# Step 4: Add connecting arrows
python scripts/add-arrow.py my-aws-diagram.excalidraw 200 150 250 200  # Internet → VPC
python scripts/add-arrow.py my-aws-diagram.excalidraw 265 230 350 250  # VPC → ELB
python scripts/add-arrow.py my-aws-diagram.excalidraw 415 280 500 300  # ELB → EC2
python scripts/add-arrow.py my-aws-diagram.excalidraw 565 330 650 350 --label "SQL" --style dashed

# Result: Complete diagram with professional AWS icons, labels, and connections

优势：

• 无需手动计算坐标
• 无需为图标数据消耗 token
• 结果确定、可靠
• 易于迭代和调整位置

替代工作流（手动，脚本不可用时）：

1. 检查：libraries/aws-architecture-icons/reference.md 是否存在 → 是
2. 读取 reference.md → 查找 Internet-gateway、VPC、ELB、EC2、RDS 的条目
3. 加载：
   • icons/Internet-gateway.json（298 行）
   • icons/VPC.json（550 行）
   • icons/ELB.json（363 行）
   • icons/EC2.json（231 行）
   • icons/RDS.json（大小相近） 总计：约 2000+ 行 JSON 需要处理
4. 从每个 JSON 中提取元素
5. 计算每个图标的边界框和偏移量
6. 转换所有坐标（x、y）以进行定位
7. 为所有元素生成唯一 ID
8. 添加展示数据流的箭头
9. 添加文本标签
10. 生成最终的 .excalidraw 文件

手动方式的挑战：

• token 消耗高（约 2000-5000 行）
• 坐标计算复杂
• ID 冲突风险

支持的图标库（示例 — 请验证可用性）

• 此工作流适用于你提供的任何有效的 .excalidrawlib 文件。
• 你可能在 https://libraries.excalidraw.com/ 上找到的库类别示例：
  • 云服务图标
  • Kubernetes / 基础设施图标
  • UI / Material 图标
  • 流程图 / 图表符号
  • 网络图图标
• 可用性和命名可能会变化；使用前请先在网站上验证确切的库名称。

回退方案：无可用图标

如果未设置任何图标库：

• 使用基本形状（矩形、椭圆、箭头）创建图表
• 使用颜色编码和文本标签来区分各个组件
• 告知用户之后可以添加图标，或为将来的图表设置图标库
• 图表仍将功能完整、清晰可读，只是视觉上不够精致

参考

请参阅随附的参考文档：

• references/excalidraw-schema.md - 完整的 Excalidraw JSON schema
• references/element-types.md - 详细的元素类型规范
• templates/flowchart-template.excalidraw - 基本流程图模板
• templates/relationship-template.excalidraw - 关系图模板
• templates/mindmap-template.excalidraw - 思维导图模板
• templates/business-flow-swimlane-template.excalidraw - 业务流泳道图模板
• templates/class-diagram-template.excalidraw - 类图模板
• templates/data-flow-diagram-template.excalidraw - 数据流图模板
• templates/er-diagram-template.excalidraw - 实体关系图模板
• templates/sequence-diagram-template.excalidraw - 时序图模板
• scripts/add-icon-to-diagram.py - 将 Excalidraw 库中的图标添加到图表
• scripts/add-arrow.py - 在图表中的元素之间添加箭头（连接）
• scripts/split-excalidraw-library.py - 拆分 .excalidrawlib 文件的工具
• scripts/README.md - 库工具的文档
• scripts/.gitignore - 防止本地 Python 产物被提交

限制

• 复杂曲线会被简化为直线 / 基本曲线
• 手绘粗糙度设置为默认值（1）
• 自动生成不支持嵌入图像
• 建议的最大元素数量：每张图 20 个
• 无自动碰撞检测（请使用间距指南）

未来增强

潜在改进：

• 自动布局优化算法
• 从 Mermaid/PlantUML 语法导入
• 模板库扩展
• 生成后交互式编辑