企业官网建设流程全解析

1. 当"全能"变成负担：我为什么从 Claude Code 切到 pi

1.1 Claude Code 的强与重

Claude Code 刚推出的时候我就开始用了，第一印象确实是"无所不能"——能直接改代码、能跑终端命令、能查文档、能关联各种外部工具，甚至还能在对话里维护长期记忆。那段时间我几乎把日常开发全塞给了它，觉得自己终于找到了理想的 AI 结对编程助手。但用了一两个月之后，一个很反直觉的感受慢慢冒了出来：它太全能了，全能到让我开始有点累。

这个"累"不是说它不好用，而是功能越多，决策链路越长。一次普通的 bug 修复，它可能先判断要不要联网查资料、要不要调 subagent、要不要翻历史记忆，然后才开始读代码。如果中间某个环节判断错了，整个任务的路径就偏了。审查一个"绕了很多弯"的 agent 输出，比我自己动手改还要费神。另一个问题是学习成本：新的配置项、新的权限模型、新的插件生态，每隔一段时间就要跟上新玩法。有时候我只是想让它把某个函数重构一下，结果它先问我好几轮"是否允许执行某个工具"。功能越丰富，行为的不确定性反而越高。

后来我做了个统计，把一个月里真正让 agent 干的活拉出来看，翻来覆去其实就是四件事：读文件、改文件、找文件、跑命令。写周报、查资料、解释概念这些需求虽然有，但不是编码代理该干的活，那是通用助手的领域。想通这一点之后，我开始寻找更"克制"的方案，然后就遇到了 pi。

1.2 pi 的减法哲学

pi 这个项目打动我的地方，在于它主动做了减法。它给自己的定位非常明确：我只是一个 coding agent，不负责聊天、不负责上网搜资料、不负责写文档，只负责把代码相关的事情做干净。它对外暴露的工具只有四个：read、edit、glob、bash。没有 subagent 体系，没有复杂的记忆系统，没有几十个可插拔的工具接口。

你可能觉得这很简陋，但我实际用下来发现，这才是一个编码代理该有的样子。你让它修一个 bug，它的思路非常直：先用 read 读相关文件，再用 glob 找可能牵连到的其他文件，然后用 edit 做精准修改，最后用 bash 跑一遍测试验证。每一步都可以预测，每一步都可以审查。它不会自作主张去"思考"要不要额外做点什么，因为它的工具箱里压根没有多余的东西。

这一点和 Claude Code 形成了鲜明的对比。Claude Code 的默认行为是"尽量帮你把事情都做了"，而 pi 的行为是"只做你让它在代码上做的事情"。这两种设计没有绝对的高下之分，但如果你对"可审计性"有要求，pi 这套极简设计会让你安心很多。

还有一点必须提：pi 是模型无关的。你想接什么模型都行，官方 API、第三方 API、本地模型都没问题。Claude Code 深度绑定 Anhtropic 生态，换模型要么走配置折腾，要么受订阅体系限制。而 pi 在架构上就是一套工具执行器，模型只是一块随时可以换的大脑。对于想横向对比 DeepSeek、Qwen、GLM 或本地模型的开发者来说，这个自由度非常关键。

1.3 谁适合切到 pi，谁不适合

先说适合的人。第一类是团队协作场景里对审查要求高的开发者。pi 每一步都走得很慢、很明确，输出里能清楚看到它读了哪个文件、改了什么字符串、跑了什么命令，代码评审时可以顺着它的轨迹复查。第二类是同时使用多个模型的开发者，因为 pi 的模型切换成本极低，改一个配置就能换大脑，特别适合做模型效果评测。第三类是机器性能一般、不想让 IDE 吃满内存的终端党，pi 本身只是一个极轻量的 CLI 进程，几乎不占什么资源。

不适合的人也很明显。如果你想要的是一个能陪你头脑风暴、能上网查资料、能生成大段文档的"全能助理"，那 pi 会把你逼疯。它不会在你卡壳的时候给你灵感，不会帮你润色 commit message，更不会主动给你科普某个框架的用法。这种需求请老老实实用 Claude Code 或完整的桌面版助手。

