Rome Action 机制一次讲透:6 种执行结果状态与「暂停等人工审批」的底层设计

原创2026-10-26 21:07:571,898 阅读

Rome Action 机制一次讲透:6 种执行结果状态与「暂停等人工审批」的底层设计

Rome 是一个为递归 Agent 设计的开源 Agent 操作系统,也是 Grok Bot 与 Meta Muse 的开源替代品。本文聚焦 Rome 的 Action 机制:每个 Action 执行后只返回一种结果状态,共 6 种——ok、error、pending_approval、pending_interaction、handoff、place_widget。其中「暂停等人工审批」是敏感操作的最后一道安全闸,本文将一次讲透它的底层设计。

Rome Agent 操作系统概览界面

一、Action 是什么:Rome 里的最小执行单元

在 Rome 的概念模型里(见 docs/concepts/actions.md):

  • Skill 教 Agent「怎么做」,是一段加载进上下文的说明;
  • Action 才是真正跑起来的代码,属于某个 App、必须通过 manifest 声明才能被调用;
  • Hook 是事件订阅,最终也是路由到 Action。

关键设计在于:每个 Action 的产出都装进同一个「结果信封」(result envelope),信封里恰好携带一个状态。这封信封会穿越所有调用边界——Agent 工具调用结果、App 间调用、webhook 记录——全部长一个样。

该信封在 SDK 中被建模为一个带 status 字段的联合类型,定义于 packages/app-runtime-sdk/src/index.ts:

export type ActionResult<T = unknown> =
  | { status: "ok"; data?: T }
  | { status: "error"; error: string }
  | { status: "pending_approval"; approval: PendingApproval }
  | { status: "pending_interaction"; interaction: PendingInteraction }
  | { status: "handoff"; handoff: Handoff }
  | { status: "place_widget"; placement: PlaceWidget };

「单一状态、永不叠加标志位」是官方契约里反复强调的原则,这也是后文所有设计的地基。📦

二、6 种执行结果状态逐个拆解

官方契约见 docs/concepts/actions.md,按「是否让调用方继续跑」可分为三类。

1. ok —— 正常完成

Action 成功跑完,data 里是产物。Agent 拿到后直接继续下一轮推理。

2. error —— 业务层面的拒绝

注意一个容易混淆的点:error 状态是领域拒绝(domain rejection),是调用方能据此采取行动的正常结果,例如「routine 名字已被占用」。而基础设施故障——处理器崩溃、worker 进程挂掉——绝不会被包装成 error 结果,而是作为抛出的 invocation error 直接冒给调用方。失败永远不会伪装成一个「装着失败载荷的成功结果」。

3. pending_approval —— 暂停等人工审批 ⏸️

敏感 Action 在 guardian(守护人)拍板前一行代码都不会执行。Action 引擎返回此状态后,调用它的 Agent 被「挂起」,等待审批卡片被处理。这是全文主角,第三节展开。

4. pending_interaction —— 内联交互挂起

Action 已经跑过,它把调用方 Agent 挂起在一张内联交互卡上:App 自己的组件直接挂载在聊天里(例如 ask-user 应用的结构化提问卡片)。线程不会被锁死,同一时间可以挂起多张。

5. handoff —— 交接给子会话

把「话语权」移交给一个子会话:守护人在那里与被召唤的 Agent 协作。与内联交互不同,handoff 会锁住父聊天直到控制权归还。若声明了 handback 契约,候选产物必须先通过 schema 校验、再由守护人批准,才能驱动原调用方继续。

6. place_widget —— 放置工作区组件

把 App 的 web 组件「顺手」放到守护人的工作区(freegrid)上。它是火后即忘(fire-and-forget):不挂起任何东西,当前轮次直接算完成。适合放「看一眼就好」的只读视图,而不是收集输入。

💡 速记:ok/error/place_widget 不挂起;pending_approval 在执行前停车;pending_interaction/handoff 在执行后停车(统称 suspension,见 docs/concepts/actions.md)。

