excalidraw-diagram#

能力概述#

将自然语言描述转为 Excalidraw 可视化图表（.excalidraw 文件），保存到当前工作目录或用户指定路径。

支持图表类型： 流程图 · 架构图 · 思维导图 · 关系图 · ER图 · 时序图 · 泳道图 · 类图 · 数据流图

---

执行步骤#

Step 1 — 理解需求#

• 识别图表类型（如未明确，根据内容自动判断）
• 提取节点、关系、层次结构
• 确认文件名（用户未指定时用 diagram-{YYYYMMDD-HHmm}.excalidraw）
• 确认保存路径（用户未指定时保存到当前工作目录）

Step 2 — 规划布局#

参考 references/diagram-templates.md 对应模板，按以下规则布局：

• 水平间距： 200–300px
• 垂直间距： 100–150px
• 起点坐标： x=100, y=100
• 流程图：从上到下或从左到右
• 思维导图：中心节点向四周辐射
• 时序图/泳道图：横向分列

Step 3 — 生成 JSON#

严格按照 元素规范 构建 elements 数组，生成标准 .excalidraw 文件结构：

json

{
  "type": "excalidraw",
  "version": 2,
  "source": "openclaw-skill",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Step 3.5 — 文字元素叠加（关键！）#

每个带文字的形状（rectangle/ellipse/diamond）除了形状自身的 text 属性外， 必须同时生成一个独立的 text 元素叠加在形状上方。

原因：Excalidraw 在 headless 浏览器导出 PNG 时，形状内嵌文字不渲染， 但独立 text 元素可以正常显示。双重文字确保在线编辑和导出都能看到文字。

text 元素坐标计算：

• x = 形状.x + 10
• y = 形状.y + (形状.height - 行数 × 22) / 2
• width = 形状.width - 20
• textAlign: "center"
• containerId: null（不绑定到容器）

示例：

json

// 形状元素
{
  "id": "rect001",
  "type": "rectangle",
  "x": 100, "y": 100,
  "width": 160, "height": 60,
  "label": { "text": "用户登录" }
}
// 叠加的独立 text 元素（必须同时生成）
{
  "id": "txt001",
  "type": "text",
  "x": 110,
  "y": 119,
  "width": 140,
  "text": "用户登录",
  "fontSize": 16,
  "fontFamily": 5,
  "textAlign": "center",
  "containerId": null
}

Step 4 — 保存文件#

bash

# 写入文件（使用 write 工具）
# 路径：<用户指定目录或当前工作目录>/<filename>.excalidraw

Step 4.5 — 导出 PNG（默认执行）#

生成 .excalidraw 文件后，自动导出 PNG：

bash

python3 ~/.openclaw/workspace/skills/excalidraw-diagram/scripts/export-png.py <input.excalidraw> <output.png>

• 依赖： playwright（ pip install playwright && playwright install chromium）
• 需要联网（首次加载 CDN 资源约 15-30s）
• 输出 PNG 通常 > 50 KB，分辨率 1400×900

如果导出失败，告知用户手动在 excalidraw.com 打开文件导出。

Step 5 — 回报结果#

告知用户：

• 文件保存路径
• 图表包含的元素数量
• 如何在 Excalidraw 中打开（excalidraw.com 或桌面版）
• 如需导出 PNG，参考 references/headless-export.md

---

元素快速参考#

颜色方案（强制使用）#

用途颜色代码主要节点 Primary#a5d8ff次要节点 Secondary#b2f2bb重要/高亮 Important#ffd43b警告/错误 Alert#ffc9c9背景透明"transparent"

字体规范（强制）#

• fontFamily: 5（Excalifont，Excalidraw 官方手绘字体）
• 正文字号： fontSize: 16
• 标题字号： fontSize: 20
• 大标题： fontSize: 24

元素类型#

形状type典型用途矩形rectangle流程步骤、模块、类椭圆ellipse开始/结束节点、实体菱形diamond判断条件、决策箭头arrow连接、流向、关系文本text标签、说明

详细属性见 元素规范。

---

各图表类型要点#

图表类型主要形状元素数量建议方向流程图rectangle + diamond + arrow3–10 步上→下架构图rectangle + arrow5–15 节点分层思维导图ellipse + rectangle + arrow中心+4–6 分支辐射关系图ellipse/rectangle + arrow3–8 实体自由ER 图rectangle + text + arrow3–8 表网格时序图rectangle + text + arrow3–6 参与者左→右+时间轴泳道图rectangle(lane) + arrow2–4 泳道左→右类图rectangle + text + arrow3–8 类层次数据流图ellipse + rectangle + arrow5–12 节点自由

---

ID 生成规则#

每个元素需要唯一 ID，使用随机字符串（8位字母数字）：

text

"id": "abc12345"

箭头的 startBinding.elementId 和 endBinding.elementId 必须指向对应元素的 id。

---

常见错误预防#

1. 箭头未绑定：arrow 元素必须设置 startBinding 和 endBinding，否则连线会断开
2. 坐标重叠：确保相邻元素之间有足够间距（最小 20px padding）
3. 文字溢出：元素宽度 = 文字字符数 × 10 + 40（最小 120px）
4. 缺少 points：arrow 类型必须包含 points: [[0,0],[dx,dy]]
5. 文字不显示（导出时）：必须按 Step 3.5 为每个形状叠加独立 text 元素

---

示例参考#

见 references/examples.md — 包含各类图表的完整 prompt + 输出示例。