excalidraw-studio

Excalidraw Studio

根据自然语言描述生成 Excalidraw 格式的图表。输出 .excalidraw JSON 文件，可直接在 Excalidraw（网页、VS Code 扩展或 Obsidian 插件）中打开。

工作流

UNDERSTAND → CHOOSE TYPE → EXTRACT → GENERATE → SAVE

第 1 步：理解请求

分析用户的描述，确定：

1. 图表类型 — 使用下方的决策矩阵
2. 关键元素 — 实体、步骤、概念、参与者
3. 关系 — 流向、连接、层级
4. 复杂度 — 元素数量（目标：少于 20 个，以保持清晰）

第 2 步：选择图表类型和视觉模式

图表类型：

用户意图	图表类型	关键词
流程、步骤	流程图	"workflow", "process", "steps"
连接、依赖关系	关系图	"relationship", "connections", "dependencies"
概念层级	思维导图	"mind map", "concepts", "breakdown"
系统设计	架构图	"architecture", "system", "components"
数据移动	数据流图（DFD）	"data flow", "data processing"
跨职能流程	泳道图	"business process", "swimlane", "actors"
面向对象设计	类图	"class", "inheritance", "OOP"
交互序列	时序图	"sequence", "interaction", "messages"
数据库设计	ER 图	"database", "entity", "data model"

视觉模式 — 提前决定，并在所有元素中保持一致：

模式	roughness	fontFamily	适用场景
草图	1	5	默认 — 非正式、易于理解、原生 Excalidraw 风格
简洁	0	2	高管演示、正式规格说明
混合	zones: 0, shapes: 1	5	架构图（结构区域 + 草图风格的形状）

第 3 步：提取结构化信息

根据图表类型提取关键组成部分。对于每种类型，请确定：

• 节点/实体 — 方框或形状分别是什么？
• 连接 — 哪些内容相互连接？连接标签是什么？
• 层级 — 哪些内容包含哪些内容？顺序如何？
• 决策点 — 流程从哪里分支？

有关各图表类型的详细提取指南，请阅读 references/element-types.md。

第 4 步：生成 Excalidraw JSON

**重要：生成第一个图表前，请先阅读 references/excalidraw-schema.md。**其中包含正确的元素格式、文本容器模型和绑定系统。

生成规则：

1. 形状内的文本——在形状上使用 boundElements，并单独创建一个带有 containerId 的文本元素。切勿使用 label 简写：

   [
     {
       "id": "step-1",
       "type": "rectangle",
       "x": 100, "y": 100, "width": 200, "height": 80,
       "boundElements": [{ "type": "text", "id": "text-step-1" }]
     },
     {
       "id": "text-step-1",
       "type": "text",
       "x": 130, "y": 128, "width": 140, "height": 24,
       "text": "My Step", "originalText": "My Step",
       "fontSize": 20, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "step-1", "lineHeight": 1.25, "roundness": null
     }
   ]
   

2. 箭头标签——同样使用 boundElements 和带有 containerId 的独立文本元素。切勿在箭头上使用 label 简写：

   [
     {
       "id": "arrow-1",
       "type": "arrow",
       "x": 100, "y": 150,
       "points": [[0, 0], [200, 0]],
       "boundElements": [{ "type": "text", "id": "text-arrow-1" }]
     },
     {
       "id": "text-arrow-1",
       "type": "text",
       "x": 160, "y": 132, "width": 80, "height": 18,
       "text": "sends data", "originalText": "sends data",
       "fontSize": 14, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "arrow-1", "lineHeight": 1.25, "roundness": null
     }
   ]
   

3. 箭头绑定——使用 startBinding/endBinding（而非 start/end）。相连的形状必须在其 boundElements 中列出箭头：

   {
     "id": "shape-1",
     "boundElements": [
       { "type": "text", "id": "text-shape-1" },
       { "type": "arrow", "id": "arrow-1" }
     ]
   }
   

   {
     "id": "arrow-1",
     "type": "arrow",
     "startBinding": { "elementId": "shape-1", "focus": 0, "gap": 1 },
     "endBinding": { "elementId": "shape-2", "focus": 0, "gap": 1 }
   }
   

4. 元素顺序（z-index）——始终先声明形状，再声明箭头，最后声明文本元素。这样可以确保文本显示在最上层，不会被箭头或其他形状遮挡。

5. 定位——使用与网格对齐的坐标（当 gridSize: 20 时，坐标应为 20 px 的倍数）。元素之间留出 200-300 px 的水平间距和 100-150 px 的垂直间距。

6. 唯一 ID——每个元素都必须有唯一的 id。使用描述性 ID，例如 "step-1"、"decision-valid"、"arrow-1-to-2"、"text-step-1"。

7. 颜色——使用一致的配色方案：

   角色	颜色	十六进制
   主要实体	浅蓝色	#a5d8ff
   流程步骤	浅绿色	#b2f2bb
   重要/中心	黄色	#ffd43b
   警告/错误	浅红色	#ffc9c9
   次要	青色	#96f2d7
   默认描边	深色	#1e1e1e

第 5 步：保存并展示

1. 保存为 <descriptive-name>.excalidraw

2. 提供摘要：

   Created: user-workflow.excalidraw
   Type: Flowchart
   Elements: 7 shapes, 6 arrows, 1 title
   Total: 14 elements
   
   To view:
   1. Visit https://excalidraw.com → Open → drag and drop the file
   2. Or use the Excalidraw VS Code extension
   3. Or open in Obsidian with the Excalidraw plugin
   

模板

