RT-03-002 跨平台 Agent 对话与接入设计

2026-10-18 更新（ADR-0022）：Drama 已解除冻结并恢复开发，是 Runtime 的第二消费者，与 Studio 并行推进；Commerce 保持原型。下文涉及 Drama 的段落按现行计划理解。

2026-10-15用户进一步明确：OceanWay任何平台都应能够接入Agent对话入口，整体设计结合Higgsfield与Krea的Agent模式。 本页维护目标接入设计；核心/Artifact/Agent、薄SDK/最小固定流程已有实现，Studio双入口及非Studio宿主fixture沿 WP-RT-001收口，具名版本、合并、CI与未发布边界见 PROC-02-005。早期免费fixture、旧公开过程候选和既有单账号生产各保留回执，不互相覆盖。Studio首消费、Commerce原型、Drama冻结，后续真实平台动作仍逐项授权交付。

公共部分统一命名 OceanWay Runtime。其中的Agent会话与执行引擎可通过SDK、可选UI和产品适配器嵌入各处；直接工具、Workflow和Agent继续共用Job。完整权属见目标架构，任务与判定只在开发清单和验收维护。

本页的公开过程与人机交互遵循用户最新选择：简单明确的请求自动执行；复杂、缺少关键信息或涉及重要选择时先澄清；额外生成、显著扩大的范围或高消耗操作先呈现方案并确认。 这是创作意图与执行计划的确认，不改变 Platform 逐调用自动准入、唯一资金与原 Operation 规则，也不要求每次普通生成都重复批准。候选版本、待验事项及生产版本分栏记录在公开过程候选验收；不得把本页目标当作生产已经升级。

两个平台分别借鉴什么

以下区分已观察模式与OceanWay的设计推论；对标不等于已经知道竞品私有服务实现。

Higgsfield的逐次工具审批只在本样本具名分支观察到，不能转为OceanWay所有生成的额外确认。Krea的本次响应正文、完整ToolCall→Job→File关联及精确费用归因未闭合；不据此推断DAG、沙箱、数据库或微服务。来源与边界见运行对比和Higgsfield服务证据。

公开行动过程与交互策略

用户应能看到 Agent 正在做什么、执行到哪一步、需要补充什么，以及确认后会执行什么。公开过程使用专门的行动摘要和真实状态，不展示模型内部思维链、系统或 Skill 指令、供应响应、凭据和内部执行提示词；不能直接把原始模型响应转成“思考过程”。

公开阶段可包括“理解需求、准备方案、等待答复、正在生成、保存结果、加入产品候选、完成/失败/停止/暂停”。阶段由实际运行事实投影；多份输出必须按全部预期产物判断保存与交付，不能拿一份成功代表整批完成。生成、保存、候选送达与用户采纳仍分别表达。

“高消耗先确认”的现行候选机制由 Planner 策略识别，再通过专用持久审批屏障执行；Platform 尚无与该确认原子绑定的 quoted-price/budget 合同。不能声称已按财务金额硬阈值强制拦截、锁定报价或保证未来总消费；模型不得虚构费用。若以后增加财务硬阈值，须由 Platform 正式交付报价、价格/方案指纹、有效期和派发时原子校验，另行验收，不能以产品确认按钮代替。

Studio Host 对可确定的额外执行另有硬屏障：本 v2 原规划历史已出现成功图片生成观察后，再提出直接 generate_image 必须转为批准；数量参数 n/num_outputs/num_images/batch_size 大于 1 时也必须批准。这些依据已发生的原观察与实际数量，不是金额阈值。首次单图简单请求仍可自动执行。确认摘要补入 Host 从已验证输入生成的模型、尺寸/比例和数量公开行，不仅依赖模型描述；Platform 已发布价格可冻结投影给 Planner 辅助判断，但不是原子 quote 或财务授权。

中性 checkpoint 与宿主接线

人机交互属于独立 Runtime 的可复用合同。Runtime 0.4 的 interaction 决策区分澄清与批准，持久保存原 Run/step、交互身份、计划指纹、版本和服务端生成的命令身份；不以 Studio 对话、React 组件或产品数据库作为内核依赖。产品只增加受限 Host 适配和 renderer，后续消费者不能复制一套审批执行器。

澄清答案通过单独的 userDecisions 追加给下一次 Planner 请求，不冒充 Job 或 ToolObservation，也不修改原用户输入、冻结 context 或旧供应 envelope。批准方案的私有 proposedTool 只保存在不可变执行决策中；公开 AgentInteractionView 只含标题、摘要、问题、状态和稳定回执身份。批准与接受冻结工具在同一事务完成，同命令并发/丢回执重放只返回原回执；异意图同键、旧计划、旧版本、错误 scope 或终态新回答拒绝。

