1. 为什么我要从 Claude Code 转向 pi1.1 一个全能选手带来的真实困扰Claude Code 刚出来那阵子我几乎是第一时间就上手了。说实话它的能力确实强文件读写、命令执行、代码搜索、任务规划、子代理调度几乎你能想到的编码代理该有的能力它都塞进去了。但用得越久我越有一种说不出的别扭感——这东西太重了。重在哪首先是启动链路长。每次开一个新会话它要加载一大堆系统提示、工具定义、上下文管理逻辑冷启动那几秒的等待在频繁切换任务时特别磨人。其次是行为不可预测。工具越多模型在每一步的决策空间就越大有时候我只是想让它读一个文件它却自作主张地先去搜索、再规划、再调用子代理绕了一大圈才回到正题。再就是定制成本高。想改个提示词、换个模型、调个工具行为得钻进它那套庞大的配置体系里改完还不一定生效。我不是说 Claude Code 不好它在复杂任务上的表现确实顶。但问题在于我日常 80% 的工作其实是读代码、改代码、跑命令、查资料这四件事的排列组合用一台航空母舰去送外卖属实有点浪费。1.2 pi 的核心思路只做四件事但做到极致pi 这个项目吸引我的地方恰恰是它的克制。它整个代理循环只暴露四个工具读文件、写文件、执行命令、以及一个用于任务收尾的完成信号。没有花哨的子代理没有复杂的规划器没有一堆可选的工具开关。你给它一个任务它就在读—想—写—跑这个循环里推进直到它认为任务完成。这种设计哲学我特别认同。工具数量从几十个砍到四个带来的直接好处是模型每一步的决策空间急剧缩小行为变得高度可预测。你不会再遇到我只是让你改个变量名你怎么把整个仓库都重构了这种惊吓。同时系统提示可以写得非常短上下文占用小冷启动快token 消耗也低——这对经常要开一堆并行会话的人来说省的是真金白银。当然四个工具能不能覆盖所有场景答案是绝大多数日常编码任务都能覆盖。因为读、写、跑这三件事本身就是编码工作的原子操作剩下的规划搜索子代理本质上都是这三件事的组合。pi 把这个组合权交回给了模型本身而不是用一堆工具去替模型做决定。1.3 oh-my-pi 是什么给极简内核配一套顺手的全家桶pi 本身是个极简内核开箱即用的体验比较素。oh-my-pi社区里常简称 omp就是围绕 pi 打造的一套配置增强集合你可以理解成给一台裸机装上了顺手的驱动和常用软件。它主要解决几个痛点一是提供开箱即用的模型接入配置省去你手动填 base url、api key、模型名的麻烦二是预置了一批针对常见任务优化的提示词模板三是补上了 pi 原生没有的一些便利功能比如会话管理、历史记录、快捷命令等。打个比方pi 是发动机oh-my-pi 是变速箱加仪表盘加座椅。发动机决定车能跑多快但决定你开得舒不舒服的往往是后面这些。很多人第一次试 pi 觉得也就那样多半是因为没配 oh-my-pi用裸内核去跑日常任务体验自然打折扣。1.4 这套组合适合谁如果你符合下面任意一条这套 pi oh-my-pi 的组合值得你花一个下午试试你日常的编码任务以中小型为主不需要动辄跨几十个文件的巨型重构你对代理行为的可预测性要求高讨厌惊喜你在意 token 成本和响应速度经常开多个并行会话你喜欢折腾配置想把代理调成完全贴合自己习惯的样子你已经用过 Claude Code 这类全能代理想找个更轻的替代或补充。反过来如果你的任务经常是给我把这个遗留系统整体迁移到新框架这种量级那 Claude Code 那套重型装备可能还是更合适。工具没有绝对好坏只有场景匹配。2. pi 的四个工具到底怎么用2.1 读文件工具不只是 catpi 的读文件工具看起来最简单但用起来门道不少。它支持按行范围读取这一点非常关键。很多人习惯让代理读一下这个文件结果一个几千行的文件全塞进上下文token 瞬间爆炸。正确的做法是让代理先读文件头部或特定区间定位到关键部分再精读。我在实际使用中总结出一个习惯对于陌生文件先让它读前 50 行了解结构再根据 import 或函数定义定位到目标区间。pi 的读工具支持传入起始行和结束行配合得好能省下大量上下文。另外要注意读工具返回的内容是带行号的这在后续做精确编辑时非常有用——你可以直接告诉代理把第 87 行那个判断改掉而不是让它去猜。提示读大文件时优先读结构函数签名、类定义、import 块而不是从头到尾通读。代理的上下文是有限资源要像花自己的钱一样花它。2.2 写文件工具覆盖与追加的取舍写文件工具是 pi 里最需要小心使用的。它默认是整文件覆盖写入这意味着如果代理对文件内容理解有偏差一次写入就可能把好好的代码改坏。我的经验是对于小文件或全新文件直接覆盖没问题对于大文件一定要让代理先读、再改、再写并且写之前把要改的片段单独确认一遍。pi 的写工具通常还支持追加模式这在写日志、生成配置文件、往列表里加条目时很有用。但要注意追加模式不会做任何去重或格式校验代理如果判断失误可能往同一个文件里追加重复内容。我踩过一次坑让它往一个 JSON 数组里追加元素结果它追加了两次因为第一次追加后它没确认成功又追加了一遍。后来我养成了习惯追加类操作一定让它先读一遍确认当前状态。2.3 执行命令工具威力最大也最危险执行命令工具是 pi 的灵魂也是风险最高的地方。它让代理能跑测试、装依赖、查 git 状态、执行构建脚本真正把想和做连了起来。但正因为能执行任意命令一旦代理判断失误后果可能很严重——比如误删文件、误改系统配置、往生产环境推代码。我的做法是给命令执行加几道保险。第一在提示词里明确禁止危险命令比如rm -rf、git push --force、任何涉及生产环境的操作。第二对于有副作用的命令要求代理先dry run或先打印出它打算执行的命令确认后再执行。第三把工作目录限制在项目根目录内避免它跑到系统目录去乱搞。# 让代理执行命令时养成先看后跑的习惯 # 第一步让它列出打算执行的命令 # 第二步确认无误后再实际执行 git status git diff --stat2.4 完成信号工具什么时候算做完了pi 的第四个工具是一个完成信号代理调用它表示任务结束。这个设计看似简单实则很讲究。它逼着代理在每一步都要判断我是不是真的做完了而不是无限循环下去。但问题也在这里代理对完成的判断可能和你不一致。它可能觉得改完代码就算完了而你其实还想让它跑一遍测试。解决办法是在任务描述里把完成标准写清楚。比如不要说修复这个 bug而要说修复这个 bug并运行相关测试确认通过测试通过后调用完成信号。把验收标准前置到任务描述里代理的完成判断就会准很多。2.5 四个工具的组合威力单看每个工具都很朴素但组合起来能覆盖的场景其实非常广。读加写等于重构读加跑等于调试写加跑等于开发加验证三个一起用就是完整的理解—修改—验证闭环。我做过统计我日常任务里大约 70% 是读加写20% 是读加跑剩下 10% 才是三个全用上。也就是说大部分时候我根本用不到那些花哨的高级功能。这也解释了为什么 pi 敢只做四个工具因为编码工作的本质就是这几件事的循环工具多了反而是干扰。就像厨房里真正天天用的就那几把刀刀具套装里一半的刀一年都用不上一次。3. oh-my-pi 全家桶的配置与实战3.1 安装与初始化从零到能跑装 pi 本身不复杂但配 oh-my-pi 有几个关键步骤容易卡住。我按自己的实操顺序梳理一遍。首先是环境准备确保你的 Node 版本在 18 以上npm 或 pnpm 能正常用。然后全局安装 pi 的命令行工具再拉取 oh-my-pi 的配置仓库。# 检查环境 node -v npm -v # 全局安装 pi具体包名以官方为准 npm install -g pi/cli # 拉取 oh-my-pi 配置 git clone oh-my-pi-repo ~/.pi/oh-my-pi初始化阶段最容易出问题的是配置文件路径。pi 默认会去~/.pi/下找配置而 oh-my-pi 的配置需要软链或复制到正确位置。我建议直接用软链这样后续更新 oh-my-pi 时不用重新复制。# 用软链把 oh-my-pi 配置接入 pi ln -s ~/.pi/oh-my-pi/config.json ~/.pi/config.json注意如果你之前已经手动配过 pi先备份原配置再操作避免覆盖掉自己的自定义设置。3.2 模型接入base url 与 key 的正确填法oh-my-pi 最实用的功能之一就是帮你管理模型接入。它支持配置多个模型供应商每个供应商有自己的 base url、api key 和模型列表。配置文件的典型结构是这样的{ providers: { default: { baseUrl: https://your-endpoint/v1, apiKey: sk-xxxx, models: [model-a, model-b] } }, defaultModel: model-a }这里有几个坑要提醒。第一base url 结尾要不要带/v1取决于你的供应商填错了会报 404。第二api key 不要直接写死在会提交到 git 的文件里用环境变量引用更安全。第三模型名要和供应商文档里的一致大小写敏感。我见过有人把模型名写错一个字母排查了半小时才发现。3.3 提示词模板把常用任务固化下来oh-my-pi 预置了一批提示词模板覆盖了代码审查、bug 修复、测试生成、重构等常见场景。这些模板的价值在于它们把完成标准和约束条件都写进去了你不用每次从头描述。比如它的 bug 修复模板大致是这样的逻辑先复现问题再定位根因再最小化修改最后跑测试验证。我自己的做法是在这些模板基础上再定制。比如我会在代码审查模板里加一条重点关注边界条件和错误处理在重构模板里加一条保持公共接口不变。这些个人偏好固化下来后每次调用省心很多。3.4 会话管理与历史记录pi 原生对会话的管理比较弱oh-my-pi 补上了这块。它支持给会话命名、保存历史、快速恢复。这在多任务并行时特别有用——你可以给每个任务开一个命名会话切换时直接恢复不用重新交代背景。我的习惯是按项目或按任务类型命名会话比如proj-a-refactor、proj-b-bugfix。历史记录默认保存在本地注意定期清理不然攒多了会占不少磁盘空间。3.5 快捷命令与自定义扩展oh-my-pi 允许你定义快捷命令把一长串常用操作封装成一个短命令。比如我定义了一个review命令一键触发读当前 git diff、按审查模板分析、输出问题列表这一整套流程。这种封装对高频操作特别值能把重复劳动降到最低。{ commands: { review: { prompt: 读取当前 git diff按代码审查模板分析列出问题, tools: [read, exec] } } }自定义扩展这块oh-my-pi 的文档不算特别全很多功能得靠读源码或社区分享。我的建议是先从预置功能用起遇到确实高频的需求再考虑自己扩展别一上来就折腾。4. 实战案例用 pi 完成一个真实任务4.1 任务背景与目标拆解我拿一个真实的小任务来演示给一个 Node 项目加一个命令行参数解析功能要求支持--verbose和--output两个参数并且要有对应的单元测试。这个任务不大但覆盖了读、写、跑三个工具很适合演示。任务描述我是这么写的在 src/cli.js 中增加命令行参数解析支持 --verbose布尔和 --output字符串默认 stdout。解析逻辑抽成独立函数便于测试。完成后在 test/cli.test.js 中补充对应单元测试运行测试确认全部通过后结束。注意我把完成标准写得很明确测试通过才算完。这样代理不会改完代码就草草收工。4.2 代理的执行过程还原代理拿到任务后第一步是读src/cli.js了解现有结构。它读了前 60 行发现这个文件用的是 CommonJS导出了一个 main 函数。接着它读package.json确认测试框架是 Jest。然后它开始写代码在 cli.js 里加了一个parseArgs函数并修改 main 函数调用它。写完代码后它读了一遍自己写的部分确认无误然后去写测试文件。测试写完后它执行npm test发现有一个用例失败——因为--output的默认值处理逻辑有问题。它读了失败信息定位到问题改了代码再跑一次通过。最后调用完成信号。整个过程大概花了不到两分钟token 消耗比我用 Claude Code 做同样的事少了大概一半。4.3 关键决策点分析这个过程中有几个决策点值得说。第一代理选择把解析逻辑抽成独立函数而不是直接写在 main 里。这是因为它读到了任务描述里便于测试这个要求主动做了设计。这说明任务描述里的约束会实实在在影响代理行为。第二测试失败后代理没有慌而是先读失败信息再定位。这得益于 pi 的循环设计——它天然就是跑—看结果—再改的模式不需要额外的调试工具。第三代理在写测试时没有过度设计只覆盖了任务要求的两个参数。如果我用 Claude Code它可能会顺手把整个 cli.js 的测试都补上虽然更全面但超出了我的需求也浪费了 token。4.4 与 Claude Code 做同样任务的对比我特意用同样的任务在 Claude Code 上跑了一遍做对比。Claude Code 的表现是它先做了一轮规划列了个 todo 列表然后开始执行。执行过程中它调用了搜索工具确认项目里有没有现成的参数解析库发现没有才自己写。写完后它跑了测试失败后也修复了。最终结果一样但过程更长token 消耗大约是 pi 的 1.8 倍。差异主要来自两点一是 Claude Code 的规划阶段本身消耗 token二是它的搜索工具会做更广的扫描。对于这种小任务这些额外动作其实是浪费。但如果任务更大更模糊这些额外动作可能就有价值了。所以还是那句话看场景。5. 常见问题与避坑经验5.1 代理陷入死循环怎么办pi 的循环设计有个副作用如果代理判断失误它可能在一个问题上反复打转。比如测试一直失败它反复改同一处代码每次改法都差不多。我遇到过最夸张的一次它在一个类型错误上循环了七八轮。解决办法有两个。一是给任务加最大尝试次数约束比如在提示词里写如果测试连续失败三次停下来汇报问题而不是继续改。二是及时人工介入看到它开始重复就打断把失败信息贴给它帮它跳出局部。5.2 命令执行权限与安全边界前面提过命令执行的风险这里再展开说。pi 默认会执行代理生成的任何命令这在本地开发环境问题不大但如果你在服务器上跑一定要加限制。我的做法是用一个受限的用户账户跑 pi并且把工作目录限制在项目内。另外对于涉及网络请求、文件删除、git 推送这类命令我要求代理必须先打印命令让我确认。oh-my-pi 支持配置命令白名单和黑名单把危险命令拉黑能省不少心。5.3 模型选择与成本控制pi 支持接各种模型选哪个直接决定成本和效果。我的经验是日常小任务用便宜快速的模型就够了复杂任务再切到强模型。oh-my-pi 支持按任务类型配置默认模型我把代码审查配成强模型格式化重命名这类配成便宜模型。成本控制还有个技巧是控制上下文。pi 的读工具支持行范围善用它。另外定期清理会话历史别让无关的旧上下文一直挂着。5.4 配置文件踩坑速查问题现象可能原因解决办法启动报 404base url 结尾/v1不匹配对照供应商文档调整模型名无效大小写或拼写错误复制文档里的准确名称配置不生效软链指向错误检查~/.pi/config.json指向key 泄露风险明文写在配置文件改用环境变量引用会话丢失历史目录被清理检查历史保存路径配置5.5 我踩过的三个真实坑第一个坑是软链循环。我有次把配置软链指到了自己导致 pi 启动时无限递归读取直接卡死。排查了半天才发现是ln -s的目标写错了。教训是软链建完一定要ls -l确认指向。第二个坑是模型名带版本号。有些供应商的模型名带日期后缀比如model-2024-01-01我按文档写了个不带日期的结果报模型不存在。后来学乖了配置前先用 curl 测一下模型列表接口。第三个坑是命令执行的工作目录。pi 默认在启动目录执行命令我有次在 home 目录启动结果代理的npm install装到了 home 下把全局环境搞乱了。现在我都固定在项目根目录启动。6. 我的使用心得与扩展思路6.1 什么时候该用 pi什么时候该上重型工具用了几个月下来我的判断标准很清晰任务边界清晰、涉及文件少、验收标准明确用 pi任务模糊、需要大量探索、跨多个模块用 Claude Code 这类重型工具。前者追求的是快和准后者追求的是全和稳。我现在的日常是两者混用。早上处理一堆小任务用 pi快速清掉遇到需要深入调研的大任务再切重型工具。这种搭配让我的整体效率比只用一种工具高不少。6.2 把 pi 嵌进自己的工作流pi 的命令行特性让它很容易嵌进现有工作流。我把它接进了 git hook提交前自动跑一轮代码审查也接进了任务管理工具从 issue 直接生成 pi 任务。oh-my-pi 的快捷命令让这些集成变得很简单基本就是配个命令模板的事。6.3 后续可以怎么扩展pi 的极简内核其实留了很大的扩展空间。我最近在尝试的是给它加一个项目记忆层把项目的约定、常用命令、目录结构存成一个文件每次任务开始时自动注入上下文。这样代理就不用每次都重新摸索项目结构了。另一个方向是给四个工具加包装。比如在读工具外面包一层缓存避免重复读同一个文件在写工具外面包一层 diff 预览写之前先给你看改动。这些扩展都不需要改 pi 内核在 oh-my-pi 层面就能做。最后分享一个小技巧pi 的完成信号工具其实可以玩出花样。我给它配了个钩子代理调用完成信号时自动跑一遍 lint 和测试只有都通过才真正结束。这样相当于给代理加了一道自动验收省得我每次手动检查。这个钩子用 oh-my-pi 的扩展机制实现大概二十行配置就搞定了性价比极高。