gilles/system_update
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
system_update/tache6.md
T
gilles 0fbca06d3d docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation 
Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-05 19:50:25 +02:00

527 lines
16 KiB
Markdown
Raw Permalink Blame History

# Consigne de dev — Hermes, volet gauche, MCP, skills et messagerie
> **Type** : mission d'**investigation + design intégration agent** (PAS d'implémentation).
> **Langue** : français.
> **Livrable final attendu** : spec d'intégration Hermes prête à passer en plan d'implémentation.
---
## 0. Contexte
L'utilisateur dispose d'un agent Hermes sur `10.0.0.80`.
Deux usages sont visés :
1. **Depuis la webapp** : le volet gauche permet de discuter avec Hermes, demander une analyse, un rapport, un plan, ou une action proposée.
2. **Depuis Hermes TUI ou messagerie** : l'utilisateur parle à Hermes ailleurs, puis Hermes utilise un skill et/ou MCP pour analyser une ou plusieurs machines, générer un rapport global, demander/lancer des upgrades validés, analyser les retours et erreurs.
Docs Hermes consultées :
- Documentation générale : https://hermes-agent.nousresearch.com/docs/
- API Server : https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/
- MCP : https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/
- Use MCP with Hermes : https://hermes-agent.nousresearch.com/docs/guides/use-mcp-with-hermes
- Skills System : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
- Cron : https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
- Messaging Gateway : https://hermes-agent.nousresearch.com/docs/user-guide/messaging
- Webhooks : https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/
---
## 1. Outils Hermes pertinents à déployer
D'après la documentation Hermes, les briques pertinentes sont :
### API Server Hermes
Hermes expose un serveur HTTP compatible OpenAI. La doc indique :
- activer `API_SERVER_ENABLED=true` ;
- définir `API_SERVER_KEY` ;
- lancer `hermes gateway` ;
- endpoint typique `http://host:8642/v1`.
Usage dans ce projet :
- le volet gauche de la webapp parle au backend `system_update` ;
- le backend relaie vers Hermes API Server sur `10.0.0.80:8642` ;
- l'API key Hermes reste côté backend, jamais dans le navigateur ;
- streaming via `/v1/runs` ou Chat Completions selon support détecté.
### MCP HTTP côté system_update
Hermes sait se connecter à des serveurs MCP HTTP (`url`, `headers`) et filtrer les tools exposés.
Usage dans ce projet :
- `system_update` expose un serveur MCP HTTP interne ;
- Hermes sur `10.0.0.80` déclare ce MCP dans `~/.hermes/config.yaml` ;
- seuls les tools sûrs/minimaux sont exposés ;
- les actions dangereuses créent une demande de validation webapp au lieu de s'exécuter directement.
### Skills Hermes
Hermes charge des skills depuis `~/.hermes/skills/`, avec `SKILL.md`, références, scripts et slash commands.
Usage dans ce projet :
- créer un skill `system-update-ops` ;
- il apprend à lire les snapshots JSON ;
- il produit rapports globaux ;
- il sait demander des refresh ;
- il sait créer une proposition d'upgrade ;
- il sait analyser erreurs APT/Docker/post-install ;
- il ne manipule jamais les secrets.
### Messaging Gateway
Hermes peut être utilisé depuis Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, Home Assistant, Mattermost, Teams, etc.
Usage dans ce projet :
- permettre à l'utilisateur de demander depuis un messager :
- "analyse toutes les machines" ;
- "fais un rapport global" ;
- "prépare les upgrades" ;
- "analyse l'échec sur vm_mqtt".
### Webhooks Hermes
Hermes expose un adaptateur webhook avec HMAC, routes et livraison. Il peut fonctionner en mode agent ou `deliver_only`.
Usage dans ce projet :
- envoyer à Hermes une notification quand un job backend termine ;
- notifier un canal messagerie après schedule automatique ;
- transmettre un résumé JSON réduit ;
- utiliser `deliver_only` pour notifications simples sans LLM.
### Cron Hermes
Hermes peut planifier des tâches avec `/cron` ou `hermes cron`, charger des skills et livrer des résultats.
Usage dans ce projet :
- optionnel : planifier côté Hermes des audits périodiques de haut niveau ;
- recommandé : garder les refresh machine opérationnels côté backend `system_update` (tâche 5), et utiliser Hermes cron pour rapports/analyses/résumés, pas pour exécuter SSH.
---
## 2. Architecture cible
```text
┌──────────────────────────────┐
│ Webapp system_update │
│ ┌──────────┬───────────────┐ │
│ │ Hermes │ Dashboard │ │
│ │ chat │ tuiles │ │
│ └──────────┴───────────────┘ │
└───────────────┬──────────────┘
│ HTTP/SSE
┌───────────────▼──────────────┐
│ Backend system_update │
│ - API machines/actions │
│ - stockage JSON │
│ - MCP HTTP server │
│ - proxy Hermes API │
└───────┬─────────────────┬────┘
│ │
│ MCP HTTP │ OpenAI-compatible API
│ │
┌───────▼─────────────────▼────┐
│ Hermes Agent 10.0.0.80 │
│ - API Server : :8642 │
│ - Gateway messaging │
│ - Skills system-update-ops │
│ - MCP client system_update │
└───────────────────────────────┘
```
Règle forte :
> Hermes ne fait jamais de SSH directement vers les machines. Il passe par les tools MCP/API de `system_update`.
---
## 3. Cas 1 — Volet gauche Hermes dans la webapp
Flux recommandé :
1. Utilisateur écrit dans le volet gauche.
2. Frontend envoie le message au backend `system_update`.
3. Backend ajoute un contexte système court :
- rôle Hermes ;
- interdiction secrets ;
- appeler MCP/API pour données machine ;
- actions dangereuses = validation webapp.
4. Backend appelle Hermes API Server sur `10.0.0.80:8642`.
5. Réponse streamée vers le volet gauche.
6. Si Hermes propose une action, la webapp l'affiche comme carte de validation, pas comme exécution directe.
Exigences UX pour la discussion :
- séparation claire entre messages utilisateur, messages Hermes et messages système ;
- copier-coller natif du texte ;
- bouton copier sur chaque message long ;
- blocs de commande monospace avec bouton copier ;
- références cliquables vers machine, snapshot, exécution, rapport ou extrait de log ;
- action proposée rendue dans une carte validable séparée du texte ;
- aucun secret dans l'historique envoyé à Hermes ou affiché au navigateur.
Endpoints frontend/backend à concevoir :
```text
POST /api/hermes/chat
GET /api/hermes/runs/:runId/events
POST /api/hermes/runs/:runId/stop
GET /api/hermes/health
GET /api/hermes/capabilities
```
Le backend doit vérifier `/v1/health` et `/v1/capabilities` Hermes.
Configuration :
```text
HERMES_BASE_URL=http://10.0.0.80:8642/v1
HERMES_API_KEY=...
HERMES_SESSION_KEY=system-update-webapp
```
L'API key n'est jamais exposée au navigateur.
---
## 4. Cas 2 — Hermes TUI ou messagerie contrôle system_update
Depuis Hermes TUI/messagerie, l'utilisateur peut demander :
- analyser une machine ;
- analyser toutes les machines ;
- faire un rapport global ;
- comparer les updates ;
- proposer un ordre de mise à jour ;
- demander un upgrade ;
- analyser le résultat ;
- expliquer une erreur.
Hermes utilise alors :
- skill `system-update-ops` ;
- MCP HTTP `system_update`.
Exemple `~/.hermes/config.yaml` :
```yaml
mcp_servers:
system_update:
url: "http://10.0.0.X:8787/mcp"
headers:
Authorization: "Bearer ${SYSTEM_UPDATE_MCP_TOKEN}"
tools:
include:
- list_machines
- get_machine_state
- get_machine_hardware
- get_machine_metrics
- get_machine_snapshot
- get_all_snapshots
- get_machine_execution
- get_machine_messages
- search_reports
- get_report
- search_log_artifacts
- run_refresh
- request_action
- get_pending_actions
- preview_template
- list_templates
resources: false
prompts: false
```
Le tool `request_action` ne lance pas directement les actions dangereuses. Il crée une demande :
```json
{
"requestId": "req_x",
"machineId": "vm_mqtt",
"action": "apt_upgrade",
"status": "pending_user_approval",
"summary": "4 paquets seront mis à jour",
"risk": "medium"
}
```
La webapp affiche la demande et l'utilisateur valide.
---
## 5. Tools MCP system_update
Surface minimale à concevoir :
```text
list_machines
get_machine_state
get_machine_hardware
get_machine_metrics
get_machine_snapshot
get_all_snapshots
get_machine_execution
get_machine_messages
search_reports
get_report
search_log_artifacts
run_refresh
request_action
get_pending_actions
preview_template
list_templates
```
À éviter au MVP :
- accès log brut complet non filtré ;
- accès secrets ;
- actions SSH directes depuis Hermes ;
- suppression destructive ;
- modification template sans validation.
Accès logs/rapports autorisé :
- `search_reports` : recherche dans titres/résumés/rapports Markdown ;
- `get_report` : lecture d'un rapport archivé, sans secret ;
- `get_machine_messages` : warnings/erreurs/dépréciations extraits des logs ;
- `search_log_artifacts` : recherche ciblée dans logs bruts avec limites, masquage et pagination ;
- `get_log_excerpt` (futur, hors liste MVP) : extrait par `artifactId` et plage de lignes, jamais log complet par défaut.
Hermes doit travailler d'abord sur :
1. `machine_state` ;
2. profil OS/type machine, hardware et métriques simples ;
3. snapshots JSON réduits ;
4. messages importants ;
5. rapports Markdown ;
6. extraits de logs ciblés seulement si nécessaire.
### Terminal SSH interactif
La webapp peut prévoir un vrai terminal SSH interactif dans le volet droit, mais ce n'est pas un tool Hermes.
Règles :
- l'utilisateur ouvre lui-même une session SSH interactive ;
- Hermes peut suggérer une commande copiable ;
- Hermes ne peut pas injecter une commande dans le terminal interactif ;
- une commande copiée/collée reste une action utilisateur ;
- ouverture/fermeture de session auditée ;
- désactivation globale possible ;
- session non persistée dans Hermes ;
- logs de session conservés uniquement selon paramètre explicite, avec masquage secrets.
Actions dangereuses :
- `apt_full_upgrade`
- `apt_dist_upgrade`
- `docker_prune`
- `docker_down`
- `post_install_identity_network`
- `reboot_verified`
Ces actions doivent passer par validation UI.
---
## 6. Skill Hermes `system-update-ops`
Créer une spec de skill :
```text
~/.hermes/skills/devops/system-update-ops/
├─ SKILL.md
├─ references/
│ ├─ json-contracts.md
│ ├─ apt-error-taxonomy.md
│ ├─ important-messages-taxonomy.md
│ ├─ docker-compose-workflow.md
│ ├─ log-access-policy.md
│ └─ safety-rules.md
└─ templates/
├─ global-report.md
├─ machine-report.md
└─ upgrade-plan.md
```
Déclencheurs :
- "analyse mes machines"
- "rapport global system_update"
- "pourquoi l'upgrade a échoué"
- "prépare les mises à jour"
- "propose un ordre d'upgrade"
Procédure du skill :
1. Lister machines via MCP.
2. Récupérer snapshots récents.
3. Si snapshots trop anciens, demander `run_refresh`.
4. Dédupliquer updates APT/Docker.
5. Récupérer les messages importants non acquittés.
6. Classer risques, warnings futurs et notices sécurité.
7. Produire rapport.
8. Si action demandée, créer demande de validation via `request_action`.
9. Après exécution, analyser `ExecutionResult`, messages importants et extraits de logs utiles.
---
## 7. Rapports Hermes
Rapport global attendu :
```text
# Rapport global system_update
## Résumé
- Machines OK
- Machines avec updates
- Machines en erreur
- Reboots requis
## APT
- Paquets par machine
- Doublons
- Risques
## Docker
- Stacks avec updates
- Pull errors
- Prune possible
## Post-install
- Profils manquants
- Actions recommandées
## Plan proposé
1. Machine A
2. Machine B
## Actions en attente de validation
```
Le rapport doit être archivable côté backend et consultable depuis la webapp.
---
## 8. Notifications et webhooks
Le backend `system_update` peut appeler Hermes Webhooks :
- job automatique terminé ;
- updates détectées ;
- erreur critique ;
- machine non revenue après reboot ;
- rapport global prêt.
Webhook Hermes recommandé :
- HMAC obligatoire ;
- payload JSON réduit ;
- mode `deliver_only` pour notifications simples ;
- mode agent avec skill `system-update-ops` pour synthèse.
Exemple payload :
```json
{
"event": "updates_available",
"machineCount": 3,
"aptUpdates": 12,
"dockerUpdates": 2,
"reportRef": "reports/global/..."
}
```
---
## 9. Sécurité
Règles non négociables :
- Hermes ne reçoit jamais de mot de passe SSH/sudo/token registry ;
- Hermes ne fait jamais SSH directement ;
- Hermes ne reçoit pas les logs bruts complets par défaut ;
- MCP expose seulement les tools whitelistés ;
- actions dangereuses = validation UI ;
- API Hermes appelée par backend seulement ;
- token MCP avec rotation possible ;
- audit des demandes Hermes ;
- prompt injection : les données machine/logs sont traitées comme non fiables.
---
## 10. Livrables attendus
À produire sous `docs/` :
1. Architecture Hermes/webapp/MCP.
2. Spécification du proxy backend vers Hermes API Server.
3. Spécification MCP `system_update`.
4. Spec du skill `system-update-ops`.
5. Spec des rapports globaux.
6. Spec notifications/webhooks Hermes.
7. Sécurité et validations.
8. Plan de déploiement Hermes sur `10.0.0.80`.
9. Découpage en sous-jalons.
---
## 11. Définition de terminé
- Les deux cas d'usage sont couverts : volet gauche et TUI/messagerie.
- Les outils Hermes à déployer sont listés.
- Le MCP minimal est défini.
- Le skill Hermes est spécifié.
- Les actions dangereuses ne peuvent pas être exécutées sans validation webapp.
- Les secrets restent côté backend.
- Aucun code de production n'est livré pendant cette mission de design.
---
## 12. Technos à utiliser — checklist
- [ ] Hermes API Server côté agent.
- [ ] Backend proxy vers Hermes, clé jamais dans navigateur.
- [ ] MCP HTTP exposé par `system_update`.
- [ ] Skill Hermes `system-update-ops`.
- [ ] Webhooks Hermes pour notifications.
- [ ] Messaging Gateway si canaux externes utilisés.
- [ ] JSON réduit, références rehydratables.
- [ ] Audit MCP/API.
- [ ] Validation UI obligatoire pour actions dangereuses.
- [ ] Aucun SSH direct depuis Hermes.
## 13. URLs utiles
- Hermes docs : https://hermes-agent.nousresearch.com/docs/
- Hermes API Server : https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/
- Hermes MCP : https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/
- Use MCP with Hermes : https://hermes-agent.nousresearch.com/docs/guides/use-mcp-with-hermes
- Hermes Skills : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
- Hermes Messaging : https://hermes-agent.nousresearch.com/docs/user-guide/messaging
- Hermes Webhooks : https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/
- Model Context Protocol : https://modelcontextprotocol.io/
- JSON Schema : https://json-schema.org/
## 14. Liens parent/enfant avec les autres tâches
- Parents :
- `tache5.md` pour API, stockage et action requests.
- `tache1.9.md` pour tables Hermes/MCP/audit.
- `tache2.md` pour contrats JSON.
- `tache7.md` pour réduction tokens.
- Enfants :
- `tache3.md` intègre le volet Hermes web.
- `tache8.md` peut exposer une vue Hermes native via backend.
- Validation : `validation_tache6.md`.
Reference in New Issue View Git Blame Copy Permalink