Canvas 跨产品交接

本文是跨产品链路在 Canvas 侧的详细适配规范。通用 Handoff 字段、Run、钱包、MCP 和领域事件仍以对应主规范为准；本文重点定义用户在“进入 Canvas、继续创作、返回来源产品”时看到什么，以及 Canvas 可以写什么。

已确认原则

• AI 漫剧与电商工作台目标上是独立产品，不是 Canvas 的子页面。
• 产品之间传递 Handoff 与 Context Package，不复制完整聊天记录或共享私有数据库。
• “在 Canvas 中打开”固定来源资源版本，Canvas 编辑只产生派生版本。
• 目标 Agent 创建新的 Run，权限和预算在目标上下文重新计算。
• returnBinding 描述允许返回的位置和数据契约，不代表自动写回授权。
• 结果默认是候选；只有用户明确接收后，来源产品才能更新自己的业务槽位。
• Console 提供全局导航、资源和任务治理；普通页面跳转本身不等于 Handoff。

当前态

当前 oceanway-vozeb 中，Canvas 与漫剧同仓库运行，已有部分 Canvas / Drama 跳转、项目摘要和媒体引用能力。现有链路仍带有页面路由、可变快照或媒体 URL 绑定的实现痕迹，尚未完整具备：

• 通用 Organization / Workspace / Project Context；
• 固定 CanvasRevision 与来源资源 Revision；
• 独立、幂等的 Handoff 身份；
• 结构化 Context Package；
• 目标 Run 与来源 Run 的明确区分；
• 可验证的 returnBinding 和冲突处理；
• 漫剧、电商独立部署后的服务边界。

因此，同仓库内部跳转是迁移基线，不是最终互通契约。

目标态

每个产品保留自己的 Host、专业 Agent、领域聚合和审核流程，通过共享 Handoff Service、Resource Registry、Asset Service 与 Run Service 协作。Canvas 只接收已授权的固定版本和最小上下文，只返回新的候选资源；来源产品继续拥有最终写回决定。

来源产品领域对象 + 固定 Revision
→ Handoff + Context Package
→ CanvasDocument / CanvasRevision + ResourceBinding
→ 目标 Agent Run
→ 候选 AssetVersion / CanvasRevision
→ 用户确认 returnBinding
→ 来源产品校验并写回自己的聚合

页面跳转、运行执行和领域写回由三个独立契约完成，因此将漫剧或电商迁移到独立部署时，不需要改变用户看到的交接语义。

三种不同动作

用户界面必须区分以下行为：

“在 Canvas 中打开”“交给漫剧”“用于商品内容”等文案表示交接；“查看资产”“打开任务”“进入 Console”只是导航。不得把一次普通跳转包装成后台自动生成或扣费。

Canvas 侧 Handoff 解释

通用契约由跨产品主规范定义，Canvas 至少使用下列语义：

Handoff 只授予完成这次目标所需的最小范围。目标产品不能因为用户能访问同一 Workspace，就自动读取该 Workspace 的全部 Canvas、资产或 Connection。

Context Package

Context Package 是目标 Agent 可消费的最小业务上下文，建议按以下类别组织：

用户可见目标
当前 Organization / Workspace / Project
固定输入资源版本
Canvas 当前选区或来源产品业务槽位
明确的创作与合规约束
请求的输出 Schema
允许的模型、工具和外发范围摘要
预算与审批策略引用
returnBinding

它不能包含：

• 完整聊天历史和无关会话消息；
• 平台基础提示词、模型选择理由或内部路由策略；
• API Key、MCP Token、Provider Credential 或长期签名 URL；
• 未被用户选择或未获授权的 Workspace 资源；
• 用于绕过目标产品审核状态的隐藏指令。

目标 Run 根据当前用户权限、Agent Revision、Workspace / Project 授权、Tool Grant、数据外发策略和预算重新计算有效权限。Context Package 不能提升权限。

“在 Canvas 中打开”

