按层调试
智能体里的一次失败是某一层里的一次失败,而要找出是哪一层,最快的办法是替换它下面那一层,看症状是否存留;本章把每一层与它的症状和它的仪器配对。
那个扩展昨天还能用。今天同一条命令什么也不做,转录记录看起来正常,而哪里都没有错误。你没有栈跟踪。你只有一个做了某件事的模型、一个把它记录下来的进程,以及七个它可能出问题的地方。
把一个智能体调试得很糟,意味着同时看遍所有地方。把它调试得好,则从你现在已经掌握的架构出发。第 1 章的那些层,加上第五部分新增的两层,给你一份嫌疑人名单,还有一个每问一次就把名单砍掉一半的问题。
嫌疑人
界面 terminal、print、JSON、RPC、SDK:你如何观察它
宿主 / 应用 扩展、设置、信任、上下文文件、会话
工具 / 效果 一个工具做了什么,以及一道门放过了什么
智能体内核 循环:轮次、钩子、事件、队列
模型访问(pi-ai) 一次请求:认证、负载、停止原因、用量
provider 应答的那个服务
从最便宜可查的那一层开始,而不是从一条关于哪一层通常出错的规则开始。对于"模型无视我的指令",第一个该怀疑的是请求上游的某个东西——一个没有加载的提示词小节、一个没有被准入的上下文文件、一个被压缩掉的条目——因为那些检查起来是免费的。这是一个起始启发式,不是一次诊断:一个静默丢弃参数的 provider,从外面看起来一模一样,而排除它需要和其他一切一样的那个替换测试。“智能体一直在重试"是 provider 和重试层。“我的命令在 --print 下什么也不做"是界面。功夫在于通过实验、而不是凭借预期,把症状分配到某一层。
那个有效的问题
替换你怀疑的那一层下面那一层。症状还存留吗?
第五部分让这种做法变得代价很低,因为各层是可分离的,而你有一个脚本化的 provider:
| 要测试这一层…… | ……这样替换 | 然后寻找 |
|---|---|---|
| 模型之上的你的代码 | 那个 provider,用 faux provider 替换 | 症状存留:它是你的代码或循环,不是模型 |
| 智能体循环 | 那个编码智能体,用一个光秃秃的 Agent |
症状消失:它在宿主或一个扩展里 |
| 一个扩展 | 关掉扩展运行(-ne) |
症状消失:就是那个扩展 |
| 界面 | 那个界面,用 --mode json 或 SDK 替换 |
症状消失:它是呈现层的问题 |
| provider | 直接通过 pi-ai 发出一次请求 |
症状在没有智能体的情况下仍存留:它是模型、凭据或请求 |
这是第 1 章的可替换性测试,被当作诊断手段使用。如果对一层的改动不可能在不扰动另一层的情况下做出,你发现的那个耦合通常就是 bug。
flowchart TD
S["一个症状"] --> Q1{"用一个脚本化的 provider 替换后它还存留吗?"}
Q1 -->|"否"| MODEL["模型、凭据或请求:模型访问或 provider"]
Q1 -->|"是"| Q2{"在一个光秃秃的 Agent 里、没有编码智能体时它还存留吗?"}
Q2 -->|"否"| HOST["宿主或应用:扩展、设置、上下文、会话"]
Q2 -->|"是"| Q3{"移除每一个钩子之后它还存留吗?"}
Q3 -->|"否"| HOOK["一个钩子或一道门:工具边界"]
Q3 -->|"是"| CORE["循环本身,或你自己的工具"]
HOST --> Q4{"在另一个界面里它还存留吗?"}
Q4 -->|"否"| UI["界面"]
Q4 -->|"是"| APP["应用层"]
一层一层看
对每一层:它的失败是什么样子,以及一步回答那个问题的仪器。
Provider
*看起来像:*一次 529 和一段停顿、一个挂起的请求、一个被截断的回答、一次限流。
*仪器:*重试与恢复事件(auto_retry_start、带着 reason: "overflow" 的 compaction_end)替你把这个失败分类,而第 29 章是参考资料。provider_stream_event 在 Pi 归一化每一个已解析的 provider 事件之前为它触发。把它当作只读,因为修改可能影响归一化,并且注意它是 Pi 所拥有的最早的结构化值,不是原始 HTTP 字节。随附的 debug-provider.ts 示例按助手消息把那些事件分组。如果你怀疑的是一个 provider 适配器、而不是你的代码,它是第一个该试的东西。
模型访问(pi-ai)
*看起来像:*一个加载了却不出现在 /model 里的模型、一次返回 stopReason: "error" 的调用、一个在你的 shell 里能用而在 Pi 里不能用的凭据。
*仪器:*第 3 章的凭据顺序(运行时的 --api-key,然后是 auth.json,然后是 models.json,然后是环境)解释了其中大多数。而因为一次失败的请求是一个值、不是一个异常,先检查 stopReason 和 errorMessage:一次"什么也没返回"的调用,通常是返回了一条你没有读的错误消息。pi-ai 的 onPayload 回调精确显示出被发送出去的内容:
const response = await models.complete(model, context, {
onPayload: (payload) => console.log(JSON.stringify(payload, null, 2)),
});
*有文档记载,未运行:*来自 pi-ai README,由 stream、complete、streamSimple 和 completeSimple 支持。它是"provider 拒绝了我的请求"和"模型从未看到我声明的那个工具"这两个问题的正确仪器。
智能体内核
*看起来像:*循环多跑了一轮或少跑了一轮、一个工具从未被调用、一个钩子好像没有触发、一条引导消息到得很晚。
*仪器:*事件流,以及第 39 章里已观察到的钩子顺序。订阅并打印 event.type。如果 agent_end 触发了而工作还在继续,你看到的是编码智能体的重试、恢复或队列(第 25 章),因为内核的那次运行确实已经结束了。回忆一下,一个无条件返回 continue 的 finishTurn 是一个无限循环。如果一个守卫看到陈旧的状态,回忆一下原始的 agentLoop() 不会等待你的处理器,而 Agent 类会。
工具与效果
*看起来像:*模型"一直在重试”、一道"太严"的门、一次本不该发生的写入。
仪器:一个失败的 tool_call 处理器会把工具作为一道保护性措施挡下,而模型看到的是一个失败的结果,不是崩溃,所以一道过严的门看起来像一个听不进"不"的模型。一个返回一个说着"失败"的对象的工具并没有失败:只有抛出异常,或者 isError: true,才标记它失败了。对于一个 MCP 工具,一道以工具名为键的门会静默跳过 mcp__<server>__<tool> 这个形式(第 21 章)。并且记住第 39 章的那个矩阵:如果效果已经发生了,后面没有任何一个钩子能解释为什么。问题是哪一个钩子本该在它之前拒绝它。
宿主与应用
*看起来像:*一个"静默地什么也没做"的扩展、一个没有生效的设置、一个恢复错了的会话、一些没有被遵循的指令。
*仪器:*四条有文档记载的生命周期规则解释了其中大多数。
- 工厂不是启动进程的地方。“不要在工厂里启动进程、套接字、监视器或定时器,因为有些调用会加载扩展而不启动会话。“它在交互式下能用,而在
--print下什么也不做。 - **命令上下文操作仅限命令。**等待空闲、重载和会话替换不在
ExtensionContext上,因为从生命周期处理器里调用它们可能让运行时死锁。一个挂起的处理器:先检查这个。 - **重载会替换运行时。**在
await ctx.reload()之前捕获的状态,在它之后绝不能使用。 - **一次处理器失败既不是无操作,也不是崩溃。**Pi 会报告处理器错误,并在可能的地方继续。
关于状态而不是生命周期:/session 显示文件、ID、消息数、token 用量和费用,而"我恢复的会话不是我想要的那个"几乎总是一个工作目录问题。模型看到的是活动分支,不是文件,所以"它在上下文里吗?“这个问题是一个会话问题。pi --export 和 /export 把文件写出来,而一次失败的压缩会让上下文比你以为的更大,所以一个突然退化的长会话,在责怪模型之前应该先检查这一点。
关于导出,一处需要精确的地方:--export 和 /export 写的是会话文件,所以你得到的是存下来的条目,以及包含非活动分支在内的完整文件。对于"会话里含有什么”,它是对的那个产物,而对于"模型收到了什么”,它是错的那个——transformContext、convertToLlm 和提示词小节都坐在两者之间。第 27 章从会话一侧做出同一个区分,而第 18 章的测试是你观察另一端的方式。
界面
*看起来像:*一个什么也不做的按键、一个渲染故障、一条交互式下能用而在脚本里不能用的命令。
*仪器:*先检查模式。一次 --print 运行里的 ctx.ui.confirm() 不是 bug,它是一个有文档记载的 UI 缺席,而 ctx.hasUI 和 ctx.mode === "tui" 守卫就是修复。关于渲染,PI_TUI_WRITE_LOG 捕获原始 ANSI 流,而 /hotkeys 是哪些快捷键当前有效的权威。附录 B 有终端细节。
那些产物
有些工具横切各层。它们值得你按名字认识,而第一个带着一条警告。
| 产物 | 它捕获什么 | 什么时候用 |
|---|---|---|
/debug,然后是 pi-debug.log |
渲染出来的终端行,以及当前的会话消息 | 一个渲染或会话状态问题 |
/bug [描述] |
一份包含环境与 provider 配置但不含凭据值的报告,外加错误诊断 | 某件你无法复现的事 |
/session |
文件、ID、消息数、token 用量、费用 | “我在哪个会话里?” |
/hotkeys |
当前生效的绑定 | 一个快捷键什么也没做 |
启动时的头部信息,或者 --verbose |
加载了的指令与资源 | 一个资源没有出现 |
pi --export / /export |
导出为 HTML 或 JSONL 的会话 | 上下文里有什么 |
**分享 pi-debug.log 之前先审阅它。**它可能包含提示词、模型响应、工具输出、文件内容和终端数据。同一条警告适用于 /export、/share 和 /bug。“不含凭据值"描述的是报告格式,而不是关于其内容的承诺:如果诊断包含你的对话,它仍然会包含它,而这就是 /bug 让你省略转录记录、或者改让当前模型来总结这个问题的原因。
当各层意见不一致时
最难的失败是那些两层各自看起来都正确的失败。两个模式覆盖了其中大多数。
**一个在你替换某一层时会移动的症状。**你把 provider 换成 faux provider,bug 就消失了。那是关于模型的证据,不是关于你的代码的,而这正是第 41 章的脚本化测试对模型什么也不能说的原因。在得出任何结论之前,把真实 provider 运行若干次(第 41 章的评估):一次运行里发生五分之一概率的失败,在一次运行里是看不见的。
**一个在转录记录里没有原因的效果。**磁盘上有个东西变了,而转录记录没有显示哪个工具调用做了它。看看还有别的什么以这个进程的权限运行:一个扩展自己的代码、一个包的 postinstall、一个你启动的 MCP 服务器。这是第 42 章的主题:转录记录是模型要求了什么的记录,不是这个进程做了什么的完整记录。
你能主张什么、不能主张什么
*有文档记载:*那些产物(usage.md、sessions.md、tui.md)、扩展生命周期规则(extensions.md)、onPayload 和 onProviderStreamEvent(pi-ai README),以及从第 29 章和第 39 章引用的循环与钩子行为。
*本书提出:*那个层列表、“替换下面那一层"的方法,以及那个决策图。这个方法是本书的表述。它从各层是可分离的这一事实推出,而第 1 章和第 37 章展示了这一点,且它还没有针对一组真实失败做过验证。把它当作一个在本文描述的这些失败上奏效过的启发式,而不是 Pi 用文档规定好的一套流程。
下一章
现在你能说出一次失败属于哪一层了。这结束了第三部分。下一部分把主题从一次失败住在哪里换成同一个智能体如何被驱动,而关于任何界面的第一个问题,是它能看到这个智能体的多少。
第 31 章要问的是,界面究竟是不是智能体的一部分。