转载请注明出处❤️

作者：测试蔡坨坨

原文链接：caituotuo.top/abb6cd85.html

背景

你好，我是测试蔡坨坨。

两周前，我把 Codex 升级到 GPT-5.6，结果越用越慢。以前最多几十分钟就能完成的任务，现在经常要跑四五个小时，Token 也花得更多了。

刚开始我以为 5.6 就是慢。用了几天又觉得不太对，xhigh 和 max 的能力明明更强，考虑问题也更全面，只是干活之前总要准备很久。任务拆得特别细，计划写了一版又一版，代码迟迟没动。

我干脆把会话的 JSONL 文件翻出来，看它到底在忙什么。很多时间都花在读 Skills、写计划和补 TDD 上，还有一部分推理是在处理不同 Skill 之间的冲突。

至少从我翻过的这些会话来看，5.5 也会调用 Skills，但经常只看前面几行，后面的模板和引用文档不一定读全。5.6 正好相反，读得全，执行得也认真。Skills 写得不合适时，这种认真就变成了负担。

特别是 superpowers 类型的 Skill，表现更为明显。改个变量名，也恨不得走一遍完整 TDD。单个 Skill 文档又很长，从这份 JSONL 里看，启动时完整读一遍，大约会占用 6.5K Token 的上下文。再碰上 planning-with-files、SDD、brainstorming 和 Plan 模式互相抢流程，模型只能来回纠偏。

我不反对 TDD，代码质量当然重要。但一个小改动折腾几个小时，时间全耗在重复计划和过度准备上，肯定不对。这不是严谨的模型对比，只是我从几次实际使用中得出的判断：GPT-5.6 变慢，锅未必都在模型，之前装进去的那些网红 Skills 也有一份。

我准备把 Skills 重新清理一遍，只留下符合自己工作流的文档组织和个人风格约束。也是因为这次折腾，我开始找更轻便的编码 Agent，然后看到了 Pi Agent。

Pi 是什么

Pi 本身不提供模型，它是连接模型和代码库的那一层。你在终端里给任务，模型通过它读取文件、修改代码和执行命令。官方把 Pi 称为「minimal terminal coding harness」，默认工具只有 read、write、edit 和 bash，其他能力需要时再加。

这也对应了官网那句话：Adapt pi to your workflows, not the other way around. 让 Pi 适应你的工作流，而不是反过来。

Pi 也不只是一个终端工具。OpenClaw 的 Agent 运行时最初就是基于 Pi SDK 搭建的，Pi 官方文档把它列为 SDK 的实际案例。现在 OpenClaw 已经把大部分运行时代码收进自己的仓库，终端部分仍在使用 @earendil-works/pi-tui。

Databricks 还在内部一个包含数百万行代码的代码库中，对比过不同模型和 harness。同一个模型、相同思考强度，换一个 harness，部分任务的成本会相差 2 倍以上，完成质量基本没变。Pi 每轮送给模型的上下文大约只有对方的三分之一，任务需要的执行轮次也更少。

这份测试只代表 Databricks 自己的代码库，不能直接套到所有项目上。不过它和我在 JSONL 里看到的情况很像：模型是一部分，Agent 往上下文里塞什么、塞多少，也会影响时间和 Token。

安装、检查和更新

使用 npm 全局安装：

1

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

macOS 和 Linux 也可以使用官方安装脚本：

1

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

安装完成后检查版本：

1

pi --version

进入项目目录，执行 pi 即可启动：

1
2

cd your-project
pi

第一次使用需要配置模型凭证。在 Pi 中执行 /login，选择对应的供应商即可。Pi 支持 API Key，也支持 Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro（Codex）和 GitHub Copilot 等订阅登录方式。

更新 Pi：

1

pi update

连同已经安装的 Pi Packages 一起更新：

1

pi update --all

Pi 默认给模型开放 read、write、edit 和 bash 4 个工具。模型可以读取文件、局部修改代码并运行 Shell 命令，日常改代码已经够用。

基本使用

Pi 的界面很简单，但有几个操作会直接影响使用效率。

