工具

文字編輯器工具

了解如何使用 Anthropic 定義的文字編輯器工具來檢視和修改文字檔案。

Claude 可以使用 Anthropic 定義的文字編輯器工具來檢視和修改文字檔案，幫助您除錯、修復和改進您的程式碼或其他文字文件。這讓 Claude 能夠直接與您的檔案互動，提供實際操作的協助，而不僅僅是建議更改。

模型相容性

模型	工具版本
Claude 4.x 模型	`text_editor_20250728`
Claude Sonnet 3.7（已棄用）	`text_editor_20250124`

適用於 Claude 4 模型的 text_editor_20250728 工具不包含 undo_edit 命令。如果您需要此功能，您需要使用 Claude Sonnet 3.7（已棄用）。

較舊的工具版本不保證與較新的模型向後相容。請始終使用與您的模型版本對應的工具版本。

何時使用文字編輯器工具

以下是一些使用文字編輯器工具的範例：

程式碼除錯：讓 Claude 識別並修復您程式碼中的錯誤，從語法錯誤到邏輯問題。
程式碼重構：讓 Claude 透過有針對性的編輯來改善您的程式碼結構、可讀性和效能。
文件生成：要求 Claude 為您的程式碼庫添加文件字串、註解或 README 檔案。
測試建立：讓 Claude 根據對實作的理解為您的程式碼建立單元測試。

使用文字編輯器工具

文字編輯器工具可以按以下方式使用：

向 Claude 提供文字編輯器工具和使用者提示
- 在您的 API 請求中包含文字編輯器工具
- 提供可能需要檢查或修改檔案的使用者提示，例如「你能修復我程式碼中的語法錯誤嗎？」
Claude 使用工具檢查檔案或目錄
- Claude 評估需要查看的內容，並使用 view 命令來檢查檔案內容或列出目錄內容
- API 回應將包含帶有 view 命令的 tool_use 內容區塊
執行檢視命令並返回結果
- 從 Claude 的工具使用請求中提取檔案或目錄路徑
- 讀取檔案內容或列出目錄內容
- 如果在工具配置中指定了 max_characters 參數，則將檔案內容截斷到該長度
- 透過繼續對話，使用包含 tool_result 內容區塊的新 user 訊息將結果返回給 Claude
Claude 使用工具修改檔案
- 在檢查檔案或目錄後，Claude 可能會使用 str_replace 等命令進行更改，或使用 insert 在特定行號添加文字。
- 如果 Claude 使用 str_replace 命令，Claude 會構建一個格式正確的工具使用請求，包含要替換的舊文字和新文字
執行編輯並返回結果
- 從 Claude 的工具使用請求中提取檔案路徑、舊文字和新文字
- 在檔案中執行文字替換
- 將結果返回給 Claude
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：要插入的文字

undo_edit

undo_edit 命令允許 Claude 還原對檔案所做的最後一次編輯。

此命令僅在 Claude Sonnet 3.7（已棄用）中可用。使用 text_editor_20250728 的 Claude 4 模型不支援此命令。

參數：

command：必須為 "undo_edit"
path：要還原最後一次編輯的檔案路徑

範例：使用文字編輯器工具修復語法錯誤

實作文字編輯器工具

文字編輯器工具是以無 schema 工具的形式實作的。使用此工具時，您不需要像其他工具一樣提供輸入 schema；schema 內建於 Claude 的模型中，無法修改。

工具類型取決於模型版本：

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

初始化您的編輯器實作
建立輔助函式來處理檔案操作，如讀取、寫入和修改檔案。考慮實作備份功能以從錯誤中恢復。

處理編輯器工具呼叫

建立一個函式，根據命令類型處理來自 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':
        # Read and return file contents
        pass
    elif command == 'str_replace':
        # Replace text in file
        pass
    elif command == 'create':
        # Create new file
        pass
    elif command == 'insert':
        # Insert text at location
        pass
    elif command == 'undo_edit':
        # Check if it's a Claude 4 model
        if 'str_replace_based_edit_tool' in model_version:
            return {"error": "undo_edit command is not supported in Claude 4"}
        # Restore from backup for Claude 3.7
        pass

實作安全措施
新增驗證和安全檢查：
- 驗證檔案路徑以防止目錄遍歷攻擊
- 在進行變更前建立備份
- 優雅地處理錯誤
- 實作權限檢查

