模型不直接改代码：AI 编程工具的文件修改机制

很多人第一次使用 AI 编程工具时，都会有一个很自然的感觉：

我说一句“帮我修一下这个 bug”，模型就把代码改好了。

于是很容易产生一个误解：
是不是大模型直接打开了我的文件，然后自己把代码写进去了？

答案是：不是。

大模型并不会直接操作你的磁盘。真正修改文件的，是运行在你本地的 AI 编程客户端。

模型负责“决定怎么改”。
工具负责“确认能不能改、怎么改、如何安全写入”。

这篇文章，我们就拆开看看：AI 编程工具到底是怎么把一句自然语言，变成一次真实的代码修改。

一、模型返回的不是文件，而是工具调用

当你对 AI 说：

帮我把这个函数里的空指针问题修一下。

模型通常不会直接返回“我要修改你的磁盘文件”。它更可能返回一个结构化的工具调用。

比如类似这样：

{
  "tool": "Edit",
  "input": {
    "file_path": "/project/src/user.ts",
    "old_string": "const name = user.profile.name",
    "new_string": "const name = user.profile?.name ?? ''"
  }
}

这段内容可以理解成：

模型建议调用 Edit 工具，把某个文件中的一段精确文本替换成另一段文本。

注意，真正执行替换的不是模型，而是客户端。

客户端收到这个 tool_use 以后，会去做参数校验、权限判断、文件读取、文本匹配、写入磁盘，然后把执行结果再告诉模型。

所以，AI 编程工具的代码修改，本质上是：

模型提出修改意图
  ↓
客户端验证修改是否安全
  ↓
本地工具执行文件操作
  ↓
执行结果返回给模型

二、为什么不能让模型直接写文件？

因为太危险。

模型生成文本很强，但它不是文件系统。

如果让模型直接改文件，会有几个问题：

第一，它可能改错路径。

第二，它可能覆盖用户刚刚手动改过的内容。

第三，它可能把一个匹配多处的字符串改到错误位置。

第四，它可能用不完整的上下文重写整个文件。

第五，它可能通过命令行做出难以审计的副作用。

所以成熟的 AI 编程工具通常不会让模型“自由写文件”，而是提供受控工具。

常见工具有几类：

• Read：读取文件
• Edit：精确替换文件中的一段文本
• Write：创建或覆盖整个文件
• ApplyPatch：按补丁修改一个或多个文件
• Bash：执行命令，通常权限更严格

模型只能调用这些工具。工具怎么执行，由客户端代码决定。

这就是安全边界。

三、最常见的修改方式：精确替换

很多 AI 编程工具最核心的修改方式不是“重写文件”，而是“精确替换”。

也就是让模型提供：

old_string：原来的代码片段
new_string：新的代码片段

工具会先打开文件，确认 old_string 是否真的存在。

如果不存在，修改失败。

如果存在多次，但模型没有明确说要全部替换，修改也会失败。

为什么这么设计？

因为这能避免很多危险的误改。

假设文件里有三处：

return null

模型如果只说把 return null 改成 return []，工具并不知道应该改哪一处。

这时候最安全的做法不是猜，而是失败，并提示模型：

匹配到多处，请提供更多上下文，或者明确 replace_all。

于是模型下一轮会重新构造更长的 old_string，比如带上前后几行代码。

这就是为什么你有时会看到 AI 先改失败，然后自己重新读文件、重新编辑。

它不是“笨”，而是工具在保护文件。

四、为什么 Claude Code 要求先 Read 再 Edit？

Claude Code 这类工具有一个很关键的约束：

修改已有文件之前，必须先读取文件。

这非常重要。

因为如果模型没有读过当前文件，它就不知道文件的真实内容。它可能基于历史上下文、README、报错片段，甚至自己的猜测来构造修改。

先 Read 的好处有三个。

第一，确保模型基于真实内容修改。

工具读到文件以后，模型才能知道函数在哪里、缩进是什么、上下文是什么。

第二，确保 old_string 能精确匹配。

Edit 工具通常要求 old_string 和文件内容完全一致，包括空格、换行、缩进。

第三，防止文件中途被改。

客户端会记录读取时的文件状态。等到真正写入时，会检查文件是否在这期间发生变化。

如果用户手动改了文件，或者格式化器、linter 改了文件，工具会拒绝写入，并提示重新读取。

这就是所谓的“防止基于过期内容写入”。

五、完整的文件修改流程是什么样？

可以用一张流程图理解：

用户提出修改需求
  ↓
模型判断需要看代码
  ↓
调用 Read / Grep / Search
  ↓
客户端返回文件内容
  ↓
