Riferimento del sistema di strumenti

file_read

Funzionalità:

• Legge il contenuto completo dei file o intervalli di righe specifici
• Essenziale per comprendere il codice prima delle modifiche
• Gestione efficiente di file di grandi dimensioni tramite specifica degli intervalli

Casi d'uso:

• Leggere file di configurazione prima di modificarli
• Comprendere i pattern di implementazione esistenti
• Esaminare i file di test per capire la copertura

Esempio:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Funzionalità:

• Sostituzione precisa del testo tramite corrispondenza esatta delle stringhe
• Operazioni di sostituzione multiple con il flag multiple
• Preserva la struttura e la formattazione dei file

Casi d'uso:

• Aggiornare le implementazioni delle funzioni
• Modificare i valori di configurazione
• Rinominare le variabili tramite refactoring nei file

Buona pratica: usalo per modifiche mirate. Per riscritture complete, usa invece file_write.

file_write

Funzionalità:

• Crea nuovi file da zero
• Sostituisce completamente il contenuto dei file esistenti
• Gestisce qualsiasi formato basato su testo

Casi d'uso:

• Generare nuovi componenti o moduli
• Creare file di configurazione
• Scrivere file di test

Attenzione: sovrascrive completamente i file esistenti. Usa file_edit per modifiche parziali.

glob

Funzionalità:

• Trova file che corrispondono a pattern: **/*.ts, src/**/*.js
• Filtra per percorso di directory
• Esclude pattern per restringere i risultati
• Controlla il numero di risultati

Casi d'uso:

• Trovare tutti i componenti di un progetto
• Individuare i file di test
• Identificare i file di configurazione tra le directory

Esempi di pattern:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Funzionalità:

• Cerca il contenuto dei file usando pattern regex
• Mostra righe di contesto prima/dopo le corrispondenze (flag -B, -A)
• Ricerca case-insensitive
• Filtra per tipo di file usando pattern glob

Casi d'uso:

• Trovare definizioni di funzioni
• Individuare implementazioni di endpoint API
• Cercare messaggi di errore specifici
• Identificare pattern di sicurezza

Esempio:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Funzionalità:

• Elenca i file contenenti corrispondenze di pattern
• Più veloce di grep_content quando ti servono solo le posizioni dei file
• Supporto per pattern regex
• Filtro glob per tipi di file

Casi d'uso:

• Identificare quali file necessitano di refactoring
• Trovare i file che importano moduli specifici
• Individuare i file con pattern deprecati

Buona pratica: usa prima grep_file per identificare i file rilevanti, poi file_read per un esame dettagliato.

list_dir

Funzionalità:

• Mostra la gerarchia delle directory
• Controlla la profondità con il parametro max_depth
• Esclude pattern per filtrare l'output

Casi d'uso:

• Comprendere la struttura del progetto
• Verificare l'organizzazione delle directory
• Trovare sottodirectory specifiche

bash

Funzionalità:

• Esegue comandi shell
• Timeout massimo: 120 secondi (2 minuti, limite fisso)
• Concatena comandi con && per le dipendenze
• Fornisce riepiloghi descrittivi per maggiore chiarezza

Casi d'uso:

• Eseguire test
• Compilare progetti
• Installare dipendenze
• Operazioni Git
• Migrazioni di database

Esempio:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Sicurezza: i comandi vengono eseguiti con i permessi dell'utente. Rivedi i comandi in Manual Accept Mode.

spawn_subagent

Funzionalità:

• Avvia sottoagenti specializzati con contesti isolati
• Tipi: explorer, verifier, code-reviewer
• Delega attività complesse senza inquinare il contesto principale
• Esecuzione parallela di sottoagenti per maggiore efficienza

Casi d'uso:

• explorer: cercare pattern in codebase di grandi dimensioni
• verifier: validare la logica di implementazione
• code-reviewer: valutazione di sicurezza e qualità

Buona pratica: delega la ricerca esplorativa al sottoagente Explorer per preservare il contesto della conversazione principale.

todo_update

Funzionalità:

• Crea e gestisce elenchi di attività
• Aggiorna lo stato delle attività (pending, in_progress, completed)
• Tiene traccia dell'avanzamento in implementazioni complesse

Casi d'uso:

• Suddividere funzionalità in più passaggi
• Monitorare l'avanzamento del refactoring
• Gestire le attività di migrazione

web_search

Funzionalità:

• Interroga i motori di ricerca su Internet
• Controlla il numero di risultati
• Filtra per attualità (giorni recenti)

Casi d'uso:

• Trovare documentazione per API sconosciute
• Ricercare messaggi di errore
• Verificare le migliori pratiche attuali

web_fetch

Funzionalità:

• Recupera il contenuto delle pagine web
• Analizza il contenuto con query specifiche
• Estrae informazioni strutturate

Casi d'uso:

