Kantin-Petit
c096fa9467
Pose les règles non négociables : SemVer + un-artefact-un-commit, pinning des images, export JSON des workflows n8n ; gabarit de doc d'asset ; paliers réversible/privilégié avec invariant anti-escalade ; schéma d'architecture et invariants d'exposition. Ignore settings.local.json. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
# Architecture CHLOVA
|
|
|
|
> Vue d'ensemble. Les règles non négociables font foi dans `CLAUDE.md`.
|
|
|
|
## Principe
|
|
CHLOVA est une **couche d'orchestration** : un LLM en boucle tool-calling
|
|
(`comprendre → choisir un outil MCP → agir → observer → répondre`) posée au-dessus
|
|
d'un homelab Debian + Docker + Traefik existant.
|
|
|
|
## Schéma logique
|
|
```
|
|
mobile (client léger)
|
|
│ Telegram (long-polling, zéro port ouvert)
|
|
▼
|
|
┌─────────────────────────┐ réseau Docker interne (chlova-internal)
|
|
│ Backend CHLOVA │ ─────────────────────────────────────────────
|
|
│ (seule surface exposée)│ ┌───────────┐ ┌──────────────┐
|
|
│ - boucle agent │ ─────► │ Ollama │ ─►│ ollama.com │ (egress)
|
|
│ - registry MCP │ │ (proxy │ │ modèles :cloud│
|
|
│ - gatekeeper (P2+) │ │ cloud) │ └──────────────┘
|
|
│ - audit log │ └───────────┘
|
|
└─────────────────────────┘
|
|
│ MCP (stdio/http interne)
|
|
├───────────────► MCP n8n ──► n8n API (interne)
|
|
└───────────────► MCP Portainer ─► socket-proxy ─► Docker / Portainer
|
|
```
|
|
|
|
## Invariants
|
|
- **Une seule surface exposée** : le backend CHLOVA (auth + TLS). Tout le reste
|
|
(Ollama, n8n, Portainer, serveurs MCP) n'écoute **que** sur `chlova-internal`.
|
|
- **Ollama sans auth native** → jamais exposé ; il sort vers `ollama.com` pour les
|
|
modèles `:cloud` (egress filtré, seul `ollama.com` autorisé).
|
|
- **Accès Docker via socket-proxy** uniquement (pas de socket brut dans l'agent).
|
|
- **Secrets par référence** : l'agent ne voit jamais les valeurs en clair.
|
|
|
|
## Boucle agent (Phase 1, lecture seule)
|
|
1. Message texte (Telegram) → backend.
|
|
2. Backend appelle Ollama `/api/chat` avec la liste d'outils MCP **read-only**.
|
|
3. Le modèle choisit un outil → le backend l'exécute via le serveur MCP.
|
|
4. Observation renvoyée au modèle → réponse finale → utilisateur.
|
|
5. Toute exécution d'outil est **audit-loggée**.
|
|
|
|
En Phase 1, le **readonly-filter** garantit que seuls les outils `readOnlyHint=true`
|
|
sont exposés : aucun risque d'écriture.
|
|
|
|
## Évolutions (interfaces posées, non implémentées)
|
|
- **Gatekeeper + table assets** : vérifie le statut avant chaque exécution (P2).
|
|
- **Cycle need-review** : PROVISOIRE → APPROUVÉ/REFUSÉ/BLOQUÉ + cron horaire (P2).
|
|
- **Auto-extension** : création d'outils/workflows en "need review" (P4).
|
|
- **Voix** : STT + wake-word + TTS (P5), après un cerveau fiable.
|
|
|
|
## Composants & contrats
|
|
| Composant | Image / lib | Exposition | Palier |
|
|
|---|---|---|---|
|
|
| Backend CHLOVA | code maison (TS) | seule surface | — |
|
|
| Ollama (proxy cloud) | `ollama/ollama` épinglé | interne | — |
|
|
| MCP n8n | `czlonkowski/n8n-mcp` épinglé | interne | read-only (P1) |
|
|
| MCP Portainer | `portainer/portainer-mcp` épinglé | interne | read-only (P1) |
|
|
| socket-proxy | `tecnativa/docker-socket-proxy` épinglé | interne | scoping Docker |
|