Claude Text Editor 工具使用指南

一、概述

1. 简介

A. 是什么

Claude Text Editor 是 Anthropic 定义的一个工具，允许 Claude 直接查看和修改文本文件。这使得 Claude 能够直接与文件系统交互，提供动手协助而不仅仅是建议更改。

B. 为什么学

• 让 Claude 能够直接调试、修复和改进代码
• 自动化文档生成和测试创建
• 集成到开发工作流中，提升开发效率

C. 学完能做什么

• 使用 Claude 修复代码中的语法错误和逻辑问题
• 让 Claude 帮助重构代码结构和添加文档
• 集成文本编辑器工具到自己的应用中

2. 前置知识

A. 必备技能

• 了解 RESTful API 基本概念
• 熟悉至少一种编程语言（Python、JavaScript 等）
• 基本的文件系统操作知识

B. 推荐知识

• 了解 Claude Messages API 的使用方式
• 熟悉工具调用（Tool Use）的概念

二、模型兼容性

1. 工具版本

重要说明：

• Claude 4.x 使用的 text_editor_20250728 版本不包含 undo_edit 命令
• 如需撤销功能，需要使用 Claude Sonnet 3.7（已弃用）
• 旧版工具不保证与较新模型向后兼容

三、工具使用场景

1. 代码调试

Claude 可以识别并修复代码中的错误，从语法错误到逻辑问题。

2. 代码重构

让 Claude 通过有针对性的编辑来改进代码结构、可读性和性能。

3. 文档生成

请求 Claude 为代码库添加文档字符串、注释或 README 文件。

4. 测试创建

让 Claude 根据其对实现的理解为代码创建单元测试。

四、工具命令

1. view 命令

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

参数：

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

示例：

{
  "command": "view",
  "path": "primes.py"
}

{
  "command": "view",
  "path": "primes.py",
  "view_range": [1, 20]
}

2. str_replace 命令

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

参数：

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

示例：

{
  "command": "str_replace",
  "path": "primes.py",
  "old_str": " for num in range(2, limit + 1)",
  "new_str": " for num in range(2, limit + 1):"
}

3. create 命令

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

参数：

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

4. insert 命令

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

参数：

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

5. undo_edit 命令

undo_edit 命令允许 Claude 撤销对文件的上一次编辑。

重要说明：此命令仅在 Claude Sonnet 3.7（已弃用）中可用。Claude 4 模型使用的 text_editor_20250728 不支持此命令。

参数：

• command：必须是 "undo_edit"
• path：应该撤销上一次编辑的文件的路径

五、使用流程

Text Editor 工具的使用遵循以下流程：

sequenceDiagram
    participant U as 用户应用
    participant C as Claude API
    participant F as 文件系统

    U->>C: 1. 提供工具和用户提示
    C->>U: 2. 返回 view 命令
    U->>F: 3. 读取文件内容
    F-->>U: 返回文件内容
    U->>C: 4. 返回 tool_result
    C->>U: 5. 返回 str_replace 命令
    U->>F: 6. 执行文本替换
    F-->>U: 替换成功
    U->>C: 7. 返回执行结果
    C-->>U: 8. 提供完整解释

1. 提供工具和提示

将 Text Editor 工具提供给 Claude 并附带用户提示：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-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?"
      }
    ]
  }'

2. Claude 使用工具查看文件

Claude 会首先使用 view 命令查看文件内容：

{
  "type": "tool_use",
  "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "view",
    "path": "primes.py"
  }
}

3. 执行 view 命令并返回结果

应用读取文件内容并返回给 Claude。返回的内容应包含行号前缀（如 "1: def is_prime(n):"），这对于使用 view_range 和 insert_line 参数至关重要。

4. Claude 使用 str_replace 命令修复错误

Claude 识别错误后使用 str_replace 命令进行修复：

{
  "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):"
  }
}

5. 执行编辑并返回结果

应用执行文本替换并返回成功结果给 Claude。

6. Claude 提供完整解释

最后 Claude 会提供其发现和更改的完整说明。

六、实现指南

1. 工具类型

Text Editor 工具是无架构工具。使用时无需提供输入架构，架构内置在 Claude 模型中，无法修改。

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

• Claude 4：type: "text_editor_20250728"
• Claude Sonnet 3.7：type: "text_editor_20250124"

2. 实现步骤

A. 初始化编辑器实现

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

B. 处理编辑器工具调用

创建函数根据命令类型处理来自 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 从备份恢复
        pass

C. 实现安全措施

添加验证和安全检查：

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

D. 处理 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
        }

3. 实现注意事项

• 安全：工具可以访问本地文件系统，需实施适当的安全措施
• 备份：在允许编辑重要文件之前始终创建备份
• 验证：验证所有输入以防止意外更改
• 唯一匹配：确保替换仅匹配一个位置以避免意外编辑

七、错误处理

1. 文件未找到

当请求的文件不存在时，应在 tool_result 中返回明确的错误消息，告知 Claude 文件未找到。

2. 替换有多个匹配

当 str_replace 命令的 old_str 在文件中匹配多个位置时，应返回错误，要求 Claude 提供更具体的上下文以确保唯一匹配。

3. 替换无匹配

当 old_str 在文件中找不到匹配时，应返回错误，告知 Claude 未找到匹配的文本。

4. 权限错误

当没有足够的权限执行文件操作时，应返回权限错误信息。

八、最佳实践

1. 提供清晰的上下文

向 Claude 提供足够的上下文信息，以便它能够理解要完成的任务。

2. 明确指定文件路径

始终使用明确的文件路径，避免相对路径的歧义。

3. 编辑前创建备份

始终在编辑重要文件之前创建备份副本。

4. 谨慎处理唯一文本替换

确保 str_replace 命令的 old_str 参数在文件中只匹配一个位置。

5. 验证更改

在执行编辑后验证更改是否符合预期。

九、定价和 token 使用

Text Editor 工具使用与其他工具相同的定价结构。根据使用的 Claude 模型遵循标准的输入和输出 token 定价。

除了基础 token 外，Text Editor 工具还需要以下额外的输入 token：

十、工具集成

Text Editor 工具可以与其他 Claude 工具一起使用。组合工具时，确保：

• 工具版本与使用的模型匹配
• 考虑请求中包含的所有工具的额外 token 使用

十一、变更日志

十二、下一步使用建议

以下是将 Text Editor 工具用于更方便和强大的方式的一些建议：

1. 集成到开发工作流

将 Text Editor 工具构建到开发工具或 IDE 中

2. 创建代码审查系统

让 Claude 审查代码并进行改进

3. 构建调试助手

创建一个系统，让 Claude 帮助诊断和修复代码中的问题

4. 实现文件格式转换

让 Claude 帮助将文件从一种格式转换为另一种格式

5. 自动化文档

为 Claude 自动记录代码设置工作流

参考资料

1. Text editor tool - Claude Docs