Excalidraw Diagram Generator

Generate Excalidraw hand-drawn diagrams from natural language. Use when asked to create diagrams, flowcharts, mind maps, architecture diagrams, ER diagrams,...

Security Scan

The skill's files and runtime instructions match its stated purpose (generate .excalidraw files and optionally export PNGs); nothing requests unrelated credentials or installs arbitrary remote code during install, though it does fetch rendering libraries at runtime and requires Playwright/Chromium for PNG export.

Purpose & Capability

Name/description, templates, element spec, examples and the export script are all consistent with generating Excalidraw JSON and producing PNG exports. No unrelated environment variables, binaries, or credentials are requested.

Instruction Scope

SKILL.md confines actions to parsing prompts, creating .excalidraw JSON, saving it, and calling the included export script. It does require network access to fetch JS libraries (unpkg.com) and the headless-export fallback references excalidraw.com; these network calls are consistent with rendering but are external operations the user should be aware of. The SKILL.md uses a hard-coded path to the script under ~/.openclaw which assumes the skill is installed there.

Install Mechanism

There is no install spec (instruction-only), so nothing is written to disk automatically. PNG export requires users to install Playwright and Chromium (pip install playwright; playwright install chromium). Runtime loads libraries from unpkg.com (well-known CDN) — runtime network fetches are expected for rendering but mean remote JS is executed in the browser context.

Credentials

The skill requests no environment variables, credentials, or config paths. The export script writes to temporary directories and the specified output path only; no secret access is requested or required.

Persistence & Privilege

Flags are default (always:false, user-invocable:true). The skill does not request permanent/system-level privileges or modify other skills. The script runs a short-lived local HTTP server and a headless browser, which is standard for local rendering.

Assessment

This skill appears to do what it says: generate .excalidraw JSON and optionally export PNGs. Before installing/running: (1) be aware PNG export requires you to install Playwright and Chromium and will launch a headless browser (it uses --no-sandbox on Linux); (2) runtime will fetch JavaScript from CDNs (unpkg.com) or may open excalidraw.com in the fallback — this loads remote code into the browser context to render the image; (3) the export script writes temporary files and binds to localhost ports briefly (18765–18774); (4) review the included scripts if you require fully offline or high-assurance operation. If you don’t want network-loaded JS or headless Chromium, you can still use the skill to produce .excalidraw files and export them manually via excalidraw.com or a trusted local tool.

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

---

元素快速参考

颜色方案（强制使用）

用途	颜色代码
主要节点 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位字母数字）：

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