excalidraw-ai

excalidraw-ai

直接编写 JSON，生成 Excalidraw 图表。无需模板——你可以完全控制每个元素。

何时使用此技能

在以下情况下使用此技能：

• 创建架构图、流程图或思维导图
• 可视化系统设计、数据流或流程
• 根据代码分析或文档生成图表
• 创建可精确控制布局和样式的自定义图表

Excalidraw JSON 架构

Excalidraw 文件是一个具有以下结构的 JSON 对象：

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [ /* array of element objects */ ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

元素类型

矩形

{
  "id": "unique-id-1",
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 100,
  "strokeColor": "#1971c2",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "angle": 0,
  "seed": 12345,
  "isDeleted": false
}

椭圆

{
  "id": "unique-id-2",
  "type": "ellipse",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 100,
  "strokeColor": "#7c3aed",
  "backgroundColor": "#ede9fe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 1
}

菱形

{
  "id": "unique-id-3",
  "type": "diamond",
  "x": 100,
  "y": 100,
  "width": 120,
  "height": 120,
  "strokeColor": "#dc2626",
  "backgroundColor": "#fee2e2",
  "fillStyle": "solid"
}

文本

{
  "id": "unique-id-4",
  "type": "text",
  "x": 110,
  "y": 140,
  "width": 180,
  "height": 25,
  "text": "Your Label Here",
  "fontSize": 20,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle",
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent"
}

箭头

{
  "id": "unique-id-5",
  "type": "arrow",
  "x": 300,
  "y": 150,
  "width": 100,
  "height": 50,
  "strokeColor": "#1971c2",
  "strokeWidth": 2,
  "points": [[0, 0], [100, 50]],
  "startBinding": {
    "elementId": "source-element-id",
    "focus": 0.5,
    "gap": 5
  },
  "endBinding": {
    "elementId": "target-element-id",
    "focus": 0.5,
    "gap": 5
  },
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

直线

{
  "id": "unique-id-6",
  "type": "line",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 0,
  "strokeColor": "#868e96",
  "strokeWidth": 1,
  "points": [[0, 0], [200, 0]],
  "startArrowhead": null,
  "endArrowhead": null
}

元素属性参考

属性	类型	描述
id	字符串	唯一标识符（使用 UUID 或类似值）
type	字符串	rectangle、ellipse、diamond、text、arrow、line
x、y	数字	位置坐标
width、height	数字	尺寸
strokeColor	字符串	边框／描边颜色（十六进制）
backgroundColor	字符串	填充颜色（十六进制）或 "transparent"
fillStyle	字符串	"solid"、"hachure"、"cross-hatch"
strokeWidth	数字	线条粗细（1、2、4）
strokeStyle	字符串	"solid"、"dashed"、"dotted"
roughness	数字	0 = 锐利，1 = 普通，2 = 草图效果
opacity	数字	0–100
angle	数字	旋转角度（弧度）
groupIds	数组	将元素 ID 分组
seed	数字	手绘效果的随机种子

文本属性

属性	类型	描述
text	字符串	文本内容
fontSize	数字	字体大小（像素）
fontFamily	数字	1 = Virgil（手绘），2 = Helvetica，3 = Cascadia
textAlign	字符串	"left"、"center"、"right"
verticalAlign	字符串	"top"、"middle"

箭头属性

属性	类型	描述
points	数组	相对于元素原点的 [x, y] 坐标数组
startBinding	对象	与源元素的连接
endBinding	对象	与目标元素的连接
startArrowhead	字符串	null、"arrow"、"bar"、"dot"、"triangle"
endArrowhead	字符串	null、"arrow"、"bar"、"dot"、"triangle"

配色方案参考

基于组件的颜色（推荐用于架构图）

组件类型	描边	背景	用途
数据库	#7c3aed	#ede9fe	PostgreSQL、MySQL、MongoDB
缓存	#dc2626	#fee2e2	Redis、Memcached
队列	#16a34a	#dcfce7	Kafka、RabbitMQ、SQS
负载均衡器	#0891b2	#cffafe	Nginx、HAProxy、ALB
网关	#475569	#f1f5f9	API Gateway、Kong
CDN	#06b6d4	#e0f2fe	CloudFront、Fastly
身份验证	#e11d48	#ffe4e6	OAuth、IAM、Cognito
存储	#d97706	#fef3c7	S3、Blob Storage
服务	#2563eb	#dbeafe	后端服务、API
容器	#0284c7	#bae6fd	Docker、Kubernetes
函数	#f59e0b	#fef3c7	Lambda、无服务器
监控	#84cc16	#ecfccb	Prometheus、Grafana
Web 应用	#4f46e5	#e0e7ff	React、Vue、前端
移动端	#6366f1	#eef2ff	iOS、Android

主题颜色

现代（默认）

• 主色：#1971c2 / #e7f5ff
• 中性色：#64748b / #f1f5f9

草图（手绘）

• 主色：#495057 / #f8f9fa
• 使用 roughness: 2 和 fontFamily: 3

技术风格

• 主色：#2f9e44 / #ebfbee
• 连接线使用 strokeStyle: "dashed"

图标库（共 305 个组件）

assets/ 目录中的 .excalidrawlib 文件提供专业图标：

库	组件数	内容
aws-architecture-icons.excalidrawlib	248	AWS 服务图标（Lambda、S3、EC2、RDS、DynamoDB、SQS 等）
system-design.excalidrawlib	24	系统设计元素（服务器、数据库、存储等）
drwnio.excalidrawlib	18	Draw.io 风格图标
system-design-template.excalidrawlib	8	预构建模板（步骤、流程、数据库等）
software-architecture.excalidrawlib	7	软件架构组件

使用库组件

库文件包含可直接嵌入图表的元素数组。每个库项目都是一个由多个 Excalidraw 元素构成的组件。

使用方法：解析库 JSON，找到所需组件，调整位置，并将其包含在图表的 elements 数组中。

布局指南

架构图布局

按层组织组件（从上到下）：

Layer 1: Client/External (y: 100)
Layer 2: Edge/CDN (y: 280)
Layer 3: Gateway/Load Balancer (y: 460)
Layer 4: Services (y: 640)
Layer 5: Data/Cache (y: 820)
Layer 6: Infrastructure (y: 1000)

间距建议：

• 组件之间的水平间距：240px
• 层与层之间的垂直间距：180px
• 组件宽度：180-220px
• 组件高度：80-100px

流程图布局

按从左到右或从上到下的方向排列：

• 步骤间距：200px
• 处理流程使用矩形
• 决策使用菱形
• 开始/结束使用椭圆

思维导图布局

从中心向外辐射布局：

• 中心节点位于 (400, 300)
• 子节点位于半径为 250px 的圆周上
• 使用角度计算均匀分布

完整示例

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "id": "api-gateway",
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 180,
      "height": 80,
      "strokeColor": "#475569",
      "backgroundColor": "#f1f5f9",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "opacity": 100,
      "groupIds": ["group-1"],
      "seed": 1234
    },
    {
      "id": "api-gateway-label",
      "type": "text",
      "x": 140,
      "y": 130,
      "width": 100,
      "height": 25,
      "text": "API Gateway",
      "fontSize": 16,
      "fontFamily": 1,
      "textAlign": "center",
      "strokeColor": "#1e1e1e",
      "groupIds": ["group-1"]
    },
    {
      "id": "redis",
      "type": "diamond",
      "x": 100,
      "y": 280,
      "width": 180,
      "height": 100,
      "strokeColor": "#dc2626",
      "backgroundColor": "#fee2e2",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "seed": 5678
    },
    {
      "id": "redis-label",
      "type": "text",
      "x": 155,
      "y": 320,
      "width": 70,
      "height": 20,
      "text": "Redis",
      "fontSize": 16,
      "fontFamily": 1,
      "textAlign": "center",
      "strokeColor": "#1e1e1e"
    },
    {
      "id": "arrow-1",
      "type": "arrow",
      "x": 190,
      "y": 180,
      "width": 0,
      "height": 100,
      "strokeColor": "#64748b",
      "strokeWidth": 2,
      "points": [[0, 0], [0, 100]],
      "startBinding": {"elementId": "api-gateway", "focus": 0.5, "gap": 5},
      "endBinding": {"elementId": "redis", "focus": 0.5, "gap": 5},
      "endArrowhead": "arrow"
    }
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

输出

将图表保存为 .excalidraw 或 .json 文件。它可以：

• 直接导入 excalidraw.com
• 嵌入文档或 Web 应用
• 使用 Excalidraw 的导出功能转换为 PNG/SVG

给 AI Agent 的提示

1. 生成唯一 ID：为每个元素使用 UUID 或连续 ID
2. 组合相关元素：使用 groupIds 将形状及其标签组合在一起
3. 为箭头使用绑定：使用 startBinding 和 endBinding 将箭头连接到元素
4. 应用一致的样式：为不同类型的组件使用调色板
5. 计算文本位置：根据文本长度调整 x/y，使文本在形状内居中
6. 设置种子值：使用 seed: hash(id)，以确保一致的手绘渲染效果