另外提醒一句：不要指望一场大版本升级就能让 pi 变得"全能"。它的价值恰恰在于拒绝全能。你在安装前最好先问问自己，你到底是要一个什么都能聊的工具，还是要一个能把代码活干利索的伙伴。

2. 四个工具撑起编码闭环：read、edit、glob、bash 逐一拆解

2.1 read：先建立准确上下文

我第一次用 pi 的时候，第一个感觉是"它怎么这么啰嗦"。让它改个函数，它先说"我先读一下这个文件"，然后果然只做了读取动作，什么修改都还没发生。但用久了才发现，这个"啰嗦"其实是一种纪律。

为什么把 read 放在四个工具的第一位？因为绝大多数 agent 翻车，不是改得不好，而是没看清楚就动手。LLM 对代码的记忆是概率性的，它可能记得你项目里有个 order 模块，但记不清订单状态的字段到底是status还是state，记不清某个函数是同步还是异步。这种情况下直接 edit，等于拿错误的地图去赶路。

pi 的 read 支持按行号范围读取，也支持读文件信息，用起来可以很省 token。我的习惯是：超过 500 行的大文件，先读开头 50 行了解模块结构，再用行号定位到目标函数附近读 100 行，最后看一眼文件尾部看看有没有导出入口。分段读比一次读全文件更能让模型保持注意力。

另外，read 的结果在 pi 的会话里是可见的。也就是说，你可以亲眼看到 agent 读了什么、没读什么。如果它漏读了一个关键文件，你直接说"你漏了 src/utils/date.ts，去读一下"，它就会老老实实去读。这种透明度是"黑盒 agent"给不了的。

2.2 edit：精准替换，杜绝整文件覆盖

edit 是 pi 的核心工具，设计思路也非常"反 LLM 本能"。很多 LLM 改代码时习惯整文件重写，结果经常把原作者的格式、注释风格、无关函数一起改得面目全非。pi 的 edit 只支持一种模式：字符串替换。你告诉它把文件中某个精确的旧文本替换成新文本，匹配不到就直接报错，绝不静默乱改。

这个设计极其关键。它倒逼着 agent 必须先 read 拿到准确的原始文本，然后再动手替换。从机制上就杜绝了"我猜这里大概是这样的，直接改了吧"这类事故。而且因为替换单位小，你对每一步修改的审阅成本也低。它慢慢改，你慢慢看，整个交互节奏非常舒服。

用的时候有一个技巧：让 agent 分多次 edit，而不是一次提交很多改动。每次改动覆盖一两个点，然后立刻用 bash 跑测试或 lint 验证。宁可多对话几轮，也要保证每一步都建立在已验证的基础上。我见过太多人让 agent 一次改完五个文件，结果出错之后根本不知道是哪一步引入的问题。分步 edit + 即时验证，排查成本会低一个量级。

2.3 glob：用文件搜索替代"猜结构"

glob 这个工具的名字看起来很简单，但它解决的是 LLM 的一个核心毛病：凭空想象项目结构。你问一个 agent "订单相关的代码在哪里"，它可能会自信地告诉你一个并不存在的路径。有了 glob，它就可以先glob **/order*.py，把项目里所有订单相关的文件捞出来，然后挨个 read，真正搞清楚状况。

和直接读目录树相比，glob 的优势在于精准和便宜。大项目的目录树动辄上万条路径，全部塞进上下文里既贵又容易干扰模型的判断。glob 的定位是"给 agent 一个精准的鱼竿，而不是把整个池塘给它"。它只返回匹配到的文件名列表，模型自己决定先读哪个，决策成本大幅降低。

实际使用中，我经常把 glob 和 grep 配合着用。glob 管文件名的粗粒度定位，grep 管文件内容的细粒度定位。很多 agent 工具恨不得把这两种能力分开做成十个工具，pi 只保留两个，初衷都一样：少让模型做选择题。

2.4 bash：执行权与边界感并存

四个工具里，bash 是权限最大的一个，也是唯一一个能真正"动手"的工具。pi 在这件事上做得比较聪明：它默认要求你配置允许执行的命令前缀模式，只有匹配白名单的命令才会被自动执行，其余一律停下来问你。

比如你可以这样配：

{ "allowedCommands": [ "npm run", "npm test", "git status", "git diff", "python test" ] }

