Limitazioni e vincoli

File binari non supportati

Gli strumenti per i file di Verdent funzionano solo con formati basati su testo. I seguenti non possono essere modificati:

Soluzione alternativa: i file binari possono essere referenziati nel codice o discussi a livello concettuale, ma le modifiche richiedono strumenti esterni.

Limiti di righe di file_read

Limitazione:

• I file di grandi dimensioni (>10.000 righe) dovrebbero essere letti in sezioni
• La lettura di interi file di grandi dimensioni può esaurire il contesto

Soluzione: usa gli intervalli di righe: file_read("file.js", start_line=100, max_lines=50)

Timeout dei comandi bash

Limitazione:

• Timeout massimo: 120 secondi (2 minuti)
• Le operazioni di lunga durata verranno terminate automaticamente

Soluzione: suddividi le operazioni in comandi più piccoli che si completano entro 2 minuti

Prestazioni della ricerca

Limitazione:

• I pattern glob ampi (**/*) possono restituire migliaia di risultati
• Le ricerche con espressioni regolari sono più lente delle stringhe letterali

Soluzione: usa pattern specifici ed escludi le directory non necessarie

Esaurimento del contesto

Problema: durante sessioni lunghe o operazioni complesse, la finestra di contesto dell'AI può riempirsi, limitando la capacità di riferirsi alle parti precedenti della conversazione.

Strategie di mitigazione:

• Usa i sottoagenti per la ricerca esplorativa (solo i risultati consumano il contesto principale)
• Leggi i file in modo strategico con gli intervalli di righe
• Usa grep_file prima di leggere l'intero contenuto
• Delega le attività in background al sottoagente Explorer

Nessuna amministrazione di sistema diretta

Non può:

• Modificare le impostazioni di VS Code a livello programmatico
• Installare automaticamente estensioni di VS Code
• Modificare configurazioni a livello di sistema
• Riavviare VS Code o i servizi di sistema

Ambito: Verdent opera all'interno del workspace di VS Code, non a livello di amministrazione di sistema.

Nessuna esecuzione autonoma

Controlli di Manual Accept Mode:

• Gli utenti devono approvare le esecuzioni degli strumenti in Manual Accept Mode
• Nessuna operazione automatica in background senza approvazione
• Non può eseguire comandi mentre VS Code è chiuso

Scopo: sicurezza e controllo dell'utente su tutte le operazioni.

Nessun monitoraggio in tempo reale

Non può:

• Monitorare i processi in esecuzione in modo continuo
• Tracciare le modifiche al file system in tempo reale
• Avvisare in caso di eventi di sistema
• Trasmettere i file di log in modo continuo

Alternativa: usa le integrazioni MCP per strumenti di monitoraggio esterni.

Nessuna operazione di rete senza MCP

Limitazioni integrate:

• Non può effettuare richieste HTTP arbitrarie (usa web_fetch per pagine specifiche)
• Nessuna connessione diretta al database (richiede MCP)
• Non può accedere direttamente ai servizi cloud (richiede MCP)
• Nessuna integrazione API in tempo reale (richiede MCP)

Soluzione: configura i server MCP per l'accesso a sistemi esterni.

Modifica di file binari

Limitazione: non può modificare immagini, PDF o binari compilati

Soluzioni alternative:

• Fai riferimento a strumenti esterni nei comandi bash: bash("convert input.png -resize 50% output.png")
• Genera script che gli strumenti esterni possano eseguire
• Documenta i passaggi manuali per le operazioni sui file binari

Esempio:

# Image conversion
bash("convert input.png -resize 50% output.png")

# PDF to text
bash("pdftotext document.pdf output.txt")

Gestione dei file di grandi dimensioni

Limitazione: i file con più di 10.000 righe mettono sotto pressione la finestra di contesto

Soluzioni alternative:

• Usa gli intervalli di righe: file_read("large.log", start_line=1000, max_lines=100)
• Cerca prima: grep_content("ERROR", glob="large.log") per trovare le sezioni rilevanti
• Suddividi i file in moduli più piccoli per una gestione più semplice

Esaurimento della finestra di contesto

Limitazione: le conversazioni lunghe riempiono la finestra di contesto

Soluzioni alternative:

• Delega al sottoagente Explorer per la ricerca nella codebase
• Usa il sottoagente Verifier per attività di validazione isolate
• Avvia una nuova conversazione per attività distinte
• Usa todo_update per tracciare l'avanzamento tra le sessioni

Best practice: delega la ricerca in background ai sottoagenti per preservare il contesto principale per lo sviluppo attivo.

Differenze tra i comandi delle piattaforme

Limitazione: i comandi bash differiscono tra Windows e Unix

Soluzioni alternative:

• Usa strumenti multipiattaforma: script npm invece di bash puro
• Comandi condizionali: bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
• AGENTS.md specifico per il progetto con note sulla piattaforma

Esempio:

# Cross-platform
bash("npm run build")

# Platform-specific conditional
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then make; else nmake; fi")