Files

T

enne2 2137150da3 docs: documentazione MkDocs completa + fix build + verifica OpenCV dinamica

- Aggiunti docs/ (9 pagine MkDocs, tema Material) + mkdocs.yml
- Fix mkdocs.yml: repo_url -> git.enne2.net, tasklist (era taskbuttons),
  fence Mermaid via helper locale mermaid_fence.py (def_fence_mermaid
  rimosso da pymdown-extensions moderne)
- Documentate le nuove funzionalità: agy_create_verified (generazione
  verificata con verifica OpenCV DINAMICA generata dall'LLM), workflow
  vocale a 2 fasi (vocalPlanningMode), chiavi config context/webSearch
- tools.md ora documenta 14 tool; vocal-workflow.md include l'overlay di
  conferma piano; configuration.md include vocalPlanningMode
- .gitignore: esclusi site/ e __pycache__/
- Build MkDocs verificata (site/ generato correttamente)

2026-08-11 00:47:23 +02:00

2.6 KiB

Raw Blame History

Troubleshooting & Diagnostica

Guida alla risoluzione dei problemi comuni durante l'utilizzo dell'estensione agy-pi.

1. Strumento Diagnostico Integrato (`/agy:status`)

Prima di procedere con la ricerca manuale dei guasti, esegui il comando slash dentro pi:

/agy:status

L'overlay TUI diagnostico verificherà automaticamente:

Esistenza e versione dell'eseguibile agy.
Presenza e validità della chiave API Gemini.
Backend STT e stato notifiche TTS attivi.
Ultimo messaggio di errore registrato nei log di agy.

2. Problemi Frequenti e Soluzioni

A. Binario `agy` non trovato (`bash: agy: command not found`)

Causa: Il binario agy non si trova nel PATH di sistema o nell'ubicazione standard ~/.local/bin/agy.
Soluzione: Imposta il percorso esplicito dell'eseguibile:
```
/agy:config set agyBin /percorso/assoluto/a/agy
```

B. Registrazione vocale F12 fallita o senza audio

Causa 1: ffmpeg non è installato nel sistema.
- Soluzione: Installa ffmpeg tramite il package manager della tua distribuzione (es. sudo apt install ffmpeg).
Causa 2: Nessun parlato rilevato (audioHasSpeech ritorna errore).
- Soluzione: Verifica il microfono e alza il livello di guadagno di PulseAudio/ALSA.
Causa 3: Mancanza dell'utility di riproduzione audio PulseAudio (paplay).
- Soluzione: Installa pulseaudio-utils oppure lascia che il sistema usi il fallback automatico aplay / ffplay.

C. Errore API Gemini o Key Mancante (`HTTP 401` / `HTTP 403`)

Causa: La chiave API Gemini non è stata inserita o è scaduta.
Soluzione: Apri l'overlay grafico per configurare la chiave in modo sicuro:
```
/agy:key
```

D. Immagine generata non trovata (`IMAGE_PATH` assente)

Causa: agy ha completato l'operazione ma non ha restituito il pattern IMAGE_PATH o il modello non ha generato un file su disco.
Soluzione: Aumenta il timeout di generazione portando agyTimeoutMs a 300000 (5 minuti) o imposta stateless: true.

E. Errore HTTP 413 (`Payload Too Large`) durante la trascrizione audio

Causa: File audio di grandi dimensioni inviato in formato WAV grezzo.
Soluzione: L'estensione converte automaticamente i WAV in formato Opus/OGG (libopus a 16kbps). Assicurati che ffmpeg sia compilato con supporto a libopus o libmp3lame.

3. Ispezione dei Log

I log dettagliati delle interazioni della CLI agy sono memorizzati in:

~/.gemini/antigravity-cli/log/

Per visualizzare l'ultimo errore di sistema:

ls -t ~/.gemini/antigravity-cli/log/* | head -1 | xargs tail -n 50

2.6 KiB Raw Blame History

Troubleshooting & Diagnostica

1. Strumento Diagnostico Integrato (/agy:status)

2. Problemi Frequenti e Soluzioni

A. Binario agy non trovato (bash: agy: command not found)