阅读路线图¶

从哪开始、按什么顺序顺完全部源码。总耗时估计 12–18 小时精读，4–6 小时速读（只看 ⭐⭐⭐）。

路线总览¶

第 0 站  跑起来           README + 实际用一次 pi            0.5h
第 1 站  packages/agent   agent-loop.ts 全书核心           3h   ⭐⭐⭐
第 2 站  packages/ai      统一 LLM 抽象                   2h   ⭐⭐
第 3 站  coding-agent     会话 → 工具 → 提示词/压缩        4h   ⭐⭐⭐
第 4 站  coding-agent     cli/三种模式 → 扩展/skills       3h   ⭐⭐⭐
第 5 站  packages/tui     终端 UI（可选）                  2h   ⭐

为什么先 agent 后 ai？ agent-loop 是整个仓库的心脏，它只消费 ai 包的少数几个类型（消息、流事件），带着"这些类型被谁用、怎么用"的问题去读 ai 包，比自底向上读更有的放矢。

第 0 站：建立体感（0.5h）¶

读根 README.md，确认四个包的定位。
装一次 pi 并实际用：发一条消息、让它改个文件、按 Ctrl+C 中断、用 / 命令。每看到一个界面元素，猜它对应哪个包。

第 1 站：agent 循环（3h，全书核心）¶

对应章节：agent 包总览 → agent-loop 精读。

带着一个问题读："一条 user message 进去，到 assistant 最终回复出来，中间经过了哪些状态转换？"

types.ts 先看类型：消息、工具、事件，全是后面一切的词汇表。
agent-loop.ts 逐行读。while 循环 → 调 LLM → 解析 tool calls → 并发执行 → 结果回灌 → 再循环。
agent.ts 看 Agent 类对外暴露的 API：coding-agent 层订阅的就是这些钩子。

读懂这一站，你就懂了所有 coding agent 的 80%。

第 2 站：ai 包（2h）¶

对应章节：ai 包总览 → providers → 认证与模型目录。

types.ts 统一消息格式，和第 1 站看到的消费方式对上。
providers 只精读 Anthropic 一个：统一格式 → 各家 API 的翻译 + SSE 流归一化。其余 provider 扫一眼差异即可。
models.generated.ts 是生成文件，跳过。

第 3 站：coding-agent 的内核（4h）¶

对应章节：会话 → 工具 → 系统提示词与压缩。

agent-session.ts：产品层怎么包装 Agent 类、怎么做持久化和事件接线。
tools/：read/bash/edit/write 每个工具的 schema 和护栏。对照 README 那句"无内置权限系统"读，注意危险操作在哪设防。
compaction/：上下文满了怎么办——什么时候触发、总结什么、怎么塞回上下文。这是生产级 agent 和玩具的分水岭之一。

第 4 站：入口与扩展（3h）¶

对应章节：CLI 与三种模式 → 扩展与 skills → 配置与模型解析。

main.ts → cli.ts：启动序列和模式分发（interactive / print / rpc）。
扩展系统：架构上最值得学的部分。pi 自己的不少功能就是扩展写的，读完回答"如果我要给 pi 加一个功能，改源码还是写扩展？"
模型解析链：用户选的模型名怎么一路变成具体 provider 实例。

第 5 站：tui（2h，可选）¶

对应章节：tui 总览 → 组件精读。

只关心 agent 逻辑可跳过；对终端渲染感兴趣再读：一次按键 → 解析 → 编辑器状态变更 → 差分渲染 → ANSI 字节写出的完整链路。

读法纪律¶

以 agent-loop 为主线，遇到上下游调用再跳包，不要逐文件顺序读。
对照测试读：packages/*/test/（或 src/**/*.test.ts）有现成的输入输出样例，读循环逻辑时先看测试能省一半时间。
行号会漂移，以函数名为锚。
每章自测题答不出 80% 就重读，不要带病前进。