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
parent a81000912a
commit 2137150da3
12 changed files with 946 additions and 0 deletions
@@ -0,0 +1,89 @@
+# Context Injection Engine (Fase 2)
+
+L'estensione `agy-pi` include un motore avanzato di **Context Injection** che costruisce in tempo reale un blocco strutturato di contesto prima di ogni prompt inviato ad `agy`.
+
+---
+
+## Architettura del Blocco di Contesto
+
+Il blocco di contesto rispetta le best practice di **Context Engineering** per i modelli di grandi dimensioni (LLM):
+- Utilizzo di tag XML semantici.
+- Posizionamento della richiesta utente **sempre alla fine** del prompt per contrastare l'effetto *"Lost in the Middle"* (Liu et al., TACL 2024).
+- Gestione rigida del token budget (default 1500 token).
+
+```xml
+[CONTEXT_AGENTE] Contesto ambiente e stato corrente per la risposta. Usa solo se pertinente; la richiesta dell'utente è sotto.
+
+<environment_snapshot>
+cwd: /home/utente/progetto
+os: linux x64
+time: 2026-08-10T17:15:00.000Z
+git_branch: main (dirty)
+modified: src/index.ts | package.json
+</environment_snapshot>
+
+<session_state>
+Utente: Analizza la struttura di questo componente...
+Assistente: Ho controllato i file...
+</session_state>
+
+<durable_memory>
+goal: Implementare il nuovo modulo di autenticazione
+decisions: Usare token JWT con scadenza 1h | Database Postgres
+conventions: TypeScript strict mode
+</durable_memory>
+
+<web_context>
+[Risultati ricerca web Gemini grounding su topic pertinente]
+</web_context>
+
+--------------------------------
+[ RICHIESTA UTENTE ]
+```
+
+---
+
+## I 4 Moduli di Contesto
+
+### 1. `<environment_snapshot>`
+Estrae le informazioni dell'ambiente di lavoro corrente:
+- Directory di lavoro attiva (`cwd`).
+- Sistema operativo e architettura.
+- Data e ora correnti (ISO 8601).
+- Stato Git: branch corrente, indicatore `dirty` e lista fino agli ultimi 8 file modificati.
+
+### 2. `<session_state>`
+Recupera gli ultimi 3 messaggi dell'utente dalla sessione di `pi`. Il testo viene compresso e sanitizzato per evitare il bloat di token senza perdere il filo della conversazione.
+
+### 3. `<durable_memory>` (Memoria Persistente Automatica)
+Gestita tramite il file `~/.config/agy-pi/memory.json`:
+- Registra l'obiettivo primario del progetto (`goal`), le decisioni prese (`decisions`), le convenzioni di codice (`conventions`) e le questioni aperte (`openQuestions`).
+- **Auto-Update**: Quando la conversazione in `pi` supera i 24 turni, l'estensione estrae automaticamente i punti chiave e aggiorna `memory.json` per mantenere il contesto senza dover riinviare l'intero transcript.
+
+### 4. `<web_context>` (Strada A: Ricerca Web Integrata)
+Quando `webSearch` è impostato su `"auto"` o `"on"`, l'estensione valuta il prompt con la funzione euristica `needsWebSearch()`:
+
+#### Filtri Negativi (Non effettuano ricerca web):
+- Generazione ed editing di immagini (`agy_generate`, `agy_edit`, ecc.).
+- Task di codice locale o refactoring.
+- Comandi di gestione della conversazione o sintesi locale.
+
+#### Trigger Positivi (Attivano la ricerca web):
+- Riferimenti alla data/ora corrente (*"oggi"*, *"ultime notizie"*, *"2026"*).
+- Domande su versioni di pacchetti, dipendenze o release note.
+- Confronti tra tecnologie (*"differenza tra X e Y"*, *"migliore alternativa"*).
+- Notizie o fatti di attualità.
+
+La ricerca viene effettuata via API Gemini sfruttando la funzionalità di **Google Search Grounding**, ed i risultati vengono inseriti nel tag `<web_context>`.
+Un sistema di cache temporale evita ricerche identiche ripetute entro 60 secondi.
+
+---
+
+## Gestione del Token Budget (Token Cap)
+
+Il budget predefinito è di **1500 token**, suddiviso tra i diversi moduli:
+
+- `environment_snapshot`: max ~300 token.
+- `session_state`: max ~500 token.
+- `durable_memory`: max ~400 token.
+- `web_context`: max ~300 token.