Pi：79K Star 的 AI Agent 编码框架，把 Claude Code 变成了可插拔的工具箱

一个被忽视的真相：Coding Agent 最大的痛点不是"写不出代码"，而是"无法按你的习惯干活"

用过 Claude Code、Codex、或者任何其他 Coding Agent 的人都有这种体验——同样的 bug，Agent 今天修得好好的，明天可能就搞砸了；同样的功能，这次的实现风格和上次完全不一样。Agent 的默认工作流是你只能接受的，想要个性化？除非你去改它的源代码。

Pi 的思路很激进：让 Agent 成为可插拔的工具箱，而不是黑盒。它不提供"终极 AI 解决方案"，而是提供一个最简核心——交互式的终端对话界面 + 四个基本工具（read/write/edit/bash）——然后把所有扩展能力交给开发者自己组装。这听起来简单，但正是这种"做减法"的设计哲学，让 Pi 在短短几个月内拿下了 79,587 Star。

它到底做了什么：一个四包 monorepo 的极致拆解

Pi 的核心是一个 TypeScript monorepo，分为四个独立又相互协作的包：

包	作用	核心技术
`@earendil-works/pi-ai`	统一多提供商 LLM API 层	OpenAI/Anthropic/Gemini/Bedrock 等 26+ 提供商抽象
`@earendil-works/pi-agent-core`	Agent 运行时 + 状态管理	工具调用、会话状态、分支管理
`@earendil-works/pi-coding-agent`	交互式终端编码 Agent CLI	Bun 运行时、TUI、命令系统
`@earendil-works/pi-tui`	终端 UI 库（差分渲染）	高性能终端渲染、事件处理

核心特性：为什么它比 Claude Code 更"听指挥"

① 四重运行模式：不只是命令行

Pi 支持四种模式，适应不同的使用场景：

交互式模式（默认）—— 终端对话，支持快捷键、文件引用、内置编辑器
打印模式 —— 适合脚本和非交互式调用
JSON 模式 —— 程序化调用，输出结构化 JSON
RPC 模式 —— 用于进程集成，可以被其他工具调用

② 自定义能力的三大支柱

这是 Pi 最独特的设计。你可以通过三种方式扩展 Pi 的能力，每种都有不同的灵活性和成本：

扩展方式	灵活性	开发难度	典型用例
Skills	中——能力包标准化	低——Markdown 文件	特定领域的任务流程
Prompt Templates	高——控制 Agent 语气和格式	低——Markdown 片段	代码审查、文档生成、错误分析
Extensions（TypeScript）	极高——任意功能	中——TypeScript 模块	自定义工具、权限控制、UI 组件

③ 会话管理：像 Git 一样管理 AI 对话

Pi 的会话以 JSONL 文件存储，支持树形分支。你可以：

/tree —— 在会话树中导航，跳转到任意历史点继续
/fork —— 从某个历史点创建新分支
/clone —— 复制当前分支到新会话
--session / --fork CLI 参数——从命令行恢复会话

这意味着你可以随时"回退到昨天的修改方向"，而不需要重头再来——这对长周期任务简直是救命功能。

④ 上下文压缩：自动保存 Token

Pi 默认启用自动压缩。当上下文接近限制时，它会自动对旧消息进行总结，保留近期对话。这是类似 Headroom 的内置功能，不需要额外配置。

对比：Pi vs Claude Code vs Codex

特性	Claude Code	Codex / GitHub Copilot CLI	Pi
扩展方式	有限，通过 built-in commands	受限，插件系统不完整	Skills / Prompt / Extensions 三层扩展
会话管理	简单，无分支	无	树形分支会话，可回溯
模型提供商	Claude 为主	Codex 为主	26+ 提供商，自由切换
自定义能力	难	难	TypeScript Extensions，几乎什么都可以做
安装	简单	简单	npm / curl，但需要 Bun 运行时
配置	默认即可用	默认即可用	深度可配置，但配置项多

踩坑指南：真实体验中的三个问题

在实际使用 Pi 的过程中，我发现以下三个问题值得特别注意：

坑 1：Bun 依赖是双刃剑

