分镜行操作 · BeefTV 文档

分镜行操作使用现有 /api/ops/:op 接口，由 MCP 和 CLI 共用。先用 canvas.get 读取画布版本、脚本节点和分镜行 ID，再提交写入。

操作	参数
`canvas.script.rows.append`	`rows`：追加 1–32 行；行 ID 和镜号由服务端生成
`canvas.script.row.update`	`patches`：1–32 个带 `rowId` 的局部修改；可用 `imageNodeId`、`videoNodeId` 绑定本行的图片和视频节点
`canvas.script.row.remove`	`rowIds`：删除 1–32 行；剩余镜号重新连续编号

三个操作都要求 canvasId、nodeId、expectedRevision 和写入操作 ID。目标节点必须为 script；版本过期、未知行或重复行 ID 会拒绝整批写入。用相同操作 ID 与原参数重试会返回原回执，不再次追加。回执包含画布 ID、新版本、节点 ID 和剩余行数。删除行会同时删除关联到该行的连线，保留生成的素材节点；回执列出删除的连线 ID，整轮撤销会一起恢复行与连线。

可修改剧情、台词、时长、景别、机位、镜头运动、图片与视频提示词等创作字段；角色和资产引用不在行级写入字段中。修改提示词时会清除该提示词原有的模板变量，避免后续生成仍使用旧模板。当分镜行已绑定 imageNodeId 或 videoNodeId 时，更新行的 imageGenerationPrompt 或 videoMotionPrompt 会自动同步对应绑定节点的生成草稿（保留历史已提交 prompt 与现有媒体成品）；若节点草稿已被单独修改为不同于原分镜提示词的内容，则不覆盖并在回执 skippedNodeIds 中列出，实际已同步的节点列在 syncedNodeIds 中。

canvas.script.row.update 的 imageNodeId 和 videoNodeId 把同一画布里已有的图片节点、视频节点登记为这一行的分镜图和镜头视频；分镜进度和成片合并按这两个绑定统计。省略字段表示不改，空字符串表示解除绑定；节点不存在、不在本画布或类型不符时整批拒绝，画布不变。绑定后，这一行每类产出只保留一条从该行连到绑定节点的连线（relation: storyboard-output）。改绑或解绑只删除这一行同类的旧产出连线，其他行、另一类产出和素材引用连线保持不变。回执的 createdEdgeIds 和 deletedEdgeIds 列出实际新增和删除的连线，整轮撤销会一起恢复行绑定和连线。

内置助手沿用只读、当前画布、完全访问三档权限。当前画布模式不能写其他画布；分镜改动记入节点摘要并支持整轮撤销。外部客户端沿用自己的审批流程，后端继续检查资源归属、参数、版本及幂等写入。

项目与素材库的常规增删改查继续使用 beeftv business discover 返回的业务接口，不需要新增第二套同义操作。资源上传由 CLI 读取本地文件并提交资源接口，后端不接受任意宿主文件路径。

分镜行时长为 1–60 秒；省略时默认 6 秒。行命令与手工界面的 canvas.document.commit 在后端共用时长、提示词模板失效和删除行连线检查。整文档提交若漏清旧模板、已删除行的连线或未重排镜号会拒绝保存，避免回执确认的内容与提交文档不一致。

/api/ops 描述中的 assistantModes 和 replay 由 Go 操作注册定义生成，官方 Pi 宿主直接使用；缺少分类的工具默认不暴露、不可安全重放。分类只负责发现与重放声明，资源归属、当前画布限制、CAS 和幂等仍由后端执行层校验。外部 MCP/CLI 和手工调用继续使用同一操作入口。