Excalidraw 图表技能
Harness-agent 工具
本技能从 Octop 移植。使用这些 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
通过编写标准 Excalidraw 元素 JSON 并保存为 .excalidraw 文件来创建图表。这些文件可以拖放到 excalidraw.com 进行查看和编辑。无需账户、API 密钥或渲染库——只需 JSON。
何时使用
为架构图、流程图、序列图、概念图等生成 .excalidraw 文件。文件可以在 excalidraw.com 上打开或上传以获取可共享链接。
工作流
- 加载本技能(你已经做了)
- 编写元素 JSON——Excalidraw 元素对象数组
- 保存文件——使用
write_file创建.excalidraw文件 - 可选上传——通过
execute使用scripts/upload.py获取可共享链接
保存图表
将元素数组包装在标准 .excalidraw 信封中,并使用 write_file 保存:
{
"type": "excalidraw",
"version": 2,
"source": "octop-harness",
"elements": [ ...你的元素数组... ],
"appState": {
"viewBackgroundColor": "#ffffff"
}
}
保存到任意路径,例如 ~/diagrams/my_diagram.excalidraw。
上传获取可共享链接
通过 execute 运行上传脚本:
python _builtin_skills/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:2roughness: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-order)
- 数组顺序 = z-order(第一个 = 后面,最后一个 = 前面)
- 渐进式发射:背景区域 → 形状 → 其绑定的文本 → 其箭头 → 下一个形状
- 错误:所有矩形,然后所有文本,然后所有箭头
- 良好:bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
- 始终将绑定的文本元素紧接在其容器形状之后放置
尺寸指南
字体大小:
- 正文文本、标签、描述的最小
fontSize:16 - 标题和标题的最小
fontSize:20 - 仅限二次注释的最小
fontSize:14(谨慎使用) - 绝不使用低于 14 的
fontSize
元素大小:
- 带标签的矩形/椭圆的最小形状大小:120x60
- 元素之间至少保留 20-30px 间隙
- 优先使用更少、更大的元素,而不是许多小元素
调色板
完整颜色表参见 references/colors.md。快速参考:
| 用途 | 填充颜色 | 十六进制 |
|---|---|---|
| 主要/输入 | 浅蓝色 | #a5d8ff |
| 成功/输出 | 浅绿色 | #b2f2bb |
| 警告/外部 | 浅橙色 | #ffd8a8 |
| 处理/特殊 | 浅紫色 | #d0bfff |
| 错误/关键 | 浅红色 | #ffc9c9 |
| 笔记/决策 | 浅黄色 | #fff3bf |
| 存储/数据 | 浅青色 | #c3fae8 |
提示
- 在整个图表中一致使用调色板
- 文本对比度至关重要——绝不要在白色背景上使用浅灰色。白色上的最小文本颜色:
#757575 - 不要在文本中使用 emoji——它们在 Excalidraw 字体中不会渲染
- 对于暗色模式图表,参见
references/dark-mode.md - 对于更大的示例,参见
references/examples.md