← Pi Agents

失败、重试与恢复

对一次失败请求的三种不同回应——重试它、修复上下文后重试一次、或者停下来——以及把它们区分开来的那些设置与事件。

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 修不好的吗,如果是,就停下来并报告。它是在一个工具或一个处理器内部失败的吗,如果是,答案就不是重试,而是一个模型能够据以推理的错误结果。

第三部分到此结束。你已经有了运行循环、重定向它的队列、回退它的树、它携带的消息、存储它们的文件、比它们活得更久的指令,以及终结它的那些失败路径。这些没有一个能告诉你,刚才在你的扩展里行为异常的是哪一个——那是另一个问题,一个机械的问题。