# Integrazione knowledge base e orchestrator su `.53` ## Scopo Questo runbook serve a integrare sulla macchina `192.168.0.53` una memoria condivisa piu strutturata, partendo da due progetti open source gia individuati: - `knowledge-base-server` - `agent-orchestrator` L obiettivo non e sostituire il repository Day0 o Gitea. L obiettivo e aggiungere sopra il flusso gia esistente un livello di retrieval e coordinamento agent che renda piu facile: - recuperare decisioni, fix e runbook senza ricostruire il contesto a mano - condividere la stessa base di conoscenza tra agent diversi e macchine diverse - usare `.53` come nodo centrale non solo Git, ma anche come cervello operativo condiviso ## Stato di partenza confermato - il repository autorevole resta `netgescon-day0` - il remote autorevole resta `origin -> ssh://git@192.168.0.53:2222/michele/netgescon-day0.git` - `docs/` resta la memoria operativa ufficiale del progetto - `.53` e gia il nodo centrale piu naturale per Gitea e coordinamento rete - `knowledge-base-server` sulla `.53` e gia installato, avviato e raggiungibile su `http://192.168.0.53:3838` - l health endpoint operativo e `http://192.168.0.53:3838/api/v1/health` - l orchestrator non va centralizzato sulla `.53`: la scelta confermata e orchestrator locale per macchina/progetto ## Topologia confermata - `.53` = KB centrale + Gitea + nodo conoscenza condivisa - `.200` = orchestrator locale per `NetGescon` - `.205` = orchestrator locale per `NetLabel` Questa separazione e importante: - la `.53` non deve diventare il terminale unico che esegue tutti i task agent - la `.53` deve restare il centro di conoscenza, retrieval e coordinamento - le macchine progetto eseguono i task locali interrogando il KB centrale ## Ruoli dei tre livelli ### 1. Git e Gitea Restano la fonte di verita per: - codice - documentazione ufficiale in `docs/` - cronologia versionata - distribuzione verso staging e altri nodi Regola: - se una cosa deve essere ufficiale, auditabile e versionata, deve vivere prima in Day0 e poi su Gitea ### 2. Knowledge Base Server Va usato come layer di indicizzazione, ricerca e memoria operativa sopra il materiale ufficiale. Ruolo atteso: - indicizzare `docs/`, runbook, note operative e materiale di scambio selezionato - catturare sessioni, fix, decisioni e lezioni apprese - servire contesto a piu agent via MCP o REST - dare retrieval piu rapido di file lunghi o dispersi Regola: - il KB non sostituisce Git - il KB accelera ricerca, richiamo e sintesi della conoscenza gia validata o da promuovere ### 3. Agent Orchestrator Va trattato come livello di coordinamento runtime tra agent diversi. Ruolo atteso: - scegliere quale agent usare per pianificazione, implementazione, review o documentazione - fare failover quando un agent e fermo o limitato - interrogare il KB prima di rispondere Regola: - l orchestrator non deve inventare stato proprio fuori da Git e KB - task, prompt e output rilevanti devono ricadere in `docs/` o nel KB, non restare solo nel terminale ## Architettura minima consigliata per NetGescon ```text Day0 workspace -> Git commit -> Gitea su .53 | +-> docs/ e runbook ufficiali Gitea / mirror docs -> Knowledge Base Server su .53 | +-> ricerca BM25/semantica +-> MCP / REST +-> capture session/fix/decision Agent Orchestrator -> Claude / Codex / Gemini | +-> query al KB prima del lavoro +-> esecuzione per ruolo +-> ritorno dei risultati su docs/Git ``` ## Decisione operativa importante Per NetGescon il punto di verita deve restare doppio ma ordinato: 1. `docs/` e Git per la conoscenza ufficiale e condivisa 2. KB server per retrieval, sintesi, memoria calda e cattura operativa Questa distinzione evita il problema principale: - se il KB diventa l unico posto dove vivere, perdiamo auditabilita Git - se tutto resta solo in Markdown senza retrieval, la conoscenza cresce ma diventa difficile da usare ## Cosa ingestire per primi Prima fase consigliata sulla `.53`: 1. `docs/README.md` 2. `docs/00-INDICE-LAVORO-DISTRIBUITO.md` 3. `docs/support/` 4. `scripts/ai/` solo per gli script realmente in uso 5. eventuale materiale in `Scambio/` o share SMB solo dopo selezione minima Regola di igiene: - non ingestire tutta la share di rete in blocco al primo passaggio - prima selezionare i file che contengono runbook, analisi, handoff o specifiche utili - escludere dump rumorosi, duplicati, export casuali o file binari non classificati ## Cosa NON fare nella prima fase - non duplicare tutto il repository applicativo dentro il KB senza criterio - non usare il KB come archivio cieco di qualsiasi file di scambio - non lasciare che sessioni agent importanti restino solo nel KB se richiedono una traccia ufficiale in `docs/` - non installare l orchestrator con permessi troppo larghi su una macchina non ancora considerata trusted per automazione completa ## Modello operativo pratico ### Fase A - bootstrap della conoscenza Obiettivo: - portare nel KB solo la base operativa che oggi e gia stabile Checklist: 1. usare la `.53` come endpoint KB centrale gia disponibile, senza duplicare un secondo KB altrove 2. creare o confermare un path sorgente chiaro per il mirror docs su `.53` 3. ingestire la base `docs/` minima e verificare le prime query 4. mantenere credenziali e API key operative fuori dal repository versionato ### Fase B - cattura delle sessioni utili Obiettivo: - iniziare a registrare fix, decisioni e handoff tecnici in modo coerente Checklist: 1. definire convenzione minima per `session`, `fix`, `decision`, `runbook` 2. stabilire quali output devono finire prima in `docs/` e quali possono restare solo nel KB 3. collegare le note piu utili al progetto o stream corretto ### Fase C - orchestrazione multi-agent Obiettivo: - usare l orchestrator per lavorare su task distinti con retrieval automatico dal KB Checklist: 1. installare l orchestrator locale sulla macchina progetto, non sulla `.53` 2. definire almeno 4 ruoli: `orchestrator`, `implementation`, `review`, `uidocs` 3. definire una radice task condivisa coerente con NetGescon 4. verificare che ogni task richiami sempre il KB centrale `.53` Nota pratica sul pacchetto scelto: - per il rollout attuale e stato indicato il pacchetto PyPI `agent-orchestrator` con repository `https://github.com/luhfilho/agent-orchestrator` - questo upstream dichiara come prerequisiti `Claude` e `Gemini` - in pratica possiamo comunque avviare il setup macchina e il primo bootstrap anche con il solo `Gemini` gia autenticato - la parte `dual-agent` completa e il test di tutti gli agent richiedono anche `Claude` Regola operativa consigliata: 1. installare subito `agent-orchestrator` 2. collegare subito `Gemini` se l autenticazione Google e gia disponibile 3. aggiungere `Claude` quando sara disponibile un account Anthropic compatibile con Claude Code Nota sui comandi CLI: - per `Gemini` il pacchetto npm corretto e `@google/gemini-cli` - per `Claude` usare il pacchetto ufficiale `@anthropic-ai/claude-code` oppure l installer ufficiale Anthropic - evitare `sudo npm install -g` per Claude Code ## Collegamento con il materiale SMB `scambio/200` Lo share SMB puo diventare sorgente di materiale grezzo o semilavorato, ma non va trattato subito come fonte autorevole. Uso corretto: - inbox tecnica - handoff tra macchine - allegati da promuovere - materiale esterno da classificare e sintetizzare Uso scorretto: - sostituire `docs/` - sostituire Git - lasciare file importanti solo nello share senza promozione in `docs/` o KB ## Path confermati per `.200` Path logici confermati per la macchina `.200`: - percorso logico share: `//192.168.0.53/Scambio/200` - percorso workspace centrale dichiarato: `/home/michele/netgescon-git/Scambio/200` Regola pratica: - `docs/` resta il patrimonio tecnico di progetto - `Scambio/200` resta area operativa, inbox tecnica, handoff rapido e materiale di avvio macchina - dopo registrazione chiave macchina, il workspace quotidiano puo essere spostato da SMB guest a mount `SSHFS` fidati verso `.53` ## Risposte operative confermate ### Priorita architetturale 1. il `knowledge-base-server` sulla `.53` e gia attivo e va considerato il KB centrale di rete 2. l `agent-orchestrator` va tenuto locale alla macchina/progetto: `.200` per `NetGescon`, `.205` per `NetLabel` 3. il KB va usato prima di tutto come cervello condiviso per agent, ma puo restare anche dashboard umana consultabile ### Sorgenti da ingestire 1. per `.200` il riferimento dichiarato e `//192.168.0.53/Scambio/200`, con workspace centrale `/home/michele/netgescon-git/Scambio/200` 2. le prime priorita non sono cartelle generiche ma documenti operativi mirati dentro `Scambio/200` 3. in prima fase conviene promuovere documentazione, istruzioni macchina, handoff e runbook; il materiale piu grezzo va selezionato prima della promozione ### Modello di conoscenza 1. `docs/` e la sorgente primaria; `Scambio/` e inbox tecnica e area handoff 2. la tassonomia minima va trattata almeno come `runbook`, `fix`, `decision`, `roadmap`, `handoff`, `ricerca` 3. la separazione per stream va introdotta subito almeno a livello logico ### Stream iniziali confermati 1. `core-anagrafica` 2. `immobili-unita-import` 3. `ticket-operativita` 4. `banca-contabilita-fe` 5. `aggiornamenti-distribuzione` 6. `api-moduli-integrazioni` 7. `netlabel-etichette` 8. `netlabel-waba-webhook` 9. `pbx-telefonia` 10. `infrastruttura-gitea-dns-edge-kb` ## Documenti prioritari iniziali in `Scambio/200` Per `.200` i primi documenti da promuovere o usare come bootstrap sono: 1. `ISTRUZIONI_AGENT_200_NETGESCON.md` 2. `ACCESSO_KB_CENTRALE_DA_200.md` 3. `PRIMO_CANTIERE_200_STABILIZZAZIONE_E_CONDIVISIONE.md` 4. `PROPOSTA_CATTURA_AUTOMATICA_DA_200.md` 5. `RISPOSTE_AGENT_200_KB_ORCHESTRATOR_E_ACCESSO.md` Nota: - eventuali token, API key o credenziali presenti nei documenti di scambio non vanno riportati in `docs/` versionato - in `docs/` va riportata la procedura, non il segreto operativo ## Primo criterio di successo Questo cantiere puo dirsi avviato bene quando sulla `.53` otteniamo insieme questi risultati minimi: 1. il KB server indicizza almeno i file base di `docs/` 2. una query dal KB trova correttamente i runbook su `.53`, Gitea e docs distribuite 3. l orchestrator o un agent singolo riesce a leggere quel contesto prima di lavorare 4. almeno un esito operativo viene riportato sia nel KB sia nel repository Day0 ## Prossimo passo consigliato Il prossimo passo pratico per `.200` e questo: 1. verificare l accesso dal client `.200` al KB centrale `.53` 2. installare l orchestrator locale sulla `.200` 3. configurarlo per usare il KB centrale `.53` 4. promuovere nel KB i cinque documenti bootstrap di `Scambio/200` 5. partire dal primo stream `core-anagrafica`, poi `ticket-operativita`, poi `banca-contabilita-fe` ## Script di bootstrap replicabile Per rendere il setup riusabile sulle altre macchine e disponibile uno script locale: - `scripts/ops/netgescon-client-kb-bootstrap.sh` Scopo: - verificare trust SSH verso `.53` - montare `Documenti condivisi`, `Progetti` e `Scambio` via `SSHFS` - creare un workspace locale basato su symlink verso i mount fidati - verificare `KB health` e, se presente `NETGESCON_KB_API_KEY`, anche una query reale - installare opzionalmente `agent-orchestrator` in una virtualenv locale senza dipendere da `pipx` Uso minimo: ```bash NETGESCON_KB_API_KEY='...' scripts/ops/netgescon-client-kb-bootstrap.sh --client-id 200 --install-orchestrator ``` Per altre macchine basta cambiare `--client-id`, per esempio `205`.