从Claude Code到Pi：AI Coding工具链的工程化迁移与Agent框架实践

1. 从 Claude Code 到 Pi一场 AI Coding 工具链的理性迁移最近半年我身边不少做 AI Coding 的朋友都在悄悄换工具。不是从 Cursor 换到 Windsurf 那种小打小闹而是把用了很久的 Claude Code 从主力工作流里撤下来转投一个叫 Pi 的 agent 框架。这个现象挺有意思因为 Claude Code 在代码生成质量上一直是第一梯队按理说没有理由被轻易替换。但当我真正把两套东西放在同一个项目里跑了几周之后就完全理解了这波迁移背后的逻辑——大家放弃的不是 Claude Code 的模型能力而是它作为 harness 的封闭性和不可控性。先把这个话题里的几个核心概念理清楚不然后面聊不下去。Claude Code是 Anthropic 推出的终端级 AI Coding 工具本质上是一个封装好的 agent harness你给它一个任务它自己规划、读文件、改代码、跑命令。Pi则是一个更底层的 agent 框架它不绑定特定模型你可以把 Claude、DeepSeek、GPT 任意接进来自己定义工具集、执行流程和沙盒策略。Harness这个词在 AI Coding 圈里指的是智能体外壳——负责把大模型的推理能力翻译成实际的文件操作、命令执行和上下文管理的那一层。Agent就是跑在这个 harness 里的执行主体它决定了任务怎么拆、工具怎么调、错误怎么恢复。所以标题里说的放弃 Claude Code 转而用 Pi翻译成大白话就是越来越多开发者不再满足于用一个开箱即用但改不动的成品工具而是转向一个可以自己拼装、自己调参、自己接模型的 agent 开发框架。这背后反映的是 AI Coding 从消费级产品向工程化基础设施演进的一个切面。这篇文章适合两类人看一类是正在用 Claude Code 但觉得哪里不对劲、想搞清楚问题出在哪的开发者另一类是想自己搭 agent 工作流、但不知道从哪下手的技术人。我会把选型逻辑、核心差异、实操配置、踩坑经验全部摊开讲尽量让不同基础的人都能拿走能用的东西。2. 为什么会有这波迁移Claude Code 的边界与 Pi 的切入点2.1 Claude Code 到底强在哪又卡在哪Claude Code 刚出来的时候我第一时间就装了。它的优势非常明确开箱即用终端里敲一个命令就能让模型直接操作你的代码库读文件、写文件、跑测试、修 bug 一条龙。对于个人开发者做小项目或者快速验证一个想法它的体验几乎是无敌的。尤其是 Claude 模型本身在代码理解和生成上的质量配合它精心调过的 prompt 和工具调用逻辑很多时候你只需要描述需求它就能把整个改动做完。但用久了问题就暴露出来了。第一个卡点是模型绑定。Claude Code 只能用 Claude 系列模型你想接 DeepSeek 或者别的模型官方是不支持的。虽然社区有一些 hack 手段但稳定性很差而且每次官方更新都可能失效。第二个卡点是执行流程黑盒。它怎么拆任务、怎么决定读哪些文件、什么时候该跑命令你基本控制不了。遇到复杂项目它有时候会陷入循环反复改同一个文件或者漏掉关键依赖你只能干看着。第三个卡点是工具集固定。它内置的那套工具就那些你想加一个自定义的 lint 检查、想接入公司内部的代码规范校验、想在每次提交前自动跑一个特定的脚本都很难塞进去。这三个卡点归结起来就是一句话Claude Code 是一个封闭的 harness。它把 agent 的规划、工具调用、上下文管理全部封装在内部你只能用不能改。对于只想快速写代码的人来说这是优点但对于想把 AI Coding 接入自己工程体系的团队来说这就是天花板。2.2 Pi 这类框架解决的到底是什么问题Pi 的定位和 Claude Code 完全不同。它不提供模型也不提供开箱即用的编码体验它提供的是一个agent 运行时。你可以把它理解成一个空壳子里面有几个核心模块模型接入层、工具注册层、执行循环层、上下文管理层。你要做的就是往这个壳子里填东西——接哪个模型、注册哪些工具、执行循环怎么设计、上下文怎么裁剪。这种设计带来的最大好处是可控。你可以决定 agent 每一步做什么可以在关键节点插入自己的校验逻辑可以针对不同任务切换不同模型。比如简单的代码补全用便宜的小模型复杂的重构任务切到 Claude 或者 DeepSeek 的大模型。你还可以把公司内部的代码规范、安全扫描、单元测试全部封装成工具注册进去让 agent 在改代码的过程中自动遵守这些约束。另一个好处是可观测。Pi 这类框架通常会暴露完整的执行日志你能看到 agent 每一步的思考、每一次工具调用的输入输出、每一轮上下文的裁剪情况。这对于调试和优化 agent 行为至关重要。Claude Code 虽然也有日志但粒度粗很多很多内部决策你是看不到的。2.3 迁移背后的真实驱动力我跟几个换工具的朋友聊过总结下来驱动力有三个层次。最表层的是成本。Claude Code 按用量计费重度使用一个月下来费用不低。而用 Pi 接 DeepSeek 或者其他性价比更高的模型同样的任务量成本能降不少。中间层是灵活性。大家手里的项目越来越复杂单一模型、固定工具集的方案越来越不够用需要能自己拼装的能力。最深层是工程化诉求。当 AI Coding 从个人玩具变成团队基础设施你就必须考虑可复现、可审计、可定制这些问题封闭工具天然不满足这些要求。提示迁移不是非此即彼。我现在的做法是 Claude Code 和 Pi 并存快速原型和一次性任务用 Claude Code需要反复跑、需要接入工程体系的用 Pi。工具是拿来用的不是拿来站队的。3. 核心差异拆解Harness、Agent 与模型接入的三种路线3.1 Harness 设计哲学成品 vs 框架Claude Code 和 Pi 最本质的区别在 harness 的设计哲学上。Claude Code 走的是成品路线它把 harness 的每一个决策都替你做完了你拿到的是一个调好的黑盒。Pi 走的是框架路线它只提供骨架和接口具体怎么跑你自己定。这两种路线没有绝对优劣取决于你的使用场景。如果你是一个独立开发者项目不大追求的是打开就能写代码那 Claude Code 的成品路线明显更省心。但如果你是一个团队有既定的代码规范、CI 流程、安全要求那框架路线才能让你把 AI Coding 真正嵌进去。我打个比方。Claude Code 像是一辆整车你坐进去就能开但发动机、变速箱、悬挂都是封死的你想换个轮胎规格都费劲。Pi 像是一套改装套件你得自己选发动机、自己调悬挂、自己接线但调好之后它能完全按你的需求跑。选哪个取决于你是想通勤还是想下赛道。3.2 Agent 执行循环的差异Agent 的核心是执行循环观察当前状态、决定下一步动作、执行动作、观察结果、继续循环。Claude Code 的循环是内置的你只能通过 prompt 间接影响它。Pi 的循环是开放的你可以自己写。这个差异在实际使用中影响很大。举个例子Claude Code 在处理一个跨多文件的改动时有时候会改完 A 文件就以为任务完成了忘了 B 文件还有关联改动。你没法直接干预它的循环逻辑只能重新描述需求让它继续。而在 Pi 里你可以在循环里加一个检查步骤每次 agent 声称任务完成时自动跑一遍测试或者静态检查如果没过就把它打回去继续改。这个机制一加上任务完成率明显提升。再比如错误恢复。Claude Code 遇到命令执行失败时它的恢复策略是内置的有时候会重试有时候会放弃。Pi 里你可以定义自己的恢复策略失败几次后切换模型、失败后回滚到上一个检查点、失败后把错误信息喂回给模型让它重新规划。这些策略的差异直接决定了 agent 在复杂任务上的鲁棒性。3.3 模型接入的开放度对比模型接入是这波迁移里最直接的触发点。Claude Code 只支持 Claude 系列这在 2024 年问题不大但到了现在DeepSeek 等模型在代码任务上的表现已经非常能打而且成本优势明显。很多团队想用 DeepSeek 做日常的代码生成和重构只在最复杂的任务上才切到 Claude但 Claude Code 不支持这种混合策略。Pi 这类框架天然支持多模型接入。你可以配置一个模型路由简单任务走便宜模型复杂任务走强模型特定语言的任务走专门微调过的模型。这种灵活性在规模化使用 AI Coding 的时候成本差异是数量级的。对比维度Claude CodePi 类框架模型支持仅 Claude 系列任意模型可路由工具集内置固定可自定义注册执行循环封闭不可改开放可编程上下文管理自动黑盒可配置可观测成本控制按用量单一费率可混合模型降本工程集成有限深度可定制上手成本极低中等适用场景个人快速开发团队工程化4. 实操从零搭一个 Pi Agent 工作流4.1 环境准备与安装先说安装。Pi 的安装方式取决于你用的具体实现但大体流程是类似的。以常见的 Node.js 环境为例你需要先确保本机有 Node 18 以上的版本然后通过包管理器安装。node --version npm install -g pi/agent-cli pi --version如果你用的是 Python 生态的 agent 框架流程也差不多核心是装一个 CLI 工具然后初始化一个工作目录。初始化的时候会让你选模型提供商、填 API key、选默认工具集。pi init my-agent cd my-agent初始化完成后目录里会生成一个配置文件通常叫pi.config.json或者agent.yaml里面定义了模型、工具、执行参数。这个文件是整个 agent 的核心后面所有的定制都从这里改。注意API key 不要直接写在配置文件里提交到仓库。用环境变量或者本地的 secrets 管理工具配置文件里只引用变量名。我见过太多人把 key 硬编码然后推到公开仓库后果很麻烦。4.2 模型接入配置模型接入是 Pi 最灵活的地方。配置文件里通常有一个models字段你可以定义多个模型然后给每个模型起个别名。{ models: { fast: { provider: deepseek, model: deepseek-coder, apiKeyEnv: DEEPSEEK_API_KEY }, strong: { provider: anthropic, model: claude-sonnet, apiKeyEnv: ANTHROPIC_API_KEY } }, defaultModel: fast }配好之后你可以在任务级别指定用哪个模型。比如日常的代码补全和简单重构用fast复杂的架构级改动用strong。这个路由策略可以写死在配置里也可以在执行时动态决定。我自己的策略是这样的单文件改动、格式化、写测试用便宜模型跨文件重构、理解陌生代码库、设计新模块用强模型。实测下来整体成本能降一半以上而任务质量没有明显下降。4.3 工具注册与自定义Pi 的工具注册是它区别于 Claude Code 的核心能力。工具本质上就是一个个函数agent 在执行循环里可以调用它们。内置工具通常包括读文件、写文件、执行命令、搜索代码库这些。但你可以注册自己的工具。pi.registerTool({ name: runLint, description: 对指定文件运行项目 lint 检查, parameters: { filePath: { type: string, description: 文件路径 } }, execute: async ({ filePath }) { const result await exec(npx eslint ${filePath}); return result.stdout; } });注册完之后agent 在需要的时候就会调用这个工具。比如你可以在系统提示里告诉它每次修改完代码后必须调用 runLint 检查如果有错误就修复。这样 agent 的每一次改动都会自动过一遍 lint代码质量有保障。这个能力在团队场景下价值巨大。你可以把公司内部的代码规范检查、安全扫描、依赖审计全部封装成工具让 agent 在改代码的过程中自动遵守。Claude Code 做不到这一点因为它的工具集是固定的。4.4 执行循环定制执行循环是 agent 的大脑。Pi 允许你自定义这个循环这是它最强大的地方也是最需要小心的地方。一个典型的循环大概长这样async function agentLoop(task, context) { let state initState(task); while (!state.done) { const action await model.decide(state, availableTools); const result await executeAction(action); state updateState(state, action, result); if (shouldCheckpoint(state)) { await saveCheckpoint(state); } if (state.steps MAX_STEPS) { state.done true; state.reason max_steps_exceeded; } } return state; }这段伪代码里每一个决策点你都可以插入自己的逻辑。shouldCheckpoint可以定义成每改 5 个文件存一次快照方便回滚。MAX_STEPS可以防止 agent 陷入死循环烧钱。model.decide里你可以根据当前状态动态切换模型。我踩过的一个坑是一开始没设步数上限结果 agent 在一个死循环里跑了上百步烧了不少 token 才发现。后来加了上限和检查点稳多了。所以循环定制虽然强大但一定要有兜底机制。5. 常见问题与排查技巧实录5.1 模型接入类问题问题一API 调用报错提示 response stream malformed。这个错误通常出现在流式响应解析的时候。原因可能是模型提供商的返回格式和框架预期的不一致或者网络中间有代理改写了响应。排查思路是先关掉流式模式用非流式请求测一下如果非流式正常那就是流式解析的问题。解决方法是检查框架的流式解析配置或者升级到最新版本很多这类 bug 在新版本里已经修了。问题二模型切换后行为差异很大。不同模型的 prompt 敏感度不一样。Claude 对系统提示的遵循度很高DeepSeek 可能更依赖 few-shot 示例。切换模型后如果发现 agent 不按预期调用工具先检查系统提示是不是需要针对新模型调整。我的经验是给每个模型单独准备一份系统提示模板切换的时候一起切。问题三成本失控。多模型路由如果配得不好可能所有任务都走了贵模型。排查方法是打开执行日志统计每个任务的模型调用情况。如果发现便宜模型没被用上检查路由规则是不是写错了或者任务分类逻辑有问题。5.2 工具调用类问题问题四自定义工具注册后 agent 不调用。最常见的原因是工具描述写得不够清楚。模型是根据描述来决定调不调这个工具的描述太模糊它就不敢用。解决方法是把描述写具体包括什么时候该用、输入输出是什么、有什么限制。另外可以在系统提示里显式提醒模型有这个工具可用。问题五工具执行超时。有些工具比如跑全量测试、装依赖耗时很长。如果框架有超时限制这些工具会被中断。解决方法是在工具定义里单独设置超时时间或者把长任务拆成异步执行加轮询。问题六工具返回结果太大撑爆上下文。比如搜索代码库返回了几百个文件的内容。解决方法是在工具层面做截断和摘要只返回最相关的部分。我一般会限制返回条数和每条的长度超出部分让 agent 自己决定要不要进一步查。5.3 执行循环类问题问题七agent 陷入循环反复改同一个文件。这是最典型的问题。原因通常是任务描述有歧义或者 agent 的完成判断标准不清晰。解决方法是在循环里加一个重复检测如果连续几步改的是同一个文件且改动相似就强制中断把控制权交回给人。另外把任务描述写得更具体明确完成标准也能减少这种情况。问题八agent 提前宣布任务完成但实际没做完。这是完成判断的问题。解决方法是在循环里加一个验证步骤agent 声称完成后自动跑测试或者检查清单没过就打回去。这个机制我强烈建议加上能显著提升任务完成率。问题九上下文越来越长模型开始遗忘早期信息。长任务必然遇到这个问题。解决方法是在循环里做上下文压缩定期把已完成的部分总结成简短摘要替换掉原始的长对话。或者用检查点机制每个阶段重新开始一个新的上下文只带上必要的状态。问题类型典型表现排查方向解决手段模型接入流式报错、行为差异响应格式、prompt 适配关流式测试、分模型模板工具调用不调用、超时、撑爆上下文描述质量、超时配置、返回大小写清描述、单独超时、截断摘要执行循环死循环、提前完成、遗忘完成判断、重复检测、上下文长度加验证步骤、重复检测、压缩上下文5.4 几个独家避坑技巧第一个技巧给 agent 加一个思考预算。不是限制它思考而是限制它在单步决策上花的时间。有些模型在复杂决策上会反复权衡导致单步耗时很长。设置一个合理的预算超了就让它先做一个保守选择继续往下走。实测能提升整体吞吐。第二个技巧用检查点做实验。调 agent 参数的时候不要每次都从头跑。在关键节点存检查点调参的时候从检查点恢复能省大量时间和 token。我一般会在任务开始、每个文件改完、每次测试通过这三个节点存检查点。第三个技巧日志要结构化。agent 的执行日志如果是一大坨文本排查问题很痛苦。把每一步的输入输出、模型决策、工具调用都记成结构化的 JSON排查的时候可以按字段过滤。这个投入在调试阶段回报很高。第四个技巧别追求全自动。很多人搭 agent 的时候想的是完全无人值守但实际用下来在关键决策点让人介入一下整体效率反而更高。我的做法是在 agent 准备做破坏性操作删文件、改配置、跑迁移之前暂停等我确认。这个人在环中的设计让 agent 既高效又安全。6. 我的实际使用体会与后续扩展方向用了几个月 Pi 之后我最大的体会是AI Coding 的瓶颈从来不在模型能力上而在 harness 和 agent 的设计上。同一个模型放在不同的 harness 里表现能差出好几倍。Claude Code 把 harness 做到了极致所以体验好但它不让你改所以天花板也明显。Pi 这类框架把 harness 开放出来给了你更大的空间但也要求你承担更多的设计责任。如果你现在还在用 Claude Code 且用得很顺没必要为了迁移而迁移。但如果你开始遇到想改但改不动的情况或者团队要把 AI Coding 接入工程体系那 Pi 这类框架值得认真看看。上手成本确实比 Claude Code 高但一旦搭好它能跟着你的需求一起长。后续我打算在这个方向上继续折腾两件事。一是把 agent 的执行日志接到可观测平台上做长期的性能和质量监控看看哪些任务类型 agent 表现好、哪些还需要人工兜底。二是探索多 agent 协作让一个 agent 负责写代码、一个负责审查、一个负责跑测试互相制衡。这两个方向都还在早期等有成熟经验了再单独写一篇分享。