画布操作手册

通过已启用的“画布操作”工具控制当前运行中的画布。工具仅在存在画布上下文时可用；缺少工具时，请用户打开目标项目的画布并确认工具已启用，不通过编辑画布 JSON 绕过工具。

操作流程

1. 调用 getCanvas({})，确认激活画布、可用节点类型、实际节点和连线。
2. 根据用户要求选择下面的操作，逐次等待返回。后续调用使用前一步返回的 ID，不猜测 ID、节点类型、端口或节点函数。
3. 需要调整节点内容时，从 nodeTools 清单读取该节点函数的描述和 parameters，通过 nodeTools 调用。
4. 完成结构调整后，按需调用 fitCanvas 展示结果，再用 getCanvas 核对目标节点、名称与连接。arrangeCanvas 已自动适配视口，不必重复调用 fitCanvas。只报告工具实际完成的操作。

故事或视频制作先读取 制作阶段与确认。默认只落实当前已确认阶段；先逐步收集信息，再展示阶段成果并询问调整，等用户明确继续。不因用户说“做一个短片”就一次创建全部分镜与生成节点，也不把提问失败、跳过或沉默当作确认。

默认从本次完整剧本生成角色、场景、道具资产，再拆为多镜头片段；一片段对应一份视频提示词和一个视频节点，资产直接用于多参生成。写资产提示词前读取 资产图规范，写视频提示词前读取 片段制作指南，角色面部特写与正侧背完整三视图不能省成通用单张剧情图。

文档内链接相对当前文件目录。跨技能的 script 规范按 available_skills 中实际 location 定位；依赖缺失时说明缺项，仅继续不依赖它的结构操作，不凭简介补造规范。

以下写法表示“工具名（参数对象）”。直接调用对应工具，不额外包一层 { name, args }；只有 nodeTools 自身含有 name 和 args 参数。

读取画布

getCanvas({}) 返回：

字段	用途
id	当前激活画布的 ID。
canvases	当前工作区画布列表，每项包含 id、name。切换时传 id，不是展示名称。
nodes	节点列表，含 id、type、position、data 等；显示名称通常为 data.label，端口定义在 data.handles。
edges	连线列表，含 id、source、sourceHandle、target、targetHandle。
viewport	视口的 x、y、zoom。
selectedNodeIds	当前选中的节点 ID。
availableNodeTypes	当前可添加的类型，每项为 { type, label }。创建时使用 type，不要传 label。
nodeTools	当前节点注册的函数，每项含 nodeId、name、nodeLabel、description、parameters。

工具描述附带的初始节点函数清单可能过期。节点新增、删除或画布切换后，以最新 getCanvas 或 addNode 返回的清单为准。

画布管理

工具	参数	行为与返回
addCanvas	{ name? }	创建空白画布并切换到它；省略名称时自动使用未占用的“画布N”。返回新激活画布的完整状态。
switchCanvas	{ canvasId }	等待当前修改保存后切换到指定画布，返回新激活画布的完整状态。
renameCanvas	{ canvasId?, name }	省略 ID 时重命名激活画布，同时修改 JSON 文件名。返回操作后的激活画布状态与更新后的 canvases。

名称去除首尾空白后为 1–120 个字符，不带 .json 扩展名，须为合法文件名；不能包含路径分隔符、文件名非法字符、控制字符，不能以点结尾或使用系统保留名。同名文件不会被覆盖。

画布 ID 与文件名关联，重命名后重新读取返回的 ID。重命名非激活画布不会切换过去。通过上述工具成功创建或切换画布后，本轮后续调用会作用于新的激活画布。

节点与连线

工具	参数	行为与返回
addNode	{ type, position: { x, y }, label? }	新增节点，返回 { node, nodeTools }。未指定名称时使用类型的 label。
moveNodes	{ moves: [{ nodeId, position: { x, y } }] }	批量移动，返回 nodes，每项含 node 与 nodeTools。不可拖动的节点会拒绝操作。
renameNodes	{ renames: [{ nodeId, label }] }	批量更新显示名称，返回 nodes，每项含 node 与 nodeTools。不改变节点 ID。
deleteNodes	{ nodeIds: [...] }	删除节点及其连接边，返回 { nodeIds, removedEdgeIds }。
connectNodes	{ connections: [{ source, sourceHandle, target, targetHandle }] }	批量连接输出与输入端口，返回 { edges }。完全相同的连接已存在时返回已有边。
deleteEdges	{ edgeIds: [...] }	删除指定连线，返回 edgeIds 及关联节点信息 nodes。
selectNodes	{ nodeIds: [...] }	替换当前选择，返回 { selectedNodeIds }；空数组取消节点选择。
arrangeCanvas	{}	整理整个当前画布：按真实节点尺寸与连线将顶层节点从左到右排列，子节点随父节点移动，并自动适配视口。返回 { arrangedNodeIds, viewport }；不改内容、连线或选择，不触发生成。
fitCanvas	{ nodeIds?: [...] }	调整视口，返回 { fitted, viewport }；省略 nodeIds 展示全部节点。

参数约束

• position 使用画布坐标，不是屏幕像素坐标；x、y 必须是有限数字。开启网格吸附时，新增和移动的位置会按网格取整，以返回的 node.position 为准。
• 节点 label 去除首尾空白后为 1–200 个字符。
• addNode 只接受当前 availableNodeTypes 中的类型，不接受任意 data 或自定义节点 ID。需要填写内容或设置节点参数时使用已注册的节点函数。
• 上述移动、重命名、删除、连接操作每批 1–64 项，单项也使用数组参数。任一项校验失败则整批不执行；执行期间的异常不代表已产生的副作用自动回滚，恢复前仍需回读。
• 工具顶层参数采用严格对象校验，不传未声明字段。nodeTools.args 还要满足具体节点函数的参数定义。
• 节点 ID、画布 ID、边 ID 是不同的标识，不用显示名称代替它们。

