Macro Agent Harness SDK 错误类型详解:GetAgentSessionChangesPatchError 与变更 Patch 接口的错误契约

原创2026-10-31 11:39:321,908 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

Macro Agent Harness SDK 错误类型详解:GetAgentSessionChangesPatchError 与变更 Patch 接口的错误契约

GetAgentSessionChangesPatchError 是 Macro Agent Harness TypeScript SDK 中 GET /agent-sessions/{session_id}/changes/patch 接口的错误联合类型。它会告诉你:当请求一个 Agent 会话的 unified diff 失败时,客户端能拿到什么、错误码分别意味着什么、以及为什么仅凭类型无法区分四种失败。本文从这条类型别名出发,串起路由挂载、鉴权提取器、领域错误映射与 patch 存储预算,给出一套可落地的错误处理方案。

类型定义:一个被 keyof 摊平的字符串联合

关联文档给出的定义本身只有一行:

type GetAgentSessionChangesPatchError =
  GetAgentSessionChangesPatchErrors[keyof GetAgentSessionChangesPatchErrors];

它依赖同一目录下的 GetAgentSessionChangesPatchErrors(见 GetAgentSessionChangesPatchErrors.md),那里明确列出了四个分支:

属性 类型 含义(结合服务端实现)
401 string 调用方未通过身份/授权校验
403 string 已识别身份,但对该会话的变更没有 View 权限
404 string 会话存在但没有可用 changeset,或 patch 已丢失
500 string 摘要表或 blob 存储访问失败

在生成的 types.gen.ts 中可以看到完整的上下文:

export type GetAgentSessionChangesPatchErrors = {
    401: string;
    403: string;
    404: string;
    500: string;
};

export type GetAgentSessionChangesPatchError = GetAgentSessionChangesPatchErrors[keyof GetAgentSessionChangesPatchErrors];

export type GetAgentSessionChangesPatchResponses = {
    200: AgentSessionChangesPatchResponse;
};

关键推论一:四个分支都是 string,keyof 之后联合类型会塌缩为 string。 这意味着在 TypeScript 里对 error 做 switch 或类型收窄没有任何区分能力,唯一可靠的判别依据是 HTTP 状态码(即 SDK 返回结果中的 response.status),而不是错误体本身。这也是这类 OpenAPI 生成类型的常见陷阱:错误体只有一种结构时,类型系统帮不上忙。

关键推论二:错误体不是同一种格式。 从 crates/agent_changes/src/inbound/axum_router.rs 的错误映射可以确认,403/404/500 由领域错误直接返回纯文本,例如 "forbidden"、"no changes have been captured for this session yet";而 401 由鉴权提取器返回,并包成 JSON,形如 {"message": "..."}(见 crates/entity_access/src/inbound/axum_extractors.rs)。因此解析错误体时必须先看 Content-Type,或直接按状态码分支处理,不要对 401 的 JSON.parse 结果做无条件假设。

调用链:这条错误从哪一层冒出来

理解错误语义最快的路径,是把一次请求从头走一遍。

路由挂载

agent_changes_router 以相对路径注册三条路由(/{session_id}/changes、/{session_id}/changes/patch、/{session_id}/changes/refresh),随后被合并进 agent_sessions 路由,并整体 nest 到 /agent-sessions 前缀下(见 crates/agent_changes/src/inbound/axum_router.rs 与 services/agent_harness_service/src/api.rs)。所以 SDK 生成的 URL /agent-sessions/{session_id}/changes/patch 与服务端注册路径一一对应。

鉴权先于业务

handler 的第一个参数是 AgentSessionAccessLevelExtractor<ViewAccessLevel, Access, Auth>。也就是说,读取 patch 只需要 View 权限,与读取变更摘要同级;而触发一次新抓取(POST .../changes/refresh)才需要 Edit 权限。模块文档也明确写了这一层级关系(axum_router.rs)。

这带来一个实用结论:如果你收到 403,说明权限门槛是 View 而不是 Edit,重试或改用写接口都无济于事,应该去修正共享权限。

领域错误到 HTTP 状态的映射

handler 调用 state.service.patch(...),返回 ChangesError,再由 AgentChangesApiError 的 IntoResponse 翻译成状态码(axum_router.rs):