• Leggere pagine di documentazione
• Analizzare la documentazione API
• Estrarre esempi dai tutorial

Formati di dati

File di build e di pacchetto

Efficienza di file_read

Migliori pratiche:

• Usa intervalli di righe per file di oltre 500 righe per evitare il sovraccarico del contesto
• Leggi solo le sezioni rilevanti per l'attività
• Per i file di grandi dimensioni, usa prima grep_content per identificare i numeri di riga rilevanti

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

Precisione di file_edit

Migliori pratiche:

• Assicurati che le corrispondenze delle stringhe siano esatte per evitare modifiche fallite
• Per più modifiche simili, usa il flag multiple=true
• Verifica i percorsi dei file prima di modificarli

Sicurezza di file_write

Migliori pratiche:

• Controlla attentamente i percorsi per evitare sovrascritture accidentali
• Usalo solo per nuovi file o riscritture complete
• Per le modifiche, preferisci file_edit per maggiore sicurezza

Specificità dei pattern glob

Migliori pratiche:

• Usa pattern specifici per restringere l'ambito: src/**/*.ts invece di **/*
• Escludi le directory con pattern di esclusione: !**/node_modules/**
• Limita i risultati per evitare un output eccessivo

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

Strategia grep

Flusso di lavoro consigliato:

1. Usa grep_file per identificare i file rilevanti
2. Leggi i file specifici con file_read
3. Usa grep_content quando hai bisogno del contesto circostante

Consigli sulle prestazioni:

• I pattern regex possono richiedere più tempo delle stringhe letterali
• Le ricerche case-insensitive sono più lente
• Limita le righe di contesto (-A, -B) a quelle necessarie

Migliori pratiche per bash

Esecuzione sicura dei comandi:

• Fornisci riepiloghi chiari per le descrizioni dei comandi
• Imposta timeout appropriati per le operazioni di lunga durata
• Concatena i comandi dipendenti con &&
• Rivedi attentamente i comandi distruttivi (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Considerazioni sulla sicurezza

Regole di sicurezza fondamentali:

• I comandi vengono eseguiti con i permessi dell'utente
• Non eseguire mai comandi non attendibili
• Usa Manual Accept Mode per la revisione nelle codebase condivise
• Evita comandi che espongono credenziali o dati sensibili

Efficienza nella delega ai sottoagenti

Quando usare i sottoagenti:

• Explorer: ricerche nella codebase, domande sull'architettura (risparmia il contesto principale)
• Verifier: controlli di validazione rapidi (verifica isolata)
• Code-reviewer: revisioni di sicurezza e qualità (analisi dettagliata)
• General: attività complesse in più passaggi (esecuzione parallela)

Buona pratica: Delega le attività esplorative e di ricerca ai sottoagenti per preservare il contesto della conversazione principale per il lavoro di sviluppo attivo.

Gestione del contesto

Uso strategico degli strumenti:

• Leggi i file in modo strategico, solo ciò che serve
• Usa i sottoagenti per la ricerca in background
• Monitora il consumo del contesto durante le sessioni lunghe
• Suddividi le operazioni complesse in passaggi con todo_update

Flussi di lavoro efficienti:

1. Pianificazione: usa glob/grep per identificare l'ambito
2. Lettura: leggi solo i file/sezioni rilevanti
3. Esecuzione: delega ai sottoagenti quando appropriato
4. Verifica: controlli rapidi con il sottoagente Verifier

Limiti sulle dimensioni dei file

Gestione dei file di grandi dimensioni: I file molto grandi (>10.000 righe) dovrebbero essere letti a sezioni per evitare:

• Esaurimento della finestra di contesto
• Tempi di risposta lenti
• Problemi di memoria

Timeout predefiniti degli strumenti

Limiti degli strumenti:

• Timeout di bash: 120 secondi (2 minuti) al massimo
• Operazioni sui file: nessun limite di dimensione (i file di grandi dimensioni vengono letti automaticamente a blocchi)
• Gestione dei file di grandi dimensioni: i file >256KB restituiscono solo i primi 256KB di contenuto
• Risultati di ricerca: nessun limite sui risultati di glob o grep_content
• Sottoagenti concorrenti: nessun limite sull'esecuzione parallela

Configurazione del timeout:

• Imposta timeout espliciti per le operazioni di lunga durata
• Monitora i processi bloccati
• I comandi che superano il timeout di 2 minuti verranno terminati

Operazioni concorrenti

Esecuzione parallela: Più sottoagenti possono essere eseguiti in parallelo per operazioni complesse più veloci. L'agente principale gestisce automaticamente il coordinamento.

Vantaggi in termini di prestazioni:

• Riduzione del tempo totale di esecuzione per le attività in più passaggi
• Utilizzo efficiente delle risorse
• Orchestrazione automatica delle attività
• Nessun limite sul numero di sottoagenti concorrenti