apply_patch 是什么？agent 改文件的底层机制

让 AI 助手帮你改代码，它并不是像人一样打开编辑器逐字敲。多数 coding agent 动手改文件走的是补丁路线：先把改动意图写成一份结构化补丁——在哪个文件、删哪几行、加什么内容——再交给一个专门的应用器落到磁盘上。apply_patch 就是这道应用工序的名字。理解它，才能明白 agent 改文件为什么会卡在审批、为什么偶尔改坏、以及验证改动该看哪里。这篇拆开讲：补丁长什么样、一份补丁的完整旅程、审批循环与失败重试的来龙去脉，以及怎么配合 git diff 把验收做扎实；沙箱在哪一层拦下文件操作，见沙箱拦截排查一篇。

从描述改动到落盘：补丁的基本形状

agent 决定改文件时，输出的中间产物是一段补丁文本：声明目标文件路径，列出要删除的原文行与要插入的新行，形式上接近开发者熟悉的 diff。这种设计的好处是改动可审可回滚——补丁是一份改动说明书，人在审批时看到的正是这份说明书，而不是一句模糊的「我要改点东西」。应用器拿到补丁后按行匹配原文，匹配得上就替换，匹配不上就报失败。补丁的粒度也可大可小：小到改一个变量名，大到新建一整个文件，都走同一套表达。它和代码补全那种「原地续写」是两种机制，两者的边界在插件与命令行一篇有对照。

一份补丁的完整旅程：生成、审批、落盘

完整走一遍流程，一共四步。第一步生成：模型根据任务与当前代码上下文产出补丁文本。第二步展示：补丁连同受影响的文件路径呈现给你，等待批准或拒绝——要不要问、问多细，由审批模式决定，模式之间的升级逻辑见审批模式升级一篇。第三步应用：批准后，应用器按补丁内容在磁盘上执行增删改。第四步验证：agent 通常紧接着跑一次 diff 或测试，确认改动符合预期。四步里任何一步出问题，改动都不会发生——这是补丁机制相对直接写文件的安全垫，执行层的隔离依托，见沙箱机制一篇的拆解。

审批循环与失败重试：卡住时发生了什么

两个高频现象值得单独说。一是审批循环：补丁被拒绝后，agent 常常重新生成一份再提交；如果拒绝的原因没有传达清楚，就会出现生成、提交、拒绝、再生成的循环。这个现象在部分版本里被报告过回归（截至发稿版本，以官方更新日志为准）：审批被拒后 agent 不理解原因，反复换着花样打补丁。二是失败重试：补丁与原文匹配不上——比如文件在你审阅期间被手动改过——应用就会失败，agent 收到失败信息后通常带着上下文重试；连续失败到上限，会以类似 exceeded retry limit 的报错收场。两种情况的处理思路一致：回到对话里把原因说清楚，或者手动把文件恢复到 agent 预期的状态，再让它重打补丁。

用 git diff 验证：核对动作别省

补丁机制给验证留了天然的落点：每笔改动都有据可查。agent 应用补丁后，你用 git diff 一眼能看到全部落盘改动，逐行核对再决定是否提交，这是最可靠的验收动作。Git 盲区问题在此同样适用：工具链对未跟踪文件的可见性有边界，新建的文件先 git add 再走验证，细节见Git 盲区与 .env一篇。习惯上还有两条：重要改动让 agent 先出补丁预览再应用，别跳过审批直通；发现改坏时别在坏结果上继续叠补丁，先恢复原状再重新描述需求。动手建立手感，可以让 DeepSeek 把一段真实补丁的格式逐行讲成大白话，再用豆包复盘一次「补丁被反复拒绝」的对话，找出循环的成因。

apply_patch 速查

• 定位：agent 改文件的落盘工序，先出补丁再应用
• 四步：生成、审批、应用、验证，缺一步改动不发生
• 审批循环多因拒绝原因没传清，回对话说清再重试
• 补丁匹配不上会重试，连续失败以超限报错收场
• 验收靠 git diff 逐行核对，新文件先 git add

apply_patch 快问快答

• 拒绝补丁后 agent 反复重发怎么办？：多数是拒绝原因没传达到位。拒绝时顺手说一句为什么——路径不对还是方案不对——agent 会带着原因重打补丁，循环立刻断掉。
• 补丁应用失败会留下半成品吗？：规范的应用按整体处理，匹配失败就不落盘；个别实现可能已应用部分改动，用 git diff 一查便知，需要时整体恢复原状。
• 为什么有时改文件不弹审批？：审批粒度由模式与配置决定，低风险改动在部分模式下直接放行，文件系统层的隔离仍然生效，两层机制别混为一谈。