HERMES DOCUMENTATIONDOCS / CURRENT

Excalidraw

使用 Excalidraw JSON 格式创建手绘风格的图表。生成用于架构图、流程图、时序图、概念图等内容的 .excalidraw 文件。这些文件可以在 excalidraw.com 上打开，或上传以获取可分享的链接。

技能元数据


来源	捆绑（默认安装）
路径	`skills/creative/excalidraw`
版本	`1.0.0`
作者	Hermes Agent
许可证	MIT
标签	`Excalidraw`, `Diagrams`, `Flowcharts`, `Architecture`, `Visualization`, `JSON`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理所看到的指令。

Excalidraw 图表技能

通过编写标准的 Excalidraw 元素 JSON 并保存为 .excalidraw 文件来创建图表。这些文件可以拖放到 excalidraw.com 上进行查看和编辑。无需账户，无需 API 密钥，无需渲染库——只需 JSON。

工作流程

加载此技能（你已完成）
编写元素 JSON —— 一个 Excalidraw 元素对象数组
保存文件 使用 write_file 创建 .excalidraw 文件
可选上传 以获取可分享链接，通过 terminal 运行 scripts/upload.py

保存图表

将你的元素数组包裹在标准的 .excalidraw 信封中，并使用 write_file 保存：

{
  "type": "excalidraw",
  "version": 2,
  "source": "hermes-agent",
  "elements": [ ...your elements array here... ],
  "appState": {
    "viewBackgroundColor": "#ffffff"
  }
}

保存到任意路径，例如 ~/diagrams/my_diagram.excalidraw。

上传以获取可分享链接

通过终端运行上传脚本（位于此技能的 scripts/ 目录中）：

python skills/diagramming/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw

这会将文件上传到 excalidraw.com（无需账户）并打印可分享的 URL。需要 cryptography pip 包（pip install cryptography）。

元素格式参考

必填字段（所有元素）

type, id（唯一字符串）, x, y, width, height

默认值（跳过这些——它们会自动应用）

strokeColor: "#1e1e1e"
backgroundColor: "transparent"
fillStyle: "solid"
strokeWidth: 2
roughness: 1（手绘外观）
opacity: 100

画布背景为白色。

元素类型

矩形：

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }

roundness: { "type": 3 } 用于圆角
backgroundColor: "#a5d8ff", fillStyle: "solid" 用于填充

椭圆：

{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }

菱形：

{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }

带标签的形状（容器绑定） —— 创建一个绑定到形状的文本元素：

警告： 不要在形状上使用 "label": { "text": "..." }。这不是有效的 Excalidraw 属性，会被静默忽略，导致形状为空。你必须使用下面的容器绑定方法。

形状需要 boundElements 列出文本，而文本需要 containerId 指回形状：

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
  "boundElements": [{ "id": "t_r1", "type": "text" }] },
{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "r1", "originalText": "Hello", "autoResize": true }

适用于矩形、椭圆、菱形
当设置 containerId 时，Excalidraw 会自动居中文字
文本的 x/y/width/height 是近似值——Excalidraw 会在加载时重新计算它们
originalText 应与 text 匹配
始终包含 fontFamily: 1（Virgil/手绘字体）

带标签的箭头 —— 同样的容器绑定方法：

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
  "boundElements": [{ "id": "t_a1", "type": "text" }] },
{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "a1", "originalText": "connects", "autoResize": true }

独立文本（仅用于标题和注释——无容器）：

{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
  "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }

x 是左边缘。若要居中于位置 cx：x = cx - (text.length * fontSize * 0.5) / 2
不要依赖 textAlign 或 width 进行定位

箭头：

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow" }

points: [dx, dy] 相对于元素 x, y 的偏移量
endArrowhead: null | "arrow" | "bar" | "dot" | "triangle"
strokeStyle: "solid"（默认）| "dashed" | "dotted"

箭头绑定（将箭头连接到形状）

{
  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
  "points": [[0,0],[150,0]], "endArrowhead": "arrow",
  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
}

fixedPoint 坐标：top=[0.5,0], bottom=[0.5,1], left=[0,0.5], right=[1,0.5]

绘制顺序（Z 轴顺序）

数组顺序 = Z 轴顺序（第一个 = 背面，最后一个 = 正面）
逐步输出：背景区域 → 形状 → 其绑定的文本 → 其箭头 → 下一个形状
错误做法：所有矩形，然后所有文本，然后所有箭头
正确做法：bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
始终将绑定的文本元素紧接在其容器形状之后放置

尺寸指南

字体大小：

最小 fontSize：16 用于正文、标签、描述
最小 fontSize：20 用于标题和_heading_
最小 fontSize：14 仅用于次要注释（少用）
切勿使用低于 14 的 fontSize

元素尺寸：

最小形状尺寸：带标签的矩形/椭圆为 120x60
元素之间至少保留 20-30px 的间隙
倾向于使用更少、更大的元素，而不是许多微小的元素

颜色调色板

参见 references/colors.md 获取完整的颜色表。快速参考：

用途	填充颜色	十六进制值
主要 / 输入	浅蓝色	`#a5d8ff`
成功 / 输出	浅绿色	`#b2f2bb`
警告 / 外部	浅橙色	`#ffd8a8`
处理中 / 特殊	浅紫色	`#d0bfff`
错误 / 关键	浅红色	`#ffc9c9`
注释 / 决策	浅黄色	`#fff3bf`
存储 / 数据	浅青色	`#c3fae8`

提示

在整个图表中一致地使用调色板
文本对比度至关重要 -- 切勿在白色背景上使用浅灰色。白色背景上的最小文本颜色为：#757575
不要在文本中使用表情符号 -- 它们在 Excalidraw 的字体中无法渲染
对于深色模式图表，请参阅 references/dark-mode.md
对于更大的示例，请参阅 references/examples.md

搜索中文文档

技能元数据​

参考：完整 SKILL.md​

Excalidraw 图表技能

工作流程​

保存图表​

上传以获取可分享链接​

元素格式参考​

必填字段（所有元素）​

默认值（跳过这些——它们会自动应用）​

元素类型​

箭头绑定（将箭头连接到形状）​

绘制顺序（Z 轴顺序）​

尺寸指南​

颜色调色板​

提示​