Macro Agent Harness 会话评审决策接口:深入解析 DecideSessionReviewErrors 的 403 与 409

原创2026-10-31 20:38:321,936 阅读
文章标签:后端前端协同办公即时通讯企业应用CRMAI Agent人工智能

Macro Agent Harness 会话评审决策接口:深入解析 DecideSessionReviewErrors 的 403 与 409

DecideSessionReviewErrors 是 Macro Agent Harness OpenAPI 生成类型中一个看似精简、却直接决定客户端重试策略的类型:它为 POST /agent-sessions/{session_id}/reviews/{review_id} 明确声明了 403 与 409 两种失败语义。本文以该类型定义为骨架,结合 agent_code_mode crate 的服务端实现与 Macro TypeScript SDK 的调用封装,讲清“谁可以决策”“为什么会产生冲突”“冲突后如何安全恢复”,以及评审栈的容量与超时边界。

类型定义原文与上下文

该文档给出的定义极其紧凑:

type DecideSessionReviewErrors = {
  403: unknown;
  409: unknown;
};

它属于 packages/sdk-docs/reference/generated/agent-harness/types.gen 这一生成目录,是 OpenAPI 文档经类型生成器产出的产物,原始定义见 DecideSessionReviewErrors.md。同一接口族的相邻类型构成了完整契约:

类型 含义 文件
DecideSessionReviewData 请求结构:path{a session_id, review_id}、body: ReviewDecision、query?: never、url 字面量 DecideSessionReviewData.md
DecideSessionReviewErrors 错误响应:403、409 DecideSessionReviewErrors.md
DecideSessionReviewResponses 成功响应:200: ReviewRecord DecideSessionReviewResponses.md
DecideSessionReviewResponse 上述响应联合的索引别名 DecideSessionReviewResponse.md
ReviewDecision 三种决策分支:edit / submit / dismiss ReviewDecision.md
ReviewRecord 完整持久化记录(含 revision、items、decision) ReviewRecord.md

注意 503、500 并未出现在该类型中:生成器只为该 operation 显式声明的状态码建类型,DecideSessionReviewErrors 的“只有两个键”本身就是一份契约声明——客户端应当把这两类错误当作可预期的业务分支处理,而不是笼统的失败。

请求与响应的形状

DecideSessionReviewData 的 url 是字面量 "/agent-sessions/{session_id}/reviews/{review_id}",query? 被固定为 never,说明所有参数都在路径与 body 中。body 是判别联合(discriminated union),以 action 字段区分:

type ReviewDecision =
  | { action: 'edit';    revision: number; item: string; draft: unknown }
  | { action: 'submit';  revision: number; items: string[] }
  | { action: 'dismiss'; revision: number; items: string[] };

三个分支共享 revision,这是乐观并发控制(compare-and-swap)的令牌;items: [] 的语义是“选择全部 pending 项”,这一点在 ReviewDecision.md 中有明确描述。

服务端契约:OpenAPI 声明与错误映射

路由声明位于 axum_router.rs:

#[utoipa::path(post, path = "/agent-sessions/{session_id}/reviews/{review_id}",
    operation_id = "decide_session_review", params((...)),
    request_body = ReviewDecision,
    responses((status = 200, body = ReviewRecord), (status = 403), (status = 409)))]

这正是 DecideSessionReviewErrors 只有 403 和 409 两个键的源头。处理函数要求两重提取器:

  • AgentSessionAccessLevelExtractor<EditAccessLevel, ...>:调用方必须对目标 AgentSession 实体具备编辑级访问权;
  • MacroAuthorizationExtractor<Auth, UserOnly>:调用者身份必须是登录用户(bot 等非用户主体被排除)。

随后进入 CodeExecutionApiError 的统一映射(axum_router.rs):

领域错误 HTTP 状态 响应体
CodeModeError::Forbidden 403 forbidden
CodeModeError::NotFound 404 code execution not found
CodeModeError::Conflict 409 review changed; reload before acting
CodeModeError::Invalid(msg) 400 具体消息
其他 500 could not read code execution

一个值得注意的细节:NotFound 在 OpenAPI 注解里并未为决策接口声明(注解只列了 200/403/409),但实现层仍可能返回 404。由于 ReviewStore::get 使用 WHERE id = $1 AND agent_session_id = $2 查询,跨会话的评审 ID 只会表现为“查不到”,因此 404 实际承担了“该评审不属于这个会话”的语义。

403 Forbidden:授权失败的全部来源

