沿调用链打开 Pi ​

小A和老Z沿发光路径穿过命令入口、模型流、工具与会话工作站,追踪 Pi 的端到端调用链。

概念篇读完,小A觉得自己“懂”了:模型怎么生成、工具怎么调用、循环怎么转、会话怎么存。他把概念书一合,打开了 pi-mono 的源码目录,打算挑一个真实 Agent 看看。

十分钟后,他盯着满屏的 packages/ 目录发呆。ai、agent、coding-agent、tui、protocol……十几个文件夹,哪个是入口?哪条是主路?

他去找老Z:“概念我会背了,可这代码我看不懂从哪下手。”

老Z笑了:“概念回答的是‘通常如何工作’。你现在要回答的是另一个问题:一个真实 Agent 在哪里创建请求、怎样推进状态、何时中断或保存会话。这需要一份能复核的源码快照,而不是凭印象猜。我们选 pi-mono,按包边界和一条端到端调用链来读。”

“那我看的是哪个版本?会不会过两天又变了?”

本篇的基线与证据规则

  • 仓库: earendil-works/pi(原 badlogic/pi-mono,本书仍称 pi-mono)
  • 固定标签与提交: v1.0.0,a13d35a742c6ef8462812a28fbe1d8c8b7431c32
  • 版本边界: 根仓库 0.0.3;本书选取的八个包 1.0.0
  • 提交日期: 2026-10-01

本书仓库根目录的 pi/ 是这个标签的源码快照,全部 TypeScript 文件加了中文注释,没有自己的 git 历史。路径和符号与上游一致;行号以上游标签为准,快照里会因注释而偏移。要核对原文,在别处克隆上游并检出 v1.0.0。

小A追问:“书里的代码和结论,我该怎么核对?”

老Z说:“记住三条证据规则,读到哪都用得上:”

证据规则

  • 已确认事实必须能回到该快照的文件路径、符号名或官方原始资料;行号仅是该快照下的辅助定位。
  • 基于源码的推断只从结构和调用关系说明“这意味着”或“可以推断”,不把它写成作者意图。
  • 示意或简化的伪代码、删节代码、流程图和假设场景会明确标注;它们不是完整真实源码。

“还有,”老Z补了一句,“‘讲清源码’不等于逐行讲完所有源码。本篇承诺讲清核心入口、关键类型、主要调用链、状态变化、错误路径和设计代价,并给出能继续独立阅读的走查路线。”

小A猜:“那我是不是先把十几个文件夹的名字都过一遍?”

“先别急着记名字,要盯的是一个更具体的问题。”老Z在屏幕上敲了一行字,“一次用户输入,如何从命令行进入系统,变成模型流、工具执行、会话记录和终端更新?答案就藏在这条链路上。”

本篇解决什么

读完源码篇,你能沿两条路线独立走查:一条是请求穿过入口、模型流、循环、会话、终端与协议的主调用链;另一条是 pi-durable 的存储内核。pi-durable 不依赖 pi-agent-core,把它当成同一条链的末端会读错边界。你能:从入口找到模型请求怎么发出、流怎么穿过适配层、循环怎么推进状态、会话怎么活过进程重启、终端怎么刷新、工具与扩展怎么接入、协议怎么变成字节、远程会话怎么保持一致、评测怎么判断一次修改。核心是建立一张可验证的地图:遇到 bug 或想扩展时,你知道该往哪个文件看。

这里暂不解决:逐行讲完所有源码、覆盖全部边缘功能、把有限样本升级成全局结论。没有覆盖的部分会在对应章节标明,而不会被暗示为已完整解释。

“为什么不选别的仓库,非得是 pi-mono?”

“因为它是一个真实的、能端到端跑通的 TypeScript Agent 仓库,而且它的包边界和我们概念篇画的边界对得上。”老Z说,“概念篇讲的 Provider、循环、会话、工具、协议、评测,在 pi-mono 里都能找到对应的包和调用链。选一个具体仓库,你才能指着某一行说‘就是这里实现了它’,而不是对着抽象概念空谈。”

“读源码有没有通用的方法?”小A问。

“有,但记住三条就够起步。”老Z说,

读源码的三个习惯

  1. 先入口后细节:从 index.ts 的导出和某个 create*/run* 函数进,先看清主路径再钻分支
  2. 先契约后实现:读模块前先读它的 types.ts 或接口定义,实现细节只在怀疑 bug 时才需要
  3. 先状态后逻辑:一个类有哪些成员、谁在何时改它们,比某个 if 写得巧不巧重要十倍

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。