Claude Code 对文件进行修改的方式颇具巧思——它既不依赖行号，也不采用 AST 补丁。操作流程是：让模型输出一段待替换的原文 old_string 以及替换后的文本 new_string，实际的写入动作由 Edit 工具负责执行。

接口看上去很直观：告诉工具“把这段文字换成那段文字”即可。然而，要确保这一流程稳定可靠，必须解决两个核心问题：

1. 模型读取到的文件内容与执行编辑时的文件内容之间存在时间延迟。如果在此期间文件被意外修改，该如何处理？
2. 模型输出的文本与文件中的实际文本不完全一致，遇到这种情况又该如何应对？

我们先来看 Edit 的基本结构，再围绕这两个问题深入分析。

Edit 工具的基础实现

Edit 通过 buildTool 注册为可供模型调用的工具。核心接口包含三个部分：面向模型的 Prompt、约束参数的 schema、以及实际执行替换的 call。

export const FileEditTool = buildTool({name: FILE_EDIT_TOOL_NAME,async prompt() {return getEditToolDescription();},get inputSchema() {return z.strictObject({file_path: z.string().describe('The absolute path to the file to modify'),old_string: z.string().describe('The text to replace'),new_string: z.string().describe('The text to replace it with'),replace_all: semanticBoolean(z.boolean().default(false).optional()),});},async call(input, context, _, parentMessage) {const { file_path, old_string, new_string, replace_all = false } = input;const fileContent = readTextContent(file_path);const updatedFile = replace_all? fileContent.replaceAll(old_string, new_string): fileContent.replace(old_string, new_string);writeTextContent(file_path, updatedFile);return { updatedFile };},});

四个参数的语义说明如下：

call 的流程十分直接：读取文件、查找 old_string、替换为 new_string、写回磁盘。但 inputSchema 仅能约束字段的类型与格式，无法告知模型正确的参数书写方式。因此，同一个工具定义中还包含了 Prompt，用于明确调用规则：先读取文件、保留原始缩进、默认要求 old_string 唯一、仅当需要全局替换时才使用 replace_all。

function getEditToolDescription(): string {return `Performs exact string replacements in files.Usage:- You must use your `Read` tool at least once in the conversation before editing.- When editing text from Read tool output, ensure you preserve the exact indentation.- The edit will FAIL if `old_string` is not unique in the file.- Use `replace_all` for replacing and renaming strings across the file.`;}

这一最小版本可以正常工作，但默认了两个假设：文件不会在读写之间被修改，模型输出的文本一定能与文件内容精确匹配。而在真实环境中，这两个前提条件往往无法满足。

文件在生成过程中被改动了怎么办

模型读取文件与实际执行编辑之间存在一个时间窗口。在此期间，用户可能手动修改了代码，linter 可能自动格式化了文件，编辑器也可能保存了新的内容。如果 Edit 工具不做任何校验，它会基于过时的文件内容执行替换，从而覆盖掉用户或 linter 的改动。

readFileState：记录每个文件的最后读取状态

Edit 工具使用一个 LRU 缓存 readFileState 来追踪每个文件的最后读取状态：

