AI Agent 工程师 Day 52：Code Editing：LLM 如何可靠修改代码

2026-11-10

AI Agent 工程师 Day 52：Code Editing：LLM 如何可靠修改代码

6 个月学习计划 | M2 - Agent Harness + Tool + Environment | Day 52/168

今日主题: 代码编辑策略

Code Editing：LLM 如何可靠修改代码

核心结论：LLM 写新代码相对可靠，但修改已有代码是一等难题。工程实践中主流有三种编辑策略：全文件重写、补丁、搜索替换，没有绝对最优解，只有按上下文长度、文件大小、模型能力、验证手段做出的权衡取舍。行业的演化路径很清晰：从早期 Claude 的全文件重写，到 Aider 的 Search & Replace 标注格式，再到 OpenAI 的 unified diff、Claude Code 的 Edit 工具——每一次迭代都在解决同一个问题：让模型输出的“意图”和实际落盘的“修改”之间的损耗最小。本文讲清三种策略的因果链、失效模式，以及如何用 diff + 验证闭环兜底。

一、背景与动机：为什么这是 Agent 的“手部精细动作”

在 AI Agent 工程师的成长路径中，前几周你已经学会了 Tool Use、ReAct 循环、文件读写（Read/Write）。Write 是“造物”，Edit 是“手术”。一个 Coding Agent（编程智能体）90% 的真实工作不是从零写项目，而是在百万行存量代码里做精准修改——改一个 bug、加一个字段、重构一个函数。

如果 Edit 不可靠，Agent 会陷入“改一处、坏三处”的循环：模型认为自己改好了，实际文件被截断、缩进错了、改错了位置，然后它在错误的状态上继续推理，错误滚雪球。这就是为什么 edit 工具的设计质量直接决定 Coding Agent 的成功率下限——模型能力再强，落盘这一步丢精度，全盘皆输。

类比理解：Write 像打印一张新纸，Edit 像外科手术。手术需要的是定位（找到正确位置）+ 切除/��换（精确操作）+ 缝合验证（确认伤口愈合）。本文的三种策略，本质上是三种不同精度的“手术方案”。

二、三种编辑策略：全文件重写、补丁、搜索替换

2.1 概念对照表（先给全景）

维度	全文件重写	统一补丁	搜索替换
英文术语	Full File Rewrite	Unified Diff / Patch	Search & Replace
模型输出量	O(文件大小)	O(修改量)	O(修改量)
token 成本	高	低	低
定位可靠性	无需定位（整个文件都是答案）	依赖行号	依赖唯一匹配
典型失效模式	截断、幻觉性丢代码、行数限制	行号漂移	匹配失败、多处匹配
容错难度	天然容错（整体覆盖）	需 fuzzy match	需匹配策略
代表系统	早期 Claude、Cursor 早期	OpenAI Codex 系列	Aider、Claude Code

2.2 全文件重写：简单粗暴但贵

因果链：模型看到完整文件 → 在上下文中重建整个文件 → 输出修改后的完整内容 → 系统直接覆盖写入。

优点非常直白：不需要“定位”这个环节，一切定位错误、上下文错位问题都不存在，因为模型输出的就是最终态。这也是它成为最早期方案的原因——工程实现零复杂度，一个 Write 工具就够。

但失效模式同样直白：

成本爆炸：改一个 2000 行文件里的一行代码，输出 2000 行。输出 token 比输入还贵，且慢（输出是逐 token 生成的）。
截断（Truncation）：max_tokens 限制下，长文件输出到一半被掐断，后一半代码直接丢失。这是早期 Cursor 用户“我的文件只剩一半了”投诉的根源。
幻觉性丢失：模型在重建长文件时会“偷懒”或遗忘，把不相关的函数默默删掉、简化，产生静默回归。

工程直觉：全文件重写只适合小文件（<200~300 行）或新文件创建。文件越大，重写的期望损失越大。

2.3 Unified Diff / Patch：精确但脆弱

因果链：模型输出标准 unified diff 格式（--- / +++ / @@ -l,c +l,c @@），系统调用 patch 逻辑应用。

--- a/utils.py
+++ b/utils.py
@@ -10,7 +10,7 @@
 def calculate_total(items):
     total = 0
     for item in items:
-        total += item.price
+        total += item.price * item.quantity
     return total

优点：token 成本 O(修改量)，diff 本身就是天然的变更审计记录，可以直接喂给验证和 review 流程。

致命弱点：行号漂移。hunk 头 @@ -10,7 中的行号是模型根据它“看到的”文件版本计算的。如果模型读的版本和磁盘版本之间有任何偏差（之前一次编辑没生效、文件被外部修改、模型数错行），patch 会应用失败或应用错位置。OpenAI 的 Codex 类产品用这个方案，靠的是模型足够强 + 服务端有 fuzzy matching 兜底。

2.4 Search & Replace：当前的主流解

因果链：模型输出“要找的原文 + 替换后的新文”，系统在文件中做精确字符串匹配，找到后替换。Aider 的 SEARCH/REPLACE 块和 Claude Code 的 Edit 工具都是这个范式。

