企业官网建设流程全解析

1. 为什么我要从 Claude Code 换到 pi 试试

Claude Code 刚出来那阵子，我几乎是第一时间就上手了。终端里敲一行命令，它就能读项目、改文件、跑测试、提交 commit，确实把"AI 结对编程"这件事从 IDE 插件里拽到了命令行。用了几个月之后，我发现自己越来越依赖它，但同时也越来越觉得它"重"——启动慢、上下文塞得满、工具调用链路长，有时候我只是想让它帮我改一个配置文件里的两行，它却要先读一遍整个目录树，再规划半天，最后给我一个"我建议你这样做"的长篇回复。

这种"全能型选手"的体验，很像你请了一个什么都会的资深工程师，但他每次动手前都要开个会。对于复杂重构、跨文件改动，这种谨慎是好事；但对于日常那些"帮我看看这个报错""把这个函数改成 async""跑一下测试看看哪里挂了"的碎片化需求，就有点杀鸡用牛刀了。

后来我在社区里看到有人提到pi这个 Coding Agent，核心卖点很直接：只用 4 个工具。我当时的第一反应是"4 个工具能干嘛"，第二反应是"这不就是我一直想要的轻量版吗"。于是就有了这次从 Claude Code 到 pi 的迁移尝试，以及后面配上的oh-my-pi（社区里常简称omp）这套"全家桶"。

这篇文章不是要踩一捧一。Claude Code 依然是目前最成熟的命令行 Coding Agent 之一，它的生态、稳定性和对复杂任务的处理能力都很强。我想聊的是：当你的需求偏向轻量、快速、可控的时候，pi 这套组合为什么值得一试，以及怎么把它配到能日常用的程度。如果你也是那种"终端常驻、喜欢自己掌控工具链"的人，下面的内容应该对你有用。

先说清楚适用人群：如果你已经在用 Claude Code，但觉得它有时候太重、太慢、太"话多"，那 pi 值得你花半小时试试；如果你还没接触过任何命令行 Coding Agent，那这篇文章也能帮你理解这类工具到底在解决什么问题，以及"工具数量"这个设计选择背后的取舍。

2. pi 的核心设计：4 个工具到底够不够用

2.1 为什么是"4 个工具"这个数字

要理解 pi 的设计，得先理解 Coding Agent 的本质。一个 Agent 在终端里帮你干活，它需要的能力其实就那么几类：读东西、写东西、执行命令、然后基于结果继续推理。Claude Code 之所以工具多，是因为它把每一类都拆得很细——读文件是一个工具、搜索是一个工具、列目录是一个工具、编辑是一个工具、创建是一个工具、跑命令是一个工具、还有各种任务管理、待办列表、子 Agent 调度等等。

pi 的思路完全相反：把工具数量压到最少，把复杂度交给模型本身的推理能力。它只保留 4 个核心工具，大致对应：

这个设计的逻辑是：大部分编程任务，本质上就是"看—想—改—验"的循环。你不需要十几个专用工具，你需要的是一套通用能力，加上一个足够聪明的模型来决定怎么组合它们。

我一开始担心的是：工具少了，模型会不会"不会用"？实测下来恰恰相反。工具越少，模型的决策空间越小，反而越不容易在"我该用哪个工具"这件事上纠结。Claude Code 有时候会在多个相似工具之间反复横跳，pi 因为只有 4 个，选择成本几乎为零。

2.2 少工具带来的三个实际好处

第一个好处是启动快、上下文省。工具定义本身是要占 token 的。Claude Code 把几十个工具的 schema 塞进系统提示里，这部分开销是固定的。pi 只有 4 个工具，系统提示短了一大截，留给实际代码和对话的上下文就更多。对于大项目，这个差别在长对话里会越来越明显。

第二个好处是行为可预测。工具少意味着模型的行为模式更集中。用久了你会发现，pi 处理任务的方式很稳定：先读、再改、然后跑命令验证。不会突然给你来个"我帮你创建了一个子任务来跟踪这个改动"这种你根本没要求的操作。

第三个好处是调试简单。当 Agent 行为不对时，你要排查的东西少。4 个工具的输入输出都很直白，你能很快定位是"读错了文件"还是"命令跑错了"，而不是在一堆工具调用链里找问题。

注意：工具少不等于能力弱，但它确实意味着某些"高级编排"需要你自己来做。比如你想让 pi 先跑测试再根据结果改代码，你得在提示里说清楚，而不是指望它自动规划出一个多步骤工作流。这是取舍，不是缺陷。

2.3 pi 适合和不适合的任务类型

用了这段时间，我大致摸清了 pi 的舒适区：

特别适合的：

• 单文件或少量文件的修改，比如改配置、调函数、修 bug
• 快速问答式的代码理解，比如"这个模块是干嘛的""这个报错什么意思"
• 跑命令并解读结果，比如测试失败原因分析、构建报错定位
• 脚本类的一次性任务，比如批量重命名、格式转换

不太适合的：

