Claude Platform Docs
Messages工具

文本编辑器工具

为 Claude 提供 Anthropic 定义的文本编辑器工具,用于查看、创建和编辑文件,并处理其 view、str_replace、create 和 insert 命令。

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

有关模型支持情况,请参阅工具参考。

何时使用文本编辑器工具

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

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

使用文本编辑器工具

通过 Messages API 向 Claude 提供文本编辑器工具(名为 str_replace_based_edit_tool)。

您可以选择指定 max_characters 参数,以控制查看大文件时的截断行为。

client = anthropic.Anthropic()

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

print(response)

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

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

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

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

    • 从 Claude 的工具使用请求中提取文件或目录路径
    • 读取文件内容或列出目录内容
    • 如果在工具配置中指定了 max_characters 参数,则将文件内容截断到该长度
    • 通过包含 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 表示文件开头)
  • insert_text:要插入的文本

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "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)

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

Output
{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-5-5",
  "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-5-5",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "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()',
                }
            ],
        },
    ],
)

print(response)

Claude 识别出语法错误并使用 str_replace 命令进行修复:

Output
{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-5-5",
  "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-5-5",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    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.",
                }
            ],
        },
    ],
)

print(response)

最后,Claude 对修复内容提供完整的解释:

Output
{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-5-5",
  "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."
    }
  ]
}

实现文本编辑器工具

文本编辑器工具以无架构(schema-less)工具的形式实现。使用此工具时,您不需要像其他工具那样提供输入架构;该架构内置于 Claude 的模型中,无法修改。

对于 Claude 4 及更高版本的模型,工具类型为 type: "text_editor_20250728"。

  1. 初始化您的编辑器实现

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

  2. 处理编辑器工具调用

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

    def handle_editor_tool(tool_call):
        input_params = tool_call.input
        command = input_params.get("command", "")
        file_path = input_params.get("path", "")
    
        match command:
            case "view":
                # 读取并返回文件内容
                pass
            case "str_replace":
                # 替换文件中的文本
                pass
            case "create":
                # 创建新文件
                pass
            case "insert":
                # 在指定位置插入文本
                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,
            }

处理错误

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

遵循实现最佳实践


定价和令牌使用

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

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

工具额外输入令牌
text_editor_20250429(Claude 4.x)700 个令牌

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

将文本编辑器工具与其他工具集成

您可以将文本编辑器工具与其他 Claude 工具一起使用。组合使用工具时,请确保:

  • 工具版本与您使用的模型相匹配
  • 考虑请求中包含的所有工具所产生的额外令牌使用量

更新日志

日期版本变更
2025 年 7 月 28 日text_editor_20250728发布更新版文本编辑器工具,修复了一些问题并添加了可选的 max_characters 参数。除此之外与 text_editor_20250429 完全相同。
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 首次发布文本编辑器工具(已退役;请参阅模型弃用)。通过 view、create、str_replace、insert 和 undo_edit 命令提供查看、创建和编辑文件的功能。

后续步骤

以下是一些以更便捷、更强大的方式使用文本编辑器工具的思路:

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

文本编辑器工具使 Claude 能够直接处理您的代码库,支持从调试到自动化文档编写的各种工作流。

了解如何实现与 Claude 配合使用的工具工作流。

使用 Claude 执行 shell 命令。

Was this page helpful?