excalidraw-diagram-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Excalidraw Diagram Generator

Excalidraw图表生成器

A skill for generating Excalidraw-format diagrams from natural language descriptions. This skill helps create visual representations of processes, systems, relationships, and ideas without manual drawing.

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

When to Use This Skill

何时使用此技能

Use this skill when users request:

"Create a diagram showing..."
"Make a flowchart for..."
"Visualize the process of..."
"Draw the system architecture of..."
"Generate a mind map about..."
"Create an Excalidraw file for..."
"Show the relationship between..."
"Diagram the workflow of..."

Supported diagram types:

📊 Flowcharts: Sequential processes, workflows, decision trees
🔗 Relationship Diagrams: Entity relationships, system components, dependencies
🧠 Mind Maps: Concept hierarchies, brainstorming results, topic organization
🏗️ Architecture Diagrams: System design, module interactions, data flow
📈 Data Flow Diagrams (DFD): Data flow visualization, data transformation processes
🏊 Business Flow (Swimlane): Cross-functional workflows, actor-based process flows
📦 Class Diagrams: Object-oriented design, class structures and relationships
🔄 Sequence Diagrams: Object interactions over time, message flows
🗃️ ER Diagrams: Database entity relationships, data models

当用户提出以下请求时使用此技能：

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

支持的图表类型：

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

Prerequisites

前提条件

Clear description of what should be visualized
Identification of key entities, steps, or concepts
Understanding of relationships or flow between elements

清晰的可视化内容描述
明确关键实体、步骤或概念
理解元素之间的关系或流程

Step-by-Step Workflow

分步工作流程

Step 1: Understand the Request

步骤1：理解请求

Analyze the user's description to determine:

Diagram type (flowchart, relationship, mind map, architecture)
Key elements (entities, steps, concepts)
Relationships (flow, connections, hierarchy)
Complexity (number of elements)

分析用户的描述，确定：

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

Step 2: Choose the Appropriate Diagram Type

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

User Intent	Diagram Type	Example Keywords
Process flow, steps, procedures	Flowchart	"workflow", "process", "steps", "procedure"
Connections, dependencies, associations	Relationship Diagram	"relationship", "connections", "dependencies", "structure"
Concept hierarchy, brainstorming	Mind Map	"mind map", "concepts", "ideas", "breakdown"
System design, components	Architecture Diagram	"architecture", "system", "components", "modules"
Data flow, transformation processes	Data Flow Diagram (DFD)	"data flow", "data processing", "data transformation"
Cross-functional processes, actor responsibilities	Business Flow (Swimlane)	"business process", "swimlane", "actors", "responsibilities"
Object-oriented design, class structures	Class Diagram	"class", "inheritance", "OOP", "object model"
Interaction sequences, message flows	Sequence Diagram	"sequence", "interaction", "messages", "timeline"
Database design, entity relationships	ER Diagram	"database", "entity", "relationship", "data model"

用户意图	图表类型	示例关键词
流程、步骤、规程	流程图	"workflow"、"process"、"steps"、"procedure"
连接、依赖、关联	关系图	"relationship"、"connections"、"dependencies"、"structure"
概念层级、头脑风暴	思维导图	"mind map"、"concepts"、"ideas"、"breakdown"
系统设计、组件	架构图	"architecture"、"system"、"components"、"modules"
数据流、转换流程	数据流图(DFD)	"data flow"、"data processing"、"data transformation"
跨职能流程、角色职责	业务泳道图	"business process"、"swimlane"、"actors"、"responsibilities"
面向对象设计、类结构	类图	"class"、"inheritance"、"OOP"、"object model"
交互序列、消息流	时序图	"sequence"、"interaction"、"messages"、"timeline"
数据库设计、实体关系	ER图	"database"、"entity"、"relationship"、"data model"

Step 3: Extract Structured Information

步骤3：提取结构化信息

For Flowcharts:

List of sequential steps
Decision points (if any)
Start and end points

For Relationship Diagrams:

Entities/nodes (name + optional description)
Relationships between entities (from → to, with label)

For Mind Maps:

