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 能不能覆盖、覆盖得好不好。能力项Claude Code 表现Pi 表现迁移建议开箱即用极顺需配置保留 Claude Code 做轻任务自定义工具受限开放优先迁移循环策略控制内置可配复杂任务迁移模型混用受限支持成本敏感任务迁移上下文裁剪自动手动需调优后迁移团队协作复现较好依赖配置管理配好 harness 后迁移这张表不是标准答案是给你一个盘点框架。盘完你会发现真正需要迁移的往往只是那 20% 的复杂任务剩下 80% 的轻任务留在 Claude Code 上反而更省事。双工具并存不是妥协是理性。4.2 搭一个最小可用的 Pi harness不要一上来就追求完整功能先跑通最小闭环。一个最小 harness 通常包含一个模型调用、一个文件读取工具、一个命令执行工具、一个简单的循环。大致步骤是这样的准备运行环境确认本地有合适的运行时和依赖管理工具把 Pi 相关依赖装好。这一步不同平台差异较大按官方文档走别跳步。配置模型接入填好模型服务的地址和凭证先跑一个最简单的“你好”调用确认链路通。注册基础工具先只注册文件读取和命令执行两个工具别贪多。写一个最小循环设定最大轮数比如 5 轮让 agent 尝试完成一个“读取某文件并总结”的任务。观察日志把每一步的工具调用和返回都打出来确认你能看懂整个执行过程。这个最小闭环跑通后你才算真正摸到了 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.54≈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 常见问题速查表现象可能原因排查方向agent 不调用自定义工具工具描述含糊重写描述明确使用场景任务中途卡死循环无上限或超时过长检查最大轮数和超时配置响应变慢或失忆上下文膨胀引入摘要和裁剪策略结果不稳定配置未版本化统一 harness 配置并入库模型返回格式错误输出约束不明确在提示或工具层加格式校验成本异常高模型混用策略不当检查各环节模型选择这张表建议贴在手边出问题先对照排查能省下大量瞎试的时间。6. 到底该不该迁一份决策清单聊了这么多最后落到一个实际问题你到底该不该从 Claude Code 迁到 Pi我给一个决策清单你对着打勾。你是否每天有大量重复性的 agent 任务需要跑是倾向迁。你是否需要接自研工具或内部系统是倾向迁。你是否对 token 成本敏感、想优化模型使用是倾向迁。你是否需要精确控制 agent 的执行循环是倾向迁。你是否只是偶尔写写脚本、改改代码是留在 Claude Code。你是否没有精力维护 harness 配置是留在 Claude Code。你是否需要团队统一复现是迁之前先把配置管理做好。我的个人经验是不要非此即彼。我现在的工作流是 Claude Code 处理轻量、探索性的任务Pi 处理复杂、需要编排和复现的任务。两者共用一套代码库各司其职。迁移不是搬家是扩编。如果你决定迁第一步永远是搭最小闭环而不是照搬别人的完整配置。别人的 harness 是别人的工程约束长出来的直接拿来往往水土不服。先跑通再逐步加工具、加策略、加模型混用让 harness 跟着你的真实需求长出来这才是 Pi 这类框架真正的用法。