Self::Domain(ChangesError::Forbidden) => (StatusCode::FORBIDDEN, "forbidden"),
Self::Domain(error @ (ChangesError::NoChangeset | ChangesError::PatchMissing)) =>
    (StatusCode::NOT_FOUND, error.to_string()),
Self::Domain(error) => (StatusCode::INTERNAL_SERVER_ERROR, "internal error"),

对应的错误枚举定义在 crates/agent_changes/src/domain/error.rs:Forbidden、NoChangeset、PatchMissing、Session(AgentSessionError)、Storage(rootcause::Report)。测试 errors_answer_with_the_status_the_pane_branches_on(crates/agent_changes/src/inbound/axum_router/test.rs)直接断言了 403、404、500 三种映射,可作为该契约的回归证据。

注意 Session(AgentSessionError::Forbidden) 被单独提升为 403,而不是落到默认的 500——这意味着“会话本身不可读”和“存储挂了”在客户端看来是不同的失败,前者不该重试。

404 的两种含义,决定了不同的客户端策略

read_patch 的实现(crates/agent_changes/src/domain/service.rs)把 404 拆成了两个阶段:

let location = self.inner.repo
    .patch_location(session).await
    .map_err(ChangesError::Storage)?
    .ok_or(ChangesError::NoChangeset)?;
let patch = match location {
    PatchLocation::Blob(key) => self.inner.blobs.get_patch(&key).await,
    PatchLocation::PullRequest(changeset) => { /* 从 pull request 取 diff */ }
};
patch.map_err(ChangesError::Storage)?
     .ok_or(ChangesError::PatchMissing)
  • NoChangeset:摘要行里根本没有 patch 位置。典型场景是会话刚创建、还没有跑完一轮对话,或抓取一直未成功。错误文案为 no changes have been captured for this session yet。
  • PatchMissing:摘要行指向一个 blob,但 blob 存储里已经不存在该对象。错误文案为 the stored patch for this changeset is missing。

由于 HTTP 层把两者都压成 404,客户端只能通过错误体文案区分。实践建议是:把文案当作展示信息而非控制流分支,统一按“当前没有可展示的 patch”处理,然后引导用户调用 POST /agent-sessions/{session_id}/changes/refresh(需要 Edit 权限,返回 202 与当前状态)重新抓取,或先读 /changes 摘要判断 capturing 是否为 true。

patch 可能被裁剪:truncated 与错误无关,但会影响下游逻辑

即使请求成功拿到 200 与 { patch: string },也不代表 diff 是完整的。抓取阶段会经过一次预算裁剪(crates/agent_changes/src/domain/service.rs):

  • 单个文件超过 MAX_FILE_PATCH_BYTES = 1 MiB 时,其 hunks 会被整体省略;
  • 整个 patch 超过 MAX_PATCH_BYTES = 6 MiB 时,按 patch 顺序保留文件直到触顶;
  • 常量定义见 crates/git_patch/src/patch.rs,被省略的文件会在摘要里置位 patch_omitted,changeset 上置位 truncated。

这解释了一个容易被误判为 bug 的现象:/changes 摘要有 N 个文件,而 /changes/patch 返回的文本里少了某个大文件。这属于设计行为,truncated 字段就是给 UI 提示“此处不完整”用的,不会产生 4xx/5xx。

另外,patch 的来源有两种:一是会话自己的 blob(PatchLocation::Blob),二是引用的 GitHub pull request changeset(PatchLocation::PullRequest)。后者走 extractor.pull_request_patch,如果上游 PR 变得不可用,这条路径同样可能返回 None,最终仍然映射为 404 PatchMissing。所以“404 偶尔出现又自己好了”往往对应 PR 侧状态波动,而不是存储损坏。

在 TypeScript 中消费这个错误类型

SDK 由 @hey-api/openapi-ts 生成,Sdk 类上对应的方法是 getAgentSessionChangesPatch(packages/sdk/generated/agent-harness/sdk.gen.ts):

public getAgentSessionChangesPatch<ThrowOnError extends boolean = false>(
  options: Options<GetAgentSessionChangesPatchData, ThrowOnError>
): RequestResult<
  GetAgentSessionChangesPatchResponses,
  GetAgentSessionChangesPatchErrors,
  ThrowOnError
> {
  return (options.client ?? this.client).get({ 
    url: '/agent-sessions/{session_id}/changes/patch', 
    ...options 
  });
}

