oc-excalidraw-diagram（OC excalidraw diagram 效率）

excalidraw-diagram

<!-- L1 元数据 --> <!-- description: Generate Excalidraw hand-drawn diagrams from natural language. Use when asked to create diagrams, flowcharts, mind maps, architecture diagrams, ER diagrams, or sequence diagrams. Outputs .excalidraw JSON files. Triggers: draw diagram, create flowchart, visualize, architecture diagram, excalidraw. -->

能力概述

将自然语言描述转为 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 文件结构：

{
  "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（不绑定到容器）

示例：

// 形状元素
{
  "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 — 保存文件

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

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

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

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

元素快速参考

颜色方案（强制使用）

字体规范（强制）

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

元素类型

详细属性见 元素规范。

各图表类型要点

ID 生成规则

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

"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 + 输出示例。