type FileState = {content: string; // 读取时的文件内容timestamp: number; // Math.floor(mtimeMs)offset: number | undefined; // 读取范围起始（全文读取时为 undefined）limit: number | undefined; // 读取范围长度（全文读取时为 undefined）isPartialView?: boolean; // 自动注入的内容与磁盘不一致时为 true};

Read 工具读取文件后会写入此缓存，Edit 工具写入成功后也会更新它。该缓存是后续所有过期检测的基础。

第一道防线：validateInput 执行前检查

validateInput 在编辑执行之前运行，不写入文件，仅判断当前编辑是否满足安全执行条件。它同时检查两个问题：

1. 文件是否被修改过
2. old_string 是否能匹配上

async function validateInput(input, toolUseContext) {const { file_path, old_string, replace_all } = input;const fullFilePath = expandPath(file_path);const fileContent = readCurrentTextFile(fullFilePath);// 1. 文件必须被读取过（不能编辑模型未读过的文件）const readTimestamp = toolUseContext.readFileState.get(fullFilePath);if (!readTimestamp || readTimestamp.isPartialView) {return {result: false,message: 'File has not been read yet.',errorCode: 6,};}// 2. 文件自读取后不得被修改const lastWriteTime = getFileModificationTime(fullFilePath);if (lastWriteTime > readTimestamp.timestamp) {const isFullRead =readTimestamp.offset === undefined && readTimestamp.limit === undefined;const contentUnchanged =isFullRead && fileContent === readTimestamp.content;if (!contentUnchanged) {return {result: false,message: 'File has been modified since read.',errorCode: 7,};}}// 3. old_string 必须能在文件中匹配到const actualOldString = findActualString(fileContent, old_string);if (!actualOldString) {return {result: false,message: 'String to replace not found in file.',errorCode: 8,};}// 4. 默认只允许唯一匹配const matches = fileContent.split(actualOldString).length - 1;if (matches > 1 && !replace_all) {return {result: false,message: `Found ${matches} matches.`,errorCode: 9,};}}

前两步用于判断文件是否被修改。有几个细节值得留意：

• 时间戳比较使用了 Math.floor(mtimeMs)，去除亚毫秒精度，减少因时间戳抖动引发的误判。
• 在 Windows 上，云同步、杀毒软件等可能仅更改时间戳而不改变内容。因此，即使时间戳发生变化，如果文件是完整读取且内容未变，仍然允许编辑。
• isPartialView 标记自动注入的内容（如 CLAUDE.md）与磁盘文件不一致的情况，强制用户先 Read 再编辑。

第三步校验 old_string 能否匹配——这里使用的 findActualString 会先尝试精确匹配，若失败则将弯引号转换为直引号再试，因为 Claude 只能输出直引号但文件可能使用弯引号。如果引号规范化后依然无法匹配，则直接拒绝。匹配成功后返回原始文件中的实际文本，后续替换将使用真实字符。若文件使用的是弯引号，preserveQuoteStyle 会把 new_string 中的直引号转回弯引号，以保持风格一致。

四步检查中，每一步失败均带有明确的错误码和错误信息，模型可据此决定下一步操作：

第二道防线：call 写入前再次检查

validateInput 通过并不意味着文件绝对安全。校验通过到实际写入之间仍存在时间窗口。因此，call 在写入前会重新读取文件并再次检查：

async function call(input, { readFileState }) {const { file_path, old_string, new_string, replace_all } = input;const absoluteFilePath = expandPath(file_path);// 重新读取磁盘上的当前内容const {content: originalFileContents,encoding,lineEndings,} = readFileForEdit(absoluteFilePath);// 写入前再次进行过期检测const lastRead = readFileState.get(absoluteFilePath);const lastWriteTime = getFileModificationTime(absoluteFilePath);if (!lastRead || lastWriteTime > lastRead.timestamp) {const isFullRead =lastRead?.offset === undefined && lastRead?.limit === undefined;const contentUnchanged =isFullRead && originalFileContents === lastRead.content;if (!contentUnchanged) {// 'File has been unexpectedly modified. Read it again before attempting to write it.'throw new Error(FILE_UNEXPECTEDLY_MODIFIED_ERROR);}}// 执行替换并写入...}

call 将文件读取、过期检查、替换计算、磁盘写入放在一个同步段中，不允许任何异步操作插入检查和写入之间。目录创建、文件历史备份等需要 await 的步骤全部安排在此段之前完成。检查通过后，如果让出事件循环（例如 await 一个异步操作），其他代码就有机会在此期间修改文件，第二道防线就形同虚设。

因为 validateInput 和 call 不是连续执行的。validateInput 返回通过后，运行时还需要进行权限检查、等待用户确认、执行 hook 等操作，这些步骤可能耗时数百毫秒甚至更久。在此窗口内，用户的编辑器可能自动保存了文件，linter 可能格式化了代码，甚至另一个 Claude Code 会话可能刚刚写入了同一个文件。若仅依赖 validateInput 的检查结果就直接写入，这些并发修改将会被静默覆盖。第二道防线的意义在于：真正写入之前，通过同步读取获取最新文件内容，再做一次判断——文件变了就拒绝，未变才写入。

写入后更新 readFileState

编辑成功后，call 会更新 readFileState，将文件内容和时间戳设置为写入后的值：

readFileState.set(absoluteFilePath, {content: updatedFile,timestamp: getFileModificationTime(absoluteFilePath),});

这一步容易忽略但极为关键：如果不更新，下一次连续编辑会将自己刚写入的文件误判为“外部修改”，导致所有连续编辑均失败。

文件历史：最后一道恢复线

即使所有检查都已通过，写入结果仍可能不符合用户预期。Edit 工具在真正写入之前会调用文件历史机制备份编辑前的内容：

await fileHistoryTrackEdit(absoluteFilePath);

备份使用 fs.copyFile() 而非将文件读入内存，存储在 ~/.claude/file-history/ 目录下。这并非校验机制的一部分，而是恢复机制：前面尽量防止错误写入，后面仍保留回滚能力。

小结

总结

Edit 工具的实现揭示了一个更通用的原则：编写供 LLM 使用的工具时，不能盲目信任模型的输出，也要充分考虑环境的变化，最终依靠验证来确保正确性。

不能信任模型的输出，因为模型天然具有不稳定性。它可能记错文件内容，可能输出与原文不完全一致的文本，也可能在不恰当的位置添加空格。Prompt 可以起到引导作用，但无法保证每次输出都准确无误。

要考虑环境的变化，因为模型读取文件与执行工具之间存在时间差。在此窗口中，用户可能修改了代码，linter 可能格式化了文件，甚至另一个会话可能刚刚写入了同一文件。工具执行时，现实世界已经不是模型所看到的样子。工具必须意识到这一点，在关键操作前重新确认环境状态。

最终依靠验证来保证正确性。工具层拿到模型的输出后，可以检查文件是否被修改，可以规范化文本后再匹配，可以在写入前再次读取最新内容。能够确认安全的，就执行；无法确认的，就拒绝。对于已经完成的写入，则更新状态并保留恢复入口。

Edit 工具的每一层机制——readFileState 跟踪、mtime 检查、引号规范化、二次读取、文件历史备份——都是这一原则的具体体现。并非要求模型永不犯错，而是在模型输出不可靠、环境随时可能变化的前提下，通过验证来确保最终结果的正确性。