企业官网建设流程全解析

1. 这场“迁移潮”到底在迁移什么

最近半年，AI Coding 圈子里一个越来越明显的现象是：不少原本重度使用 Claude Code 的开发者，开始把日常主力工具换成 Pi。注意，这里说的不是“尝鲜装一下”，而是真正把每天写代码、跑 agent、调 harness 的工作流整体搬过去。这个动作背后，绝对不是简单的“新工具更好用”能解释的。

先把概念对齐一下，避免后面聊岔。Claude Code是 Anthropic 推出的终端侧 AI Coding 工具，核心形态是一个能读写本地文件、执行命令、跑测试、做多步任务的 agent。Pi则是另一套 agent 运行框架，它把“模型能力”和“执行编排”拆得更开，强调 harness（执行骨架）的可替换性。AI Coding指的是用 AI 参与真实工程代码的生成、修改、验证全流程，而不是只让它补个函数。agent在这里特指能自主规划、调用工具、观察结果并继续推进的执行体。harness则是承载 agent 的那层“骨架”，负责工具注册、上下文管理、循环控制、错误恢复。

所以标题里说的“放弃 Claude Code 转而用 Pi”，本质上是开发者对agent 执行层控制权的一次重新选择。Claude Code 把很多东西封装得很顺滑，开箱即用；Pi 则把 harness 这层暴露出来，让你能换模型、换工具、换循环策略。一个像精装房，一个像毛坯加可定制水电。住惯了精装房的人为什么愿意搬去毛坯？因为住久了发现，墙不能砸、线不能改，才是真正的痛点。

这篇文章适合三类人看：第一类是用 Claude Code 已经上手、但开始觉得“有些事它不让我干”的中级用户；第二类是正在选 agent 框架、想搞清楚 harness 到底值不值得自己搭的工程师；第三类是被各种热词绕晕、想知道 Pi 和 Claude Code 到底差在哪的新手。我会把选型逻辑、harness 原理、实操步骤、踩坑经验都摊开讲，尽量让你看完能直接判断自己该不该迁。

2. 为什么“封装得好”反而成了劝退理由

2.1 Claude Code 的顺滑是有代价的

Claude Code 刚出来的时候，最打动人的就是顺。装完、登录、进项目目录，敲一句话它就开始读文件、改代码、跑命令。对刚接触 AI Coding 的人来说，这种体验几乎没有学习成本。你不用管上下文怎么拼、工具怎么注册、循环怎么停，它全帮你处理了。

但用得越深，你越会碰到那层“看不见的墙”。比如你想让它接一个自建的内部工具，或者想把某一步的模型从默认模型换成另一个更便宜或更擅长代码的模型，你会发现可操作空间有限。它的设计哲学是“给你一条最优路径”，而不是“给你一套积木”。这在早期是优点，在深度使用阶段就变成约束。

我自己的体会是：当你只需要一个助手时，封装是福利；当你需要一个可编排的系统时，封装是天花板。很多人转向 Pi，不是因为 Claude Code 变差了，而是因为他们的需求从“帮我写代码”升级成了“帮我编排一条能反复跑的代码生产流水线”。

2.2 Pi 把 harness 摆到了台面上

Pi 最核心的差异，就是它不藏 harness。harness 这个词直译是“马具”，你可以理解成套在模型这匹“马”身上的那套挽具和缰绳。模型负责出力气，harness 负责决定往哪走、走多快、什么时候停、遇到坑怎么绕。

在 Pi 里，harness 通常包含这几块：

• 工具层：文件读写、命令执行、搜索、网络请求等能力怎么注册、怎么暴露给模型。
• 循环层：agent 执行是单轮还是多轮，什么时候判断任务完成，什么时候强制中断。
• 上下文层：历史对话、文件内容、工具返回结果怎么裁剪、怎么压缩、怎么注入。
• 模型层：哪一步用哪个模型，能不能混用，失败后怎么降级重试。

Claude Code 把这些大多内置了，你只能调参数；Pi 把这些做成可替换模块，你能改逻辑。这就是“harness anything”这个说法流行起来的原因——不是什么都用 harness，而是 harness 这层终于可以被你当成一等公民来对待。

2.3 迁移的真正驱动力是控制权

把迁移原因归成一句话：开发者想要对 agent 的执行过程有可观测、可干预、可复现的控制权。

可观测，是指每一步发生了什么、调了哪个工具、返回了什么、花了多少 token，都能看到。可干预，是指某一步跑歪了，我能中途改策略，而不是只能重开。可复现，是指同样的输入和 harness 配置，能稳定跑出接近的结果，方便团队协作和回归测试。

