名称: excalidraw-diagram-generator 描述: ‘从自然语言描述生成 Excalidraw 图表。当被要求“创建图表”、“制作流程图”、“可视化过程”、“绘制系统架构”、“创建思维导图”或“生成 Excalidraw 文件”时使用。支持流程图、关系图、思维导图和系统架构图。输出可以直接在 Excalidraw 中打开的 .excalidraw JSON 文件。’

Excalidraw 图表生成器

一个从自然语言描述生成 Excalidraw 格式图表的技能。此技能帮助创建过程、系统、关系和想法的视觉表示，无需手动绘制。

何时使用此技能

当用户请求时使用此技能：

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

支持的图表类型：

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

先决条件

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

分步工作流程

步骤 1：理解请求

分析用户描述以确定：

图表类型（流程图、关系图、思维导图、架构图）
关键元素（实体、步骤、概念）
关系（流、连接、层次）
复杂性（元素数量）

步骤 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": [
    // 图表元素数组
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

步骤 6：保存并提供指令

保存为 <描述性名称>.excalidraw
告知用户如何打开：
- 访问 https://excalidraw.com
- 点击“打开”或拖放文件
- 或使用 Excalidraw VS Code 扩展

最佳实践

元素数量指南

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

布局提示

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

复杂性管理

如果用户请求有太多元素：

建议分解为多个图表
首先关注主要元素
提供创建详细子图表

示例响应：

“您的请求包括 15 个组件。为清晰起见，我建议：
1. 高级架构图（6 个主要组件）
2. 每个子系统的详细图表

您希望我从高级视图开始吗？”

示例提示和响应

示例 1：简单流程图

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

代理生成：

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

示例 2：关系图

用户： “绘制用户、帖子和评论实体之间的关系图”

代理生成：

实体：用户、帖子、评论
关系：用户 → 帖子（“创建”）、用户 → 评论（“写入”）、帖子 → 评论（“包含”）
保存为 user-content-relationships.excalidraw

示例 3：思维导图

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

代理生成：

中心：“机器学习”
分支：监督学习、无监督学习、强化学习、深度学习
每个分支下的子主题
保存为 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);

输出格式

始终提供：

✅ 完整的 .excalidraw JSON 文件
📊 创建内容的摘要
📝 元素数量
💡 打开/编辑的指令

示例摘要：

创建：user-workflow.excalidraw
类型：流程图
元素：7 个矩形、6 个箭头、1 个标题文本
总计：14 个元素

查看方法：
1. 访问 https://excalidraw.com
2. 拖放 user-workflow.excalidraw
3. 或在 Excalidraw VS Code 扩展中使用文件 → 打开

验证清单

在交付图表前：

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

图标库（可选增强）

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

当用户请求图标时

如果用户要求 AWS/云架构图或提及想使用特定图标：

检查库是否存在：查找 libraries/<库名称>/reference.md
如果库存在：继续使用图标（参见 AI 助手工作流程）

如果库不存在：响应设置指令：

要使用 [AWS/GCP/Azure 等] 架构图标，请遵循以下步骤：

1. 访问 https://libraries.excalidraw.com/
2. 搜索“[AWS 架构图标/等]”并下载 .excalidrawlib 文件
3. 创建目录：skills/excalidraw-diagram-generator/libraries/[图标集名称]/
4. 将下载的文件放入该目录
5. 运行拆分脚本：
   python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/[图标集名称]/

这将把库拆分为单个图标文件以便高效使用。
设置完成后，我可以使用实际的 AWS/云图标创建您的图表。

或者，我现在可以使用简单形状（矩形、椭圆）创建图表，
您以后可以在 Excalidraw 中手动替换为图标。

用户设置指令（详细）

步骤 1：创建库目录

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

步骤 2：下载库

访问：https://libraries.excalidraw.com/
搜索所需的图标集（例如“AWS 架构图标”）
点击下载获取 .excalidrawlib 文件
示例类别（可用性可能变化；请在网站上确认）：
- 云服务图标
- UI/材料图标
- 流程图符号

步骤 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  (原始)
  reference.md                          (生成 - 图标查找表)
  icons/                                (生成 - 单个图标文件)
    API-Gateway.json
    CloudFront.json
    EC2.json
    Lambda.json
    RDS.json
    S3.json
    ...

AI 助手工作流程

当图标库在 libraries/ 中可用时：

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

存储库包括自动处理图标集成的 Python 脚本：

创建基础图表结构：
- 创建带基本布局（标题、框、区域）的 .excalidraw 文件
- 这建立画布和整体结构

使用 Python 脚本添加图标：

python skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py \
  <图表路径> <图标名称> <x> <y> [--label "文本"] [--library-path 路径]

默认启用 .excalidraw.edit 编辑以避免覆盖问题；传递 --no-use-edit-suffix 以禁用。

示例：

# 在位置 (400, 300) 添加 EC2 图标，带标签
python scripts/add-icon-to-diagram.py diagram.excalidraw EC2 400 300 --label "Web 服务器"

# 在位置 (200, 150) 添加 VPC 图标
python scripts/add-icon-to-diagram.py diagram.excalidraw VPC 200 150

# 从不同库添加图标
python scripts/add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
  --library-path libraries/gcp-icons --label "API 服务器"

添加连接箭头：

python skills/excalidraw-diagram-generator/scripts/add-arrow.py \
  <图表路径> <从-x> <从-y> <到-x> <到-y> [--label "文本"] [--style solid|dashed|dotted] [--color HEX]

默认启用 .excalidraw.edit 编辑以避免覆盖问题；传递 --no-use-edit-suffix 以禁用。

示例：

