从Claude Code迁移到Pi：AI Coding harness与多agent协作实战

1. 从 Claude Code 到 Pi一场关于 AI Coding 控制权的迁移最近半年我身边做 AI Coding 的朋友陆续在换工具。不是从 Cursor 换到 Windsurf 那种平级跳而是从 Claude Code 这种官方大厂出品转向一个叫 Pi 的东西。第一次听到Pi这个名字我下意识以为是树莓派那个 Pi或者是数学常数直到有人在群里甩了一句Pi agent 官网文档比 Claude Code 清楚十倍我才意识到这是另一个赛道的东西。先把话说清楚Pi 在这里指的是一套围绕harness概念构建的 AI Coding agent 框架核心思路是把模型能力和执行编排彻底解耦。Claude Code 走的是官方一体化路线——模型、工具链、权限系统、上下文管理全打包开箱即用但黑盒Pi 走的是 harness 路线——你拿一个模型可以是 Claude也可以是 DeepSeek、GPT 或者本地模型套上 Pi 的 harness 层自己决定 agent 怎么跑、工具怎么调、上下文怎么裁。这个差别听起来很抽象但落到日常写代码的场景里就是你能不能改它的行为和你只能适应它的行为的区别。为什么越来越多人放弃 Claude Code 转 Pi我自己的答案有三层。第一层是成本与可控性Claude Code 的订阅和 token 消耗对重度用户不友好而且你没法换模型模型涨价或者限流你只能干等。第二层是harness 工程的可玩性Pi 把 agent 的执行循环、工具注册、skill 加载都暴露出来你可以像搭积木一样拼自己的 coding 工作流这对做 agent 开发的人来说是刚需。第三层是多智能体协作Claude Code 本质是单 agent 加子任务Pi 的 harness 设计天然支持多 agent 分工一个负责读代码库一个负责写一个负责跑测试这在大型项目里效率差距非常明显。这篇文章适合三类人看正在用 Claude Code 但觉得哪里不对劲的重度用户、想入门 agent 开发但被各种框架绕晕的新手、以及团队里需要统一 AI Coding 规范的技术负责人。我会把 Pi 的 harness 机制、和 Claude Code 的实际差异、安装配置、多 agent 协作规范、以及我踩过的坑全部摊开讲。不吹不黑只讲我实测下来的东西。2. 核心概念拆解harness、agent 和 Pi 到底在解决什么问题2.1 harness 和 agent 的区别一句话讲透很多人第一次看到 harness 这个词是懵的因为它直译是马具、挽具跟 AI 八竿子打不着。但在 agent 工程语境里harness 的意思非常精准它是套在模型外面的那层挽具负责把模型的原始输出转化成可执行的行动再把行动结果喂回给模型。打个比方。模型是一匹力气很大但不知道往哪跑的马agent 是要送快递到某地这个任务harness 就是马具加缰绳加车架——它决定了马往哪个方向跑、跑多快、遇到障碍怎么绕、累了怎么换马。没有 harness模型只能聊天有了 harness模型才能真的去读文件、跑命令、改代码。所以harness 和 agent 的区别是agent 是做什么目标、角色、决策逻辑harness 是怎么做执行循环、工具调用、错误处理、上下文管理。一个 agent 可以换不同的 harness同一个 harness 也能跑不同的 agent。Claude Code 把这两者焊死在一起Pi 把它们拆开卖。这个拆分的价值在哪举个我自己的例子。我用 Claude Code 的时候最烦的是它读大文件时经常把整个文件塞进上下文token 哗哗烧。我想改成只读函数签名和注释但 Claude Code 不给我这个开关。换到 Pi 之后我在 harness 层写了个 context 裁剪策略先用 tree-sitter 解析文件只把函数签名、类型定义、docstring 提取出来给模型需要看具体实现时再按需读取。同样的任务token 消耗降了大概 60%而且模型因为上下文更干净改代码的准确率反而上升了。2.2 Pi 的定位不是 Claude Code 的替代品是它的可编程版需要澄清一个误区Pi 不是要做一个更好的 Claude Code。它的定位更像AI Coding 的 harness 运行时。你可以把它理解成 agent 世界的 Node.js——它提供事件循环、工具注册、skill 加载、多 agent 调度这些底层能力具体你的 coding agent 长什么样你自己定义。这就解释了为什么热词里同时出现 pi agent、pi harness、pi web、pi agent github 这些词。Pi agent 是跑在 Pi harness 上的具体 agent 实现pi web 是它的 Web 界面pi agent github 是源码仓库。它们是一套东西的不同切面。和 Claude Code 对比Pi 的核心差异我整理成了一张表维度Claude CodePi模型绑定只能用 Anthropic 模型任意模型可热切换执行逻辑黑盒官方定义harness 层完全可编程工具系统内置固定工具集工具注册制可自定义多 agent单 agent 子任务原生多 agent 协作上下文管理自动不可干预可自定义裁剪策略部署方式官方客户端/CLI自托管可跑在本地或服务器成本模型订阅 token取决于你接的模型学习曲线低开箱即用中高需要理解 harness这张表里最关键的一行是执行逻辑。Claude Code 的黑盒意味着你遇到问题时只能等官方修或者绕过去。Pi 的可编程意味着你能自己修甚至能针对自己的代码库做深度定制。对于把 AI Coding 当生产力工具的重度用户这个差别是决定性的。2.3 为什么是现在AI Coding 进入工程化阶段Pi 这类 harness 框架火起来不是偶然。2024 年大家还在惊叹AI 能写代码了2025 年大家的关注点已经变成AI 写的代码质量怎么保证、多 agent 怎么协作不打架、上下文怎么管理不爆 token。热词里 ai coding 的到来会不会让代码质量下降 和 多智能体 ai agent coding 协助开发规范 同时上榜说明行业焦虑已经从能不能用转向怎么用好。Claude Code 解决的是让 AI 能写代码Pi 解决的是让 AI 按你的工程规范写代码。前者是能力问题后者是工程问题。当团队规模上来、代码库变大、规范要求变严工程问题的重要性就压过了能力问题。这就是迁移潮的底层逻辑。3. 实操从零搭一套 Pi harness 环境3.1 安装前的环境准备与选型先说清楚Pi 的安装方式取决于你拿它干什么。如果你只是想体验一下 Pi agent 写代码最省事的是用官方提供的 CLI 或者 pi web 界面。如果你想做 agent 开发、定制 harness那就得从源码或者包管理器装。我实测下来Ubuntu 22.04 和 macOS 是最顺的两个环境。Windows 用户建议走 WSL2原生 Windows 下有些工具调用的路径处理会有问题。Node.js 版本建议 20 LTS 以上因为 Pi 的 harness 层用了不少较新的异步特性。Python 环境建议 3.11如果你要用到 skill 系统里的一些数据处理脚本。注意装之前先确认你的模型接入方式。Pi 本身不带模型你得准备好至少一个模型的 API key或者本地跑一个模型服务。这一步没准备好装完 Pi 也是空转。安装步骤我按 Ubuntu 走一遍macOS 基本一致# 1. 确认 Node 版本 node -v # 需要 20 # 2. 全局安装 Pi CLI具体包名以官方 github 为准 npm install -g pi-agent/cli # 3. 验证安装 pi --version # 4. 初始化配置目录 pi initpi init会在你的用户目录下生成一个.pi配置文件夹里面有harness.yaml、agents/、skills/、tools/几个子目录。这个结构就是 Pi 的核心harness.yaml 定义执行循环agents 放 agent 定义skills 放可复用的能力模块tools 放自定义工具。3.2 harness.yaml 的关键配置项harness.yaml 是整个 Pi 环境的心脏它决定了 agent 怎么跑。我把我常用的配置拆开讲harness: name: my-coding-harness max_iterations: 30 # 单任务最大循环次数防止死循环 context_strategy: smart # 上下文裁剪策略full / smart / minimal error_retry: 3 # 工具调用失败重试次数 parallel_agents: true # 是否允许多 agent 并行 model: provider: deepseek # 或 anthropic / openai / local name: deepseek-coder temperature: 0.2 # 写代码建议低温度 max_tokens: 8192 tools: - file_read - file_write - shell_exec - code_search - test_runner skills: - path: ./skills/code-review - path: ./skills/refactor这里有几个参数值得展开说。max_iterations我建议设 20 到 40 之间。设太小复杂任务跑一半就断了设太大agent 陷入死循环时会烧掉大量 token。我一般按任务复杂度动态调简单改 bug 设 15大型重构设 40。context_strategy是 Pi 相比 Claude Code 最大的优势点。full是把所有相关文件完整塞进去适合小项目smart是先用代码解析提取结构按需加载实现适合中型项目minimal是只给函数签名和类型适合超大代码库。我实测一个 5 万行的项目用 smart 策略比 full 策略 token 消耗低 55% 左右任务完成率反而高因为模型不被无关代码干扰。temperature这块写代码我强烈建议 0.1 到 0.3。高于 0.5 模型会开始发挥创意改出来的代码风格飘忽review 起来很痛苦。这个参数在 Claude Code 里你是改不了的Pi 里随便调。3.3 接入 DeepSeek 模型的完整流程热词里 deepseek harness 出现频率很高说明不少人是用 DeepSeek 当 Pi 的模型后端。这条路我走过性价比确实高但有几个坑要提前说。model: provider: deepseek name: deepseek-coder api_base: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} # 从环境变量读别硬编码 temperature: 0.2 max_tokens: 8192 timeout: 120配置好之后用pi model test验证连通性。如果报 the response stream was malformed and no response was produced 这个错热词里有人提到八成是三个原因一是 api_base 写错了DeepSeek 的兼容接口路径和官方不完全一样二是 max_tokens 设太大超过了模型上限三是网络层有代理干扰了流式响应。逐个排查基本能解决。DeepSeek 接进 Pi 之后我最大的感受是便宜到可以随便造。同样的重构任务用 Claude 模型跑一次的成本大概是 DeepSeek 的 8 到 10 倍。对于需要反复迭代的 agent 任务这个成本差直接决定了你敢不敢让 agent 多试几次。当然 DeepSeek 在复杂推理上还是弱一些我的策略是日常改代码、写测试、重构用 DeepSeek遇到架构级难题临时切 Claude 模型。Pi 支持运行时热切换模型这个灵活性是 Claude Code 给不了的。4. 多 agent 协作Pi 真正拉开差距的地方4.1 单 agent 的天花板在哪用 Claude Code 久了会发现一个瓶颈它再强也是一个 agent 在干活。一个 agent 要同时负责理解需求、读代码、设计方案、写代码、跑测试、修 bug上下文里塞满了各种角色的信息很容易精神分裂。我遇到过好几次Claude Code 写着写着突然开始review自己刚写的代码然后把自己改回去来回横跳。这不是模型笨是单 agent 架构的固有缺陷。一个上下文窗口里塞太多角色模型的注意力会被稀释。Pi 的 harness 从设计上就支持多 agent每个 agent 有独立的上下文窗口和角色定义通过 harness 层调度协作。这是架构级的差异不是调参能弥补的。4.2 一套可落地的多 agent 分工方案我在实际项目里跑通了一套四 agent 协作方案配置放在agents/目录下# agents/reader.yaml name: reader role: 代码库理解专家 model: deepseek-coder context_strategy: minimal tools: [file_read, code_search] prompt: | 你负责理解代码库结构和依赖关系。 输出格式模块清单 关键接口 依赖图。 不要写任何代码只做分析。 # agents/planner.yaml name: planner role: 方案设计专家 model: deepseek-coder context_strategy: smart tools: [file_read] prompt: | 基于 reader 的分析设计实现方案。 输出改动文件清单 每个文件的改动要点 风险点。 # agents/coder.yaml name: coder role: 代码实现专家 model: deepseek-coder context_strategy: smart tools: [file_read, file_write, shell_exec] prompt: | 严格按 planner 的方案实现不要自行扩大改动范围。 每改完一个文件跑一次相关测试。 # agents/verifier.yaml name: verifier role: 代码验证专家 model: deepseek-coder context_strategy: full tools: [file_read, test_runner, shell_exec] prompt: | 独立验证 coder 的改动重点检查边界条件和回归风险。 发现问题直接报告不要自己修。这套方案的核心是职责隔离。reader 只看不写planner 只设计不实现coder 只按方案写verifier 只验证不修改。每个 agent 的上下文都很干净模型注意力集中输出质量明显比单 agent 高。harness 层的调度逻辑写在 harness.yaml 里workflow: - agent: reader input: ${task.description} output: analysis - agent: planner input: ${analysis} output: plan - agent: coder input: ${plan} output: changes - agent: verifier input: ${changes} output: report - condition: ${report.has_issues} then: coder # 有问题回到 coder 重修 max_loops: 3这个 workflow 定义了一个带反馈回路的流水线。verifier 发现问题就打回 coder 重修最多循环 3 次。实测下来这套流程处理中等复杂度的功能开发一次通过率大概 70%两次内通过率 90% 以上。比单 agent 反复横跳的效率高太多了。4.3 多 agent 协作的避坑要点多 agent 不是银弹我踩过的坑列几个第一个坑是agent 之间信息传递丢失。reader 分析出的依赖关系如果只是文本描述传给 plannerplanner 可能理解偏差。我的解法是让 reader 输出结构化数据JSON 格式的模块清单planner 直接读结构化数据减少自然语言转述的损耗。第二个坑是循环失控。verifier 和 coder 来回打回如果 max_loops 设太大token 烧得飞快。我一般设 3 次超过就人工介入。热词里 agent execution terminated due to error 这个报错很多时候就是循环次数超限被 harness 强制终止。第三个坑是模型混用导致风格不一致。如果 reader 用 DeepSeek、coder 用 Claude两个模型的代码风格和命名习惯可能打架。我的建议是同一套 workflow 里尽量用同一个模型要换模型就整套换。5. 常见问题与排查技巧实录5.1 安装和配置阶段的典型报错我把这段时间遇到的问题整理成了一张速查表报错信息可能原因解决方法pi: command not found全局安装路径没进 PATH检查 npm 全局 bin 路径手动加进 PATHresponse stream was malformedapi_base 错误或流式响应被干扰核对接口地址检查 max_tokens 是否超限agent execution terminated due to error循环超限或工具调用连续失败调大 max_iterations检查工具权限context window exceeded上下文策略太激进从 full 切到 smart 或 minimaltool not registeredharness.yaml 里没声明该工具在 tools 列表里补上skill load failedskill 路径错误或依赖缺失检查路径确认 skill 依赖已安装这张表里我重点说两个。response stream was malformed这个错我排查了整整一个下午最后发现是本地网络环境对长连接做了限制导致流式响应被截断。解法是把 timeout 调大或者改用非流式模式牺牲一点响应速度换稳定性。agent execution terminated due to error这个错更隐蔽。表面看是执行出错实际可能是 agent 在某个工具调用上连续失败 3 次触发了 harness 的保护机制。这时候要看 harness 的日志找到具体是哪个工具调用失败而不是盲目重试。5.2 上下文管理的实战心得上下文管理是 Pi 用得好不好的分水岭。我总结了三条经验第一条永远不要用 full 策略跑大项目。full 策略看起来信息最全实际上是把噪声也全塞进去了。模型在大量无关代码里找相关信息准确率反而下降。我实测一个 3 万行的项目full 策略下模型改错文件的概率是 smart 策略的 2 倍多。第二条给不同 agent 配不同策略。reader 用 minimal只要结构planner 用 smart要关键实现coder 用 smart要上下文但不要全量verifier 用 full要完整验证。这个组合是我试了很多次才调出来的。第三条定期清理 agent 的对话历史。Pi 的 agent 默认会保留完整对话历史跑久了上下文会膨胀。我在 harness 里配了个策略每完成一个子任务就把该子任务的中间过程压缩成摘要只保留结论。这样长任务跑下来上下文不会爆。5.3 关于代码质量的真实观察热词里 ai coding 的到来会不会让代码质量下降 这个问题我用 Pi 跑了几个月之后有个比较明确的答案工具本身不决定代码质量工程规范才决定。Claude Code 时代因为工具是黑盒你很难强制它遵守团队的代码规范。它写出来的代码风格取决于模型训练数据你只能事后 review 修改。Pi 的 harness 层可以挂 skill我把团队的代码规范写成了一个 code-review skill每次 coder 写完代码harness 自动调用这个 skill 做规范检查不符合的直接打回重写。# skills/code-review/skill.yaml name: code-review trigger: after_write rules: - 函数不超过 50 行 - 必须有类型注解 - 禁止裸 except - 命名遵循团队规范 - 公共函数必须有 docstring action: reject_and_retry这个 skill 挂上之后agent 写出来的代码规范符合度从大概 60% 提到了 95% 以上。这就是 harness 工程的价值把事后 review变成事前约束。6. 迁移决策什么情况下该换什么情况下别折腾6.1 适合迁移到 Pi 的三类人第一类是重度 AI Coding 用户。如果你每天用 Claude Code 超过 2 小时token 成本已经让你肉疼或者你经常遇到想改它行为但改不了的憋屈那 Pi 值得投入时间学。前期学习成本大概两三天之后每天省下的成本和提升的效率很快能回本。第二类是agent 开发学习者。热词里 agent开发学习路线 和 agent框架 热度很高说明很多人想入门这个方向。Pi 的 harness 设计比大多数 agent 框架都清晰拿它练手能快速理解 agent 的执行循环、工具调用、多 agent 协作这些核心概念。而且它是真能干活的不是玩具。第三类是有代码规范要求的团队。如果你的团队对代码质量有硬性要求Pi 的 skill 系统能把规范固化到 agent 工作流里比人工 review 靠谱得多。6.2 不建议迁移的情况如果你只是偶尔用 AI 写写小脚本Claude Code 的开箱即用更省心。Pi 的灵活性是有代价的你得理解 harness、配 agent、调参数这些对轻度用户是负担。如果你团队里没人懂 agent 工程也不建议贸然上 Pi。Pi 出问题时需要有人能看日志、改配置、调 harness没有这个能力的话遇到问题会卡死。Claude Code 虽然黑盒但至少官方会修。还有一种情况是项目对稳定性要求极高。Pi 是自托管稳定性取决于你的环境和配置。Claude Code 是官方服务稳定性由官方保证。如果你的项目一分钟都停不得那还是用官方服务稳妥。6.3 混合使用的现实方案我现在的实际方案是混合用日常改代码、写测试、重构用 Pi DeepSeek成本低、可控性强遇到特别复杂的架构设计或者 Pi 搞不定的难题临时切回 Claude Code 或者用 Pi 接 Claude 模型。两套工具不是非此即彼而是各管一段。Pi 的模型热切换能力让这种混合方案很自然。我在 harness 里配了模型路由规则任务复杂度低于阈值走 DeepSeek高于阈值走 Claude。这样既控制了成本又保证了难题的解决质量。7. 我踩过的那些坑和最后的几句实话说几个文档里不会写、但实际用起来一定会遇到的坑。第一个坑是工具权限的边界。Pi 的 shell_exec 工具默认权限很大agent 能跑任意命令。我有一次让 agent 重构代码它跑了个rm -rf清理临时文件结果路径写错删了不该删的东西。后来我在 harness 里给 shell_exec 加了白名单只允许跑测试命令和构建命令危险操作一律拦截。这个教训很深刻agent 再聪明也是程序权限该收就得收。第二个坑是skill 的加载顺序。Pi 的 skill 是按声明顺序加载的如果 code-review skill 在 refactor skill 之前加载refactor 产生的代码可能绕过 review。我调了好几次才把顺序理顺先加载规范类 skill再加载操作类 skill。第三个坑是多 agent 的日志排查。四个 agent 并行跑的时候日志是交织的出问题很难定位是哪个 agent 的锅。我的解法是给每个 agent 配独立的日志文件harness 层再汇总一份带 agent 标记的总日志。排查时先看总日志定位到 agent再翻该 agent 的详细日志。最后说几句实话。Pi 不是完美的它的文档还在完善中社区生态也比不上 Claude Code 成熟遇到冷门问题可能得自己啃源码。但它代表的方向是对的AI Coding 工具应该把控制权还给使用者而不是把用户锁在官方定义的工作流里。Claude Code 像一辆出厂调好的车好开但改不了Pi 像一套改装套件上手麻烦但能改成你想要的样子。选哪个取决于你是想开车还是想造车。我现在的工作流已经稳定在 Pi 上了偶尔回 Claude Code 反而觉得束手束脚。这个迁移不是跟风是需求变了——从让 AI 帮我写代码变成让 AI 按我的工程规范写代码。如果你也走到了这个阶段Pi 值得你花两天时间认真试试。