一、Pi 简介

Pi（仓库 earendil-works/pi，官网 pi.dev）是一款 MIT 协议开源 的轻量级终端编码 Agent，也是一套可以嵌进你自己程序的 Agent 开发工具包（SDK）。

截至 2026 年 8 月，Pi 在 GitHub 上已收获 8.6 万+ Star、周下载量约 130 万次。更硬核的是：当下最火的明星开源项目 OpenClaw（38 万+ Star）就是基于 Pi 的 SDK 构建的——Pi 的终端界面组件、Agent 运行时都来自它；社区还衍生出了给 Pi 加上浏览器和子代理的 "Oh My Pi"（近 2 万 Star），以及 VS Code 插件 Pendant、Emacs 前端等。一句话：Pi 已经成了开源 Agent 开发的底层基座之一。

核心设计哲学：做减法

Pi 的 slogan 是 "There are many agent harnesses, but this one is yours."（Agent 外壳很多，但这个是你的）。它的设计逻辑和 Claude Code 这类"开箱即用全家桶"完全相反——只给你一个最小、可完全读懂的核心，其余一切靠扩展（Extension）补齐：

  • 默认只给模型 4 个工具：read（读文件）、write（写文件）、edit（精确改文件）、bash（跑命令）。

  • 系统提示词 + 工具描述加在一起 不到 1000 token，把宝贵的上下文留给你的项目代码和当前任务。

  • 没有内置 MCP、没有子代理、没有 Plan 模式、没有待办列表、没有权限确认弹窗、没有沙箱。

二、安装 Pi：一行命令搞定

环境要求

  • Node.js 20+

  • 支持 macOS / Linux / Windows

安装方式（任选其一）

# 方式 1：官方安装脚本（Linux / macOS，推荐）
curl -fsSL https://pi.dev/install.sh | sh

# 方式 2：PowerShell（Windows）
powershell -c "irm https://pi.dev/install.ps1 | iex"

# 方式 3：npm
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式 4：pnpm
pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式 5：bun
bun add -g --ignore-scripts @earendil-works/pi-coding-agent

⚠️ 务必带上 --ignore-scripts：这是官方明确推荐的参数。它会禁用依赖包的安装生命周期脚本——Pi 本身不需要这些脚本即可运行，禁掉能少一层供应链攻击面。配合精确版本锁定 + 2 天最小发布年龄，能有效挡住"当天被投毒的依赖"混进构建。

