pi 的"不做"清单
理解 pi,理解它不做什么和理解它做什么同样重要。这份清单出自作者的构建手记,每一条初看都反直觉,合起来却构成一套自洽的哲学:任何能由用户在工作流层面解决的需求,都不该焊死在核心里。逐条过一遍,并给出我们自己的判断。
No MCP
别人怎么做:通过 MCP(Model Context Protocol)接入外部能力——数据库、浏览器、第三方 SaaS,工具描述自动注入上下文。
pi 为什么拒绝:常驻上下文的成本被严重低估。作者给的数字:Playwright MCP 有 21 个工具、约 13.7k token 的描述,Chrome DevTools MCP 26 个工具、约 18k token——还没开始干活,7–9% 的上下文窗口就没了,而这些工具你一次会话大多用不上几个。
替代方案:CLI 工具 + README。把能力做成命令行工具,配一份写给模型看的 README;agent 需要时用 read 读 README、用 bash 调工具——token 成本按需支付(渐进式披露),能力天然可组合(管道、链式调用)。作者维护的 agent-tools 就是这个思路的集锦;非用 MCP 不可时,可以用 mcporter 把 MCP server 包成 CLI。
什么时候不适用你:你的团队已重度投资 MCP 生态,或需要给非技术用户提供"开箱即连"的集成。此时 pi 的回答是:写一个接 MCP 的扩展——核心不挡你。
No sub-agents
别人怎么做:复杂任务派生 sub-agent 并行处理(探索、审查、实现)。
pi 为什么拒绝:可观察性灾难——"黑盒套黑盒"。编排 agent 决定传给 sub-agent 的初始上下文,你既看不到它看了什么,也看不到它漏了什么;出错了无法调试。作者的另一个判断更扎心:在主会话里派 sub-agent 收集上下文,往往说明你没有规划工作流——收集上下文应该是独立的前置会话,产出 artifact(文档、清单),再喂给实现会话。这样 artifact 可复用、过程全透明。他还补了一刀:派多个 sub-agent 并行写代码,除非你不在乎代码库变成垃圾场。
替代方案:需要分身时,让 pi 用 bash 派生它自己(pi --print "…"),最好跑在 tmux 里——输出全程可见,随时可以进去接管。作者的代码审查工作流就是一个自定义命令:主 agent 派生自己做 review,完整报告落盘,还能另开会话进去追问。
什么时候不适用你:需要大规模并行探索且不在乎过程可见性的场景。参考答案同样是扩展:examples/extensions/subagent。
No plan mode
别人怎么做:内置 plan mode——只读分析、出计划、批准后执行。
pi 为什么拒绝:和 agent 一起讨论方案而不动文件,本来就不需要"模式",直接聊就行。需要持久化的计划?写进 PLAN.md 文件:可版本化、可跨会话复用、人和 agent 可以协作编辑同一份文件——这比活在会话内存里的"模式"强得多。作者还指出一个讽刺的现实:别家的 plan mode 往往要批准一大堆命令才能跑完计划阶段,而且计划过程常常是派 sub-agent 做的——又是不可观察。
替代方案:口头讨论 + PLAN.md;要只读约束就 pi --tools read,grep,find,ls;要真正的 plan mode 交互,有现成的扩展示例 examples/extensions/plan-mode。
什么时候不适用你:团队已经把"计划→批准→执行"的仪式固化进协作流程,且依赖权限门控。那正是该上扩展的地方。
No built-in to-dos
别人怎么做:内置 todo 工具,让模型维护任务清单。
pi 为什么拒绝:作者的经验是内置 todo 对模型的干扰大于帮助——它给模型增加了一份需要持续跟踪和更新的状态,状态不同步就引入新的失败模式。
替代方案:TODO.md 文件,checkbox 语法。外部化、可见、人和 agent 都能改——"状态在文件里"又一次战胜了"状态在 harness 里"。
No background bash
别人怎么做:bash 工具支持后台任务(起 dev server、跑 watch),后台任务列表由 harness 管理。
pi 为什么拒绝:后台进程管理是真复杂(进程跟踪、输出缓冲、退出清理、向运行中的进程喂输入),而且 harness 管得并不好——作者举的例子:某版本 Claude Code 的 agent 在压缩后就忘了自己的后台进程,还没有工具可以查询它们,只能手动 kill。
替代方案:tmux。tmux new-session -d 起服务,tmux capture-pane 看输出,tmux send-keys 喂输入,tmux ls 列出全部——可观察、可交互,人还能随时进同一个 tmux 会话和 agent 并肩调试。作者贴过 pi 在 tmux 里用 LLDB 调试崩溃 C 程序的例子:"How's that for observability?"
No permission popups(YOLO 默认)
别人怎么做:文件写入、命令执行前弹确认。
pi 为什么拒绝:作者认为那大多是 security theater——一旦 agent 能写代码也能跑代码,边界实际上已经不存在;逐条确认只会训练你无脑点"允许"。真正要防数据外泄,得断网或域名白名单,而那样 agent 也基本废了。
替代方案:默认完全信任操作者;需要硬边界就把整个 pi 放进容器/沙箱(官方文档给出 Gondolin micro-VM、Docker、OpenShell 三种模式);需要软策略就用扩展做权限门(permission-gate.ts、protected-paths.ts)。
什么时候不适用你:让 agent 接触生产凭据、或在不可信仓库上工作。那就老实容器化——pi 自己也这么说。
合起来看
六条"不做"背后是同一个取舍:harness 不做 workflow 的决策。每砍掉一个内置功能,pi 都给出了成本更低的替代物——文件(PLAN/TODO/README)、Unix 工具(tmux/CLI)、或一个扩展示例。砍掉的东西没有消失,只是从"核心负债"变成了"用户资产"。
这对我们自己造 agent 的启示是双向的:
- 加功能之前先问:能不能用文件或 Unix 工具解决? 能,就不进核心。
- 但扩展点必须给足。pi 能这么任性,是因为它的扩展 API 覆盖了工具、事件、UI 三层——"核心极简"和"扩展激进"是一体两面,缺一不可。