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)
This commit is contained in:
@@ -0,0 +1,97 @@
|
||||
# Architettura di agy-pi
|
||||
|
||||
Questo documento descrive la struttura interna e il ciclo di vita dell'estensione `agy-pi`, spiegando l'interazione tra l'agente host (`pi`), l'estensione Node.js/TypeScript e il subagent CLI (`agy`).
|
||||
|
||||
---
|
||||
|
||||
## Architettura dei Componenti
|
||||
|
||||
L'estensione `agy-pi` fa da ponte tra l'ambiente di esecuzione di `pi` e la CLI `agy` / API Google Gemini:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor User as Utente / Tastiera (F12)
|
||||
participant PI as pi Agent Core
|
||||
participant EXT as agy-pi (extensions/index.ts)
|
||||
participant FFMPEG as ffmpeg & Audio Subsystem
|
||||
participant AGY as agy CLI (Antigravity)
|
||||
participant GEMINI as Google Gemini API
|
||||
|
||||
rect rgb(30, 40, 60)
|
||||
note over User, EXT: Workflow Vocale F12
|
||||
User->>EXT: Pressione F12 (Start Record)
|
||||
EXT->>FFMPEG: Spawn ffmpeg (pulse -> wav 16kHz)
|
||||
EXT->>User: Audio sound "start" (aevalsrc)
|
||||
User->>EXT: Pressione F12 (Stop Record)
|
||||
EXT->>FFMPEG: SIGINT & optimizeAudio (silenceremove)
|
||||
EXT->>GEMINI: POST generateContent (Audio Opus/OGG + STT)
|
||||
GEMINI-->>EXT: Trascrizione testuale
|
||||
EXT->>EXT: Legge editorText & unisce contesto sessione
|
||||
EXT->>AGY: Interpretation prompt via executeAgy()
|
||||
AGY-->>EXT: Testo interpretato finale
|
||||
EXT->>PI: sendUserMessage(finalText)
|
||||
end
|
||||
|
||||
rect rgb(40, 50, 30)
|
||||
note over PI, AGY: Tool Execution Workflow
|
||||
PI->>EXT: Execute Tool (es. agy_generate)
|
||||
EXT->>EXT: buildContextBlock() [Env + Memory + Web]
|
||||
EXT->>AGY: execFileAsync(agy -p prompt --output-format json)
|
||||
AGY-->>EXT: JSON Output & IMAGE_PATH
|
||||
EXT-->>PI: ToolResult { content, details }
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Moduli Funzionali
|
||||
|
||||
### 1. Engine di Gestione dello Stato e Persistenza
|
||||
|
||||
L'estensione mantiene lo stato sia in memoria sia su disco attraverso diverse strutture dati:
|
||||
|
||||
- **Conversazione agy Multi-Turno**:
|
||||
- `~/.agy-chat/conversation_id`: File di testo contenente l'ID dell'ultima conversazione attiva.
|
||||
- `~/.gemini/antigravity-cli/conversations/`: Cartella gestita dalla CLI `agy` contenente i file SQLite `.db` con la cronologia dei turni.
|
||||
- **Configurazione Persistente (`AgyConfig`)**:
|
||||
- `~/.config/agy-pi/config.json`: File protetto (permessi `0600`) che mantiene le preferenze di sistema (modello di default, backend STT/TTS, token budget, ecc.).
|
||||
- **Memoria Durevole (`DurableMemory`)**:
|
||||
- `~/.config/agy-pi/memory.json`: Archivio dei fatti rilevanti (obiettivi, decisioni, convenzioni, questioni aperte) aggiornato in modo automatico.
|
||||
|
||||
### 2. Wrapper di Esecuzione `executeAgy()`
|
||||
|
||||
Tutte le interazioni con il binario `agy` passano attraverso la funzione asincrona `executeAgy()`:
|
||||
|
||||
```typescript
|
||||
interface AgyExecOptions {
|
||||
prompt: string;
|
||||
mode?: "chat" | "image" | "analyze";
|
||||
model?: string;
|
||||
effort?: "low" | "medium" | "high";
|
||||
newConversation?: boolean;
|
||||
stateless?: boolean;
|
||||
addDirs?: string[];
|
||||
filePaths?: string[];
|
||||
yolo?: boolean;
|
||||
timeoutMs?: number;
|
||||
outputDir?: string;
|
||||
signal?: AbortSignal;
|
||||
contextBlock?: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### Risoluzione Bug Output Format (`--output-format json`)
|
||||
Quando `agy` viene eseguito in modalità non interattiva (piped/redirected), la CLI non scrive su `stdout` grezzo. Per superare questo limite, `executeAgy` aggiunge automaticamente il flag `--output-format json`, parsando la proprietà `.response` dell'oggetto ritornato.
|
||||
|
||||
---
|
||||
|
||||
## Ciclo di Vita di una Chiamata Tool
|
||||
|
||||
1. **Invocazione del Tool**: `pi` seleziona uno dei 13 tool registrati ed esegue il metodo `execute()`.
|
||||
2. **Costruzione del Prompt**: Il tool trasforma i parametri strutturati in un prompt narrativo (es. aggiungendo `IMAGE_PATH` o clausole `Keep+Change+Add+Render`).
|
||||
3. **Context Injection**: Se abilitato (`contextInject = true`), viene inserito il blocco `<CONTEXT_AGENTE>` preparato da `buildContextBlock()`.
|
||||
4. **Esecuzione CLI / API**: Invocazione del binario `agy` con gestione dei timeout (3 min per chat/analisi, 5 min per immagini).
|
||||
5. **Post-Processing Asset**: Se viene generata un'immagine, la funzione `extractImagePath()` rileva il percorso dall'output e `copyImage()` lo duplica eventualmente nella cartella di destinazione `outputDir`.
|
||||
6. **Aggiornamento Stato**: Se la chiamata è stateful, l'ID della conversazione viene aggiornato in `~/.agy-chat/conversation_id`.
|
||||
7. **Ritorno a pi**: Restituzione del risultato formattato secondo la specifica di `pi` (`{ content, details }`).
|
||||
Reference in New Issue
Block a user