译 > 设置并使用 Pi 编码代理

本文已获得原作者的电子邮件书面许可翻译并发布，版权所有归属原作者。

我用 AI 编码工具已经有一段时间了。写本文时，我订阅了 Cursor 和 OpenAI Codex。它们各有所长，我在大部分主要项目中都使用它们工作。

但在两周前，我偶然遇见了 Pi——又一个开源的终端编码代理。它的核心很小，允许你通过扩展和包添加功能，而不是一开始就把所有东西都塞进去。我很喜欢这个想法，所以我决定配置它，看看它适合什么地方。

我还在摸索最佳平衡点，不过 Pi 已经在我的业余项目和实验中找到了位置。在本文中，我将分享我是如何安装、配置它，以及我目前的真实体验。

Pi 是由 Mario Zechner 创建的开源终端编码代理。运行在终端里，它默认给 AI 大模型提供四个工具——read、write、edit 和 bash——以便处理你的代码库。

它没有内置的计划模式、子代理、MCP，也没有权限弹窗。这些功能需要通过扩展 (extensions)、技能 (skills) 和包 (packages) 来添加。保持核心精简，允许你构建完全符合自身需求的环境。

Pi 支持很多 AI 提供商——Anthropic、OpenAI、DeepSeek、Google Gemini、Groq、xAI、OpenRouter、Kimi 等等，你可以使用 API 密钥或现有订阅登录。

目前，我会针对不同类型的工作切换不同的工具：

Pi 很适合业余项目，因为它非常快速、轻量，因此我可以放心使用更便宜的模型，而不必消耗昂贵的订阅额度。

举个例子：我最近用 Pi 搭配 DeepSeek v4 Flash，从一个网站抓取了 28.5 万个 URL。整个任务跑了大约 1.5 小时，使用 DeepSeek 官方 API 只花了 1 美元。我还用 pi-codex-goal 扩展来跟踪这个长时间运行的任务，过程非常顺利。你可以 在 X 上了解更多细节。

安装 Pi 只需要一条命令：

curl -fsSL https://pi.dev/install.sh | sh

安装完成后，在终端输入 pi 即可启动。不过在此之前，你至少需要配置一个 AI 提供商和 API Key。

Pi 内置的 /login 命令，配置任意提供商都很方便。我是这样做的：

就这样，Pi 会保存密钥，你就可以开始用了。登录后，再用 /model 选择模型——我选的是 deepseek-v4-pro，并把思考强度设为 xhigh。

我默认使用 xhigh 思考模式，因为我希望模型在动手修改前先进行充分思考。对于像 URL 抓取这类更轻的任务，我会切换到更快、更便宜的 deepseek-v4-flash 模型。

使用 Ctrl+L 打开模型选择器，Ctrl+P 在可用的模型之间循环切换，Shift+Tab 用于调整思考等级。

我还会根据任务使用 Kimi K2.7 Code 和其他模型，更多详情请参见下面的型号列表。

我启用了多个模型，并根据不同类型的任务来切换：

切换是实时的——Ctrl+L 打开模型选择器，Ctrl+P 在可用的模型之间循环切换。

打开 Pi 后，界面很干净：编辑器在底部，对话在中间，页脚会显示当前工作目录、Git 分支、当前模型、思考等级以及上下文窗口的使用情况。

我最开始自定义的一项内容是页脚。默认页脚显示的信息比我需要的更多，所以我让 Pi 自己帮我制作里一个极简页脚。我描述里我的需求——当前路径、带脏标记的 Git 分支、模型名、思考等级、pi-codex-goal 的当前目标，以及一个紧凑的上下文栏——它就直接帮我写好了 TypeScript 扩展。

把扩展放在 ~/.pi/agent/extensions/minimal-footer.ts，Pi 每次启动时都会自动加载它。我把代码放到 GitHub Gist 上了——只要把它放进扩展目录，然后重启 Pi 就行。虽然只是个小改动，但体验一下子变得个性化了。在这个过程中，我对 Pi 扩展的工作机制也有了一些了解。

Pi 的包是把扩展、技能、提示词和主题打包在一起的 npm 包或者 git 包。你可以用 pi install 命令来安装。下面是我在使用的：