• 跨十几个文件的大重构，这种还是 Claude Code 的规划能力更稳
• 需要长时间自主循环的复杂任务，pi 更偏向"你问我答"的节奏
• 需要大量并行子任务的场景，pi 没有那套编排机制

搞清楚这个边界之后，我的用法就变成了：日常碎片任务用 pi，大工程用 Claude Code。两者不冲突，反而互补。

3. oh-my-pi：给 pi 配一套顺手的全家桶

3.1 omp 解决了 pi 的哪些"原生痛点"

pi 本身很精简，但精简的另一面就是"什么都得自己配"。oh-my-pi（omp）就是社区里为了补这块短板做的一套配置集合，你可以理解成"给 pi 装的一套预设主题+插件+快捷配置"。它主要解决几个问题：

第一是配置管理。pi 的配置文件散在几个地方，模型、API 地址、快捷键、主题各管各的。omp 把这些收拢成一套统一的配置结构，改起来不用到处翻。

第二是开箱即用的体验。装完 omp 之后，常用的模型预设、常用的提示模板、常用的快捷键都配好了，不用从零开始调。

第三是扩展能力。omp 里带了一些社区维护的小工具和钩子，比如自动格式化、提交信息生成、会话历史管理这些，让 pi 更接近"日常能一直开着"的状态。

我用下来的感受是：pi 是发动机，omp 是内饰和仪表盘。光有发动机能跑，但配上内饰之后，你才愿意天天开。

3.2 安装前的环境准备

在动手之前，先把环境理清楚。这套东西对系统要求不高，但有几个前提：

• Node.js 环境：pi 和 omp 都跑在 Node 生态里，建议 Node 18 以上，我用的是 20 LTS，比较稳。
• 包管理器：npm 或 pnpm 都行，我个人偏好 pnpm，装依赖快、磁盘占用小。
• 终端：任意现代终端都可以，我用的是 iTerm2 和 Windows Terminal 两套环境都测过。
• API 访问：你需要有一个能用的模型 API。pi 支持配置自定义 base url，所以你可以接自己习惯的模型服务。

先确认 Node 版本：

node -v npm -v

如果版本太低，建议先升级。Node 版本不对是后面各种奇怪报错的头号来源，我踩过好几次。

提示：如果你在 Windows 上，建议用 WSL 环境来跑这类命令行工具，原生 Windows 下路径和权限问题会多一些。这不是必须，但能省不少事。

3.3 安装 pi 与 omp 的完整步骤

安装 pi 本身很直接，通过 npm 全局装：

npm install -g @pi/pi

装完之后验证一下：

pi --version

能打印出版本号就说明装好了。如果提示命令找不到，多半是 npm 全局 bin 目录没在 PATH 里，检查一下npm config get prefix的输出，把对应的 bin 目录加进环境变量。

接下来装 omp。omp 的安装方式取决于你用的版本，常见的是通过 npm 或者直接从仓库拉配置：

npm install -g oh-my-pi

装完之后，omp 通常会提供一个初始化命令，帮你生成默认配置：

omp init

这一步会在你的用户目录下生成配置文件，一般是~/.pi/或~/.config/pi/下面。具体路径以命令输出为准，别凭记忆猜。

3.4 配置模型与 base url 的关键细节

这是整个流程里最容易出问题的一步。pi 支持自定义 base url，意味着你可以接不同的模型服务。配置一般在配置文件里，结构大致是这样：

{ "model": "your-model-name", "baseUrl": "https://your-api-endpoint/v1", "apiKey": "your-api-key" }

几个关键点：

base url 的结尾。很多服务要求 base url 以/v1结尾，有些不要。这个必须看你接的服务文档，填错了会报 404 或者路径错误。我一开始就是漏了/v1，排查了半天。

api key 的管理。不要把 key 硬编码进会提交到 git 的文件里。omp 一般支持从环境变量读取，建议用环境变量：

export PI_API_KEY="your-key"

然后在配置里引用这个变量。这样配置文件可以安全地分享和备份。

模型名称要精确。模型名写错是最常见的"看起来配好了但就是不通"的原因。确认你填的名字和服务端支持的完全一致，大小写、连字符都不能差。

配好之后，跑一个最简单的测试：

pi "帮我看看当前目录下有哪些文件"

如果它能正常读取并回复，说明链路通了。

4. 把 pi 用顺手的实操技巧

4.1 日常高频用法与提示词写法

pi 的交互方式很直接，你给它一句话，它决定用哪几个工具。但"怎么问"对结果影响很大。我总结了几条：

明确范围。与其说"帮我优化一下代码"，不如说"帮我看看src/utils/date.js这个文件，把里面的日期格式化函数改成支持时区参数"。范围越具体，它读的文件越少，改得越准。

说清验证方式。如果你希望它改完跑测试，直接说"改完跑一下npm test确认没挂"。pi 不会自动假设你要验证，你得告诉它。

一次一件事。pi 的工具少，不适合一次塞五个需求。分开问，每步确认，反而更快。我试过一次性让它"改 A、修 B、再重构 C"，结果它顾此失彼，还不如分三次。