Central topic
Main branches (3-6 recommended)
Sub-topics for each branch (optional)

For Data Flow Diagrams (DFD):

Data sources and destinations (external entities)
Processes (data transformations)
Data stores (databases, files)
Data flows (arrows showing data movement from left-to-right or from top-left to bottom-right)
Important: Do not represent process order, only data flow

For Business Flow (Swimlane):

Actors/roles (departments, systems, people) - displayed as header columns
Process lanes (vertical lanes under each actor)
Process boxes (activities within each lane)
Flow arrows (connecting process boxes, including cross-lane handoffs)

For Class Diagrams:

Classes with names
Attributes with visibility (+, -, #)
Methods with visibility and parameters
Relationships: inheritance (solid line + white triangle), implementation (dashed line + white triangle), association (solid line), dependency (dashed line), aggregation (solid line + white diamond), composition (solid line + filled diamond)
Multiplicity notations (1, 0..1, 1..*, *)

For Sequence Diagrams:

Objects/actors (arranged horizontally at top)
Lifelines (vertical lines from each object)
Messages (horizontal arrows between lifelines)
Synchronous messages (solid arrow), asynchronous messages (dashed arrow)
Return values (dashed arrows)
Activation boxes (rectangles on lifelines during execution)
Time flows from top to bottom

For ER Diagrams:

Entities (rectangles with entity names)
Attributes (listed inside entities)
Primary keys (underlined or marked with PK)
Foreign keys (marked with FK)
Relationships (lines connecting entities)
Cardinality: 1:1 (one-to-one), 1:N (one-to-many), N:M (many-to-many)
Junction/associative entities for many-to-many relationships (dashed rectangles)

对于流程图：

顺序步骤列表
决策点（如果有）
开始和结束点

对于关系图：

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

对于思维导图：

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

对于数据流图(DFD)：

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

对于业务泳道图：

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

对于类图：

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

对于时序图：

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

对于ER图：

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

Step 4: Generate the Excalidraw JSON

步骤4：生成Excalidraw JSON

Create the

.excalidraw

file with appropriate elements:

Available element types:

```
rectangle
```
: Boxes for entities, steps, concepts
```
ellipse
```
: Alternative shapes for emphasis
```
diamond
```
: Decision points
```
arrow
```
: Directional connections
```
text
```
: Labels and annotations

Key properties to set:

Position:
```
x
```
,
```
y
```
coordinates
Size:
```
width
```
,
```
height
```
Style:
```
strokeColor
```
,
```
backgroundColor
```
,
```
fillStyle
```
Font:
```
fontFamily: 5
```
(Excalifont - required for all text elements)
Text: Embedded text for labels
Connections:
```
points
```
array for arrows

Important: All text elements must use

fontFamily: 5

(Excalifont) for consistent visual appearance.

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

可用元素类型：

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

需要设置的关键属性：

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

重要提示：所有文本元素必须使用

fontFamily: 5

（Excalifont）以确保视觉一致性。

Step 5: Format the Output

步骤5：格式化输出

Structure the complete Excalidraw file:

json

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

构建完整的Excalidraw文件结构：

json

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    // 图表元素数组
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

Step 6: Save and Provide Instructions

步骤6：保存并提供说明

Save as
```
<descriptive-name>.excalidraw
```
Inform user how to open:
- Visit https://excalidraw.com
- Click "Open" or drag-and-drop the file
- Or use Excalidraw VS Code extension

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

Best Practices

最佳实践

Element Count Guidelines

元素数量指南

Diagram Type	Recommended Count	Maximum
Flowchart steps	3-10	15
Relationship entities	3-8	12
Mind map branches	4-6	8
Mind map sub-topics per branch	2-4	6

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

Layout Tips

布局技巧

Start positions: Center important elements, use consistent spacing
Spacing:
- Horizontal gap: 200-300px between elements
- Vertical gap: 100-150px between rows
Colors: Use consistent color scheme
- Primary elements: Light blue (
```
#a5d8ff
```
  )
- Secondary elements: Light green (
```
#b2f2bb
```
  )
- Important/Central: Yellow (
```
#ffd43b
```
  )
- Alerts/Warnings: Light red (
```
#ffc9c9
```
  )
Text sizing: 16-24px for readability
Font: Always use
```
fontFamily: 5
```
(Excalifont) for all text elements
Arrow style: Use straight arrows for simple flows, curved for complex relationships

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

Complexity Management

复杂度管理

If user request has too many elements:

Suggest breaking into multiple diagrams
Focus on main elements first
Offer to create detailed sub-diagrams

Example response:

"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?"

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

建议拆分为多个图表
先聚焦于主要元素
提供创建详细子图表的选项

示例回复：

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

您是否希望我先创建高层级视图？

Example Prompts and Responses

示例提示与回复

Example 1: Simple Flowchart

示例1：简单流程图

User: "Create a flowchart for user registration"

Agent generates:

Extract steps: "Enter email" → "Verify email" → "Set password" → "Complete"
Create flowchart with 4 rectangles + 3 arrows
Save as
```
user-registration-flow.excalidraw
```

用户： "创建用户注册流程图"

Agent生成：

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

Example 2: Relationship Diagram

示例2：关系图

User: "Diagram the relationship between User, Post, and Comment entities"

Agent generates:

Entities: User, Post, Comment
Relationships: User → Post ("creates"), User → Comment ("writes"), Post → Comment ("contains")
Save as
```
user-content-relationships.excalidraw
```

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

Agent生成：

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

Example 3: Mind Map

示例3：思维导图

User: "Mind map about machine learning concepts"

Agent generates:

Center: "Machine Learning"
Branches: Supervised Learning, Unsupervised Learning, Reinforcement Learning, Deep Learning
Sub-topics under each branch
Save as
```
machine-learning-mindmap.excalidraw
```

用户： "生成关于机器学习概念的思维导图"

Agent生成：

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

Troubleshooting

故障排除

Issue	Solution
Elements overlap	Increase spacing between coordinates
Text doesn't fit in boxes	Increase box width or reduce font size
Too many elements	Break into multiple diagrams
Unclear layout	Use grid layout (rows/columns) or radial layout (mind maps)
Colors inconsistent	Define color palette upfront based on element types

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

Advanced Techniques

高级技巧

Grid Layout (for Relationship Diagrams)

网格布局（适用于关系图）

javascript

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

javascript

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

Radial Layout (for Mind Maps)

放射状布局（适用于思维导图）

javascript

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

javascript

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

Auto-generated IDs

自动生成ID

Use timestamp + random string for unique IDs:

javascript

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

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

javascript

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

Output Format

输出格式

Always provide:

✅ Complete
```
.excalidraw
```
JSON file
📊 Summary of what was created
📝 Element count
💡 Instructions for opening/editing

Example summary:

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

始终提供：

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

示例摘要：

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

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

Validation Checklist

验证清单

Before delivering the diagram:

All elements have unique IDs
Coordinates prevent overlapping
Text is readable (font size 16+)
All text elements use
fontFamily: 5
(Excalifont)
Arrows connect logically
Colors follow consistent scheme
File is valid JSON
Element count is reasonable (<20 for clarity)

交付图表前：

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

Icon Libraries (Optional Enhancement)

图标库（可选增强）

For specialized diagrams (e.g., AWS/GCP/Azure architecture diagrams), you can use pre-made icon libraries from Excalidraw. This provides professional, standardized icons instead of basic shapes.

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

When User Requests Icons

当用户请求图标时

If user asks for AWS/cloud architecture diagrams or mentions wanting to use specific icons:

Check if library exists: Look for
```
libraries/<library-name>/reference.md
```
If library exists: Proceed to use icons (see AI Assistant Workflow below)

If library does NOT exist: Respond with setup instructions:

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.

如果用户要求创建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中手动替换为图标。

User Setup Instructions (Detailed)

用户设置说明（详细版）

Step 1: Create Library Directory

bash

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

Step 2: Download Library

Visit: https://libraries.excalidraw.com/
Search for your desired icon set (e.g., "AWS Architecture Icons")
Click download to get the
```
.excalidrawlib
```
file
Example categories (availability varies; confirm on the site):
- Cloud service icons
- UI/Material icons
- Flowchart symbols

Step 3: Place Library File

Rename the downloaded file to match the directory name (e.g.,
```
aws-architecture-icons.excalidrawlib
```
)
Move it to the directory created in Step 1

Step 4: Run Splitter Script

bash

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

Step 5: Verify Setup After running the script, verify the following structure exists:

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

步骤1：创建库目录

bash

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

步骤2：下载库

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

步骤3：放置库文件

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

步骤4：运行拆分脚本

bash

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 Assistant Workflow

AI助手工作流

When icon libraries are available in
libraries/
:

RECOMMENDED APPROACH: Use Python Scripts (Efficient & Reliable)

The repository includes Python scripts that handle icon integration automatically:

Create base diagram structure:
- Create
```
.excalidraw
```
  file with basic layout (title, boxes, regions)
- This establishes the canvas and overall structure

Add icons using Python script:

bash

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

Edit via
```
.excalidraw.edit
```
is enabled by default to avoid overwrite issues; pass
```
--no-use-edit-suffix
```
to disable.

Examples:

bash

# 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"

Add connecting arrows:

bash

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]

