源码篇第12章 接力赛——End-to-End ​

本章导读: 源码路线的终点。本章不再读新文件,只把前十章走过的
models.ts→lazy.ts→agent-loop.ts→agent-session.ts→main.ts串起来。pi-mono 里并没有一个“总控函数”:一次完整请求是跨包的控制流拼接,每一站只交接不包办。
源码篇走完了。小A合上笔记本,长长舒了一口气:“所以 pi-mono 里一定有个‘总控函数’吧?我从命令行敲一句话进去,它就从第一行开始,一路跑完,把结果吐出来。”
“没有这样的函数。”老Z笑了,“这不算缺点,源码篇给你的本来就是一张地图:把不同包的真实调用点连起来,就是走查路线。下面这条基于上游 pi@v1.0.0(提交 a13d35a7)拼出。这一章不读新文件,只把第19到源码篇第11章的交接点串起来;远程宿主背后怎样跑 Agent,前面没有跟读,这里也不补。”
一条正常路径 ​
CLI main/模式选择
→ 配置、资源与模型运行时
→ AgentSession
→ Agent 与 runAgentLoop
→ Models.streamSimple → Provider.streamSimple
→ 模型事件 → assistant message / tool call
→ 工具结果 → 后续模型消息
→ session entry 与 TUI 更新“packages/coding-agent/src/main.ts 与 cli.ts 是命令行启动路径;core/resource-loader.ts、core/model-runtime.ts、core/agent-session.ts 负责资源、模型和会话装配。packages/agent/src/agent.ts、agent-loop.ts 承接状态和循环;v1.0.0 的 pi-agent-core 不再有 harness,会话和压缩在 core/session-manager.ts、core/compaction/。packages/ai/src/models.ts 的 streamSimple 解析认证并委派 Provider 流。交互模式在 modes/interactive/interactive-mode.ts,TUI 基础设施在 packages/tui/src。”
比喻:接力赛
每个包只负责自己那一段接力棒(上下文、模型、事件、条目)。
“这条链路的每段都有独立入口,属于跨模块的控制流拼接。别把上面的箭头读成这些文件按排列顺序逐个互调。”
小A有点不放心:“没有总控,那每段怎么知道上一段把什么交给了自己?”
“靠类型契约。”老Z逐段点交接点,“CLI 层把 args 解析成配置对象,传给 resource-loader.ts;resource-loader 汇集成 Resources,传给 agent-session.ts;session 装配出 AgentContext(messages,其中 system message 携带 system prompt 和工具声明;以及可执行的 tools)、Model 和 AbortSignal,交给 Agent;loop 拿到这些后调 streamFunction,也就是 Models.streamSimple;Models 解析认证后委派给 Provider.streamSimple。每一段只消费上游显式传进来的参数,不读全局单例,所以替换 Provider 或换 TUI 都不用重写 loop,代价是排查故障得在交接点逐段关联。”
“把一次本地交互的完整形态画出来,是这样的。”老Z说:
main() ──args──> createAgentSessionFromServices ──> AgentSession(持有 Agent)
│ │
└──interactive 模式─────┘
InteractiveMode.init ──> AgentSession.subscribe(handleEvent)
用户输入 ──> Agent.runPromptMessages ──> runAgentLoop(prompts, context, config, emit, signal, streamFn)
├─ streamAssistantResponse ──> Models.streamSimple
│ │ lazyStream 同步返回,auth 后台解析
│ v
│ Provider.streamSimple ──> 真实 HTTP/SDK 流
│ v
│ assistant message(stop / toolUse / length / error / aborted)
v
tool call ──> executeToolCalls / failToolCallsFromTruncatedMessage
v
tool result 作为消息 push 回 context
v
下一次 stream → turn_end → agent_end
v
AgentSession 持久化 + InteractiveMode 刷新 TUI“注意这条图里没有一条线把‘CLI → 模型 → 工具 → 会话 → TUI’串成函数调用栈。”老Z说,“每条边都是独立入口:main() 装配,runAgentLoop 循环,Models.streamSimple 认证委派,AgentSession 持久化,InteractiveMode 订阅渲染。这张图要按‘谁在什么时机把什么交给谁’来读。”
“再看交接的数据形态。”老Z补充,“传给 Agent 的不是裸字符串 prompt,而是 AgentContext(messages 数组 + 可执行 tools;system prompt 和工具声明在 system message 里);模型层拿到的也不是裸 HTTP 请求,而是 Model 引用加 SimpleStreamOptions。失败语义也分属各段:CLI 失败是配置错误,session 初始化失败不进 loop,loop 失败是 stopReason 异常,Models 失败是认证或 provider 未知,四种错误不会混成一种。”
“把失败按层级捋一遍,关键分界是‘会不会进 loop’。”老Z边说边把六类失败归位:
| 失败层 | 典型错误 | 从哪里暴露 | 会不会进入 loop |
|---|---|---|---|
| CLI 配置 | 参数解析、资源读取、cwd 不存在 | main() 退出前 |
否 |
| session 装配 | 模型未选、服务初始化失败 | createAgentSessionFromServices |
否 |
| 认证/provider | applyAuth 抛 ModelsError |
lazy stream 的 error 事件 | 是,以 error stopReason 出现 |
| 模型流 | HTTP 中断、限流、采样异常 | provider stream 事件 | 是,stopReason error/aborted |
| 工具执行 | 工具抛错 | executeToolCalls 捕获 |
是,isError tool result 回传 |
| 会话持久化 | JSONL 写失败 | SessionManager._persist 抛错,经 AgentSession 事件处理向上传播 |
可在 loop 中发生,并进入 Agent 失败处理;UI 可能已先收到消息事件 |
工具结果怎样返回循环 ​
小A指着链路问:“tool call 发出去之后,loop 这边接着做哪些事?”
“助手流中的 tool call 被 Agent 循环交给已装配的工具,工具结果再作为消息进入后续模型上下文。”老Z说,“runAgentLoop 管理停止原因、中止和下一次流;AgentSession 负责把状态与条目交给存储。工具输出可能失败、被截断或被拒绝,正常路径必须把结果显式传回。”
小A想看得更细:“tool call 到底在 loop 的哪一步变成 tool result?”
“看 runAgentLoop 的内层循环。”老Z回到 agent-loop.ts,“stream 完一条 assistant message 后,先检查 stopReason:error 或 aborted 直接 emit agent_end 退出,不执行工具。正常情况下从 message 里 filter(c => c.type === "toolCall") 拿出 tool calls,接着是个关键分支:stopReason === "length" 时走 failToolCallsFromTruncatedMessage,把所有 tool call 标记为失败而不是执行。length 截断意味着 tool call 的 arguments 可能不完整,执行它会有语义错误。只有非 length 的 stopReason 才走 executeToolCalls 真正执行。”
“执行完的 tool results 被 push 进 currentContext.messages 和 newMessages。”老Z继续,“然后看 hasMoreToolCalls = !executedToolBatch.terminate:如果工具批次要求终止(比如某个工具返回了致命错误),内层循环就停。v1.0.0 里宿主还可以在 finishTurn 返回 { action: "end" } 提前结束。否则继续下一轮 stream,此时 context 里已经带着 tool result messages,模型看到它们再决定下一步。tool result 就是普通消息,模型把工具输出当成对话历史的一部分。”
小A数了起来:“一个 tool call 从消息里被拿出来,到变成 result,中间到底几步?”
“四步,每步都可能短路成 error result。”老Z把 executeToolCalls 的管线摊开,“第一步 prepareToolCall:按 name 找工具,找不到直接产 Tool not found;找到了就 prepareArguments 预处理、validateToolArguments 验证参数,再跑 beforeToolCall 钩子,钩子 block 就产出被阻止的 error result。第二步 tool.execute,抛错被捕获成 error result。第三步 finalizeExecutedToolCall 跑 afterToolCall 钩子,钩子抛错也把结果降级为 error。第四步 createToolResultMessage 把 outcome 变成 toolResult 消息。另外,顺序执行时每跑完一个工具就检查 signal.aborted:abort 短路后续工具,已执行的照常保留。”
小A抢答:“这个我猜是 some,只要有一个工具返回 terminate,整批就停?”
“看 shouldTerminateToolBatch。”老Z指回 agent-loop.ts,“条件是 finalizedCalls.length > 0 && finalizedCalls.every(f => f.result.terminate === true):批里每个工具的结果都标记了 terminate,整批才终止,是 every 不是 some。terminate 字段由工具返回,也可被 afterToolCall 改写。loop 自己不猜‘哪个错误该终止’,这是产品层通过工具显式表达的;length 分支正好相反,那边是 loop 代判参数不完整。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。