WorkRally 无限画布指南

详细说明 WorkRally Infinite Canvas 的节点模型、画板规则、build-draft 增量合并与覆盖模式，以及项目和画布的区别。

项目与画布的区别

`workrally project list` 返回项目 ID，用于 `asset create --project-id`。
`workrally canvas list` 返回画布 ID，用于 `canvas build-draft` 和画布内 AI 生成。
在画布场景下，素材通常既要关联项目，也要在画布中有节点。

8 种节点类型

type	说明	关键字段	画板内可用
image	图片素材节点	asset.id 或 task	可放入画板
video	视频素材节点	asset.id 或 task	可放入画板
audio	音频素材节点	asset.id	可放入画板
imageGenerator	图片生成器节点	通常无需手工创建	不可放入画板
videoGenerator	视频生成器节点	通常无需手工创建	不可放入画板
artboard	画板容器	建议设置 width/height	不可嵌套
text	文本节点	data.text.content	不可放入画板
freehand	涂鸦节点	points + initialSize	不可放入画板

其中 `image`、`video`、`audio` 是实际素材节点；`text` 和 `freehand` 是说明与标注节点； `artboard` 是容器；`imageGenerator` 和 `videoGenerator` 通常不需要手工创建。

画板规则

画板只能承载 `image`、`video`、`audio` 子节点。
画板不可嵌套。
不要给画板子节点设置 `extent: "parent"`，否则拖拽会被锁死。
如果没传尺寸，系统会按默认值补齐画板大小。

artboard-example.jsonjson

[
  {
    "id": "board_001",
    "type": "artboard",
    "position": { "x": 0, "y": 0 },
    "data": {},
    "style": { "width": 600, "height": 800 }
  },
  {
    "id": "img_in_board",
    "type": "image",
    "position": { "x": 20, "y": 20 },
    "data": { "asset": { "id": "asset_abc123" } },
    "style": { "width": 256, "height": 256 },
    "parentId": "board_001"
  }
]

build-draft 操作模式

build-draft.shbash

# 增量合并
workrally canvas build-draft <canvas_id> --nodes '[...]'

# 删除节点
workrally canvas build-draft <canvas_id> --delete-node-ids "id1,id2"

# 同时删除 + 新增
workrally canvas build-draft <canvas_id> --nodes '[...]' --delete-node-ids "old1"

# 全量覆盖
workrally canvas build-draft <canvas_id> --nodes '[...]' --mode overwrite

默认模式是增量合并，规则是：

相同 `id`：覆盖更新。
新 `id`：追加到现有画布。
未提及节点：保持不变。

`overwrite` 只适合你明确要重建整张画布的场景。多人协作时优先用默认的增量模式。