请求参数类型由 GetAgentSessionChangesPatchData 规定:无 body、无 query,只有 path.session_id,url 固定为模板字符串(见 GetAgentSessionChangesPatchData.md)。

一个基于生成类型编写的调用与分支示例(默认 ThrowOnError = false,错误从返回值读取):

import { Sdk } from './generated/agent-harness';
import { client } from './generated/agent-harness/client.gen';

// client 由 createClient(createConfig<ClientOptions>()) 创建,只要求 baseUrl
client.setConfig({ baseUrl: 'https://api.example.com' });

const sdk = new Sdk({ client });

const { data, error, response } = await sdk.getAgentSessionChangesPatch({
  path: { session_id: sessionId },
  headers: { Authorization: `Bearer ${token}` },
});

if (response.status === 200) {
  return data!.patch; // AgentSessionChangesPatchResponse: { patch: string }
}

// error 的类型是 string,无法靠类型区分 401/403/404/500,
// 必须用状态码分支;且各分支错误体格式不同(401 是 JSON,其余是纯文本)。
switch (response.status) {
  case 401:
    throw new Error('需要重新登录');
  case 403:
    throw new Error('没有查看该会话变更的权限(需 View)');
  case 404:
    // NoChangeset 或 PatchMissing:先看摘要再决定是否 refresh
    return null;
  case 500:
    // Storage 失败,可按退避策略重试
    throw new Error(`变更服务暂不可用: ${error}`);
  default:
    throw new Error(`未预期的状态码: ${response.status}`);
}

若需要“错误即异常”的风格,可把泛型参数显式设为 true:

const result = await sdk.getAgentSessionChangesPatch<true>({
  path: { session_id: sessionId },
});

此时失败会抛出错误值,成功路径上 result.data 直接可用。请按团队习惯统一一种风格,避免同一模块里两种语义混用。

错误处理与重试矩阵

把上面的证据合起来,可以得到一张明确的操作指引:

状态码 触发层 是否重试 建议动作
401 鉴权提取器 否 刷新 token / 重新登录
403 ChangesError::Forbidden 或会话级 Forbidden 否 检查会话共享权限,需 View
404 NoChangeset / PatchMissing 有条件 先读 /changes;若 capturing 为真则等待,否则带 Edit 权限调用 /changes/refresh
500 Storage(摘要表或 blob 存储) 是 指数退避重试,且记录 response.status 与错误体

两条容易踩坑的补充:

  1. 不要因为 404 就立刻 refresh。 refresh 需要 Edit 权限,只读共享者调用会直接拿到 403;并且同一会话同一时刻只允许一次抓取,落在抓取过程中的请求会被折叠为一次重跑(crates/agent_changes/src/domain/service.rs)。先读摘要里的 capturing / attempt 字段更省事。
  2. attempt.outcome 是排查 404 的关键线索。 CaptureOutcomeDto 取值为 captured / not_ready / failed;当它是 not_ready 且带 error 说明时,多数情况是关联的 pull request 还没就绪,此时 refresh 往往很快就能成功。

可观测性:如何把错误定位到具体环节

patch handler 上带有 tracing::instrument,span 字段为 agent.session.id,并以 err(Debug) 记录错误(axum_router.rs)。抓取侧还有 agent.changes.capture span 与 capturing session changes failed 告警日志,成功时输出文件数、增删行数与 truncated 标志。

排查顺序建议为:先按 agent.session.id 过滤日志,确认最近一次抓取的 outcome;再确认 patch_location 落在 blob 还是 pull request;最后才看存储侧是否报错。这条顺序与 read_patch 的代码路径一致,能避免在错误的一层反复排查。

小结

GetAgentSessionChangesPatchError 表面上只是一个三行的类型别名,但它背后是一套明确的分层契约:鉴权提取器负责 401,权限与实体校验产生 403,领域层的 NoChangeset / PatchMissing 合并为 404,存储故障统一为 500。由于四个分支在 TypeScript 中都会塌缩成 string,正确做法始终是以 HTTP 状态码驱动分支、以错误体做展示、以 /changes 摘要和 refresh 接口处理可恢复的“无变更”状态。围绕这一点,错误枚举、读取实现、路由映射 与 SDK 生成类型 共同构成了可验证的事实来源。

登录后查看全文
macro