pi 源码分析¶
状态：开源 MIT；研究快照：2026-09-26。
它是什么¶
pi 是一个终端 coding agent 和 Agent toolkit，强调多模型支持、会话树、可嵌入 runtime 与“少量核心工具 + 扩展”。仓库在近期从 badlogic/pi-mono 迁移到 earendil-works/pi-mono，生产使用必须记录实际包名和 commit。
官方入口：pi.dev、pi monorepo、coding-agent docs。
源码地图¶
| 目录/包 | 责任 | 为什么值得读 |
|---|---|---|
packages/ai 或 pi-ai |
多供应商统一 LLM API | 看 provider、stream、tool call、abort 和 context overflow 归一化 |
packages/agent 或 pi-agent-core |
Agent loop、状态和工具调用 | 看 step、tool result、handoff 与中断语义 |
packages/coding-agent |
CLI、TUI、配置、会话和 coding tools | 终端产品边界与默认安全行为 |
packages/tui |
差分渲染和交互 | 把长任务状态变成可操作终端界面 |
packages/web-ui |
Web 组件 | 复用 agent 事件而不是重写模型层 |
packages/pods |
vLLM pod 管理工具 | 把 coding harness 与推理基础设施连接起来 |
默认执行链¶
用户输入
-> context files（AGENTS.md / CLAUDE.md）
-> model resolver + provider
-> read / write / edit / bash
-> tool result 回填上下文
-> session JSONL + tree branch
-> continue / fork / stop / RPC output
官方 quickstart 明确默认 coding tools 为 read、write、edit、bash，并提供可选的只读 grep、find、ls。这套最小工具面是 pi 的关键判断：让模型通过少数原子操作完成复杂任务，而不是预装几十个业务动作。
交互和自动化模式¶
| 模式 | 适合 | 代价 | 验证方式 |
|---|---|---|---|
| TUI | 人机协作 coding | 人在回路，自动化程度有限 | 记录工具审批、session 和中断 |
-p print |
CI、单次任务 | 需要自己处理退出码和输出 | JSON/文本输出 contract test |
--mode json |
机器消费事件 | schema 需要固定 | 对每类 event 做 parser 测试 |
--mode rpc |
被其他程序驱动 | 生命周期、并发和取消更复杂 | 启动、调用、取消、恢复测试 |
| SDK embedding | 作为企业 Agent 内核 | 需要理解 session 与 tool contract | 最小 host app + 回放集 |
session tree 是核心能力¶
pi 的 session 不是一条不可分叉的聊天记录，而是可继续、浏览、fork、clone 的树状事件流。对 FDE 有三个价值：
- 一个失败实验可以保留现场后从上一步分支。
- 模型切换和 thinking level 变化可以和同一任务对照。
- 评测器可以把一次运行导出为事件序列，而不只保存最终答案。
代价是存储与隐私治理更复杂。JSONL 可能包含完整代码、命令输出、密钥误打印和用户数据，必须设置目录权限、脱敏和保留期限。
可扩展点¶
- Extensions：新增命令、事件处理和 UI 行为。
- Skills：按需加载提示与工作方法，不必把所有规则塞入 system prompt。
- Provider/model resolver：模型与账户切换。
- RPC/SDK：被 IDE、CI 或企业服务驱动。
- AGENTS.md：项目级约束，启动时载入。
适用条件、代价、验证¶
适用条件¶
需要 Windows/Linux/macOS 终端协作、频繁切换模型、保留任务树、同时支持交互与 headless 的团队。
代价¶
pi 的“可组合但不强约束”意味着安全、审批和业务工具 contract 要由集成者补齐。默认 bash/编辑能力不能直接映射到生产写操作。
验证方式¶
- 用同一仓库跑交互、print、JSON 和 RPC 四条路径。
- 人为制造工具失败、上下文超限、模型切换和网络中断。
- 检查 session 是否能恢复、fork 是否保持正确上下文。
- 用 20 条 coding workload 比较模型切换对通过率、时延、成本的影响。
FDE 结论¶
pi 最适合作为 个人或团队内部的 coding harness 参考实现，也适合作为 dsh/Codex 的对照基线：它把 agent core、LLM adapter、TUI、会话和扩展拆得足够清楚。若要做企业平台，需要额外实现租户、集中策略、审批、审计、密钥隔离和资源配额。