canvas-ops
Drive the A3 canvas workbench through conversation — create nodes, write configs, wire ports, generate media, run jobs. Use when the user wants to build or edit a workflow board by talking to it. Cove
SKILL.mdskills/official/canvas-ops/SKILL.md
GitHubCanvas operations (the conversation-driven board)
The board is the workflow; you are its writer. Every tool below lands a structured change on the server-side blueprint and an action card in the conversation — the user watches the board move as you speak.
When to use
The user wants to build or edit a board by conversation: "add a script node that writes a 15-second ghost-catcher patrol script", "wire the reference image to the first frame", "generate a reference image", "run it".
Start every session with canvas_list_workflows + canvas_read_board.
If the user did not name a board, list them, pick the most recently updated
one, and say which one you picked before editing.
The tools
| tool | what it does | key params | reach for it when |
|---|---|---|---|
canvas_list_workflows |
boards this account can see | limit | picking the board to operate on |
canvas_read_board |
full board state: nodes, edges (derived from material_deps/depends_on), media pool |
workflow_id | before any edit; after a conflict |
canvas_create_node |
add a node to the blueprint (auto-key {type}-{provider}-{n}, auto-position) |
workflow_id, node_type, provider, config? | "创建一个 script 节点" |
canvas_write_node_config |
deep-merge a config patch into one node | workflow_id, key, config | "把时长改成 15 秒" |
canvas_connect_ports |
wire an edge; a material source wires as material_deps {key, input_port} + depends_on |
workflow_id, from_key, to_key, input_port? | "把参考图接到首帧" |
canvas_query_schema |
node definition + derived port analysis (enums, required, alternative input modes) | node_type+provider or node_id | before every connect or submission |
canvas_read_node_output |
newest job output for one node (async poll) | workflow_id, key | after submitting a generation |
canvas_submit_node_job |
submit ONE node as a job, quote-first | workflow_id, node_type, provider, config | running a single node |
canvas_run_workflow |
submit the whole board as one job, quote-first | workflow_id | "跑一下这个流程" |
canvas_generate_image |
submit a PAID gpt-image-2 image job | workflow_id, prompt, size? | "生成一张参考图" |
canvas_list_media |
the board's media pool entries (with index and referenced_by) |
workflow_id | checking what is available; resolving "第 3 张"; before deleting |
canvas_add_media |
add an upload-origin pool entry by URL | workflow_id, url, name | bringing an external image onto the board |
canvas_rename_media |
rename one pool entry (locked, wholesale pool replace) | workflow_id, entry_id, name | "把参考图改名为钟馗立绘" |
canvas_delete_media |
remove one pool entry (409 if referenced) | workflow_id, entry_id | "删掉池里第 2 张" (check referenced_by first) |
Node types you will meet: generate is the workhorse — script/LLM text
generation is generate:script (NOT process:script), media generation is
generate:minimax-h3 / generate:gpt-image-2 / ...; material is a
media-pool reference (pure data input, never executed). process exists for
edit/postprocess providers.
Single-node submission carries its own prompt (单节点提交自带提示词)
canvas_submit_node_job submits ONE node in node execution mode — the
platform does NOT merge upstream text into it. A generate node whose provider
needs a prompt (minimax-h3, gpt-image-2, ...) MUST carry the prompt itself:
write it into the node's config (prompt for video/image providers,
instruction for script) via canvas_write_node_config BEFORE submitting.
Wiring a script node upstream (depends_on) documents the flow but does
not inject its output — read the upstream script output with
canvas_read_node_output and put the distilled text into the consumer's
prompt config yourself.
Lock discipline (写锁纪律)
Every blueprint write (create_node / write_node_config / connect_ports)
is already wrapped by the runtime in the server-side lock protocol:
lock → read → modify → PUT → unlock, with finally semantics (a failed PUT
still unlocks — a crash can never strand a lock; a dead holder's lock is
taken over by the next applicant server-side).
If a write raises LockHeldError (画板正被占用):
- Stop. Tell the user the board is busy and who holds it (the error carries holder kind/id and since when).
- Do not retry in a loop. The holder is alive and working; your calls do not preempt it.
- Reads (
canvas_read_board,canvas_query_schema) still work — you can keep planning, just not writing.
Your own API calls refresh the lock heartbeat implicitly while you hold it — you never need to think about expiry.
Port matching iron rule (端口匹配铁律)
Before canvas_connect_ports, ALWAYS canvas_query_schema the TARGET
node. The schema is the judge of which ports may receive what:
- enum fields — e.g.
image_rolesaccepts exactlyreference_image/first_frame/last_frame; - required fields — what a submission will 400 without;
- alternative input modes — arrays that cannot be mixed.
Canonical case — minimax-h3. Its image inputs are exclusive:
first_frame and reference_image cannot coexist in one submission. Wiring
a reference image to first_frame when reference_image entries already
exist (or vice versa) is a 400 at submit time — expensive to discover
late. Query the schema, decide the port deliberately, then connect. Never
guess a port from the field name alone.
input_port is never silently dropped. A connect that passes
input_port with a NON-material source (a script or generate node) fails
with a structured error naming the source node — a plain depends_on edge
carries no port semantics, and a board that silently degrades the wiring is
worse than a refused one. If the error names a material node with no pool
reference, fix that node's config.pool_entry_id first, then connect.
Quote-first (先报价)
Paid submissions (canvas_submit_node_job, canvas_run_workflow,
canvas_generate_image) fetch an estimate before the submission exists.
Quote amounts are integer micro-USD plus a USD display figure. When the
estimate is material, state the USD figure to the user and get the go-ahead
— the wallet is charged on submit (held at the quote's upper bound, settled
at measured usage).
When the caller started the run with confirm_paid (the desktop and web
workbenches do), a material quote PAUSES the tool: the shell shows a
confirmation card (estimate + wallet balance + confirm/cancel) and the tool
blocks until the user answers. A decline (or a timeout) raises
PaidConfirmDeclined — nothing was charged; ask the user what to change
instead of resubmitting. In that mode you do NOT need to ask in conversation
first — the card IS the question.
Failure self-correction (失败自修正)
| failure | what to do |
|---|---|
| schema/validation 400 | read the structured error — the platform names the offending field and the allowed values. Fix that field, retry once. No blind retries, no fallback wrappers. |
| 409 workflow-modified | the runtime already retried once; canvas_read_board again before your next write — the board moved under you. |
LockHeldError |
report to the user, stop writing (see above). |
| 402 / 413 quota | report the number, do not retry. |
Media pool flow (参考图上板)
Generation is async and the pool is where artifacts land:
canvas_generate_imagesubmits only — a paid gpt-image-2 job.- Poll with
canvas_read_node_output(orbeehive_get_job) untilcompleted. - On completion the server auto-captures the image into the board's
media pool (
origin.kind=generated) — no add needed.
For an external image the user supplied by URL: canvas_add_media, then
make it wireable as a material node, then connect:
canvas_add_media(workflow_id, url, name) -> pool entry id
canvas_create_node(workflow_id, 'material', '', -> material node
config={pool_entry_id: <id>})
canvas_query_schema(node_type='generate', provider='minimax-h3')
canvas_connect_ports(workflow_id, from_key=<material key>,
to_key=<consumer key>, input_port='first_frame')
Material nodes are identified by config.pool_entry_id; the runtime wires
them into the consumer's material_deps and depends_on, and the server
compiles that to images[] + image_roles[] (or video_refs/audio_refs)
at submit time. The pool pointer is read leniently (pool_entry_id or the
entry_id alias), but ALWAYS write pool_entry_id — it is the field the
server compiles, and a lenient read that has to normalize your spelling
reports the drift on the action card.
Media pool lifecycle (池内资产管理)
The pool is the board's asset shelf — full lifecycle:
what is there:
canvas_list_mediareturns every entry with anindex(its 1-based position), render fields, andreferenced_by(the material node keys wiring it onto the board).input references ("用池里第 3 张"): list the media, resolve the ordinal to
entries[index-1], then wire it — create a material node pointing at that entry'sidand connect it to the consumer:canvas_list_media(workflow_id) -> entries[2] = {id: mp-3, kind: image, ...} canvas_create_node(workflow_id, 'material', '', config={pool_entry_id: 'mp-3'}) -> material node key canvas_connect_ports(workflow_id, from_key=<material key>, to_key=<consumer key>, input_port=<port from query_schema>)Never guess an entry id from a name — names collide; list first, match on index or exact id.
rename:
canvas_rename_media(workflow_id, entry_id, name)— locked write, the platform's designed pool-replacement path.delete:
canvas_delete_media(workflow_id, entry_id)— the platform refuses (409) an entry still referenced by a material node and names the referencing keys; offer to remove or rewire those nodes first. Alwayscanvas_list_mediaand checkreferenced_bybefore deleting.
Board delta awareness
Every successful canvas call lands an action row in the conversation with a
board_delta (added node, wired edge, pool entry, submitted job). The UI
renders these as cards the user can expand and click to locate on the board.
Keep your result summaries human-readable — the card's one-liner is what the
user reads first.