Claude Code Edit工具的工作流程详解

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 };
  },
});

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.`;
}

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

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,
    };
  }
}

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);
    }
  }

  // 执行替换并写入...
}

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

await fileHistoryTrackEdit(absoluteFilePath);