故障 → 恢复
映射表
书里有句话把这一章的价值说尽了:「错误处理的边界不是单次请求,而是整个恢复循环」。 这篇是那张表的中文化落地——四层故障,逐层回 pi 与 dsh 的源码核对。 结果比我预期的更分化:有一层做得比书里描述的还细,有一层是两个仓库共同的真空,还有一处是「两层重试策略不一致」—— 我自己第一次的判断就在那里被推翻了。
为什么值得单独做一张表
「故障恢复」是 harness 里唯一不能靠聪明设计绕过去的部分。上下文可以压缩,工具可以少给,唯独故障一定会来—— 每个厂商的限流文案不一样,每个 SDK 的超时语义不一样,每个模型的截断方式也不一样。
书把它拆成四层,因为四层的处理方式完全不同:
| 层 | 典型故障 | 正确处理方向 |
|---|---|---|
| API 层 | 限流 429、过载、超时、连接中断、输出触顶 | 与任务内容无关的噪声 → 可以重试,但要区分可重试与不可重试 |
| 工具层 | 幻觉调用、参数畸形、执行抛异常、同一个错误反复重试 | 不终止会话,把错误变成模型的输入,让它下一轮自己改 |
| 上下文层 | 窗口溢出、压缩失败、轨迹结构损坏(调用缺配对结果) | 识别 + 修复,且每条恢复路径都要有上限 |
| 控制流层 | 死循环、死亡螺旋(错误处理逻辑自己又调模型) | 检测模式(指纹 / 连续失败计数)+ 全局终止条件 |
出处:chapter5.md:178(四层故障分类学)。
四层总表:谁做了,谁没做
这一张是全文的索引。✅ 内建实现 ⚠️ 有但不完整或推给别人 ❌ 未发现实现。
| 层 | 书要求的能力 | pi | dsh | 判定 |
|---|---|---|---|---|
| API | 可重试 / 不可重试分类 | ✅ 两层正则表,先排除再匹配 | ✅ 5 个稳定错误码 | 都强,pi 更细 |
| 指数退避 | ✅ base × 2^(n-1) |
✅ 同式 | 平手 | |
| 随机抖动 | ⚠️ 两层不一致:SDK 层有,全量层没有 | ✅ 对称抖动 0.1(单层) | dsh 更一致 | |
| 尊重服务端 Retry-After | ⚠️ 仅 SDK 路径 + Copilot 分支 | ✅ 解析成 providerRetryAfterMs |
dsh 覆盖更全 | |
| 流静默看门狗 | ✅ 交给 undici 的 bodyTimeout |
✅ 自建 IdleWatchdog 原语 |
都有,dsh 更准 | |
| 工具 | 错误变成模型输入 | ✅ 三类错误统一成 isError 结果 |
✅ 同一模式 | 平手 |
| 调用 / 结果配对完整 | ✅ 截断时合成配对错误结果 | ⚠️ 只拒绝跨配对切分,已坏则抛错 | 取向相反 | |
| 参数畸形执行前修复 | ✅ prepareArguments 钩子,edit 做三类修复 |
⚠️ 仅 schema 校验 | pi 独有 | |
| 上下文 | 溢出识别 | ✅ 26 条正则 + 3 类情形 | ✅ 错误码 + 压缩单独发包 | pi 领先 |
| 压缩失败熔断 | ⚠️ 一次性标志(1 次即停) | ⚠️ 未发现计数器 | 都只是「有上限」 | |
| 静默溢出检测 | ✅ 用量 > 窗口、零输出触顶 | — | pi 独有 | |
| 控制流 | 重复调用指纹 | ❌ | ❌ | 共同真空 |
| 连续失败计数 | ❌ | ❌(重试计数只管单次请求) | 共同真空 | |
| 最大迭代轮数 | ❌ while (true) |
❌ | 共同真空 | |
| 死亡螺旋防护 | ⚠️ 无显式防护,但有重入抛错 | ⚠️ 未发现 | 都缺 |
这张表里 22 条证据全部逐行核对过,链接在下面各节。❌ 表示「在 packages/*/src 下未搜到实现」,不是「确定不存在于任何角落」。
API 层:pi 在「分类」上更细,dsh 在「退避」上更对
3.1 分类:两个仓库用了两种截然不同的方法
pi 面对的是二十多家厂商的文案差异,所以它的第一层是字符串分类器:先用一张「不可重试」表把订阅额度、账单耗尽这类错误挑出来, 再用一张「可重试」表匹配过载、限流、网络中断。顺序不能反—— retry.ts:266 的实现就是先判否定表,再判肯定表。
// 第一层:先排除「不该重试」的 const NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN = buildProviderErrorPattern([ "GoUsageLimitError", "insufficient_quota", "out of budget", ... ]); // 第二层:再匹配「值得重试」的 const RETRYABLE_PROVIDER_ERROR_PATTERN = buildProviderErrorPattern([ "overloaded", "rate.?limit", "(?<![a-z0-9])(?:429|500|502|503|504|520|524)(?![a-z0-9])", ... ]); export function isRetryableAssistantError(message) { if (NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN.test(errorMessage)) return false; return RETRYABLE_PROVIDER_ERROR_PATTERN.test(errorMessage); }
dsh 走另一条路:不匹配文案,而是在适配器里把 HTTP 状态翻译成稳定错误码,策略只看码。
码表很短,但语义干净:QUOTA / RATE_LIMIT / CONTEXT_WINDOW_EXCEEDED / INVALID_REQUEST / SERVER;
默认只有后四类里可恢复的进重试白名单,还加了一个 EMPTY_RESPONSE——模型返回空内容也算一次可重试的故障,这是个很细的活性判断。
证据: transport.ts:30-33(状态→错误码)、 retry-policy.ts:18(默认白名单)。
3.2 退避:pi 有两层重试,策略不一致
这是我在核对时最有收获、也是第一次判断被自己推翻的一条。
我先看到 agent 层的退避函数——注释写着 before jitter,函数体里却没有随机项:
export function retryDelayMs(policy, attempt): number {
const delay = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
const safeDelay = Number.isSafeInteger(delay) ? delay : Number.MAX_SAFE_INTEGER;
return Math.min(safeDelay, policy.maxAgentDelayMs ?? DEFAULT_MAX_AGENT_RETRY_DELAY_MS);
// ← 这一层没有抖动
}
但继续搜下去,另一个文件里有抖动、有 Retry-After、还能读服务端指令:
// 服务端可以显式指定要不要重试 const shouldRetry = error.headers?.get("x-should-retry"); if (shouldRetry === "true") return true; if (shouldRetry === "false") return false; // 服务端说等多久就等多久(超上限则直接失败,而不是干等) const retryAfterMs = error.headers?.get("retry-after-ms"); ... const exponentialDelay = Math.min(0.5 * 2 ** retryIndex, 8) * 1000; return exponentialDelay * (1 - Math.random() * 0.25); // ← 这一层有抖动
所以准确的结论不是「pi 忘了抖动」,而是:pi 有两层嵌套重试,好策略只覆盖少数 provider。
| 层 | 覆盖范围 | 退避策略 | 谁在控制 |
|---|---|---|---|
provider-retry.tsSDK 层 |
仅两个路径:openai-responses、openrouter-images |
0.5s 起、上限 8s,带抖动;尊重 retry-after / retry-after-ms / x-should-retry |
retry.provider.maxRetries(默认未设 → 0 次) |
retry.tsagent 层 |
全部 provider(兜底) | 2s 起、上限 60s,无抖动;不读 Retry-After | retry.maxRetries(默认 3 次) |
一个值得注意的设计细节:SDK 层遇到「服务端要求等 90 秒」时不会等,而是立刻抛错,理由是超时上限默认 60 秒——
注释写得很清楚:Provider-requested delays above maxRetryDelayMs fail immediately。
这是「宁可快速失败,不要静默干等」的取舍,和下面第 4 节 pi 的看门狗风格一致。
而 dsh 只有一层,但这一层是完备的:指数 + 对称抖动 + 尊重 Retry-After + 可持久化。
配置项就叫 jitterRatio:
function localDelay(config, retry, random): number {
const exponent = Math.min(retry - 1, 1024)
const exponential = Math.min(config.initialDelayMs * 2 ** exponent, config.maxDelayMs)
const jitter = 1 - config.jitterRatio + 2 * config.jitterRatio * random()
return Math.min(exponential * jitter, config.maxDelayMs)
}
为什么抖动这一项重要:书里说得很直白——没有抖动,大量客户端会在同一时刻同步重试,造成二次拥塞。 pi 的兜底层正是确定性的:所有实例在 t=2s、6s、14s 一起回来。而覆盖面更广的恰恰是没有抖动的那一层。
两层证据: retry.ts:142(agent 层无抖动)· provider-retry.ts:68(SDK 层有抖动)· :26(x-should-retry)
3.3 两套默认值放在一起
| 参数 | pi | dsh | 谁更保守 |
|---|---|---|---|
| 最大重试次数 | 3 次 | 5 次 | dsh 更耐心 |
| 初始延迟 | 2,000 ms | 500 ms | dsh 反应更快 |
| 单次延迟上限 | agent 层 60,000 ms / SDK 层 8,000 ms | 10,000 ms | pi 允许更长的等待 |
| 随机抖动 | 仅 SDK 层(±25%),agent 层无 | ±10%,单层全覆盖 | dsh 更一致 |
| 服务端 Retry-After | 仅 SDK 层 + Copilot OAuth | 全路径 | dsh |
| 服务端可否否决重试 | ✅ x-should-retry(SDK 层) | 未发现 | pi 独有 |
| 重试状态持久化 | 无 | 有——「每次排定的重试在等待前先落盘」 | dsh |
| 无限重试模式 | 无 | 有 mode: 'always' | 见第 07 节 |
pi 默认值: settings-defaults.ts:18-26; dsh 默认值: retry-policy.ts:14-17。
retry.provider.maxRetries 设成 3),
一次请求最多会发出 4 × 4 = 16 次尝试——而书里的原则是「每条恢复路径独立计数」,不是「叠起来算」。
默认值下 SDK 层是 0 次,所以平时不会碰到;但一旦有人为了「更稳」把它打开,就会得到这个放大效应。
活性:书点名的那个坑,两家都没踩
书里这段写得很具体:流式连接最危险的失败不是断开(断开立刻报错),而是静默卡死—— 连接建好了,数据不动了,像水管通着但不出水。而「SDK 的超时机制往往只覆盖初始连接而非传输过程」。 我原以为两个仓库都会中招,结果都没有,但用的办法不一样。
pi:把看门狗交给 HTTP 层
pi 没有在模型调用层做这件事,而是在进程启动时重配了 undici 的 dispatcher,把
headersTimeout 和 bodyTimeout 同时设成一个可配值,默认 5 分钟:
export const DEFAULT_HTTP_IDLE_TIMEOUT_MS = 300_000; // 5 min new undici.EnvHttpProxyAgent({ ... bodyTimeout: normalizedTimeoutMs, // 传输中途无数据 → 断 headersTimeout: normalizedTimeoutMs, })
bodyTimeout 的语义正好是「body 上没有新数据到达超过 N 毫秒就断」——这就是看门狗。
对外还给了五档:30 秒 / 1 分钟 / 2 分钟 / 5 分钟 / 关闭。
http-dispatcher.ts:91 · 档位表 :8-14
dsh:造了一个可重臂的原语
dsh 把它做成了一等公民:packages/util/timeout 里导出的 IdleWatchdog,
接口只有三个东西——signal、next(iterator)、pulse()。
pulse() 的注释解释了为什么需要它:
「有活动但没有值」正是流式响应的常态:心跳、空 delta、usage 块。粗暴的看门狗会把正常的慢响应误杀,
而「只在有值时才重置计时器」又会让心跳把卡死掩盖掉。pulse() 是这个两难的标准答案。
两个 provider 适配器都在用它,而且各自带了可区分的超时码:MESSAGES_IDLE、LLM_STREAM_IDLE_TIMEOUT——
出问题时日志里能直接看出是哪一层卡的。
timeout/index.ts:66(接口)· llm-pi-ai/adapter.ts:391(使用处)
上下文层:pi 这一块做得比书里描述的还狠
我原本预期这一层两家都薄。核对完发现 pi 的溢出识别是全项目最精细的一段代码,值得单独讲。
5.1 26 条正则 + 一张否定表 + 三类情形
packages/ai/src/utils/overflow.ts 里有一张 OVERFLOW_PATTERNS,
覆盖了 Anthropic、OpenAI、Google、xAI、Groq、OpenRouter、Together、llama.cpp、LM Studio、MiniMax、Kimi、Mistral、z.ai、DashScope、Bedrock、Copilot、Cerebras、Ollama……
每一条都带着真实报错原文当注释。
更关键的是它还有一张 NON_OVERFLOW_PATTERNS(
overflow.ts:80)。
注释说明了为什么必须有它:
这正是书里「先分类,再计数」的极致版:不是「匹配到就重试」,而是「先证明它不属于不该重试的那一类」。
而且它识别三种形态(overflow.ts:142):
| 形态 | 特征 | 为什么必须单独处理 |
|---|---|---|
| 报错式溢出 | 主流厂商:stopReason: "error" + 特定文案 | 最好处理,正则即可 |
| 静默溢出 | 请求成功返回,但 usage.input + cacheRead > contextWindow | z.ai 这类会接受超长请求,不报错——只看报错会永远发现不了 |
| 触顶式溢出 | 服务端把输入裁到刚好填满窗口,返回 length 且 output = 0 | 小米 MiMo 的行为;表现为「正常结束但一个字没说」 |
5.2 压缩熔断:一次机会,然后明确收手
书要求「每条恢复路径都要有明确上限」。pi 的做法是一个一次性标志 _overflowRecoveryAttempted:
溢出后压缩并重试一轮,如果又溢出,就不再尝试,直接给出可执行的建议——
if (this._overflowRecoveryAttempted) {
const errorMessage = contextOverflow
? "Context overflow recovery failed after one compact-and-retry attempt. "
+ "Try reducing context or switching to a larger-context model."
: "Truncated response recovery failed after one compact-and-retry attempt.";
这不是计数器,是个布尔量——阈值硬编码为 1。书里建议「阈值从生产数据来」,pi 这里的选择是「一次就够,因为第二次通常还是失败」。 考虑到压缩本身要花一次完整的模型调用,这个偏保守的取值是合理的。
agent-session.ts:2995-3078(三种触发情形与上限判断)
5.3 结构完整性:这里两家的哲学正好相反
书提到一个很具体的工程细节:发现工具调用缺少配对结果时,应当在注入上下文前自动修复配对。 而且它指出生产实现常有两种模式——产品模式宽容(用占位符补),训练模式严格(拒绝修复,怕污染数据)。
| 系统 | 遇到「调用没有结果」时 | 对应哪种模式 |
|---|---|---|
| pi | 输出被 token 上限截断时,为每一个工具调用合成一条错误结果,内容是「参数可能被截断,请带完整参数重新发起」 | 产品模式宽容——结构保住,模型被告知该重做 |
| dsh | 压缩选切点时用 toolPairingBalanced* 算平衡,不允许在未闭合的调用处切开;如果一个结果找不到前置调用,直接抛错 |
训练模式严格——结构坏了就报,不假装修好 |
这两个取向都能从各自的定位推出来:pi 是给人用的 CLI,卡住比脏一点更糟;dsh 的会话是可重放、可迁移的规范化日志, 悄悄补一条假结果会破坏「模型可见即已记录」这条不变量。
pi 的合成逻辑: agent-loop.ts:488-512; dsh 的平衡计算: tool-pairing.ts:112
工具层:这一层两家都做对了,而且做得很干净
书的要求只有一句:不终止会话,把错误变成模型的输入。pi 的实现把这句话拆成了三条路径的统一出口。
runToolCall 的文档注释自己就把契约写清楚了——
isError: true.isError: true 返回。三条路径分别是:
| 故障 | pi 的处理 | 模型看到什么 |
|---|---|---|
| 幻觉调用(工具不存在) | 直接生成错误结果 | Tool xxx not found → 下一轮换工具 |
| 参数不合 schema | 校验失败转为错误结果 | 带上约束提示的错误 |
| 执行抛异常 | 捕获后转为错误结果 | 异常文本 |
| 输出截断导致参数不全 | 批量合成「请重发」错误 | 明确告知「参数可能被截断」 |
agent-loop.ts:730(not found)· :818-820(契约注释)
prepareArguments 钩子(内核 types.ts:473,
在 agent-loop.ts:705 调用),edit 工具用它做了三类真实修复:
JSON 字符串 → 数组、单个对象 → 单元素数组、旧版 oldText/newText → edits[]。
注释还点名了触发方:Some models (Opus 4.6, GLM-5.1) send edits as a JSON string instead of an array.
所以这一格 pi 是 ✅ 而不是 ⚠️——而且是「有明确故障来源驱动的修复」,不是泛泛的容错。
控制流层:两个仓库共同的真空
这是全表唯一一片两边都空着的地方。书在这里提了三件东西,一个都没有: 重复调用指纹(工具名 + 参数算指纹,反复出现即无进展)、 连续失败计数(每条恢复路径独立的计数器)、 全局终止条件(最大迭代轮数、会话预算、升级人工)。
7.1 pi 的循环没有上限
主循环是字面意义上的 while (true),退出条件是「模型这一轮不再请求工具」:
while (true) { ... const toolCalls = message.content.filter((c) => c.type === "toolCall"); if (toolCalls.length > 0) { const executedToolBatch = ... await executeToolCalls(...); hasMoreToolCalls = !executedToolBatch.terminate; } // 没有 maxSteps / maxIterations / 预算判断 }
唯一的「终止」来自工具自己声明的 terminate。也就是说:如果模型坚持每次都调工具,这个循环不会自己停。
7.2 dsh 朝反方向走了一步
更值得注意的是 dsh 的重试策略里有一个 mode: 'always':
这不是疏忽,是明写的模式。它的合理性在于:dsh 的重试是 durable 的,且等待可取消,所以「无限重试」在一个可随时中断、重启后能续的宿主里是有意义的。 但它同时说明:「每条恢复路径都要有上限」这条原则,dsh 是选择性地不遵守的。
7.3 死亡螺旋:架构上留了口子
书讲的那个真实事故很具体:Agent 因上下文溢出而停止 → 触发「结束时自动提交代码」的钩子 → 钩子调模型生成 commit message → 又溢出 → 又触发钩子。 防护靠两条:在错误路径上禁用会再调模型的副作用逻辑,以及递归深度计数器。
| 系统 | 有没有这个口子 | 有没有防护 |
|---|---|---|
| pi | 有:扩展可以监听 agent_end,而扩展 API 能调 compact()、executeTool() |
无显式防护。不过 compact() 开头会 await this.abort(),且「Already compacted / Nothing to compact」会抛错——多数递归会撞死在错误上,而不是无限展开 |
| dsh | 同类口子在扩展层 | 未发现递归深度计数器 |
agent_end 事件定义:extensions/types.ts:972;
重入时的报错点:agent-session.ts:2829
7.4 为什么这不是「它们做得差」
同一个判断我在读书指南里已经写过一次,这里更硬:控制流上限是「宿主」的责任,不是「框架」的。
| 角色 | 谁该管死循环 | 理由 |
|---|---|---|
| 产品(Claude Code 类) | 自己管,且必须管 | 用户不会盯着看,成本与声誉都由产品承担 |
| 框架(pi / dsh) | 提供挂点,由宿主决定阈值 | 「多少轮算太多」是业务问题:批量重构和聊天机器人的答案不一样 |
pi 的 durable 包里其实承认了这一点——它的调度器注释里写着「计数可以交给 host,例如用于熔断」。
所以准确的说法不是「pi 没有熔断」,而是 「pi 把熔断的定义权交给了宿主,但没有给出一个开箱可用的实现」。
如果要补:最小改造清单
按「投入产出比」排序。前三条是真正的 bug 级缺口,后面是增强。
| # | 补什么 | 落在哪里 | 为什么值得 |
|---|---|---|---|
| 1 | 统一两层的退避策略 | pi:把 provider-retry.ts 的抖动与 Retry-After 下沉到 retry.ts(或反之合并成一层) |
覆盖面最广的那层(agent 层)没有抖动;而且两层同时开启时重试次数会相乘 |
| 2 | 重复调用指纹 | pi:agent-loop.ts 里对 toolName + args 算哈希,连续 N 次相同则注入一条「你可能在原地打转」的提示 |
书第一章的消融实验证明:这是最容易出现的无进展循环,而两个仓库都没有任何检测 |
| 3 | 可配的迭代上限 | pi:SETTINGS_DEFAULTS 加一个 maxSteps(默认 0 = 不限),在 while (true) 里判一次 |
不改变交互体验(默认不限),但让无人值守场景有一个开关 |
| 4 | 错误路径上的副作用隔离 | pi:在 agent_end 的溢出分支里跳过会调模型的钩子 |
堵住书里描述的那条死亡螺旋;改动小,风险低 |
| 5 | 压缩失败改成计数器 | pi:把 _overflowRecoveryAttempted 布尔量换成计数(阈值仍可为 1) |
让阈值可观测、可配置,也为将来放宽留出空间 |
| 6 | 看门狗加 pulse 语义 |
pi:现成的 undici bodyTimeout 不会区分「心跳」与「卡死」 | 只有跨长连接、跨代理的重度场景才需要,优先级最低 |
收束:这张表最终说明了什么
写完这张表,我对「harness 的成熟度」这件事的看法变了。
x-should-retry、带抖动;
agent 层什么都不读、不带抖动;Copilot OAuth 那条分支又自己实现了一遍 429 退避。
三处都对,但三处不一致——这正是为什么这类能力要靠一张表来对齐,而不是靠一次代码评审。
最后一句:能检测到「没有进展」比能处理「每一种错误」更重要。 错误是有限枚举的,没有进展是无限形态的——而两个仓库都还没有开始做这件事。