模型构造 Edit / Write / Patch 调用
  ↓
客户端校验参数 schema
  ↓
检查路径和权限
  ↓
检查文件是否已读、是否被修改
  ↓
执行精确替换或写入
  ↓
生成 diff / tool_result
  ↓
把结果作为上下文再发给模型
  ↓
模型继续解释、修正或运行测试

用户看到的是“AI 改好了代码”。

底层其实经历了多次判断和校验。

六、OpenCode 和 Claude Code 的差异

不同工具实现细节不一样，但大方向相同。

OpenCode 提供了比较直接的几个文件修改工具：

• edit：精确替换一个文件中的文本
• write：写入一个文件
• apply_patch：按 patch 顺序执行新增、修改、删除

它的重点是：

• 路径解析
• 权限确认
• 精确匹配
• 文件未变化检查
• patch 顺序应用

Claude Code 的实现更产品化一些。

它除了 Edit 和 Write，还会处理：

• 必须先 Read
• 文件大小限制
• 权限规则
• 文件是否在读取后被修改
• file history
• LSP 通知
• VSCode diff 通知
• hooks
• 工具执行日志
• 用户批准或拒绝

所以可以简单理解：

OpenCode 更像清晰的工具内核。
Claude Code 更像完整的产品级执行系统。

但它们的核心原则是一致的：

模型不直接改文件，模型只提出工具调用；客户端工具负责真正落盘。

七、为什么有时 AI 会选择 Write，而不是 Edit？

Edit 适合小范围修改。

比如：

• 改一个函数
• 补一段判断
• 替换一个变量名
• 删除几行重复代码

Write 适合：

• 创建新文件
• 完整重写一个小文件
• 生成配置文件
• 生成测试文件

但如果是已有大文件，直接 Write 风险更高。

因为 Write 是整体覆盖，一旦模型遗漏某些内容，就可能造成代码丢失。

所以成熟工具的 prompt 通常会告诉模型：

修改已有文件优先用 Edit。
只有创建新文件或完整重写时才用 Write。

这不是风格问题，而是安全策略。

八、为什么不推荐让模型用 sed、awk、cat 改文件？

很多人会想：既然有 Bash，直接让模型执行：

sed -i 's/old/new/g' file.ts

不就行了吗？

问题是，这类命令对 AI 来说不够安全。

它们通常有几个缺点：

• 不容易展示结构化 diff
• 不容易做文件状态检查
• 不容易判断是否基于最新读取内容
• 命令转义容易出错
• 跨平台兼容性差
• 审计和权限控制更困难

所以很多 AI 编程工具会在系统提示中明确要求：

编辑文件用 Edit，不要用 sed/awk。
创建文件用 Write，不要用 cat 重定向。

这背后的原因不是模型不会写 shell，而是专用工具更可控、更可审计。

九、一次失败的 Edit，反而是好事

你可能见过这种情况：

AI 先尝试编辑，失败了。
然后它又读取文件，重新编辑，最后成功。

这不一定是坏事。

常见失败原因有：

• old_string 没有精确匹配
• 文件被用户改过
• 匹配到了多处
• 文件没有先读
• 路径不在允许范围内
• 权限需要用户确认

这些失败，说明工具系统在工作。

一个没有保护的工具，可能会悄悄改错文件。
一个有保护的工具，会宁可失败，也不轻易写入。

对代码修改来说，失败可恢复，误改才麻烦。

十、给使用者的建议

如果你希望 AI 修改代码更稳定，可以这样提问：

请先读取相关文件，再做最小范围修改，不要重写无关代码。

如果你担心它误改，可以加：

修改前先说明将改哪些文件，修改后给出 diff 摘要。

如果你希望它更像工程师，可以说：

优先使用精确替换，不要通过 shell 命令批量改文件，除非确实需要。

如果是复杂需求，可以要求：

先定位调用链，再只修改主路径相关代码，最后运行测试验证。

这些提示的目的不是教模型写代码，而是约束它的执行方式。

结尾

AI 编程工具修改代码，并不是模型拥有了你的文件系统。

真正的机制是：

模型负责判断
工具负责执行
客户端负责安全边界
上下文负责连接前后步骤

所以，当你看到 AI “自动改好了代码”，背后其实是一套工程化流程：

读取 → 理解 → 构造修改 → 校验 → 写入 → 返回结果 → 继续推理

理解这一点以后，你就会更清楚地知道：

为什么它有时要先读文件。
为什么它有时会编辑失败。
为什么它不应该直接用命令行乱改。
为什么好的 AI 编程工具一定要有权限、diff 和文件状态检查。

模型生成的是意图。
工具落下的，才是代码。