来源产品进入 Canvas 的目标流程：

进入前确认

确认界面至少展示：

• 将进入的产品和目标动作；
• 来源 Organization、Workspace、Project 与资源名称；
• 将带入的资源数量和固定版本；
• 产物归属与付款主体；
• 预估费用或需要审批的预算条件；
• 完成后可以返回的来源槽位。

同 Organization 且用户已经显式发起的低风险打开可以使用紧凑确认；跨 Organization、复制所有权、外发数据或产生高费用时必须使用完整确认。

Canvas 中的来源提示

无限画布编辑器应持续显示可收起的来源信息：来源产品、来源业务对象、固定版本、目标和返回入口。用户升级 Binding、改变输出规格或扩大工具范围时，需要重新确认并形成新 Revision；不能悄悄改变既有 Handoff。

完成与返回

Canvas 生成的输出先成为候选 AssetVersion 或 CanvasRevision。用户选择“发送回漫剧”“用于商品主图”等动作后：

1. Canvas 校验输出符合 requestedOutputSchema。
2. Handoff Service 校验 returnBinding、当前权限和来源版本。
3. 来源产品展示候选与版本差异。
4. 用户在来源产品执行接收、替换、提交审核或发布等领域动作。
5. 来源产品写入自己的聚合，并记录新的 Binding 与审计事件。

Canvas 永远不直接更新 Shot.storyboardAssetId、SKU 主图、Campaign 发布状态或其他产品正式字段。

从 Canvas 交给专业工作台

从 Canvas 发起的交接使用相同契约：

• CanvasRevision 和用户选中的节点固定为输入；
• 目标产品必须由用户选择，不能根据节点类型静默推断并执行；
• 目标产品创建或选择自己的领域对象，例如 DramaProject / Shot 或 CommerceCampaign；
• 目标产品 Agent 创建新的 Run，不沿用 Canvas Run 的临时权限；
• 结果进入目标产品候选区；需要返回 Canvas 时创建新的输出 Binding 和 Revision。

即使迁移期两个产品位于同一进程，也必须通过领域服务接口执行，禁止直接写对方数据库表。

漫剧端到端场景

场景：镜头分镜进入 Canvas 精修，再返回 Shot。

1. 用户在漫剧工作台选择一个 Shot 和当前已审核的剧本、角色、场景版本。
2. 漫剧创建 Handoff，inputResourceVersions 固定这些版本，returnBinding 指向该 Shot 的分镜候选槽位。
3. Canvas 新建或打开当前共享 Project 下的 CanvasDocument，并用 Binding 引用输入版本。
4. 用户在 Canvas 调用 Agent 生成多份分镜；每份成功结果都登记为 AssetVersion。
5. 用户选择一个或多个候选发送回漫剧。
6. 漫剧检测 Shot、剧本或角色基线是否已变化；未冲突时接收为候选，有冲突时要求比较、重新绑定或重新生成。
7. 用户在漫剧审核流程中选定正式版本。Canvas 无权直接把 Shot 标记为已审核或已完成。

验收重点：刷新或切换 Host 后仍能恢复 Handoff；多结果不丢失；返回不覆盖已审核版本；费用能通过同一 traceId 还原。

电商端到端场景

场景：SKU 资料进入 Canvas 生成主图与短视频，再返回 Campaign。

1. 用户在电商工作台选择 SKU、商品图、卖点和品牌规范，并选择目标 Campaign。
2. 电商创建 Handoff，固定商品资料版本、渠道尺寸与版权约束，returnBinding 指向 Campaign 的内容候选区。
3. Canvas 展示来源和约束，图片、视频作为统一 Agent 的创作模式完成生成。
4. 输出登记为带 derived_from 血缘的 AssetVersion；Canvas 不保存外部渠道凭据。
5. 用户发送候选回电商，电商校验 SKU 状态、渠道规格和当前 Campaign Revision。
6. 用户在电商工作台选择主版本并发起渠道审核或 MCP 发布；外部发布不会由 Canvas 自动触发。

