Code Agent 应如何选择 whole、diff 和 SEARCH/REPLACE 编辑格式？

Code Agent 的编辑格式不是单纯的输出样式，它决定模型要重复多少文件内容、工具怎样定位目标、失败是否可解释，以及多文件变更能否稳定应用。whole、SEARCH/REPLACE 和统一补丁各有适用范围。选择时应结合文件大小、修改密度、模型格式遵循能力与错误代价，而不是默认一种格式处理所有任务。

先澄清 Aider 中的格式名称

Aider 官方文档把返回完整文件的方式称为 whole，把一组 SEARCH/REPLACE 块称为 diff。后者使用类似合并冲突的 SEARCH、分隔线和 REPLACE 标记，并不是标准 git unified diff。

接近统一补丁的格式叫 udiff，它是在常见 unified diff 基础上的简化版本。另有 diff-fenced，将文件路径放进代码围栏，主要用于更适应该格式要求的模型。editor-diff 与 editor-whole 则用于 architect 模式，格式主体相同，但提示更专注于执行已经确定的编辑计划。

whole：最简单的完整文件输出

whole 要求模型返回每个待修改文件的完整新版本。工具无需匹配旧片段，只要识别路径和围栏内容即可写入。对新文件、小型配置和短脚本，它具有最低的协议复杂度。

代价是输出量与文件长度相关，而不是与改动大小相关。只改一行也要重新生成整个文件，既增加 Token 和延迟，也可能遗漏模型没有注意到的原内容。文件越长，截断、占位注释和无关格式变化的风险越高。

whole 适合文件很短、改动覆盖大部分内容，或者目标模型难以稳定生成差异格式的情况。写入前应确认文件版本没有变化，写入后用 diff 检查未计划删除与重排。

SEARCH/REPLACE：局部编辑的常用选择

SEARCH/REPLACE 块让模型分别给出当前文件中的旧内容和替换后的新内容。工具定位唯一旧块后进行局部替换，因此输出只与变更区域大小相关。Aider 的 diff 格式采用的就是这种契约。

它适合修改一个函数、添加导入、更新条件或在明确锚点附近插入代码。旧块本身既是定位信息，也是并发保护：文件内容变化导致无法匹配时，工具可以拒绝应用。

主要风险是模型没有逐字复制真实内容。缩进、空格、引号或注释差异会导致未匹配；旧块出现多次则产生歧义。错误反馈应展示最接近的实际片段，而不是自动选择第一个候选。

udiff：适合紧凑的结构化补丁

udiff 用文件头、上下文和加减行描述变更，能高效表达同一文件多处修改和跨文件重构。对于熟悉补丁结构的模型，输出紧凑，审阅方式也接近版本控制。

Aider 文档说明 udiff 曾主要用于 GPT-4 Turbo 系列，因为这些模型使用其他格式时容易省略大段代码，并留下“原代码放这里”一类占位注释。统一补丁只输出必要上下文，可减少让模型重建完整文件的诱因。

但补丁格式要求更高。文件头、区块边界、上下文行和加减号必须一致，行号或上下文漂移也会使应用失败。模型未经相应提示或示例训练时，格式错误率可能高于 SEARCH/REPLACE。

diff-fenced 为什么存在

有些模型经常把文件路径放错到围栏外或丢失围栏边界。diff-fenced 与 SEARCH/REPLACE 语义相同，只是把路径也放进代码围栏。Aider 官方文档称它主要用于 Gemini 系列的格式适配。

这说明最佳格式取决于模型，不只是工具算法。同一编辑语义通过不同包装呈现，模型遵循率可能显著变化。Agent 框架应允许按模型配置默认格式，并通过真实任务评测，而不是假设所有模型对标记同样敏感。

文件规模如何影响选择

短文件中，whole 的额外输出很小，简单协议可能比差异解析更稳。长文件只改几行时，SEARCH/REPLACE 或 udiff 明显更高效，也减少无关区域被重写。

但长文件中的目标片段可能重复。SEARCH/REPLACE 需要加入函数签名和邻近上下文保证唯一，区块过大又会提高复制漂移概率。udiff 可用多个较小区块分别定位，但要保证整体事务性。

