文字編輯器工具

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 檔案中的語法錯誤。問題出在 `get_primes` 函數的第 19 行。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 的功能來提升您的開發工作流程和生產力。