enne2
2137150da3
- 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)
98 lines
4.4 KiB
Markdown
98 lines
4.4 KiB
Markdown
# 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 }`).
|