这样 agent 可以自己跑测试、看 git 状态，但要想执行rm -rf /或者curl到某个外网地址，就得先征求你的同意。我的建议是使用白名单思维而不是黑名单思维：只放行你真正高频使用的操作，其他的一律手动确认。宁可多几次交互，也别让 agent 在一个你没想到的角落执行了危险操作。

有人可能会问，bash 都给了，为什么不给 agent 完整的终端自由？答案很简单：编码 agent 的价值在于帮你改代码，而不是替代你的判断。执行是手段，验证是目的。当你把"执行"也变成一种需要对齐和确认的动作时，你反而会对每一步的后果更清楚。

2.5 为什么是"4 个"而不是更多

这句话我在不同项目的文档里都看到过，但真正理解还是靠实践：对编程 agent 来说，限制决策空间就是提升可靠性。

每多一个工具，模型在一次任务中就要多考虑一个分支：这个情况要不要用网页搜索？要不要用记忆文件？要不要起一个子代理？这些分支里每一个都可能出错。工具越多，决策树越深，行为越难预测。而编码这件事，恰恰是"行为可预测"比"功能丰富"更重要的场景。

read 建立上下文，edit 产生改动，glob 发现关联，bash 验证结果，四件事正好构成一个完整的编码闭环，不多不少。这个设计不是拍脑袋砍出来的，而是回归了程序员日常工作的本质。我甚至觉得，以后如果 pi 要加新工具，也应该先问一个问题："这个工具能不能被现有四个工具组合出来？"如果能，就不该加。

3. 从零跑通 pi：安装、模型接入与编辑器联动

3.1 三平台安装路线与第一道坑

pi 的安装非常轻，本体就是一个命令行工具。Windows 上我踩过不少坑，这里给你一条相对顺畅的路线。

Windows 用户最容易遇到的问题，就是热搜里那个"由于与64位版本的 Windows 不兼容"，十有八九是 Node.js 版本或架构不对。我的建议是：先把系统的 Node.js 彻底卸载，去官网下载最新版 64 位安装包重装，然后用管理员身份打开 PowerShell 或 CMD，再执行安装命令。

node -v # 确认版本 >= 18 npm install -g pi-coding-agent pi --version # 验证安装成功

macOS 和 Ubuntu 上就简单得多，基本上就是一条 npm 全局安装命令的事。如果你用的是一个比较干净的 Ubuntu 环境，可能还需要先装一下 build-essential 之类的编译工具链，但大多数情况下 npm 装完就能直接跑。网络慢的话，把 npm registry 切到国内镜像再装，体验会好很多。

一个容易被忽略的问题：pi 本身不依赖任何官方订阅账号，所以不存在"注册才能用"的概念。你真正需要准备的是模型侧的 API Key。把 Key 配好，pi 才能正常工作。

3.2 模型接入：API Key、配置文件与多模型切换

pi 支持环境变量和配置文件两种方式注入模型信息。我强烈推荐用配置文件，因为每次开终端都要 export 一堆变量实在太烦了。

拿接入 DeepSeek 为例，配置文件大概长这样：

{ "model": "deepseek-chat", "apiBase": "https://api.deepseek.com/v1", "apiKey": "sk-xxxxxx" }

如果你想接 Qwen、GLM、Moonshot 或者其他任何走 OpenAI 兼容协议的服务商，改四个字段就行。这个自由度是 pi 最让我舒服的地方。以前用 Claude Code 时，要接第三方模型总得绕各种配置，而 pi 从一开始就把"模型无关"写进了基因里。

配置好之后，建议用一个简单任务验证连通性，比如让它给某个函数加个注释，或者让它解释一段代码。如果它答非所问，多半是 base URL 或 model 名写错了。我遇到最多的情况是把/v1路径漏了，导致接口 404，排查时优先检查这处。

3.3 在 VSCode 里用 pi：换个姿势

pi 天生是终端工具，但这不代表它和编辑器无缘。我日常的开发方式是：在 VSCode 的终端里启动 pi，让它以当前项目目录作为工作区上下文。这样它 glob、read 的都是项目真实文件。

想要更顺手，可以在 VSCode 的tasks.json里配一个自定义任务，一键唤起新终端并自动进入 pi：