Host 负责当前本人会话、Origin、对象与产品归属，以及批准前的正式 Platform 授权核对；真正派发时仍独立重新准入。resume 恢复资源授权，answer/approve 记录用户决定，两者不能互相冒充。停止阻止后续新调用，已派发原单仍核对、保存和结算；停止前未回答的问题可保留历史事实，但终态界面不能再显示可执行的批准/回答控件。

Host 的公开 GET/SSE 读取使用中性的只读 reader，不为显示状态调用引擎 start/advance；产品可持久化白名单公开快照及其单调 revision。UI 的初次读取、历史恢复和事件都消费同一快照，迟到事件不得回退终态；PostgreSQL bigint 事件游标保持字符串，不能转成 JS number 充当公开 revision。Studio /create 是本切片接入面；Canvas、通用 SDK/Panel、其他消费者与独立服务各自过原 Gate，不因公开 DTO 或一个页面接入而完成。

一个运行时，多个对话入口

入口可以是完整工作区、右侧面板、抽屉或页面内嵌区域；同一产品可有多个入口。UI只负责输入、显示和正式命令，后台执行与产品领域写回有独立生命周期。关闭面板、换页面或网络断开，不重新派发原任务。

Runtime服务端核心不依赖Next.js或Studio页面；可选React组件用于现有前端，其他前端可只消费headless SDK。客户端包不包含数据库、调度器、模型供应凭据或服务Key。产品BFF在服务端绑定真实调用方和作用域，浏览器传来的surface ID只定位受控配置，不能选择任意产品凭据。

会话、运行与任务身份

同一合法scope内，完整工作区和侧栏可读取当前获准的同一Session/Thread；Session保留创建入口，当前surface/profile/toolset在每轮Run绑定。切换surface时重验目标入口、对象权限与上下文，产生新一轮快照；已有Run沿原快照继续。跨scope不自动复用。

Runtime是上述中性会话与执行记录的唯一Writer。产品保留自己的页面状态、领域对象、采纳记录及可重建的对话投影。迁移时旧Studio conversation/run/message保持原身份，通过版本化映射接入；不复制为另一套可再次派发的任务，不以抽离覆盖旧记录或原费用。

每个入口的最小接入合同

建议以服务端受控的AgentSurfaceDefinition连接界面与领域，实际schema归Runtime工程：

type AgentSurfaceDefinition = {
  id: string;
  revision: string;
  callerScopeRef: string;
  profileRef: string;
  contextResolverId: string;
  toolsetRef: string;
  resultSinkId: string;
  rendererSetRef: string;
  presentation: "panel" | "inline" | "workspace";
};

同进程阶段用受信处理器注册，独立服务阶段使用受限服务端API；不接受任意模块路径、脚本或回调URL。产品实现适配器，Runtime仅依赖协议，不反向import产品。领域写回和Runtime交付各用自己的事务/outbox，凭持久回执接续，不假设跨库事务。

共用对话组件需要支持的交互

• 当前上下文可见。 显示所在产品、当前项目/对象和用户选中的素材/选区；页面变化时明确显示新范围，已受理Run继续使用其冻结上下文。下一轮重新解析，不能静默拼接全站私密资料。
• 消息与工具过程。 显示公开回复、实际使用的工具、必要参数摘要、任务状态及可解释错误；内部提示词和隐藏推理不作为用户消息输出。
• 结构化交互。 问题、字段补充、候选选择和领域采纳由schema表达，保存decision ID与对象修订；用户刷新后可继续同一决定，重复提交不多写。已定义业务中的候选确认继续保留。
• 持续结果卡片。 工具受理后即可展示稳定Job；图片/视频在原卡片推进，保存或领域挂载失败有独立状态。再次进入工作台可读回原产物，不依赖Agent重复描述图片。
• 正式停止与继续。 UI调用当前Run的正式命令。停止阻止后续新调用，已派发媒体继续完成、结算与保存；资源不足暂停，补足后用户主动继续原Run。
• 持久历史与重连。 读取Session/Thread、活跃Run及其Job，按游标恢复事件；事件缺失时回读权威状态。未知提交只定位原运行，不把页面重载转为新一轮生成。

模型选择、附件、Skill及integration选择按该入口真实已验能力呈现；它们是可组合模块，不要求所有平台出现同一排控件。费用来自Platform原Operation，报价、用量和结算分开，未知不填零。沿OceanWay现行资源规则，不新增Run预算或所有媒体生成前的重复审批。

一轮Agent执行怎样推进