403 的响应体是纯文本 forbidden,但这一个状态码背后至少有五个不同的判定点,全部集中在 reviews.rs 与决策入口:

  1. 会话已归档:owner() 在读取会话状态时,若 state.archived 为真即返回 Forbidden。
  2. 实体类型不是 AgentSession:session_id() 会对 EntityType::AgentSession 做严格校验,其他实体类型的访问凭据一律拒绝,即使 UUID 恰好可解析(reviews.rs)。
  3. 凭据主体与调用者不一致:authorize() 比较 access.acting_user_id() != Some(actor)。
  4. 评审归属账户与调用者不一致:decide_owned() 中 record_actor(&record) != actor 即拒绝。所谓 record_actor,是 record.acting_user,若为空则回退为会话所有者——因此历史记录(早于多账户评审的旧数据)按会话所有者校验。
  5. 聊天入口的额外约束:通过 decide_for_session(Agent 工具路径)决策时,还要求当前轮次由真实的用户提示驱动:prompter.kind == PrompterKind::User 且 prompter.user == actor。代码注释写得很直白:“A system event cannot approve itself.”——系统事件无法自我批准评审。

这解释了为什么 403 在客户端侧不可重试:它不是竞态,而是身份或生命周期问题。唯一的处理方式是提示用户检查权限、确认会话未归档,或者用正确的账户身份重新发起。

409 Conflict:修订号不匹配与状态不可决策

409 的语义在服务端被统一收敛为“review changed; reload before acting”。判定逻辑位于 reviews.rs:

if revision != record.revision
    || record.presented_at.is_none()
    || record.items.iter().any(|i| i.status == ReviewItemStatus::Submitting)
{
    return Err(CodeModeError::Conflict);
}

三个条件:

  • revision 过期:ReviewRecord.revision 是 compare-and-swap 版本号,每次保存自增(record.revision += 1)。客户端拿到的是旧快照,服务端已推进过版本。
  • 评审尚未被呈现:presented_at 为空意味着该评审尚未完成 presentation 写入,此时任何决策都视为非法(正常情况下 present 会先补齐)。
  • 仍有提交中的条目:任一条目处于 submitting,说明上一批动作仍在执行,禁止并发提交。

进入类型分支后还有两类冲突:

  • edit 指向的条目不存在或已非 pending:find(|e| e.id == item && e.status == Pending).ok_or(Conflict)?。
  • submit/dismiss 的 items 含非 pending 条目:只要有一个 ID 不满足 status == Pending 即冲突。

此外,存储层的乐观锁本身也会产生冲突:save 的 SQL 为 UPDATE ... WHERE id = $1 AND agent_session_id = $2 AND revision = $3,若 rows_affected() != 1 就返回 Conflict(outbound/reviews.rs)。所以即使同一进程内两次并发 submit,也只会有一个成功——测试 double_submit_claims_before_work_and_never_repeats_an_action 断言了“恰好一个成功、另一个 Conflict、动作只执行一次”。

为什么 409 必须“先刷新再重试”

如果对 409 直接原样重发(带着旧 revision),由于 revision 永远不会回到旧值,请求会持续 409。SDK 的实现正体现了这一点:review.ts 中的私有 decide() 每次都先 await this.detail.get() 读取当前 revision,再用 mutate 提交;而 submitAll() 的文档直接写着 “Never retries a conflict or ambiguous send.”(review.ts)。语义上,409 只是“你的视图过期了”,不是“请求有问题”。

决策链路:从 claim 到后台执行

理解 403/409 之后,才能正确解读 200 的含义。decide_owned 的执行顺序是:

  1. 读取并校验归属(可能 403);
  2. 校验 revision / presented / submitting(可能 409);
  3. edit 分支:校验草稿大小与结构,写入 draft、置 edited = true,检查所有条目草稿总字节数不超过 MAX_INPUT_BYTES(1 MiB),保存后立即返回,不执行任何动作;
  4. submit/dismiss 分支:把选中项状态改为 Submitting 或 Dismissed,写入 ReviewDecisionContext{by, via, revision, items},持久化并发出 NotificationEvent::ReviewDecided;
  5. tokio::spawn 后台执行:对 submit 逐项调用 actions.execute(),每项外层套 ACTION_TIMEOUT(60 秒)。成功则置 Completed 并记录 result;超时或失败则置 Unknown 并写入告警文案 “The submission outcome could not be confirmed. Check the destination before retrying.”。

因此 200 只代表“决策已被原子地认领”,不代表邮件已发出。响应体是当时的 ReviewRecord 快照(response = record.clone() 在 spawn 之前完成),后续状态需要轮询或依赖 review.settled 通知。这也是 409 中“仍有 submitting 条目”这一条件的必要性:它避免了客户端在动作飞行途中再次提交。

result 还有 8 KiB 的截断保护(MAX_RESULT_BYTES):超出时替换为 {"outputOmitted": true, "reason": "..."},避免把巨大的后端响应写进记录。

SDK 侧:如何正确调用 decideSessionReview

SessionReview 是对 ReviewRecord 的实体句柄,继承自 MacroEntity,详情记录惰性加载、任何变更后失效。核心调用如下:

import type { SessionReview } from './packages/sdk/src/entities/agent-sessions/review';

// 提交全部 pending 项(items: [] 表示“全选”)
await review.submitAll();

