docs: fondation projet (CLAUDE.md, design system, spec + plan jalon 1)
Ignore les dépôts de référence imbriqués (linux-update-dashboard, nas-ops). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
À prévoir dans les consignes : un volet gauche “Hermes” intégré à la webapp.
|
||||
|
||||
Architecture proposée :
|
||||
|
||||
Frontend Webapp
|
||||
├─ Centre : dashboard machines / tuiles / actions
|
||||
├─ Droite : terminal live xterm.js
|
||||
└─ Gauche : panneau Hermes
|
||||
├─ chat avec Hermes
|
||||
├─ envoi d’ordres structurés
|
||||
├─ retour d’analyse
|
||||
├─ plan de mise à jour proposé
|
||||
└─ liens vers rapports Markdown
|
||||
|
||||
Principe important : Hermes ne doit pas exécuter directement les commandes SSH. Il dialogue avec la webapp via API/MCP, analyse les snapshots JSON, propose un plan, puis l’utilisateur valide les actions dans l’interface.
|
||||
|
||||
À ajouter dans les fichiers de consigne :
|
||||
|
||||
Ajout : intégration Hermes dans la webapp
|
||||
|
||||
Prévoir un panneau latéral gauche dédié à Hermes Agent.
|
||||
|
||||
Objectif
|
||||
|
||||
Permettre à l’utilisateur de dialoguer avec Hermes depuis la webapp pour :
|
||||
|
||||
transmettre des messages ;
|
||||
demander une analyse des mises à jour disponibles ;
|
||||
demander un plan de mise à jour ;
|
||||
analyser les erreurs après exécution ;
|
||||
générer ou consulter un rapport Markdown ;
|
||||
demander une synthèse globale multi-machines.
|
||||
Règle de sécurité
|
||||
|
||||
Hermes ne doit jamais exécuter directement de commandes SSH.
|
||||
|
||||
Hermes doit uniquement passer par :
|
||||
|
||||
l’API interne de la webapp ;
|
||||
le serveur MCP du projet ;
|
||||
les actions explicitement autorisées ;
|
||||
les JSON normalisés produits par la webapp.
|
||||
|
||||
Les secrets SSH, mots de passe, sudo password, tokens et clés privées ne doivent jamais être transmis à Hermes.
|
||||
|
||||
UX attendue
|
||||
|
||||
Le layout principal doit prévoir trois zones :
|
||||
|
||||
volet gauche : assistant Hermes ;
|
||||
zone centrale : dashboard machines ;
|
||||
volet droit : terminal live.
|
||||
|
||||
Le volet Hermes doit permettre :
|
||||
|
||||
historique de conversation ;
|
||||
saisie de message ;
|
||||
boutons d’actions rapides :
|
||||
analyser les mises à jour ;
|
||||
proposer un plan ;
|
||||
analyser les erreurs ;
|
||||
générer rapport ;
|
||||
comparer plusieurs machines ;
|
||||
affichage des réponses Hermes ;
|
||||
lien vers les rapports Markdown archivés.
|
||||
Flux recommandé
|
||||
La webapp collecte les mises à jour disponibles.
|
||||
Elle produit un snapshot JSON par machine.
|
||||
Le frontend peut transmettre à Hermes une version filtrée et dédupliquée.
|
||||
Hermes analyse les mises à jour.
|
||||
Hermes propose un plan.
|
||||
L’utilisateur valide manuellement.
|
||||
La webapp exécute les actions.
|
||||
La webapp remonte un JSON de résultat.
|
||||
Hermes peut analyser le résultat et générer un rapport Markdown.
|
||||
Fichiers à prévoir dans le projet
|
||||
|
||||
Créer les fichiers suivants dès le démarrage du projet :
|
||||
|
||||
CLAUDE.md
|
||||
docs/CONSIGNE_PROJET.md
|
||||
docs/ARCHITECTURE.md
|
||||
docs/MCP_CONTRACTS.md
|
||||
docs/HERMES_INTEGRATION.md
|
||||
docs/SECURITY.md
|
||||
docs/JSON_SCHEMAS.md
|
||||
docs/TEMPLATES_UPDATE.md
|
||||
hermes-skills/update-ops-planner/SKILL.md
|
||||
mcp/README.md
|
||||
templates/apt/update.sh.tpl
|
||||
templates/apt/upgrade.sh.tpl
|
||||
templates/apt/full-upgrade.sh.tpl
|
||||
templates/apt/dist-upgrade.sh.tpl
|
||||
templates/apt/clean.sh.tpl
|
||||
templates/apt/autoremove.sh.tpl
|
||||
templates/apt/reboot-check.sh.tpl
|
||||
templates/docker/scan-compose.sh.tpl
|
||||
templates/docker/pull.sh.tpl
|
||||
templates/docker/up.sh.tpl
|
||||
templates/docker/prune-images.sh.tpl
|
||||
|
||||
Les fichiers importants doivent être modifiables par l’agent Claude Code, mais la structure finale sera décidée après échange avec l’agent.
|
||||
|
||||
Les dépôts de référence doivent être placés dans un dossier dédié :
|
||||
|
||||
references/
|
||||
├─ linux-update-dashboard/
|
||||
└─ nas-ops/
|
||||
|
||||
Ils servent d’inspiration et de comparaison technique, pas de copie directe.
|
||||
|
||||
Ajout : rôle du MCP server pour Hermes
|
||||
|
||||
Le serveur MCP doit exposer une interface stable entre la webapp et les agents.
|
||||
|
||||
Tools MCP proposés
|
||||
list_machines
|
||||
get_machine_snapshot
|
||||
get_all_snapshots
|
||||
get_machine_execution_result
|
||||
get_report
|
||||
search_reports
|
||||
run_refresh
|
||||
request_action_plan
|
||||
run_approved_action
|
||||
list_templates
|
||||
preview_template
|
||||
Règles
|
||||
Le MCP ne reçoit jamais de secret.
|
||||
Le MCP ne donne accès qu’aux actions prévues.
|
||||
Les actions dangereuses nécessitent validation côté webapp.
|
||||
Hermes peut proposer, analyser et documenter.
|
||||
La webapp reste responsable de l’exécution réelle.
|
||||
Exemple de commande agent
|
||||
|
||||
L’utilisateur peut écrire dans le volet Hermes :
|
||||
|
||||
Analyse les mises à jour disponibles sur toutes les machines Debian et Proxmox, regroupe les doublons, puis propose un ordre de mise à jour.
|
||||
|
||||
Hermes doit alors :
|
||||
|
||||
récupérer les snapshots via MCP ;
|
||||
dédupliquer les paquets et images Docker ;
|
||||
rechercher les composants importants si besoin ;
|
||||
produire un plan court ;
|
||||
générer un rapport Markdown archivable.
|
||||
|
||||
|
||||
|
||||
Je retiendrais donc : Hermes comme copilote d’exploitation, mais webapp comme chef d’orchestre sécurisé.
|
||||
Reference in New Issue
Block a user