开源了一本《动手学 Pi》，用 15 个 checkpoint 把 Agent 的运行链路走一遍

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

• 我的帖子已经打上 开源推广 标签： 是


• 我的开源项目完整开源，无未开源部分： 是


• 我的开源项目已链接认可 LINUX DO 社区： 是


• 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是


• 以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

项目链接

• 在线教材：https://build-your-own-pi-cn.enochzhang.chatgpt.site


• 教材仓库：GitHub - hahhforest/pi-textbook: 《动手学 Pi》：沿 15 个真实 checkpoint 从零构建 Pi-style Agent · GitHub


• 课程代码：pi/packages/pi-course at course/build-your-own-pi · hahhforest/pi · GitHub

教材首页

项目介绍

写这套教材的起点其实很简单：我想把 coding agent 的运行过程真正弄明白。于是我让codex去看到《动手学深度学习》是怎么组织教材的，然后把pi agent开发过程拆成了类似的章节形式，有实现的代码分支，以及配套的教材讲解。

现在很多 Agent 教程会从“调用一次模型”直接跳到一个完整框架。最后确实能跑起来，但中间最关键的部分还是黑盒：流式消息怎么拼起来，tool call 和 tool result 怎么对应，循环什么时候停，会话状态如何保存，context 太长以后又该怎么压缩。碰到问题时，往往只能在一个很大的系统里反复猜。

所以我沿着 Pi 的实际运行链路，把这些东西拆成了 15 个 checkpoint。从一段离线轨迹开始，逐步实现消息协议、流式模型、Provider、工具系统、Agent Loop、会话树、Context Compaction、扩展机制和 Eval。每一章只增加一层复杂度，并对应到真实的上游 commit，不是另外写一份看起来相似的示例代码。

前几章完全离线，不需要模型额度。先把协议、状态和工具边界弄清楚，确认测试都能通过，再接入真实 Provider。每章除了正常路径，还安排了聚焦测试和故障实验，目的是让人看见第一处偏差到底发生在哪里，而不只是展示一遍成功结果。

目前开源的内容包括教材网站、15 个 checkpoint 的 TypeScript 代码、测试以及练习生成器。练习目录里不会附带答案和课程 Git 历史，可以自己从当前 checkpoint 往下实现。最好的方式是由一个agent读取教材和checkpoint历史后，在旁边辅导（所谓的copilot？）。看教材、agent指导实现和答疑、agent验证

顺手统计了一下投入：目前能从任务日志核到的消耗下限大约是 5061 万 token，其中缓存输入约 4843 万，模型输出约 19.6 万。早期建设教材正文时的日志并不完整，所以这不是完整制作成本，只是目前能确认的部分。

注意：项目是社区原创的非官方课程，不隶属于 Pi 或 Earendil Works；代码使用 MIT License，教材正文和原创媒体使用 CC BY 4.0，上游代码继续沿用原有许可证。