从一个小 Agent 读懂 Pi
本系列文档基于 Pi v0.80.10 源码。我们不从一堆目录和术语开始，而是先做一个很小的 Agent，再一步步看 Pi 为了让它真正可用，增加了哪些能力。
如果你只想先抓住重点，请从 从一个最小 Agent 开始 开始。读完它，你应该能用自己的话解释：模型为什么需要工具、Agent 为什么需要循环，以及 Pi 的源码里这些东西分别在哪里。
系列导航
速览：Pi 是什么？
Pi 是一个终端 AI 编码智能体（Terminal AI Coding Agent）。它的核心理念：
先记住三个角色
注意：
pi-ai和pi-coding-agent的文件数看起来很多，其中相当一部分是按 Provider 生成的模型目录（providers/*.models.ts）和工具实现，手写核心逻辑仍然集中在几千行内。
一句话理解 Agent
Pi 的关键设计是把“决定下一步”和“真正执行”分开：Agent Loop 不直接处理 API key，也不绑定某一家模型，而是通过 streamFn 请求模型。coding-agent 再用 ModelRuntime 接上模型、认证、配置和 Provider。
读完后你会得到什么？
读完本系列，你将：
- 能用自己的话解释 Agent，而不是只会背 API 名称。
- 能写出一个带工具的简易 Agent，并知道它还缺少哪些生产能力。
- 能沿着一条真实请求读懂 Pi 的核心源码。
- 理解 Pi 为什么强调可扩展、可替换和把安全边界交给程序控制。
- 再按需要学习 Extension、Skill、Tool、自定义 Provider 和 TUI。
快速开始
Node.js 版本要求以源码仓库的
package.json和 CI 配置为准。开发时可以直接用仓库提供的脚本运行检查；需要追踪单个入口时，再使用tsx运行 TypeScript 源码。
阅读建议
如果你只有半小时：
- 读 从一个最小 Agent 开始。
- 只看 从输入到 LLM 循环 的“Agent Loop”部分。
- 回到这里，再选择你感兴趣的方向。
然后按需深入：
- 做扩展开发 → 核心架构与设计哲学 的扩展系统部分 + 项目信任与认证体系
- 做 TUI 定制 → 核心架构与设计哲学 的 TUI 部分
- 做长会话优化 → 上下文压缩与会话分支