Strumento editor di testo

Claude può utilizzare uno strumento editor di testo con schema Anthropic per visualizzare e modificare file di testo, aiutandoti a eseguire il debug, correggere e migliorare il tuo codice o altri documenti di testo. Questo consente a Claude di interagire direttamente con i tuoi file, fornendo assistenza pratica anziché limitarsi a suggerire modifiche.

Per il supporto dei modelli, consulta il Riferimento degli strumenti.

Quando usare lo strumento editor di testo

Alcuni esempi di quando usare lo strumento editor di testo sono:

• Debug del codice: Fai in modo che Claude identifichi e corregga i bug nel tuo codice, dagli errori di sintassi ai problemi di logica.
• Refactoring del codice: Lascia che Claude migliori la struttura, la leggibilità e le prestazioni del tuo codice attraverso modifiche mirate.
• Generazione di documentazione: Chiedi a Claude di aggiungere docstring, commenti o file README alla tua base di codice.
• Creazione di test: Fai in modo che Claude crei unit test per il tuo codice in base alla sua analisi dell'implementazione.

Usa lo strumento editor di testo

Fornisci lo strumento editor di testo (denominato str_replace_based_edit_tool) a Claude utilizzando la Messages API.

Puoi facoltativamente specificare un parametro max_characters per controllare il troncamento durante la visualizzazione di file di grandi dimensioni.

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)

Usa lo strumento editor di testo nel modo seguente:

1. 1

   Fornisci a Claude lo strumento editor di testo e un prompt utente

   • Includi lo strumento editor di testo nella tua richiesta API
   • Fornisci un prompt utente che potrebbe richiedere l'esame o la modifica di file, come "Puoi correggere l'errore di sintassi nel mio codice?"
2. 2

   Claude usa lo strumento per esaminare file o directory

   • Claude valuta cosa deve esaminare e usa il comando view per esaminare il contenuto dei file o elencare il contenuto delle directory
   • La risposta dell'API conterrà un blocco di contenuto tool_use con il comando view
3. 3

   Esegui il comando view e restituisci i risultati

   • Estrai il percorso del file o della directory dalla richiesta di uso degli strumenti di Claude
   • Leggi il contenuto del file o elenca il contenuto della directory
   • Se nella configurazione dello strumento è stato specificato un parametro max_characters, tronca il contenuto del file a quella lunghezza
   • Restituisci i risultati a Claude continuando la conversazione con un nuovo messaggio user contenente un blocco di contenuto tool_result
4. 4

   Claude usa lo strumento per modificare i file

   • Dopo aver esaminato il file o la directory, Claude può usare un comando come str_replace per apportare modifiche o insert per aggiungere testo a un numero di riga specifico.
   • Se Claude usa il comando str_replace, Claude costruisce una richiesta di uso degli strumenti correttamente formattata con il testo vecchio e il nuovo testo con cui sostituirlo
5. 5

   Esegui la modifica e restituisci i risultati

   • Estrai il percorso del file, il testo vecchio e il testo nuovo dalla richiesta di uso degli strumenti di Claude
   • Esegui la sostituzione del testo nel file
   • Restituisci i risultati a Claude
6. 6

   Claude fornisce la sua analisi e spiegazione

   • Dopo aver esaminato ed eventualmente modificato i file, Claude fornisce una spiegazione completa di ciò che ha trovato e delle modifiche che ha apportato

Comandi dello strumento editor di testo

Lo strumento editor di testo supporta diversi comandi per visualizzare e modificare i file:

view

Il comando view consente a Claude di esaminare il contenuto di un file o elencare il contenuto di una directory. Può leggere l'intero file o un intervallo specifico di righe.

Parametri:

• command: Deve essere "view"
• path: Il percorso del file o della directory da visualizzare
• view_range (facoltativo): Un array di due interi che specifica i numeri di riga iniziale e finale da visualizzare. I numeri di riga partono da 1, e -1 per la riga finale significa leggere fino alla fine del file. Questo parametro si applica solo alla visualizzazione di file, non di directory.

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

{
  "type": "tool_use",
  "id": "toolu_02B19r91rw91mr917835mr9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "view",
    "path": "src/"
  }
}

str_replace

Il comando str_replace consente a Claude di sostituire una stringa specifica in un file con una nuova stringa. Viene utilizzato per apportare modifiche precise.

Parametri:

• command: Deve essere "str_replace"
• path: Il percorso del file da modificare
• old_str: Il testo da sostituire (deve corrispondere esattamente, inclusi spazi bianchi e indentazione)
• new_str: Il nuovo testo da inserire al posto del testo vecchio

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "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):"
  }
}

create

Il comando create consente a Claude di creare un nuovo file con il contenuto specificato.

Parametri:

• command: Deve essere "create"
• path: Il percorso in cui deve essere creato il nuovo file
• file_text: Il contenuto da scrivere nel nuovo file

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "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

Il comando insert consente a Claude di inserire testo in una posizione specifica di un file.

Parametri:

• command: Deve essere "insert"
• path: Il percorso del file da modificare
• insert_line: Il numero di riga dopo il quale inserire il testo (0 per l'inizio del file)
• insert_text: Il testo da inserire

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "insert",
    "path": "primes.py",
    "insert_line": 0,
    "insert_text": "\"\"\"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"
  }
}

Esempio: Correggere un errore di sintassi con lo strumento editor di testo

