我已经使用 AI 编码工具有一段时间了。在写这篇文章时，我同时订阅了 Cursor 和 OpenAI Codex。它们各自都很擅长自己的工作，我在大多数主要项目里都会用到它们。
但两个多星期前，我遇到了 Pi——一个开源的终端编码代理。它的核心很小，不会默认把所有功能都塞进去，而是让你通过扩展和包来添加能力。我喜欢这个思路，所以决定把它配置起来，看看它适合放在我的工作流中的什么位置。
我还在摸索合适的平衡点，但 Pi 已经开始在我的副项目和实验里占据一席之地。在这篇文章中，我会分享我是如何安装它的、我的配置是什么样子，以及到目前为止的真实使用体验。
Pi 是什么？
Pi 是一个由 Mario Zechner 创建的开源终端编码代理。它在你的终端里运行，并默认给 AI 模型提供四个工具——read、write、edit 和 bash——让模型可以操作你的代码库。
它没有内置 plan mode，没有 sub-agents，没有 MCP，也没有权限弹窗。相反，你可以通过扩展、技能和包来添加这些东西。这让核心保持很小，也让你可以准确构建自己想要的配置。
Pi 支持很多 AI 提供商——Anthropic、OpenAI、DeepSeek、Google Gemini、Groq、xAI、OpenRouter、Kimi 等。你可以使用 API key，也可以用已有订阅登录。
我如何把 Pi 和其他工具搭配使用
目前，我会针对不同类型的工作使用不同工具：
- OpenAI Codex 用于主要项目里的复杂任务
- Cursor 用于同一批项目中更简单的日常编码
- Pi 用于副项目、实验和一次性任务——通常搭配 DeepSeek 和 Kimi 这样的开源模型
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 就可以启动它。但在此之前，你需要先设置提供商和 API key。
将 DeepSeek 设置为提供商
Pi 内置了 /login 命令，可以很轻松地设置任何提供商。我是这样做的：
- 在终端输入
pi打开 Pi - 输入
/login，然后选择 Use an API key - 在提供商列表中选择 DeepSeek
- 在提示时输入我的 DeepSeek API key
就这样。Pi 会保存 key，然后你就可以开始使用了。登录后，用 /model 选择模型——我选的是带 xhigh thinking 的 deepseek-v4-pro。
我默认使用 xhigh thinking，因为我希望模型在修改之前能更深入地思考。对于 URL 抓取这类轻量任务，我会切换到更快也更便宜的 deepseek-v4-flash 模型。
你可以用 Ctrl+L 打开模型选择器，用 Ctrl+P 在 scoped models 之间切换，用 Shift+Tab 改变 thinking level。
我有时也会通过 Pi 使用 Kimi For Coding 模型，效果也不错。我喜欢这种不换工具就能尝试不同模型的感觉。
界面和我的自定义 footer
打开 Pi 后，界面很干净。编辑器在底部，对话在中间，footer 会显示你的工作目录、git 分支、当前模型、thinking level 和上下文窗口使用情况。
我很早就自定义了 footer。默认 footer 显示的信息比我需要的更多。所以我让 Pi 自己帮我构建一个自定义的极简 footer。我描述了自己想要的内容——当前文件夹、带 dirty marker 的 git 分支、模型名称、thinking level，以及一个紧凑的上下文条——然后它为我写出了 TypeScript 扩展。
这个扩展放在 ~/.pi/agent/extensions/minimal-footer.ts，Pi 每次启动时都会自动加载。这个改动很小，但让体验更像是我自己的工具。在这个过程中，我也顺便学到了一点 Pi 扩展的工作方式。
我安装的包
Pi packages 是 npm 或 git 包，可以打包扩展、技能、提示词和主题。你可以用 pi install 安装它们。下面是我使用的包：
1. pi-web-access
这个包让 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",
"summaryModel": "deepseek/deepseek-v4-flash",
"workflow": "none"
}
有了这个包，Pi 可以搜索网页、阅读文档、理解 YouTube 视频，以及克隆并探索 GitHub 仓库——整个过程都不需要离开终端。
2. pi-codex-goal
这个包为 Pi 添加了 goal tracking。它由 Mitch Fultz 构建。它给模型新增了三个工具——get_goal、create_goal 和 update_goal——让你可以创建长时间运行的任务并追踪进度。
pi install npm:pi-codex-goal
当我有跨越多个 prompt 的较大任务时，就会使用它。相比每次重复上下文，我只需要创建一次 goal，Pi 就会持续追踪需要完成的事情。它在 28.5 万 URL 抓取任务中特别有用——即使会话变得很长，goal 也能让任务保持在正确轨道上。
3. pi-vision-proxy
DeepSeek 不能看图——它没有视觉能力。pi-vision-proxy 这个包通过把图片代理给另一个具备视觉能力的模型来解决这个问题。
pi install npm:pi-vision-proxy
我把 Kimi K2.6 设置成了视觉模型。现在，每当我把图片粘贴到 Pi 里，它就会带上一些上下文把图片发送给 Kimi，然后 DeepSeek 会利用 Kimi 看到的内容来完成任务。对于偶尔丢进去的截图或设计参考，这个方式很好用。你可以在 X 上阅读更多这个配置，那条 X 帖里也有一个短视频。
使用 AGENTS.md 和 APPEND_SYSTEM.md 配置项目指令
Pi 有两种方式给模型提供指令：用于项目特定上下文的 AGENTS.md，以及用于全局行为规则的 APPEND_SYSTEM.md。
AGENTS.md（项目上下文）
Pi 会在启动时加载 AGENTS.md 文件，并把它们注入到系统提示词中。它有三个发现位置——全局的 ~/.pi/agent/AGENTS.md，然后沿父目录逐级向上查找，最后是当前目录——所有内容会被拼接在一起。
我的全局 AGENTS.md 很精简。它只描述了我通常使用的技术栈：
# Global Pi Instructions
- Projects commonly use Laravel (PHP/Inertia/React), Next.js
(TypeScript/Tailwind), or Astro. Check the project-root AGENTS.md for
stack-specific rules – if none exists, ask.
其中 “if none exists, ask” 这部分很重要。当我在普通 HTML/CSS/JS 文件夹或其他技术栈里工作时，代理不会强行套用某个框架——它会先询问我。
我的大多数项目也都有自己的 AGENTS.md，里面包含框架特定规则，但我很少手写它们。它们通常由框架工具（比如 Laravel Boost）生成，包含该项目的准确包版本和约定。
APPEND_SYSTEM.md（全局行为规则）
AGENTS.md 用于项目上下文，但有些规则会跨所有项目生效，和技术栈无关。这就是 APPEND_SYSTEM.md 的用途。它位于 ~/.pi/agent/APPEND_SYSTEM.md，并会直接追加到系统提示词中——这意味着这些规则的权限高于 AGENTS.md 指令。
下面是我放进去的内容：
- If the default provider doesn't have vision capabilities, use
pi-vision-proxy for images.
- Read relevant local files first when the answer is available in the
codebase. If not, research online via pi-web-access. Before making a
big change based on online research findings, confirm with me first.
- Explain risky file edits and destructive commands before executing.
- Write simply. Avoid AI-slop language – no flowery adjectives,
unnecessary adverbs, or overly formal phrasing.
- Use en dashes (–) not em dashes (—).
关于这些规则，有几点说明：
- 视觉代理规则现在是 provider-agnostic 的。我可能使用 Kimi、DeepSeek 或另一个模型作为默认模型，所以它不会硬编码某个提供商名称，而是检查当前模型是否具备视觉能力。
- 第二条规则比我早期版本更明确。它不是简单说“不要搜索你已经知道的东西”，而是告诉代理先读取本地文件，只有在需要时才在线搜索，并在基于在线研究做大改动之前先向我确认。
- en dash 规则是一个简单的机械偏好，用来让所有会话中的写作风格保持一致。
我常用的键盘快捷键和命令
Pi 有很多快捷键。下面是我经常使用的：
Key
作用
Ctrl+L
打开模型选择器
Ctrl+P
在 scoped models 之间切换
Shift+Tab
改变 thinking level
Ctrl+C（两次）
退出 Pi
Escape
取消或中止当前操作
Enter
作为 steering message 发送（打断当前工作）
Alt+Enter
作为 follow-up message 发送（在工作完成后送达）
Enter 和 Alt+Enter 的区别需要一点时间适应。如果我希望 Pi 在工作中途改变方向，我会按 Enter。如果我只是想补充一条等它完成后再处理的备注，我会用 Alt+Enter。
下面这些是我常用的命令，通常是在编辑器里输入 /：
/model– 不记快捷键也能切换模型/settings– 修改 thinking level、主题和其他设置/resume– 从之前的会话继续/new– 开始一个新会话/tree– 查看完整会话历史，并跳转到任意位置/compact– 总结旧消息，释放上下文空间/session– 显示当前会话信息，比如 token 和成本
/tree 命令尤其有用。你可以像树一样查看完整对话历史，跳到任意分支，然后从那里继续。当你想尝试另一种做法，同时又不想丢掉之前内容时，它非常好用。我是在看到 Dillon Mulroy 的这个共享 Pi 会话后，对它产生了很大兴趣。后来我把从那个会话里学到的内容整理到了我的原始笔记中。
使用 Pi 时我学到的一些事
长会话会填满上下文窗口。Pi 有自动压缩功能，会在空间不足时总结较早的消息。你也可以用 /compact 手动触发。我也很喜欢 pi --continue 命令，它会直接打开当前 repo/文件夹里的上一个聊天。
我喜欢的另一点是 steering system。当 Pi 正在工作时（运行 bash 命令、编辑文件等），你可以输入一条新消息并按 Enter。它会排队成为一条 steering message，在当前工具完成后送达。当我发现 Pi 在工作中途走偏，想快速纠正它时，就会这样做。有时我不发 steering message，而是用 Option+Enter，这样消息会在上一段输出完全生成结束后再发送。
虽然我自己不用，但你也可以在 Pi 里使用你的 Codex 订阅，通过这个 SDK 使用 Cursor 订阅，或者通过 OpenRouter、xAI、Claude 等提供商的 API 使用数百种模型。
我喜欢 Pi 的地方
使用 Pi 几周后，下面这些点最让我印象深刻：
- 简单且快速： 终端界面很灵敏。没有 Electron，也没有 UI 卡顿。
- 可定制： 我构建了自己想要的 footer，选择了需要的包，其余部分保持极简。
- 支持任何提供商： 我经常使用 DeepSeek 和 Kimi，而且只需一个快捷键就能在它们之间切换。使用它时我也能学到很多——你会更接近事情真正的工作方式，不像更精致的工具那样把一切都藏起来。
- Session tree 很出色： 能够给对话创建分支，并回到任意时间点，这是我在其他工具里会想念的功能。
- 开源（MIT）： 我喜欢没有公司来决定我能得到哪些功能、要付多少钱。
- Compaction 就是能用： 我不用考虑上下文限制。Pi 会在后台处理，而且比其他工具更快、更好。
最后的想法
我仍然在主要项目工作中使用 Cursor 和 Codex，而且短期内看不到改变的理由。它们是成熟的工具，也能很好地完成自己的工作。
但 Pi 已经在我的副项目和实验里获得了一个固定位置。它快、便宜（尤其是搭配开源模型时），而 Pi + DeepSeek + 几个精心选择的包这个组合，到目前为止一直很稳。
下面是我当前配置的样子：
- DeepSeek v4 Pro，
xhighthinking（默认） - DeepSeek v4 Flash，用于更轻量的任务
- Kimi For Coding，作为替代模型
- pi-web-access，用于网页搜索和内容提取
- pi-codex-goal，用于追踪较长任务
- pi-vision-proxy，通过 Kimi K2.6 处理图片
- 一个自定义极简 footer 扩展
就是这些。我尝试过更多包，但最后只保留了真正会用到的那些。
如果你熟悉终端，并且喜欢一个极简、可扩展代理的想法，可以试试 Pi。从基础开始，根据需要再添加包。
我已经使用 Pi 几周了，目前这个配置很稳定。我卸载了一些价值不够高的扩展。配置越简单越好。
我会在发现 Pi 的新东西时继续更新这篇文章。