WorkRally 画布整理 Skill(MCP 版)
执行通道:本 skill 全程使用 WorkRally MCP 工具(
mcp__workrally1__*)。 不要调用workrallyCLI,也不要依赖WORKRALLY_API_KEY——鉴权由 MCP 连接器托管。 本地脚本只做纯计算;所有 I/O 由 Agent 走 MCP 完成。迁移对照:
workrally tools call asset_search→asset_search;workrally canvas get→canvas_manage(action="get");workrally canvas build-draft→canvas_manage(action="build_draft")。
适用场景
用户说"帮我整理一下画布"、"把图片和视频分画板"、"按类型把画布归类"等,并给出一个 WorkRally 画布链接或画布 ID 时使用。
画布链接形如 https://workrally.qq.com/toolbox/canvas/<canvas_id>。
🛡️ 核心安全铁律(不可违反)
1. 文字节点(text)和画笔节点(freehand)永远保留,不论任何情况、任何参数、任何用户指令都不动它们。
2. 默认使用
mode="merge"(增量合并),只新增/重排媒资,不删除任何现有节点。
展开说明:
- text / freehand 绝对保留 — 用户的笔记、手绘、旁白、分镜文字记录是其创作心血,任何整理/清理操作都必须跳过它们。这条是最高优先级约束,即使用户说"清空画布"、"全部删了",也必须先与用户二次确认且显式列出要删除的节点清单。
- merge 模式优先 — 常规整理操作必须使用
mode="merge",绝对禁止mode="overwrite"(全量覆盖会毁掉所有未传入的节点)。 - 媒资(image/video)可重排 — 素材资产通过重新写入坐标归位到新画板中,但不会删除素材本身(只是移动位置)。
- 清理散落原节点 — 整理完成后如果用户要求"清理散落的旧节点",可以只针对散落的 image/video 孤儿节点执行删除,必须硬编码排除
type in ('text', 'freehand', 'artboard', 'generator')。
技术说明
asset_search 只返回媒资(image/video/audio),不返回 text/freehand/artboard 节点。因此:
- 常规整理操作只影响媒资的位置归位(移入分类画板)
- 文字、画笔、原有画板不受影响
- 清理散落原节点需要另行解析
canvas_manage(action="get")返回的 draft_v1(Y.js update 二进制),详见 Step 7
核心工作流
Step 1:解析画布 ID
从用户给的 URL 或参数中提取 canvas_id:
# URL: https://workrally.qq.com/toolbox/canvas/p9x251r3jsgima0uenm0dv3
# 取末尾路径段即可。
Step 2:获取画布里的全部素材(MCP)
调用 asset_search。⚠️ 画布筛选必须同时传 canvas_project_id 与 channel=["toolbox_canvas"]:
asset_search(
canvas_project_id = ["<canvas_id>"],
channel = ["toolbox_canvas"],
page_size = 100, # 默认 20,最大值 100
page = 1
)
→ {"assets": [{"id":..., "type":"image|video|audio", "title":..., "asset_details": {...}}, ...]}
把返回原样落盘(如 /tmp/workrally/assets.json)。若本页返回条数 = page_size,说明还有下一页,继续 page=2,3... 并把 assets[] 合并。
不传 project_id 也能查到。
Step 3:按规则分类
根据 title 的前缀/关键词将素材分组。不同场景下规则不同,需要先把所有 title 列给用户看,征询分类依据后再执行。
典型规则示例(见 references/classification-rules.md):
| 组名 | 匹配规则 |
|---|---|
| 🎭 人物资产 | title 含特定关键词(如"韩团风"、"清凉造型"、"角色"、"人物") |
| 🎬 风格/分镜组 | title 前缀匹配(如"迪金斯·"、"太空电梯·") |
| 🎥 视频库 | type == "video",不考虑标题 |
| 📦 杂项 / 散图 | hash 命名、默认命名(image.png)、未匹配上的兜底组 |
Step 4:用脚本生成节点 JSON 布局(纯本地)
python3 scripts/organize_canvas.py \
--canvas-id <canvas_id> \
--assets /tmp/workrally/assets.json \
--rules rules.json \
--captions \
--output /tmp/workrally/canvas_nodes.json \
--emit-args /tmp/workrally/build_args.json
布局参数:
- 网格单元尺寸:
CELL_W=280, CELL_H=280 - 单元间距:
GAP=20 - 画板内边距:
PAD=40(左/右/下)、PAD + TITLE_H=60+40(上,为标题预留) - 画板之间横向间距:
BOARD_GAP=200 - 画板标题:独立 text 节点,放在画板外部上方(text 不能作为 artboard 子节点)
画板从左到右依次铺开,每板列数根据数量调整(一般 4 ~ 7 列)。
可选 --captions 为每个素材生成标题文字节点(caption),显示在素材下方。
Step 5:增量合并写入画布(⚠️ 必须 mode="merge",禁止 overwrite)
canvas_manage(
action = "build_draft",
canvas_id = "<canvas_id>",
nodes = <build_args.json 里的 nodes 数组>,
mode = "merge"
)
mode="merge"= 增量合并,只新增/更新传入的节点,不删除任何现有节点。 同名id覆盖(修改)、新id追加(新增)、未提及的已有节点保留不动。 遇到版本冲突(code=3009)MCP 会自动重试。
Step 6:校验
再调一次 canvas_manage(action="get", canvas_id="<canvas_id>"),看返回里的节点统计与类型分布,确认画板与素材数量符合预期。
Step 7(可选):清理散落的旧媒资节点(文字节点绝不清理)
触发时机:整理完成后,用户说"原节点除了文字都不用保留"、"清理散落的旧图片"、"把归类外的图片删掉"等。
关键约束:
- 只删除
type ∈ {image, video}且parentId为空(即不在任何画板内的孤儿节点) text、freehand、artboard、generator类型硬编码排除,绝不删除- 新整理产生的子节点都挂在画板下(
parentId非空),不会被误删
① Agent 取快照(MCP):
canvas_manage(action="get", canvas_id="<canvas_id>")
→ 完整返回原样落盘 /tmp/workrally/canvas_snapshot.json
② 本地筛孤儿:
python3 scripts/cleanup_orphans.py \
--canvas /tmp/workrally/canvas_snapshot.json \
--canvas-id <canvas_id> \
--emit-delete-args /tmp/workrally/del_args.json
③ 目检清单后执行(MCP,逐批):
canvas_manage(action="build_draft", canvas_id="<canvas_id>",
delete_node_ids=<某一批>, mode="merge")
该脚本会:
- 读
canvas_manage(action="get")落盘的完整返回 - 解析
draft_v1(Y.js update 二进制)扫描出所有节点 id/type/parentId - 筛选
type ∈ {image, video} && parentId is empty的孤儿节点 - 硬性排除 text/freehand(无论 parentId 如何)
- 分批(每批 ≤ 80)输出
delete_node_ids,交给 MCPbuild_draft删除
⚠️ 若快照里找不到
draft_v1,说明落盘时被裁剪了。必须把 MCPget的完整返回原样落盘。
快速调用
常规整理(安全,不删任何东西)
python3 <skill_dir>/scripts/organize_canvas.py \
--canvas-id <canvas_id> \
--assets /tmp/workrally/assets.json \
--rules <skill_dir>/rules.json \
--captions \
--emit-args /tmp/workrally/build_args.json
# 然后 Agent 用 MCP canvas_manage(build_draft, mode="merge") 写回
整理后清理散落原节点(文字节点强制保留)
python3 <skill_dir>/scripts/cleanup_orphans.py \
--canvas /tmp/workrally/canvas_snapshot.json \
--canvas-id <canvas_id> \
--emit-delete-args /tmp/workrally/del_args.json
# 然后 Agent 用 MCP canvas_manage(build_draft, delete_node_ids=[...], mode="merge") 删除
关键经验 / 踩坑
asset_search的画布筛选要两个字段一起给 ——canvas_project_id=[...]必须搭配channel=["toolbox_canvas"],否则筛不出来。asset_search的page_size默认 20、最大 100 —— 画布素材多时要翻页并合并assets[]。canvas_manage(action="get")返回的 draft.content 总是"{}",这是正常现象(节点在 Yjs 端)。真正的节点数据在draft_v1字段(base64 编码的 Y.js update)。- artboard 子节点只能是 image/video/audio,text/freehand/generator 都不能放画板里。因此 caption 文字节点使用绝对坐标放置在素材下方,而不是作为 artboard 的子节点。
- text 节点必须有
data.text.content,用于画板标题时建议fontSize: 40, fontWeight: 700, color: '#ffffff'。 - 子节点不要设置
extent: "parent",否则被锁死拖不出画板(服务端会自动清除,但别写)。 - 永远使用
mode="merge",禁止overwrite。merge 是安全的增量操作。 - 删除节点走
delete_node_ids:canvas_manage(action="build_draft", canvas_id=<id>, delete_node_ids=[...], mode="merge")。每批建议 ≤ 80 个 ID 保险。不要用delete_node_ids与nodes混在一批里做危险操作。 - draft_v1 是 Y.js update 二进制(非 gzip/msgpack/cbor),字段编码为
<name_len><name>\x01w<varint_len><value>。无需 Y.js 官方库,手写扫描即可提取 id/type/parentId。 - 识别散落原节点:新整理生成的媒资子节点 id 形如
node_<uuid>且parentId=board_*;原 UUID (36 字符) 节点且无 parentId 即散落孤儿。 - 落盘 MCP 返回时不要裁剪 ——
canvas_manage(get)的完整返回里才有draft_v1;只存content会导致 Step 7 无法解析。
相关参考
- references/classification-rules.md — 分类规则写法与
rules.json配置格式 - references/layout-cheatsheet.md — 网格布局公式与常用尺寸
✅ 执行前告知用户
常规整理(非破坏性)
我要把画布整理成 N 个画板:A (x张) / B (y张) / ... 。素材会被归位到新画板中,你现有的文字、画笔等内容完全不受影响。 直接执行?
清理散落原节点(破坏性 — 必须二次确认)
我会删除 X 个散落的原图片/视频节点(未归类到任何画板的孤儿)。 🛡️ 已强制保留:Y 个文字节点 + Z 个画笔节点 + 所有分类画板及其子节点。 是否执行?