replace - 替换文本

概述

replace 工具用于在文件中替换文本。默认替换单个匹配项，但可以通过指定 expected_replacements 参数来替换多个匹配项。此工具需要提供足够的上下文来确保精确定位。

工具名称

• 内部名称: replace
• 显示名称: Edit
• 图标: 铅笔 (Pencil)

参数

必需参数

参数名	类型	说明
file_path	string	要修改的文件的绝对路径。必须以 / 开头。
old_string	string	要替换的精确文本（包括所有空格、缩进、换行符等）。
new_string	string	用于替换 old_string 的精确文本（包括所有空格、缩进、换行符等）。确保结果代码正确且符合习惯。

可选参数

参数名	类型	说明
expected_replacements	number	预期的替换次数。默认为 1。当需要替换多个匹配项时使用。最小值为 1。
modified_by_user	boolean	编辑是否由用户手动修改。用于内部跟踪。

功能说明

1. 精确匹配：

   • 必须提供精确的文本匹配（包括空格、缩进、换行符）
   • 不要转义 old_string 或 new_string
   • 匹配区分大小写

2. 上下文要求：

   • 对于单次替换：在目标文本前后至少包含 3 行上下文
   • 精确匹配空格和缩进
   • 如果字符串匹配多个位置或不完全匹配，工具将失败

3. 多次替换：

   • 设置 expected_replacements 为要替换的次数
   • 工具将替换所有精确匹配 old_string 的位置
   • 确保替换次数与预期匹配

4. 安全限制：

   • 文件路径必须是绝对路径
   • 文件必须在项目根目录内
   • 在执行前使用 read_file 检查文件内容

重要提示

必须满足以下所有要求，否则工具将失败：

1. file_path 必须是绝对路径
2. old_string 必须是精确的字面文本（包括所有空格、缩进、换行符和周围代码等）
3. new_string 必须是精确的字面文本（也包括所有空格、缩进、换行符和周围代码等）
4. 永远不要转义 old_string 或 new_string

关键要求：old_string 必须唯一标识要更改的单个实例。在目标文本前后至少包含 3 行上下文，精确匹配空格和缩进。

使用示例

单次替换（带上下文）

{
  "file_path": "/home/user/project/src/app.ts",
  "old_string": "function greet(name: string) {\n  console.log('Hello, ' + name);\n  return name;\n}",
  "new_string": "function greet(name: string): string {\n  console.log(`Hello, ${name}`);\n  return name;\n}"
}

多次替换

{
  "file_path": "/home/user/project/src/utils.ts",
  "old_string": "var ",
  "new_string": "const ",
  "expected_replacements": 5
}

替换带缩进的代码块

{
  "file_path": "/home/user/project/src/component.tsx",
  "old_string": "  render() {\n    return (\n      <div>Old Content</div>\n    );\n  }",
  "new_string": "  render() {\n    return (\n      <div>New Content</div>\n    );\n  }"
}

返回结果

工具返回一个包含以下字段的对象：

• llmContent: 操作结果描述
• returnDisplay: 用户友好的显示信息（包含文件差异）
• summary: 操作摘要（例如："Replaced 1 occurrence in file.ts"）

错误处理

可能的错误情况：

1. 匹配错误：

   • 找不到 old_string
   • 找到多个匹配但 expected_replacements 为 1
   • 实际替换次数与 expected_replacements 不匹配

2. 路径错误：

   • 路径不是绝对路径
   • 路径不在项目根目录内
   • 文件不存在

3. 参数错误：

   • 缺少必需参数
   • old_string 或 new_string 为空
   • expected_replacements 小于 1

工作流程

1. 读取文件：首先使用 read_file 检查文件当前内容
2. 计划替换：确定要替换的精确文本和上下文
3. 执行替换：调用 replace 工具
4. 验证结果：检查替换是否成功

注意事项

1. 始终使用 read_file：在尝试替换之前，使用 read_file 工具检查文件的当前内容
2. 提供足够上下文：对于单次替换，在目标文本前后包含至少 3 行上下文
3. 不要转义：不要转义 old_string 或 new_string，这会破坏精确文本要求
4. 验证缩进：确保空格和缩进完全匹配
5. 行尾符：注意行尾符（LF vs CRLF）的一致性

相关工具

• read_file: 读取文件内容
• write_file: 写入整个文件
• search_file_content: 搜索文件内容
• list_directory: 列出目录内容