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)
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 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.
|