从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 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 init

pi 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 分析出的依赖关系，如果只是文本描述传给 planner，planner 可能理解偏差。我的解法是让 reader 输出结构化数据（JSON 格式的模块清单），planner 直接读结构化数据，减少自然语言转述的损耗。

第二个坑是循环失控。verifier 和 coder 来回打回，如果 max_loops 设太大，token 烧得飞快。我一般设 3 次，超过就人工介入。热词里 "agent execution terminated due to error" 这个报错，很多时候就是循环次数超限被 harness 强制终止。

第三个坑是模型混用导致风格不一致。如果 reader 用 DeepSeek、coder 用 Claude，两个模型的代码风格和命名习惯可能打架。我的建议是同一套 workflow 里尽量用同一个模型，要换模型就整套换。

5. 常见问题与排查技巧实录

5.1 安装和配置阶段的典型报错

我把这段时间遇到的问题整理成了一张速查表：

这张表里我重点说两个。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 值得你花两天时间认真试试。