Claude Code 确实是目前终端编程智能体里名声最响的一个工具面板大而全几乎所有能在终端里做的事它都能接手。但“全能”这两个字在我实际用了两三个月之后慢慢变成了一种负担。每轮推理模型都要在一大堆工具里做选择题工具返回的 JSON 又疯狂吃掉上下文配置项越来越多团队里两个人能吵出三种用法。后来我换了一条完全相反的路线——一个只保留 4 个核心工具的 pi再用 oh-my-pi 把它武装成全家桶。这篇文章就把我的完整体验、踩坑记录和配置方案整理出来给同样被“工具过载”困扰的人一个参考。1. Claude Code 太全能反而成了日常开发的负担1.1 Claude Code 给过我的“全能幻觉”先说清楚我并不是要否定 Claude Code。它在大型重构、跨文件联动、复杂架构分析这些场景里依然是目前最能打的选手之一。我第一次用的时候也被震撼到它能自己翻仓库、自己跑测试、自己改代码像一个真的坐在你旁边的资深工程师。但正是这种全能让我渐渐产生一种依赖——不管任务大小都习惯性丢给它。结果是什么呢工具太多模型偶尔会选错工具。比如想搜本地代码它却去调 web search想改文件它先生成一个看起来华丽但完全用不上的大计划。上下文窗口被工具返回撑爆。Claude Code 默认带不少工具每次工具调用的返回结果都要进上下文长任务跑到一半就开始“失忆”前面的决策全忘了。配置成本高。权限规则、hooks、子代理、MCP 生态……每一项都需要学习成本。对我这种“只是想快速改点代码”的人来说确实有点重。我印象很深的一次我只是想改一个 30 行的 shell 脚本结果 Claude Code 启动后先扫描了整个仓库、加载了一堆工具配置光启动到进入状态就花了快一分钟改完文件之后还自作主张帮我跑了一遍全量测试。不是说这样不好而是对于这个任务来说确实有点“高射炮打蚊子”。1.2 当我开始盘点自己真正需要的工具有段时间我认真盘了盘我日常给终端编程智能体提的需求80% 可以归成这么几类读文件、看代码逻辑执行命令、看输出、找报错修改文件、重跑验证跨会话记住项目上下文和我的偏好。也就是说真正高频的核心能力只有四个方向读、写、执行、记忆。其他那些炫酷的工具——网页抓取、子代理、多模态输入、花哨的插件生态——大多是锦上添花而不是雪中送炭。想通这一点之后我就开始寻找一个“只做这四件事”的工具于是找到了 pi。1.3 pi 的出现把“极简”做成设计原则pi 是一个社区里关注度很高的轻量级命令行编程智能体它的定位非常明确只给模型暴露 4 个工具分别是 shell、read、write、context。它不追求功能大而全而是把“少而可靠”当成第一原则。我一开始是怀疑的4 个工具够用吗但实际用下来我发现它反而给了我一种 Claude Code 没有的踏实感——模型几乎不会用错工具因为选项就摆在那里每一步的行动链很短看 → 想 → 改 → 验清清楚楚上下文也很干净不会被一堆无关工具的输出污染。pi 适合谁我觉得特别适合这几种人日常任务以改 Bug、写脚本、做小模块为主不需要重型架构分析的开发者被 Claude Code 的配置复杂度和工具噪音劝退的人希望接本地模型或开源模型的用户——pi 对 OpenAI 兼容接口支持得很干脆接什么模型你说了算。如果你需要的是动辄跨 20 个文件的大型重构那 pi 可能不是最优解至少现阶段我会推荐继续用重型方案。但作为日常主力它的定位非常精准。2. pi 的核心设计4 个工具组成最小闭环2.1 为什么是 4 个而不是 40 个很多人看到“只有 4 个工具”会下意识觉得这是功能残缺但我觉得这恰恰是它设计最聪明的地方。先算一笔账每次模型推理时工具列表是要进入注意力的。工具越多模型每轮要做的工作越多。几十个工具的 agent 看起来能力上限高但实际使用时错误率和延迟都会上升。而 4 个工具的情况下模型几乎不用在“选工具”上花任何心思指令遵循质量明显更高。我自己的实测感受是同样一个任务pi 的初次尝试成功率比我在 Claude Code 里关掉一堆工具后还要高一点。因为它的工具集合是精心裁剪过的不存在“两个工具功能相似”让模型犯迷糊的困惑。另一个容易被忽略的点工具少了系统提示里那段工具描述就短省下的 token 可以留给真正的代码内容。对长任务来说这个差别会在后半段放大——很多 agent 后期“变笨”其实不是模型不行而是上下文被工具定义和工具返回占满了。2.2 每个工具的职责边界四个工具的划分本质上是把一个程序员在终端里的行为抽象成了四类原子操作shell一切命令动作的出口。跑测试、查 git、构建、搜索文件、调用其他 CLI 工具全都可以通过 shell 完成。它是最万能的一个工具也是整个 agent 的“手”。read读取文件的工具。支持按行号区间、按模式读取大文件会自动分块。它存在的意义是给模型提供精准的“视力”而不是一次把整本书塞给模型。write写入和修改文件的工具。社区版本里通常支持全量写入和最小 patch 两种模式写完自动生成 diff 让用户确认。它是 agent 的“笔”。context最特殊的一个工具。它不直接操作文件系统而是维护一个项目级记忆包括项目结构索引、历史决策、用户偏好、任务清单。你可以把它理解成 agent 的“笔记本”。这个设计最妙的地方在于闭环完整性任何你交给 agent 的任务都可以通过这四个工具完成“理解 → 行动 → 验证”的循环。如果需要更多能力比如发 HTTP 请求、查数据库不需要改核心——让模型用 shell 调 curl、调 sqlite3 就行。2.3 四工具模式下的实测表现我在几个真实项目里做过对比用同一个模型、同一套 API分别在 pi 和 Claude Code 上执行同样的任务。结果大致如下任务类型pi4 工具Claude Code全工具我的判断修复单文件 Bug成功率高速度快成功率高启动慢pi 胜写一个 100 行左右的脚本基本一次过偶尔会过度设计pi 胜跨 5 个文件的耦合改动需要多轮提示一次性能做完Claude Code 胜大型仓库结构梳理会丢上下文有架构分析优势Claude Code 胜接本地开源模型兼容性好需要折腾pi 胜这个表只能代表我的个人使用习惯但趋势很明显任务越小、越聚焦pi 的优势越明显任务越大、越分散Claude Code 的重火力才有用武之地。我把这个结论跟朋友聊的时候有人打了个比方Claude Code 是瑞士军刀pi 是一把好菜刀。切菜时菜刀比瑞士军刀好用多了但真要到野外求生你还是得带瑞士军刀。这话糙理不糙。3. oh-my-pi把极简单工具武装成全家桶3.1 从 oh-my-zsh 借鉴来的插件化思路如果你用过 oh-my-zsh那 oh-my-pi 的理念你一定能秒懂核心保持最小一切能力通过插件按需加载。pi 本身坚持 4 工具不动摇但用户的需求是五花八门的。有人想要自动生成 commit message有人想要命令历史补全有人想要按项目记录 TODOs。这些需求如果都塞进核心那 pi 就不再是 pi 了。oh-my-pi 就是用来解决这个问题的它在 pi 外层搭一套插件管理机制让用户按需装插件。安装方式很简单社区最常见的做法# 通过 pi 的插件管理器安装 pi plugin install oh-my-pi pi plugin enable oh-my-pi装完后重启 pi 会话再用pi doctor检查一下环境和插件兼容性。如果一切正常你会看到提示符变样了还多了一堆可用命令——比如pi up、pi mem、pi log这类快捷指令。整个过程的体验确实很像当年装 oh-my-zsh 的感觉。3.2 必装插件清单我用下来的推荐列表分三类效率类git-integrator自动生成符合规范的 commit message还能在提交流程里帮你只看 diff 摘要command-history记录常用命令配合 autosuggest 实现像 zsh 一样的命令联想shell-timeout给 shell 工具加超时保护防止模型写出死循环把终端卡死。记忆类project-memory项目级长期记忆重启会话后还能记住之前的决策todo-tracker在 agent 内部维护任务清单多步任务不容易跑偏architecture-notes帮你维护一份仓库架构笔记新会话启动时快速恢复上下文。体验类themes换提示符主题纯审美但真的会让人心情好exit-code 提示上一条命令失败时高亮显示模型漏看报错的情况会少很多。我自己的习惯是效率类全装记忆类按项目开体验类随便选。插件并不是越多越好每多一个插件启动时会多加载一些东西也会多一分配置冲突的风险。记住 oh-my-pi 的核心价值是“按需”不是“全装”。3.3 按项目精细化启停插件oh-my-pi 一个比较贴心的设计是支持按项目粒度启停插件。比如你在一个纯前端项目里不需要 architecture-notes在数据仓库项目里不需要前端构建辅助插件就可以在项目目录下建一个配置覆盖全局设置。项目根目录下创建.pi/project.json{ plugins: { project-memory: true, todo-tracker: true, architecture-notes: false, git-integrator: true }, context: { maxTokensPerFile: 4000, autoInit: true } }这个文件会被 pi 自动识别。它的好处是同一台机器上不同项目拥有不同的 agent 配置互不干扰。这一点在我同时维护多个仓库时尤其受用——以前全局配置改了会影响所有项目现在每个项目自己管自己的插件省了很多心。4. 实操安装、配置与日常使用流程4.1 环境要求与跨平台安装pi 目前主流的安装方式是通过 npm 全局安装对 Node.js 版本有要求。官方建议 Node.js 18 及以上我自己的经验是 20 LTS 最稳。如果你本机有 Bun 或 Deno也可以跑便携版。三个常见平台的安装路径# macOS / Linux npm install -g pi-agent # Windows建议先装 WSL2在 Ubuntu 里装 # Windows 原生终端也能跑但路径转义、权限模型会折腾一些安装完成后验证一下pi --version pi doctor如果pi命令找不到大概率是 npm 全局目录不在 PATH 里这个放到后面排查章节细说。VS Code 用户可以在终端面板里直接开一个 pi 会话不需要额外插件如果你想让 pi 出现在编辑器通知里可以装社区做的 VS Code 扩展但说实话我用了几天觉得没必要——pi 的强项就是终端里快速干活开个大编辑器反而违背初衷。4.2 接模型OpenAI 兼容接口是最大公约数pi 默认走 OpenAI 兼容接口这意味着它能接的模型范围非常广OpenAI 系、DeepSeek、各类本地推理服务比如 Ollama、vLLM、LM Studio以及各家兼容网关。对不想被单一厂商绑定的用户来说这是个很实在的优点。我的配置写在~/.pi/config.json{ provider: openai-compatible, baseUrl: http://127.0.0.1:11434/v1, model: qwen2.5-coder:32b, temperature: 0.2, maxSteps: 20, tools: [shell, read, write, context], approveMode: auto, timeoutMs: 30000 }几个关键参数我解释一下approveMode是auto时模型在低风险操作读取、搜索上不需要逐个确认效率高我建议不要全局 auto把 write 和 shell 里会改文件的命令设为手动确认。maxSteps限制单次任务最多行动步数防止模型陷入死循环按我的习惯普通任务 20 步足够大型任务再调高。temperature我固定 0.2编程任务里低一点更稳定。timeoutMs是单次工具调用的超时给 shell 里的长命令留够余量。如果你用的是 Anthropic 模型但想让 pi 调用现在也有第三方兼容层可以桥接不过那属于进阶玩法这里不展开。4.3 第一次实战让 pi 修一个真实 Bug说了这么多理论来一个实际任务演示。假设我有个 Python 脚本用户反馈日期解析总是报错。我把报错信息和文件路径丢给 pipi 看看 utils/date_parser.py修复日期解析报错的问题。报错信息ValueError: time data 2024-13-01 does not match format %Y-%m-%dpi 的实际处理流程大致是这样先用 context 工具查项目索引定位 date_parser.py 的位置用 read 读取文件理解现有解析逻辑用 shell 跑一下python -c复现异常确认问题用 write 修改解析代码加了异常处理和对非法月份的回退逻辑用 shell 重新跑测试用例验证通过后输出 diff 让我确认。整个过程里模型的动作非常清晰我只需要在最后确认一次 diff。相比 Claude Code 那种“它自己决定跑全量测试、自己装依赖”的霸气pi 更像个听话的执行者——你让它改哪它就改哪改完给你看证据。这里有个小技巧任务描述里尽量包含文件路径和具体报错信息pi 会少走很多弯路。如果你的命令太长也可以先pi context init让它建立项目索引再开始干活。4.4 VS Code 里怎么跟 pi 配合很多人问我在 VS Code 里怎么用 pi。我的方案很简单用 VS Code 内置终端开两个面板——一个跑编辑器逻辑一个跑pi会话。那种把 pi 完全嵌入 IDE 的扩展我也试过但总觉得多了一层不如终端直接。如果你确实需要编辑器集成社区方案一般是装一个终端集成扩展把 pi 设置为默认 shell 的一个命令别名。但我的经验是pi 的最佳使用场景就是纯粹的终端。它不需要 IDE不需要可视化面板一个终端窗口加一个模型接口就够干活了。这本身就是它存在的意义。5. 常见问题与排查实战5.1 pi 命令找不到、启动报错这是新人最容易踩的坑。现象pi命令提示 command not found。原因npm 全局包的 bin 目录不在 PATH 里。解决先看npm config get prefix然后把对应的 bin 目录加到 shell 的 PATH。macOS 上常见的是/usr/local/bin如果用了 nvm则是~/.nvm/versions/node/.../bin。还有一个我踩过的Windows 下直接在 cmd/PowerShell 里跑npm install -g后命令能识别但启动报错 EPIPE。后来我总结在 Windows 上就用 WSL2所有终端 agent 类工具在 WSL 里的体验都比原生 shell 稳定得多。文件路径、权限、信号处理全都省心。5.2 模型死循环、乱改代码四工具模式下死循环的概率已经比巨型工具集低很多了但还是会遇到。典型症状是模型反复 read 同一个文件、反复执行同一条命令或者在一个错误修复上原地打转。我的排查顺序看maxSteps是不是设太高了先压到 10 看看。步骤少了模型会更早停下来汇报而不是硬撑。打开--dry-run模式观察模型每一步的动作确认它是不是在重复无效操作。如果发现是直接在会话里打断它补充更明确的指令。如果是写代码任务让它先输出计划再动手。pi 的 context 工具可以存一份 task plan模型会照着计划走跑偏概率小很多。还有一个很实用的经验当模型开始乱改代码十有八九是上下文里已经没有准确信息了。这时候不要让它继续猜而是明确告诉它“先重新 read 一下 config.py 第 40 到 60 行”把地面信息重新喂给它。5.3 上下文过早耗尽四工具本身很省上下文但如果你加载了一堆 oh-my-pi 插件插件输出的信息也会进上下文。我见过一个项目每次启动会话时 architecture-notes 插件自动往 context 里塞了一份两千行的架构文档结果没聊几句就上下文告急了。排查方法pi context stats查看当前上下文占用检查哪个插件在启动时写入大块内容如果就是某个插件导致的按项目关掉它或调整它的输出长度上限。另外长任务请主动分段。让 pi 完成第一段后用 context 工具保存阶段性结论然后开新会话继续。这不丢人反而是正确地使用方式——再大的上下文也不如人类的分阶段工作流可靠。5.4 oh-my-pi 插件冲突与升级踩坑插件装多了难免冲突。我遇到过两次比较典型的两个记忆类插件同时维护 context 文件导致内容互相覆盖oh-my-pi 升级后某个旧插件接口不兼容启动直接报错。排查步骤很粗暴但有效pi plugin list pi plugin disable 插件名 pi doctor先把所有插件禁用确认核心能正常工作再逐个启用就能定位到是哪个插件出的问题。建议在project.json里控制插件的启用范围而不是一股脑全局启用。还有一个经验是升级前先看一眼 release notes尤其是大版本升级插件接口很容易变。6. 我一直到现在的分工策略最后聊聊我现在的分工。很多人以为“极简”和“全能”只能二选一我一开始也这么想后来发现核心问题不是工具不行而是我对场景没有区分。我现在的默认工作流是日常小任务、改 Bug、写脚本、调接口pi oh-my-pi启动快、上下文省、模型很少跑偏跨文件联动、大型仓库重构、复杂技术方案设计Claude Code 或者其他重型方案火力全开两个工具用同一套模型接口维护成本并没有翻倍。如果你决定试试 pi我的建议是先别急着装一堆插件用纯四工具跑一周把它的能力边界摸清楚。然后再上 oh-my-pi一个一个插件加加到你觉得“顺手”就停。插件不是越多越好极简内核才是 pi 最值钱的东西。我个人最大的感受是工具不在多在于它能不能在你最需要的那一刻不添乱。pi 和 oh-my-pi 的组合让我重新找回了那种“打开终端就能干活”的清爽感。希望这篇记录对你有用。