一个我常用的模板：

读一下 <文件路径>，我要 <具体目标>。 改完之后跑 <验证命令>，把结果告诉我。

简单、明确、可验证。

4.2 用 omp 提升效率的几个配置

omp 装好之后，有几个配置我强烈建议调一下：

快捷键绑定。把常用的"重新加载配置""清空会话""切换模型"绑到顺手的键上。我绑的是Ctrl+R重载、Ctrl+L清屏、Ctrl+M切模型，用起来很顺。

会话历史。omp 一般会保存会话历史，建议开启并设置合理的保留条数。这样你可以回溯之前让它做过什么，尤其是排查"它上次到底改了啥"的时候很有用。

自动格式化钩子。如果你写的是 JS/TS/Python 这类有成熟格式化工具的语言，配一个保存后自动格式化的钩子，能让 pi 改出来的代码风格和你项目一致，省得手动调。

提示模板。把你常用的几类任务（改 bug、写测试、解释代码）做成模板，用的时候直接调，不用每次重新组织语言。

4.3 和 Claude Code 混用的工作流

我现在的工作流是这样的：

• 探索和理解阶段：用 pi。快速读代码、问问题、定位问题，轻量高效。
• 复杂改动阶段：切 Claude Code。需要跨文件规划、需要它自主循环验证的时候，Claude Code 更稳。
• 收尾和提交：回到 pi。跑测试、生成提交信息、做最后的小修小补。

这个分工的核心逻辑是：让工具做它擅长的事。pi 擅长快速响应和精确操作，Claude Code 擅长复杂规划和长链路执行。硬要一个工具包打天下，体验反而会打折。

实操心得：两个工具可以共用同一套 API 配置，切换成本很低。你不需要"二选一"，把它们当成工具箱里的两把不同尺寸的螺丝刀就行。

5. 常见问题与排查实录

5.1 安装和配置阶段的典型报错

报错一：命令找不到（command not found）

装完pi或omp之后敲命令提示找不到。九成是全局 bin 目录不在 PATH 里。解决：

npm config get prefix

把输出的路径加上/bin加到 PATH。或者用npx pi临时跑一下确认包本身装好了。

报错二：权限错误（no write permission）

这类错误通常出现在全局安装或者自动更新的时候，提示没有写权限。原因是 npm 全局目录的权限不对。解决方式是改 npm 的全局目录到你自己的用户目录下：

npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH

然后重新装。这样就不需要 sudo，也不会再有权限问题。

报错三：API 请求 404 或 401

404 一般是 base url 路径不对，检查结尾的/v1。401 是 key 不对或者没读到，检查环境变量有没有正确 export，以及配置里引用的变量名对不对。

报错四：模型名无效

服务端返回"model not found"。核对模型名，注意有些服务对模型名大小写敏感。

5.2 使用过程中的行为异常

问题：pi 读文件读错了

有时候它会读一个你没提到的文件。原因通常是你的描述里有歧义，或者项目里有同名文件。解决：在提示里给完整路径，别只给文件名。

问题：改完代码没跑验证

pi 默认不会自动验证，除非你说。养成习惯，每次改动都带上验证命令。

问题：上下文越来越长，响应变慢

长会话会累积上下文。omp 一般有清空会话的命令，或者你可以开新会话。我习惯每完成一个独立任务就清一次，保持轻快。

问题：改出来的代码风格不一致

配自动格式化钩子，或者在提示里说明项目的代码规范。

5.3 一张速查表

避坑技巧：每次改配置之后，先用一个最简单的任务验证链路，别直接上复杂任务。这样出问题时你能确定是配置问题还是任务问题，排查范围小很多。

6. 我对这套组合的真实体会

用 pi 加 omp 这段时间，最大的感受是"轻"。不是功能上的轻，而是心理上的轻。Claude Code 给我的感觉是"我在操作一个强大的系统"，而 pi 给我的感觉是"我在用一个顺手的工具"。这两种体验没有高下之分，取决于你当下要干什么。

我踩过的坑主要集中在配置阶段：base url 的结尾、环境变量的引用、全局目录的权限，这三个问题我各花了不少时间。但一旦配通，后面就很少再动配置了。omp 的价值也在这里——它把那些"一次性但很烦"的配置工作打包好了，让你能更快进入"用"的状态。

如果你现在正在用 Claude Code 并且觉得够用，那没必要折腾。但如果你和我一样，日常有大量碎片化的代码任务，又希望工具响应快、行为可预测、配置可控，那 pi 加 omp 这套组合值得你花一个下午试试。装好之后，先拿几个小任务练手，摸清它的脾气，再决定要不要把它纳入你的日常工作流。

最后分享一个小技巧：把 pi 和 Claude Code 的配置放在同一个目录下管理，用注释标清楚各自的用途和关键参数。这样时间久了回头看，不会忘记当初为什么这么配。工具会换，但"把配置管理清楚"这个习惯，能让你在换任何工具的时候都少走弯路。