Pi Agent 源码级教程
APX

裂缝 —— Pi 自己没修干净的八件事

2,446 字 · 含 43 行代码 · 约 18 分钟

前四十章都在讲 Pi 怎么把事情做对。

这一篇反过来:Pi 哪里没做干净,为什么没做干净,对你意味着什么。

写这一篇不是为了挑刺。一个跑了一年多的 agent 框架,它的价值有一半藏在"哪些地方它妥协了"里——因为那些妥协正好标出了这个问题的真实难度。你在别处读到的都是"应该怎么做",只有源码能告诉你"实际能做到什么程度"。

八条,全部来自正文已经讲过的地方,不引入新代码。

怎么读:每条四段——现象、源码位置、为什么不修、对你意味着什么。赶时间的话只看每条的第三段,那是判断的依据。


一、中止不是原子的

现象:你按 Ctrl-C,一批工具执行到一半。前两个已经写进磁盘,第三个没跑。Pi 不会回滚。

源码位置:packages/agent/src/agent-loop.ts:582-587

ts
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):

ts
if (signal?.aborted) {	break;}

并行路径的 immediate 分支不一样(:615-627):

ts
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

ts
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 包着的,抛了最多把这一条结果替换成错误消息:

ts
} 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: true to 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 三处

ts
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

ts
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