Pi 源码伴读指南

这是 pi-mono（pi coding agent，作者 Mario Zechner）源码的中文伴读材料。目标：让你按顺序把整套源码顺下来，每读一个文件都知道它为什么存在、和谁打交道。

这个仓库是什么

pi 是一个可自扩展的 coding agent CLI，TypeScript 写的 monorepo，npm 包名 @earendil-works/pi-coding-agent。四个核心包，依赖方向严格单向：

coding-agent  →  agent  →  ai
     │
     └──────→  tui（独立于 agent 链路，只管终端渲染）

包	npm 名	一句话
packages/ai	pi-ai	统一多家 LLM API（OpenAI/Anthropic/Google/…），自动发现模型
packages/agent	pi-agent-core	通用 agent 运行时：tool calling、状态管理、传输抽象
packages/tui	pi-tui	终端 UI 库，差分渲染
packages/coding-agent	pi-coding-agent	最终产品：read/bash/edit/write 工具 + 会话管理的 CLI

另外三个包（evals、server、storage）是外围设施，不影响理解主线，本指南不覆盖。

为什么值得读

• 分层干净：ai ← agent ← coding-agent 无循环依赖，每层可独立读懂。
• agent-loop 是最小可用实现：没有过度设计，一个文件讲清"LLM ↔ 工具"循环。
• 扩展机制是真架构亮点：pi 自己的很多功能就是用扩展 API 写的，读它能学到"怎么让 agent 可自扩展"。
• 无权限沙箱：README 明说 pi 没有内置权限系统，靠容器隔离——读工具实现时能直接看到真实的安全边界在哪。

怎么用这份指南

1. 按侧边栏顺序读，章节编号即阅读顺序。
2. 每章开头有"核心文件速查"表，⭐ 数决定你该逐行读还是扫一眼。
3. 文中所有 packages/xxx/src/yyy.ts:123 形式的引用都能直接跳到本地源码对应行，建议编辑器里开着 /Users/foril/projects/pi-mono 对照读。
4. 每章末尾有自测题，答不出就回去重读对应小节。

本地源码版本：3cd3916（浅克隆于 2026-07-27）。pi 迭代很快，行号会漂移——以函数名为准，行号只是定位辅助。