Kantin-Petit
ceddb86198
n8n ≥ 2.18.4 sert son propre MCP : suppression du service mcp-n8n, MCP_N8N_URL pointe vers l'endpoint natif de l'instance (auth MCP Access Token Bearer). Portainer reste un sidecar officiel. Aucun changement de code (registry HTTP+Bearer inchangé). Docs + .env alignés, compose revalidé. Palier de risque : n/a (infra + config). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
94 lines
5.3 KiB
Markdown
94 lines
5.3 KiB
Markdown
# CHLOVA — guide projet (CLAUDE.md)
|
||
|
||
CHLOVA est un assistant personnel (inspiré de Jarvis). **Ce n'est pas un produit
|
||
from-scratch** : c'est une **couche d'orchestration** au-dessus d'un homelab
|
||
existant. Le cerveau est un LLM en boucle tool-calling :
|
||
`comprendre → choisir un outil MCP → agir → observer → répondre`.
|
||
|
||
## Substrat existant (réutiliser, ne pas réinventer)
|
||
- Debian + Docker + Traefik.
|
||
- **n8n** (automations) — joignable via son MCP.
|
||
- **Portainer** (déploiement de conteneurs) — joignable via son MCP.
|
||
- **Ollama** : conteneur de la stack, joignable par l'orchestrateur sur le réseau
|
||
Docker interne (`http://ollama:11434`). On utilise des **modèles cloud**
|
||
(suffixe `:cloud`) : le conteneur Ollama local agit en **proxy authentifié**
|
||
vers l'infra distante d'Ollama. Transparent pour l'orchestrateur (il croit
|
||
parler à du Ollama local). Auth via `OLLAMA_API_KEY` (coffre, jamais en dur).
|
||
Conséquences : **pas de GPU requis**, mais les requêtes **sortent vers
|
||
`ollama.com`** (egress doit l'autoriser) et il **n'existe pas de palier
|
||
"local/privé"**.
|
||
|
||
## Architecture cible
|
||
- Tout vit sur le serveur : orchestrateur LLM + Ollama (proxy cloud) + outils MCP.
|
||
- **Une seule surface exposée : le backend CHLOVA.** Lui seul contacte Ollama,
|
||
n8n et Portainer, sur le réseau Docker interne. Aucune brique interne n'est
|
||
jamais joignable directement de l'extérieur.
|
||
- Le mobile est un **client léger** du backend CHLOVA, rien d'autre.
|
||
- Outils MCP : MCP n8n + MCP Portainer.
|
||
- Surfaces : **texte d'abord** (Telegram/Signal = nativement mobile, sans
|
||
exposition), **voix ensuite** (STT + wake-word + TTS). La voix vient **après**
|
||
un cerveau fiable.
|
||
- Auto-extension : si une demande n'est pas réalisable avec les outils existants,
|
||
CHLOVA les crée lui-même en état "need review".
|
||
|
||
## Stack retenue (Phases 0–1)
|
||
- Orchestrateur : **TypeScript + Node 22**, MCP SDK officiel
|
||
`@modelcontextprotocol/sdk` (client).
|
||
- Backend/API : **Fastify**.
|
||
- LLM : client Ollama `/api/chat` (tool-calling natif), modèles `:cloud`.
|
||
- Surface texte Phase 1 : **bot Telegram** (long-polling → zéro port ouvert).
|
||
- MCP : **n8n natif** (instance ≥ 2.18.4, pas de conteneur — endpoint MCP servi
|
||
par n8n, à activer) + **Portainer sidecar** `portainer/portainer-mcp` (tag
|
||
épinglé). **Read-only en Phase 1.**
|
||
- Tests : **Vitest** (gatekeeper + scoping read-only).
|
||
- État assets : **SQLite** (table posée dès P0/P1, câblée en P2+).
|
||
|
||
## Versioning & documentation (non négociable)
|
||
Git est la **source unique de vérité**. Tout artefact créé/modifié — workflow
|
||
n8n, stack/compose Docker, code orchestrateur, outil — doit être :
|
||
- **Versionné** : commit dédié + semver (`vMAJEUR.MINEUR.PATCH`). Chaque
|
||
création/modif = un commit clair + bump. `CHANGELOG.md` tenu à jour.
|
||
- **Documenté** : rôle, entrées/sorties, dépendances, palier de risque, rollback.
|
||
Un artefact non documenté est **incomplet**.
|
||
- Images Docker : tags **épinglés** et versionnés (jamais `:latest`).
|
||
- Workflows n8n : exportés en JSON dans `workflows-n8n/` (le dépôt fait foi).
|
||
|
||
Rien n'est "terminé" tant qu'il n'est pas **à la fois versionné ET documenté**.
|
||
|
||
## Accès mobile & exposition (non négociable)
|
||
- Seul le backend CHLOVA est exposé, derrière auth + TLS.
|
||
- Voie mobile : surface Telegram/Signal (distante par nature, zéro port ouvert)
|
||
ET/OU VPN mesh (Tailscale/Wireguard) + Traefik/TLS pour une API/UI CHLOVA.
|
||
- Ollama, n8n, Portainer n'écoutent **que** sur le réseau Docker interne.
|
||
Ollama n'a **aucune auth native** — ne jamais l'exposer.
|
||
|
||
## Paliers de risque (règle non négociable)
|
||
- **Réversible / lecture seule** → 7 jours de sursis PROVISOIRE autorisés.
|
||
- **Privilégié / destructeur** → **aucun sursis** : BLOQUÉ jusqu'à review.
|
||
(déploiement Portainer, montage de volume hôte, accès secrets, suppression,
|
||
exec dans un conteneur, etc.)
|
||
- Le LLM **ne doit jamais** pouvoir reclasser un asset privilégié en réversible.
|
||
|
||
## Cycle de vie "need review" (Phase 2+, interfaces posées en P1)
|
||
États d'un asset créé par CHLOVA : PROVISOIRE (7 j) → APPROUVÉ / REFUSÉ / BLOQUÉ.
|
||
Table assets : `id, type, version, palier_risque, statut, created_at, expires_at,
|
||
exec_count, lien_commit, lien_doc`. Cron horaire PROVISOIRE→BLOQUÉ ; **gatekeeper**
|
||
qui vérifie le statut **avant chaque exécution**.
|
||
|
||
## Sécurité (non négociable — risque n°1 : prompt injection)
|
||
- Accès quasi-root via Portainer : **socket-proxy Docker obligatoire**, tokens
|
||
Portainer/n8n à portée restreinte, réseau dédié à l'agent, **egress filtré**
|
||
(autoriser `ollama.com`).
|
||
- L'agent ne voit **jamais** les secrets en clair : il manipule des références.
|
||
Tous les secrets via env/coffre, jamais en dur ; `.env.example` fourni.
|
||
- Toute opération mutante est **audit-loggée**.
|
||
- Déploiements de stacks en **GitOps** quand possible (rollback + audit gratuits).
|
||
|
||
## Périmètre actuel
|
||
- **Phase 0** : socle (structure, CLAUDE.md, config, sécurité, conventions,
|
||
docker-compose stack avec Ollama interne + backend seule surface).
|
||
- **Phase 1** : cerveau **lecture seule** (orchestrateur LLM via Ollama cloud +
|
||
MCP n8n + MCP Portainer read-only + surface texte).
|
||
- **Phases 2+ NON implémentées** ici : écriture, need-review, voix, auto-extension.
|
||
On pose seulement les interfaces/abstractions.
|