處理 Claude 的回應

從 Claude 的回應中提取並處理工具呼叫：

# Process tool use in Claude's response
for content in response.content:
    if content.type == "tool_use":
        # Execute the tool based on command
        result = handle_editor_tool(content)
        
        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

實作文字編輯器工具時，請注意以下事項：

安全性：該工具可以存取您的本地檔案系統，因此請實作適當的安全措施。
備份：在允許編輯重要檔案之前，務必建立備份。
驗證：驗證所有輸入以防止意外變更。
唯一匹配：確保替換內容恰好匹配一個位置，以避免意外的編輯。

處理錯誤

使用文字編輯器工具時，可能會發生各種錯誤。以下是處理這些錯誤的指引：

遵循實作最佳實踐

定價與 token 使用量

The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using.

In addition to the base tokens, the following additional input tokens are needed for the text editor tool:

Tool	Additional input tokens
`text_editor_20250429` (Claude 4.x)	700 tokens
`text_editor_20250124` (Claude Sonnet 3.7 (deprecated))	700 tokens

如需更多關於工具定價的詳細資訊，請參閱工具使用定價。

將文字編輯器工具與其他工具整合

文字編輯器工具可以與其他 Claude 工具一起使用。組合工具時，請確保您：

將工具版本與您使用的模型相匹配
考慮請求中包含的所有工具的額外 token 使用量

變更日誌

日期	版本	變更
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 搭配使用的工具工作流程。

Bash 工具

使用 Claude 執行 shell 命令。

Was this page helpful?

工具

文字編輯器工具

了解如何使用 Anthropic 定義的文字編輯器工具來檢視和修改文字檔案。

模型相容性

模型	工具版本
Claude 4.x 模型	`text_editor_20250728`
Claude Sonnet 3.7（已棄用）	`text_editor_20250124`

適用於 Claude 4 模型的 text_editor_20250728 工具不包含 undo_edit 命令。如果您需要此功能，您需要使用 Claude Sonnet 3.7（已棄用）。

較舊的工具版本不保證與較新的模型向後相容。請始終使用與您的模型版本對應的工具版本。

何時使用文字編輯器工具

以下是一些使用文字編輯器工具的範例：

程式碼除錯：讓 Claude 識別並修復您程式碼中的錯誤，從語法錯誤到邏輯問題。
程式碼重構：讓 Claude 透過有針對性的編輯來改善您的程式碼結構、可讀性和效能。
文件生成：要求 Claude 為您的程式碼庫添加文件字串、註解或 README 檔案。
測試建立：讓 Claude 根據對實作的理解為您的程式碼建立單元測試。

使用文字編輯器工具

文字編輯器工具可以按以下方式使用：

向 Claude 提供文字編輯器工具和使用者提示
- 在您的 API 請求中包含文字編輯器工具
- 提供可能需要檢查或修改檔案的使用者提示，例如「你能修復我程式碼中的語法錯誤嗎？」
Claude 使用工具檢查檔案或目錄
- Claude 評估需要查看的內容，並使用 view 命令來檢查檔案內容或列出目錄內容
- API 回應將包含帶有 view 命令的 tool_use 內容區塊
執行檢視命令並返回結果
- 從 Claude 的工具使用請求中提取檔案或目錄路徑
- 讀取檔案內容或列出目錄內容
- 如果在工具配置中指定了 max_characters 參數，則將檔案內容截斷到該長度
- 透過繼續對話，使用包含 tool_result 內容區塊的新 user 訊息將結果返回給 Claude
Claude 使用工具修改檔案
- 在檢查檔案或目錄後，Claude 可能會使用 str_replace 等命令進行更改，或使用 insert 在特定行號添加文字。
- 如果 Claude 使用 str_replace 命令，Claude 會構建一個格式正確的工具使用請求，包含要替換的舊文字和新文字
執行編輯並返回結果
- 從 Claude 的工具使用請求中提取檔案路徑、舊文字和新文字
- 在檔案中執行文字替換
- 將結果返回給 Claude
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：要插入的文字

undo_edit

undo_edit 命令允許 Claude 還原對檔案所做的最後一次編輯。

此命令僅在 Claude Sonnet 3.7（已棄用）中可用。使用 text_editor_20250728 的 Claude 4 模型不支援此命令。

