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

使用文本编辑器工具前

使用兼容的模型

Anthropic 的文本编辑器工具适用于多个 Claude 模型:

  • Claude 4 Opus 和 Sonnettext_editor_20250429
  • Claude Sonnet 3.7text_editor_20250124
  • Claude Sonnet 3.5text_editor_20241022

Claude 4 模型的较新版本 text_editor_20250429 不包含 undo_edit 命令。如果您需要此功能,您需要使用 Claude 3.7 或 Sonnet 3.5 及其各自的工具版本。

评估您的用例适合性

使用文本编辑器工具的一些示例包括:

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

使用文本编辑器工具

使用 Messages API 向 Claude 提供文本编辑器工具(名为 str_replace_based_edit_tool):

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        {
            "role": "user", 
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?"
        }
    ]
)

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

1

向 Claude 提供文本编辑器工具和用户提示

  • 在您的 API 请求中包含文本编辑器工具
  • 提供可能需要检查或修改文件的用户提示,例如”你能修复我代码中的语法错误吗?”
2

Claude 使用工具检查文件或目录

  • Claude 评估需要查看的内容,并使用 view 命令检查文件内容或列出目录内容
  • API 响应将包含带有 view 命令的 tool_use 内容块
3

执行查看命令并返回结果

  • 从 Claude 的工具使用请求中提取文件或目录路径
  • 读取文件内容或列出目录内容并将其返回给 Claude
  • 通过继续对话并添加包含 tool_result 内容块的新 user 消息,将结果返回给 Claude
4

Claude 使用工具修改文件

  • 在检查文件或目录后,Claude 可能会使用 str_replace 等命令进行更改,或使用 insert 在特定行号添加文本
  • 如果 Claude 使用 str_replace 命令,Claude 会构建一个格式正确的工具使用请求,其中包含旧文本和要替换的新文本
5

执行编辑并返回结果

  • 从 Claude 的工具使用请求中提取文件路径、旧文本和新文本
  • 在文件中执行文本替换
  • 将结果返回给 Claude
6

Claude 提供分析和解释

  • 在检查并可能编辑文件后,Claude 提供关于发现内容和所做更改的完整解释

文本编辑器工具命令

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

view

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

参数:

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

str_replace

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

参数:

  • command:必须为 “str_replace”
  • path:要修改的文件路径
  • old_str:要替换的文本(必须精确匹配,包括空格和缩进)
  • new_str:要插入替换旧文本的新文本

create

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

参数:

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

insert

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

参数:

  • command:必须为 “insert”
  • path:要修改的文件路径
  • insert_line:在其后插入文本的行号(0 表示文件开头)
  • new_str:要插入的文本

undo_edit

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

此命令仅在 Claude Sonnet 3.7 和 Claude Sonnet 3.5 中可用。Claude 4 模型使用的 text_editor_20250429 不支持此命令。

参数:

  • command:必须为 “undo_edit”
  • path:应撤销最后一次编辑的文件路径

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

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

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        {
            "role": "user", 
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?"
        }
    ]
)

print(response)

行号

在上面的示例中,view 工具结果包含带有行号前缀的文件内容(例如,“1: def is_prime(n):”)。行号不是必需的,但对于成功使用 view_range 参数检查文件的特定部分和使用 insert_line 参数在精确位置添加内容至关重要。

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

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

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

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        {
            "role": "user", 
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "name": "str_replace_based_edit_tool",
                    "input": {
                        "command": "view",
                        "path": "primes.py"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "content": "1: def is_prime(n):\n2:     \"\"\"Check if a number is prime.\"\"\"\n3:     if n <= 1:\n4:         return False\n5:     if n <= 3:\n6:         return True\n7:     if n % 2 == 0 or n % 3 == 0:\n8:         return False\n9:     i = 5\n10:     while i * i <= n:\n11:         if n % i == 0 or n % (i + 2) == 0:\n12:             return False\n13:         i += 6\n14:     return True\n15: \n16: def get_primes(limit):\n17:     \"\"\"Generate a list of prime numbers up to the given limit.\"\"\"\n18:     primes = []\n19:     for num in range(2, limit + 1)\n20:         if is_prime(num):\n21:             primes.append(num)\n22:     return primes\n23: \n24: def main():\n25:     \"\"\"Main function to demonstrate prime number generation.\"\"\"\n26:     limit = 100\n27:     prime_list = get_primes(limit)\n28:     print(f\"Prime numbers up to {limit}:\")\n29:     print(prime_list)\n30:     print(f\"Found {len(prime_list)} prime numbers.\")\n31: \n32: if __name__ == \"__main__\":\n33:     main()"
                }
            ]
        }
    ]
)

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

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_based_edit_tool",
      "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):"
      }
    }
  ]
}

然后,您的应用程序应该进行编辑并返回结果:

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        # Previous messages...
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "name": "str_replace_based_edit_tool",
                    "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):"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "content": "Successfully replaced text at exactly one location."
                }
            ]
        }
    ]
)

最后,Claude 将提供完整的修复解释:

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit."
    }
  ]
}

实现文本编辑器工具

文本编辑器工具被实现为无模式工具。使用此工具时,您不需要像其他工具那样提供输入模式;模式已内置到 Claude 的模型中,无法修改。

工具类型取决于模型版本:

  • Claude 4type: "text_editor_20250429"
  • Claude Sonnet 3.7type: "text_editor_20250124"
  • Claude Sonnet 3.5type: "text_editor_20241022"
1

初始化您的编辑器实现

创建辅助函数来处理文件操作,如读取、写入和修改文件。考虑实现备份功能以从错误中恢复。

2

处理编辑器工具调用

创建一个基于命令类型处理来自 Claude 的工具调用的函数:

def handle_editor_tool(tool_call, model_version):
    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':
        # 检查是否为 Claude 4 模型
        if 'str_replace_based_edit_tool' in model_version:
            return {"error": "undo_edit command is not supported in Claude 4"}
        # 为 Claude 3.7/3.5 从备份恢复
        pass
3

实现安全措施

添加验证和安全检查:

  • 验证文件路径以防止目录遍历
  • 在进行更改前创建备份
  • 优雅地处理错误
  • 实现权限检查
4

处理 Claude 的响应

从 Claude 的响应中提取并处理工具调用:

# 处理 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
        }

实现文本编辑器工具时,请记住:

  1. 安全性:该工具可以访问您的本地文件系统,因此请实施适当的安全措施。
  2. 备份:在允许编辑重要文件之前,始终创建备份。
  3. 验证:验证所有输入以防止意外更改。
  4. 唯一匹配:确保替换恰好匹配一个位置,以避免意外编辑。

处理错误

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

遵循实施最佳实践


定价和令牌使用

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

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

工具额外输入令牌
text_editor_20250429 (Claude 4)700 令牌
text_editor_20250124 (Claude Sonnet 3.7)700 令牌
text_editor_20241022 (Claude Sonnet 3.5)700 令牌

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

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

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

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

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

更新日志

日期版本变更
2025年4月29日text_editor_20250429为 Claude 4 发布文本编辑器工具。此版本移除了 undo_edit 命令,但保留了所有其他功能。工具名称已更新以反映其基于 str_replace 的架构。
2025年3月13日text_editor_20250124引入独立的文本编辑器工具文档。此版本针对 Claude Sonnet 3.7 进行了优化,但具有与前一版本相同的功能。
2024年10月22日text_editor_20241022随 Claude Sonnet 3.5 首次发布文本编辑器工具。通过 viewcreatestr_replaceinsertundo_edit 命令提供查看、创建和编辑文件的功能。

后续步骤

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

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

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