多行输入

默认快捷键如下：

• Shift + Enter：插入新行
• Ctrl + J：插入新行，注意是字母 J
• Ctrl + Enter：可在 Windows Terminal 中尝试插入新行
• Enter：发送消息

部分终端无法区分 Shift + Enter 和普通 Enter，按下后会直接发送。最稳妥的办法是按 Ctrl + G 打开外部编辑器，写完长内容后保存并退出。

也可以修改 ~/.pi/agent/keybindings.json，给换行多绑一个快捷键：

1
2
3

{
  "tui.input.newLine": ["shift+enter", "ctrl+j", "alt+j"]
}

回到 Pi 执行 /reload，之后就能用 Alt + J 换行。VS Code 集成终端、Windows Terminal 或部分旧终端仍可能拦截组合键，这类问题需要在终端自身的快捷键配置中处理。

文件和命令

在输入框中键入 @，可以模糊搜索并引用项目文件：

1
2

pi @README.md "总结这个文件"
pi @src/app.ts @src/app.test.ts "审查这两个文件"

如果已经进入 Pi，可以用 ! 直接运行 Shell 命令：

1

!npm run lint

单个 ! 会执行命令，并把输出放进模型上下文。两个 !! 只执行，不把输出交给模型：

1

!!npm run build

这个区别挺实用。需要模型继续分析报错时用 !，只是想自己看一下构建结果时用 !!，可以少占一些上下文。

常用快捷键

Agent 工作时也能继续发消息。按 Enter 会加入一条转向消息，等当前这一轮的工具调用全部完成后再送给模型；按 Alt + Enter 会排队一条后续消息，等当前任务全部完成后再发送。按 Escape 中止任务时，排队内容会回到输入框。

会话管理

任务跑到几个小时后，会话管理就很重要。Pi 的会话默认保存在 ~/.pi/agent/sessions/，并按工作目录分类。

启动时可以直接恢复：

1
2
3
4

pi -c                  # 继续最近一次会话
pi -r                  # 浏览并选择历史会话
pi --session <path|id> # 打开指定会话
pi --no-session        # 临时会话，不保存

我建议给重要任务起个名字，后面查找会轻松很多：

1

/name Pi Agent 操作手册整理

也可以在启动时命名：

1

pi --name "Pi Agent 操作手册整理"

常用会话命令不用全部记，先记住下面这些：

/tree 是我认为很聪明的设计。Pi 的会话是树状结构，方向走错了，不必丢掉前面的内容重新开聊，可以回到某个节点继续。长会话接近上下文上限时，Pi 默认会自动压缩，也能用 /compact 手动处理。

压缩会损失细节，完整历史仍保留在会话文件里。重要约束最好写进项目文件，不要只依赖模型对长对话的记忆。

工具配置

Pi 的思路是保持核心精简，所以很多能力需要按需开启。这一点很自由，代价是第一次配置要自己动手。

开启 grep、find 和 ls

除默认 4 个工具外，Pi 还提供 grep、find 和 ls。其中 grep 依赖 ripgrep，find 依赖 fd。

macOS 可以通过 Homebrew 安装：

1

brew install ripgrep fd

Ubuntu 或 WSL 可以执行：

1
2

sudo apt update
sudo apt install ripgrep fd-find

Windows 需要 Bash 环境，普通用户安装 Git for Windows 即可。依赖可以用 WinGet 安装：

1
2

winget install --id BurntSushi.ripgrep.MSVC -e
winget install --id sharkdp.fd -e

检查安装结果：

1
2

rg --version
fd --version

WSL 中只有 fdfind 命令时，改用 fdfind --version。

启动 Pi 时指定全部 7 个内置工具：

1

pi --tools read,write,edit,bash,grep,find,ls

--tools 是白名单。用了这个参数，就要把需要保留的默认工具也写上，否则未列出的工具不会启用。

如果只想让模型审查项目，不允许修改文件，可以开只读模式：

1

pi --tools read,grep,find,ls -p "审查当前项目"

完全禁用工具，只进行对话：

