本文已获得原作者的电子邮件书面许可翻译并发布，版权所有归属原作者。
原文： Setting Up and Using the Pi Coding Agent
作者： DeepakNess
原文链接： https://deepakness.com/blog/pi-agent-setup/
我用 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-cursor-sdk) 或者与任何适合任务的模型搭配使用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 运行它/login，然后选择「使用 API key」就这样，Pi 会保存密钥，你就可以开始用了。登录后，再用 /model 选择模型——我选的是 deepseek-v4-pro，并把思考强度设为 xhigh。
我默认使用 xhigh 思考模式，因为我希望模型在动手修改前先进行充分思考。对于像 URL 抓取这类更轻的任务，我会切换到更快、更便宜的 deepseek-v4-flash 模型。
使用 Ctrl+L 打开模型选择器，Ctrl+P 在可用的模型之间循环切换，Shift+Tab 用于调整思考等级。
我还会根据任务使用 Kimi K2.7 Code 和其他模型，更多详情请参见下面的型号列表。
我启用了多个模型，并根据不同类型的任务来切换：
| 模型 | 我用它做什么 |
|---|---|
| DeepSeek v4 Pro | 大多数业余项目的默认选择——质量和成本间良好的均衡 |
| DeepSeek v4 Flash | 轻量级、重复性任务，例如数据抓取或批量文件操作——快速且成本低廉。 |
| Kimi K2.6 / K2.7 Code | 需要第二意见，或者碰到速率限制时的备选方案 |
Cursor (通过 pi-cursor-sdk) | 能在 Pi 里直接使用现有的 Cursor 订阅，无需额外的 API Key |
| OpenAI Codex (GPT-5.5) | 偶尔当一项任务受益于更大型的推理模型时使用 |
切换是实时的——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-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",
"allowBrowserCookies": false,
"summaryModel": "deepseek/deepseek-v4-flash",
"workflow": "none",
"curatorTimeoutSeconds": 20
}
有了这个包，Pi 就能直接在终端里完成网页搜索、文档阅读、YouTube 内容理解，以及 GitHub 仓库的克隆和浏览。
pi-codex-goal这个包给 Pi 增加了目标跟踪能力，由 Mitch Fultz
开发。它给模型新增了三个工具——get_goal、create_goal 和 update_goal——可以用来创建长时间运行的任务并跟踪进度。
pi install npm:pi-codex-goal
凡是跨越多个提示词的大任务，我都会用它。这样我不用每次都重复上下文，只需要先创建一个目标，Pi 就会帮我记住接下来要做什么。它在 28.5 万个 URL 的抓取任务里特别有用——即使会话拉得很长，目标也能让任务一直保持在轨道上执行。
pi-vision-proxyDeepSeek 不能看图——它没有视觉能力。pi-vision-proxy 这个包通过把图片转发给另一个具备视觉能力的模型，解决了这个问题。
pi install npm:pi-vision-proxy
我把 Kimi K2.6 设置为视觉模型。现在，每次我把图片粘贴进 Pi，它都会先把图片和一些上下文发给 Kimi，然后 DeepSeek 再根据 Kimi 看见的内容继续完成任务。对于我偶尔丢进去的截图或设计参考，这个流程很好用。
在底层，它会尽可能把多张图片批量处理，并用感知哈希缓存重复截图，这样同一张图就不会被重复分析。它还支持几种 grounding (落地) 格式1，方便在需要时精确定位坐标。你可以 在 X 上阅读 更多关于这套配置的内容，我也在那条帖子里附了一个简短的视频。
pi-agent-browser-native这个包给 Pi 在终端里提供了一个真正的浏览器。它可以打开页面、截屏、生成快照、点击链接、填写表单、执行 QA 检查、提取页面内容——全都不用离开终端。
pi install npm:pi-agent-browser-native
我会把它和 pi-web-access 一起用。网页搜索负责找信息，浏览器负责和真实页面交互、阅读需要 JavaScript 的文档、以及进行视觉检查。它还增加了 agent_browser_web_search 工具，这是一种比打开完整浏览器页面更快的网页搜索方式。
pi-cursor-sdk如果你已经付费订阅了 Cursor，这个包可以让你在 Pi 里直接用它，这样无需额外付费。
pi install npm:pi-cursor-sdk
我订阅了 Cursor，所以这个包很自然地就用上了。安装后，cursor/auto 会出现在模型选择里，我可以像使用其他提供商一样使用它。这个包也同样是由 Mitch Fultz
开发的，他也是 pi-codex-goal 的作者。在 Cursor 负责订阅模型、DeepSeek 负责便宜而重的活、Kimi 作为备选的组合下，我的覆盖面已经很好了，而且没有增加更多的 API 费用。我在 原始笔记
里写过更多通过这个 SDK 使用 Composer 2.5 模型的内容。
AGENTS.md 和 APPEND_SYSTEM.md)Pi 给模型下指令有两种方式：AGENTS.md 用于项目特定的上下文约束，APPEND_SYSTEM.md 用于全局行为规则。
AGENTS.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，会带上这个项目准确的包版本和约定。
APPEND_SYSTEM.md（全局行为规则）AGENTS.md 负责描述项目上下文，但有些规则与技术栈无关，而应该在所有项目里生效。这就是 APPEND_SYSTEM.md 的用途。它位于 ~/.pi/agent/APPEND_SYSTEM.md，并且会直接追加到系统提示词里——也就是说，这里的规则优先级比 AGENTS.md 更高。
这是我写进去的内容：
- 如果默认提供商没有视觉能力，就用 pi-vision-proxy 处理图片。
- 当代码库里已经有答案时，优先阅读相关本地文件；如果没有，再通过 pi-web-access 在线检索。在基于在线研究结果做出重大修改前，先和我确认。
- 在执行有风险的文件编辑或破坏性命令之前，先解释清楚。
- 写作要简洁。避免 AI 味太重的语言——不要堆砌花哨形容词、无必要的副词，或过于正式的措辞。
- 使用短破折号（–），不要用长破折号（—）。
关于这些规则，有几点需要说明：
Pi 有很多快捷键。下面是我最常用的：
| 快捷键 | 作用 |
|---|---|
Ctrl+L | 打开模型选择器 |
Ctrl+P | 在作用域内的模型之间循环切换 |
Shift+Tab | 调整思考等级 |
Ctrl+C (按两次) | 退出 Pi |
Escape | 取消或中止当前操作 |
Enter | 作为引导消息发送（会中断当前工作） |
Alt+Enter | 作为后续消息发送（会在工作完成后送达） |
Enter 和 Alt+Enter 的区别需要一点时间适应。如果我希望 Pi 在工作中途改变方向，我会按 Enter。如果我只是想补一条备注，让它在完成后再看，我就用 Alt+Enter。
下面这些是我常用的命令，通常是在编辑器里输入 / 调出来：
/model – 不用记快捷键，直接切换模型/settings – 调整思考等级、主题和其他设置/resume – 从上一个会话继续/new – 开始一个新会话/tree – 查看完整会话历史，并跳转到任意节点/compact – 压缩旧消息，释放上下文/session – 显示当前会话信息，比如 token 和成本/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 加上几款精挑细选的包，整体体验非常稳定。
这是我当前的配置：
xhigh 思考模式（默认）pi-web-access，通过 Exa 做网页搜索和内容提取pi-codex-goal，用于跟踪更长时间的任务pi-vision-proxy，通过 Kimi K2.6 处理图片pi-agent-browser-native，用于在终端里执行浏览器任务pi-cursor-sdk，让我在 Pi 里使用 Cursor 订阅APPEND_SYSTEM.md，记录写作风格和行为规则就这些，我试过更多包，但最后只保留了真正会用到的那些。
如果你平时就习惯在终端里工作，也喜欢「一个极简、可扩展的代理」这个思路，不妨 试试 Pi 。从基础功能开始，需要的时候再逐步添加包。
我已经用了 Pi 几个星期了，目前这套系统很稳定。我卸掉了几个没有带来足够价值的扩展。系统越简单，通常越好。
等我发现 Pi 的新内容，我还会继续更新这篇文章。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。