Pi：一个故意不替你做决定的 Coding Agent
痛点切入
现在的 coding agent 工具越来越像完整 IDE：计划模式、子代理、权限弹窗、任务列表、MCP、记忆系统，一个都不少。问题是，你不一定想要它们。
有些团队需要的不是一个把工作流全部接管的黑盒，而是一个能嵌进自己流程里的 agent harness。工具要能换，模型要能换，UI 要能改，权限策略要能自己写。最好别逼你接受它内置的“最佳实践”。
Pi 有意思的地方就在这里。它不是“Claude Code 的平替”，也不是“Cursor 的终端版”。它更像一个故意保持小核心的 coding agent 底座：默认能用，但真正的重点是你可以把它改成自己的工作台。如果你关心 agent harness 的整体架构，可以先看站内的 Agent Harness 架构解析。
项目简介
Pi 是 earendil-works 开源的 TypeScript agent harness monorepo，MIT 协议，GitHub 当前是五万星量级项目。仓库最近仍有活跃提交，主语言是 TypeScript。
它主要拆成四个包：
- @earendil-works/pi-coding-agent：交互式终端 coding agent CLI
- @earendil-works/pi-agent-core：带工具调用、状态管理和事件流的 agent runtime
- @earendil-works/pi-ai：统一的多 provider LLM API
- @earendil-works/pi-tui：支持差分渲染的终端 UI 组件库
这个拆法说明 Pi 的野心不只是做一个命令行工具。coding-agent 是产品形态，agent-core 和 pi-ai 才是更底层的可嵌入能力。你可以直接用 CLI，也可以把 runtime 嵌进自己的应用。
为什么是它
Pi 的设计哲学很鲜明：核心尽量少做判断，扩展点尽量多暴露。
官方 README 里直接写了它跳过一些常见功能：没有内置 sub-agents、没有 plan mode、没有内置 to-do、没有权限弹窗、没有 MCP。乍看像缺功能，但这其实是它的观点。
它不是说这些能力没用，而是说这些能力不应该全部硬编码进核心。你可以用 extensions、skills、prompt templates、themes，或者第三方 pi packages 加回来。这个取舍很适合已经有自己工程规范的团队。
和 Claude Code / Cursor 的区别
Claude Code 和 Cursor 的优势是“打开就有完整体验”。Pi 的优势是“你能拆开改”。
如果你只想让 AI 帮你改几处代码，Pi 不一定更省心。安装、provider、扩展、权限策略都需要你理解一点。但如果你想做下面这些事，Pi 的结构会更舒服：
- 给 agent 加内部工具，但不想等上游支持
- 把 agent runtime 嵌进自己的 Web / Slack / 桌面应用
- 用不同 provider 之间切模型，保留上下文
- 自己定义权限、沙箱、审批和审计流程
- 把 prompt、skills、themes 打包成团队共享包
Pi 不是更“傻瓜”的工具，它是更“可塑”的工具。
快速上手
官方推荐的全局安装方式很直接：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent也可以用安装脚本：
curl -fsSL https://pi.dev/install.sh | sh如果你用 API key：
export ANTHROPIC_API_KEY=sk-ant-...
pi如果你想用已有订阅，可以进入 Pi 后执行：
/login默认情况下，Pi 给模型四个工具：read、write、edit、bash。这个默认集很克制，也很好理解。你要更多能力，就通过 skills、extensions 或 pi packages 增加。
亮点代码
Pi 最值得看的不是 CLI 命令，而是它的 runtime 可以被直接嵌入。
比如用 @earendil-works/pi-agent-core 起一个最小 agent：
import { Agent } from "@earendil-works/pi-agent-core";
import { getModel } from "@earendil-works/pi-ai";
const agent = new Agent({
initialState: {
systemPrompt: "You are a helpful assistant.",
model: getModel("anthropic", "claude-sonnet-4-20250514"),
},
});
agent.subscribe((event) => {
if (
event.type === "message_update" &&
event.assistantMessageEvent.type === "text_delta"
) {
process.stdout.write(event.assistantMessageEvent.delta);
}
});
await agent.prompt("Hello!");这段代码体现了 Pi 的真正价值：它把 agent 运行循环、消息流、工具执行、状态管理拆成了可组合 API。你可以用它做终端工具，也可以做自己的产品内 agent。
再看 pi-ai 的方向，它不是只包一层 OpenAI SDK。它维护了统一的 provider / model 抽象，覆盖 Anthropic、OpenAI、Azure OpenAI、Google、Vertex AI、Mistral、Groq、xAI、OpenRouter、Vercel AI Gateway、GitHub Copilot、Amazon Bedrock、DeepSeek、Kimi、MiniMax、Xiaomi MiMo 等 provider。
对 agent 应用来说，这件事很重要。模型层不是静态依赖，而是经常会被成本、质量、速率限制、地区可用性和订阅策略影响。Pi 把“换模型”当成一等能力，而不是事后补丁。
社区与生态
从 GitHub 元信息看，Pi 已经是五万星量级、数千 fork 的项目，且在 2026 年 5 月 23 日仍有活跃 push。仓库开启了 Issues、Discussions 和 PR。
但它的贡献策略比较强势：新贡献者提交的新 Issue 和 PR 默认会被自动关闭，维护者每天 review 自动关闭的内容。这个策略可能会让第一次贡献的人有点不适，但也说明维护者在控制噪音。
我更喜欢它在供应链安全上的态度。README 明确说 npm 依赖变更按代码变更审查：直接外部依赖精确锁版本，package-lock 是依赖真相，发布 CLI 包时带 shrinkwrap，CI 使用 ignore-scripts，并且有 npm audit 和签名审计。
这不是装饰性安全说明。对一个会执行本地命令、安装扩展、运行第三方包的 coding agent 来说，供应链安全就是核心功能的一部分。
适用场景与局限
Pi 适合三类人。
第一类是想要可控 coding agent 的开发者。你不满足于固定工具集，想自己加工具、改 prompt、换 UI、调 provider。Pi 的扩展机制会很合口味。
第二类是做 agent 产品的团队。你可以把 pi-agent-core 和 pi-ai 当底座，用自己的前端、权限系统和业务工具包起来。
第三类是研究 agent 工作流的人。Pi 的 session、branching、compaction、tool events、provider handoff 都比较透明，适合观察 agent 如何真实工作。
但别把 Pi 当成“开箱即用体验最省心”的选择。
它要求 Node 22.19 以上，生态还在快速变化。它刻意不内置 MCP、plan mode、sub-agents、permission popups，这些能力都要靠你自己装、写或接受第三方包。Pi packages 和 extensions 还拥有完整系统访问权限，安装前必须看源码。
换句话说，Pi 适合愿意掌控工具的人，不适合只想点开就开始的人。
结论
Pi 最值得关注的地方不是“又一个 coding agent CLI”，而是它把 coding agent 做成了可拆、可嵌、可扩展的 TypeScript runtime。
如果你正在做自己的 agent 工作流，或者觉得现成工具的默认设计太重，Pi 值得认真研究。它不会替你决定工作方式，但会给你足够多的钩子，把工作方式做出来。
