refactor: remove direct Gemini API integrations

Route F12 and audio transcription exclusively through Antigravity OAuth, and preserve cross-model history without reusing incompatible signatures.\n\nRemove direct Gemini API keys, web grounding, internal TTS, verified image generation, obsolete commands and configuration. Update documentation and restore the local voice workflow helpers required at runtime.
2026-09-03 12:52:13 +02:00
parent cde5aaa9b7
commit 4a88084b2b
13 changed files with 198 additions and 2197 deletions
@@ -1,67 +1,23 @@
-# Troubleshooting & Diagnostica
+# Troubleshooting

-Guida alla risoluzione dei problemi comuni durante l'utilizzo dell'estensione `agy-pi`.
+## `/agy:status`

---
+Usa `/agy:status` per verificare il binario `agy`, la versione, il modello configurato, la pipeline audio Antigravity e l'ultimo errore dai log.

-## 1. Strumento Diagnostico Integrato (`/agy:status`)
+## Problemi comuni

-Prima di procedere con la ricerca manuale dei guasti, esegui il comando slash dentro `pi`:
+### `agy` non trovato

-```
-/agy:status
-```
+Installa il client e completa il login OAuth, oppure imposta `agyBin` con `/agy:config set agyBin <percorso>`.

-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`.
+### F12 non trascrive

---
+Verifica microfono/PulseAudio e `ffmpeg`. Se viene rilevato silenzio, registra di nuovo con volume più alto. Se Antigravity fallisce, controlla autenticazione e quota dell'account con `/agy:status`.

-## 2. Problemi Frequenti e Soluzioni
+### Immagine non trovata

-### 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
-  ```
+Controlla l'output del tool agy e che la directory di destinazione sia scrivibile.

-### 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`.
+## Log

-### 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:
-
-```bash
-ls -t ~/.gemini/antigravity-cli/log/* | head -1 | xargs tail -n 50
-```
+I log del client Antigravity sono sotto `~/.gemini/antigravity-cli/log`.