Pi 是 earendil-works 团队的开源 AI agent 工具包，一个 TypeScript 写的 monorepo，MIT 协议。截至 2026 年 7 月底，79,473 颗星、9,769 个 fork，排 GitHub 本周榜第 9。仓库 2025 年 8 月 9 日创建，不到一年长到这个体量，最新版 v0.82.1，还在 pre-1.0 快速迭代。它干的事一句话能说明白：给你一套从统一 LLM 接口、agent 运行时、终端 UI 到交互式 coding agent 的完整工具链，而且是「self extensible」——agent 能扩展自己的能力边界。核心是四个 npm 包：@earendil-works/pi-ai（统一多家 provider 的 LLM API）、@earendil-works/pi-agent-core（带工具调用和状态管理的 agent 运行时）、@earendil-works/pi-tui（差分渲染终端 UI 库）、@earendil-works/pi-coding-agent（交互式 coding agent CLI，旗舰产品）。
解决什么痛点
想把 AI agent 跑起来的人大多踩过这几样：要支持多家 LLM provider 就得各自封装 SDK，OpenAI 一套、Anthropic 一套、Google 一套，接口签名各不相同，换模型等于重写调用层；agent 不只是「调一次 LLM」，它得能调工具、记状态、跨多轮把任务推进到底，从零搭这套循环很容易写到一半发现状态管理是黑洞；想让 agent 在终端里有像样的交互界面，又得自己啃 terminal 渲染、输入处理、刷新逻辑；最后真要落地一个 coding agent，权限、容器化、扩展性全是坑。Pi 把这些拆成四个可独立用的包：pi-ai 解决模型层、pi-agent-core 解决运行时、pi-tui 解决界面、pi-coding-agent 把前三者攒成一个能用的 coding agent。核心定位是「给你建 agent 的积木，外加一个开箱即用的旗舰」，不是「再给你一个黑盒 CLI」。
统一 LLM API：一套接口打穿 OpenAI/Anthropic/Google
最底层是 @earendil-works/pi-ai。它给的是一个统一的多 provider LLM API，把 OpenAI、Anthropic、Google 等家接到同一套接口后面。直接后果是：你的 agent 代码不绑死某一家，今天跑 Claude，明天切 GPT，后天换 Gemini，调用层不用动。这对 agent 开发者意义在于——做评测、做 fallback、做成本控制时不用维护三份 provider 适配代码。包以 npm 发，@earendil-works/pi-ai 直接装。注意 README 对这个包的描述是「Unified multi-provider LLM API」，没公开具体方法签名和 provider 全名单（「etc.」说明不止三家），要确认支持范围得看包内的 provider model data，npm run build 时会刷新这份模型数据。
Agent 运行时：工具调用 + 状态管理
往上一层是 @earendil-works/pi-agent-core，agent 的运行时。README 给它的定位是「Agent runtime with tool calling and state management」——两件事：一是 tool calling，LLM 能调用外部工具（读文件、跑命令、查 API），不只生成文本；二是 state management，跨多轮对话和工具调用把状态管住，让 agent 能把一个长任务拆成多步推进而不是每轮失忆。这是把「LLM wrapper」和「agent」分开的关键：前者调一次模型返回，后者能循环、能记、能调用外部世界。Pi 的整套 agent 能力（包括后面的 coding agent）都跑在这个运行时上。想自己造 agent 而不是用现成 coding agent 的人，这个包是入口。
TUI：差分渲染的终端 UI 库
第三个包是 @earendil-works/pi-tui，一个终端 UI 库，卖点是 differential rendering——差分渲染，只重绘屏幕上变化的部分，不是每帧全刷。这在终端应用里意味着刷新快、闪烁少、能撑住复杂界面。它不是给最终用户的，是给「想给自己 agent 配个像样终端界面」的开发者用的。Pi 自己的 coding agent 交互界面就建在它上面。如果你的 agent 需要流式输出、工具调用进度、可滚动历史记录这种交互，pi-tui 省掉从零写 curses/Ink 的活。
Coding Agent CLI：自扩展的命令行
旗舰是 @earendil-works/pi-coding-agent，README 里强调这是「self extensible coding agent」——自扩展。意思是 agent 的能力边界不是写死的，可以扩展。它走 npm 发布，装完拿到 pi 这个命令，交互式跑。README 还提到 ! 命令这套内置工具入口，以及 pi update --self 做自更新。权限这块 README 说得很直白：Pi 没有内置权限系统，默认以启动它的用户和进程权限运行——也就是你能碰的文件它都能碰。要更硬的隔离，官方给了三种容器化方案：Gondolin 扩展（把工具和 ! 命令路由进本地 Linux micro-VM，provider 认证留宿主机）、纯 Docker（整个 pi 进程塞容器）、OpenShell（策略控制的沙箱）。对 coding agent 这种要读写文件、跑命令的场景，这个权限模型必须先想清楚再上生产。
三分钟上手
# 1. 装（需要 Node + npm）
npm install -g @earendil-works/pi-coding-agent
# 2. 配 provider key（任选一家）
export OPENAI_API_KEY=sk-... # 或 ANTHROPIC_API_KEY / GOOGLE_API_KEY
# 3. 最小可跑
pi # 启动交互式 coding agent，自然语言下指令
# 从源码跑（仓库里）：./pi-test.sh，可从任意目录执行只想用其中某个包也行：npm install @earendil-works/pi-ai 单装统一 LLM API，或 @earendil-works/pi-agent-core 单装运行时，四个包彼此可独立用。想看官方演示和文档去 pi.dev，文档地址 pi.dev/docs/latest，README 还提了一句「你也可以直接让 agent 解释它自己」。
适合谁 + 五个踩坑
适合：要搭自己的 AI agent、不想从零写 provider 适配和 agent 循环的开发者；想要一个开源、模型可换、能自扩展的 coding agent 替代闭源方案的人；要在终端里做 agent 交互界面、想省掉 TUI 底层活的开发者；需要把 coding agent 塞进容器化流水线、对隔离有要求的团队。
踩坑记五条。一是没权限系统，默认以你的用户权限跑，能读写你能碰的所有文件，生产用必须容器化，官方给的三条路里 Gondolin 留宿主认证、Docker 最省事、OpenShell 适合要策略控制的场景。二是 pre-1.0（v0.82.1），API 还在动，升级前看 changelog，别无脑 pi update --self。三是新贡献者的 issue 和 PR 默认自动关，维护者每天审，想贡献得先读懂 CONTRIBUTING.md 这套流程，别一上来发 PR 就被打回。四是「self extensible」加「无权限」等于 agent 能改自己的行为又能碰你的文件，跑陌生任务前看清楚它要干什么，别放手让它盲跑。五是 TypeScript/npm 生态，Python/Rust 团队得先装 Node 工具链，不是 pip install 就完事。
和竞品比
和 Claude Code 比，Claude Code 是 Anthropic 的闭源 CLI、绑死 Claude 模型，打磨成熟开箱即用；Pi 是 MIT 开源、模型层靠 pi-ai 通吃多家 provider、能自扩展，定位是「给你积木和一个能改的旗舰 agent」，要可控和可改选 Pi，要现成省事选 Claude Code。和 Codex（OpenAI）比同理，闭源、绑 OpenAI 模型，Pi 给你换 provider 的自由和源码。和 Aider 比，Aider 是开源的 git 配对编程工具、Python 写、聚焦在 git 工作流里的代码编辑；Pi 是 TypeScript 的完整 agent harness（LLM API + 运行时 + TUI + coding CLI），范围比 git 编辑宽，还多一个自扩展 agent 的角度。Pi 的差异化在于它不是单一 agent，是一整套可拆开单独用的积木加一个自扩展旗舰——你可以只拿 pi-ai 给自家 agent 换模型，也可以直接用 pi-coding-agent 开箱跑。
参考来源
- Pi GitHub 仓库（79,473 star，MIT，TypeScript）：https://github.com/earendil-works/pi
- 官方网站与文档（演示 + pi.dev/docs/latest）：https://pi.dev
- npm 包 @earendil-works/pi-coding-agent：https://www.npmjs.com/package/@earendil-works/pi-coding-agent
- 容器化方案（Gondolin / Docker / OpenShell）：https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/containerization.md
- Pi RFCs（长期规划）：https://rfc.earendil.com/keyword/pi/
- Discord 社区：https://discord.com/invite/3cU7Bz4UPx