Claude Code Edit工具的工作流程介绍

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

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

  },

});

1

2

3

4

5

6

7

8

9

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

}

1

2

3

4

5

6

7

type FileState = {

  content: string; // 读取时的文件内容

  timestamp: number; // Math.floor(mtimeMs)

  offset: number | undefined; // 读取范围起始（全文读取时为 undefined）

  limit: number | undefined; // 读取范围长度（全文读取时为 undefined）

  isPartialView?: boolean; // 自动注入的内容与磁盘不一致时为 true

};

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

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,

    };

  }

}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

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

    }

  }

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

}

1

2

3

4

readFileState.set(absoluteFilePath, {

  content: updatedFile,

  timestamp: getFileModificationTime(absoluteFilePath),

});

1

await fileHistoryTrackEdit(absoluteFilePath);