318 lines
12 KiB
Markdown
Executable File
318 lines
12 KiB
Markdown
Executable File
# 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`.
|