后端开发者如何学习 Pi
这是一条面向后端开发者的 Pi 源码学习路径。内容从语言和运行时基础开始，逐步进入 Agent Loop、工具调用、状态所有权、架构演进与生产运行边界。
- 补齐阅读 Pi 源码真正需要的 TypeScript、JavaScript 与 Node.js 基础。
- 从当前源码和 Commit History 中理解 Pi 的设计，而不只记住最终代码结构。
- 通过代码路径、可运行实验和反例建立可验证的认知。
- 最终能够解释 Pi 的关键边界，并安全地阅读、调试和修改它。
| Topic | 关注的问题 |
|---|---|
| 为什么阅读 Pi 源码 | Pi 值得学习什么，谁需要读源码，又应该怎样选择阅读入口？ |
| 阅读pi源码所需要的 TS/JS 知识 | 后端开发者需要补齐哪些语言与运行时知识，才能深入阅读 Pi？ |
| Pi 如何演变成今天的架构 | Commit History 如何记录 Pi 从产品闭环走向 Agent runtime、durable session 与远程协议？ |
| Pi Agent Runtime 源码考古 | loop、tool safe point、extension 顺序、compaction checkpoint 和 durable session 的源码契约如何反复收紧？ |
| Pi 当前架构 | pi-ai、pi-agent-core 与 pi-coding-agent 如何划分 module、interface、seam 与状态所有权？ |
| 学习 Pi 后应建立的基本认知 | 能否解释、预测、诊断并迁移 Pi 中的 Agent 工程机制？ |
| 从 Pi Runtime 到企业生产 Agent | Pi 之外还需要哪些 durable Run、工作流、故障恢复、权限审计、人工审批、评估与可观测能力？ |
首次阅读的默认路线是：00 → 01 → 02 → 02B → 03 → 04 → 05。先沿 02 建立宏观演进因果，再按问题选读 02B 的 runtime 源码链，最后回到 03 区分历史过程与当前事实。侧栏编号表示主题分组，不强制按数字顺读。
版本说明：00 基于 Pi
b7def9335（2026-08-27）；01、03、04、05 基于ccb946411（2026-08-28）；02、02B 研究ccb946411的祖先历史，并用该提交核对当前残留。
- 源码事实：能够在当前 Pi 源码、测试或 Commit History 中直接核对。
- 学习建议：为了降低认知负担而选择的阅读顺序，不等同于源码依赖关系。
- Go 对照：用熟悉的后端概念建立映射，同时说明 JavaScript 与 TypeScript 的语义边界。
- 适用边界：无法由源码或测试直接支持的判断，会明确标记为推断。
Pi 持续演化；当文档与当前实现不一致时，以源码、测试和提交记录为准。
源码路线按 Agent Loop、模型、工具、消息、事件、上下文和会话等主题展开；实战路线覆盖部署与二次开发。
通过 15 个 TypeScript checkpoint，逐步实现流式模型、工具协议、Agent Loop、会话树、Context Compaction、扩展入口和评测。