把 Pi 配成自己的 Coding Agent

速读#

Pi 最吸引人的地方不是功能多，而是核心足够小。默认只有 read、write、edit 和 bash 四个工具，供应商、Skills、扩展、终端界面和外部能力都可以按需补上。

我读完了 Linux.do 上的《我的 Pi 扩展与 Skills 集合笔记》。原帖列出了自定义供应商、权限确认、问题选择、工具开关、MCP、Skills 和主题等大量配置。真正值得带走的不是把清单全部装一遍，而是 Pi 提供了一种不同的 Coding Agent 组织方式：

先保留一个可理解的内核，再把自己的工作方式逐层装进去。

对我来说，最实用的配置顺序只有四层：模型接入、安全边界、交互效率和任务状态。其余功能等遇到明确问题再加。

先理解 Pi 为什么这么空#

Pi 不是一个功能固定的 Claude Code 或 Codex 替代品，更接近一个可以继续改造的 Agent Harness。官方把能力拆成几个边界清楚的载体：

载体	适合放什么
`AGENTS.md`	项目规则、测试命令、禁止事项
Skills	按需加载的专业流程和参考资料
Extensions	工具、事件监听、命令和自定义终端 UI
Pi Packages	可安装、更新和分享的扩展组合
MCP	搜索、浏览器、数据库等外部服务

这个分层比“先装一个全家桶”更重要。能写成说明文档的工作流，不需要变成 TypeScript 扩展；本地已有命令能完成的事情，也不必再接一层 MCP。

先跑起来#

官方当前推荐通过 npm 安装：

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

进入项目目录后启动 pi，再用 /login 选择订阅或 API Key 供应商。Pi 内置 Claude Pro/Max、ChatGPT Plus/Pro 和 GitHub Copilot 登录，也支持常见 API Key 供应商。

第一轮配置不需要碰扩展，先确认三件事：

AGENTS.md 能否准确约束项目操作；
/model 或 Ctrl+L 能否切到需要的模型；
pi -c 和 pi -r 能否恢复已有会话。

这三件事稳定后，再补自定义能力。否则配置问题、模型问题和项目问题会混在一起，很难判断是哪一层出了错。

我会按四层配置#

第一层：模型接入#

优先使用 Pi 内置供应商。只有在接入 OpenAI 兼容中转或私有网关时，才需要用 Extension 注册自定义 Provider。

这类配置最容易踩两个坑：

不同接口对 developer role、reasoning 参数和图片输入的兼容程度不同；
API Key 被直接写进扩展源码，随后跟着配置仓库一起提交。

Pi 的 Provider 配置允许声明兼容能力。接口不支持 developer role 时，应明确关闭对应能力，而不是等请求返回 400 再猜。密钥则留在环境变量或认证文件中，配置仓库只保存模型名称、地址和兼容参数。

第二层：安全边界#

原帖里最值得保留的 Extension 思路，是在危险命令执行前确认，并阻止写入 .env、.git/、密钥文件和依赖锁文件。

但这只能减少误操作，不能当成真正的沙箱。Pi 官方写得很清楚：Pi 默认继承启动它的用户权限，Extensions 也拥有同样的系统访问能力。项目 Trust 只决定是否加载项目内配置，不会限制模型之后可以调用什么。

所以安全配置应该分成两层：

交互护栏：危险命令确认、敏感路径写入拦截、Git 检查点；
系统隔离：处理不可信仓库或无人值守任务时，使用容器、虚拟机或策略沙箱。

正则匹配可以拦住一次 rm，拦不住所有等价写法。真正不能被碰到的文件，不应该只靠一段 Extension 保护。

第三层：交互效率#

Pi 的 Extensions 可以注册命令、工具和自定义 TUI。原帖中的几类扩展都很典型：

任务完成后发送系统通知；
让 Agent 用单选或多页问卷向用户补充信息；
在会话中启用或停用工具；
调整工具输出与主题样式。

Pi 的多问题问卷界面 — Extension 可以把多个澄清问题组织成标签页，而不是在聊天里来回追问。

我不会同时安装多个功能重叠的问题工具。单选、问卷和自动抽取问题看起来都方便，但每多一层自动判断，就多一处可能误触发的行为。先选最符合日常交互的一种，实际遇到限制后再补。