# 从 (300, 250) 到 (500, 300) 的简单箭头
python scripts/add-arrow.py diagram.excalidraw 300 250 500 300

# 带标签的箭头
python scripts/add-arrow.py diagram.excalidraw 300 250 500 300 --label "HTTPS"

# 带自定义颜色的虚线箭头
python scripts/add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"

工作流程摘要：

# 步骤 1：创建带标题和结构的基础图表
# （创建带初始元素的 .excalidraw 文件）

# 步骤 2：添加带标签的图标
python scripts/add-icon-to-diagram.py my-diagram.excalidraw "Internet-gateway" 200 150 --label "互联网网关"
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 "负载均衡器"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw EC2 450 350 --label "EC2 实例"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw RDS 550 400 --label "数据库"

# 步骤 3：添加连接箭头
python scripts/add-arrow.py my-diagram.excalidraw 250 200 300 250  # 互联网 → 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 脚本方法的优点：

✅ 无令牌消耗：图标 JSON 数据（每图标 200-1000 行）从不进入 AI 上下文
✅ 准确转换：坐标计算确定性处理
✅ ID 管理：自动 UUID 生成防止冲突
✅ 可靠：无坐标误算或 ID 碰撞风险
✅ 快速：直接文件操作，无解析开销
✅ 可重用：适用于任何提供的 Excalidraw 库

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

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

检查库：

列出目录：skills/excalidraw-diagram-generator/libraries/
查找包含 reference.md 文件的子目录

读取 reference.md：

打开：libraries/<库名称>/reference.md
这通常是轻量的（典型 <300 行）并列出所有可用图标

查找相关图标：

搜索 reference.md 表以匹配图表需求的图标名称
示例：对于带 EC2、S3、Lambda 的 AWS 图表 → 在表中查找“EC2”、“S3”、“Lambda”

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

仅读取所需的图标文件：
- libraries/aws-architecture-icons/icons/EC2.json (200-300 行)
- libraries/aws-architecture-icons/icons/S3.json (200-300 行)
- libraries/aws-architecture-icons/icons/Lambda.json (200-300 行)
注意：每个图标文件 200-1000 行 - 这会消耗大量令牌

提取和转换元素：

每个图标 JSON 包含一个“元素”数组
计算边界框 (min_x, min_y, max_x, max_y)
对所有 x/y 坐标应用偏移
为所有元素生成新的唯一 ID
更新 groupIds 引用
将转换后的元素复制到图表中

定位图标并添加连接：

调整 x/y 坐标以正确在图表中定位图标
更新 ID 以确保图表中唯一性
根据需要添加连接箭头和标签

手动集成挑战：

⚠️ 高令牌消耗（每图标 200-1000 行 × 图标数量）
⚠️ 复杂坐标转换计算
⚠️ 如果处理不当，ID 冲突风险
⚠️ 对于多图标图表耗时

示例：使用图标创建 AWS 图表

请求： “创建一个带互联网网关、VPC、ELB、EC2 和 RDS 的 AWS 架构图”

推荐工作流程（使用 Python 脚本）：请求： “创建一个带互联网网关、VPC、ELB、EC2 和 RDS 的 AWS 架构图”

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

# 步骤 1：创建带标题的基础图表文件
# 创建 my-aws-diagram.excalidraw 带基本结构（标题等）

# 步骤 2：检查图标可用性
# 读取：libraries/aws-architecture-icons/reference.md
# 确认图标存在：Internet-gateway, VPC, ELB, EC2, RDS

# 步骤 3：使用 Python 脚本添加图标
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw "Internet-gateway" 150 100 --label "互联网网关"
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 "负载均衡器"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw EC2 500 300 --label "Web 服务器"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw RDS 650 350 --label "数据库"

# 步骤 4：添加连接箭头
python scripts/add-arrow.py my-aws-diagram.excalidraw 200 150 250 200  # 互联网 → 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

# 结果：带专业 AWS 图标、标签和连接的完整图表

优点：

无手动坐标计算
无图标数据的令牌消耗
确定性、可靠结果
易于迭代和调整位置

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

检查：libraries/aws-architecture-icons/reference.md 存在 → 是
读取 reference.md → 查找 Internet-gateway, VPC, ELB, EC2, RDS 的条目
加载：
- icons/Internet-gateway.json (298 行)
- icons/VPC.json (550 行)
- icons/ELB.json (363 行)
- icons/EC2.json (231 行)
- icons/RDS.json (类似大小) 总计：处理约 2000+ 行 JSON
从每个 JSON 提取元素
为每个图标计算边界框和偏移
转换所有坐标 (x, y) 以定位
为所有元素生成唯一 ID
添加显示数据流的箭头
添加文本标签
生成最终的 .excalidraw 文件

手动方法的挑战：

高令牌消耗（约 2000-5000 行）
复杂坐标数学
ID 冲突风险

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

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

回退：无图标可用

如果未设置图标库：

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

参考

请参阅捆绑的参考：

references/excalidraw-schema.md - 完整的 Excalidraw JSON 模式
references/element-types.md - 详细元素类型规格
templates/flowchart-template.json - 基本流程图起始
templates/relationship-template.json - 关系图起始
templates/mindmap-template.json - 思维导图起始
scripts/split-excalidraw-library.py - 拆分 .excalidrawlib 文件的工具
scripts/README.md - 库工具文档
scripts/.gitignore - 防止本地 Python 工件被提交

限制

复杂曲线简化为直线/基本曲线
手绘粗糙度设置为默认 (1)
自动生成不支持嵌入图像
最大推荐元素：每个图表 20
无自动碰撞检测（使用间距指南）

未来增强

潜在改进：

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