文本编辑器工具

Claude 可以使用 Anthropic 定义的文本编辑器工具来查看和修改文本文件，帮助您调试、修复和改进代码或其他文本文档。这使 Claude 能够直接与您的文件交互，提供实际的帮助而不仅仅是建议更改。

​

使用文本编辑器工具之前

​

使用兼容的模型

Anthropic 的文本编辑器工具仅适用于 Claude 3.5 Sonnet 和 Claude 3.7 Sonnet：

• Claude 3.7 Sonnet: text_editor_20250124
• Claude 3.5 Sonnet: text_editor_20241022

两个版本提供相同的功能 - 您使用的版本应该与您正在使用的模型相匹配。

​

评估您的使用场景

以下是使用文本编辑器工具的一些示例：

• 代码调试：让 Claude 识别和修复代码中的错误，从语法错误到逻辑问题。
• 代码重构：让 Claude 通过有针对性的编辑来改进代码结构、可读性和性能。
• 文档生成：要求 Claude 为您的代码库添加文档字符串、注释或 README 文件。
• 测试创建：让 Claude 根据其对实现的理解为您的代码创建单元测试。

​

使用文本编辑器工具

使用 Messages API 向 Claude 提供文本编辑器工具（名为 str_replace_editor）：

文本编辑器工具可以按以下方式使用：

​

文本编辑器工具命令

文本编辑器工具支持几个用于查看和修改文件的命令：

​

view

view 命令允许 Claude 检查文件内容或列出目录内容。它可以读取整个文件或特定范围的行。

参数：

• command：必须是 “view”
• path：要查看的文件或目录的路径
• view_range（可选）：指定要查看的起始和结束行号的两个整数数组。行号从 1 开始，结束行为 -1 表示读取到文件末尾。此参数仅适用于查看文件，不适用于目录。

// 查看文件的示例
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "view",
    "path": "primes.py"
  }
}

// 查看目录的示例
{
  "type": "tool_use",
  "id": "toolu_02B19r91rw91mr917835mr9",
  "name": "str_replace_editor",
  "input": {
    "command": "view",
    "path": "src/"
  }
}

​

str_replace

str_replace 命令允许 Claude 将文件中的特定字符串替换为新字符串。这用于进行精确的编辑。

参数：

• command：必须是 “str_replace”
• path：要修改的文件路径
• old_str：要替换的文本（必须完全匹配，包括空格和缩进）
• new_str：替换旧文本的新文本

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "str_replace",
    "path": "primes.py",
    "old_str": "for num in range(2, limit + 1)",
    "new_str": "for num in range(2, limit + 1):"
  }
}

​

create

create 命令允许 Claude 创建具有指定内容的新文件。

参数：

• command：必须是 “create”
• path：新文件应创建的路径
• file_text：要写入新文件的内容

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "create",
    "path": "test_primes.py",
    "file_text": "import unittest\nimport primes\n\nclass TestPrimes(unittest.TestCase):\n    def test_is_prime(self):\n        self.assertTrue(primes.is_prime(2))\n        self.assertTrue(primes.is_prime(3))\n        self.assertFalse(primes.is_prime(4))\n\nif __name__ == '__main__':\n    unittest.main()"
  }
}

​

insert

insert 命令允许 Claude 在文件的特定位置插入文本。

参数：

• command：必须是 “insert”
• path：要修改的文件路径
• insert_line：在其后插入文本的行号（0 表示文件开头）
• new_str：要插入的文本

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "insert",
    "path": "primes.py",
    "insert_line": 0,
    "new_str": "\"\"\"Module for working with prime numbers.\n\nThis module provides functions to check if a number is prime\nand to generate a list of prime numbers up to a given limit.\n\"\"\"\n"
  }
}

​

undo_edit

undo_edit 命令允许 Claude 撤消对文件所做的最后一次编辑。

参数：

• command：必须是 “undo_edit”
• path：要撤消最后一次编辑的文件路径

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "undo_edit",
    "path": "primes.py"
  }
}

​

示例：使用文本编辑器工具修复语法错误

此示例演示了 Claude 如何使用文本编辑器工具修复 Python 文件中的语法错误。

首先，您的应用程序向 Claude 提供文本编辑器工具和修复语法错误的提示：

Claude 将首先使用文本编辑器工具查看文件：

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我来帮您修复 primes.py 文件中的语法错误。首先让我看看文件以识别问题。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_editor",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

您的应用程序应该读取文件并将其内容返回给 Claude：

Claude 将识别语法错误并使用 str_replace 命令修复它：

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我在您的 primes.py 文件中找到了语法错误。在 `get_primes` 函数中，for 循环行末尾缺少冒号（:）。让我来修复这个问题。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_editor",
      "input": {
        "command": "str_replace",
        "path": "primes.py",
        "old_str": "    for num in range(2, limit + 1)",
        "new_str": "    for num in range(2, limit + 1):"
      }
    }
  ]
}