1

pi --no-tools -p "解释这个概念"

macOS、Linux 和 WSL 用户可以在 ~/.zshrc 或 ~/.bashrc 中设置别名：

1

alias piall='pi --tools read,write,edit,bash,grep,find,ls'

加载配置后，在项目目录执行 piall 即可：

1
2

source ~/.zshrc
piall

联网搜索

Pi 默认没有网页搜索工具。想要一个免费方案，可以安装命令行工具 ddgr，通过 DuckDuckGo 搜索，不需要 API Key。

1
2

brew install ddgr
ddgr --json --num 8 "Pi coding agent"

--json 会返回更适合模型解析的结构化结果。还可以限制时间和站点：

1
2

ddgr --json --num 8 --time m "关键词"
ddgr --json --num 8 --site example.com "关键词"

再把调用方法写成 Skill，保存到 ~/.pi/agent/skills/ddgr-search/SKILL.md。Pi 启动时只读取 Skill 的名称和描述，任务匹配后才加载完整说明，不会把所有 Skill 一次塞进上下文。

Skill 放哪里，主要看它给谁用。所有项目都要用的个人 Skill，可以放在 ~/.pi/agent/skills/<name>/SKILL.md 或 ~/.agents/skills/<name>/SKILL.md；只服务当前项目的 Skill，则放在项目里的 .pi/skills/<name>/SKILL.md 或 .agents/skills/<name>/SKILL.md。项目级 Skill 需要先信任项目才会加载。只是临时试用，也可以在启动时通过 pi --skill <path> 指定，不必复制到固定目录。

配置完成后执行 /reload，可以直接提出“联网搜索……”之类的需求，也能明确调用：

1

/skill:ddgr-search 搜索内容

这套方案免费，但 DuckDuckGo 可能临时限流，稳定性比商业搜索 API 差一些。

项目指令

在项目根目录创建 AGENTS.md，可以告诉 Pi 这个项目的命令、规范和禁区：

1
2
3
4
5

# 项目指令

- 修改代码后运行测试。
- 不要执行生产环境数据库迁移。
- 回答保持简洁。

Pi 启动时会加载全局的 ~/.pi/agent/AGENTS.md，再从当前目录向上查找项目里的 AGENTS.md；它也兼容 CLAUDE.md。文件修改后执行 /reload，或者重新启动 Pi。

我的建议是把长期有效的规则放进 AGENTS.md，当前任务的目标留在对话里。这样即使切换会话或压缩上下文，项目约定也不会跟着消失。

Pi 还支持 Skills、Prompt Templates、Extensions、Themes 和 Pi Packages。刚开始没必要全配，先用默认工具完成一个真实任务，碰到重复动作后再封装。配置堆得太多，轻量工具一样会变重。

安全注意事项

Pi 没有内置沙箱，文件工具、Shell 命令和 Extensions 都以当前用户权限运行。它少了频繁弹窗，操作更直接，也把安全判断留给了使用者。

重要项目要放进 Git，执行修改后及时看 git diff。陌生仓库里的 .pi 配置、Extensions 和 Skills 不要直接信任，第三方 Pi Package 安装前先检查源码。处理不可信代码时，放进容器或虚拟机更稳妥；API Key 和 ~/.pi/agent/auth.json 也不要暴露给项目。

如果你受够了臃肿的 Agent 工作流，Pi 值得试一下。先装好默认版本，学会 @ 引用文件、! 执行命令和 /resume 恢复会话，就能开始干活。至于搜索、额外工具和扩展，等真正需要时再加。

这也是我现在更认可的使用方式：工具先保持简单，问题出现后再配置。

参考资料

• Pi 官方网站：https://pi.dev
• Pi 官方文档：https://pi.dev/docs/latest
• Benchmarking Coding Agents on Databricks’ Multi-Million Line Codebase：https://www.databricks.com/blog/benchmarking-coding-agents-databricks-multi-million-line-codebase
• Pi Coding Agent 入门教程（菜鸟教程）：https://www.runoob.com/ai-agent/pi-coding-agent.html