docs: roadmap v2 - lecture facilitee (sommaire, legende, quick wins, KPI), 12 axes enrichis (modeles locaux, lab, rapports, couts, favoris, profils), jalons versionnes

2026-08-16 12:31:29 -04:00
parent 979875fa63
commit 5841926b25
1 changed files with 381 additions and 0 deletions
@@ -0,0 +1,381 @@
 # 🗺️ 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
 *Ordre de construction proposé pour la phase 0 — chaque étape est un PR
 indépendant et testé :*
 1. **PR 1** — src/events.rs : journal JSONL + rotation + tests.
 2. **PR 2** — instrumentation start/stop/run (process.rs, run_cmd.rs).
 3. **PR 3** — state.json v2 + migration additive.
 4. **PR 4** — sessions.json + am sessions + réconciliation.
 5. **PR 5** — am stats + am log (lecture du journal).
 6. **PR 6** — historique structuré + am history (migration de history.txt).
 7. **PR 7** — am init + détection de contexte (git, stack, cache).
 8. **En parallèle** — les quick wins de la section 3 (am logs, am list --sort,
   am alias add, am config set, am version --json).
 ---
 *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.*