tldraw-desktop

tldraw 桌面画布 API

通过本地 HTTP API http://localhost:7236，以编程方式在 tldraw 桌面应用中创建和修改图表。

**重要：**所有 API 调用都必须使用 curl。请勿使用 fetch、wget 或任何其他 HTTP 客户端。

工作流

1. curl -s http://localhost:7236/api/doc                          → list open docs (get DOC_ID)
2. curl -s http://localhost:7236/api/doc/{id}/shapes              → read current shapes
3. curl -s -X POST http://localhost:7236/api/doc/{id}/actions     → create/modify shapes
4. curl -s http://localhost:7236/api/doc/{id}/screenshot -o f.jpg → verify result visually

完成更改后，务必通过截图检查效果。建议分成小批次逐步进行。

重叠检查 — 每批更改后都必须执行

创建或修改形状后，你必须：

1. 截取屏幕截图，并目视检查是否有形状重叠、箭头交叉或文字拥挤
2. 如果发现重叠或可读性问题，请使用 place、move、stack、align 或 distribute 进行修复
3. 再次截取屏幕截图，确认问题已修复

digraph overlap_check {
    "Make changes" -> "Screenshot";
    "Screenshot" -> "Overlaps or crowding?" [label="inspect"];
    "Overlaps or crowding?" -> "Fix layout" [label="yes"];
    "Fix layout" -> "Screenshot";
    "Overlaps or crowding?" -> "Done" [label="no, clean"];
}

常见重叠问题的修复方法：

• 形状相互叠放 → 使用 stack 并设置 gap: 80，或使用 place 并设置 sideOffset: 80
• 箭头穿过无关形状 → 将挡路的形状移出路径，或使用 kind: "elbow" 进行直角布线
• 文本标签重叠 → 加宽形状（使用 resize，或通过 update 增大 w），或增大形状间距
• 图表过于密集 → 使用 stack + align 拆分为多行或多列，或使用 distribute 增大间距

快速参考

端点

方法	端点	说明
GET	/api/doc	列出已打开的文档。筛选条件：?name=
GET	/api/doc/:id/shapes	当前页面上的所有形状
GET	/api/doc/:id/screenshot	JPEG 截图。?size=small|medium|large|full
POST	/api/doc/:id/actions	结构化操作（见下文）
POST	/api/doc/:id/exec	针对 tldraw Editor 运行任意 JS

形状类型

类型	关键属性
rectangle、ellipse、triangle、diamond、hexagon、pill、cloud、star、heart、pentagon、octagon、x-box、check-box、trapezoid、parallelogram-right/left、fat-arrow-right/left/up/down	shapeId, x, y, w, h, color, fill, text, note
text	shapeId, x, y, anchor, color, fontSize, maxWidth, text
arrow	shapeId, fromId, toId, color, kind (arc|elbow), text, bend
line	shapeId, x1, y1, x2, y2, color
note	shapeId, x, y, color, text（便利贴）
pen	shapeId, points:[{x,y}], color, style (smooth|straight), closed, fill

**颜色：**red、light-red、green、light-green、blue、light-blue、orange、yellow、black、violet、light-violet、grey、white
**填充：**none、tint、background、solid、pattern
**锚点（文本）：**top-left、top-center、top-right、center-left、center、center-right、bottom-left、bottom-center、bottom-right

操作

向 /api/doc/:id/actions 发送 POST 请求，并附上 {"actions": [...]}。一个请求中的所有操作 = 一个撤销步骤。

操作	负载
create	{"_type":"create","shape":{...}}
update	{"_type":"update","shape":{"shapeId":"id","_type":"rect",...changed props}}
delete	{"_type":"delete","shapeId":"id"}
clear	{"_type":"clear"}
label	{"_type":"label","shapeId":"id","text":"new text"}
move	{"_type":"move","shapeId":"id","x":N,"y":N,"anchor":"center"}
place	{"_type":"place","shapeId":"id","referenceShapeId":"ref","side":"right","align":"center","sideOffset":20}
align	{"_type":"align","shapeIds":[...],"alignment":"center-horizontal"}
distribute	{"_type":"distribute","shapeIds":[...],"direction":"horizontal"}
stack	{"_type":"stack","shapeIds":[...],"direction":"vertical","gap":20}
resize	{"_type":"resize","shapeIds":[...],"scaleX":2,"scaleY":1.5}
rotate	{"_type":"rotate","shapeIds":[...],"degrees":45}
bringToFront	{"_type":"bringToFront","shapeIds":[...]}
sendToBack	{"_type":"sendToBack","shapeIds":[...]}
pen	{"_type":"pen","shapeId":"id","points":[{"x":0,"y":0},...],"color":"black","style":"smooth"}

place 的侧边： top、bottom、left、right align 选项： top、center-vertical、bottom、left、center-horizontal、right

最佳实践

• 所有 HTTP 调用一律使用 curl——无例外
• **默认形状尺寸：**约 300x200，形状之间间隔约 200
• **用箭头连接形状：**使用 fromId/toId——形状移动时箭头仍会保持连接
• 优先使用高级操作（place、stack、align），而非手动计算坐标
• 在单个 POST 请求中批量执行操作，以便原子化地撤销/重做
• 使用 place 将形状相对于彼此定位，而不是计算坐标
• **默认样式：**黑色、中等、绘制样式、文本居中、无填充——除非有理由更改
• **填充建议：**轮廓使用 none，有色背景使用 solid
• 更改后截取屏幕截图，以验证布局并检查是否有重叠
• 分配易读的 shapeId（例如 "auth-box"、"db-node"），以便更轻松地引用
• **大型图表（7 个或更多形状）：**分阶段构建——先创建几个形状，截取屏幕截图，调整布局，然后再添加更多形状

示例：创建流程图

DOC_ID="your-doc-id"
BASE="http://localhost:7236/api/doc/$DOC_ID"

# Create shapes + connect with arrows in one call
curl -s -X POST "$BASE/actions" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"_type":"create","shape":{"_type":"rectangle","shapeId":"start","x":100,"y":100,"w":300,"h":200,"text":"Start"}},
      {"_type":"create","shape":{"_type":"diamond","shapeId":"decision","x":100,"y":400,"w":300,"h":200,"text":"Condition?"}},
      {"_type":"create","shape":{"_type":"rectangle","shapeId":"end","x":100,"y":700,"w":300,"h":200,"text":"End"}},
      {"_type":"create","shape":{"_type":"arrow","shapeId":"a1","fromId":"start","toId":"decision"}},
      {"_type":"create","shape":{"_type":"arrow","shapeId":"a2","fromId":"decision","toId":"end","text":"Yes"}}
    ]
  }'

# MANDATORY: Screenshot to check for overlaps
curl -s "$BASE/screenshot?size=medium" -o screenshot.jpg
# Inspect the screenshot — if shapes overlap or arrows cross, fix with place/move/stack

Exec API

对于结构化操作未涵盖的高级操作：

curl -s -X POST "$BASE/exec" \
  -H "Content-Type: application/json" \
  -d '{"code": "return editor.getCurrentPageShapeIds().size"}'

完整 SDK 文档可通过以下命令获取：curl -s http://localhost:7236/api/llms