FileEditTool：编辑文件

这个工具解决的不是“能改文件”，而是“怎么安全地改”

FileEditTool 负责对已有文件做定点修改。
在 Claude Code 里，它的价值从来不只是“替换一段字符串”，而是：

• 先确认文件读过
• 再确认文件没被别人改过
• 再确认当前编辑权限允许
• 最后才生成 patch 并写回

也就是说，FileEditTool 体现的是 Claude Code 的受控编辑模型。

看源码，它的依赖明显比想象中重

tools/FileEditTool/FileEditTool.ts：

import { countLinesChanged } from '../../utils/diff.js'
import { fetchSingleFileGitDiff } from '../../utils/gitDiff.js'
import { checkWritePermissionForTool } from '../../utils/permissions/filesystem.js'
import { readFileSyncWithMetadata } from '../../utils/fileRead.js'
import { getPatchForEdit } from './utils.js'

这些导入已经说明它不是一个简单替换器，而是同时关注：

• diff
• Git 视角
• 权限
• 文件元数据
• patch 生成

先看工具本体定义

export const FileEditTool = buildTool({
  name: FILE_EDIT_TOOL_NAME,
  searchHint: 'modify file contents in place',
  strict: true,
  ...
})

这里的 strict: true 很重要。
它意味着 Anthropic 对这个工具的输入结构和行为约束更严格，不希望模型随便糊弄参数。

一张图看编辑链路

它最关键的一点：要求先读文件

FileEditTool 在校验逻辑里，会检查这个文件是否已经读过。
这是 Claude Code 特别重要的一条工程约束。

你从它的写入邻居 FileWriteTool 就能看到类似逻辑，而 Edit 这边更强调局部修改场景。
Anthropic 这么做的目的很明确：

• 避免模型盲改
• 避免基于过期内容改
• 避免用户和模型同时修改导致冲突

这和“让 AI 随便改代码再说”的工具思路很不一样。

它不是直接覆盖，而是 patch 驱动

源码里有几个很有代表性的工具函数：

import { getPatchForEdit } from './utils.js'
import { areFileEditsInputsEquivalent, findActualString } from './utils.js'

这说明 FileEditTool 更像是在做：

• 找到要改的旧片段
• 生成局部补丁
• 保留尽可能多的原始结构

而不是：

把整个文件重新生成一遍后覆盖

这也是为什么 Edit 通常比 Write 更适合已有文件的小中型改动。

它还会盯着文件是否被外部修改过

源码里有一个非常关键的错误常量：

FILE_UNEXPECTEDLY_MODIFIED_ERROR

对应的场景就是：

• Claude 读过文件
• 用户或 linter 后来又改了文件
• Claude 还想基于旧快照继续编辑

这时系统会阻止它继续写。
这类设计很重要，因为真实项目里：

• 保存时自动格式化
• IDE 自动修复
• 你和 Claude 同时改文件

都非常常见。

一次典型使用路径

它和 FileWriteTool 的区别

很多人会把 Edit 和 Write 混在一起。
两者分工其实非常清楚：

• FileEditTool：已有文件，局部替换，强调 patch
• FileWriteTool：整文件创建或覆盖，强调完整内容写入

所以如果一个文件已经存在，而且你只想改其中一小块逻辑，Edit 更合理。

最容易误解它的地方

误解一：Edit 和 Bash sed 没本质区别

有很大区别。
Edit 直接接入了权限系统、文件读状态和 diff 跟踪。

误解二：Edit 是文本工具，不涉及工程状态

不对。
它会联动：

• Git diff
• LSP 诊断
• 文件历史
• 技能目录激活

误解三：Edit 只是“更安全的替换”

更准确一点：

它是 Claude Code 的受控增量编辑器。

它和相邻工具的关系

小结

FileEditTool 最值得学的点，不是“怎么替换字符串”，而是：

Claude Code 如何把文件编辑做成一个带前置阅读、冲突检测、权限控制和 patch 结果的工程化操作。

这正是它比“AI 帮你执行 sed 命令”高级的地方。