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)
3.6 KiB
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).
[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
dirtye 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
pisupera i 24 turni, l'estensione estrae automaticamente i punti chiave e aggiornamemory.jsonper 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.