assets/ 中提供了预构建模板，可快速开始。图表类型匹配时请使用这些模板——它们提供了正确的结构和样式：

模板	文件
流程图	assets/flowchart-template.json
关系图	assets/relationship-template.json
思维导图	assets/mindmap-template.json
数据流图（DFD）	assets/data-flow-diagram-template.json
泳道图	assets/business-flow-swimlane-template.json
类图	assets/class-diagram-template.json
时序图	assets/sequence-diagram-template.json
ER 图	assets/er-diagram-template.json

首次创建某种图表时，请阅读对应模板。以其结构为基础，再根据用户请求修改元素。

图标库

对于带有服务图标（AWS、GCP、Azure 等）的专业架构图，可以配置图标库。遇到以下情况时，请阅读 references/icon-libraries.md：

• 用户请求绘制 AWS/云架构图
• 用户提到希望使用特定服务图标
• 需要检查图标库是否可用

最佳实践

元素数量

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

如果用户的请求超过最大数量，建议拆分为多个图表：

"你的请求包含 15 个组件。为保持清晰，我建议：（1）绘制包含 6 个主要组件的高层架构图；（2）为每个子系统绘制详细的子图。要我先从高层视图开始吗？"

布局

• 流程方向：流程从左到右，层级从上到下
• 间距：元素之间的水平间距为 200-300px，垂直间距为 100-150px
• 网格对齐：坐标使用 20px 的倍数，确保整齐对齐
• 边距：距画布边缘至少 50px
• 文本大小：标题为 28-36px，标签为 18-22px，注释为 14-16px
• 字体：使用 fontFamily: 5（Excalifont）以保持手绘风格一致。如果不支持 5，则回退到 1（Virgil）。
• 背景区域：对于架构图，将半透明虚线区域矩形（opacity: 35、strokeStyle: "dashed"、roughness: 0）作为数组中的首批元素添加，以创建视觉分组区域。请参阅 references/excalidraw-schema.md → 背景区域。
• 元素顺序：区域 → 形状 → 箭头 → 文本元素（确保 z-index 正确，且文本始终显示在最上层）

应避免的常见错误

• ❌ 在形状或箭头上使用 label: { text: "..." } 简写形式——Excalidraw 解析器不支持
• ❌ 在形状元素上直接放置 text，却不设置 containerId
• ❌ 使用 start/end 绑定箭头——请改用包含 elementId/focus/gap 的 startBinding/endBinding
• ❌ 忘记将箭头添加到其连接形状的 boundElements 数组中
• ❌ 在容器内的文本元素中遗漏 originalText、lineHeight、autoResize 或 backgroundColor: "transparent"
• ❌ 遗漏必需的基础属性（angle、strokeStyle、opacity、groupIds、frameId、index、isDeleted、seed、version、versionNonce、updated、link、locked）——元素将无法渲染
• ❌ 在 JSON 顶层遗漏 "files": {}
• ❌ 在椭圆上使用 roundness: { "type": 3 }——椭圆必须使用 roundness: null
• ❌ 在箭头上遗漏 lastCommittedPoint、startArrowhead、endArrowhead
• ❌ 在箭头之前声明文本元素——文本会渲染在下方并被遮挡
• ❌ 使用没有绑定的悬空箭头（不会随形状移动）
• ❌ 元素重叠（请增加间距）
• ❌ 颜色使用不一致（请预先定义调色板）
• ❌ 单张图中元素过多（请拆分为子图）

验证清单

交付图表之前，请确认：

• 所有元素都有唯一 ID
• 每个元素都包含所有必需的基础属性：angle、strokeStyle、opacity、groupIds、frameId、index、isDeleted、link、locked、seed、version、versionNonce、updated
• index 值按顺序分配（"a0"、"a1"……），且文本元素的值高于形状/箭头
• JSON 顶层包含 "files": {}
• 带文本的形状使用 boundElements，并搭配单独的文本元素及其 containerId
• 容器内的文本元素包含 containerId、originalText、lineHeight: 1.25、autoResize: true、roundness: null、backgroundColor: "transparent"
• 连接形状时，箭头使用 startBinding/endBinding（包含 elementId、focus、gap），并设置 lastCommittedPoint: null、startArrowhead: null、endArrowhead: "arrow"
• 连接的形状在其 boundElements 数组中列出了箭头
• 元素顺序为：形状 → 箭头 → 文本元素（文本始终显示在最上层）
• 椭圆使用 roundness: null（而非 { "type": 3 }）
• 坐标设置避免重叠（检查间距）
• 文本清晰可读（字号为 16+）
• 颜色遵循一致的方案
• 文件是有效的 JSON
• 元素数量合理（少于 20 个，以确保清晰）

故障排除

问题	解决方案
形状中未显示文本	使用 boundElements 和单独的文本元素，并设置 containerId、originalText、lineHeight
文本被箭头遮挡	将文本元素移至 elements 数组末尾（所有箭头之后）
箭头不会随形状移动	使用带有 elementId、focus: 0、gap: 1 的 startBinding/endBinding
形状不会随箭头移动	将箭头添加到形状的 boundElements 数组中
元素重叠	增大坐标之间的间距
文本无法完整显示	增大形状宽度或减小字号
元素过多	拆分为多个图表
颜色看起来不一致	预先定义调色板，并保持一致地应用

限制

• 复杂曲线会简化为直线或基本曲线
• 手绘粗糙度设为默认值（1）
• 自动生成时不支持嵌入图像（服务图标请使用图标库）
• 为确保清晰度，每个图表建议最多包含 20 个元素
• 不会自动检测碰撞 — 请遵循间距指南