#从一个小 Agent 读懂 Pi

本系列基于 Pi v0.85.1 源码。不是官方文档的翻译，而是一条读码路径：先做一个很小的 Agent，再看 Pi 为了让它真正能用，加了哪些边界。

如果你只有半小时，先读 从一个最小 Agent 开始。读完后，你应该能用自己的话解释：模型为什么需要工具、Agent 为什么需要循环，以及这些东西在 Pi 里分别落在哪一层。

#系列导航

#速览：Pi 是什么？

Pi 是一个终端里的编码 Agent。它把三件事分开：

用户输入
  → 模型决定“直接回答”还是“调用工具”
  → 程序校验并执行工具
  → 把结果交回模型
  → 重复，直到得到最终回答

对应到源码，先记住三个角色：

日常使用的主路径是：

CLI / TUI
  → AgentSession（消息预处理、压缩、扩展、会话）
  → Agent（生命周期）
  → runAgentLoop（LLM → 工具 → 再 LLM）
  → streamFn
  → ModelRuntime.streamSimple()
  → Provider

AgentHarness 也在仓库里，但是更通用、偏实验性的会话运行时。读 pi 命令本身时，不要从它开始。

#读完后你会得到什么？

1. 能用自己的话解释 Agent，而不是只会背 API 名称。
2. 能写出一个带工具的简易 Agent，并知道它还缺哪些生产能力。
3. 能沿着一次真实输入读懂 Pi 的核心源码。
4. 知道项目信任、认证和压缩各自守哪条边界。
5. 再按需要学习 Extension、Skill、自定义 Provider 和 TUI。

#快速开始

仓库用 npm workspaces，不是 pnpm。开发规则见上游 AGENTS.md。

git clone https://github.com/earendil-works/pi.git
cd pi
npm install --ignore-scripts
npm run check

从源码运行，优先用仓库脚本（它会保留你当前的工作目录）：

./pi-test.sh

要给单个入口打断点时，再用 TypeScript 源码：

npx tsx packages/coding-agent/src/cli.ts --help

Node.js 要求 >= 22.19.0。日常读码不需要先 npm run build。