Claude Code 在可观测和可复现上做了不少工作，但它的干预点相对固定。Pi 则把干预点铺开，代价是你得自己承担配置复杂度。这笔账划不划算，取决于你的使用强度。偶尔写写脚本的人，Claude Code 依然更省心；每天跑几十个 agent 任务的人，Pi 的灵活性会很快回本。

3. 拆开 Pi 的 harness：它到底比 Claude Code 多给了什么

3.1 工具注册：从“内置清单”到“自己插拔”

Claude Code 的工具集是相对固定的，你能用的是它提供的那一套。这在大多数场景够用，但一旦你要接内部系统，就会卡住。比如你想让 agent 查公司内部的知识库、调一个自研的代码检查服务、或者把结果写进某个特定格式的文件，Claude Code 往往需要绕路。

Pi 的工具注册是开放的。你可以按它的接口写一个工具描述，声明参数和返回值，然后挂进 harness。模型在规划时就能“看到”这个工具并调用它。这个差别在真实项目里非常关键。

举个我实际遇到的场景：团队有一套自研的接口规范检查脚本，以前用 Claude Code 时，只能让 agent 改完代码后，我手动跑脚本再贴回结果。换成 Pi 之后，我把这个脚本包成一个工具，agent 改完代码会自己调用检查、自己读报错、自己再改一轮。整个闭环从“人肉中转”变成了“自动收敛”。

提示：自定义工具的描述一定要写清楚“什么时候该用”。模型不会读心，工具描述就是它的使用说明书。描述含糊，模型要么不用，要么乱用。

3.2 循环控制：从“它自己决定”到“你说了算”

agent 执行本质上是一个循环：观察 → 规划 → 行动 → 再观察。Claude Code 的循环策略是内置的，你大致能感觉到它在多轮推进，但很难精确控制每一轮的边界。

Pi 把循环控制暴露出来，你可以设定最大轮数、每轮的超时、失败重试次数、以及“什么条件下判定任务完成”。这听起来很工程化，但实际价值很大。比如跑批量重构时，你希望每个文件最多尝试三轮，超过就跳过并记录，避免一个文件卡死拖垮整批任务。这种策略在 Pi 里是配置项，在 Claude Code 里往往只能靠提示词去“求”它。

3.3 上下文管理：token 花在刀刃上

上下文管理是 agent 成本的大头。Claude Code 会自动做裁剪和压缩，省心但不可控。Pi 让你决定哪些内容进上下文、哪些丢弃、历史怎么摘要。

我做过一个对比：同一个中等规模的重构任务，Claude Code 跑下来 token 消耗稳定但偏高，因为它倾向于保留较多上下文以求稳；Pi 在调好裁剪策略后，token 消耗能降下来一截，代价是我得花时间调策略。对于高频使用的人来说，这个降本会累积成可观的数字。

3.4 模型混用：不同环节用不同“大脑”

这是 Pi 很吸引人的一点。一个 agent 任务里，规划阶段可能需要强推理模型，执行阶段可能只需要一个快而便宜的模型，代码审查阶段又可能需要擅长静态分析的模型。Claude Code 基本绑定自家模型体系，Pi 则允许你在 harness 里按环节指定模型。

这种混用的收益是双重的：成本和效果都能优化。规划用强模型保证方向对，执行用快模型保证吞吐，审查用专精模型保证质量。当然，配置复杂度也上去了，你得对每个环节的模型特性有基本判断。

4. 从 Claude Code 迁到 Pi 的实操路径

4.1 先别急着卸载，做一次能力盘点

迁移最忌讳一上来就全量切换。我的建议是先花半天做能力盘点，把你在 Claude Code 上高频使用的功能列出来，逐条判断 Pi 能不能覆盖、覆盖得好不好。

这张表不是标准答案，是给你一个盘点框架。盘完你会发现，真正需要迁移的往往只是那 20% 的复杂任务，剩下 80% 的轻任务留在 Claude Code 上反而更省事。双工具并存不是妥协，是理性。

4.2 搭一个最小可用的 Pi harness

不要一上来就追求完整功能，先跑通最小闭环。一个最小 harness 通常包含：一个模型调用、一个文件读取工具、一个命令执行工具、一个简单的循环。

大致步骤是这样的：

1. 准备运行环境：确认本地有合适的运行时和依赖管理工具，把 Pi 相关依赖装好。这一步不同平台差异较大，按官方文档走，别跳步。
2. 配置模型接入：填好模型服务的地址和凭证，先跑一个最简单的“你好”调用，确认链路通。
3. 注册基础工具：先只注册文件读取和命令执行两个工具，别贪多。
4. 写一个最小循环：设定最大轮数，比如 5 轮，让 agent 尝试完成一个“读取某文件并总结”的任务。
5. 观察日志：把每一步的工具调用和返回都打出来，确认你能看懂整个执行过程。