验收重点：商品正式图不被自动替换；品牌与渠道约束可追溯；MCP Credential 不进入 Context Package；取消 Canvas Run 不改变 SKU 或 Campaign。

状态、重试与幂等

Canvas 体验至少区分：待接收、已接收、处理中、候选就绪、待来源接收、已返回、失败、已取消和已过期。具体持久化状态枚举由通用 Handoff 契约统一，产品不得各自定义互不兼容的同义状态。

规则：

• 创建 Handoff 和写回都使用幂等键；双击、刷新或回跳不能重复创建 Document、Run 或产品 Binding。
• 目标 Run 失败后重试产生新 Attempt，仍归属原 Handoff。
• 用户关闭浏览器不取消 Run；可从 Canvas 当前任务或 Console 全局任务中心恢复。
• Handoff 取消后停止尚未开始的步骤并释放预占，已登记的候选资产按保留策略处理。
• 外部发布或其他不可逆动作状态未知时进入对账，禁止自动重复执行。
• Handoff 过期只撤销继续处理权限，不删除已经形成的审计、账本和合法资产记录。

版本冲突

返回前必须比较创建 Handoff 时固定的来源 Revision 与来源产品当前 Revision：

任何冲突处理都不能通过“最后写入获胜”覆盖产品正式状态。

Console 与 Canvas 的协作

Console 负责：

• 查看跨产品 Handoff、Run、费用和审批摘要；
• 切换 Organization / Workspace / Project；
• 管理钱包、预算、成员、资产授权和 Connection；
• 深链接回 Canvas 的 Document、Revision、Run 或来源节点。

Canvas 负责：

• 展示当前画布相关的交接和运行；
• 组织选区与 Context Package；
• 执行创作、呈现候选和触发明确返回；
• 在原位置恢复用户的创作上下文。

Console 的任务中心是读模型，不接管 Handoff、Run 或 Canvas 状态；Canvas 也不复制 Console 的全局管理页面。

安全与审计

• 每次打开 Handoff、读取 Binding 和写回都重新验证 Membership 与资源权限。
• Handoff 记录发起人、确认人、来源与目标版本、预算策略、审批和 traceId。
• Agent 只得到短期 Run Principal；Model Gateway 和 MCP Gateway 不接收用户 Session。
• Context Package、事件和浏览器状态中禁止出现 Secret 与长期签名 URL。
• 分享 Canvas 不自动分享来源产品权限；接收者无权读取的节点只显示受限状态。
• 跨组织交接必须采用授权引用、复制或转让，不得仅修改 organizationId。

目标态验收

• 漫剧和电商可以独立部署，仍通过同一 Handoff 契约与 Canvas 双向协作。
• “在 Canvas 中打开”固定来源 Revision，并在 Canvas 中建立可追溯 ResourceBinding。
• 用户在确认前能看见目标产品、输入版本、产物归属、付款主体和返回位置。
• Context Package 只包含最小业务上下文，不携带完整聊天、内部提示、Credential 或无关资产。
• 每个目标 Agent 执行创建独立 Run，并重新计算权限、Tool Grant、预算与数据外发策略。
• 目标结果先成为候选，Canvas 不能直接修改 Shot、SKU、Campaign 或外部发布状态。
• 返回遇到来源版本变化时能阻止覆盖并提供差异、重新绑定或新建 Handoff 路径。
• 刷新、重复点击、失败重试和跨站回跳不会重复生成、写回或扣款。
• Console 能聚合任务和治理信息，但所有状态变更仍由 Handoff、Run 和产品领域服务完成。
• 从任一结果可以用稳定 ID 和 traceId 还原来源、输入版本、Run、Asset、写回、费用与审计链。

延伸阅读

• OceanWay Studio
• OceanWay Studio 信息架构
• Canvas 资源模型
• 跨产品链路
• 模型、Agent 与 MCP
• 统一客户控制台