1. 产品服务端确认当前身份、正式调用方和surface配置；生成稳定clientRunId/消息命令ID，持久化受理关系。同ID不同意图拒绝。
2. Runtime定位或创建本scope的Session/Thread；冲突时读取原活跃Run。submit、steer、stop、continue分别是正式命令，不能用再次submit冒充恢复。
3. 按权限解析当前对象/附件与Skill，固定ContextSnapshot、Profile/工具策略版本及来源修订；Platform校验实际调用授权。
4. Agent做必要规划和能力发现，工具以明确schema派发共同Job；每个收费意图经Platform原Operation，固定供应输入与幂等身份。
5. 工具返回已受理Job时使用结果v2的accepted/awaiting_job，不能据此完成必需工具；Runtime已核验原Job和完整真实Artifact后才写saved observation，纯计算工具用completed。Studio现有v1继续沿原saved:true合同，本轮只加固检查点与恢复，不把受理改作保存。
6. Agent本轮公开输出可以结束；媒体Job按原状态继续。需要依赖结果的后续步骤在持久检查点等待，再读取原Artifact继续；无需等待的对话表现可先完成。
7. 结构化问题或人工选择持久等待；用户决定按原decision和目标修订继续。steer仅影响获准的后续规划，不能改写已派发或UNKNOWN的输入意图。
8. 结果先持久保存，再由ResultSink投递；产品按权限/修订采纳。刷新/重启恢复原Session、Run、Job和回执；领域服务不可用只积压交付，不重做模型。

固定参数工具仍可直接创建Job，固定Workflow仍可按已知依赖执行；嵌入Agent面板不使它们自动增加LLM步骤。

本轮Agent循环采用的成熟模式

以下是对公开设计的取舍，未引入OpenAI Agents SDK或LangGraph依赖，也不表示已还原Higgsfield/Krea私有后端。

Runtime每次advance最多跨一个Planner边界，接受工具后立即持久返回；未知Planner调用只recover原调用，恢复接口没有新派发方法。每个工具observation与原callId/输入/Job绑定，输入校验明确失败可供修正，数据库或适配器异常继续传播，不伪装成可安全重做的参数错误。需要Artifact的工具还会核实原Job全部输出与真实保存行，不能由回调自报saved绕过。

现有Studio v1已将批末一次写改为逐工具检查点，重启仅恢复未完成后缀；新工具前重读本地停止状态与Platform授权，已在途媒体仍恢复原操作。候选回执与采纳由产品负责。首期固定串行Workflow/人工checkpoint和双入口实现按WP-RT-001，实际版本与验证见当前首期记录；旧公开过程历史保留PROC-02-004。完整DAG、独立服务和后续入口不因首期实现而结项。

各平台怎样接入

以下为可选场景映射，不代表全部开始开发或已有正式动作授权。

现有产品Run合同仍主要面向studio/drama/commerce。Console/Admin/Site等新消费者须先在Platform正式定义合法调用方、作用域、模型/动作及委托合同；嵌入UI不会完成这项扩约，也不能借用studio产品身份。平台员工权限、内容权限和模型调用权限分别核验。

跨平台连续使用与数据边界

所有入口复用同一个Runtime能力，不意味着一个用户的所有平台聊天自动混在一起。默认Session/Thread按subject和产品/调用方作用域读取；上下文、工具集与输出目标由当前surface受控绑定。

需要把Studio产物带到Drama或Commerce时，走明确的对象交接：重验来源和目标权限，引用稳定资产/版本，创建目标上下文快照并记录来源。是否继续原Thread或建立关联Thread由正式会话合同决定；首期可以只支持后者。跨产品续接不凭同账号自动开放完整聊天、项目或素材。

先交付什么

首批证明“同一Runtime、两种入口”：Studio完整对话工作区与Canvas侧栏共享Session/Job/事件合同，使用各自上下文与工具集；再用非Studio消费者fixture验证没有Studio源码、会话或路由依赖。独立API/Worker按原切换协议交接，不要求所有产品同时上线。

随后选择一个领域消费者或Console/Admin具名场景验证SDK/Panel、身份范围、历史重载、结构化选择和业务写回。其他平台依相同合同增加Profile、上下文、工具与ResultSink，无需复制引擎。具体批次沿迁移顺序，UP-T10/14为主要接入工作包，授权扩约、原单恢复、事件和发布分别关联UP-T04/08/13/17。

核心验收包括：无Studio环境可构建/运行、同clientRunId不重复受理、冲突可定位原Run、跨surface权限正确、Agent流结束后Job继续、刷新读回原产物、问题/选择幂等、上下文逐轮重验、跨产品交接授权、领域回执重放不新增模型调用。验收正文见UP-AC01/02/05/09/12，文档发布不计作这些业务能力已完成。