我用 AI 编程工具已经有一段时间了。写这篇文章的时候，我同时订阅了 Cursor 和 OpenAI Codex。它们各有所长，我大部分主力项目的工作都靠它们完成。

但两周多前，我偶然发现了 Pi —— 一款开源的终端编程智能体。它的核心非常精简，功能通过扩展和包来添加，而不是默认打包一切。我很喜欢这个理念，于是决定安装试试，看看它能用在哪些场景。

我还在摸索最佳的搭配方式，但 Pi 已经在我的副业项目和实验中找到了一席之地。这篇文章里，我会分享安装过程、我的配置方案，以及到目前为止的真实使用体验。

一、Pi 是什么？

Pi 是由 Mario Zechner 开发的开源终端编程智能体。它在终端中运行，

默认给 AI 模型提供四个工具 —— read (读取)、write (写入)、edit (编辑) 和 bash (命令行)

—— 来操作你的代码库。

它没有内置的计划模式 (plan mode)、子智能体 (sub-agents)、MCP (Model Context Protocol)，也没有权限弹窗。但你可以通过扩展、技能 (skills) 和包来添加这些功能。这样核心保持精简，你可以按需搭建自己想要的配置。

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

二、我如何搭配其他工具使用 Pi

目前，我针对不同类型的工作使用不同的工具：

OpenAI Codex：处理主力项目中的复杂任务Cursor：在同一批项目中的日常简单编码Pi：副业项目、实验性项目和一次性任务 —— 搭配 DeepSeek、Kimi、Cursor (通过 pi-cursor-sdk)，以及适合当前任务的任何模型

Pi 很适合副业项目，因为它快速、轻量，而且我可以使用更便宜的模型，不用烧昂贵的订阅费。

举个例子：最近我用 Pi 搭配 DeepSeek v4 Flash 模型抓取了一个网站的 28.5 万个 URL。运行了大约 1.5 小时，通过官方 DeepSeek API 只花了 1 美元。我用 pi-codex-goal 扩展来跟踪这个长时间运行的任务，一切顺利。

三、安装 Pi

安装只需一条命令：

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

或者通过npm安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

如果npm安装存在网络访问问题，可以设置腾讯的 NPM 镜像地址：http://mirrors.tencent.com/npm/。

可直接执行：

npm config set registry http://mirrors.tencent.com/npm/

安装完成后，在终端输入 pi 即可启动。但首先，你需要配置提供商和 API 密钥。

四、配置 DeepSeek 作为提供商

Pi 内置了 /login 命令，让任何提供商的配置都变得简单。

以下是我的操作步骤：

在终端输入 pi 打开 Pi输入 /login，选择 使用 API 密钥 (Use an API key)在提供商列表中选择 DeepSeek按提示输入 DeepSeek API 密钥

我默认用 xhigh 思考深度，因为希望模型在做修改前深入思考。对于像 URL 抓取这样更轻量的任务，我会切换到更快也更便宜的 deepseek-v4-flash 模型。

你可以用 Ctrl+L 打开模型选择器，用 Ctrl+P 在已配置的模型间循环切换，用 Shift+Tab 调整思考深度。

我还会根据任务需要切换 Kimi K2.7 Code 和其他模型。

五、我的模型阵容

我启用了多个模型，根据任务需求灵活切换：

六、我安装的包

Pi 的包是 npm 或 git 包，打包了扩展、技能 (skills)、提示词 (prompts) 和主题。用 pi install 安装。以下是我使用的：

1. pi-web-access

这个包赋予 Pi 搜索网页、获取页面内容、提取 YouTube 视频字幕和探索 GitHub 仓库的能力。详见 pi.dev/packages/pi-web-access。

pi install npm:pi-web-access

它开箱即用，支持 Exa 搜索 (无需 API 密钥)，你也可以选配 Perplexity、Exa 或 Gemini 的 API 密钥以获得更精细的控制。我通过创建 ~/.pi/web-search.json 文件将其配置为默认使用 Exa 作为搜索提供商：

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

有了这个包，Pi 可以搜索网页、阅读文档、理解 YouTube 视频，以及克隆和探索 GitHub 仓库 —— 全部无需离开终端。

2. pi-codex-goal

这个包为 Pi 添加了目标跟踪功能。由 Mitch Fultz 开发。它给模型增加了三个新工具 —— get_goal (获取目标)、create_goal (创建目标) 和 update_goal (更新目标) —— 让你可以创建长时间运行的任务并跟踪进度。

pi install npm:pi-codex-goal

每当我有跨越多轮对话的较大任务时就会用它。不用每次都重复上下文，创建一次目标后 Pi 会持续跟踪需要完成的事项。在抓取 28.5 万个 URL 的任务中它特别有用 —— 即使会话时间很长，目标也能让任务保持在正轨上。

3. pi-vision-proxy

DeepSeek 无法查看图片 —— 它没有视觉能力。 pi-vision-proxy 包通过将图片代理给有视觉能力的模型来解决这个问题。

pi install npm:pi-vision-proxy

我把 Kimi K2.6 配置为视觉模型。现在每当我往 Pi 里粘贴图片时，它会将图片发送给 Kimi 并附带一些上下文，然后 DeepSeek 使用 Kimi 看到的内容来完成任务。对于偶尔扔进去的截图或设计参考，效果还不错。

底层实现上，它会尽可能批量处理多张图片，并使用感知哈希 (perceptual hashing) 缓存重复的截图，避免同一张图片被重复分析。它还支持多种定位格式 (grounding formats)，在需要时实现精确的坐标定位。