📦 包名变更提醒：2026 年 5 月，Pi 的包从 @mariozechner/* 作用域迁移到了 @earendil-works/*。凡是早于这个时间的旧教程指向 @mariozechner/pi-coding-agent 的都已废弃；老用户执行 pi update --self 即可自动迁移。

验证安装

pi --version

能正常打印版本号即安装成功。进入任意项目目录，直接敲 pi 即可启动交互界面。

三、认证与配置：接上模型就能跑

Pi 支持两种认证方式，二选一。

方式一：API Key（环境变量）

# 以 Anthropic 为例
export ANTHROPIC_API_KEY=sk-xxxx

# 进入项目目录启动
cd /path/to/your-project
pi

其他常见变量：OPENAI_API_KEY、GOOGLE_API_KEY、GITHUB_TOKEN（GitHub Copilot）等，也可写入 ~/.pi/agent/auth.json。

方式二：订阅登录（OAuth）

启动后在交互界面输入：

/login

Pi 内置了多家订阅的 OAuth 登录，支持 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot、Grok、Kimi For Coding、OpenAI Codex、OpenRouter、xAI 等。

项目级上下文

Pi 会分层加载项目指令，迁移现有仓库时几乎是"零成本"：

  • AGENTS.md：全局（~/.pi/agent/）→ 父目录 → 当前目录，逐级覆盖

  • CLAUDE.md：Pi 也读，所以从 Claude Code 项目迁移过来无需改动

  • SYSTEM.md：可替换/追加默认系统提示词

四、使用 Pi

1. 交互模式

cd /path/to/your-project
pi

启动后就是交互式终端界面，直接打字对话即可。第一次用可以让它先熟悉项目：

阅读这个项目，告诉我它的目录结构、启动方式和测试命令。

2. 一句话 / 脚本模式

# 非交互式执行一次性任务（适合脚本、CI）
pi -p "检查这个项目最近的改动，并列出可能的问题"

# JSON 事件流（方便程序消费）
pi -p "重构 utils 目录" --mode json

3. 继续 / 回放会话

pi -c   # 继续最近一次会话
pi -r   # 打开会话浏览器，挑选历史会话恢复

Pi 的会话是树状结构而非线性日志：走错方向了可以回到某个节点开新分支，原来的尝试都保留在同一个文件里（纯 JSONL，可以 grep）。常用导航命令：

  • /tree：在会话树里跳转任意历史节点

  • /fork / /clone：派生新分支

  • /share：导出到 GitHub Gist 拿到可渲染的分享链接

  • /export：导出为 HTML

4. 常用快捷键与符号

操作

说明

@ + 文件名

模糊搜索并引用项目文件

! + 命令

直接在终端跑 bash，结果发给模型

Ctrl+L

切换模型

Ctrl+P

在收藏模型间轮换

Shift+Tab

切换思考等级

Esc 按两次

打开对话树

Enter

发送"转向消息"（当前工具执行完后送达，可打断剩余工具）

Alt+Enter

发送"追问"（等 Agent 跑完再处理）

五、与其他 Agent 对比：极简派 vs 全家桶

下面把 Pi 和当前最主流的几款编码 Agent 放在一起看。核心差异不在于"谁功能多"，而在于设计范式：Pi 是"运行时/引擎"，其它多数是"产品"。

维度

Pi

Claude Code

OpenAI Codex CLI

OpenCode

WorkBuddy

定位

极简 Agent 引擎 + SDK

开箱即用全家桶

开源可审计 Agent

开源多模型 Agent

全场景桌面智能体

开源

✅ MIT

❌

✅ Apache 2.0

✅ MIT

❌

默认能力

仅 4 工具，其余靠扩展

子代理/Plan/hooks/MCP 全有

三档审批模式

75+ 模型、TUI

编程+文档+数据+海报

扩展性

⭐ 极强（TypeScript 扩展 + SDK）

中（hooks/MCP）

中（MCP）

强（工具/MCP）

中（Skills 生态）

沙箱/权限

❌ 无（自己负责）

✅ 审批流

✅ 三档审批

⚠️ 需自配

✅ 有

模型自由度

15+ 提供商，可本地 Ollama

仅 Claude

多 Provider

75+ 模型含本地

混元/DeepSeek 等

可嵌入自己程序

✅ SDK / RPC

❌

部分

❌

❌

上下文大小

<1000 token 系统提示（极省）

100 万 token 窗口

中等

可配

可配

适合人群

想完全掌控、想造自己 Agent 的开发者

要顶级代码质量、懒得配置的终端党

要开源审计 + Rust 实现

要免费 + 多模型 + 本地

不只写代码、要全场景办公

几个关键取舍

  • Pi vs Claude Code：Claude Code 把子代理、Plan 模式、hooks、MCP 都焊死了，装上就能用；Pi 一个都不给，全靠你扩展。想要"开箱全配齐"选 Claude Code，想要"完全读懂 + 自己掌控"选 Pi。注意 Pi 没有沙箱，而 Claude Code 有审批流。

  • Pi vs OpenCode：两者都 MIT 开源。OpenCode 开箱就有 75+ 模型和富交互 TUI，更像"免费的 Claude Code 替代品"；Pi 更底层、更克制，核心只有 4 工具，但它的 SDK 和扩展系统让它能变成你自己产品的引擎（OpenClaw 就是证明）。

  • Pi vs Codex CLI：Codex 用 Rust 写、Apache 2.0，有 Suggest / Auto-Edit / Full-Auto 三档审批粒度；Pi 用 TypeScript、连权限弹窗都没有，全交给你。要"开源 + 精细审批"选 Codex，要"极简 + 可嵌入"选 Pi。

  • Pi 的独特身份：它不是要跟谁抢"最佳编码助手"，而是给你一套可以 fork、可以嵌、可以发布的 Agent 底座。如果你只想写代码，它可能"一开始空荡荡"；如果你想造自己的 Agent 产品，它是目前最有趣的选择之一。