Questo esempio dimostra come Claude usa lo strumento editor di testo per correggere un errore di sintassi in un file Python.

Innanzitutto, la tua applicazione fornisce a Claude lo strumento editor di testo e un prompt per correggere un errore di sintassi:

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 usa lo strumento editor di testo prima per visualizzare il file:

{
  "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"
      }
    }
  ]
}

La tua applicazione dovrebbe quindi leggere il file e restituirne il contenuto a 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 identifica l'errore di sintassi e usa il comando str_replace per correggerlo:

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

La tua applicazione dovrebbe quindi apportare la modifica e restituire il risultato:

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

Infine, Claude fornisce una spiegazione completa della correzione:

{
  "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."
    }
  ]
}

Implementa lo strumento editor di testo

Lo strumento editor di testo è implementato come strumento senza schema. Quando usi questo strumento, non devi fornire uno schema di input come per gli altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.

Il tipo di strumento è type: "text_editor_20250728" per Claude 4 e modelli successivi.

1. 1

   Inizializza la tua implementazione dell'editor

   Crea funzioni di supporto per gestire le operazioni sui file come lettura, scrittura e modifica dei file. Considera l'implementazione di una funzionalità di backup per recuperare dagli errori.

2. 2

   Gestisci le chiamate allo strumento editor

   Crea una funzione che elabora le chiamate agli strumenti da parte di Claude in base al tipo di comando:

   PythonTypeScriptC#GoJavaPHPRuby

   

   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":
               # Leggi e restituisci il contenuto del file
               pass
           case "str_replace":
               # Sostituisci il testo nel file
               pass
           case "create":
               # Crea un nuovo file
               pass
           case "insert":
               # Inserisci il testo nella posizione indicata
               pass

3. 3

   Implementa misure di sicurezza

   Aggiungi controlli di validazione e sicurezza:

   • Valida i percorsi dei file per prevenire il directory traversal
   • Crea backup prima di apportare modifiche
   • Gestisci gli errori in modo appropriato
   • Implementa controlli dei permessi
4. 4

   Elabora le risposte di Claude

   Estrai e gestisci le chiamate agli strumenti dalle risposte di Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Elabora l'uso degli strumenti nella risposta di Claude
   for content in response.content:
       if content.type == "tool_use":
           # Esegui lo strumento in base al comando
           result = handle_editor_tool(content)
   
           # Restituisci il risultato a Claude
           tool_result = {
               "type": "tool_result",
               "tool_use_id": content.id,
               "content": result,
           }

Gestisci gli errori

Quando usi lo strumento editor di testo, possono verificarsi vari errori. Ecco alcune indicazioni su come gestirli:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: File not found",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Found 3 matches for replacement text. Please provide more context to make a unique match.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: No match found for replacement. Please check your text and try again.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Permission denied. Cannot write to file.",
      "is_error": true
    }
  ]
}

Segui le best practice di implementazione

def backup_file(file_path):
    """Create a backup of a file before editing."""
    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):
    """Replace text only if there's exactly one match."""
    with open(file_path, "r") as f:
        content = f.read()

    count = content.count(old_text)
    if count == 0:
        return "Error: No match found"
    elif count > 1:
        return f"Error: Found {count} matches"
    else:
        new_content = content.replace(old_text, new_text)
        with open(file_path, "w") as f:
            f.write(new_content)
        return "Successfully replaced text"

def verify_changes(file_path):
    """Run tests or checks after making changes."""
    try:
        # Per i file Python, verifica la presenza di errori di sintassi
        if file_path.endswith(".py"):
            import ast

            with open(file_path, "r") as f:
                ast.parse(f.read())
            return "Syntax check passed"
    except Exception as e:
        return f"Verification failed: {str(e)}"

Prezzi e utilizzo dei token

Lo strumento editor di testo utilizza la stessa struttura di prezzi degli altri strumenti usati con Claude. Segue i prezzi standard dei token di input e output in base al modello Claude che stai utilizzando.

Oltre ai token di base, per lo strumento editor di testo sono necessari i seguenti token di input aggiuntivi:

Per informazioni più dettagliate sui prezzi degli strumenti, consulta Prezzi dell'uso degli strumenti.

Integra lo strumento editor di testo con altri strumenti

Puoi usare lo strumento editor di testo insieme ad altri strumenti di Claude. Quando combini gli strumenti, assicurati di:

• Abbinare la versione dello strumento al modello che stai utilizzando
• Tenere conto dell'utilizzo aggiuntivo di token per tutti gli strumenti inclusi nella tua richiesta

Registro delle modifiche

Passaggi successivi

Ecco alcune idee su come usare lo strumento editor di testo in modi più comodi e potenti:

• Integra con il tuo flusso di lavoro di sviluppo: Incorpora lo strumento editor di testo nei tuoi strumenti di sviluppo o IDE
• Crea un sistema di revisione del codice: Fai in modo che Claude riveda il tuo codice e apporti miglioramenti
• Costruisci un assistente per il debug: Crea un sistema in cui Claude possa aiutarti a diagnosticare e correggere problemi nel tuo codice
• Implementa la conversione di formati di file: Lascia che Claude ti aiuti a convertire file da un formato a un altro
• Automatizza la documentazione: Configura flussi di lavoro affinché Claude documenti automaticamente il tuo codice

Lo strumento editor di testo consente a Claude di lavorare direttamente con la tua base di codice, supportando flussi di lavoro dal debug alla documentazione automatizzata.