docs: runbook deploiement superpowers (hermes, claude code, antigravity, pieges tls et ssh path synology)
This commit is contained in:
Antigravity
@@ -0,0 +1,141 @@
|
||||
# Déploiement Superpowers (obra/superpowers) — Flotte Hermes Agent, Claude Code & Antigravity
|
||||
|
||||
**Instance auteur** : hermes-perso
|
||||
**Date** : 2026-08-18
|
||||
**Tags** : [hermes, superpowers, plugins, skills, tls, ssh, synology, claude-code, antigravity]
|
||||
**Statut** : valide
|
||||
|
||||
---
|
||||
|
||||
## Probleme
|
||||
|
||||
Déployer le framework de compétences et de méthodologie agentique **Superpowers** (`obra/superpowers`) de manière unifiée et sécurisée sur :
|
||||
1. Les trois instances Hermes Agent NAS (`hermes-agent-nyora`, `hermes-agent-tt`, `hermes-agent-perso`) sous Docker.
|
||||
2. Claude Code (extension VS Code / CLI).
|
||||
3. Antigravity (`agy`).
|
||||
|
||||
Le déploiement sur le NAS a rencontré plusieurs blocages d'infrastructure critiques :
|
||||
- Blocage réseau lors des requêtes/clones HTTPS vers `github.com` (handshake TLS 1.3 bloqué/timeout).
|
||||
- Commandes `docker` introuvables lors des accès SSH non-interactifs.
|
||||
- Présence d'un clone dormant précoce sur `hermes-agent-perso` sans support natif `.hermes-plugin`.
|
||||
|
||||
---
|
||||
|
||||
## Contexte et contraintes
|
||||
|
||||
- **Hôte** : Synology NAS DS920+ (DSM 7.x, Linux 4.4 kernel).
|
||||
- **Conteneurs** : `nousresearch/hermes-agent:v2026.8.3` (UID 1026, GID 100, utilisateur `hermes`).
|
||||
- **Gestionnaire de processus interne** : s6-overlay (`s6-rc`, `s6-supervise`).
|
||||
- **Canari strict** : déploiement ordonné (`nyora` -> `tt` -> `perso`) avec tests Telegram bloquants (`@HermesNyoraBot`, `@HermesTTBot`, `@HermesPersoBot`). Tolérance zéro pour les régressions sur TT.
|
||||
|
||||
---
|
||||
|
||||
## Ce qui NE fonctionne PAS
|
||||
|
||||
| Tentative | Erreur obtenue | Raison de l'echec |
|
||||
|-----------|----------------|-------------------|
|
||||
| `hermes plugins install obra/superpowers` direct | `fatal: unable to access 'https://github.com/...': Failed to connect... Connection timed out` | Le handshake TLS 1.3 sortant vers `github.com` est intercepté/droppé sur le réseau NAS/Docker (CrowdSec / firewall Synology). Seul TLS 1.2 passe. |
|
||||
| `docker exec ...` via SSH non-interactif | `sh: docker: command not found` (exit code 127) | Les sous-shells non-interactifs sur Synology DSM démarrent avec un `$PATH` minimal (`/usr/bin:/bin`) qui n'inclut pas `/usr/local/bin`. |
|
||||
| Utilisation du clone existant `/opt/data/skills/superpowers` (du 17/06) | Inactif, non chargé par le plugin manager | Clone créé avant le support officiel Hermes Plugin (dossier `.hermes-plugin` absent). |
|
||||
| `hermes skills update <nom>` pour découvrir de nouveaux skills | `No updates available` | La commande `skills update` ne découvre que les mises à jour de skills déjà installés, pas les nouveaux skills ajoutés à un tap distant. |
|
||||
|
||||
---
|
||||
|
||||
## Solution validee
|
||||
|
||||
### 1. Piège SSH PATH Synology
|
||||
|
||||
Toujours exporter explicitement le chemin `/usr/local/bin` dans toute commande SSH non-interactive :
|
||||
|
||||
```bash
|
||||
ssh -p 22222 Best0f@192.168.100.33 "export PATH=/usr/local/bin:\$PATH; <commande>"
|
||||
```
|
||||
|
||||
### 2. Contournement réseau TLS 1.2 (Système + Utilisateur)
|
||||
|
||||
Forcer Git en TLS 1.2 au niveau système (`/etc/gitconfig`) ET utilisateur (`/opt/data/home/.gitconfig`) dans chaque conteneur :
|
||||
|
||||
```bash
|
||||
for c in hermes-agent-nyora hermes-agent-tt hermes-agent-perso; do
|
||||
docker exec $c git config --system http.sslVersion tlsv1.2
|
||||
docker exec -u hermes $c git config --global http.sslVersion tlsv1.2
|
||||
done
|
||||
```
|
||||
|
||||
### 3. Nettoyage du clone dormant sur hermes-agent-perso
|
||||
|
||||
Renommer le clone obsolète sans le supprimer :
|
||||
|
||||
```bash
|
||||
docker exec hermes-agent-perso mv /opt/data/skills/superpowers /opt/data/skills/superpowers.STALE-pre-hermes-plugin-support-20260818
|
||||
```
|
||||
|
||||
### 4. Déploiement canari séquentiel sur Hermes Agent
|
||||
|
||||
Pour chaque instance (`nyora`, puis `tt`, puis `perso`) :
|
||||
|
||||
```bash
|
||||
# 1. Installation du plugin
|
||||
docker exec -u hermes hermes-agent-<instance> hermes plugins install obra/superpowers --enable
|
||||
|
||||
# 2. Redémarrage du conteneur (chargement s6 propre)
|
||||
docker restart hermes-agent-<instance>
|
||||
|
||||
# 3. Vérification locale
|
||||
docker exec -u hermes hermes-agent-<instance> hermes plugins list --plain --no-bundled
|
||||
docker logs --tail 40 hermes-agent-<instance>
|
||||
|
||||
# 4. Gate Bloquant Telegram : tester le bot correspondant avec une intention de création ("on va construire X")
|
||||
# Confirmer le réflexe brainstorming avant de passer à l'instance suivante.
|
||||
```
|
||||
|
||||
### 5. Claude Code (Extension VS Code & CLI)
|
||||
|
||||
Puisque le binaire `claude` est présent (`~/.local/bin/claude` — Cas A) :
|
||||
|
||||
```bash
|
||||
claude plugin install superpowers@claude-plugins-official
|
||||
```
|
||||
*Note : Recharger la fenêtre VS Code (`Developer: Reload Window`) pour que l'extension prenne en compte le plugin partagé.*
|
||||
|
||||
### 6. Antigravity
|
||||
|
||||
Installation directe via le gestionnaire de plugins d'Antigravity :
|
||||
|
||||
```bash
|
||||
agy plugin install https://github.com/obra/superpowers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# 1. Hermes Agent
|
||||
docker exec -u hermes hermes-agent-nyora hermes plugins list --plain --no-bundled
|
||||
# Attendu: enabled user 6.3.0 superpowers
|
||||
|
||||
# 2. Claude Code
|
||||
claude plugin list --json
|
||||
# Attendu: "id": "superpowers@claude-plugins-official", "enabled": true
|
||||
|
||||
# 3. Antigravity
|
||||
agy plugin list
|
||||
# Attendu: "name": "superpowers", "components": ["skills", "hooks"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pieges specifiques DSM / NAS
|
||||
|
||||
1. **TLS 1.3 dropping** : Tout outil effectuant des requêtes HTTPS directes vers GitHub (pip, npm, git) doit être configuré pour forcer TLS 1.2 si un timeout survient lors du handshake.
|
||||
2. **Utilisateur hermes vs root** : `docker exec` exécute par défaut sous `root`. Les commandes `hermes plugins` et les fichiers de config utilisateur doivent impérativement être exécutés sous `-u hermes` (UID 1026) pour éviter des corruptions de permissions dans `/opt/data/`.
|
||||
3. **Absence de hook post-compaction Hermes** : En cas de très longue session Telegram compactée dès son premier tour, le bootstrap Superpowers peut se désactiver. Ouvrir une session fraîche restaure l'amorçage.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Repo upstream obra/superpowers](https://github.com/obra/superpowers)
|
||||
- [Documentation Nous Research Hermes Agent](https://github.com/NousResearch/Hermes-Agent)
|
||||
- [PROTOCOL-INFRA NAS DS920+](common/PROTOCOL-INFRA.md)
|
||||
Reference in New Issue
Block a user