这个最小闭环跑通后，你才算真正摸到了 harness 的门。很多人卡在第一步就放弃，是因为想一步到位配全套，结果被复杂度劝退。

注意：最小闭环阶段不要接生产代码库。用一个测试目录，避免 agent 误操作真实文件。这个坑我见过太多次。

4.3 把 Claude Code 的工作流翻译成 Pi 配置

跑通最小闭环后，开始做工作流翻译。以“改一个 bug 并验证”为例，Claude Code 里你大概说一句“修复这个 bug 并跑测试”，它自己安排。在 Pi 里，你要把这句话拆成 harness 能执行的策略：

• 第一步：读取相关文件和测试文件。
• 第二步：定位问题，生成修改方案。
• 第三步：应用修改。
• 第四步：运行测试命令。
• 第五步：如果测试失败，回到第二步，最多重试三轮。
• 第六步：输出修改摘要和测试结果。

这个拆解过程本身就是价值。你会发现以前在 Claude Code 里“一句话搞定”的背后，其实有很多隐含决策。把这些决策显式化，你对 agent 行为的理解会上一个台阶。

4.4 参数计算：轮数和超时怎么定

轮数和超时不是拍脑袋定的，可以按任务复杂度估。一个粗略的经验公式是：

最大轮数 ≈ 任务涉及的文件数 × 1.5 + 基础轮数（3 到 5）

比如一个涉及 4 个文件的重构，最大轮数可以设成 4×1.5+4≈10 轮。设太少，任务没跑完就被截断；设太多，跑歪了会浪费大量 token。

超时则按单轮平均耗时估。如果单轮平均 30 秒，最大轮数 10 轮，那整体超时至少设 5 分钟以上，留出余量。这些数字不用一次到位，跑几次看日志再调，比一开始就追求精确更实际。

5. 迁移路上最容易踩的坑

5.1 工具描述写得太随意

这是新手最常犯的错。工具描述是模型判断“要不要用这个工具”的唯一依据。描述写成“执行命令”，模型不知道什么时候该用；写成“在需要运行测试、构建或检查代码时执行 shell 命令，参数为完整命令字符串”，模型就清楚多了。描述质量直接决定 agent 的规划质量。

5.2 上下文无限膨胀

Pi 给了你上下文控制权，但很多人一开始干脆不裁剪，结果几轮之后上下文爆掉，模型开始“失忆”或者响应变慢。正确做法是尽早引入摘要机制：把早期轮次的详细内容压缩成简短结论，只保留最近几轮的完整信息。

5.3 错误恢复没设计

agent 跑任务一定会遇到错误：命令失败、文件不存在、模型返回格式不对。Claude Code 内置了一些恢复逻辑，Pi 里你得自己设计。最基本的做法是：工具调用失败时，把错误信息作为观察结果喂回模型，让它决定重试还是换策略，同时设一个重试上限，避免死循环。

5.4 忽略可复现性

团队协作时，harness 配置必须能版本化。把工具定义、循环策略、模型配置都放进版本控制，别人拉下来就能跑出接近的结果。我见过团队里每个人 Pi 配置都不一样，结果同一个任务跑出不同结果，排查起来非常痛苦。

5.5 常见问题速查表

这张表建议贴在手边，出问题先对照排查，能省下大量瞎试的时间。

6. 到底该不该迁：一份决策清单

聊了这么多，最后落到一个实际问题：你到底该不该从 Claude Code 迁到 Pi？我给一个决策清单，你对着打勾。

• 你是否每天有大量重复性的 agent 任务需要跑？是，倾向迁。
• 你是否需要接自研工具或内部系统？是，倾向迁。
• 你是否对 token 成本敏感、想优化模型使用？是，倾向迁。
• 你是否需要精确控制 agent 的执行循环？是，倾向迁。
• 你是否只是偶尔写写脚本、改改代码？是，留在 Claude Code。
• 你是否没有精力维护 harness 配置？是，留在 Claude Code。
• 你是否需要团队统一复现？是，迁之前先把配置管理做好。

我的个人经验是：不要非此即彼。我现在的工作流是 Claude Code 处理轻量、探索性的任务，Pi 处理复杂、需要编排和复现的任务。两者共用一套代码库，各司其职。迁移不是搬家，是扩编。

如果你决定迁，第一步永远是搭最小闭环，而不是照搬别人的完整配置。别人的 harness 是别人的工程约束长出来的，直接拿来往往水土不服。先跑通，再逐步加工具、加策略、加模型混用，让 harness 跟着你的真实需求长出来，这才是 Pi 这类框架真正的用法。