沿调用链打开 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说,
读源码的三个习惯
- 先入口后细节:从
index.ts的导出和某个create*/run*函数进,先看清主路径再钻分支- 先契约后实现:读模块前先读它的
types.ts或接口定义,实现细节只在怀疑 bug 时才需要- 先状态后逻辑:一个类有哪些成员、谁在何时改它们,比某个 if 写得巧不巧重要十倍
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。