394 lines
19 KiB
Markdown
394 lines
19 KiB
Markdown
# 🗺️ ROADMAP agent-manager — vers le « super outil »
|
||
|
||
> **Version du document : 2.0** · Statut : propositions, non engagées
|
||
> Base : analyse du code **v0.2.7** (Rust, 45+ tests, zéro dépendance runtime)
|
||
|
||
---
|
||
|
||
## 📖 Sommaire
|
||
|
||
1. [Résumé exécutif](#1--résumé-exécutif)
|
||
2. [Légende de lecture](#2--légende-de-lecture)
|
||
3. [Quick wins — valeur immédiate](#3--quick-wins--valeur-immédiate)
|
||
4. [État des lieux](#4--état-des-lieux)
|
||
5. [Vision & principes](#5--vision--principes)
|
||
6. [Socle technique : le modèle de données](#6--socle-technique--le-modèle-de-données)
|
||
7. [Les 12 axes](#7--les-12-axes)
|
||
8. [Jalons versionnés](#8--jalons-versionnés)
|
||
9. [Indicateurs de succès (KPI)](#9--indicateurs-de-succès-kpi)
|
||
10. [Risques & garde-fous](#10--risques--garde-fous)
|
||
11. [Par où commencer](#11--par-où-commencer)
|
||
|
||
---
|
||
|
||
## 1. 📌 Résumé exécutif
|
||
|
||
**am** est aujourd'hui un excellent *gestionnaire* d'agents : 72 agents au
|
||
catalogue, 9 méthodes d'installation, dépendances résolues automatiquement,
|
||
processus pilotés, REPL avec passerelle shell, sauvegarde export/import.
|
||
|
||
Mais il est **aveugle** : il ne retient ni ce qui a été fait, ni quand, ni
|
||
par quel agent, ni dans quel projet, ni avec quel résultat. Les logs sont du
|
||
texte libre non interrogeable, l'état ne contient que les installations et
|
||
le PID courant, l'historique est un simple fichier plat.
|
||
|
||
Cette roadmap transforme **am** en **cockpit de votre parc d'agents IA** :
|
||
|
||
| Rôle | Promesse | Porté par |
|
||
|---|---|---|
|
||
| 📓 Journal de bord | tout est tracé, rien ne se perd | Axe 1 (journal d'événements) |
|
||
| 🔎 Rétroviseur | tout est cherchable en 2 secondes | Axes 2, 3, 4 |
|
||
| 📊 Tableau de bord | tout est mesuré | Axes 1, 5, 9 |
|
||
| 🤖 Copilote | il pilote à votre place | Axes 6, 7 |
|
||
|
||
**Chiffres clés :** 12 axes · ~55 fonctionnalités · 4 jalons (v0.3.0 → v1.0)
|
||
· ~15 semaines de travail cumulé · 0 dépendance runtime ajoutée.
|
||
|
||
---
|
||
|
||
## 2. 📚 Légende de lecture
|
||
|
||
| Symbole | Signification |
|
||
|---|---|
|
||
| **P0** | Fondations — à démarrer tout de suite (socle des autres axes) |
|
||
| **P1** | Court terme — après la phase 0 |
|
||
| **P2** | Moyen terme |
|
||
| **P3** | Vision — long terme |
|
||
| ⭐ | Reprend une demande explicite de l'utilisateur |
|
||
| **S** | Effort : moins d'1 jour |
|
||
| **M** | Effort : 2 à 4 jours |
|
||
| **L** | Effort : 1 à 2 semaines |
|
||
| **XL** | Effort : plus de 2 semaines |
|
||
| ⬜ / 🔨 / ✅ | Proposé / En cours / Livré (rien n'est commencé aujourd'hui) |
|
||
|
||
---
|
||
|
||
## 3. ⚡ Quick wins — valeur immédiate
|
||
|
||
*Tous en effort S, phase P0, sans dépendance sur le socle. Livrables en
|
||
quelques jours, à caler avant ou pendant la construction du journal.*
|
||
|
||
| Fonctionnalité | Commande | Apport |
|
||
|---|---|---|
|
||
| Voir les logs d'un agent | am logs claude-code (--follow) | tail des logs déjà écrits par process.rs |
|
||
| Filtres sur la liste | am list --running · --sort name,version,status | repérage instantané |
|
||
| Éditer la config sans éditeur | am config set key value | moins de friction YAML |
|
||
| Alias à la volée | am alias add cc claude-code | sans éditer le fichier |
|
||
| Historique propre | dédup + horodatage de history.txt | base saine pour l'axe 2 |
|
||
| Doctor scriptable | am doctor --json | CI et monitoring |
|
||
| Ouvrir l'installation | am open claude-code | explorer le répertoire de l'agent |
|
||
| Version scriptable | am version --json | introspection des scripts |
|
||
|
||
---
|
||
|
||
## 4. 🧭 État des lieux (points d'ancrage dans le code)
|
||
|
||
| Brique actuelle | Fichier | Limite aujourd'hui |
|
||
|---|---|---|
|
||
| Catalogue 72 agents, alias, groupes | src/catalog.rs, config.yaml | recherche = sous-chaîne stricte, pas de ranking |
|
||
| Installation (9 méthodes), dépendances OS | src/installers/, src/deps.rs, src/toolchain.rs | solide — rien à redire |
|
||
| État local | src/state.rs (state.json v1) | installations + PID courant uniquement, **aucun historique** |
|
||
| Détection externe + cache | src/probe.rs | excellent pattern de cache — à généraliser |
|
||
| Processus | src/process.rs | logs non structurés, pas de sessions, pas de métriques |
|
||
| Journal applicatif | src/output.rs | texte libre horodaté, non interrogeable |
|
||
| REPL + passerelle shell | src/repl.rs (history.txt, session_id()) | historique plat, pas de recherche ni de stats |
|
||
| Backup | src/commands/export_import.rs | manuel, pas de synchronisation |
|
||
|
||
---
|
||
|
||
## 5. 🎯 Vision & principes directeurs
|
||
|
||
**Vision :** le cockpit unique du parc d'agents — journal de bord, rétroviseur,
|
||
tableau de bord et copilote.
|
||
|
||
**Principes :**
|
||
|
||
1. **Zéro dépendance runtime** — tout est Rust pur et fichiers locaux
|
||
(JSONL/JSON), jamais de base de données externe.
|
||
2. **Local par défaut, opt-in pour le distant** — la télémétrie n'existe que
|
||
si l'utilisateur l'active ; tout le reste est 100 % local.
|
||
3. **Contrats stables** — les sorties --json sont la base des scripts et des
|
||
futurs UI : champs ajoutés, jamais retirés.
|
||
4. **Performance** — écriture en append (JSONL), lectures par fenêtres
|
||
temporelles, index dérivés régénérables, caches sur le modèle de probe.rs.
|
||
5. **Livraison continue** — chaque phase produit un binaire utilisable et
|
||
testé ; la barre des 45+ tests monte à chaque jalon.
|
||
|
||
---
|
||
|
||
## 6. 🧱 Socle technique : le modèle de données
|
||
|
||
*Tout dépend de ceci. À construire en premier, avant les commandes visibles.*
|
||
|
||
state_dir/
|
||
state.json # v2 : + sessions_count, last_used (migration auto depuis v1)
|
||
events.jsonl # NOUVEAU — journal d'événements (source de vérité)
|
||
events-202608.jsonl # rotation mensuelle
|
||
sessions.json # NOUVEAU — registre des sessions (index dérivé)
|
||
history/
|
||
<session>.jsonl # NOUVEAU — historique structuré du REPL
|
||
projects.json # NOUVEAU — agrégats par projet (recalculable)
|
||
probe-cache.json # existant — pattern de cache à suivre
|
||
|
||
| Fichier | Rôle | Alimenté par | Reconstruction |
|
||
|---|---|---|---|
|
||
| events.jsonl | faits bruts (start, stop, run, install…) | process.rs, run_cmd.rs, install_cmd.rs, repl.rs, doctor_cmd.rs | source de vérité, jamais reconstruit |
|
||
| sessions.json | index des sessions | dérivé du journal | doctor --fix (rejoue le journal) |
|
||
| projects.json | agrégats par projet | dérivé du journal | doctor --fix |
|
||
| history/*.jsonl | commandes REPL | repl.rs | non (données primaires) |
|
||
| state.json v2 | installations + résumé | state.rs | partiellement (compteurs depuis le journal) |
|
||
|
||
**Règles :** JSONL append-only pour les faits · JSON dérivés régénérables ·
|
||
migration additive (state v1 reste lisible partout) · doctor --fix répare
|
||
tout ce qui peut l'être.
|
||
|
||
---
|
||
|
||
## 7. 🗂️ Les 12 axes
|
||
|
||
### Axe 1 — 📊 Observabilité & statistiques d'utilisation ⭐
|
||
|
||
🎯 Savoir **quoi** a tourné, **quand**, **combien de temps**, avec **quel
|
||
taux de succès** — et **combien ça coûte**.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Journal d'événements events.jsonl (toutes les actions de am) | M | P0 |
|
||
| am stats + --period 7d/30d/90d + --json (tableaux et barres ASCII) | M | P0 |
|
||
| am top — classement des agents par utilisation | S | P1 |
|
||
| am log — filtres agent/type/date, --follow | S → M | P0 → P1 |
|
||
| am report — rapport hebdo/mensuel en markdown (top agents, échecs, changements) | M | P1 |
|
||
| Suivi des coûts — tokens/€ par session quand l'agent expose son usage (Claude Code --output-format json, Codex…) | M | P2 |
|
||
| am monitor — TUI temps réel : CPU/mémoire par PID, uptime, alertes | L | P2 |
|
||
| Télémétrie anonyme **opt-in** (compteurs agrégés uniquement, jamais de chemins) | M | P3 |
|
||
|
||
am stats # vue globale
|
||
am stats claude-code --period 30d
|
||
am top # qui tourne le plus
|
||
am report --last-week # digest markdown
|
||
|
||
### Axe 2 — 💾 Historique des commandes ⭐
|
||
|
||
🎯 Gérer, **rechercher** et **réutiliser** tout ce qui a été tapé.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Historique structuré : history/<session>.jsonl (cmd, kind am/shell, cwd, durée, exit, agent) + migration de history.txt | M | P0 |
|
||
| am history — filtres --kind, --cwd, --search, --failed, --session | M | P0 |
|
||
| Ctrl-R + !! + !install + !42 + ^old^new dans le REPL | M | P1 |
|
||
| am history --rerun 42 (réexécution confirmée) | S | P1 |
|
||
| Playbooks : am history 12..25 --save deploy.yaml puis am playbook deploy.yaml | L | P2 |
|
||
|
||
am history --search "install" --failed
|
||
am history --rerun 42
|
||
|
||
### Axe 3 — 🧭 Projets & workspaces ⭐
|
||
|
||
🎯 Centraliser **quel agent travaille sur quel projet** — automatiquement.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Contexte auto au lancement : racine + branche git, stack détectée (Cargo.toml, package.json…), mis en cache | S | P0 |
|
||
| am projects / am projects api — agents, sessions, durées, dernière activité | M | P1 |
|
||
| Profils de projet dans config : default_agent, env, hooks | M | P1 |
|
||
| am start (sans argument) = agent par défaut du dossier courant ; REPL contextuel | S | P1 |
|
||
| am init — génère un agent-manager.yaml selon la stack détectée | S → M | P0 |
|
||
| Templates : am init --template web | M | P2 |
|
||
|
||
am projects
|
||
am projects api
|
||
am init # dans un projet Node → config pré-remplie
|
||
|
||
### Axe 4 — 🗂️ Sessions centralisées ⭐
|
||
|
||
🎯 Un registre unique de **toutes les sessions de tous les agents** —
|
||
consultable, reprenable, archivable.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| sessions.json + session_id() partagé (repl.rs) ; fin de session avec exit code et durée | M | P0 |
|
||
| Réconciliation au démarrage : sessions interrompues (crash, reboot) marquées et datées | S | P0 |
|
||
| am sessions — filtres agent/projet/statut ; show = résumé + extrait de log | M | P0 |
|
||
| am timeline — vue chronologique unifiée de toute l'activité | M | P1 |
|
||
| am sessions resume <id> — relance avec les mêmes args/env/cwd | M | P1 |
|
||
| am sessions export <id> + rétention configurable (settings.sessions_retention_days) | M | P2 |
|
||
|
||
am sessions --status failed
|
||
am sessions show 20260815_143926_a1b2c3
|
||
am timeline --project api
|
||
|
||
### Axe 5 — 🖥️ Tableau de bord
|
||
|
||
🎯 Voir l'état du parc d'un coup d'œil.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| am dashboard — TUI (ratatui/crossterm) : vue d'ensemble, activité en direct, stats, sessions, projets | L | P1 |
|
||
| am web — serveur local + API JSON + page HTML embarquée avec graphiques | XL | P2 |
|
||
|
||
### Axe 6 — 🤖 Automatisation & orchestration
|
||
|
||
🎯 Laisser am **superviser et piloter seul** le parc.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Hooks on_install / on_start / on_stop / on_update (agent, projet, global) — via le runner existant | M | P0 |
|
||
| am watch claude-code --restart-on-crash --notify | M | P1 |
|
||
| Services : unités systemd / plists launchd / tâches Windows, am service install claude-code --autostart | L | P2 |
|
||
| Planification : am schedule --daily update --all + check santé (cron / Task Scheduler) | M | P2 |
|
||
| Orchestration de groupes : ordre, --parallel, attente de santé | L | P2 |
|
||
| Conteneurs : profil docker/podman par agent (isolation à la demande) | L | P2 |
|
||
| am doctor --watch — vérifications périodiques avec alertes | M | P2 |
|
||
|
||
### Axe 7 — 🧠 Intelligence & catalogue
|
||
|
||
🎯 Trouver le bon agent, suivre leurs sorties, et comparer.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Recherche fuzzy dans am search (typos, scoring, « vouliez-vous dire ») | M | P1 |
|
||
| am compare a b — tableau côte à côte (méthode, deps, catégorie, activité) | S | P1 |
|
||
| am news — dernières releases des agents installés (API GitHub/Gitea, cache) | M | P1 |
|
||
| Catalogue distant : am catalog update / am catalog add <url> | M | P2 |
|
||
| am suggest "un agent pour du Python" — tags + usage réel | M | P2 |
|
||
| am lab — benchmark : même tâche sur N agents, comparaison durée/résultat/coût | L | P2 |
|
||
| Registre communautaire : publier son catalogue (Gitea) + am registry | L | P3 |
|
||
| am ask "installe claude et lance-le" — langage naturel → commande am (fournisseur LLM configurable, optionnel) | L | P3 |
|
||
|
||
### Axe 8 — 🔒 Sécurité & gouvernance
|
||
|
||
🎯 Protéger les secrets, tracer les changements, pouvoir revenir en arrière.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| am secret set OPENAI_KEY --agent claude-code (keyring OS) + injection --env automatique | M | P1 |
|
||
| am audit — qui a modifié quoi quand (checksums des configs, événements) | M | P2 |
|
||
| am update --rollback — backup automatique avant chaque mise à jour | M | P2 |
|
||
| Politiques : pin de version, settings.update_policy | S | P2 |
|
||
| Profils sandbox par agent (commandes/répertoires autorisés) | L | P3 |
|
||
|
||
### Axe 9 — 🌐 Multi-machine & collaboration
|
||
|
||
🎯 Retrouver son cockpit partout, et le partager.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Synchronisation git automatique : settings.sync_repo, am sync, push à la fermeture du REPL | L | P2 |
|
||
| Partage de catalogue d'équipe : include par URL | S | P2 |
|
||
| am migrate — assistant de transfert machine A → B | M | P2 |
|
||
| am serve --token — API HTTP + WebSocket pour piloter à distance | XL | P3 |
|
||
|
||
### Axe 10 — 🧩 Confort & personnalisation
|
||
|
||
🎯 Adapter am à sa façon de travailler.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Favoris : am favorite / am unfavorite + ⭐ dans am list | S | P1 |
|
||
| Notes : am note claude-code "utiliser pour …" | S | P1 |
|
||
| Tags personnels : am tag claude-code python | S | P1 |
|
||
| Raccourcis de commandes : settings.shortcuts (i → install, s → start) | S | P1 |
|
||
| Profils d'environnement : am profile dev / prod (env + args + agent par profil) | M | P1 |
|
||
| Thèmes couleurs du REPL | S | P2 |
|
||
|
||
### Axe 11 — 🎛️ Modèles locaux
|
||
|
||
🎯 Étendre le cockpit aux modèles : **ollama, llama.cpp, LM Studio**.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| am models — inventaire : nom, taille disque, quantisation, dernière utilisation | M | P2 |
|
||
| Lien agent ↔ modèle : am run mon-agent --model llama3.1 | M | P2 |
|
||
| doctor vérifie ollama / llama-server comme n'importe quel outil | S | P2 |
|
||
| am models prune — purge des modèles inutilisés | S | P2 |
|
||
|
||
### Axe 12 — 🛠️ Écosystème & expérience développeur
|
||
|
||
🎯 Rendre am disponible partout et contribuable.
|
||
|
||
| Fonctionnalité | Effort | Phase |
|
||
|---|---|---|
|
||
| Fixtures d'événements rejouables + tests de bout en bout du journal | S | P0 |
|
||
| Packaging officiel : winget, scoop, deb/rpm, Homebrew + CI de release | M | P1 |
|
||
| Complétions dynamiques (agents installés, groupes personnalisés) | S | P1 |
|
||
| Man pages + documentation générée | S | P1 |
|
||
| i18n : messages EN/FR | L | P2 |
|
||
| Plugin scripts (hooks avancés, intégration CI) | M | P2 |
|
||
|
||
---
|
||
|
||
## 8. 🚀 Jalons versionnés
|
||
|
||
| Jalon | Version | Contenu principal | Durée | Critère de sortie |
|
||
|---|---|---|---|---|
|
||
| **J0 — Fondations** | v0.3.0 | events.jsonl, sessions, am stats, am log, am history, am init, quick wins | ≈ 2 sem | 100 % des actions tracées · 100+ tests |
|
||
| **J1 — Cockpit** | v0.4.0 | recherche fuzzy, Ctrl-R, projects, timeline, dashboard TUI, hooks, secret, favoris, packaging | ≈ 3 sem | retrouver n'importe quelle action passée en < 2 s |
|
||
| **J2 — Automatisation** | v0.5.0 | watch, services, schedule, news/compare, catalogue distant, lab, models, sync | ≈ 4 sem | parc auto-supervisé (crash = redémarrage + alerte) |
|
||
| **J3 — Plateforme** | v1.0 | am web, am serve, am ask, registry, télémétrie opt-in, sandbox | ≈ 6 sem | dashboard web complet + API distante |
|
||
|
||
---
|
||
|
||
## 9. 📈 Indicateurs de succès (KPI)
|
||
|
||
| Indicateur | Cible |
|
||
|---|---|
|
||
| Part des actions tracées dans events.jsonl | 100 % dès la v0.3.0 |
|
||
| Temps pour retrouver une commande ou session passée | < 2 s |
|
||
| am list à chaud, journal actif | < 100 ms |
|
||
| Dépendances runtime ajoutées | 0 |
|
||
| Couverture de tests | ≥ 100 tests en v0.3, +25 par jalon |
|
||
| Contrats --json cassés entre versions mineures | 0 |
|
||
|
||
---
|
||
|
||
## 10. ⚠️ Risques & garde-fous
|
||
|
||
1. **ADN « zéro runtime »** : toute dépendance nouvelle est compilée dans le
|
||
binaire, jamais requise à l'exécution.
|
||
2. **Performance** : le journal grossit — fenêtres temporelles, index dérivés,
|
||
rotation mensuelle, caches façon probe.rs.
|
||
3. **Vie privée** : local par défaut ; télémétrie opt-in, agrégée, anonyme.
|
||
4. **Contrats --json** : ajout de champs sans retrait (scripts utilisateurs).
|
||
5. **Compatibilité** : migrations additives ; les exports 0.2.x restent
|
||
importables en 0.3+.
|
||
6. **Complexité UX** : les fonctions avancées restent derrière
|
||
settings.experimental jusqu'à maturité.
|
||
7. **Périmètre** : rester un orchestrateur — ne pas réimplémenter les
|
||
fonctionnalités propres aux agents (tokens, MCP, prompts), sauf valeur
|
||
transversale (stats, sessions, secrets, coûts).
|
||
|
||
---
|
||
|
||
## 11. 🏁 Par où commencer
|
||
|
||
*Le suivi est en place sur Gitea : 4 milestones (v0.3.0 → v1.0), 22 labels
|
||
(P0–P3, axe-1…axe-12, S/M/L/XL, quick-win, epic) et les issues ci-dessous.
|
||
Chaque PR doit référencer son issue avec `closes #N` pour une clôture
|
||
automatique. Ordre de construction proposé pour la phase 0 — chaque étape
|
||
est un PR indépendant et testé :*
|
||
|
||
1. **[PR 1](https://git.dracodev.net/Projets/agent-manager/issues/2)** — src/events.rs : journal JSONL + rotation + tests.
|
||
2. **[PR 2](https://git.dracodev.net/Projets/agent-manager/issues/3)** — instrumentation start/stop/run (process.rs, run_cmd.rs) — dépend de PR 1.
|
||
3. **[PR 3](https://git.dracodev.net/Projets/agent-manager/issues/4)** — state.json v2 + migration additive — dépend de PR 1.
|
||
4. **[PR 4](https://git.dracodev.net/Projets/agent-manager/issues/5)** — sessions.json + am sessions + réconciliation — dépend de PR 2.
|
||
5. **[PR 5](https://git.dracodev.net/Projets/agent-manager/issues/6)** — am stats + am log (lecture du journal) — dépend de PR 2.
|
||
6. **[PR 6](https://git.dracodev.net/Projets/agent-manager/issues/7)** — historique structuré + am history (migration de history.txt).
|
||
7. **[PR 7](https://git.dracodev.net/Projets/agent-manager/issues/8)** — am init + détection de contexte (git, stack, cache) — dépend de PR 1.
|
||
8. **En parallèle** — les quick wins de la section 3 :
|
||
[am logs #9](https://git.dracodev.net/Projets/agent-manager/issues/9) ·
|
||
[am list --sort #10](https://git.dracodev.net/Projets/agent-manager/issues/10) ·
|
||
[am config set #11](https://git.dracodev.net/Projets/agent-manager/issues/11) ·
|
||
[am alias add #12](https://git.dracodev.net/Projets/agent-manager/issues/12) ·
|
||
[dedup history.txt #13](https://git.dracodev.net/Projets/agent-manager/issues/13) ·
|
||
[am doctor --json #14](https://git.dracodev.net/Projets/agent-manager/issues/14) ·
|
||
[am version --json #15](https://git.dracodev.net/Projets/agent-manager/issues/15) ·
|
||
[am open #16](https://git.dracodev.net/Projets/agent-manager/issues/16).
|
||
|
||
Épique de suivi : [issue #1](https://git.dracodev.net/Projets/agent-manager/issues/1) (Phase 0).
|
||
|
||
---
|
||
|
||
*Document généré à partir de l'analyse du code (v0.2.7, commit d886de3).
|
||
Chaque item peut être chiffré et planifié indépendamment ; les phases 1 à 3
|
||
seront détaillées dans des documents dédiés au moment de leur démarrage.*
|