<<<<<<< SEARCH
        total += item.price
>>>>>>> REPLACE
        total += item.price * item.quantity

为什么它胜出？关键洞察：用内容本身做锚点，替代行号做锚点。行号是模型容易算错的“间接引用”，而原文内容是模型直接从上下文复制的“直接引用”，复制比计算可靠得多——尤其是当 Edit 工具要求 SEARCH 块逐字精确匹配（包括缩进）时，模型复制的错误率很低。

但它的失效模式也很有代表性，恰恰构成了你实践练习的核心：

失效模式	原因	解法
匹配失败	模型凭记忆写 SEARCH 块，与实际文件不符	强制先 Read 再 Edit；失败时返回实际文��片段给模型重试
多处匹配	目标片段在文件中出现多次	要求提供更多上下文行保证唯一性；或 fail-fast 报错
缩进/空白差异	Tab vs 空格、尾随空格	匹配时做 whitespace 归一化（谨慎使用）
重复编辑同一文件时旧内容过期	前一次编辑改变了文件，模型的上下文缓存已失效	每次编辑后让工具返回新的关键片段

2.5 edit_file 的三种操作：replace / insert / delete

工程上，一个 edit_file 工具通常收敛为三个原子操作，各自需要不同的实现策略：

def edit_file(path: str, op: str, anchor: str = None, 
              old: str = None, new: str = None) -> str:
    content = read(path)
    
    if op == "replace":
        # 精确匹配 anchor/old，替换为 new
        count = content.count(old)
        if count == 0:
            return f"ERROR: not found. Nearby content:\n{snippet_near(content, anchor)}"
        if count > 1:
            return "ERROR: multiple matches, provide more context"
        return write(path, content.replace(old, new, 1))
    
    elif op == "insert":
        # 在 anchor（锚点文本）之后插入 new
        if anchor not in content:
            return "ERROR: anchor not found"
        return write(path, content.replace(anchor, anchor + "\n" + new, 1))
    
    elif op == "delete":
        # 找到 old 块并删除（连同其独占的换行）
        if content.count(old) != 1:
            return "ERROR: match count != 1"
        return write(path, content.replace(old + "\n", "", 1))

注意两个设计细节背后的因果：

错误信息要“可行动”：匹配失败时不只说 “not found”，而是返回锚点附近的真实文件内容，模型下一轮就能用正确原文重试。这是 Agent 错误恢复设计的关键模式——错误信息本身是给模型看的提示词。
insert 用锚点而非行号：insert_at_line(42) 看似简单，但一旦文件在两次工具调用间发生变化，42 就不再是你想要的行。文本锚点天然抗漂移。

三、可靠性的根因分析：为什么 LLM 改代码容易错

把失效模式往上抽象，可靠性问题的根因有三个层次：

上下文保真度：模型对文件内容的认知来自上次 Read。任何“模型认为的文件”与“磁盘上的文件”的偏差都会传导为编辑错误。所以 Coding Agent 的铁律是：编辑前必须重新读取，编辑后立即验证。
生成式输出的精度极限：LLM 是采样生成的，不是查表复制。让它重产出 2000 行，每行都有独立的出错概率，错误率随长度累积；让它只产出 5 行 SEARCH/REPLACE，错误面收窄到修改本身。
缺少反馈闭环：单次编辑没有 ground truth。没有 diff 检查、没有编译/lint/测试，模型和系统都不知道改坏了。可靠性不是靠模型“更小心”实现的，是靠验证闭环实现的。

工程公式化表达：

1	编辑可靠性 ≈ P(定位正确) × P(内容正确) × P(验证通过后止损)

三种策略分别在不同因子上发力：Search & Replace 拉高 P(定位正确)，缩小输出拉高 P(内容正确)，diff + 测试闭环保证 P(验证)。

四、Diff 与验证：最后的防线

无论用哪种策略，落盘前都应过两道检查：

1. Diff 生成与审查

import difflib

def apply_and_diff(path, new_content):
    old_lines = read(path).splitlines(keepends=True)
    new_lines = new_content.splitlines(keepends=True)
    diff = "".join(difflib.unified_diff(old_lines, new_lines, 
                                        fromfile=path, tofile=path))
    # 把 diff 返回给 Agent，供其自检 + 记录审计日志
    write(path, new_content)
    return diff

把 diff 回传给模型不只是审计需要——模型看到自己的实际改动后，能发现“咦，我不小心删了整��函数”这类静默错误。这相当于给 Agent 装了后视镜。

2. 程序化验证（分层兜底）

验证层	手段	成本	拦截的问题
语法层	AST parse / 编译	极低	截断、括号不闭合
静态层	lint / type check	低	引用不存在的变量
行为层	跑相关测试	中	逻辑错误、回归
Agent 自检	把 diff + 报错回喂模型	低	各类

实践中至少要做语法层：一次截断编辑 100% 能被 AST parse 拦截，成本几乎为零。验证失败时把具体报错回给模型重试——这就是 Agent 的自我修复循环。

1
2
3

Read ──► Edit(策略选择) ──► Diff 检查 ──► AST/测试验证 ──► 通过则继续 / 失败则带错误重试
                ▲                                                    │
                └────────────── 错误信息回流（最多 N 轮）◄────────────┘

