最近我把 Claude Code 从主力工具降级成了备用工具原因不是它不好用而是它太全能了。全能到每次开始新项目之前我都要先把工具链重新梳理一遍这次到底需要哪些权限、哪些命令、哪些扩展Claude Code 在处理多文件重构、跨模块代码梳理这类大任务时确实是一把好手但日常 80% 的临时小任务也用它就有点杀鸡用牛刀的意思——启动慢、上下文占用大、工具调用链路长而且每次面对一堆内置工具模型还得花时间去“选择”用哪个。后来我在社区里看到有人推荐 pi一个默认只带 4 个工具的极简终端代理搭配上 oh-my-pi 这个配置全家桶我试了一周感受是终于找到了一个“轻量但能干活”的平衡点。这篇就把我的实测过程、配置细节和踩坑记录完整分享一下。1. 为什么我说 Claude Code 太全能了1.1 Claude Code 能做什么做对了什么Claude Code 是 Anthropic 推出的终端编程助手核心使用方式是直接在命令行里用自然语言下发任务它会帮你读取项目文件、定位问题点、修改代码、执行测试甚至完成 git 提交。它的优点非常明确对复杂工程的理解能力强能够跨文件追踪调用关系重构老项目的时候能一口气梳理出“影响面”这是它最吸引我的地方。我当初从编辑器插件转过来第一感觉确实是“爽”。以前要在 IDE 里手动搜索引用、逐个文件改现在一句“把这个函数从 utils 迁移到 service 层并更新所有调用方”就够了。它内部挂载的工具很多像文件读取、代码搜索、终端命令、测试运行、git 操作等都能通过 Agent 自动调度。但问题也随之而来工具太多选择成本就高。模型在每次决策时都要从庞大的工具列表里挑一个最合适的一旦选错链路就会多跑好几轮token 消耗上去了执行速度反而变慢。尤其在脚本任务、临时改配置、快速批量替换这些简单场景下全量工具带来的优势几乎体现不出来。1.2 “全能”的真正代价上手成本和心智负担Claude Code 的新手引导其实做得不错但真正用起来心智负担还是有的。比如权限模型什么时候自动执行命令、什么时候需要人工确认不同版本的默认策略还不一样比如上下文管理项目一大了它会把大量文件读进上下文经常出现“改到一半突然忘了最初需求”的情况你得不断提醒它聚焦目标。还有一个很现实的问题Claude Code 的默认模型是 Anthropic 自家的模型虽然也能通过环境变量接入 DeepSeek 等第三方模型但配置项比较多对只想“快速跑起来”的人来说门槛偏高。尤其在 VSCode 或者 Ubuntu 服务器环境里折腾过的人应该都懂安装本身不难难的是把各种模型端点、密钥、代理参数一次配对。我并不是否定全能型工具而是觉得越是强大的工具越需要分场景使用。大型重构、新项目脚手架、跨模块调研交给 Claude Code 这种全能选手很合适但改个小脚本、格式化一批文件、查一个报错用这么重的工具就是浪费。1.3 pi 的思路默认 4 个工具够用就行pi 这个项目在社区里流传的定位就是“反全能”。它默认只带 4 个工具文件读写、命令执行、代码搜索、会话记忆。你可能会觉得 4 个工具能干吗我刚开始也这么想但实际跑下来发现日常终端里的编码任务80% 都可以被这 4 类工具覆盖。文件读写解决“改代码”命令执行解决“跑代码”代码搜索解决“找代码”会话记忆解决“不重复解释需求”。这四件事凑齐了就是一个能独立完成小任务的闭环。它把自己的职责严格限定在“终端里的轻量代理”而不是一个完整的开发平台。这样设计的好处很明显模型每次决策时只在 4 个工具里挑几乎不会选错响应更快上下文里不需要塞入大量的工具描述留给真正代码的空间就大了权限模型也简单四个工具的行为都可以预判不需要复杂的确认机制。对于我这种经常在服务器上干杂活的人来说这反而是最顺手的状态。2. pi 的四件套每个工具都值得单独聊聊2.1 文件读写工具我最常用的一个pi 把文件读和写合并成了一个大类工具而不是拆成十几个细粒度操作。以前用 Claude Code 的时候它“读文件”和“写文件”是分开的有时还会冒出一个“追加文件”“重命名文件”“创建目录”之类的操作模型判断起来慢我审核起来也累。pi 的 file 工具就是一个统一入口通过参数区分读、写、追加、批量替换。这里有个细节值得说pi 的文件写入默认是“全量重写指定行区间”而不是像某些工具那样每次重写整个文件。这个设计很聪明既避免了模型输出完整个大文件导致 token 爆炸也降低了误改其他代码的风险。我实测下来批量替换硬编码路径、给多个函数加日志这类任务file 工具配合 search 工具一起用效率非常高。使用上要注意的是pi 对文件编码的判断比较保守遇到 GBK 编码的老项目文件可能会出现乱码。我一般会在项目根目录放一个.pi_config文件里面指定encoding: utf-8或者按单文件覆盖这个后面实操章节会细讲。2.2 命令执行工具把终端还给你很多 AI 编程工具的命令执行权限都做得“过于安全”每一步都要确认结果确认弹窗比手动敲命令还烦。pi 的 run 工具则走另一个极端思路默认允许执行白名单内的命令白名单之外的命令会直接拒绝而不是询问。白名单默认包括ls、cat、grep、find、npm、pip、python3、git status这类常用命令。你可以通过配置把git commit、docker compose up之类的高危命令加进去或者反过来把某些命令设为“永不执行”。# pi 配置示例 [run] whitelist [ls, cat, grep, find, npm, pip, python3, git status] blacklist [sudo, rm -rf]我一开始觉得这个设计有点激进但用久了反而觉得这才符合“终端工具”的定位。AI 代理本来就该是半自动辅助不该越俎代庖。真要执行敏感操作我自己手动来比让 AI 代劳更安心。2.3 代码搜索工具AI 的重点其实是定位很多人低估了搜索工具的重要性觉得“AI 不就应该自己找文件吗”。但现实是小模型的检索能力本来就有限与其让模型瞎猜文件路径不如给它一个高效的搜索工具直接拉取结果。pi 的 search 工具内置了类似rg的索引逻辑支持正则、文件名通配、内容过滤返回结果直接附带行号和上下文片段。这个工具在日常用得最多的是“找定义”“找引用”和“找硬编码”。比如你怀疑某个配置项在多个文件里被写死了一条 search 命令把所有命中点列出来file 工具跟进修改整个链路特别顺畅。相比之下Claude Code 的代码搜索能力也很强但它把搜索能力拆成了“全局搜索”“语义搜索”“文件搜索”等多种模式反而让模型经常选错入口。还有一点pi 的 search 工具返回结果会默认去重同一个文件里重复出现的匹配项会被折叠成一条记录。这对处理大型代码库特别有用避免了上下文被无关结果刷屏。我建议你在接大项目的时候先让 pi 建立一次项目文件索引之后搜索速度会有明显提升。2.4 会话记忆工具一个被低估的关键工具会话记忆是 pi 默认 4 个工具里最不起眼却被我夸过最多次的一个。它做了一件事让 pi 在多次任务之间记住你的项目约定、命令偏好和上下文背景不需要每次重新解释。比如我在一个 Python 项目里已经告诉过 pi“测试统一用 pytest不要用 unittest”这个约定会被写入会话记忆。下次再让它改代码它会自动遵守不会“失忆”。Claude Code 也有类似能力但如果项目大、工具多上下文很快就被淹没经常聊了几句它就忘了旧约定。pi 的记忆工具本质是一个轻量的本地 KV 存储支持设置长期记忆和会话级临时记忆。长期记忆会持久化到~/.pi/memory.json会话级记忆只存在当前 session 中。我建议你把项目特有的东西放在项目级记忆里比如“这个仓库是 monorepo 结构”“前端构建命令是 pnpm build 而不是 npm run build”。{ project: web-app, memory: [ {key: test_framework, value: pytest}, {key: build_command, value: pnpm build}, {key: coding_style, value: google style} ] }记忆工具用好了pi 用起来会越来越顺手这也是它有“养成感”的来源。3. oh-my-pi 全家桶核心瘦身外围可以豪华3.1 目录结构一眼看懂pi 本身走极简路线oh-my-pi 则是负责“豪华外围”的配置全家桶。名字明显是在致敬 oh-my-zsh结构也借鉴了那一套插件、主题、别名、初始化脚本全部预先配好clone 下来就能用。我的 oh-my-pi 目录结构大致如下~/.oh-my-pi/ ├── aliases.zsh # 终端别名集合 ├── init.zsh # 初始化入口 ├── plugins/ │ ├── docker/ # docker 命令增强 │ ├── git/ # git 工作流快捷命令 │ ├── python/ # venv 自动激活、pip 加速 │ ├── node/ # nvm 集成、npm 镜像切换 │ └── tmux/ # tmux 会话管理 ├── themes/ │ ├── minimal.zsh │ └── powerline.zsh └── models/ ├── claude.conf ├── deepseek.conf └── local.conf它把配置分成几大类用的时候按需启用。核心思想就是pi 本身不做任何“多余”的事所有锦上添花的操作都来自 oh-my-pi 这个可选层。你不用它pi 照常能跑你用了它体验会更顺手。3.2 插件机制需要什么再加什么oh-my-pi 的插件机制很克制没有一上来就给你开几十个插件。每个插件都是独立的目录里面包含 pi 的配置片段、工具扩展函数和初始化脚本。想用就在init.zsh里把它加入启用列表不想用直接删掉。我实际启用最多的是这几个git 插件提供pi review一键让 pi 检查当前分支 diff并生成审查意见。python 插件自动检测项目里的虚拟环境接入 pi 会话记忆执行测试时自动激活 venv。tmux 插件让 pi 在 tmux 新开窗格执行长任务不至于阻塞当前会话。node 插件自动切换 Node 版本配合 npm 调试命令使用。插件机制最直观的价值是“把经验沉淀成配置”。比如你在团队里摸索出一套很顺手的命令组合完全可以把它封装成自己的插件放到 oh-my-pi 的 plugins 目录下下次环境重装时直接复用。3.3 模型路由与快速切换oh-my-pi 里我最喜欢的一个功能是模型路由。pi 本身不绑定固定模型你可以通过环境变量指定不同后端而 oh-my-pi 把常见的模型配置做成了独立文件用一条命令就能切换。比如日常快速任务我用轻量的本地模型延迟低、不花钱遇到代码理解要求较高的任务切换到 DeepSeek 或者 Claude 模型需要完全离线的时候再切回本地模型。这些切换动作在 oh-my-pi 里被封装成一条命令pi model use deepseek pi model use claude pi model use local它本质上就是帮你改了环境变量和 pi 的配置文件省得每次手动 export。对于经常在多环境、多模型之间横跳的开发者来说这个功能提升非常直接。4. 装机前的准备4 个必查项少一个都会卡壳4.1 运行时检查清单安装 pi 之前我建议先花两分钟把环境检查一遍避免装到一半卡住。第一个必查项是 Node.js 版本官方要求的版本一般是 18 以上推荐 20。如果你的环境比较老可以先升级 Node 再往下走。node -v npm -v python3 --version git --version第二个必查项是终端的默认 Shell我测试时在 bash 和 zsh 下都能正常运行但 oh-my-pi 的别名和初始化脚本对 zsh 的适配更完整。如果你主力是 bash也不耽误使用只是部分主题效果和自动补全功能会有差异。第三个必查项是磁盘和权限。pi 的安装文件不大但运行时会在~/.pi目录写日志、记忆和临时文件要确保这个目录有写权限。如果在公司服务器上注意不要用 root 安装全局 npm 包建议配置用户级的 npm prefix。# 用户级 npm 配置 npm config set prefix $HOME/.npm echo export PATH$HOME/.npm/bin:$PATH ~/.bashrc source ~/.bashrc4.2 API Key 和模型选型的取舍pi 只是一个壳真正干活的是背后的模型。所以第二个必查项是你的模型后端配置。如果你用默认的 Claude 模型需要提前准备好 API Key并在环境变量里指定export ANTHROPIC_API_KEYyour-api-key如果你想用 DeepSeek 或者其他兼容 OpenAI 协议的服务pi 也支持通过环境变量切换 base_url 和模型名。我实测下来DeepSeek 在代码补全和小规模重构上的表现很稳定而且成本比 Claude 低不少适合日常高频使用。export PI_MODEL_PROVIDERdeepseek export PI_MODELdeepseek-chat export PI_API_BASEhttps://api.deepseek.com/v1 export PI_API_KEYyour-deepseek-key这里有个坑要提醒不同模型的工具调用协议不完全一致pi 的 4 个工具是以 Anthropic Function Calling 格式设计的部分第三方模型对这个格式的支持不到位会出现“工具名返回错误”的情况。我建议先拿本地模型或 DeepSeek 跑通一个最简单的文件读写任务再逐步放大场景。4.3 终端里的 alias 与环境变量第三个必查项是别名冲突。很多开发者已经在终端里配过pi作为别的工具的别名比如树莓派相关的脚本或者圆周率计算工具装完 pi 之后可能会互相覆盖。我在一台老服务器上就遇到过pi指向了另一个程序排查了半天才意识到是 PATH 顺序问题。建议装完先跑一下which pi确认路径指向。如果不希望 pi 这个名字被占用也可以在 oh-my-pi 的 aliases 里给它起个备用名比如pipi或者pit按个人习惯来。# 检查 pi 指向 which pi pi --version第四个必查项是系统代理。如果你所在网络环境需要走代理才能访问模型 API记得在环境变量里设置 HTTPS_PROXY 和 HTTP_PROXY否则会卡在连接阶段错误信息还不直观。不过我这里要提醒一句配置网络一定要遵守当地法律法规和公司规定别乱来。5. 完整实操从零跑通 pi oh-my-pi并完成一个小任务5.1 安装 pi 的最小可运行版本第一步安装 pi使用 npm 全局安装即可一条命令搞定npm install -g pi装完之后先验证版本然后做一次最小初始化。初始化过程会生成默认配置文件~/.pi/config.toml里面会列出默认启用的工具清单。这时你可以在命令行里直接跟 pi 对话做一个最简单的测试pi 列出当前目录下的文件并说明每个文件是什么如果这一步能正常返回说明 pi 的核心链路已经通了。这一步我建议不要跳过很多问题提前暴露比后面排查容易得多。5.2 Clone 并挂载 oh-my-pi最小版本跑通之后再装 oh-my-pi 就顺理成章了。git clone https://github.com/your-user/oh-my-pi.git ~/.oh-my-pi如果你在社区里找不到我这份配置也可以自己按第 3.1 节的结构搭一个目录。挂载方式是把初始化脚本加到 shell 配置文件的末尾echo source ~/.oh-my-pi/init.zsh ~/.zshrc source ~/.zshrc挂载完成之后可以通过pi doctor检查配置是否完整。这个命令会逐个检查工具可达性、模型端点、记忆目录权限并给出修复建议比手动排查方便很多。pi doctor5.3 实操一个真实任务批量改写代码里的硬编码路径光说不练没用我拿一个真实到有点常见的场景来演示项目里有十几个 Python 文件把数据库路径硬编码成了/data/old_path/现在要统一改成/data/new_path/并且只改.py文件。如果用 Claude Code我会输入一大段指令它会自动搜索、修改、汇报整个过程没问题但稍显“重”。如果用 pi我的思路是分步驱动每一步都确认结果pi 用 search 工具在项目里搜索 /data/old_path/只查 .py 文件pi 会返回所有命中文件列表和行号。确认列表无误后我继续pi 用 file 工具把以上所有 .py 文件里的 /data/old_path/ 替换为 /data/new_path/执行完再让它确认一遍结果顺便跑一下项目里的测试脚本。整个过程下来没有复杂的权限交互也没有多余的工具调度4 个工具之间来回切换非常干净。5.4 一行命令把 pi 接入 VSCode 终端很多人习惯在 VSCode 的集成终端里干活pi 同样可以直接使用。只需要在 VSCode 的settings.json里把默认终端改成你的 shell确保PATH里包含 Node 和 pi 的路径即可不需要额外安装插件。{ terminal.integrated.defaultProfile.linux: zsh, terminal.integrated.env.linux: { PATH: /home/user/.npm/bin:/usr/local/bin:/usr/bin:/bin } }用 VSCode 集成的终端跑 pi还有一个额外的好处输出里的文件路径可以直接 Cmd/Ctrl 点击跳转方便在编辑器和终端之间来回切换。这也是我平时最常用的工作姿势。6. 常见问题排查速查表6.1 工具调用失败日志什么都看不出来这是我遇到最多的问题。pi 调用工具失败时终端只显示一个简单的错误码不仔细看日志根本不知道是权限问题还是模型返回格式问题。排查思路分三步先看~/.pi/logs下的最近日志确认是工具执行报错还是模型输出解析报错。如果日志显示“tool result format invalid”十有八九是模型 API 返回格式和 pi 的预期不一致换一个模型端点试试。如果日志显示“permission denied”去config.toml里检查 run 工具的白名单配置。tail -50 ~/.pi/logs/pi.log6.2 4 个工具不够用怎么办有几次我确实觉得 4 个工具不够特别是要操作 Docker 容器或者调数据库的时候。这时不要硬撑——pi 允许你在配置里添加自定义工具只要按它的工具接口规范写一个 JSON Schema 描述就行。我加过最实用的是一个db_query工具用来在开发环境里执行只读 SQL。添加方式是在配置文件的[tools.custom]段注册工具名、参数说明和执行命令模板。一但注册成功它在对话里就能像内置工具一样被调用。[tools.custom.db_query] description 在开发数据库上执行只读 SQL params query: string command psql $DB_URL -c \{{query}}\6.3 token 消耗太快怎么办token 消耗快通常不是因为对话次数多而是每次请求都带上了太多上下文。pi 在长会话里会把历史记忆和文件内容一并发送项目一复杂消耗就上来了。我的做法是用 “会话重置” 指令清空临时记忆避免上下文越滚越大。把长期记忆里的无关约定定期删掉。选择便宜快速的模型处理日常任务只在关键时刻切到更强的模型。6.4 Claude Code 和 pi 同时在环境里的冲突与共处这不是二选一的问题我实际两个都在用。Claude Code 负责重活pi 负责快活它们之间没有直接冲突但要留意两点两个工具都把会话配置写在~目录下最好用不同的配置目录隔离避免互相读取多余的上下文。如果你在 VSCode 的同一个项目里既启动 Claude Code 又启动 pi建议把各自的启动命令写清楚不要同时在一个终端里开两个交互会话否则日志容易混淆。也可以结合我的习惯进一个新项目先用 pi 快速跑一遍目录结构、测试命令、代码风格把这些信息写进记忆遇到大规模重构再用 Claude Code 接手。两个工具各管一段效率更高。7. 实操心态与两个小习惯7.1 给工具起别名提升效率给常用命令起短别名是一个被低估的效率提升手段。我自己的.zshrc里加了这几行alias pi4pi --toolsfile,run,search,memory alias pidpi --toolsfile,run,search,memory --debug alias pi-localpi model use localpi4是我最常用的命令因为它强制把工具限制在最核心的 4 个上避免不小心用到自定义工具。这在需要“只做一个精确改动”的场景里特别好用模型不会东拉西扯。7.2 不迷信全家桶什么时候该禁用插件oh-my-pi 叫全家桶但不意味着每个插件都适合你。插件越多pi 启动时加载的配置就越多交互延迟会变高有时还会因为插件里的环境变量互相干扰导致命令行为异常。我建议新环境只开 2-3 个核心插件比如 git、python其他按需慢慢加。每加一个插件跑一遍pi doctor验证配置没问题再继续。7.3 我最后想分享的体会用 pi 这一个多月我最大的体会是工具链的价值不在于“功能多”而在于“边界清楚”。Claude Code 很强大强大到它想帮你解决所有问题pi 则更克制它只做好终端里那几件事。配合 oh-my-pi 的外围配置你既能享受极简核心的高效率又能拥有类似 oh-my-zsh 的便捷体验。如果你手头正有一台服务器、一堆日常脚本和偶尔的代码改动需求我真心建议你按这篇文章的步骤试一下 pi oh-my-pi。先跑通最小配置再加插件再调模型你会发现原来在终端里“说说话就能干活”可以这么轻量。最后再分享一个小技巧给 pi 的会话记忆里写清楚每个项目的构建命令和测试框架一个月之后你会回来感谢这个决定的。