这个包让 Pi 能够搜索网页、抓取页面内容、提取 YouTube 视频字幕，以及浏览 GitHub 仓库。你可以在 pi.dev/packages/pi-web-access 找到它。

pi install npm:pi-web-access

它开箱即用地支持 Exa 搜索，不需要 API Key；也可以按需接入 Perplexity、Exa 或 Gemini 的 API Key，以获得更强的控制。通过创建 ~/.pi/web-search.json 文件，我把默认搜索提供商设成了 Exa：

{
  "provider": "exa",
  "allowBrowserCookies": false,
  "summaryModel": "deepseek/deepseek-v4-flash",
  "workflow": "none",
  "curatorTimeoutSeconds": 20
}

有了这个包，Pi 就能直接在终端里完成网页搜索、文档阅读、YouTube 内容理解，以及 GitHub 仓库的克隆和浏览。

这个包给 Pi 增加了目标跟踪能力，由 Mitch Fultz 开发。它给模型新增了三个工具——get_goal、create_goal 和 update_goal——可以用来创建长时间运行的任务并跟踪进度。

pi install npm:pi-codex-goal

凡是跨越多个提示词的大任务，我都会用它。这样我不用每次都重复上下文，只需要先创建一个目标，Pi 就会帮我记住接下来要做什么。它在 28.5 万个 URL 的抓取任务里特别有用——即使会话拉得很长，目标也能让任务一直保持在轨道上执行。

DeepSeek 不能看图——它没有视觉能力。pi-vision-proxy 这个包通过把图片转发给另一个具备视觉能力的模型，解决了这个问题。

pi install npm:pi-vision-proxy

我把 Kimi K2.6 设置为视觉模型。现在，每次我把图片粘贴进 Pi，它都会先把图片和一些上下文发给 Kimi，然后 DeepSeek 再根据 Kimi 看见的内容继续完成任务。对于我偶尔丢进去的截图或设计参考，这个流程很好用。

在底层，它会尽可能把多张图片批量处理，并用感知哈希缓存重复截图，这样同一张图就不会被重复分析。它还支持几种 grounding (落地) 格式1，方便在需要时精确定位坐标。你可以 在 X 上阅读 更多关于这套配置的内容，我也在那条帖子里附了一个简短的视频。

这个包给 Pi 在终端里提供了一个真正的浏览器。它可以打开页面、截屏、生成快照、点击链接、填写表单、执行 QA 检查、提取页面内容——全都不用离开终端。

pi install npm:pi-agent-browser-native

我会把它和 pi-web-access 一起用。网页搜索负责找信息，浏览器负责和真实页面交互、阅读需要 JavaScript 的文档、以及进行视觉检查。它还增加了 agent_browser_web_search 工具，这是一种比打开完整浏览器页面更快的网页搜索方式。

如果你已经付费订阅了 Cursor，这个包可以让你在 Pi 里直接用它，这样无需额外付费。

pi install npm:pi-cursor-sdk

我订阅了 Cursor，所以这个包很自然地就用上了。安装后，cursor/auto 会出现在模型选择里，我可以像使用其他提供商一样使用它。这个包也同样是由 Mitch Fultz 开发的，他也是 pi-codex-goal 的作者。在 Cursor 负责订阅模型、DeepSeek 负责便宜而重的活、Kimi 作为备选的组合下，我的覆盖面已经很好了，而且没有增加更多的 API 费用。我在 原始笔记 里写过更多通过这个 SDK 使用 Composer 2.5 模型的内容。

Pi 给模型下指令有两种方式：AGENTS.md 用于项目特定的上下文约束，APPEND_SYSTEM.md 用于全局行为规则。

Pi 启动时会加载 AGENTS.md 文件，并把它们注入系统提示词里。它会按三个位置查找：全局位置 ~/.pi/agent/AGENTS.md，然后向上遍历父目录，最后是当前目录；这些内容会全部拼接起来。

我把全局的 AGENTS.md 保持得很精简，只描述我通常使用的技术栈：

# 全局 Pi 指令

