失败、重试与恢复
对一次失败请求的三种不同回应——重试它、修复上下文后重试一次、或者停下来——以及把它们区分开来的那些设置与事件。
provider 返回 529 overloaded。Pi 等了两秒,然后再试一次。又试了两次。然后它停下来,告诉你模型不可用。
这是正确的——而它是 Pi 所处理的失败里最不有意思的那一种。对一次失败的请求有三种回应,它们不可互换,而选错了那一种,就会让智能体去重试一个永远不可能成功的请求。
三种回应,三种含义
**重试。**失败是暂时的。请求本身没问题;有问题的是服务器。重复它。
**恢复。**这个请求按原样永远不可能成功,但一个不同的请求会成功。上下文溢出是典型情形:提示词太长,所以缩小上下文,发送一个不同的提示词。
**停下。**请求本身是错的,或者这个条件是永久性的。重试只会产生同样的失败。
Pi 严格分开的那些机制,以及每一个做些什么:
flowchart TD
F["一个请求失败了"] --> T{"暂时的:过载、限流、5xx"}
T -->|是| R["重复它:auto_retry_start"]
R -->|成功| OK["运行继续"]
R -->|尝试次数用尽| S["停下:auto_retry_end,success 为 false"]
T -->|否| O{"上下文溢出,或 stopReason 为 length"}
O -->|是| C["压缩一次,然后一次全新的运行:compaction_end,willRetry 为 true"]
C -->|压缩调用失败| Z["summarization_retry_scheduled"]
O -->|否| X{"它在哪里失败"}
X -->|tool execute| E["模型能读到的错误结果"]
X -->|tool_call 处理器| B["工具被作为保护性措施挡下"]
X -->|都不是| S
三个形似重试的机制,分属三个不同的事件族,外加第四种情况——那里对的答案根本不是重试。系统里没有任何东西替你在前两者之间做选择,而这正是本章末尾那个分类步骤值得仔细写的原因。
重试
rpc-commands.md 界定了范围:“启用或禁用针对暂时性错误(过载、限流、5xx)的自动重试。“三个类别,全都意味着稍后再试一次。
{"type": "set_auto_retry", "enabled": true}
{"type": "abort_retry"}
第二条命令——“中止一次正在进行中的重试(取消延迟并停止重试)"——之所以存在,是因为两次尝试之间的延迟是指数增长的,最长可达一分钟。retry.maxAgentDelayMs 默认为 60000。
智能体级别的设置:
| 设置 | 默认值 | 说明 |
|---|---|---|
retry.enabled |
true |
为暂时性失败启用智能体级别的自动重试。 |
retry.maxRetries |
3 |
智能体级别的最大重试次数。 |
retry.baseDelayMs |
2000 |
初始的指数退避延迟,单位为毫秒。 |
retry.maxAgentDelayMs |
60000 |
智能体级别的最大重试延迟,单位为毫秒。 |
以及单独的一层 provider 级别设置:
| 设置 | 默认值 | 说明 |
|---|---|---|
retry.provider.timeoutMs |
httpIdleTimeoutMs |
provider 请求的超时时间,单位为毫秒。 |
retry.provider.maxRetries |
0 |
provider 级别的重试次数。 |
retry.provider.maxRetryDelayMs |
60000 |
服务器所请求延迟的最大值,单位为毫秒。 |
注意 retry.provider.maxRetries 的默认值是 0,而文档用的是一条警告、而不是一条理由来解释为什么:“除非确实需要 provider 级别的重试,否则请把 retry.provider.maxRetries 保持在 0。provider 级别的重试会延迟 Pi 自己去处理配额与用量限制错误。”
这就是整套设计哲学,一句话说完。provider 库内部的一次重试对 Pi 是不可见的,所以 Pi 无法判定一个配额错误应该停下而不是重复。两层重试叠在一起,意味着外层失去它的判断力。
超时紧挨着重试,因为挂起是一次没有错误消息的失败。httpIdleTimeoutMs 默认为 300000,而"设为 0 即禁用。"websocketConnectTimeoutMs 默认为 15000。关掉超时并不会禁用重试;它意味着一个死掉的连接现在看起来像一个慢连接。
恢复
恢复是一套不同的机制,有不同的触发条件,还有一个硬性上限。
compaction.md:“一次 provider 的上下文溢出错误,或一个提前出现的最终 stopReason: "length",可以选择使用一次压缩并重试的恢复尝试。”
一次尝试。上下文溢出错误意味着请求超出了窗口——原封不动地再发一次,会再次溢出。唯一的出路是一个更小的请求。
顺序是要紧的,而它被一步一步地规定清楚:
持久化最终的助手响应
→ extension/public turn_end
→ extension/public agent_end
→ 为被选中的那次尝试追加 context_edit 的省略项
→ 对于 overflow/length:运行 session_before_compact,成功时追加 compaction
→ 把重试作为一次全新的运行启动
有三点要注意。那次失败的尝试仍然可见——turn_end 和 agent_end 照常为它触发,而"原始转录记录历史、导出、计费总额,以及历史搜索扩展仍能检查那次被省略的尝试。“恢复修复的是模型上下文,不是记录。第二,那些省略是 context_edit 条目,所以它们是分支相对的、仅追加的:原始条目留在原处,它们只是不再到达模型。第三,那次重试是"一次全新的运行。“不是一次续接。
当恢复不起作用时:“如果恢复用的压缩失败或被取消,Pi 会保留那些省略编辑,不追加压缩,也不安排内部重试。“省略保留着,没有压缩,没有重试——会话以一个修复过但没有摘要的投影结束,而那次失败对你是可见的。
agent_before_settle “看到的是恢复处理之后的那个修复过的投影。“所以一个在落定时检查上下文的扩展,看到的是重试将会发送的内容,而不是失败的内容。
把这些区分开来的事件
json.md 给每一种都分了一个独立的事件族。这就是你不看转录记录也能判断 Pi 在做什么的方式。
重试:
{"type":"auto_retry_start","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"529 overloaded"}
{"type":"auto_retry_end","success":true,"attempt":2}
“在最终失败时,auto_retry_end 带有 success: false 和一个 finalError 字符串。”
摘要重试是独立的一族,针对的是压缩调用本身:
{"type":"summarization_retry_scheduled","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"terminated"}
{"type":"summarization_retry_attempt_start","source":"compaction","reason":"threshold"}
{"type":"summarization_retry_finished"}
“对于一次分支摘要,source 是 "branchSummary",而 reason 不存在。压缩重试上的 reason 是 "manual"、"threshold" 或 "overflow"。”
压缩与恢复,其中 reason 是 "manual"、"threshold" 或 "overflow"——而 overflow 就是那个告诉你一次恢复正在进行中的值:
{"type":"compaction_start","reason":"threshold"}
{
"type": "compaction_end",
"reason": "overflow",
"result": {
"summary": "...",
"firstKeptEntryId": "abc123",
"tokensBefore": 150000,
"estimatedTokensAfter": 32000
},
"aborted": false,
"willRetry": true
}
“一次成功的溢出恢复会在 Pi 重试该提示词之前把 willRetry 设为 true。“如果压缩被中止了,result 不存在,且 aborted 为 true。如果它失败了,result 不存在,aborted 为 false,而 errorMessage 描述这次失败。
所以:auto_retry_start 意味着重复。带着 reason: "overflow" 的 compaction_start 和带着 willRetry: true 的 compaction_end 意味着修复。带着 success: false 的 auto_retry_end 意味着放弃。
这个分类是从哪来的
对于一个自定义 provider,custom-provider.md 对那条你绝不能越过的边界说得很明确:“在已识别的上下文溢出错误之后,Pi 可以压缩并重试。如果该服务用的是一条未知的消息,就在一个加了防护的 message_end 处理器里,只把那一个 provider 的溢出响应归一化成 context_length_exceeded。“然后同样坚决地:“不要把限流或暂时的 provider 失败改写为上下文溢出。那些失败改用 Pi 的普通重试行为。”
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
// For a provider whose context-overflow message Pi does not recognise: rewrite
// only that provider's overflow response, and nothing else, so Pi's own
// compact-and-retry recovery can run.
export default function (pi: ExtensionAPI) {
pi.on("message_end", async (event) => {
const msg = event.message;
if (msg.role !== "assistant") return;
if (msg.stopReason !== "error") return;
if (!msg.errorMessage?.includes("model is too long")) return;
return {
message: { ...msg, errorMessage: "context_length_exceeded" },
};
});
}
那个处理器返回 { message },而不是消息本身:结果类型是 MessageEndEventResult,它唯一的那个字段替换掉已最终确定的消息,并且必须保持其角色。本章的第一稿直接返回了 { ...msg, errorMessage }。那样编译不过,而如果没有编译器,它会被静默忽略:溢出永远不会被归一化,而 Pi 永远不会恢复。
它在 examples/ch29-failures/ 里被运行过,对手是一个会以 model is too long for this context 失败的脚本化 provider,运行在一个启用了压缩的会话里:
- 带着那个处理器,事件是带着
reason: "overflow"的compaction_start,然后是compaction_end,然后是产生了答案的第二次运行。那次失败的尝试通过一条context_edit条目从上下文中被省略,而不是被删除,并且追加了一条compaction条目:正是上面恢复一节所描述的那个顺序,已观察; - 没有那个处理器,同样的消息只是一次失败。没有尝试压缩,因为 Pi 没有识别出它;
- 在处理器存在的情况下,一条仅仅包含 length 这个词的限流消息被原样放过。
这是整个系统里后果最重大的一个分类。一个方向上弄错,Pi 会在失败前把一个不可能的请求重试三次。另一个方向上弄错,Pi 会因为一条限流消息恰好包含 “length” 这个词而静默压缩你的对话。
扩展内部的失败
重试机器只与模型请求有关。工具失败和处理器失败遵循不同的规则,而 extensions.md 划出了界线:
“Pi 会报告处理器错误,并在可能的地方继续。一次 tool_call 处理器失败会把工具作为一道保护性措施挡下;一次工具执行失败会变成给模型的一个错误结果。”
两个不同的目的地,而这个区别是关于执行的,不是关于模型是否看到某个东西。一个返回 { block: true } 的 tool_call 处理器会阻止工具运行——execute() 永远不运行,所以没有真实效果可报告。但循环仍然为这次调用发出一个工具结果,带着 isError: true 和你的 reason,而那个结果确实作为数据到达模型。第 16 章和第 39 章都描述了这一点:一次被挡下的调用作为一个模型能读到并据以回应的错误结果回来。被阻止的是工具;被传达的是拒绝。一次工具执行失败从模型那一侧看行为相同,而"从 execute() 抛出以产生一个失败的工具结果"是有文档记载的故意失败方式。对于那些即使结果已经带着数据、你也想传递的状态:“返回带 isError: true 的结果,而不是抛出:模型看到一个错误,而脚本仍然收到 structuredContent。”
Shell 命令是第三种情况。rpc-commands.md 记录了 bash 上的 excludeFromContext:“当命令输出应当被存进会话、但在下一个提示词里从模型上下文中省略时,把 excludeFromContext 设为 true。“一个没有人需要再看一遍的构建日志不是一次失败,但它是同一种形状的决策——把它挡在模型读的东西之外。
失败之后的清理
extensions.md:“即使在正常操作已经尝试过清理的情况下,也要在 session_shutdown 里释放资源。保持清理幂等,因为取消、重载、会话替换和进程退出可能汇聚到同一条路径上。”
四种不同的结束方式,一个清理函数。幂等是要求,不是整洁。
而"用 ctx.shutdown() 请求一次有序的进程关闭。“这就是停下与崩溃之间的区别——一次失败之后,一次干净的关闭会运行你的清理,而 kill 不会。
配置它
一个合理的起点,理由都摆在明面上:
{
"retry": {
"enabled": true,
"maxRetries": 3,
"baseDelayMs": 2000,
"maxAgentDelayMs": 60000,
"provider": {
"timeoutMs": 300000,
"maxRetries": 0,
"maxRetryDelayMs": 60000
}
},
"httpIdleTimeoutMs": 300000,
"transport": "auto"
}
编码进这里的是四个决定。智能体级别重试开启,因为那三个暂时的类别确实是暂时的。provider 级别重试关掉,理由有文档记载。超时设为有限值,好让一个死掉的连接变成一个错误、而不是一段等待。transport——"auto"、"sse"、"websocket" 或 "websocket-cached",默认 "auto"——值得为一个长时间运行的会话显式设置,因为一个重连良好的传输和一个重连不佳的传输,会产生非常不同的重试体验。
当重试是错误答案时
如果一个请求确定性地失败——一个错误的 API 密钥、一个未知的模型、一个格式不对的端点——三次重试花掉你一分钟,什么也不改变。对一个你已经诊断出来的配置错误,用 enabled: false 的 set_auto_retry、或 retry.enabled: false,是对的回应。models.md 的故障排除一节是同一个想法的散文版:“确认它的 provider 有可用的认证,“以及"在 models.json 里检查它的 API 类型和兼容性设置。上游服务器必须支持相应的请求字段和行为。“那些没有一样会因为再试一次而变好。
它的形状
每一个失败都由按顺序提出的四个问题之一来回答:它是暂时的吗,如果是,就带着退避重试。它是确定的但可修复的吗,如果是,就压缩并重试一次。它是确定的且 Pi 修不好的吗,如果是,就停下来并报告。它是在一个工具或一个处理器内部失败的吗,如果是,答案就不是重试,而是一个模型能够据以推理的错误结果。
第三部分到此结束。你已经有了运行循环、重定向它的队列、回退它的树、它携带的消息、存储它们的文件、比它们活得更久的指令,以及终结它的那些失败路径。这些没有一个能告诉你,刚才在你的扩展里行为异常的是哪一个——那是另一个问题,一个机械的问题。