工具开关则更实用。不同任务需要的权限不同，审查代码时可以只保留读取与搜索，确认方案后再开放写入和命令执行。

Pi 的工具开关界面 — 工具状态可以通过 Extension 在会话中切换并持久化。

第四层：任务状态#

长任务真正需要持久化的不是每一句对话，而是目标、发现、决策和验证结果。原帖使用文件驱动的计划 Skill，把状态拆成：

Task/
├── task_plan.md
├── findings.md
└── progress.md

这比一味增加上下文更可靠。模型可以切换，会话可以压缩，任务文件仍然能被人检查，也能交给另一个 Agent 继续。

我会把信息分到三个位置：

AGENTS.md 保存长期有效的项目规则；
Skill 保存可重复调用的工作流程；
Task/ 保存当前任务的阶段状态。

这也对应了《Pi 的公开信》里讨论的会话所有权：供应商状态可以加速工作，但项目继续运行所需的信息不能只留在供应商内部。

Skills 与 Extensions 怎么分#

判断标准可以很简单：

如果能力主要是“告诉 Agent 应该怎样做”，写成 Skill。
例如代码审查流程、文件命名、生成 Frontmatter、持续追问设计约束。

如果能力必须“改变 Pi 怎样运行”，写成 Extension。
例如拦截工具调用、注册新工具、添加命令、渲染问卷或监听会话事件。

Skills 可以放在 ~/.pi/agent/skills/、~/.agents/skills/、.pi/skills/ 或项目的 .agents/skills/ 中。Pi 遵循 Agent Skills 标准，也可以在设置里读取 Claude Code 和 Codex 的 Skills 目录。

Extensions 则放在 ~/.pi/agent/extensions/ 或项目的 .pi/extensions/ 中，并可通过 /reload 热重载。因为它们是直接运行的 TypeScript 模块，只应该安装自己读过或明确信任的代码。

哪些先装，哪些先不装#

能力	什么时候值得加
通知	经常让 Pi 在后台执行长任务
MCP Adapter	已经有明确要连接的搜索、浏览器或数据库服务
权限确认	希望降低危险命令和敏感文件误操作
问题/问卷工具	Agent 经常需要结构化澄清需求
自定义 Provider	内置供应商无法覆盖实际接口
主题与圆角工具	功能稳定后再改善阅读体验
Subagent	任务确实需要隔离上下文或并行执行

原帖选择停用内置 Agent 和 Subagent，因为当前模型拥有 1M 上下文，单会话已经足够容纳工作。这是一个具体场景下的取舍，不是通用结论。

是否使用 Subagent 应该看任务结构，而不是上下文数字。并行调查、权限隔离和独立验证仍然有价值；如果只是把同一任务拆给更多模型，再把结果全部塞回主会话，反而会增加调用与协调成本。

不把 Token 倍数当结论#

原帖提到，同一问题在特定模型和配置下，Pi 的调用成本显著低于 Claude Code。这个现象可以理解：Pi 默认系统提示更小，加载的工具与规则更少，自然可能减少固定开销。

但具体倍数不能直接外推。模型、缓存、上下文长度、工具定义和任务类型都会改变结果。Pi 真正稳定的优势不是某个 Token 数字，而是你可以看见并决定哪些内容进入上下文。

配置也会反过来增加开销。Skills 越多、MCP 工具描述越长、Extensions 注入的信息越复杂，Pi 就越接近一个功能完整但负担更重的 Agent。保持可控的办法仍然是按需加载。

最后#

Pi 的自由不是免费功能。它把产品替你做的决定重新交回来了：模型怎样接、什么命令要确认、哪些状态要落盘、哪些能力值得进入当前会话，都需要自己选择。

我会从最小配置开始：

先写好 AGENTS.md；
使用内置登录和模型选择；
加一层危险操作护栏；
用任务文件保存长期状态；
最后再补通知、问卷、MCP 和界面主题。

这样配置出来的 Pi 不一定拥有最多功能，但每一层都知道为什么存在，也知道不需要时该从哪里删掉。

参考资料：

封面与界面截图取自原帖，用于说明其配置方案。