Macro Agent Harness SDK 错误类型详解:GetAgentSessionChangesPatchError 与变更 Patch 接口的错误契约
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 与错误体 |
两条容易踩坑的补充:
- 不要因为 404 就立刻
refresh。refresh需要Edit权限,只读共享者调用会直接拿到403;并且同一会话同一时刻只允许一次抓取,落在抓取过程中的请求会被折叠为一次重跑(crates/agent_changes/src/domain/service.rs)。先读摘要里的capturing/attempt字段更省事。 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 生成类型 共同构成了可验证的事实来源。