{ "label": "Start pi", "type": "shell", "command": "pi", "presentation": { "reveal": "always", "panel": "dedicated", "group": "ai" } }

这里还有一个很多人会忽略的细节：启动时的工作目录决定了 pi 的上下文范围。如果你在一个空目录里启动 pi，它就会把空目录当作项目根目录，导致 glob 什么都找不到。不管用什么终端，一定要先在项目根目录cd进去，再启动。

3.4 用 cc-switch 管理多模型 Profile

如果你同时测 DeepSeek、Qwen、GLM 多个模型，手动改配置文件真的很痛苦。cc-switch 是社区里很流行的第三方模型切换器，虽然本来是为 Claude Code 设计的，但同样的思路完全可以用到 pi 上。

我现在的做法是在 pi 的配置目录里维护多个 profile，每个 profile 对应一个模型服务商的配置。切换的时候只需要一条命令，几秒钟就能换一个模型来跑同一段 Prompt。这对做模型效果横向对比特别有帮助——同一个 bug 修复任务，分别让 DeepSeek 和 Qwen 跑一遍，看谁的改动更干净，几分钟就有结论。

这个机制另外一个潜在价值是团队协作。新人加入项目，不需要自己摸索半天 API 配置，直接导入团队的 profile 就能开跑。配置本身就是一种可复用的工程资产。

4. 全家桶 oh-my-pi 到底补了什么

4.1 从 oh-my-zsh 说起：全家桶的设计思路

用过 zsh 的人一定懂 oh-my-zsh 的定位：zsh 本身很强大但裸奔体验不佳，oh-my-zsh 把主题、插件、别名这些周边体验一次性配好。oh-my-pi 对 pi 做的事情一模一样——pi 核心保持克制，oh-my-pi 在外部把常用技能、模型接入、界面体验全部补齐。

这个拆分的意义在于：核心与周边解耦。pi 本体永远保持四工具的简洁设计，不会因为社区需要某个功能就往核心塞。而 oh-my-pi 作为一个独立配置层，可以快速迭代，今天加一个 Skill 包，明天换一个模型配置模板，都不会影响 pi 本身的稳定性。

安装 oh-my-pi 的方式很简单，社区仓库里拉下来之后跑一个安装脚本，它会在你的用户目录下创建一套默认配置。装好之后你会发现，它预设了一些常用的系统提示词、几条常用命令别名、以及一套比较合理的 bash 白名单初始值。对于不想从零开始调配置的人，这一步能省不少时间。

4.2 Skills 机制：把经验沉淀成可复用资产

oh-my-pi 里我最看重的，是它的 Skills 机制。所谓 Skill，就是把一种完整的工作流写成结构化提示词，包括触发条件、执行步骤、输入输出示例，然后放进指定目录。pi 在运行时会读取这些 Skill，遇到匹配场景就自动加载。

举个例子。我们在团队里总结了一套代码审查流程：先读 diff、再定位变更影响面、然后按 checklist 逐项检查潜在问题、最后输出风险等级。这套流程原来只在某个人的脑子里，现在写成 Skill 之后，任何用 oh-my-pi 的同事都能直接复用。

Skill 的价值在团队场景里会被放大很多倍。它本质上是把个人经验转化为团队资产。新人上手项目时，不用到处问"你们一般怎么排查这个模块的问题"，装上 oh-my-pi、Skills 一加载，agent 的行为风格立刻对齐团队习惯。

这里有个非常重要的实操建议：Skill 的编写质量直接决定效果。写 Skill 时不要写那种空泛的"检查代码质量"的废话，要写具体的、可执行的步骤，最好附上正反例。我见过写得好的 Skill 是"针对支付回调幂等性问题，先检查消息去重，再检查状态机流转，最后检查超时补偿"，这种粒度才有实用价值。

4.3 本地模型接入：LM Studio 与隐私场景

oh-my-pi 的另一个贴心之处，是把本地模型接入的配置模板直接做好了。如果你有隐私要求，或者想离线开发，可以下载 LM Studio，在里面加载一个量化模型，然后启动本地服务。

配置写法同样走 OpenAI 兼容协议：

{ "model": "local-model", "apiBase": "http://localhost:1234/v1", "apiKey": "lm-studio" }