改动密度如何影响选择

若修改覆盖文件大部分内容，例如重写生成器或迁移配置结构，whole 可能比几十个碎片化替换更清楚。若只改少数局部，差异格式更合适。

跨文件重命名通常应使用支持原子提交的补丁或多编辑工具。多个独立 SEARCH/REPLACE 顺序执行时，前半成功、后半失败会留下不一致状态。工具应先预检全部区块，再一起写入。

模型能力如何影响格式

强推理能力不等于稳定遵循编辑协议。有些模型擅长规划，却会漏掉围栏或补丁标记；有些快速模型能机械生成格式，但不适合决定复杂重构。模型选择与格式选择应分别评估。

可以建立小型回归集，覆盖新增文件、单点修改、多点修改、跨文件变更和故意漂移。统计首次可解析率、首次应用率、最终正确率、输出 Token 和重试次数，再为每个模型选默认格式。

architect 模式为何拆分规划和编辑

architect 模式让较强模型先用自然语言决定改什么，再由 editor 模型把计划转换成 diff 或 whole。editor-diff 和 editor-whole 使用更窄的提示，只关注文件修改，不再重新解决整个任务。

这种职责分离能减少规划模型同时承担推理和严格格式输出的负担，也允许使用不同成本的模型。但计划必须明确到文件、符号、约束和验收条件，否则 editor 只能猜测。

两阶段增加一次模型调用，不适合简单一行修改。复杂多文件任务中，如果它显著降低格式失败和返工，总成本仍可能更低。

怎样建立选择规则

• 创建新文件或重写短文件时优先 whole。
• 一个文件中的少量明确修改优先 SEARCH/REPLACE。
• 跨文件或多区块变更使用原子 patch 或 udiff。
• 模型经常错放路径时采用适配围栏格式。
• 复杂任务可先规划，再由 editor 输出差异。
• 格式连续失败时根据错误切换，不盲目重复。

失败后应如何回退

格式解析失败时，应返回缺失标记、出错区块和期望语法，让模型修复协议。目标文本未匹配时，应返回实际候选和行号。不要把两类错误混为“编辑失败”，否则模型无法选择正确恢复动作。

SEARCH/REPLACE 因轻微漂移失败，可以重新读取并精确重试；多个区块频繁失败时可切换原子补丁；短文件在差异协议持续失败时可回退 whole。长文件不应因一次失败直接整文件覆盖。

验证比格式更重要

任何格式成功应用都只代表文本操作完成。系统仍需重新读取 diff、运行语法和类型检查，再运行相关测试。whole 要特别检查无关删除，模糊替换要检查缩进与标点，patch 要检查所有文件是否一起提交。

验证应基于真实工作树，不依赖模型的完成声明。若工具支持版本控制快照，可以在失败时回滚本次事务，同时保留用户原有未提交修改。

如何衡量格式的真实成本

输出 Token 只是成本的一部分。一个非常紧凑但经常解析失败的格式，经过多次重试可能比 whole 更贵。应统计从首次生成到验证通过的总输入输出、工具调用、延迟和人工介入。

最重要指标是每次正确编辑成本。正确意味着目标行为通过测试、无无关文件变化，并满足 diff 范围。只比较一次响应长度会高估紧凑格式的优势。

常见误区

第一，Aider 的 diff 不等于标准 unified diff，它实际是 SEARCH/REPLACE 块。第二，whole 的简单不代表总是安全，完整重写可能丢内容。第三，udiff 的高效率依赖模型格式能力和应用器实现。

第四，强制所有模型使用相同格式未必带来一致性。官方文档明确指出不同模型对格式表现不同，并为常见模型配置合适默认值。自定义模型应通过基准选择，而不是照搬名称相近模型的配置。

结论

whole 以高输出成本换取协议简单，适合新文件和短文件重写；Aider 的 diff 使用 SEARCH/REPLACE，适合局部、唯一目标；udiff 更紧凑，适合模型能够稳定生成的多区块和跨文件变更。

格式选择应由文件规模、改动密度、模型遵循能力和失败代价共同决定。再配合原子提交、结构化错误和写后验证，才能把编辑格式从提示技巧变成可靠工程契约。