- 项目通常使用 Laravel（PHP/Inertia/React）、Next.js（TypeScript/Tailwind）或 Astro。
  请检查项目根目录下的 AGENTS.md 是否有针对技术栈的规则；
  如果没有框架，就先问我。

「如果没有框架，就先问我」这一点很重要。当我在纯 HTML/CSS/JS 文件夹里，或者其他技术栈里工作时，代理不会强行把某个框架套到我头上——它只会先问清楚。

我大多数项目都有自己的 AGENTS.md，里面写着框架相关规则，不过我很少手写这些文件。它们通常由框架工具生成，比如 Laravel Boost，会带上这个项目准确的包版本和约定。

AGENTS.md 负责描述项目上下文，但有些规则与技术栈无关，而应该在所有项目里生效。这就是 APPEND_SYSTEM.md 的用途。它位于 ~/.pi/agent/APPEND_SYSTEM.md，并且会直接追加到系统提示词里——也就是说，这里的规则优先级比 AGENTS.md 更高。

这是我写进去的内容：

- 如果默认提供商没有视觉能力，就用 pi-vision-proxy 处理图片。
- 当代码库里已经有答案时，优先阅读相关本地文件；如果没有，再通过 pi-web-access 在线检索。在基于在线研究结果做出重大修改前，先和我确认。
- 在执行有风险的文件编辑或破坏性命令之前，先解释清楚。
- 写作要简洁。避免 AI 味太重的语言——不要堆砌花哨形容词、无必要的副词，或过于正式的措辞。
- 使用短破折号（–），不要用长破折号（—）。

关于这些规则，有几点需要说明：

Pi 有很多快捷键。下面是我最常用的：

Enter 和 Alt+Enter 的区别需要一点时间适应。如果我希望 Pi 在工作中途改变方向，我会按 Enter。如果我只是想补一条备注，让它在完成后再看，我就用 Alt+Enter。

下面这些是我常用的命令，通常是在编辑器里输入 / 调出来：

/tree 这个命令尤其有用。你可以把整段对话历史看成一棵树，跳到任意分支，然后从那里继续。想尝试不同方向、又不想丢掉之前思路的时候，这个功能特别好用。我第一次接触它，是因为看到了 Dillon Mulroy 分享的 那段 Pi 会话。后来我把从那次会话里学到的内容都记到了原始笔记 里。

长会话会把上下文窗口塞满。Pi 有自动压缩功能，在空间不够时会自动压缩旧消息的上下文并进行总结。你也可以手动执行 /compact。另外我很喜欢 pi --continue 这个命令，它会直接打开当前仓库或文件夹里的上一段聊天记录。

我还很喜欢它的 steering (转向) 机制。当 Pi 正在工作时（比如在执行 bash 命令、编辑文件等），你可以直接输入新消息并按 Enter。这样系统会把这条引导消息排队，等当前工具执行完再送进去。我会在发现 Pi 中途跑偏、想快速纠正方向时用这个方法。有时候，我也会用 Option+Enter，它会在前一段输出完全生成完之后再发送消息。

你也可以在 Pi 里使用 OpenAI Codex 订阅、通过 pi-cursor-sdk 使用 Cursor 订阅，或者通过 API 接入 OpenRouter、xAI、Claude 等数百个模型。

用了几周之后，下面这些点最突出：

我现在还是会用 Cursor 和 Codex 来处理主要项目的工作，而且我觉得短期内这不会改变。它们是很成熟的工具，确实把自己的事情做得很好。

但 Pi 已经在我的业余项目和实验里占据了一个固定位置。它速度很快，成本很低，尤其是配合 DeepSeek 和 Kimi 使用之后；到目前为止，Pi 加上几款精挑细选的包，整体体验非常稳定。

这是我当前的配置：

就这些，我试过更多包，但最后只保留了真正会用到的那些。

如果你平时就习惯在终端里工作，也喜欢「一个极简、可扩展的代理」这个思路，不妨 试试 Pi。从基础功能开始，需要的时候再逐步添加包。

我已经用了 Pi 几个星期了，目前这套系统很稳定。我卸掉了几个没有带来足够价值的扩展。系统越简单，通常越好。

等我发现 Pi 的新内容，我还会继续更新这篇文章。