Edit via
```
.excalidraw.edit
```
is enabled by default to avoid overwrite issues; pass
```
--no-use-edit-suffix
```
to disable.

Examples:

bash

# 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"

Workflow summary:

bash

# 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

Benefits of Python Script Approach:

✅ No token consumption: Icon JSON data (200-1000 lines each) never enters AI context
✅ Accurate transformations: Coordinate calculations handled deterministically
✅ ID management: Automatic UUID generation prevents conflicts
✅ Reliable: No risk of coordinate miscalculation or ID collision
✅ Fast: Direct file manipulation, no parsing overhead
✅ Reusable: Works with any Excalidraw library you provide

ALTERNATIVE: Manual Icon Integration (Not Recommended)

Only use this if Python scripts are unavailable:

Check for libraries:

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

Read reference.md:

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

Find relevant icons:

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

Load specific icon data (WARNING: Large files):

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

Extract and transform elements:

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

Position icons and add connections:

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

Manual Integration Challenges:

⚠️ High token consumption (200-1000 lines per icon × number of icons)
⚠️ Complex coordinate transformation calculations
⚠️ Risk of ID collision if not handled carefully
⚠️ Time-consuming for diagrams with many icons

当
libraries/
目录中存在图标库时：

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

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

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

使用Python脚本添加图标：