Pi 使用 Bun 作为 JavaScript 运行时，这带来了极快的启动速度，但也是一个潜在的门槛。如果你不熟悉 Bun，或者在某些受限环境中（如某些 CI 环境、受限的生产服务器），安装 Bun 可能会成为障碍。

建议：先在本地试用，确认 Bun 在你的工作流中没问题后再深入使用。如果 Bun 不可用，Pi 仍然可以运行，但部分功能可能受限。

坑 2：项目信任机制的摩擦

Pi 引入了项目信任机制：当进入一个新目录时，Pi 会询问你是否信任该项目，以便加载项目本地的 `.pi/` 配置和扩展。这个机制是为了安全，但频繁信任同一个项目会让人烦躁。

解决：使用 `/trust` 命令保存信任决策，或者在 `~/.pi/agent/settings.json` 中设置 "defaultProjectTrust": "always"（注意安全风险）。

坑 3：Telemetry 和数据隐私

Pi 默认会发送安装遥测和更新检查。虽然只是匿名数据，但如果你的工作流对隐私有严格要求（如处理企业代码），这些行为可能会让你不舒服。

解决：设置 PI_TELEMETRY=0 和 PI_SKIP_VERSION_CHECK=1 环境变量来禁用这些功能，或者使用 --offline 启动。

快速上手：5 分钟体验 Pi

最简单的方式（假设你已经有 API 密钥）：

# 方式 1：通过 npm 安装全局 CLI
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式 2：通过安装脚本（推荐）
curl -fsSL https://pi.dev/install.sh | sh

# 设置 API 密钥（以 Claude 为例）
export ANTHROPIC_API_KEY=sk-xxx...

# 启动 pi
pi

# 首次运行会提示你：
# 1. 选择模型提供商
# 2. 选择模型（如 claude-3-5-sonnet）
# 3. 开始对话！

几个值得玩味的命令

命令	说明
`pi -c`	继续最近的会话
`pi -r`	浏览并选择历史会话
`pi --no-session`	临时模式（不保存会话）
`pi --name "我的任务"`	设置会话显示名称
`/model`	在交互模式下切换模型（也可以用 Ctrl+L）
`@`	在编辑器中模糊搜索项目文件
`!command`	执行 bash 命令并把输出发送给 Agent

扩展实战：写一个自己的 Extension

Pi 的 Extension 是 TypeScript 模块，可以注册自定义工具、命令、事件监听器。以下是一个简单的示例，展示如何创建一个自动提交 git 更改的扩展：

// ~/pi/agent/extensions/auto-commit.ts

export default function (pi) {
  pi.registerTool({
    name: "auto-commit",
    description: "自动提交当前工作区的更改",
    parameters: {
      type: "object",
      properties: {
        message: { type: "string", description: "提交信息" }
      }
    },
    async execute({ message }) {
      // 获取文件列表
      const files = await pi.getChangedFiles();
      if (files.length === 0) {
        return "没有文件需要提交";
      }

      // 执行 git 操作
      await pi.executeCommand("git add .");
      await pi.executeCommand(`git commit -m "${message || 'auto-commit'}"`);
      await pi.executeCommand("git push");

      return `✅ 已提交 ${files.length} 个文件`;
    }
  });

  pi.registerCommand("commit", {
    description: "快速提交代码",
    handler: async () => {
      const message = prompt("提交信息（回车则使用默认）:");
      await pi.callTool("auto-commit", { message });
    }
  });
}

总结：为什么 Pi 值得你花 10 分钟试试

Pi 做了一个重要的方向性选择：在 AI 编码时代，可组合性比开箱即用更重要。Claude Code 和类似工具提供了开箱即用的体验，但你无法控制它们如何工作；Pi 提供了一个极简内核，然后把控制权完全交还给你。

如果你发现自己经常需要：

🔁 在不同的 LLM 提供商之间切换而不想重置工作流
🎨 让 Agent 按照你的代码规范、风格、工具链习惯干活
📝 保存和回溯长时间的对话历史（像 Git 一样）
🔧 给 Agent 添加特定于你项目或工作流的能力

那么 Pi 值得一试。它的 79K Star 不是偶然的——它解决的是 AI 编码领域最本质的问题：如何让 Agent真正听你的话，而不是让你的 Agent 听它的话。

项目信息：GitHub | 官网 | 文档 | MIT 协议 | 79,587 Star