4. pi-agent-browser-native

这个包给 Pi 提供了一个真正的终端内浏览器。它可以打开页面、截图和抓取快照、点击链接、填写表单、运行 QA 检查、提取页面内容 —— 全部无需离开终端。

pi install npm:pi-agent-browser-native

我把它和 pi-web-access 配合使用。网页搜索找到信息，浏览器让我与实时页面交互、阅读需要 JavaScript 的站点上的文档，以及进行视觉检查。它还添加了 agent_browser_web_search 工具，这是一种比打开完整浏览器页面更快的网页搜索方式。

5. pi-cursor-sdk

如果你已经为 Cursor 订阅付费，这个包让你在 Pi 内使用它，不用付两份钱。

pi install npm:pi-cursor-sdk

我有 Cursor 订阅，这个包自然很合适。安装后，cursor/auto 会作为模型选项出现在选择器中，我可以像使用其他提供商一样使用它。它同样由 Mitch Fultz 开发，和 pi-codex-goal 是同一人。Cursor 用于订阅模型，DeepSeek 用于便宜的繁重工作，Kimi 作为替代方案 —— 这样的组合让我无需增加更多 API 账单就能获得良好的覆盖。

七、用 AGENTS.md 和 APPEND_SYSTEM.md 配置项目指令

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

AGENTS.md (项目上下文)

Pi 启动时会加载 AGENTS.md 文件并注入到系统提示词 (system prompt) 中。有三个发现位置 —— 全局的 ~/.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 (—).

关于这些规则的几点说明：

视觉代理规则现在是提供商无关的。我可能用 Kimi、DeepSeek 或其他模型作为默认模型，所以不再硬编码提供商名称，而是检查当前模型是否具有视觉能力。

第二条规则比我之前的版本更明确。不再只是说"不要搜索你已经知道的东西"，而是告诉智能体先读取本地文件，只在需要时在线搜索，并基于在线研究发现做大改动前先跟我确认。

en dash 规则是一个简单的格式偏好，让我在所有会话中的写作风格保持一致。

八、我常用的键盘快捷键和命令

Pi 有很多快捷键。以下是我经常使用的：

Enter 和 Alt+Enter 的区别我花了一些时间才习惯。如果我想让 Pi 在工作过程中改变方向，按 Enter。如果只是想在它完成后补充说明，用 Alt+Enter。

以下是我常用的命令，通常在编辑器中输入 / 来使用：

/model —— 无需记住快捷键即可切换模型

/settings —— 调整思考深度、主题和其他设置

/resume —— 从之前的会话继续

/new —— 开启新会话

/tree —— 查看完整的会话历史并跳转到任意节点

/compact —— 总结旧消息以释放上下文空间

/session —— 显示当前会话信息，如 Token 数和费用

/tree 命令特别有用。你可以像树一样查看整个对话历史，跳转到任意分支，并从那里继续。当你想尝试不同方法又不想丢失之前的内容时，这非常棒。

九、使用 Pi 过程中学到的一些东西

长时间会话会填满上下文窗口。Pi 有自动压缩 (automatic compaction) 功能，当空间不足时会总结旧消息。你也可以手动用 /compact 触发。我很喜欢 pi --continue 命令，它能直接打开当前仓库/文件夹中的最后一次聊天。

另一个我喜欢的是引导系统 (steering system)。Pi 工作时 (运行 bash 命令、编辑文件等)，你可以输入新消息并按 Enter。这会排队一条引导消息，在当前工具执行完成后送达。当我发现 Pi 工作方向有误想快速纠正时，我就用这个。有时，我也会用 Option+Enter 发送消息，让它在前一个输出完全生成后再送达。

你还可以在 Pi 内使用你的 OpenAI Codex 订阅、通过 pi-cursor-sdk 使用 Cursor 订阅、通过 OpenRouter 使用数百种模型、使用 xAI、Claude 以及更多提供商的 API。

十、我喜欢 Pi 的地方

用了几周 Pi 后，以下特点让我印象深刻：

简洁快速： 终端界面响应迅速。没有 Electron，没有 UI 卡顿。高度可定制： 我搭建了完全符合需求的页脚，挑选了需要的包，其余保持精简。兼容任何提供商： 我常用 DeepSeek 和 Kimi，切换只需一个快捷键。使用过程中也能学到很多 —— 你更接近事情的底层原理，不像那些更精致的工具把一切都隐藏起来。会话树 (session tree) 太棒了： 能够分支对话并回到任意节点，这是我在其他工具中非常想念的功能。开源 (MIT 协议)： 我喜欢没有公司决定我能用什么功能、收我多少钱。压缩功能无缝工作： 我不用考虑上下文限制。Pi 在后台处理，而且比其他工具更快更好。

最后的话

我仍在用 Cursor 和 Codex 处理主力项目工作，短期内这不会改变。它们是精致的工具，各司其职。

但 Pi 已经在我的副业项目和实验中赢得了永久的位置。它快速、便宜 (尤其搭配 DeepSeek 和 Kimi)，Pi 加几个精选包的组合到目前为止表现稳健。

以下是我当前的配置：

DeepSeek v4 Pro，思考深度 xhigh (默认)DeepSeek v4 Flash 用于轻量任务Kimi K2.6 / K2.7 Code 作为替代模型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，配置已经稳定。我卸载了几个价值不大的扩展。配置越简单越好。