您的应用程序应该进行编辑并返回结果：

最后，Claude 将提供完整的修复说明：

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我已经修复了您的 primes.py 文件中的语法错误。问题出在第 19 行的 `get_primes` 函数中。for 循环行末尾缺少冒号（:）。\n\n以下是我所做的更改：\n\n从：\n```python\nfor num in range(2, limit + 1)\n```\n\n改为：\n```python\nfor num in range(2, limit + 1):\n```\n\n在 Python 中，开始新代码块的语句末尾需要冒号，例如 for 循环、if 语句、函数定义等。没有冒号，Python 会报语法错误，因为它不知道代码块从哪里开始。\n\n您的代码现在应该可以正常运行了。该函数将正确生成指定限制内的质数列表。"
    }
  ]
}

​

实现文本编辑器工具

文本编辑器工具作为无模式工具实现，由 type: "text_editor_20250124" 标识。使用此工具时，您不需要像其他工具那样提供输入模式；模式已内置在 Claude 的模型中，无法修改。

def handle_editor_tool(tool_call):
    input_params = tool_call.input
    command = input_params.get('command', '')
    file_path = input_params.get('path', '')
    
    if command == 'view':
        # 读取并返回文件内容
        pass
    elif command == 'str_replace':
        # 替换文件中的文本
        pass
    elif command == 'create':
        # 创建新文件
        pass
    elif command == 'insert':
        # 在指定位置插入文本
        pass
    elif command == 'undo_edit':
        # 从备份恢复
        pass

# 处理 Claude 响应中的工具使用
for content in response.content:
    if content.type == "tool_use":
        # 根据命令执行工具
        result = handle_editor_tool(content)
        
        # 将结果返回给 Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

​

处理错误

使用文本编辑器工具时可能会发生各种错误。以下是如何处理这些错误的指导：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：未找到文件",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：找到 3 处匹配的替换文本。请提供更多上下文以进行唯一匹配。",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：未找到匹配项。请检查您的文本并重试。",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：权限被拒绝。无法写入文件。",
      "is_error": true
    }
  ]
}

​

遵循实现最佳实践

def backup_file(file_path):
    """在编辑前创建文件备份。"""
    backup_path = f"{file_path}.backup"
    if os.path.exists(file_path):
        with open(file_path, 'r') as src, open(backup_path, 'w') as dst:
            dst.write(src.read())

def safe_replace(file_path, old_text, new_text):
    """仅在恰好有一个匹配项时替换文本。"""
    with open(file_path, 'r') as f:
        content = f.read()
    
    count = content.count(old_text)
    if count == 0:
        return "错误：未找到匹配项"
    elif count > 1:
        return f"错误：找到 {count} 个匹配项"
    else:
        new_content = content.replace(old_text, new_text)
        with open(file_path, 'w') as f:
            f.write(new_content)
        return "成功替换文本"

def verify_changes(file_path):
    """在进行更改后运行测试或检查。"""
    try:
        # 对于 Python 文件，检查语法错误
        if file_path.endswith('.py'):
            import ast
            with open(file_path, 'r') as f:
                ast.parse(f.read())
            return "语法检查通过"
    except Exception as e:
        return f"验证失败：{str(e)}"

​

定价和令牌使用

文本编辑器工具使用与其他 Claude 工具相同的定价结构。它遵循基于您使用的 Claude 模型的标准输入和输出令牌定价。

除了基本令牌外，文本编辑器工具还需要以下额外的输入令牌：

有关工具定价的更详细信息，请参阅工具使用定价。

​

将文本编辑器工具与计算机使用集成

文本编辑器工具可以与计算机使用工具和其他 Anthropic 定义的工具一起使用。在组合这些工具时，您需要：

1. 包含适当的测试版标头（如果与计算机使用一起使用）
2. 将工具版本与您使用的模型匹配
3. 考虑请求中包含的所有工具的额外令牌使用

有关在计算机使用上下文中使用文本编辑器工具的更多信息，请参阅计算机使用。

​

更改日志

​

下一步

以下是一些如何以更方便和强大的方式使用文本编辑器工具的想法：

• 集成到您的开发工作流程中：将文本编辑器工具构建到您的开发工具或 IDE 中
• 创建代码审查系统：让 Claude 审查您的代码并进行改进
• 构建调试助手：创建一个系统，让 Claude 帮助您诊断和修复代码中的问题
• 实现文件格式转换：让 Claude 帮助您将文件从一种格式转换为另一种格式
• 自动化文档：设置工作流程，让 Claude 自动为您的代码生成文档

当您使用文本编辑器工具构建应用程序时，我们很期待看到您如何利用 Claude 的功能来提升您的开发工作流程和生产力。