1. 从 Claude Code 到 Pi：一场关于 AI Coding 工具链的理性迁移
最近半年，我身边不少做 AI Coding 的朋友都在悄悄换工具。不是从 Cursor 换到 Windsurf 那种小打小闹，而是把用了很久的 Claude Code 从主力位置上撤下来，转投一个叫 Pi 的 agent 框架。这个现象挺有意思——Claude Code 背靠 Anthropic，模型能力强、生态成熟，按理说没有明显的硬伤，为什么会被一个相对小众的 Pi 抢走用户？
我自己也是这波迁移的亲历者。大概三个月前，我还在用 Claude Code 跑日常的代码生成和重构任务，后来因为一个多 agent 协作的项目需求，开始接触 Pi，结果用着用着就把主力工作流整个搬过去了。这篇文章不是要踩一捧一，而是想把这几个月踩过的坑、对比过的参数、以及最终做出选择的逻辑，完整地摊开来聊一聊。如果你正在纠结要不要换工具，或者单纯想搞清楚 Pi 到底解决了什么问题，这篇内容应该能帮你省下不少试错时间。
先说结论：Pi 吸引人的地方不在于模型本身，而在于它把harness这层做薄了、做透了。Claude Code 更像一个封装好的成品，开箱即用但定制空间有限；Pi 则更像一套乐高积木，你需要自己搭，但搭出来的东西完全贴合你的工作流。这个差异在简单任务上感知不强，一旦涉及多 agent 编排、自定义工具链、或者需要接入 DeepSeek 这类第三方模型时，差距就非常明显了。
2. 核心差异拆解：Claude Code 和 Pi 到底在解决什么问题
2.1 Claude Code 的定位与它的隐性天花板
Claude Code 本质上是一个agent harness——它把 Claude 模型包装成一个可以读写文件、执行命令、调用工具的编程助手。你安装完 Claude Code，配置好 API key，就能在终端里让它帮你改代码、跑测试、提交 commit。这个体验在早期非常惊艳，因为它把“模型能力”和“工程操作”之间的鸿沟填平了。
但用久了会发现几个问题。第一，Claude Code 的工具调用是黑盒的。你没法精细控制它什么时候读文件、什么时候执行命令，只能通过 prompt 去引导。第二，它的 agent 循环是固定的，你很难插入自己的预处理或后处理逻辑。第三，也是最要命的一点——它和 Claude 模型绑定得太紧。虽然社区有人尝试用 Claude Code 接入 DeepSeek，但本质上是在 hack 它的 API 层，稳定性和官方支持都谈不上。
我实测下来，Claude Code 在单轮任务上表现很好，比如“把这个函数重构成 async 的”或者“给这个模块补单元测试”。但一旦任务需要多步推理、跨文件修改、或者需要调用外部工具（比如查数据库、调内部 API），它的表现就开始不稳定。有时候它会陷入循环，反复读同一个文件；有时候它会跳过关键步骤，直接给你一个看起来对但跑不通的结果。
2.2 Pi 的设计哲学：薄 harness，厚 agent
Pi 的思路完全不一样。它不试图做一个“全能助手”，而是提供一个agent 执行框架，让你自己定义 agent 的行为、工具集、以及执行流程。你可以把它理解成一个 agent 的操作系统——它负责调度、通信、状态管理，但具体的“智能”部分由你接入的模型和工具来决定。
这个设计带来的最大好处是灵活性。你可以用 Pi 搭一个专门做代码审查的 agent，只给它读文件和写评论的权限；也可以搭一个多 agent 系统，一个负责写代码，一个负责测试，一个负责合并。这些在 Claude Code 里很难做到，因为它的抽象层级太高了。
另一个关键差异是模型无关性。Pi 不绑定任何特定模型，你可以接 Claude，也可以接 DeepSeek，甚至可以接本地部署的开源模型。这对于需要控制成本或者有数据合规要求的团队来说，吸引力巨大。我认识几个做企业级 AI Coding 的朋友，他们选 Pi 的核心原因就是可以接入 DeepSeek 的 harness，把推理成本降到 Claude 的几分之一。
2.3 一张表看清两者的核心差异
| 维度 | Claude Code | Pi |
|---|---|---|
| 定位 | 成品 agent 助手 | agent 执行框架 |
| 模型绑定 | 强绑定 Claude | 模型无关，可接 DeepSeek 等 |
| 工具调用 | 黑盒，prompt 引导 | 白盒，可自定义工具集 |
| 多 agent 支持 | 弱，基本单 agent | 强，原生支持多 agent 编排 |
| 定制化程度 | 低，配置项有限 | 高，可改执行流程 |
| 上手难度 | 低，开箱即用 | 中，需要理解 agent 概念 |
| 适用场景 | 日常代码生成、重构 | 复杂工作流、多 agent 协作 |
这张表不是要证明 Pi 全面优于 Claude Code，而是想说明两者的适用场景不同。如果你只是想让 AI 帮你写写函数、改改 bug，Claude Code 可能更省心。但如果你需要构建一套可复用的 AI Coding 工作流，或者想把 agent 能力嵌入到现有系统里，Pi 的架构优势就体现出来了。
3. Pi 的核心机制：harness、agent 与执行循环
3.1 什么是 harness，为什么它决定了 agent 的上限
Harness 这个词在 AI Coding 圈子里最近被提得很多，但很多人其实没搞清楚它到底指什么。简单来说，harness 是连接模型和实际执行环境的中间层。模型负责“想”，harness 负责“做”。它决定了模型能调用哪些工具、以什么顺序调用、调用结果如何反馈给模型、以及整个循环什么时候终止。
Claude Code 的 harness 是封装好的，你只能通过配置文件调整一些参数，比如最大迭代次数、超时时间。但 Pi 的 harness 是开放的，你可以自己定义工具、自己写执行逻辑、自己控制循环终止条件。这个差异在简单任务上感知不强，但在复杂场景下就是天壤之别。
举个例子：假设你想让 agent 在修改代码后自动跑一遍 lint，如果 lint 失败就回滚。在 Claude Code 里，你只能通过 prompt 告诉它“改完后跑 lint，失败就回滚”，但模型不一定每次都遵守。在 Pi 里，你可以直接在执行循环里插入一个 lint 步骤，失败就触发回滚工具，这是确定性的，不依赖模型的“自觉性”。
3.2 Agent 执行循环的拆解：从输入到输出发生了什么
Pi 的 agent 执行循环大致分为几个阶段。首先是任务解析，agent 接收用户输入，结合上下文生成一个执行计划。然后是工具调用，agent 根据计划选择合适的工具，比如读文件、写文件、执行命令。接着是结果评估，agent 检查工具返回的结果，判断任务是否完成。如果没完成，就回到工具调用阶段，继续循环。最后是终止条件判断，当任务完成或达到最大迭代次数时，循环结束。
这个循环看起来简单，但每个阶段都有很多可调参数。比如任务解析阶段，你可以控制 agent 的“思考深度”——是让它直接生成计划，还是先做一轮推理再生成计划。工具调用阶段，你可以设置工具的优先级和互斥关系，避免 agent 同时调用冲突的工具。结果评估阶段，你可以定义自己的成功标准，而不是依赖模型的自我判断。
我实测下来，Pi 的循环控制比 Claude Code 精细很多。Claude Code 的循环基本是“模型说完了就停”，但 Pi 允许你在每一轮循环后插入自定义逻辑。这个能力在调试 agent 行为时特别有用——你可以打印每一轮的中间状态，看清楚 agent 到底在干什么。
3.3 多 agent 编排：Pi 的真正杀手锏
Pi 最吸引我的功能是多 agent 编排。你可以定义多个 agent，每个 agent 有自己的角色、工具集和模型配置，然后通过一个 orchestrator 来协调它们的工作。这个模式在复杂任务上优势明显。
比如我最近做的一个项目，需要 agent 自动完成“读需求文档 -> 生成代码 -> 写测试 -> 跑测试 -> 提交 PR”这个流程。在 Claude Code 里，我只能用一个 agent 从头跑到尾，中间任何一步出错都得重新来。但在 Pi 里，我拆了四个 agent：一个负责读文档和生成代码，一个负责写测试，一个负责跑测试，一个负责提交。每个 agent 只做一件事，出错时只需要重跑对应的 agent，不用整个流程重来。
更重要的是，多 agent 可以并行。比如代码生成和测试编写可以同时进行，只要测试 agent 知道代码的接口约定就行。这个并行能力在大型项目上能省不少时间。当然，多 agent 也带来了新的复杂度——agent 之间的通信、状态同步、错误传播都需要仔细设计。这个后面会详细讲。
4. 实操：从零搭建一个 Pi agent 工作流
4.1 环境准备与 Pi 的安装
Pi 的安装比 Claude Code 稍微复杂一点，因为它不是一个单一的二进制文件，而是一套框架。你需要先装 Node.js 环境（建议 18 以上），然后通过 npm 安装 Pi 的 CLI 工具。安装命令大概是这样的：
npm install -g @pi-agent/cli装完之后，你需要初始化一个 Pi 项目。在你的工作目录下运行：
pi init这个命令会生成一个pi.config.js文件，里面包含了 agent 的基本配置。你需要在这里填入模型信息、工具配置、以及执行参数。如果你要接入 DeepSeek，还需要额外配置 DeepSeek 的 API endpoint 和 key。
注意：Pi 的配置文件格式在不同版本间可能有变化，建议装完后先跑
pi doctor检查环境，它会告诉你哪些配置缺失或格式不对。
我踩过的一个坑是 Node 版本太低导致 Pi 的某些依赖装不上。Pi 用了一些较新的 ES 特性，Node 16 会报错，建议直接上 Node 20。另外，如果你在国内，npm 源建议换成淘宝镜像，不然安装过程会很慢。
4.2 定义你的第一个 agent：从配置到运行
Pi 的 agent 定义在一个叫agents的目录下，每个 agent 是一个独立的 JS 文件。一个最简单的 agent 配置大概长这样：
export default { name: 'code-reviewer', model: 'deepseek-chat', tools: ['readFile', 'writeFile', 'runCommand'], systemPrompt: '你是一个代码审查专家，负责检查代码质量和潜在 bug。', maxIterations: 10, };这个配置定义了一个叫code-reviewer的 agent，它使用 DeepSeek 的模型，可以读文件、写文件、执行命令，最多循环 10 次。systemPrompt是这个 agent 的“人设”，决定了它的行为风格。
定义完 agent 后，你可以通过 CLI 直接运行它：
pi run code-reviewer --input "审查 src/utils 目录下的所有文件"Pi 会启动 agent 循环，调用模型生成计划，然后执行工具调用。你可以在终端里看到每一步的输出，包括模型生成的计划、工具调用的参数和结果、以及最终的总结。
我建议新手先从单 agent 开始，跑通一个简单任务后再尝试多 agent。Pi 的文档里有一个“hello world”级别的示例，就是让 agent 读一个文件然后输出文件内容，这个用来验证环境是否配置正确非常合适。
4.3 工具集配置：给 agent 装上手脚
Pi 的工具集是它最灵活的部分。内置工具包括readFile、writeFile、runCommand、listDir等基本操作，但你可以通过插件机制扩展自己的工具。比如你想让 agent 能查数据库，可以写一个queryDatabase工具：
export const queryDatabase = { name: 'queryDatabase', description: '执行 SQL 查询并返回结果', parameters: { sql: { type: 'string', description: '要执行的 SQL 语句' }, }, execute: async ({ sql }) => { const result = await db.query(sql); return JSON.stringify(result); }, };然后在 agent 配置里把这个工具加进去：
tools: ['readFile', 'writeFile', 'queryDatabase'],这个扩展能力在 Claude Code 里基本没有。Claude Code 的工具集是固定的，你只能用它提供的那些。Pi 则允许你根据业务需求自由扩展，这对于需要接入内部系统的团队来说非常关键。
提示：自定义工具时，
description和parameters的写法会直接影响模型调用工具的准确性。描述要尽量具体，参数类型要明确，否则模型可能会传错参数或者干脆不调用。
4.4 多 agent 协作的配置与调试
多 agent 的配置稍微复杂一些。你需要定义一个 orchestrator agent，它负责协调其他 agent 的工作。Orchestrator 的配置里需要声明它管理的子 agent：
export default { name: 'orchestrator', model: 'claude-3-opus', subAgents: ['code-writer', 'test-writer', 'test-runner'], systemPrompt: '你是一个项目协调者，负责分配任务给子 agent 并汇总结果。', };Orchestrator 会根据任务内容决定调用哪个子 agent，子 agent 执行完后把结果返回给 orchestrator，orchestrator 再决定下一步。这个模式在 Pi 里是原生支持的，你不需要自己写调度逻辑。
调试多 agent 时，最大的挑战是状态同步。子 agent 之间不共享内存，它们通过 orchestrator 传递消息。如果消息格式不对，或者某个子 agent 返回了预期之外的结果，整个流程就可能卡住。我的经验是，在开发阶段给每个子 agent 加上详细的日志输出，这样出问题时能快速定位是哪个环节出了错。
5. 迁移过程中踩过的坑与排查技巧
5.1 模型接入的常见问题
从 Claude Code 迁到 Pi，第一个要面对的就是模型接入。Claude Code 默认用 Claude，你不需要操心 API 格式。但 Pi 是模型无关的，你需要自己处理不同模型的 API 差异。我试过接 DeepSeek，也试过接本地的开源模型，踩了不少坑。
最常见的问题是响应格式不兼容。不同模型返回的 JSON 结构可能不一样，有的把工具调用放在tool_calls字段，有的放在function_call字段。Pi 虽然做了适配层，但并不是所有模型都能完美支持。我遇到过一次，DeepSeek 返回的工具调用参数格式和 Pi 预期的不一致，导致 agent 一直卡在工具调用阶段。后来在 Pi 的配置里加了一个responseParser才解决。
另一个问题是流式响应的处理。Pi 默认支持流式输出，但有些模型的流式响应格式比较特殊，会导致 Pi 报the response stream was malformed错误。这个错误在社区里被提过很多次，解决办法通常是关掉流式模式，或者升级 Pi 到最新版本。
5.2 Agent 执行中断的排查思路
Agent 执行中断是另一个高频问题。Pi 的 agent 循环可能因为多种原因中断：模型返回了无法解析的内容、工具调用超时、达到了最大迭代次数、或者触发了自定义的终止条件。
排查时我一般按这个顺序来：先看日志里最后一条工具调用的结果，确认是不是工具本身出了问题；然后看模型的最后一条输出，确认是不是模型“跑偏”了；最后检查配置里的maxIterations和超时设置，确认是不是参数太保守。
有一个坑我印象很深：有一次 agent 一直卡在“读文件”这一步，反复读同一个文件。查了半天发现是systemPrompt写得太模糊，模型不确定任务是否完成，所以一直循环。后来把 prompt 改得更具体，明确告诉它“读完文件后直接输出内容，不要做其他操作”，问题就解决了。
5.3 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 安装时报 Node 版本错误 | Node 版本过低 | 升级到 Node 20 以上 |
| 模型返回格式解析失败 | 模型 API 格式不兼容 | 配置 responseParser 或换模型 |
| 流式响应报 malformed 错误 | 流式格式不兼容 | 关闭流式模式或升级 Pi |
| Agent 反复执行同一步骤 | systemPrompt 不明确 | 细化 prompt，明确终止条件 |
| 多 agent 通信卡住 | 消息格式不一致 | 检查子 agent 的返回格式 |
| 工具调用超时 | 工具执行时间过长 | 增加超时时间或优化工具实现 |
这张表是我这几个月踩坑的精华总结，基本上覆盖了 80% 的常见问题。遇到新问题时，我建议先去 Pi 的 GitHub issues 里搜一下，很多问题社区已经有人遇到过并给出了解决方案。
6. 我的实操心得与选型建议
6.1 什么时候该用 Pi，什么时候该留在 Claude Code
用了几个月 Pi 之后，我的感受是：工具没有绝对的好坏，只有适不适合。如果你是一个独立开发者，日常任务主要是写写函数、改改 bug、生成一些样板代码，Claude Code 的开箱即用体验其实更好。你不需要理解 agent 循环、工具集、多 agent 编排这些概念，装完就能干活。
但如果你符合以下任何一种情况，Pi 可能更适合你：需要接入 DeepSeek 或其他非 Claude 模型来控制成本；需要构建可复用的 AI Coding 工作流；需要多 agent 协作来完成复杂任务；需要把 agent 能力嵌入到现有系统里。这些场景下，Pi 的灵活性和扩展性是 Claude Code 给不了的。
我自己的选择是两者都用。日常的轻量任务用 Claude Code，复杂的工作流用 Pi。这样既能享受 Claude Code 的便利，又能利用 Pi 的灵活性。工具是为人服务的，没必要非此即彼。
6.2 给准备迁移的朋友几条实在建议
如果你决定试试 Pi，我有几条建议可以帮你少走弯路。第一，先从单 agent 开始，不要一上来就搞多 agent。单 agent 跑通了，理解了 Pi 的执行循环和工具调用机制，再考虑多 agent 编排。第二，把 systemPrompt 写具体，不要指望模型自己“悟”出你的意图。你写得越明确，agent 的行为越可控。第三，善用日志，Pi 的日志系统很详细，出问题时先看日志，大部分问题都能从日志里找到线索。
还有一点很重要：不要盲目追求最新版本。Pi 的迭代速度很快，新版本可能引入不兼容的变更。我一般会等一个新版本发布后观察一周，确认社区没有大规模反馈问题再升级。生产环境尤其要谨慎，升级前先在测试环境跑一遍完整流程。
6.3 关于 AI Coding 工具链的一点个人观察
这波从 Claude Code 到 Pi 的迁移，本质上反映了一个趋势：AI Coding 正在从“成品工具”向“可编程框架”演进。早期的 AI Coding 工具追求的是“开箱即用”，把模型能力包装成一个易用的产品。但随着用户需求分化，越来越多的人开始需要定制化、可扩展的解决方案。Pi 这类框架的出现，正好填补了这个空白。
我个人的判断是，未来 AI Coding 工具会分成两层：上层是面向普通用户的成品工具，下层是面向开发者的 agent 框架。两者不是替代关系，而是互补关系。Claude Code 在上层做得很好，Pi 在下层有独特优势。理解这个分层，能帮你在选型时做出更理性的判断。
最后分享一个我最近发现的小技巧：Pi 的 agent 配置支持环境变量注入，你可以把 API key、数据库连接串这些敏感信息放在环境变量里，而不是硬编码在配置文件里。这样既安全，又方便在不同环境间切换。具体做法是在pi.config.js里用process.env.XXX引用环境变量，然后在启动 Pi 之前 export 对应的变量。这个技巧在团队协作时特别有用，每个人用自己的 key，互不干扰。
