裂缝 —— Pi 自己没修干净的八件事
前四十章都在讲 Pi 怎么把事情做对。
这一篇反过来:Pi 哪里没做干净,为什么没做干净,对你意味着什么。
写这一篇不是为了挑刺。一个跑了一年多的 agent 框架,它的价值有一半藏在"哪些地方它妥协了"里——因为那些妥协正好标出了这个问题的真实难度。你在别处读到的都是"应该怎么做",只有源码能告诉你"实际能做到什么程度"。
八条,全部来自正文已经讲过的地方,不引入新代码。
怎么读:每条四段——现象、源码位置、为什么不修、对你意味着什么。赶时间的话只看每条的第三段,那是判断的依据。
一、中止不是原子的
现象:你按 Ctrl-C,一批工具执行到一半。前两个已经写进磁盘,第三个没跑。Pi 不会回滚。
源码位置:packages/agent/src/agent-loop.ts:582-587
finalizedCalls.push(finalized); messages.push(toolResultMessage); if (signal?.aborted) { break; }}break 在 push 之后。串行路径下,中止前的调用各自带着完整结果落账,中止后的调用直接不执行。
并行路径稍好一点(:629-638):中止时占位函数仍然返回一条 Operation aborted 的 isError 结果,所以并行批次里每个调用都有一条结果——只不过有的内容是"我没跑"。
为什么不修:回滚需要每个工具都提供 undo,而 bash 执行的命令根本没有 undo。rm -rf 之后回滚什么?Pi 的选择是不回滚,但保证历史诚实——已做的有记录,没做的也有记录(并行路径明确写"Operation aborted")。
这背后是一句没写在文档里的话:工具的原子性责任在工具自己,不在循环。
对你意味着什么:你要写一个"移动文件"的工具,就得自己保证"移到一半中止"不会留下半个文件。循环不会帮你,也不会提醒你。
二、同一个中止,串行和并行给出不同结果
这条比上一条更尖锐,而且在正文里没写过。
现象:同样是在批次开始前就已经中止(AbortSignal 是 aborted 状态),串行模式给出 0 条工具结果,并行模式给出 N 条「Operation aborted」。同一个输入,两种模式两种历史。
源码位置:串行 :559 每次调 prepareToolCall,中止在 :767 被拦下,返回 immediate 结果——但串行路径不用 result.messages,它直接 break(:585):
if (signal?.aborted) { break;}并行路径的 immediate 分支不一样(:615-627):
if (preparation.kind === "immediate") { const finalized = { toolCall, result: preparation.result, isError: preparation.isError, } satisfies FinalizedToolCallOutcome; await emitToolExecutionEnd(finalized, emit); finalizedCalls.push(finalized); // :622 照样入队 if (signal?.aborted) { break; } continue;}finalizedCalls.push 在 break 之前。
为什么不修:没人报。这条路径要求"批次一开始就处于中止态",日常使用很难撞到——用户按 Ctrl-C 时,通常已经有几个工具在跑了。它是个只在理论上存在的分叉。
对你意味着什么:如果你在拓展里依赖"中止后历史里一定有 N 条 aborted 结果"来清理状态,换成串行模式就会失效。别赌这个。
三、finishTurn 抛异常会吞掉整轮工具结果
现象:一轮里 5 个工具都跑完了,结果都在内存里。这时你注册的 finishTurn 钩子抛了个异常。这 5 条结果永远不会进 transcript,turn_end 也不会发出。
源码位置:agent-loop.ts:289-296
lastCompletedTurn = { message, toolResults, context: currentContext, newMessages,};const decision = await config.finishTurn?.(lastCompletedTurn, signal);await emit({ type: "turn_end", message, toolResults });两行裸 await,没有 try/catch。钩子抛出的 rejection 直接穿出 runLoop,被 Agent.runWithLifecycle 的 catch 接住(packages/agent/src/agent.ts:533-536),交给 handleRunFailure 合成一条空的 assistant 消息。
工具白跑了。
为什么不修:finishTurn 是宿主的"这一轮做完了,要不要继续"的决定点。如果它自己崩了,语义上确实说不清——继续?停止?所以 Pi 选择让整个 run 失败,把问题暴露给上层。这个判断没错。
问题在执行顺序:先调钩子、后发 turn_end。如果先发事件再调钩子,工具结果至少已经广播出去了。
对比一下 afterToolCall(agent-loop.ts:880-911):它是被 try/catch 包着的,抛了最多把这一条结果替换成错误消息:
} catch (error) { result = createErrorToolResult( error instanceof Error ? error.message : String(error), ); isError = true;}同一个"宿主钩子",两道保险差这么多。写钩子的时候,你得知道自己在哪一档。
对你意味着什么:任何可能抛异常的 finishTurn 都要自己包 try/catch。它不是一个"我返回决定"的纯函数位置,而是一个能让整轮白跑的位置。
四、terminate 是一个没人用的出口
现象:书上讲 terminate 用 every 判定,你以为这是主干路径。实际扫一遍全仓,terminate: true 只出现在三个地方,八个内置工具一个都没有。
源码位置:agent-loop.ts:700-702(判定)+ 全仓 terminate: true 字面量
| 位置 | 口径 | 用途 |
|---|---|---|
coding-agent/examples/extensions/structured-output.ts:42 |
示例 | 在工具调用处结束,直接产出结构化结果 |
coding-agent/examples/extensions/reload-runtime.ts:37 |
示例 | 重载运行时后不让循环继续 |
evals/evals/documentation-audit.eval.ts:27 |
评测 | 审计结束收尾 |
packages/agent/src/types.ts:323 的注释把它的定位写得很明确:
A blocked result can also set
terminate: trueto participate in the batch early-termination rule.
"can also set"——能设,不是必须设。
为什么不修:因为内置工具里没有一个会"说完这句就别再说了"。read 完还要 edit,grep 完还要看结果。真正需要提前收尾的是扩展场景:我把结构化答案放进工具调用的参数里,拿到就该停。
对你意味着什么:这是本书里唯一一个"文档说了、代码有、但生产环境没用"的机制。它告诉你的不是"Pi 有个 bug",而是一个好框架要为一个尚不存在的用例先留好接口。你要做扩展时,这是你的。
五、事件里的数组就是那个数组
现象:你订阅了 agent_end,在回调里 messages.push(...) 补了一条系统提示。你以为只改了自己手里的副本。实际你改了 run 的返回值,也改了 stream.result()。
源码位置:agent-loop.ts:263、:299、:329 三处
await emit({ type: "agent_end", messages: newMessages });而 runAgentLoop 最后 return newMessages——同一个对象,不是拷贝。
同样的坑在 turn_end 里也有:lastCompletedTurn 的 context 和 newMessages(:289-294)装的都是引用。
为什么不修:拷贝是 O(n),而消息数组在长会话里能到几百条、每条几 KB。每轮拷一次,代价可观。更重要的是语义:Pi 的设计是"事件就是事实",不是"事件是事实的快照"。订阅者看到的就是正在发生的东西。
对你意味着什么:在事件回调里改数组之前,先 [...messages]。想观察变化用只读视角,想改就复制。
六、declareToolChanges 有时返回新数组,有时返回原数组
现象:你想用 === 判断"工具集变了没有"。同一个输入,有时 true 有时 false,看起来像随机。
源码位置:agent-loop.ts:362-371
if (pending) { if (unchanged && !pending.toolsAdded?.length && !pending.toolsRemoved?.length) { return pendingMessages; } return baseline.map((message, index) => index === systemIndex ? withToolChanges(pending, changes) : message, );}if (unchanged) return pendingMessages;两处 return pendingMessages 是原引用(:364、:367),另外两处是新数组(:365、:371)。所以拿返回值做同一性判断,会在"没变"时得到 true、"变了"时得到 false——正好反过来。
它还会被调两次(:119 注入 prompt、:220 注入 pending),第二次的入参是 [...preparedMessages, ...pendingMessages],本来就是个新数组。所以"传进去再传回来"也不保证同一性。
为什么不修:返回原引用是一个有意为之的优化——"没变化"是最常见的路径(工具集大部分时候不变),直接返回能省一次 .map。代价是同一性语义不稳定。
对你意味着什么:别在返回值上挂状态,也别用它判断变化。真要知道变没变,比对内部的 toolsAdded / toolsRemoved 长度。
七、"ask" 在没有 UI 的时候等于拒绝,而且不报错
现象:你在 CI 里跑 pi --mode json,项目里的 .pi/settings.json 明明配了,就是不生效。没有警告,没有日志,只是"没生效"。
源码位置:packages/coding-agent/docs/security.md:77-82
Print、JSON、RPC 三种模式没有内置信任弹窗。前三段决议(命令行、扩展事件、trust.json)都没给出结论时:
defaultProjectTrust |
结果 |
|---|---|
"always" |
加载受保护的项目资源 |
"ask" |
跳过 |
"never" |
跳过 |
默认值是 "ask"。所以在无 UI 环境里,默认就是拒绝。
为什么不修:因为"问一个不存在的 UI"没有正确答案。"ask" 的字面意思是"问我",没人可问的时候,最安全的解释就是"不批准"。让 "ask" 退化成 "always" 才是危险的——那等于无 UI 即全信任。
对你意味着什么:CI 里跑 Pi,要么显式 --approve,要么把 defaultProjectTrust 改成 "always"(并接受后果)。别指望默认值能工作。
八、信任决议之前,已经读过项目目录了
现象:你拒绝信任某个目录,以为"它什么也没读"。实际上 Pi 已经读过一次 sessionDir 设置了。
源码位置:coding-agent/docs/security.md:31
Pi 在决议信任之前就要读项目的
sessionDir设置——因为得先选出会话文件。拒绝信任也撤不回这一次目录查找。
同一条文档里还有一句更重要的(:33):
信任不限制工具调用能访问什么。启动之后,启用的工具用的是 Pi 进程的操作系统权限。
为什么不修:会话文件必须在启动时就确定位置,否则整个恢复流程无从开始。而"读完再决定要不要读"在逻辑上就做不到。
第二条更根本:项目信任不是沙箱。它管的是"加载哪些可执行资源",不是"能碰哪些文件"。真正的路径隔离只能靠容器或虚拟机。
对你意味着什么:如果你把 Pi 放进"跑不受信任的仓库"的场景,项目信任给你的是代码注入防护,不是数据防护。两者别混。要数据防护,看 F10 那张三档表,走容器。
收尾:这八条的共同形状
八个问题,四种成因:
| 成因 | 条目 | 特征 |
|---|---|---|
| 性能取舍 | 五、六 | 拷贝太贵,于是共享引用 |
| 语义边界 | 一、七、八 | "这件事到底该谁负责"没有唯一答案 |
| 用例没发生 | 二、四 | 接口留好了,没人走到那条路 |
| 顺序使然 | 三 | 先钩子后事件,一步之差 |
没有一条是"写错了"。它们是在真实约束下做出的选择,只是这些选择的代价没有写在文档里。
这也正是源码级教程和 API 文档的分界:文档告诉你"有什么",源码告诉你"代价在哪"。
源码索引
| 文件 | 本章用到的位置 |
|---|---|
packages/agent/src/agent-loop.ts |
中止 :582-587 :615-627 :629-638 :651;finishTurn :289-296;terminate :700-702;agent_end :263 :299 :329;declareToolChanges :362-371;afterToolCall 容错 :880-911 |
packages/agent/src/agent.ts |
生命周期 catch :533-536,handleRunFailure :542 起 |
packages/agent/src/types.ts |
terminate 定位 :323 |
packages/coding-agent/docs/security.md |
信任决议 :29-33、无 UI 行为 :77-82 |
packages/coding-agent/examples/extensions/structured-output.ts |
terminate 的典型用法 :42 |
packages/coding-agent/examples/extensions/reload-runtime.ts |
terminate 的另一处 :37 |