Claude Code 修改文件的方式不是傳行號(hào)，也不是打 AST patch。它讓模型輸出一段要替換的原文 old_string 和替換后的文本 new_string，由 Edit 工具完成實(shí)際寫入。

這個(gè)接口看起來簡(jiǎn)單——告訴工具"把這段文字換成那段文字"就行了。但真正要把它做穩(wěn)定，需要回答兩個(gè)問題：

1. 模型看到的文件內(nèi)容和執(zhí)行編輯時(shí)的文件內(nèi)容之間存在時(shí)間差。如果文件在這段時(shí)間里被改了，怎么辦？
2. 模型輸出的文本和文件里的真實(shí)文本不完全一樣，怎么辦？

下面先看 Edit 的基本結(jié)構(gòu)，然后圍繞這兩個(gè)問題展開。

Edit 工具的基本實(shí)現(xiàn)

Edit 通過 buildTool 注冊(cè)為一個(gè)可被模型調(diào)用的工具。核心接口包括三部分：給模型看的 Prompt、約束參數(shù)的 schema、以及真正執(zhí)行替換的 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 };
  },
});

四個(gè)參數(shù)的語義：

call 的邏輯很直接：讀文件、找 old_string、替換成 new_string、寫回磁盤。但 inputSchema 只能約束字段形狀，不能告訴模型怎么寫參數(shù)。所以同一個(gè)工具定義里還有 Prompt，把調(diào)用規(guī)則寫清楚：先讀文件、保留縮進(jìn)、默認(rèn)要求 old_string 唯一、需要全局替換時(shí)再使用 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.`;
}

這個(gè)最小版本能工作，但它默認(rèn)了兩件事：文件不會(huì)在讀寫之間被改，模型輸出的文本一定能和文件內(nèi)容精確匹配。真實(shí)環(huán)境里，這兩個(gè)默認(rèn)都不成立。

文件在生成過程中被改了怎么辦

模型讀文件和實(shí)際執(zhí)行編輯之間存在時(shí)間窗口。在這個(gè)窗口里，用戶可能手動(dòng)改了代碼，linter 可能自動(dòng)格式化了文件，編輯器可能保存了新的內(nèi)容。如果 Edit 工具不做任何檢查，它會(huì)基于過時(shí)的文件內(nèi)容執(zhí)行替換，把用戶或 linter 的改動(dòng)覆蓋掉。

readFileState：記住每個(gè)文件的最后讀取狀態(tài)

Edit 工具用一個(gè) LRU 緩存 readFileState 跟蹤每個(gè)文件的最后讀取狀態(tài)：

type FileState = {
  content: string; // 讀取時(shí)的文件內(nèi)容
  timestamp: number; // Math.floor(mtimeMs)
  offset: number | undefined; // 讀取范圍起始（全文讀取時(shí)為 undefined）
  limit: number | undefined; // 讀取范圍長(zhǎng)度（全文讀取時(shí)為 undefined）
  isPartialView?: boolean; // 自動(dòng)注入的內(nèi)容與磁盤不一致時(shí)為 true
};

Read 工具讀取文件后會(huì)寫入這個(gè)緩存，Edit 工具寫入成功后也會(huì)更新它。這個(gè)緩存是后續(xù)所有過期檢測(cè)的基礎(chǔ)。

第一道防線：validateInput 執(zhí)行前檢查

validateInput 在編輯執(zhí)行之前運(yùn)行，不寫文件，只判斷這次編輯是否滿足安全執(zhí)行條件。它同時(shí)檢查兩個(gè)問題：

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 必須能匹配到文件內(nèi)容
  const actualOldString = findActualString(fileContent, old_string);
  if (!actualOldString) {
    return {
      result: false,
      message: 'String to replace not found in file.',
      errorCode: 8,
    };
  }

  // 4. 默認(rèn)只允許唯一匹配
  const matches = fileContent.split(actualOldString).length - 1;
  if (matches > 1 && !replace_all) {
    return {
      result: false,
      message: `Found ${matches} matches.`,
      errorCode: 9,
    };
  }
}

前兩步檢查文件是否被改過。有幾個(gè)細(xì)節(jié)值得注意：

• 時(shí)間戳比較用的是 Math.floor(mtimeMs)，去掉亞毫秒精度，減少時(shí)間戳抖動(dòng)造成的誤報(bào)。
• Windows 上云同步、殺毒軟件等可能只改時(shí)間戳不改內(nèi)容。所以即使時(shí)間戳變了，如果文件是完整讀取的且內(nèi)容沒變，仍然允許編輯。
• isPartialView 標(biāo)記自動(dòng)注入的內(nèi)容（如 CLAUDE.md）與磁盤文件不一致的情況，強(qiáng)制用戶先 Read 再編輯。

第三步檢查 old_string 能不能匹配上——這里用的 findActualString 會(huì)先試精確匹配，失敗后把彎引號(hào)轉(zhuǎn)成直引號(hào)再試，因?yàn)?Claude 只能輸出直引號(hào)但文件里可能用彎引號(hào)。 如果引號(hào)規(guī)范化后仍然匹配不到，直接拒絕。匹配成功后返回的是原始文件里的實(shí)際文本，后續(xù)替換用真實(shí)字符。如果文件用的是彎引號(hào)，preserveQuoteStyle 會(huì)把 new_string 里的直引號(hào)轉(zhuǎn)回彎引號(hào)，保持風(fēng)格一致。

四步檢查，每一步失敗都有明確的錯(cuò)誤碼和錯(cuò)誤消息，模型可以根據(jù)錯(cuò)誤信息決定下一步行動(dòng)：

第二道防線：call 寫入前再檢查一次

validateInput 通過不代表文件就安全了。校驗(yàn)通過到真正寫入之間仍然有時(shí)間窗口。所以 call 在寫入前會(huì)重新讀取文件并再次檢查：

async function call(input, { readFileState }) {
  const { file_path, old_string, new_string, replace_all } = input;
  const absoluteFilePath = expandPath(file_path);

  // 重新讀取磁盤上的當(dāng)前內(nèi)容
  const {
    content: originalFileContents,
    encoding,
    lineEndings,
  } = readFileForEdit(absoluteFilePath);

  // 寫入前再次做過期檢測(cè)
  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);
    }
  }

  // 執(zhí)行替換并寫入...
}

call 把文件讀取、過期檢查、替換計(jì)算、磁盤寫入放在一個(gè)同步段里，不允許任何異步操作插入到檢查和寫入之間。目錄創(chuàng)建、文件歷史備份等需要 await 的步驟全部安排在這個(gè)段之前完成。 檢查通過之后如果讓出事件循環(huán)（比如 await 一個(gè)異步操作），別的代碼就有機(jī)會(huì)在這段時(shí)間里修改文件，第二道防線就白做了。

為什么只有第一道防線不夠？

因?yàn)?validateInput 和 call 之間不是連續(xù)執(zhí)行的。validateInput 返回通過之后，運(yùn)行時(shí)還要做權(quán)限檢查、等待用戶確認(rèn)、執(zhí)行 hook 等操作，這些步驟可能耗時(shí)數(shù)百毫秒甚至更長(zhǎng)。在這個(gè)窗口里，用戶的編輯器可能自動(dòng)保存了文件，linter 可能格式化了代碼，甚至另一個(gè) Claude Code 會(huì)話可能剛剛寫入了同一個(gè)文件。如果只靠 validateInput 的檢查結(jié)果就直接寫入，這些并發(fā)修改會(huì)被靜默覆蓋。第二道防線的意義在于：真正寫入之前，用同步讀取拿到最新的文件內(nèi)容，再做一次判斷——文件變了就拒絕，沒變才寫入。

寫入后更新 readFileState

編輯成功后，call 會(huì)更新 readFileState，把文件內(nèi)容和時(shí)間戳設(shè)為寫入后的值：

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

這一步容易被忽略，但很關(guān)鍵：如果不更新，下一次連續(xù)編輯會(huì)把自己剛寫入的文件誤判為"外部修改"，導(dǎo)致所有連續(xù)編輯都失敗。

文件歷史：最后一道恢復(fù)線

即使所有檢查都通過了，寫入仍然可能不是用戶期望的。Edit 工具在真正寫入之前會(huì)調(diào)用文件歷史機(jī)制備份編輯前的內(nèi)容：

await fileHistoryTrackEdit(absoluteFilePath);

備份使用 fs.copyFile() 而不是把文件讀內(nèi)存，存儲(chǔ)在 ~/.claude/file-history/ 下。這不是校驗(yàn)機(jī)制的一部分，而是恢復(fù)機(jī)制：前面盡量避免錯(cuò)誤寫入，后面仍然保留回滾能力。

小結(jié)

總結(jié)

Edit 工具的實(shí)現(xiàn)揭示了一個(gè)更一般的道理：寫一個(gè)讓 LLM 使用的工具，不能信任模型的輸出，也要考慮環(huán)境的變化，最終靠驗(yàn)證來保證正確性。

不能信任模型的輸出，因?yàn)槟Ｐ吞烊徊环€(wěn)定。它可能記錯(cuò)文件內(nèi)容，可能輸出和原文不完全一致的文本，可能在不該加空格的地方加了空格。Prompt 可以引導(dǎo)它，但無法保證它每次都對(duì)。

要考慮環(huán)境的變化，因?yàn)槟Ｐ妥x取文件和執(zhí)行工具之間存在時(shí)間差。在這個(gè)窗口里，用戶可能改了代碼，linter 可能格式化了文件，甚至另一個(gè)會(huì)話可能剛剛寫入了同一個(gè)文件。工具執(zhí)行的時(shí)候，世界已經(jīng)不是模型看到的樣子了。工具必須意識(shí)到這一點(diǎn)，在關(guān)鍵操作前重新確認(rèn)環(huán)境狀態(tài)。

最終靠驗(yàn)證來保證正確性。工具層拿到模型的輸出后，可以檢查文件是否被改過，可以規(guī)范化文本后再匹配，可以在寫入前再讀一次最新內(nèi)容。能確認(rèn)安全的，執(zhí)行；不能確認(rèn)的，拒絕。已經(jīng)完成的寫入，更新狀態(tài)并保留恢復(fù)入口。

Edit 工具的每一層機(jī)制——readFileState 跟蹤、mtime 檢查、引號(hào)規(guī)范化、二次讀取、文件歷史備份——都是這個(gè)原則的具體體現(xiàn)。不是讓模型永遠(yuǎn)不犯錯(cuò)，而是在模型輸出不可靠、環(huán)境隨時(shí)可能變化的前提下，通過驗(yàn)證保證最終結(jié)果的正確性。

以上就是Claude Code Edit工具的工作流程詳解的詳細(xì)內(nèi)容，更多關(guān)于Claude Code Edit工具工作流程的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論