bash

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

默认启用通过
```
.excalidraw.edit
```
编辑以避免覆盖问题；传递
```
--no-use-edit-suffix
```
可禁用此功能。

示例：

bash

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

# 在位置(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 Server"

添加连接箭头：

bash

python skills/excalidraw-diagram-generator/scripts/add-arrow.py \
  <图表路径> <起始x> <起始y> <目标x> <目标y> [--label "文本"] [--style solid|dashed|dotted] [--color 十六进制颜色]

默认启用通过
```
.excalidraw.edit
```
编辑以避免覆盖问题；传递
```
--no-use-edit-suffix
```
可禁用此功能。

示例：

bash

# 从(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"

工作流摘要：

bash

# 步骤1：创建包含标题和结构的基础图表
# (创建包含初始元素的.excalidraw文件)

# 步骤2：添加带标签的图标
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"

# 步骤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包含一个“elements”数组
计算边界框（min_x、min_y、max_x、max_y）
对所有x/y坐标应用偏移
为所有元素生成新的唯一ID
更新groupId引用
将转换后的元素复制到您的图表中

定位图标并添加连接：

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

手动集成的挑战：

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

Example: Creating AWS Diagram with Icons

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

Request: "Create an AWS architecture diagram with Internet Gateway, VPC, ELB, EC2, and RDS"

Recommended Workflow (using Python scripts): Request: "Create an AWS architecture diagram with Internet Gateway, VPC, ELB, EC2, and RDS"

