★ FEATURED ARTICLE 最近我在几个开发者社群里连续看到同一个话题越来越多人放弃 Claude Code转身去折腾一个叫 Pi 的东西。起初我以为 Pi 只是某个小圈子里的玩具结果热度越来越高连 GitHub 上的 pi agent、pi harness、pi web 这些关键词都开始频繁出现在热搜里。作为一个从 Claude Code 早期版本就开始用、最近又把主要工作流迁到 Pi 上的人我打算把这段时间的观察和实操经验完整写出来。这篇文章要解决的问题很具体Claude Code 到底哪些方面让人想卸载Pi 靠什么把人吸引走如果你也想从 Claude Code 切到 Pi安装、配置、上手、排坑要怎么走我会尽量用大白话把每个环节讲透不绕弯子。1. Claude Code 和 Pi其实是两种完全不同的思路1.1 Claude Code终端里的智能管家Claude Code 是 Anthropic 推出的终端 AI 编程代理安装之后你在项目目录里敲一句claude它就能把一个代码仓库“接管”过去读文件、搜代码、改 bug、跑测试、提 commit甚至帮你把 PR 标题都想好。这套体验做得很顺尤其是在上下文理解上Claude 的模型确实能记住一个大型工程的来龙去脉。你只需要在交互框里描述问题它会自己规划一连串工具调用像极了一个坐在旁边看你屏幕的老工程师。但问题也恰恰出在“管家”这两个字上。管家替你做了所有事可你很难插手它的办事逻辑。它的规划策略、工具选择、上下文压缩规则都是黑盒。你付了钱享受了效率但一不满意想调整就会发现自己几乎没有控制权。1.2 Pi可拼接、可编排的代理工具箱Pi 和 Claude Code 走的是完全相反的路。它不是想把你锁进某个模型生态里而是先给你一套骨架代理的核心循环、工具调用的接口、与模型对话的抽象层都做成模块。你爱接什么模型就接什么模型OpenAI、Anthropic、本地 Ollama、DeepSeek只要有一个 API往配置里一填就能跑。最让我觉得 Pi 有价值的是它的 harness 概念。这个词直译过来是“马具”搁在编程代理里我理解成一套“工作流编排框架”。你不再依赖模型自发地决定下一步干什么而是可以在 harness 配置里写明遇到报错先搜日志、找到相关文件再读取、读完文件再改代码、改完代码立刻跑测试。每一步用什么工具、按什么顺序、失败后怎么办全部可以由你定义。也就是说Claude Code 是“模型决定流程”Pi 是“你决定流程模型填内容”。这一丁点差别放在真实工程场景里体验差距非常大。1.3 一张表看懂核心差异对比维度Claude CodePi以常见开源 agent 为例模型绑定仅 Claude 系列模型模型无关支持 OpenAI、Anthropic、DeepSeek、Ollama 本地模型工作流控制黑盒内部规划不可见harness 显式编排工具调用顺序可控成本订阅 API 双重开销重度使用压力大开源免费模型费用自选可接廉价或本地模型扩展方式skills / AGENTS.md受官方约束工具函数、插件、自定义 harness自由度更高上下文管理超长上下文1M 版本模型自动处理依赖工具按需读取需要合理切分任务运行资源Node CLI多会话内存占用偏高CLI 轻量适合低配机器看这张表你就明白这次迁移潮的根本原因不是 Claude Code 变差了而是很多人的真实需求正在从“省心”转向“可控 低成本”。2. 大家放弃 Claude Code主要是这四个原因2.1 成本高到个人开发者心疼先说最直接的痛点钱。Claude Code 不像普通命令行工具装完只是拿到一把钥匙真正的开销在模型调用上。个人想用比较强的 Claude 模型往往要订阅 Pro 甚至 Max 档团队场景还得买 Team 席位即便订阅了长会话、大仓库、高频交互的场景下API 费用的累积速度远超想象。我身边一个做外包的朋友算过一笔账用 Claude Code 跑一整个中型项目一个月光是模型花费就能吃掉一单外包利润的一小半。他后来换成 Pi 接 DeepSeek同一类任务的开销直接降了一个数量级效果虽然做不到完全一致但收了客户的钱之后利润率好看太多。这里不是劝所有人都去做极限省钱而是提醒你认真评估AI 编程代理省下的时间是否真的抵得过长期订阅和 Token 费用的双重大山。对很多个人开发者、自由职业者、小工作室来说开源工具 平价模型这条路性价比明显更优。2.2 模型被锁死选择权消失Claude Code 的好用很大程度建立在 Claude 模型的能力上。但副作用是你被困在了这一个模型里。今天 DeepSeek 在某些代码任务上表现惊艳明天本地模型又可能因为私密项目需求成为刚需可这些模型和 Claude Code 的正经集成路径绕来绕去总显得别扭。网上其实有不少人在研究“Claude Code 接入 DeepSeek”这类玩法但 Claude Code 官方并不原生支持非 Claude 模型。你折腾代理、改环境变量勉强跑通之后还会遇到工具调用格式不对、参数解析失败之类的问题。说到底它的设计出发点就不是让你随意换模型的。Pi 这类 agent 框架天然就是模型无关的配置里改一行模型名就能切换甚至可以在同一个任务链里让不同的模型各管一段。选择权一旦拿回自己手里再回头看那种被锁死的感觉真的会谢绝回头。2.3 工作流是黑盒想改改不动Claude Code 的自动化程度高这在简单任务上是优点在复杂流程上却让人心累。比如我想让它“先跑测试测试挂了再根据失败信息找修复点”它却可能一上来就扫整个项目我想让它“改代码前先看看相关历史提交记录”它可能跳过这一步直接开写。后来官方也意识到这个问题陆续加入了 skills、自定义指令等功能但玩过一圈就会发现这些扩展还是在模型自带的规划逻辑上打补丁。你给的是“建议”模型接不接受、什么时候接受得看它的心情。Pi 的思路就不一样。它把工具调用的骨架直接露给你你在 harness 配置里写好了流程代理就按流程执行。这大大减少了你和模型“商量着办事”的随机性。工程团队尤其喜欢这种方式因为那个流程本身就是团队经验的沉淀可以随项目迭代。2.4 资源占用和启动速度的体感差异Claude Code 是 Node 生态的 CLI装起来确实简单但跑起来并不算轻盈。我自己的开发机上一旦同时开着多个 Claude Code 会话风扇声音就很明显偶尔还会卡顿。这倒不是说什么惊天动地的性能差距而是日常体感真的很影响心情。Pi 类的轻量 agent 就友好很多。我换了之后最直观的感受是启动速度变快了内存占用下降了遇到问题时排查链路也更清晰。那些只用轻量笔记本写代码、或者喜欢在服务器上开代理任务的人对这种差异尤其敏感。3. 迁移到 Pi 的完整实操记录3.1 安装与初始化配置先说安装。Pi 不像 Claude Code 那样有统一的官方渠道你在 GitHub 上搜 pi agent 会看到好几个相关项目各自侧重点不同。我的建议是认准一个活跃度高、文档完善的仓库然后按 README 里的说明来装。常见的安装方式有两种一种是用包管理器比如pip install pi-agent或者npm install -g pi另一种是直接 clone 仓库后从源码构建。我走的组合是 clone 包管理器局部安装这样后续改源码做自定义工具比较方便。装完第一件事是初始化配置。大多数类似架构的 agent 会支持一个配置文件比如config.toml或.env在里面指定模型 provider、API Key、默认工作目录、日志级别等。以我最常用的配置为例# 切换到项目目录 cd ~/my-project # 初始化默认配置 pi init # 编辑 .env 填入模型 API Key cat .env.env大概长这样MODEL_PROVIDERdeepseek MODEL_NAMEdeepseek-chat API_KEYsk-xxxx这里的 Model Provider 就体现了 Pi 的核心优势——你换成openai、anthropic或者ollama命令都不用改pi 就能跑另一套模型。我一开始为了稳妥先用 DeepSeek 的 API 跑通后来又试了本地 Ollama切换过程不超过两分钟。3.2 把 Claude Code 的 skills 迁移成 Pi 的工具函数如果你之前是 Claude Code 的重度用户手上多半积累了一些自定义 skills比如“总结本次改动”“生成规范 commit message”“按团队模板创建 MR”。这些技能本质上是“提示词模板 预设工具调用”迁移到 Pi 时逻辑可以拆成一个个工具函数。我习惯在 Pi 的配置目录下建一个tools文件夹每个文件定义一个函数式工具标明输入参数和行为描述。比如把“生成 commit message”做成一个工具def commit_message_tool(diff_text: str) - str: 根据 diff 生成符合团队规范的 commit message。 instruction ( 你是一名资深代码审查者。请阅读以下 diff 生成一句符合 Conventional Commits 规范的提交信息 只输出 commit message不要解释。\n fdiff:\n{diff_text} ) return instruction工具定义好后在 harness 配置里挂载即可。这个迁移过程并不复杂难的是思维转变Claude Code 里你依赖模型自己调用 skills在 Pi 里你需要主动把“何时调用哪个工具”写清楚。一旦把这步做扎实其实得到的东西比原来还多一些因为团队里其他人也能复用同一套工具链。3.3 用 harness 编排一个 bug 修复工作流如果你觉得很抽象我们直接看一个例子。假设我想让 Pi 在收到一个报错信息时自动进入一套固定的排查修复流程搜索报错关键字段锁定相关文件读取文件内容尝试修复最后运行测试验证。我在 harness 配置里可以这样写name: bugfix-workflow description: 根据报错信息定位并修复问题 model: deepseek-chat tools: - search_logs - read_file - edit_file - run_tests steps: - tool: search_logs params: keyword: {error_message} next_on_success: read_file - tool: read_file params: file: {matched_file} next_on_success: edit_file - tool: edit_file params: instruction: 修复定位到的问题保留原有编码风格 next_on_success: run_tests - tool: run_tests params: command: pytest这个示例不是官方标准语法而是我自己根据项目习惯整理的一种常见写法。重点是它背后的思路你不是把一把需求扔给代理而是把“排查——定位——修复——验证”这条 SOP 拆成了可视化步骤。每个步骤调用什么工具、参数从哪来、成功之后走向哪里全部是有序的。相比 Claude Code 那种“你给我贴一段报错我自由发挥”的交互这套方式在执行稳定性上明显更可靠。特别是当你的项目足够大、坑足够多的时候确定性就是生产力。3.4 日常使用习惯的调整换到 Pi 之后我最需要调整的就是提示词的写法。Claude Code 的超大上下文让我习惯了把整个项目的背景和任务一次性说清楚但 Pi 配合普通模型时上下文窗口要小不少。一开始我不适应经常把任务描述写太长结果跑着跑着就被截断。后来我自己总结了一套“切块式使用法”一个大任务拆成几个小任务每个小任务只负责一小块信息。要分析整个仓库前先让 Pi 列出目录结构再让它按需读取相关文件而不是一股脑把整个工程塞进对话里。另一个调整是温度参数。接 DeepSeek 这种话痨型模型时不把 temperature 调低到 0.3 以下它能在每一步操作前先跟你解释一大段它的“思路”。这在聊天场景没问题但在代理场景是灾难。我在配置里加了一条约束性提示词“只输出执行结果不要解释过程”行为立刻规矩了很多。4. 我踩过的三个 Pi 坑附带排查思路4.1 response stream was malformed重试本身解决不了问题这个报错我在迁移后没几天就撞上了而且是在任务跑到一半的时候突然冒出“pi error: the response stream was malformed and no response was produced. try again.”当时第一反应是 Pi 本身有 bug差点卸载重装。冷静下来之后我开始排查发现真正的原因在模型 API 返回的流式响应上。响应流是多个 SSE 事件拼接的中间任意一个事件被截断、乱序或者出现意外字符代理解析时就会抛出这个错误。常见诱因包括网络抖动、代理网关缓存干预以及某些参数设置导致的输出中断。最终的解决办法是三管齐下先在一次任务里降低max_tokens避免生成长响应时被掐断然后在网关层关掉了对响应内容的缓冲最后给 Pi 配置了自动重试机制限定重试次数避免死循环。提示遇到这类流式解析错误不要急着骂工具先看模型返回的原始响应是否完整。很多所谓“代理难用”的锅其实在模型服务端。4.2 上下文被日志灌满任务跑一半就“失忆”我一度让 Pi 直接承接“帮我看看这个项目测试为什么挂”的任务结果它跑着跑着自己把自己绕晕了。打开日志一看问题不在推理能力而是过程信息太杂测试输出、临时打印、无关文件内容全都堆进了上下文真正有价值的错误线索反而被挤掉了。这其实是一个信息筛选问题。Claude Code 因为模型上下文能力强能在大噪音中抓重点但 Pi 配合普通模型时如果喂给它一堆垃圾日志模型的“记忆区”很快就会被占满。我的应对方案是给 harness 增加“先过滤再读取”的步骤凡是日志文件先跑一遍过滤规则提取其中的 ERROR、Exception、关键堆栈再进入代理上下文。这一步前移之后Pi 的准确率和稳定性都明显提升。4.3 接入 DeepSeek 后话痨、格式不稳的调教方案DeepSeek 的代码能力大家都有目共睹但它直接作为代理模型使用时会有一个很典型的问题喜欢解释喜欢输出思考过程偶尔还让 markdown 格式错乱。这在纯对话里是优点放在自动执行任务的代理里就变成了干扰。我做的第一件事是调整 system prompt把“你是资深工程师执行任务时保持沉默只输出结果”写进跟用户提示词同等重要的位置。第二件事是调低 temperature让生成更稳定。第三件事是准备了一份“负面示例”把上一次跑偏的输出放进去让模型在后续交互中刻意避开那种风格。这套“提示词约束 采样参数调整 负面示例反馈”的组合帮我稳定住了大多数场景。虽然做不到每句话都完美但执行效率已经从“堪用”提升到了“可用”。5. 迁移过程中的常见问题速查表问题现象可能原因解决办法response stream was malformed模型流式响应被截断或乱序降低 max_tokens关闭网关缓冲配置限次重试上下文塞爆任务中途效果变差无关信息填充过多在 harness 中增加日志过滤步骤缩小任务粒度接 DeepSeek 后输出解释性废话太多模型风格 提示词约束不足加“只输出结果”约束temperature 调低到 0.3 以下本地模型响应慢CPU 推理或无 GPU 加速换量化模型减少并发任务分片执行工具调用流程不符合预期harness 步骤定义不清晰把每个步骤的参数和跳转逻辑写全别依赖模型自行判断不知道某功能是否支持不同开源版本差异大认准一个主仓库直接读源码确认别只搜帖子想用回 Claude Code 的 skills格式不兼容把 skill 拆成工具函数迁移思路比迁移写法更重要这张表来自我自己的实操和各种群聊里面别人踩坑的经验汇总。它不见得覆盖所有场景但覆盖了迁移动摇期最容易劝退你的那些点。6. 我的最终选择与一条最实在的建议经过这段时间的折腾我现在的主力工具已经是 Pi但并没有彻底卸载 Claude Code。偶尔处理那些特别依赖超长上下文、需要极强推理能力的复杂重构任务时我还是会切回 Claude Code。两者不冲突反而形成了互补Pi 负责那些可以被规则化、流程化的日常工作Claude Code 负责那些需要“灵光一现”的硬骨头。如果你也在犹豫要不要迁移我的建议是先别急着卸载任何东西。花一个下午把 Pi 的 harness 配起来拿一个小型 Python 项目跑一圈感受一下“显式工作流”和“模型自由发挥”的差别。等你习惯了控制流程带来的确定性大概率就回不去了。反正我是从“试试看”变成“日常主力”的这个转变用时不到两周。最后再分享一个我个人的小经验迁移时不要试图把 Claude Code 里的每一个功能都在 Pi 里原样复刻。先挑最核心的两三个场景比如“报错修复”“提交信息生成”“代码审查”把它们做成稳定的 harness 工作流。用得顺手了再逐步加新的工具和流程比一次性大搬迁稳妥得多。
阅读完成 · 觉得有帮助？
