Pi Agent 源码解析（一）：从调试环境到双层主循环
内容提要
本文解析 Pi Agent 源码：先介绍调试环境搭建（安装依赖、下载模型目录、配置密钥、VS Code 断点），再重点讲解双层主循环——内层处理工具调用与 steering，外层处理 follow-up；通过 StreamFn 依赖注入解耦 Agent Core 与模型供应商，流式事件经归并更新状态，工具调用先校验后执行，结果回填上下文以触发下一轮请求。
延伸解读
StreamFn 注入：解耦 Agent Core 与模型供应商
Pi Agent 通过 StreamFn 依赖注入将 Agent Core 与具体模型供应商解耦。agent-loop.ts 只认识抽象的 StreamFn，不直接调用 OpenAI SDK。实际实现由 sdk.ts 在创建 Agent 时显式注入，包装了超时、重试、header 扩展等逻辑。这种设计让 Core 保持供应商无关，便于替换或扩展模型后端，也使得调试最终请求时可以在注入点设置断点。
双层循环：内层处理工具链与 steering，外层处理 follow-up
runLoop 包含内外两层循环。内层循环在 hasMoreToolCalls 或 pendingMessages 非空时持续运行，处理工具调用后的下一轮请求以及 steering 消息（用户在当前任务进行中插入的纠偏）。外层循环在内层退出后检查 follow-up 消息，若有则重新进入内层，否则结束。这种设计清晰区分了当前任务链的延续与后续任务的排队，避免了递归调用。
流式事件归并：partial message 原位替换避免历史污染
streamAssistantResponse 消费 Provider 流事件时，收到 start 事件先将 partial message 放入上下文末尾，后续每个 delta 事件都替换该位置而非追加新消息，确保一个回答在历史中只占一条 assistant message。收到 done 或 error 后，用 response.result() 的最终对象替换 partial message。这种归并方式防止了每个 token 都变成独立历史消息，保持了上下文的整洁。
工具调用安全：先校验后执行，截断时拒绝执行
工具调用执行前需经过 prepareToolCall 检查：工具是否存在、参数预处理、schema 校验、beforeToolCall 钩子是否阻止。只有通过预检的调用才会执行 tool.execute。特别地，当模型因 token 上限以 stopReason === 'length' 结束时，所有工具调用参数都可能被截断，代码不会执行任何工具，而是生成错误结果让模型重新发起完整调用，这是一个容易被忽略的安全细节。
Q&A
Pi Agent 源码调试环境怎么搭建？需要哪些步骤？
需要 Node.js >=22.19.0，克隆仓库后运行 npm ci --ignore-scripts 安装依赖，再执行 npm run hydrate:model-data 下载模型元数据，并用 npm run check:model-data 验证。模型密钥配置在 ~/.pi/agent/models.json 中，可通过环境变量引用。VS Code 调试入口是 packages/coding-agent/src/cli.ts，使用 tsx 运行。
Pi Agent 的双层主循环分别解决什么问题？
内层循环处理工具调用和 steering：只要还有工具结果需要交给模型或有 steering 消息，就继续请求 LLM。外层循环处理 follow-up：当内层结束、Agent 准备停止时，检查是否有排队的 follow-up 消息，有则重新进入内层循环，至少再触发一次 LLM 请求。
Pi Agent 中 StreamFn 是如何注入的？有什么作用？
在 packages/coding-agent/src/core/sdk.ts 中创建 Agent 时显式传入 streamFn 包装函数。它负责在请求前补充超时、重试、header 和扩展 hook，然后调用 ModelRuntime.streamSimple 选择具体 provider。这样 Agent Core 只依赖抽象的 StreamFn，与模型供应商解耦。
Pi Agent 的流式响应事件是如何被消费并更新状态的？
streamAssistantResponse 中，收到 start 事件时把 partial message 放入 context.messages 末尾；后续 text_delta、thinking_delta 等事件替换最后一项而非新增；done 或 error 时用 response.result() 取得最终消息替换。Agent 的 processEvents 根据 message_start、message_update、message_end 等事件归并状态，只有 message_end 才追加到正式历史。
Pi Agent 工具调用执行前有哪些校验步骤？
prepareToolCall 会检查工具是否存在、预处理参数、按工具 schema 校验参数，并执行 beforeToolCall hook 判断是否阻止。只有通过预检的调用才会执行 tool.execute。如果模型因 token 上限截断（stopReason 为 length），则不会执行任何工具，而是生成错误结果让模型重新发起。
Pi Agent 中 steering 和 follow-up 有什么区别？
steering 是当前 Agent 还在工作时用户发来的纠偏消息，会在当前 turn 完整结束后、下一次 LLM 请求前注入上下文，参与当前任务链。follow-up 是等当前任务自然完成后再开始的消息，更像排队的下一项任务，由外层循环处理，至少触发一次新的 LLM 请求。
