Pi：极简主义，缺什么自己加

Pi 默认只给模型 4 个工具：read、bash、edit、write。没有权限审批，没有计划模式，没有子代理。缺什么，就用扩展、Skill、提示词模板自己补。安全靠 Git 和容器，不靠弹窗。

前面三个工具（Claude Code、Codex、OpenCode）把功能给全：计划模式、子代理、权限审批、待办清单，开箱就有。

Pi 走另一条路，核心压到最少，其余交给你。它的系统提示词很短，工具很少，模型做的每一步都摆在屏幕上，没有藏在后台的子代理。

缺什么就用 TypeScript 写一个扩展，或者装一个别人写好的包。想把一个 Agent 怎么跑起来的搞清楚，Pi 适合当样本：系统提示词短，工具只有四个，读起来没有多少要跳过的部分。

Pi 目前也是我用的最多的一个 Agent。

一、Pi 是什么

Pi 是 Mario Zechner（游戏框架 libGDX 的作者）开发的开源编程 Agent（MIT 协议），现在由 Earendil 团队维护，只有终端界面。

和 Claude Code 摆在一起看：

Pi 把工具压到四个，理由是：

• 上下文留给你的代码。工具越多，工具说明占掉的上下文越多。四个工具的说明很短，省下来的空间都是项目代码的
• 看得见才管得住。没有后台子代理，没有自动跑的计划，模型读了什么、改了什么、跑了什么命令，全在屏幕上
• 每个人要的不一样。内置一个大家凑合用的计划模式，不如给一个扩展接口，需要什么样的自己写

代价是开箱能做的事很少，尤其是没有权限审批这一点。

二、安装与接模型

1. 安装

# macOS / Linux，官方安装脚本
curl -fsSL https://pi.dev/install.sh | sh

# 或者用 npm（需要 Node.js 22.19 以上）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

2. 接入 DeepSeek

DeepSeek 是 Pi 的内置服务商，不用写配置。两种方式任选。

方式一，环境变量（推荐）：

# 写进 ~/.zshrc 或 ~/.bashrc
export DEEPSEEK_API_KEY="sk-你的key"

方式二，在界面里输入：启动 Pi 后输入 /login，选 DeepSeek，粘贴 Key。Key 会存进 ~/.pi/agent/auth.json，这个文件不要提交、不要外传。

配好后，不用进界面就能确认 Pi 认到了哪些 DeepSeek 模型：

pi --list-models deepseek

3. 第一次启动：信任这个项目吗

cd your-project
pi

如果项目里有 .pi/ 下的配置、扩展、Skill，或者 .agents/skills/，Pi 会先问信不信任这个项目：

它会先问一遍，因为扩展就是能执行的代码，Pi 启动时就会运行它。别人仓库里的 .pi/extensions/ 可能藏着任何东西，第一次进一个项目，得你点头才加载。

• Trust：信任，记到 ~/.pi/agent/trust.json，以后不再问
• Trust parent folder：把上一级目录整个信任了，适合放自己项目的那个文件夹
• this session only：只这一次
• Do not trust：不加载项目里的扩展、Skill、设置

两个要点：

• AGENTS.md、CLAUDE.md 不受信任与否影响，总会加载。所以陌生项目即使选了不信任，它的说明文件也可能指挥模型
• 信任只管启动时加载什么，管不住模型后面做什么。它不构成安全边界，后面细讲

以后想改主意，输入 /trust。

4. 认识界面

下面是配完本节入门部分之后的启动画面：

• 顶部的清单：Pi 这次加载了什么。[Context] 项目说明，[Skills] Skill，[Prompts] 提示词模板，[Extensions] 扩展。哪个没出现在这里就是没加载上，排查问题先看这里
• 左下 ~/order-admin (main)：当前目录和 Git 分支
• 左下 0.0%/1.0M (auto)：上下文用了多少，auto 表示满了会自动压缩
• 右下 deepseek-flash • high：当前模型和思考深度
• 中间那句 Pi can explain its own features and look up its docs：Pi 自带完整文档，不会用就直接问它，比如怎么给你写一个扩展

输入 /model，搜 deepseek 选模型。选中后按 Ctrl+S，会存成默认模型：

默认值存在 ~/.pi/agent/settings.json，也可以直接改：

{
  "defaultProvider": "deepseek",
  "defaultModel": "deepseek-flash",
  "defaultThinkingLevel": "high"
}

⚠️ Shift+Tab 在 Pi 里不切权限模式，它循环切换思考深度（off、low、medium、high……），右下角跟着变。Pi 没有权限模式这个概念。

三、概念对照表

输入 / 能搜索所有指令。扩展、提示词模板、Skill 加的指令也都在这里：

四、入门：15 分钟跑通一个工作流

还是用 order-admin 项目。跟着前两节配过 Codex、OpenCode 的话，AGENTS.md 和 .agents/skills/ 都能直接复用。

1. AGENTS.md

项目里有 AGENTS.md 或 CLAUDE.md，Pi 直接读，什么都不用做。启动画面顶部 [Context] 下面能看到它。

Pi 没有 /init。项目里什么都没有的话，直接让它写：

读一下这个项目，写一份 AGENTS.md：只写技术栈、常用命令、代码规范、禁止事项，不超过 30 行。

2. 先给 Pi 装上两道闸

Pi 不会问你任何事：改文件、删文件、跑任何命令，都直接执行。官方文档写得很直白，看着屏幕、点信任、事后看 diff，都不算安全措施。

所以动手前，先做两件事。

第一道闸：Git。每次让 Pi 干活前，先 git commit 一次。Pi 改坏了，git restore . 就回来了。

第二道闸：危险命令弹窗。Pi 自带一批示例扩展，其中 permission-gate.ts 会在模型要执行 rm -rf、sudo、chmod 777 这类命令时弹窗问你。把它装到用户目录，所有项目都生效：

# npm 安装的，示例在全局 node_modules 里
EX="$(npm root -g)/@earendil-works/pi-coding-agent/examples/extensions"
mkdir -p ~/.pi/agent/extensions
cp "$EX/permission-gate.ts" ~/.pi/agent/extensions/

用安装脚本装的，到 GitHub 仓库 earendil-works/pi 的 packages/coding-agent/examples/extensions/ 下载同名文件，放到同一个位置。

装好后重启 Pi（或者输入 /reload），启动画面的 [Extensions] 里会出现 permission-gate.ts。