Pi Agent Core 实战（10/10）：循环上线之后

极简框架把复杂度从框架搬到了你身上。循环本身只有 1445 行，它不替你做日志、不替你做预算、不替你做回滚、不替你做评测。它只保证一件事：模型做了什么、失败了什么，都变成事件发出来。剩下的账，得自己付。

20 条失败用例覆盖四类：调用不存在的工具、参数不合 schema、工具抛异常、工具超时。每条独立跑一次完整循环，统计失败信号是否送达模型、循环是否崩溃。

框架能保证的：失败一定被说出来

20 条用例，四类失败各 5 条。结果很干净：20 条全部产生了明确的错误结果，带 isError 标记和可读原因；循环零崩溃，每次都能继续或正常收尾。

四类的处理路径不一样。工具不存在时，循环直接生成「Tool xxx not found」的结果，不让模型空等；参数不合 schema 时，校验在执行前失败，工具根本没被调用；工具抛异常时，异常被捕获成错误结果；超时同理。

这个一致性是设计出来的，不是碰巧。它意味着模型永远知道「刚才那步为什么没成」，而不是收到一个空结果或者一个被吞掉的异常。上一代系统最缺的就是这一层。

失败类型	用例数	信号送达	错误信息平均长度
工具不存在	5	5	74 字符
参数不合 schema	5	5	90 字符
工具抛异常	5	5	77 字符
工具超时	5	5	88 字符

四类失败各 5 条，全部把错误如实送给模型，循环没有一次崩溃。

注意：但「信号送达」不等于「问题解决」。框架保证模型看见错误，不保证它看见之后能改对。实测里能跑通是因为策略是脚本化的、确定会换策略；真实模型可能在同一处反复试，这时候需要的是预算闸门和人工接管，不是更多的重试。

循环没有内置预算。模型可以一直调工具，直到上下文爆掉或者你手动停。必须在钩子里计次、在上层计 token，两道闸门都要有。

计次容易，计 token 麻烦——用量在 assistant 消息的 usage 字段里，要自己累加。累加的地方应该是 afterToolCall 或每轮结束，别放在界面层，界面层可能在重连后丢掉。

这不是理论风险。我让一个脚本化模型在同一个错误上反复重试：权限被拒，它继续读同一个路径。没有闸门时，30 轮上限内它把 30 次调用全用完了；加一条「8 次预算 + 拦下后 terminate」的规则，第 9 轮就收尾。

工具调用次数对比条形图：无预算闸门 30 次，8 次预算 8 次

同一个死循环任务：无预算闸门时 30 轮上限内把 30 次调用全部用尽，加 8 次预算后 9 轮收尾。差的不只是次数，还有这 22 轮里每一个 token。

更值得记的是那 30 轮不是终点，是我给实验设的上限。没有 terminate，模型会在这个错误上继续试下去，直到上下文撑爆或者你手动 kill。脚本编排时代这个由进程超时兜着，循环里没有进程生命周期，只能靠钩子。

所以预算闸门要做两件事：到点拦住，并且让这一轮直接结束。只拦不终止，模型下一轮还会再请求同一个工具，你只是把频率降低了。

pi 生态里有独立的 pi-telemetry 包，但那是可选项。真正必须做的是把事件落盘：每个事件带会话 id、轮次、时间戳、工具名、耗时、结果摘要。有了这份结构化记录，任何一次线上异常都能重放出来。

反例是只记日志。日志是自由文本，事后要靠正则去猜当时发生了什么；事件是结构化的，可以直接算工具成功率、平均轮次、按失败类型分组。

循环会改东西——改文件、写库、重启服务。要能回滚，前提是每个有副作用的工具都留下「改之前是什么」。这件事框架不管，工具的作者必须管。

务实做法是给工具加一个 replay 策略字段：声明为 safe 的工具可以重放，声明为 never 的工具出错后必须人工确认。循环本身支持这个语义，但具体哪些工具是 safe，只有你知道。

真实模型做回归测试几乎不可能：温度、采样、上游版本都会让结果漂移。可行的做法是分层——循环用脚本化模型做单测，锁死「钩子是否拦截」「队列是否消费」「错误是否送达」这类行为；模型效果用固定用例集做抽查，允许答案措辞不同但要求关键结论一致。

评测集不要超过 30 条。超过就没人维护了。每条用例写清三件事：输入、期望的关键结论、不可接受的结果。

把这一篇和前九篇压缩成一张表。每一条都对应一个具体的失败模式，不是泛泛而谈。