大话 Pi

Appearance

🐣 小a的精读清单

老z递给小a一份清单:"pi 几千个文件,你不可能全读。这 20 个是『设计含金量』最高的——读懂它们,你就懂了 pi 的精髓。"

本附录按"精读优先级"排序,每个文件标了:路径、大小、为什么值得读、难度。

怎么用这份清单 ​

  • 按顺序读:从 1 到 20,难度递增
  • 对照正文:每个文件都标了对应哪一章
  • 先读注释:pi 的源码注释质量很高,先读注释理解意图,再看实现

精读清单(按优先级) ​

🥇 必读 · 理解 Agent 本质(前 5 个) ​

1. packages/agent/src/agent-loop.ts(~22KB) ​

  • 对应:第 18 章
  • 为什么必读:Agent 循环的真身。读懂它,就懂了 Agent 是怎么"自主干活"的。
  • 难度:★★★(中等,有双层循环和并发)
  • 重点看:runAgentLoop 函数、双层 while、StopReason 处理

2. packages/agent/src/agent.ts(~18KB) ​

  • 对应:第 18 章
  • 为什么必读:Agent 类——状态机 + 观察者。读懂 subscribe,就懂事件驱动。
  • 难度:★★★
  • 重点看:subscribe() 方法、状态管理

3. packages/ai/src/models.ts(createProvider 部分) ​

  • 对应:第 17 章
  • 为什么必读:统一抽象的核心——闭包工厂。读懂它,就懂 pi 怎么盖住 近 40 家厂商。
  • 难度:★★★
  • 重点看:createProvider 函数、currentModels 合并逻辑

4. packages/ai/src/providers/deepseek.ts(15 行) ​

  • 对应:第 17 章
  • 为什么必读:最简 provider,15 行看懂"一个厂商 = 一份配置"。
  • 难度:★(最简单,适合入门)
  • 重点看:五项配置(id/auth/models/api...)

5. packages/ai/src/types.ts(~32KB) ​

  • 对应:第 1、2、17 章
  • 为什么必读:pi-ai 的"字典"——所有核心类型(Usage/StopReason/Provider/Model)都在这。
  • 难度:★★(类型多,但单个不难)
  • 重点看:Usage(计费四档)、StopReason(6 种)、Provider 接口

🥈 重要 · 理解产品化(6-12) ​

6. packages/coding-agent/src/core/system-prompt.ts(162 行) ​

  • 对应:第 20 章
  • 为什么:pi 的"人格"定义。读懂它,就懂 pi 为什么是"编程助手"。
  • 难度:★★
  • 重点看:BuildSystemPromptOptions、提示词怎么拼

7. packages/coding-agent/src/core/trust-manager.ts ​

  • 对应:第 20 章
  • 为什么:安全设计的核心——防 prompt 注入。
  • 难度:★★

8. packages/agent/src/harness/agent-harness.ts(~40KB) ​

  • 对应:第 18 章
  • 为什么:看裸 Agent 怎么被"穿衣服"(加 system prompt/tools/session)。
  • 难度:★★★★(较大)

9. packages/protocol/src/framing.ts ​

  • 对应:第 21 章
  • 为什么:帧协议的教科书级实现——encodeFrame 几行讲清"长度前缀"。
  • 难度:★(短小精悍)
  • 重点看:encodeFrame 的 4 字节大端拆分

10. packages/tui/src/tui-main-screen.ts ​

  • 对应:第 19 章
  • 为什么:差分渲染 + 同步输出(CSI 2026)的真身。
  • 难度:★★★
  • 重点看:\x1b[?2026h ... \x1b[?2026l 的成对使用

11. packages/coding-agent/src/core/tools/bash.ts ​

  • 对应:第 6、20 章
  • 为什么:一个工具的完整实现——schema + execute + 安全检查。
  • 难度:★★

12. packages/coding-agent/src/core/cache-stats.ts(~6KB) ​

  • 对应:附录 E.2
  • 为什么:缓存命中检测——CACHE_TTL_MS、NOISE_FLOOR_TOKENS 都在这。
  • 难度:★★

🥉 进阶 · 理解工程深度(13-20) ​

13. packages/coding-agent/src/modes/interactive/interactive-mode.ts(~208KB!) ​

  • 对应:第 20 章
  • 为什么:pi 最大的文件,交互模式的全部。不建议全读,挑感兴趣的组件看。
  • 难度:★★★★★(巨大)

14. packages/agent/src/harness/compaction/compaction.ts ​

  • 对应:第 18 章
  • 为什么:上下文压缩的实现——窗口满了怎么总结。
  • 难度:★★★

15. packages/agent/src/harness/session/fork.ts ​

  • 对应:第 18 章
  • 为什么:会话分叉——"试这条路不通就退回去"。
  • 难度:★★

16. packages/ai/src/auth/resolve.ts ​

  • 对应:第 17 章
  • 为什么:责任链模式范本——resolveProviderAuth 多级降级找凭据。
  • 难度:★★

17. packages/ai/src/api/transform-messages.ts ​

  • 对应:第 17 章
  • 为什么:消息格式互转——统一抽象最难的"翻译"。
  • 难度:★★★★

18. packages/server/src/sessions.ts(LiveSessionManager) ​

  • 对应:第 22 章
  • 为什么:会话池管理——create/attach/list。
  • 难度:★★★

19. packages/agent/src/proxy.ts(~10KB) ​

  • 对应:附录 D(代理模式)
  • 为什么:远程流代理——客户端不直连厂商。
  • 难度:★★

20. packages/evals/src/pi-harness.ts ​

  • 对应:第 23 章
  • 为什么:评测 harness——怎么把真实 AgentSession 适配成可评测。
  • 难度:★★

附:packages/storage/sqlite-node/(第 9 个包) ​

  • 对应:第 16 章
  • 为什么:"可选依赖"的设计典范——核心包(agent-core)不背 SQLite 原生依赖,需要时才装这个后端。
  • 难度:★★

精读建议 ​

🧙 老z的阅读心法:

  1. 先读注释,再读代码:pi 的注释质量极高,经常把"为什么这么设计"写清楚
  2. 抓主线,跳细节:第一次读 agent-loop.ts,只看"循环怎么转",跳过错误处理
  3. 对照本书:本书 Part II 是"地图",源码是"实景",对照着读不易迷路
  4. 改一改试试:读懂后改个小地方(比如加个 console.log),看行为变化——这是最深的理解

不建议逐行读的(扫一眼即可) ​

  • *.generated.ts(构建生成的,看不懂也正常)
  • *.models.ts(模型清单,数据为主)
  • node_modules/(第三方依赖)
  • 各种 test/(除非你要学测试写法)

省下时间,全花在前 20 个核心文件上。

参考 ​

  • 文件大小数据:基于 pi 仓库 find ... | xargs wc -c 真实统计
  • 对应章节:见本书 Part II 各章