Loading... # 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 | | Claude Sonnet 3.7（已弃用） | text_editor_20250124 | **重要说明**： - 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 表示读取到文件末尾。此参数仅适用于查看文件，不适用于目录。 **示例**： ```json { "command": "view", "path": "primes.py" } ``` ```json { "command": "view", "path": "primes.py", "view_range": [1, 20] } ``` ## 2. str_replace 命令 str_replace 命令允许 Claude 用新字符串替换文件中的特定字符串。用于进行精确编辑。 **参数**： - command：必须是 "str_replace" - path：要修改的文件的路径 - old_str：要替换的文本（必须完全匹配，包括空格和缩进） - new_str：要在旧文本位置插入的新文本 **示例**： ```json { "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 工具的使用遵循以下流程： ```mermaid 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 并附带用户提示： ```bash 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 命令查看文件内容： ```json { "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 命令进行修复： ```json { "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 的工具调用： ```python 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 的响应中提取并处理工具调用： ```python # 处理 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： | 工具 | 额外输入 token | |------|---------------| | text_editor_20250429（Claude 4.x） | 700 tokens | | text_editor_20250124（Claude Sonnet 3.7） | 700 tokens | # 十、工具集成 Text Editor 工具可以与其他 Claude 工具一起使用。组合工具时，确保： - 工具版本与使用的模型匹配 - 考虑请求中包含的所有工具的额外 token 使用 # 十一、变更日志 | 日期 | 版本 | 变更 | |------|------|------| | 2025 年 7 月 28 日 | text_editor_20250728 | 发布更新的 Text Editor 工具，修复了一些问题并添加了可选的 max_characters 参数。其他方面与 text_editor_20250429 相同。 | | 2025 年 4 月 29 日 | text_editor_20250429 | 发布面向 Claude 4 的 Text Editor 工具。此版本移除了 undo_edit 命令，但保留所有其他功能。工具名称已更新以反映其基于 str_replace 的架构。 | | 2025 年 3 月 13 日 | text_editor_20250124 | 引入独立的 Text Editor 工具文档。此版本针对 Claude Sonnet 3.7 优化，但与前一版本功能相同。 | | 2024 年 10 月 22 日 | text_editor_20241022 | Text Editor 工具的首次发布，与 Claude Sonnet 3.5 一起提供。通过 view、create、str_replace、insert 和 undo_edit 命令提供查看、创建和编辑文件的功能。 | # 十二、下一步使用建议 以下是将 Text Editor 工具用于更方便和强大的方式的一些建议： ## 1. 集成到开发工作流 将 Text Editor 工具构建到开发工具或 IDE 中 ## 2. 创建代码审查系统 让 Claude 审查代码并进行改进 ## 3. 构建调试助手 创建一个系统，让 Claude 帮助诊断和修复代码中的问题 ## 4. 实现文件格式转换 让 Claude 帮助将文件从一种格式转换为另一种格式 ## 5. 自动化文档 为 Claude 自动记录代码设置工作流 *** ## 参考资料 1. [Text editor tool - Claude Docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool) 最后修改：2026 年 01 月 19 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