Excalidraw Diagram Generator

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.

mcdowelll@mcdowell8023

Install

openclaw skills install @mcdowell8023/oc-excalidraw-diagram

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 + arrow	3–10 步	上→下
架构图	rectangle + arrow	5–15 节点	分层
思维导图	ellipse + rectangle + arrow	中心+4–6 分支	辐射
关系图	ellipse/rectangle + arrow	3–8 实体	自由
ER 图	rectangle + text + arrow	3–8 表	网格
时序图	rectangle + text + arrow	3–6 参与者	左→右+时间轴
泳道图	rectangle(lane) + arrow	2–4 泳道	左→右
类图	rectangle + text + arrow	3–8 类	层次
数据流图	ellipse + rectangle + arrow	5–12 节点	自由

ID 生成规则

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

text

"id": "abc12345"

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

常见错误预防

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

示例参考

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