连接规则

先读取两端 data.handles，每个端口含 id、type、dataType，可能还有 label。source、target 是节点 ID；sourceHandle、targetHandle 是各自节点内的端口 ID。

• 只能从 type: "source" 的输出端口连接到 type: "target" 的输入端口。
• 使用实际端口 ID，不根据“图片输入”等提示文字猜测。不同节点可有同名端口，必须同时确认所属节点。
• 工具沿用画布和目标节点的连接校验；类型匹配不保证一定可连，目标节点可能有额外规则。连接被拒绝时检查最新端口和函数说明，不修改 JSON 强行接线。
• 剧本和分镜文本用于规划，不直接作为图片或视频生成节点的输入。先确认角色、场景等资产，再把当前片段的全部镜头转写成一份专用视频提示词；连线只承载本次真正使用的素材。
• 接好媒体后核对目标的实际引用顺序，再用 node:setPrompt 写入 {{ref N}}、素材名称和用途。连线成功不等于提示词已绑定素材，详细编号与配置核对见 制作转换第 3–4 节。
• 节点或连线禁止连接、选择、移动、删除时遵守返回错误。删除有子节点的节点须先删除子节点或将其纳入同一删除批次；若涉及用户未要求删除的内容，先明确范围，不自动扩大删除操作。

调用节点函数

使用 nodeTools({ nodeId, name, args })：

• nodeId 与 name 必须来自同一项函数清单；name 保留完整 node: 前缀。
• 按该项 parameters 的 JSON Schema 构造 args，遵守必填字段、枚举与数据结构；无参数函数也传 {}。
• 不假定所有节点都有同一组函数，例如设置提示词、导入素材、生成媒体等能力必须以该节点实际注册内容为准。
• 需要核对或修改生成配置时，若清单提供 node:getConfig，通过它读取当前配置和可用模型能力；需要变更的选项使用 node:setConfig 按实际参数说明修改，再核对返回结果。配置修改不触发生成；用户已确认的有效设置继续沿用，不因普通编辑任务重新选模型。
• 图片或视频生成前展示实际模型、对象与数量、规格、提示词、参考及费用，等待用户明确批准算力消耗方案；报价未知就说明未知。单张、小样、追加、重生成和可能收费的重试都受授权范围约束，具体批次可一次确认。使用可用的 askUser，没有该工具时文字提问等待答复；未回答不能触发生成。图片未指定模型时优先选择可用的 gpt-image，不能把节点自动默认值当成用户选择；不可用时先确认替代模型。
• 返回值由节点函数决定；无返回值时为 null。执行成功不自动代表媒体生成成功，须检查返回内容及最新节点状态。
• 新建节点后可立即使用 addNode 返回的 nodeTools，不必结束当前轮对话。

常见任务

把创作方案转成可执行画布

剧本、小说或创意制作任务需要把分镜、素材和提示词落实为节点时，读取 视频制作的画布转换。其中说明哪些内容放进文本节点、如何复用媒体和连接真实依赖，以及后台生成的完成核对。通用参数仍以本手册和当前工具返回的说明为准。

新建画布并添加节点

调用 addCanvas({ "name": "分镜草稿" })，从返回的 availableNodeTypes 选取符合用户要求的类型，传入 addNode 的 type。例如位置可用 { "x": 120, "y": 160 }；名称由用户意图决定。记录返回的 node.id，使用返回清单中的函数填写节点内容，最后调用 fitCanvas({})。

连接两个已有节点

调用 getCanvas({})，按用户指定的名称或选择状态定位两个节点；若同名节点无法区分，先明确目标。读取输出与输入端口后，将实际 ID 填入 connectNodes 的 connections 数组。检查返回 edges 的两端，再按需聚焦这两个节点。

批量整理节点

仅当用户明确要求整理整幅当前画布时，在确认目标后调用一次 arrangeCanvas({})，不自行计算所有节点坐标再逐个移动。此工具复用画布现有整理功能，不接受 nodeIds 或其他局部范围参数。

待整理节点尚未测量或不可移动时，工具明确返回错误；不要猜测尺寸或绕过移动限制。空画布正常返回空的 arrangedNodeIds，不执行布局或视口调整。

只整理指定镜头或局部节点时，读取实际位置与目标范围，用 moveNodes 的 moves 数组调整这些节点，按需用 fitCanvas({ "nodeIds": [...] }) 展示。只要求看清内容时直接用 fitCanvas，不重排节点。不得为了局部整理调用 arrangeCanvas 移动用户其他节点，也不删除或重建节点来代替移动。

失败后的处理

• 节点类型未启用、端口不存在、函数未注册：重新读取 getCanvas，以最新清单调整操作。不要猜测替代函数。
• 画布已关闭、用户手动切换项目或画布、本轮上下文失效：停止沿用旧 ID，请用户在目标画布重新发送请求。
• 超时、取消或保存失败不等于操作已回滚。上下文仍有效时先读取最新画布状态，确认是否已创建节点、连线或画布，再决定是否重试，避免重复创建或重复触发生成。
• 工具会等待需要保存的操作完成保存；不要另外直接写画布 JSON。当前工具不提供删除画布、任意写入节点数据或任意设置视口参数的通用接口。