Recommended Workflow (using Python scripts):

bash

undefined

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

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

bash

undefined

Step 1: Create base diagram file with title

步骤1：创建包含标题的基础图表文件

Create my-aws-diagram.excalidraw with basic structure (title, etc.)

创建my-aws-diagram.excalidraw并添加基础结构（标题等）

Step 2: Check icon availability

步骤2：检查图标可用性

Read: libraries/aws-architecture-icons/reference.md

读取：libraries/aws-architecture-icons/reference.md

Confirm icons exist: Internet-gateway, VPC, ELB, EC2, RDS

确认图标存在：Internet-gateway、VPC、ELB、EC2、RDS

Step 3: Add icons with Python script

步骤3：使用Python脚本添加图标

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

步骤4：添加连接箭头

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

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

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

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


**Benefits**:
- No manual coordinate calculation
- No token consumption for icon data
- Deterministic, reliable results
- Easy to iterate and adjust positions

**Alternative Workflow (manual, if scripts unavailable)**:
1. Check: `libraries/aws-architecture-icons/reference.md` exists → Yes
2. Read reference.md → Find entries for Internet-gateway, VPC, ELB, EC2, RDS
3. Load:
   - `icons/Internet-gateway.json` (298 lines)
   - `icons/VPC.json` (550 lines)
   - `icons/ELB.json` (363 lines)
   - `icons/EC2.json` (231 lines) 
   - `icons/RDS.json` (similar size)
   **Total: ~2000+ lines of JSON to process**
4. Extract elements from each JSON
5. Calculate bounding boxes and offsets for each icon
6. Transform all coordinates (x, y) for positioning
7. Generate unique IDs for all elements
8. Add arrows showing data flow
9. Add text labels
10. Generate final `.excalidraw` file

**Challenges with manual approach**:
- High token consumption (~2000-5000 lines)
- Complex coordinate math
- Risk of ID conflicts


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

**替代工作流（手动，若脚本不可用）**：
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文件

**手动方法的挑战**：
- 高令牌消耗（约2000-5000行）
- 复杂的坐标计算
- ID冲突风险

Supported Icon Libraries (Examples — verify availability)

支持的图标库（示例——请确认可用性）

This workflow works with any valid
```
.excalidrawlib
```
file you provide.
Examples of library categories you may find on https://libraries.excalidraw.com/:
- Cloud service icons
- Kubernetes / infrastructure icons
- UI / Material icons
- Flowchart / diagram symbols
- Network diagram icons
Availability and naming can change; verify exact library names on the site before use.

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

Fallback: No Icons Available

回退方案：无可用图标

If no icon libraries are set up:

Create diagrams using basic shapes (rectangles, ellipses, arrows)
Use color coding and text labels to distinguish components
Inform user they can add icons later or set up libraries for future diagrams
The diagram will still be functional and clear, just less visually polished

如果未设置图标库：

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

References

参考资料

See bundled references for:

```
references/excalidraw-schema.md
```
- Complete Excalidraw JSON schema
```
references/element-types.md
```
- Detailed element type specifications
```
templates/flowchart-template.json
```
- Basic flowchart starter
```
templates/relationship-template.json
```
- Relationship diagram starter
```
templates/mindmap-template.json
```
- Mind map starter

scripts/split-excalidraw-library.py

- Tool to split

.excalidrawlib

files

```
scripts/README.md
```
- Documentation for library tools
```
scripts/.gitignore
```
- Prevents local Python artifacts from being committed

查看捆绑的参考资料：

```
references/excalidraw-schema.md
```
- 完整的Excalidraw JSON schema
```
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工件被提交

Limitations

限制

Complex curves are simplified to straight/basic curved lines
Hand-drawn roughness is set to default (1)
No embedded images support in auto-generation
Maximum recommended elements: 20 per diagram
No automatic collision detection (use spacing guidelines)

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

Future Enhancements

未来增强

Potential improvements:

Auto-layout optimization algorithms
Import from Mermaid/PlantUML syntax
Template library expansion
Interactive editing after generation

潜在的改进方向：

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