Pi 源码解读·结课总结：把八课串成一条执行主线

本篇沿用 Pi v0.84.1。这是固定的教学快照，不是“永远最新的版本”。下面的例子是教学推演；本次核对的是源码，没有运行项目或测试。¹

一、用一个任务，把八课连起来

还是你熟悉的需求：

把 src/App.vue 的页面标题从 Hello 改成你好，只改这个文件；完成后检查改动，并说明哪些验证做过、哪些没做。

假设 Pi 已经有合适的工具和模型配置，文件内容还没有提供给模型。不要把下面当成固定脚本，它只是一条可能的执行路径。

先准备材料，再找模型。 Pi 组织规则、需求和已有记录，通过模型层把请求交给对应 Provider。第四课的适配解决“怎么与这家服务沟通”，不是替工具读文件。具体可以在 ModelsImpl.streamSimple 看到查找 Provider、应用鉴权、交出请求的过程。²

模型请求读取，程序真正去读。 文件内容作为工具结果回到记录里。下一轮模型才有依据提出修改；修改结果再返回，模型再决定是否继续。这就是第二、三课的主线：提出动作 → 执行动作 → 得到观察 → 决定下一步。不是每次都只把最开始那句话重新发一遍。³

团队规范与执行检查，分别起作用。 如果配置了相关 Skill，它可以按需提供检查方法；如果安装了对应 Extension，执行前处理器可以阻止某个工具请求。但不能因为用户说了“只改这个文件”，就声称系统已经建立了完整的文件权限隔离。⁴⁵

记录和显示伴随过程发生。 会话层处理消息保存与运行收尾，界面通过事件了解进度。任务聊得很长时，才可能需要第五课的压缩：用摘要和保留消息重建工作材料。不要为了把八课都塞进例子，就假设每次改标题都会发生压缩、重试或模型切换。⁶⁷

最后，按证据回答，而不是按口气回答。 在这个练习里，可以重新读取文件、检查差异，必要时运行项目已有的相关验证。但“修改工具返回成功”“构建通过”“页面效果正确”不是同一个结论。这是任务验收要求，不是 Pi 保证自动完成的固定流程。

到这里，八课就连上了：架构说明谁负责，循环说明如何继续，工具负责动作，模型层负责通信，会话保存过程，扩展参与控制，事件提供反馈，异常分支处理不顺利的情况。

二、面试不用复述八课，挑三个具体细节

讲完主流程后，挑一两个细节展开，比一次报出十几个类名更容易说明你读过源码。

细节 1：参数看起来合法，也不一定允许执行

Pi 发现模型以 length 原因停止且包含工具请求时，会把这条响应中的工具请求转成错误结果，而不是执行可能缺内容的参数。看 runLoop 和 failToolCallsFromTruncatedMessage。⁸

能讲出的取舍是：结构能解析，不代表内容完整；宁可重新请求，也不冒险执行。

细节 2：完成顺序与记录顺序是分开的

并行工具可以按实际完成顺序发出结束事件，但最终结果消息仍按原请求顺序组织。看 executeToolCallsParallel，对照扩展文档中的工具事件说明。⁵

能讲出的取舍是：界面及时反馈，记录保持稳定；记录排好了，不代表操作具备了先后依赖。

细节 3：底层结束，不一定等于会话已经收尾

AgentSession._runAgentPrompt 在底层 Agent 返回后，还会检查后续处理；最终通过 _emitAgentSettled 通知会话级收尾。第七课据此区分 agent_end 与 agent_settled。⁶

能讲出的取舍是：生命周期有层次，界面不能拿任意一个“结束”事件充当业务成功。

三、一段面试表达，把重点讲完整

下面这段适合在你确实打开并跟过相关源码之后使用。不需要声称自己读完了整个仓库。

我通过 Pi 学习了 Coding Agent 的运行机制，主要跟的是模型请求、工具执行和结果回到上下文这条链路。比如改一个 Vue 页面的标题，模型可以先请求读取，看到实际内容后再请求修改；真正操作文件的是运行时，不是模型本身。模型层把不同服务的调用差异隔开，会话层则管理历史以及必要时的压缩。³²⁷

然后选择你最熟的一个细节继续讲：

我还专门看了输出截断的处理。Pi 不是拿到能解析的参数就执行，而是在模型因长度限制停止时拒绝执行这批工具请求。我理解这里是在避免参数形式完整、实际内容却缺了一部分的风险。⁸

表达顺序就是：我读了什么 → 一个任务怎么走 → 一处具体实现 → 为什么这样处理。 不用把整份目录背给面试官。

四、最后一次自测：先预测，再找源码

不要求写程序。先不看答案，分别写一句判断，再打开对应文件找证据。

问题 A：模型输出被截断，但工具参数看起来已经是合法对象。Pi 会直接执行吗？

问题 B：一个 RPC 消息更新不再携带完整助手消息。前端应该怎样得到最终文本？

问题 C：旧历史仍在磁盘上，但某条要求不在摘要、保留消息或其他本轮输入里。能保证模型还知道吗？

这三个问题分别对应第八、第七、第五课。只要某题说不清，就回到那一课；不需要为了补一个疑问重新刷完八课。

五、什么时候可以认为这一阶段完成了？

• 我能不看笔记，把“用户需求 → 模型 → 工具 → 结果 → 后续处理”讲通。
• 我能在固定版本里指出两处具体实现，并解释为什么这么处理。
• 我能明确区分：文章告诉我的、自己查过源码的、真正运行验证过的。

最值得补的实践不是再写一个大项目，而是在一个无敏感资料、可恢复的练习仓库里，观察一次小任务。记下模型请求了什么、工具实际做了什么、最终文件差异，以及到底运行过哪些验证。只有完成了这一步，才把它描述成自己的实测经历。

如果目前只做了阅读，就说“我阅读并跟踪了 Pi 的相关模块”；做过小实验，就描述实验过程和观察。读过源码，不等于自己实现过 Harness；阅读案例，也不等于生产落地。

至于其他工具的比较，继续沿用一条规则：Pi 的结论回到 Pi 源码；Codex 和 Claude Code 的对照单独标来源，不用相似名词代替实现证据。 暂时不需要把对照扩成另一整套课。

参考源码