五、策略选择的工程决策树

新文件 or 文件 < ~200 行？
├── 是 → 直接 Write（全文件重写）
└── 否 → 模型支持原生 diff 输出且服务端有 fuzzy apply？
        ├── 是 → Unified Diff
        └── 否 → Search & Replace（强制先 Read，失败带上下文重试）
                  └── 连续失败 2 次 → 降级为全文件重写（小文件时）

最后一条很重要：没有银弹。工程上常见做法是策略级联——Search & Replace 连续失败说明模型对文件状态的认知已经腐化，此时重读整个文件、甚至重写，反而是止损最快的路径。

六、实践练习与思考题

练习：实现上文骨架的 edit_file 工具，构造三个测试文件分别触发三种失效模式（不存在的原文、多处匹配、跨多次编辑后内容过期），观察错误信息设计如何影响模型的重试成功率。如果你的环境里有 LLM API，让模型先 Read 再 Edit，统计一次通过率 vs 盲改的一次通过率。

思考题：

为什么“要求 SEARCH 块逐字精确匹配”反而比“模糊匹配”在整体系统上更可靠？（提示：考虑静默错误的代价 vs 显式失败后重试的代价）
如果 Agent 需要连续做 10 处编辑，每次编辑后是否应该把整个文件重新回传给模型？token 成本和信息时效如何平衡？
全文件重写的截断问题，能否用“输出前先让模型声明目标行数”来检测？这个方案的漏洞在哪？

七、与 Agent Engineering 的关联

这个知识点是 Coding Agent 的核心基建，但对所有 Agent 都有迁移价值：

工具错误信息 = 提示词。本讲的”not found + 附近内容”模式适用于一切 Agent 工具：数据库工具的查询失败应返回相似表名，API 工具应返回参数 schema。Agent 的自我修复能力，一半来自工具错误的设计质量。
状态一致性是 Agent 系统的头号敌人。模型认知中的世界状态和真实世界状态的偏差（文件过期、数据库已变、页面已刷新），是 Agent 错误的最大来源。Edit 工具只是这个问题最尖锐的战场。
缩小输出面 = 提高可靠性。这个原则同样适用于结构化输出、SQL 生成、配置修改：永远让模型输出最小必要的变更，而不是重建整个对象。

学完本讲，你具备了搭建一个最小编程 Agent（read → edit → verify 循环）的全部零件，这是 M3 阶段多 Agent 系统和真实工程实践的前置条件。

FAQ

Q1：为什么 Claude Code / Aider 都放弃了全文件重写？
A：不是完全放弃，而是把它降级为小文件的兜底方案。核心原因是成本和截断：长文件重写输出 token 爆炸且易被 max_tokens 掐断，产生静默丢代码——这种错误用户极难发现，代价太高。

Q2：Search & Replace 匹配失败该怎么办？
A：分三步：失败时返回锚点附近真实文件内容 → 模型用正确原文重试 → 连续失败则强制重新 Read 或降级为重写。禁止系统端做激进的模糊匹配静默通过——显式失败重试的代价远小于改错位置的代价。

Q3：行号定位（line-based edit）为什么被淘汰？
A：行号是间接引用，模型需要自己数行，且文件在多次编辑间会漂移。内容锚点是直接引用，复制原文比计算行号可靠一个数量级。少数系统（如某些 OpenAI 端点）仍用行号，但都配了 fuzzy matching 兜底。

Q4：编辑后一定要跑测试吗？
A：理想是，现实要分层。至少做语法层验证（AST/编译），成本近零且能拦住截断类灾难性错误；测试在改动涉及逻辑时再触发，避免每轮编辑都跑全量测试的延迟爆炸。

Q5：如何防止模型“顺手法”删掉不相关代码？
A：靠 diff 回审。每次编辑生成 unified diff 并回传给模型自检，同时写入审计日志。全文件重写场景下，还可以对比新旧文件行数/AST 结构，发现超预期的删除时要求模型确认。

参考资料

Aider 官方博客：Unified diffs make GPT-4 138% less lazy（diff 策略与模型懒惰问题的经典分析）
Aider 官方文档：Search/Replace 格式设计说明（aider.chat/docs/more/edit-formats.html）
Anthropic 文档：Claude Code 的 Edit 工具设计（逐字匹配、先读后写约束）
OpenAI Codex 产品文档：基于 diff 的代码应用机制
SWE-bench 论文及排行榜（不同编辑策略下 Agent 成绩的实证对比）

📋 本日知识点清单

Full File Rewrite vs Patch vs Search & Replace 的对比
edit_file 的 replace/insert/delete 操作
LLM 修改代码的可靠性问题
不同编辑策略的优缺点
代码修改的 diff 与验证

📝 实践练习

实现 edit_file，对比 3 种编辑策略的问题和效果。

本文是「AI Agent 工程师」6 个月学习计划的一部分。学习路线：LLM → Inference → Runtime → Harness → Memory → Environment → Evaluation → Production。目标：Agent / AI Systems Engineer。