三、「暂停等人工审批」的底层设计

1. 审批闸门:执行前短路

Action 配置里有 requiresApproval 标记(见 packages/app-runtime-sdk/src/index.ts)。引擎在处理根调用时会短路:记录待审批记录、落一条 status: "pending_approval" 的执行记录,然后直接返回 pending_approval 结果,Action 本体根本不进入执行路径。这段逻辑位于 packages/core/src/actions/engine.ts。

Rome 网页端 webchat 界面:守护人在此审批 Action

2. 审批记录是持久化的,重启不丢

审批单由 packages/core/src/actions/approval-handler.ts 驱动,其核心契约:

  • 审批状态只有四种:pending、approved、rejected、auto_approved(见 packages/api-types/src/approvals.ts 中定义、packages/app-runtime-sdk/src/index.ts 导出);
  • 只有 guardian 能决策,拒绝意味着 Action 永远不执行(概念说明见 docs/concepts/messaging.md);
  • 关键一句:「An execution awaiting approval keeps waiting」——Rome 进程重启后,已完成的执行会记为错误,但等审批的执行继续等。审批单 + 回放日志(replay journal)让「暂停」成为可持久化的状态,而不是一段内存中的挂起。

3. 批准后如何「续跑」:原子认领 + 回放

守护人在 web 面板批准后,onApproved 流程分三步(见 packages/core/src/actions/approval-handler.ts):

  1. 原子认领:claimExecution 把执行状态从 queued 原子地置为 running,保证多 worker 下只有一个实例真正执行,杜绝重复扣款式的并发事故;
  2. 回放续跑:凭审批单里保存的 replayJournal 与根调用信息重放整条链路——已完成的步骤走回放缓存,被卡住的敏感调用则真正执行,不会重复创建审批单;
  3. 唤醒 Agent:执行结果被格式化成一轮新对话喂回原会话(formatResultForAgent),Agent 在同一上下文里继续,而不是从头再来。

若守护人拒绝,onRejected 则把「该 Action 已被拒绝」作为新一轮提示送回 Agent(packages/core/src/actions/approval-handler.ts)——拒绝不是错误,而是一等公民结果,Agent 会据此调整路线。

4. 嵌套调用的审批冒泡

如果敏感 Action 是作为嵌套调用触发的,pending_approval 会冒泡到根结果:无论审批请求在调用树的哪个位置产生,根调用方看到的信号一致(packages/core/src/actions/engine.ts)。同一轮里首次出现的待审批成为根级信号,后续审批各自建记录但不再重复打断。

四、审批 vs 挂起:两个「暂停」别混淆

维度 Approval(审批) Suspension(挂起)
时机 Action 执行前停车 Action 已执行后停车
守护人角色 授权者(approve / reject) 产物生产者(提供交互结果)
典型状态 pending_approval pending_interaction / handoff

此外别忘了 place_widget:它挂载组件但什么都不挂起,属于完成结果的副作用。官方在 docs/concepts/actions.md 中专门用「Not to be confused with」章节划清这些边界,这是理解 Rome Action 契约最快的入口。

五、总结:为什么这套设计值得借鉴

  1. 单一状态信封:6 种状态互斥,失败不会被伪装成成功,跨所有调用边界语义一致;
  2. error 只管业务,崩溃走异常:调用方永远能区分「可行动的拒绝」和「跑不动了」;
  3. 审批是一等状态而非锁:审批单持久化、可原子认领、重启后继续等,批准后靠回放日志精确续跑;
  4. 拒绝也是正常结果:Agent 被明确告知「被拒」并继续工作,而非收到一个模糊的错误。

对于想在 Agent 框架里加入人工审批的开发者,Rome 给出的答案可以浓缩为一句话:把「等待人」建模成结果状态,把「批准」建模成一次可回放的执行——而不是一个内存里的回调。

登录后查看全文
rome