注意这里有一个常见的坑：LM Studio 的服务端口有时候会被系统防火墙拦截，导致 pi 连不上。第一次配置时，先在浏览器里访问一下http://localhost:1234/v1/models，能返回模型列表说明服务正常，再去 pi 里测试。

我对本地模型的定位是：处理那些"不需要很强推理能力"的编码任务。比如给代码加统一格式、批量生成测试桩、整理 import 顺序，这些活本地小模型干得很稳。但复杂重构、跨模块影响分析这类任务，我依然建议用云端的强模型。别指望一行命令的本地部署能媲美大厂在线推理，工具选型要讲性价比。

4.4 桌面版与网页版：降低团队使用门槛

热词里常常刷到 pi desktop 和 pi web，这俩其实是 oh-my-pi 生态里的外围组件。桌面版给 pi 套了一个图形外壳，会话历史、配置修改、Skill 管理都变成了可视化界面。对于不习惯纯终端操作的人来说，这个门槛降低是很关键的。

网页版则偏向远程和协作场景。你可以在网页端管理 Skills、发起会话甚至分享会话记录。团队里的非工程师成员（比如测试、产品）也能在网页版里通过预设的 Skill 来调用 pi 的能力，不需要自己懂命令行。

我个人的偏好永远是终端，但不得不承认，如果想让整个团队用上同一套 AI 编码工作流，桌面版和网页版几乎是必须的。它们没有改变 pi 的核心行为，只是把"怎么和 pi 交互"这层体验做得更友好。一个工具链，核心极简、周边丰满，这可能反而是最可持续的形态。

5. 实测对比与踩坑记录：和 Claude Code 的真实差异

5.1 同一任务，两种完全不同的处理路径

为了让你更直观地理解 pi 和 Claude Code 的差异，我拿一个真实任务做过对比：给订单模块加一个超时自动关闭逻辑。

Claude Code 的处理风格是"并行推进、一次搞定"。它自己梳理了一遍订单状态相关的十几个文件，直接改服务层逻辑、补数据库迁移、顺手更新了前端提示文案。效率确实高，但问题也来了：因为改动面太大，我 review 它提交的 diff 花了将近半小时，还要逐项确认它有没有改到不该碰的地方。

pi 的处理路径则是"串行确认、逐步推进"。它先 read 订单模型，再 glob 找出所有状态判断的位置，改完服务层之后停下来问我："接下来是否要继续处理超时任务的定时调度？"每一步都可见、都可控，虽然整体花的时间比 Claude Code 长一些，但我的大脑完全跟得上它的节奏，review 压力小很多。

这个差异的本质是信任模型的不同。Claude Code 把你当成一个愿意放权的人，它负责快速完成；pi 把你当成一个需要全程掌握的审查者，它负责透明推进。没有哪个绝对更好，完全取决于你的使用场景和个人偏好。

5.2 高频报错排查速查表

下面这几条是我在实际安装使用中踩过、以及身边朋友高频遇到过的报错，整理成一张速查表：

还有一个容易被忽略的坑：如果你在团队环境里使用，代理或网络策略可能会影响终端工具的请求。这类问题往往不是 pi 本身配置错了，而是系统层网络异常。排查顺序我一般遵循：先确认 API Key 有效，再确认网络连通，最后才怀疑配置格式。

5.3 不要神化任何工具

最后说点不那么技术的话。不管是 Claude Code 还是 pi，本质上都只是一个"能听懂话的执行器"。你给它清晰的上下文、明确的边界、合理的验证方式，它就能帮你干漂亮活；你什么都不交代就甩一个大任务过去，再强的 agent 也容易翻车。

我现在的工作流是：pi 加 oh-my-pi 作为日常开发主力，处理大多数模块级改动和增量修复；Claude Code 仍然保留，用在需要全局理解大项目架构、做批量重构、生成大量跨文件代码的场景。两个工具我都装，不互相排斥。

切换工具的代价其实很低，也就是重新熟悉几条命令、几个配置项。真正值钱的，是你慢慢形成的那套"如何把任务拆解给 agent 做"的思维方式——先建上下文、再定方案、分步实施、及时验证。这套方式是模型无关的。今天套在 pi 上，明天套在任何一个新 agent 上，都同样成立。