// 逐项操作
const items = await review.items();
await items[0].edit({ subject: '改后的主题', body: '...' });
await items[1].dismiss();

// 冲突后:先刷新,再重试
await review.refresh();
await review.submitAll();

refresh() 的实现是 this.detail.clear(); await this.detail.get();,配合 Lazy 缓存即可拿到新 revision。由于 items() 返回的 ReviewItem 句柄携带的是创建时的快照,在长时间停留的界面上,item.status 可能已过期;判断是否可提交应以 refresh() 后的记录为准。

对于“共享同一评审的多个入口”(卡片、聊天、收件箱),DecisionVia 枚举记录了来源:"card" | "chat" | "inbox"(DecisionVia.md)。该值会写入 ReviewDecisionContext.via,并参与通知去重键的构造:

dedupe_key: format!("{}:{}:{}", event.kind(), record.id.0, decision.revision)

也就是说,同一评审的同一决策版本只产生一条通知,重复的播报不会打扰用户。

状态机与错误处理速查

ReviewItemStatus 只有五个取值:pending | submitting | completed | dismissed | unknown(ReviewItemStatus.md)。据此可以写出对齐服务端语义的客户端分支:

客户端观察 建议动作
403 不重试。检查会话是否归档、当前登录账户是否等于 review.actingUser(为空时为会话所有者)、是否以用户而非系统事件/机器人身份发起
409 不原样重发。refresh() 后用新 revision 重试一次;若用户已无意操作则放弃
200 且条目为 submitting 等待 review.settled 或轮询至非 submitting,期间禁止再提交
条目为 unknown 去目标系统(邮箱已发件箱、日历)核实后再决定是否重发,切勿盲目重试
条目为 dismissed 终态,不可再提交

关于 unknown 的自动修复:refresh() 会扫描“updated_at 距今超过 STALE_SUBMISSION_MS(300000 ms,即 5 分钟)且仍有 submitting 条目”的记录,将其改写为 unknown 并附加提示 “Submission was interrupted; check the destination before retrying.”,同时补写一次 ReviewDecisionContext(针对没有决策上下文的旧记录)并发出 ReviewSettled 事件。这解决的是“副本被杀导致界面永远转圈”和“允许盲目重试”两个问题(reviews.rs)。

硬性边界:评审栈的容量与体积限制

DecideSessionReviewErrors 没写 400,但决策路径确实可能返回 400(CodeModeError::Invalid),主要来自草稿校验与体积上限。理解这些常量有助于解释为何某些“合法请求”会被拒(reviews.rs):

常量 值 作用
MAX_REVIEWS_PER_SESSION 100 单个会话的评审栈上限,创建时通过 SELECT ... FOR UPDATE 锁会话行后计数
MAX_DRAFT_BYTES 128 KiB 单条草稿序列化后的上限
MAX_RECORD_BYTES 2 MiB 整条 ReviewRecord 保存时的上限
MAX_INPUT_BYTES 1 MiB 创建请求体与“所有条目的草稿总和”的上限
STALE_SUBMISSION_MS 300000 submitting 被视为中断的阈值(5 分钟)
ACTION_TIMEOUT 60 s 单个条目执行动作的超时
MAX_RESULT_BYTES 8192 保存执行结果的上限,超出则省略

创建时还有形状约束:title 去空白后不能为空且长度 ≤ 256;drafts 数量必须在 1–100;kind == import 时必须恰好一条草稿。这些检查在 create_owned 中一次性完成(reviews.rs),edit 分支则复用 validate_draft 并重算总量。

权限模型小结:谁拥有评审

评审引入了“会话所有者”与“评审账户”两套身份。acting_user 是不可变字段(创建时写入 Some(actor)),后续所有动作都以它为准;而 present() 写会话 transcript 的能力属于会话所有者,因此呈现用所有者身份、动作用 acting_user 身份。这一分离使得“代表他人邮箱起草并发送”的场景既能在 UI 上呈现,又不会被代理身份越权执行。

create_for_session 与 decide_for_session 这一对“会话内工具入口”进一步限定:创建允许会话所有者或当前轮次的实际行动用户;决策则只允许真实用户提示驱动。这套规则让 Agent 可以“发起评审”,但不能“批准自己的评审”。

结语

DecideSessionReviewErrors 这个只有两行的类型别名,实际上是 Macro Agent Harness 会话评审机制的接口边界:403 编码了“身份、归属与生命周期”的静态约束,409 编码了“基于版本号的并发控制”的动态约束。把 403 当最终失败、把 409 当作“刷新令牌后重试”的信号,并牢记 200 只代表“认领成功”而非“动作完成”,就能在卡片、聊天与收件箱三种入口上实现一致且安全的决策行为。要深入细节,建议依次阅读 领域服务、PostgreSQL 存储、HTTP 路由 与 SDK 封装。

登录后查看全文
macro