參數：

command：必須為 "undo_edit"
path：要還原最後一次編輯的檔案路徑

範例：使用文字編輯器工具修復語法錯誤

實作文字編輯器工具

文字編輯器工具是以無 schema 工具的形式實作的。使用此工具時，您不需要像其他工具一樣提供輸入 schema；schema 內建於 Claude 的模型中，無法修改。

工具類型取決於模型版本：

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

初始化您的編輯器實作
建立輔助函式來處理檔案操作，如讀取、寫入和修改檔案。考慮實作備份功能以從錯誤中恢復。

處理編輯器工具呼叫

建立一個函式，根據命令類型處理來自 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':
        # Read and return file contents
        pass
    elif command == 'str_replace':
        # Replace text in file
        pass
    elif command == 'create':
        # Create new file
        pass
    elif command == 'insert':
        # Insert text at location
        pass
    elif command == 'undo_edit':
        # Check if it's a Claude 4 model
        if 'str_replace_based_edit_tool' in model_version:
            return {"error": "undo_edit command is not supported in Claude 4"}
        # Restore from backup for Claude 3.7
        pass

實作安全措施
新增驗證和安全檢查：
- 驗證檔案路徑以防止目錄遍歷攻擊
- 在進行變更前建立備份
- 優雅地處理錯誤
- 實作權限檢查

處理 Claude 的回應

從 Claude 的回應中提取並處理工具呼叫：

# Process tool use in Claude's response
for content in response.content:
    if content.type == "tool_use":
        # Execute the tool based on command
        result = handle_editor_tool(content)
        
        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

實作文字編輯器工具時，請注意以下事項：

安全性：該工具可以存取您的本地檔案系統，因此請實作適當的安全措施。
備份：在允許編輯重要檔案之前，務必建立備份。
驗證：驗證所有輸入以防止意外變更。
唯一匹配：確保替換內容恰好匹配一個位置，以避免意外的編輯。

處理錯誤

使用文字編輯器工具時，可能會發生各種錯誤。以下是處理這些錯誤的指引：

遵循實作最佳實踐

定價與 token 使用量

The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using.

In addition to the base tokens, the following additional input tokens are needed for the text editor tool:

Tool	Additional input tokens
`text_editor_20250429` (Claude 4.x)	700 tokens
`text_editor_20250124` (Claude Sonnet 3.7 (deprecated))	700 tokens

如需更多關於工具定價的詳細資訊，請參閱工具使用定價。

將文字編輯器工具與其他工具整合

文字編輯器工具可以與其他 Claude 工具一起使用。組合工具時，請確保您：

將工具版本與您使用的模型相匹配
考慮請求中包含的所有工具的額外 token 使用量

變更日誌

日期	版本	變更
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 搭配使用的工具工作流程。

Bash 工具

使用 Claude 執行 shell 命令。

Was this page helpful?

模型相容性

何時使用文字編輯器工具

使用文字編輯器工具

文字編輯器工具命令

view

view 命令範例

str_replace

str_replace 命令範例

create

create 命令範例

insert

insert 命令範例

undo_edit

undo_edit 命令範例

範例：使用文字編輯器工具修復語法錯誤

實作文字編輯器工具

處理錯誤

找不到檔案

替換文字有多個匹配

替換文字無匹配

權限錯誤

遵循實作最佳實踐

提供清晰的上下文

明確指定檔案路徑

編輯前建立備份

謹慎處理唯一文字替換

驗證變更

定價與 token 使用量

將文字編輯器工具與其他工具整合

變更日誌

後續步驟

模型相容性

何時使用文字編輯器工具

使用文字編輯器工具

文字編輯器工具命令

view

view 命令範例

str_replace

str_replace 命令範例

create

create 命令範例

insert

insert 命令範例

undo_edit

undo_edit 命令範例

範例：使用文字編輯器工具修復語法錯誤

實作文字編輯器工具

處理錯誤

找不到檔案

替換文字有多個匹配

替換文字無匹配

權限錯誤

遵循實作最佳實踐

提供清晰的上下文

明確指定檔案路徑

編輯前建立備份

謹慎處理唯一文字替換

驗證變更

定價與 token 使用量

將文字編輯器工具與其他工具整合

變更日誌

後續步驟