788 lines
26 KiB
Markdown
788 lines
26 KiB
Markdown
# 🏗️ Document d'architecture — agent-manager (`am`)
|
||
|
||
> Ce document décrit la conception, le fonctionnement et les fonctionnalités de **agent-manager** (binaire `am`), un CLI Rust multiplateforme pour gérer des agents IA de coding locaux.
|
||
>
|
||
> 📦 Version : `0.6.0` · 🦀 Rust 2021 · ✅ Windows · ✅ Linux · ✅ macOS
|
||
|
||
---
|
||
|
||
## 🎯 Vue d'ensemble
|
||
|
||
`am` est un gestionnaire d'agents IA de coding qui permet de :
|
||
|
||
- 📋 Découvrir et lister plus de **72 agents** via un catalogue YAML embarqué
|
||
- 📦 Les installer avec **9 méthodes** différentes (npm, pip, uv, cargo, go, bun, curl, binaire, git)
|
||
- 🚀 Les démarrer, arrêter, redémarrer en avant-plan ou en arrière-plan
|
||
- 🔍 Observer leur état, leurs logs, leurs statistiques d'utilisation
|
||
- 🛠️ Gérer dépendances, alias, groupes, profils, secrets, favoris et annotations
|
||
- ⚡ Exécuter des actions shell via langage naturel avec un agent léger (`am ai`)
|
||
|
||
Le tout sans toucher au système : chaque agent est installé dans un répertoire utilisateur isolé.
|
||
|
||
---
|
||
|
||
## 🧩 Architecture globale
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph UI["🖥️ Interfaces utilisateur"]
|
||
CLI["Ligne de commande<br/>clap v4"]
|
||
REPL["Shell interactif<br/>rustyline"]
|
||
TUI["Dashboard TUI<br/>ratatui + crossterm"]
|
||
WEB["Dashboard web<br/>tiny_http (127.0.0.1)"]
|
||
end
|
||
|
||
subgraph CORE["⚙️ Noyau applicatif"]
|
||
APP["App<br/>contexte partagé"]
|
||
CLI_DEF["cli.rs<br/>définition des commandes"]
|
||
CMD["commands/<br/>dispatch"]
|
||
SHELL_AI["shell_ai.rs<br/>agent shell léger"]
|
||
end
|
||
|
||
subgraph DATA["💾 Données persistantes"]
|
||
CONFIG["Configuration YAML<br/>embarquée + utilisateur"]
|
||
CATALOG["Catalog<br/>index agents/alias/groupes"]
|
||
STATE["StateStore<br/>state.json"]
|
||
EVENTS["Journal JSONL<br/>events-YYYYMM.jsonl"]
|
||
CACHE["Probe cache<br/>probe-cache.json"]
|
||
end
|
||
|
||
subgraph EXEC["🔧 Exécution"]
|
||
RUNNER["Runner trait<br/>système / mock"]
|
||
INSTALLERS["installers/<br/>9 méthodes"]
|
||
DEPS["deps.rs<br/>vérification dépendances"]
|
||
PROCESS["process.rs<br/>PID / signaux"]
|
||
end
|
||
|
||
subgraph OBS["👁️ Observation"]
|
||
PROBE["probe.rs<br/>détection agents externes"]
|
||
DASH["dashboard.rs<br/>agrégation"]
|
||
STATS["stats.rs<br/>statistiques"]
|
||
SESSIONS["sessions.rs<br/>registre sessions"]
|
||
end
|
||
|
||
CLI --> APP
|
||
REPL --> APP
|
||
TUI --> APP
|
||
WEB --> APP
|
||
APP --> CLI_DEF
|
||
APP --> SHELL_AI
|
||
APP --> CONFIG
|
||
APP --> CATALOG
|
||
APP --> STATE
|
||
APP --> EVENTS
|
||
APP --> CACHE
|
||
CMD --> RUNNER
|
||
CMD --> INSTALLERS
|
||
CMD --> DEPS
|
||
CMD --> PROCESS
|
||
CMD --> PROBE
|
||
CMD --> DASH
|
||
CMD --> STATS
|
||
CMD --> SESSIONS
|
||
SHELL_AI --> CMD
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Flux d'exécution d'une commande
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant User
|
||
participant main as main.rs
|
||
participant lib as lib.rs
|
||
participant help as help.rs
|
||
participant cli as cli.rs
|
||
participant app as app.rs
|
||
participant cfg as config.rs
|
||
participant state as state.rs
|
||
participant cmd as commands/mod.rs
|
||
participant impl as commands/xxx_cmd.rs
|
||
|
||
User->>main: am install jcode
|
||
main->>lib: main_entry()
|
||
lib->>lib: spawn thread 8 Mo
|
||
lib->>help: intercept(-h/--help) ?
|
||
help-->>lib: None
|
||
lib->>cli: Cli::parse()
|
||
cli-->>lib: Cli { command: Install {...} }
|
||
lib->>app: App::from_cli(cli)
|
||
app->>cfg: load() config embarquée + user
|
||
cfg-->>app: Config
|
||
app->>state: StateStore::new()
|
||
state-->>app: state.json chargé
|
||
app-->>lib: App
|
||
lib->>cmd: commands::execute(&app)
|
||
cmd->>impl: install_cmd::run(...)
|
||
impl->>impl: vérifier dépendances, installer
|
||
impl->>state: persister
|
||
impl->>app: emit(event install)
|
||
impl-->>cmd: Ok(0)
|
||
cmd-->>lib: 0
|
||
lib-->>main: code sortie
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Structure du code source
|
||
|
||
```
|
||
src/
|
||
├── main.rs 🚪 Point d'entrée
|
||
├── lib.rs 🧭 main_entry(), doc du crate
|
||
├── cli.rs 📋 Définition clap de toutes les commandes
|
||
├── app.rs 🧰 Contexte App (config, state, paths, logger, theme)
|
||
├── config.rs ⚙️ Schéma YAML, chargement, fusion, validation
|
||
├── catalog.rs 🔍 Index agents + recherche fuzzy + suggestions
|
||
├── catalog_remote.rs 🌐 Catalogues distants (fetch, cache, includes)
|
||
├── state.rs 💾 Base JSON des installations et annotations
|
||
├── events.rs 📝 Journal d'événements JSONL
|
||
├── runner.rs 🏃 Trait d'exécution système / mock
|
||
├── process.rs ⚙️ Lancement, arrêt, signaux des processus
|
||
├── deps.rs ✅ Vérification et auto-installation des dépendances
|
||
├── toolchain.rs 🖥️ Détection OS / gestionnaire de paquets
|
||
├── download.rs ⬇️ Téléchargement, checksums, extraction
|
||
├── probe.rs 🔎 Détection des agents externes sur le PATH
|
||
├── dashboard.rs 📊 Données agrégées du dashboard
|
||
├── ps.rs 🧮 Table des processus
|
||
├── context.rs 📂 Contexte du projet courant
|
||
├── repl.rs 💬 Shell interactif
|
||
├── shell.rs 🐚 Gestion des shells supportés
|
||
├── help.rs ❓ Aide Nushell-style
|
||
├── output.rs 🖨️ Logger et rendu
|
||
├── tables.rs 📋 Rendu tabulaire
|
||
├── theme.rs 🎨 Thèmes de couleur (REPL et tableaux)
|
||
├── web.rs 🌐 Serveur HTTP local (127.0.0.1) + API JSON + frontend embarqué
|
||
├── serve.rs 🚀 API HTTP + WebSocket authentifiée (pilotage à distance, issue #80)
|
||
├── frontend/ 📄 index.html — dashboard web (HTML5 + CSS + JS vanilla, include_str!)
|
||
├── history.rs ⏪ Historique des commandes
|
||
├── sessions.rs 📅 Registre des sessions
|
||
├── projects.rs 🗂️️ Agrégation par projet
|
||
├── hooks.rs 🪝 Hooks de cycle de vie
|
||
├── secrets.rs 🔒 Gestion des secrets (keyring OS)
|
||
├── providers.rs 🏷️ Registre de providers LLM (base_url, modèles, défaut, @secret)
|
||
├── registry.rs 📦 Registre communautaire de catalogues (manifeste + sha256)
|
||
├── ask.rs 💬 Langage naturel → commandes am (règles locales + LLM optionnel)
|
||
├── sandbox.rs 🛡️ Profils sandbox par agent (allowlist, périmètre, réseau)
|
||
├── telemetry.rs 📈 Télémétrie anonyme opt-in (compteurs agrégés)
|
||
├── lab.rs 🧪 Benchmark d'agents (tâches YAML versionnables)
|
||
├── playbook.rs ▶️ Rejeu pas à pas d'une séquence d'historique
|
||
├── plugins.rs 🔌 Scripts d'extension sur les événements (contrat JSON)
|
||
├── models.rs 🤖 Inventaire des modèles locaux (ollama, llama.cpp, LM Studio)
|
||
├── shell_ai.rs ⚡ Agent shell léger : langage naturel → action shell
|
||
├── sync.rs 🔄 Push git de l'état (journal, sessions, config)
|
||
├── agent_config.rs ⚙️ Adaptateurs de configuration post-install (TOML/YAML/JSON/key=value)
|
||
├── costs.rs 💰 Coûts estimés par agent (tokens in/out, modèles de prix)
|
||
├── automation.rs ⚙️ Services système + tâches planifiées (systemd/launchd/schtasks)
|
||
├── backup.rs 💾 Sauvegardes (update --rollback, migrate)
|
||
├── doctor.rs 🩺 Diagnostics environnement + --fix
|
||
├── nav.rs 🧭 Tables de navigation (ls/dir)
|
||
├── i18n.rs 🌍 Catalogue de traductions FR/EN (--lang, AM_LANG, LANG)
|
||
├── version.rs 🏷️ Informations de version
|
||
├── commands/ 📦 51 modules, un par commande
|
||
└── installers/ 📦 8 installateurs spécialisés
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ Configuration : catalogue YAML extensible
|
||
|
||
### Hiérarchie de chargement
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
EMB["📦 config.yaml<br/>embarqué dans le binaire"] --> MERGE["🔀 Fusion"]
|
||
USER["👤 ~/.config/agent-manager/config.yaml"] --> MERGE
|
||
LOCAL["📂 ./agent-manager.yaml"] --> MERGE
|
||
FLAG["⚡ --config <file>"] --> MERGE
|
||
MERGE --> EFFECTIVE["✅ Configuration effective"]
|
||
```
|
||
|
||
Priorité (la plus prioritaire en dernier) :
|
||
|
||
1. `config.yaml` embarqué (catalogue par défaut, ~72 agents)
|
||
2. `~/.config/agent-manager/config.yaml`
|
||
3. `./agent-manager.yaml` (configuration locale par projet)
|
||
4. `--config <fichier>`
|
||
|
||
### Schéma de configuration
|
||
|
||
```yaml
|
||
version: "1.0"
|
||
|
||
settings:
|
||
install_dir: null # ~/.local/share/agent-manager/agents
|
||
log_dir: null # ~/.local/state/agent-manager/logs
|
||
default_shell: null # shell utilisateur par défaut
|
||
auto_install_deps: true # proposer d'installer les dépendances manquantes
|
||
confirm_before_run: true # confirmer avant les scripts d'installation
|
||
stop_timeout_secs: 5 # délai SIGTERM → SIGKILL
|
||
self_update_repo: Projets/agent-manager
|
||
self_update_base_url: https://git.dracodev.net/api/v1
|
||
theme: null
|
||
hooks:
|
||
on_install: []
|
||
on_start: []
|
||
on_stop: []
|
||
on_update: []
|
||
|
||
aliases:
|
||
cc: claude-code
|
||
gemini: gemini-cli
|
||
|
||
groups:
|
||
dev: [claude-code, aider, codex]
|
||
|
||
include:
|
||
- ./extra-agents.yaml
|
||
|
||
agents:
|
||
- name: claude-code
|
||
display_name: "Claude Code"
|
||
description: "..."
|
||
category: coding-agent
|
||
website: https://github.com/anthropics/claude-code
|
||
install:
|
||
type: npm
|
||
package: "@anthropic-ai/claude-code"
|
||
dependencies:
|
||
- { name: node, min_version: "18.0.0" }
|
||
run: claude
|
||
tags: [anthropic, assistant]
|
||
|
||
profiles:
|
||
dev:
|
||
agent: claude-code
|
||
env: { API_ENV: dev }
|
||
args: [--verbose]
|
||
|
||
projects:
|
||
mon-projet:
|
||
root: ~/projets/mon-projet
|
||
default_agent: claude-code
|
||
env: { KEY: value }
|
||
```
|
||
|
||
### Définition d'un agent (`AgentDef`)
|
||
|
||
| Champ | Description |
|
||
|-------|-------------|
|
||
| `name` | Identifiant unique (slug) |
|
||
| `display_name` | Nom lisible |
|
||
| `description` | Description longue |
|
||
| `category` | Catégorie (coding-agent, assistant, local-first...) |
|
||
| `website` | URL du projet |
|
||
| `install` | Spécification d'installation |
|
||
| `dependencies` | Outils requis (node, python, go...) avec version min |
|
||
| `run` | Commande de lancement |
|
||
| `args` | Arguments par défaut |
|
||
| `env` | Variables d'environnement par défaut |
|
||
| `tags` | Tags pour recherche/filtrage |
|
||
| `installable` | `false` pour les agents SaaS/Desktop |
|
||
| `platforms` | Restriction `linux`/`macos`/`windows` |
|
||
|
||
### Méthodes d'installation supportées
|
||
|
||
| Type | Fichier | Principe |
|
||
|------|---------|----------|
|
||
| `npm` | `installers/npm.rs` | `npm install -g --prefix <root>` |
|
||
| `bun` | `installers/npm.rs` | `bun install -g` |
|
||
| `pip` / `uv` | `installers/pipuv.rs` | virtualenv privé dans `install_dir` |
|
||
| `cargo` | `installers/cargo.rs` | `cargo install --root` |
|
||
| `go` | `installers/golang.rs` | `go install` avec `GOBIN` local |
|
||
| `curl` | `installers/script.rs` | Télécharge et exécute un script |
|
||
| `binary` | `installers/binary.rs` | Release GitHub/Gitea → extraction archive |
|
||
| `git` | `installers/git.rs` | Clone + build + `binary_path` |
|
||
|
||
---
|
||
|
||
## 💾 Gestion des états
|
||
|
||
### `state.json` — base d'installation locale
|
||
|
||
Format JSON version 3, atomique (écriture `.tmp` + `rename`).
|
||
|
||
```json
|
||
{
|
||
"version": 3,
|
||
"installed": {
|
||
"jcode": {
|
||
"name": "jcode",
|
||
"version": "0.76.0",
|
||
"method": "binary",
|
||
"directory": ".../agents/jcode",
|
||
"binaries": ["jcode"],
|
||
"pid": null,
|
||
"installed_at": "...",
|
||
"updated_at": "..."
|
||
}
|
||
},
|
||
"annotations": {
|
||
"jcode": {
|
||
"favorite": true,
|
||
"note": "mon agent préféré",
|
||
"tags": ["perso"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Journal d'événements JSONL
|
||
|
||
- Un fichier par mois : `events-YYYYMM.jsonl`
|
||
- Append-only, horodaté
|
||
- Types d'événements : `start`, `stop`, `run`, `install`, `update`, `uninstall`, `doctor`, `config`, `repl`, `shell`, `annotate`
|
||
- Les secrets ne sont jamais journalisés
|
||
- Source de vérité pour les statistiques, sessions, projets et timeline
|
||
|
||
### Cache de sondes
|
||
|
||
`probe-cache.json` évite de re-scanner le PATH à chaque commande pour détecter les agents externes et leurs versions.
|
||
|
||
---
|
||
|
||
## 🛡️ Gestion des dépendances
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
INSTALL["am install jcode"] --> CHECK["deps::check_dep"]
|
||
CHECK --> MISSING{Manquant ?}
|
||
MISSING -->|Oui| DETECT["toolchain::detect OS"]
|
||
DETECT --> COMMANDS["toolchain::install_commands"]
|
||
COMMANDS --> PROMPT["Proposer la commande"]
|
||
PROMPT --> AUTO["Exécuter si --yes"]
|
||
AUTO --> INSTALL2["installers::run_install"]
|
||
MISSING -->|Non| INSTALL2
|
||
```
|
||
|
||
- `deps.rs` vérifie chaque dépendance via `<outil> --version`
|
||
- `toolchain.rs` détecte l'OS et le gestionnaire de paquets :
|
||
- Windows : `scoop` → `winget`
|
||
- Linux : `apt` / `dnf` / `pacman` / `apk`
|
||
- macOS : `brew`
|
||
- Si `auto_install_deps: true`, `am` propose et peut exécuter la commande d'installation
|
||
- Les dépendances de l'agent (modules npm/pip) restent isolées dans le répertoire `install_dir`
|
||
|
||
---
|
||
|
||
## ⚡ Gestion des processus
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
START["am start <agent>"] --> MODE{Mode ?}
|
||
MODE -->|Foreground| FG["Attache au terminal<br/>Ctrl-C pour quitter"]
|
||
MODE -->|Background| BG["spawn_background()"]
|
||
BG --> LOG["Redirection stdout/stderr<br/>vers log agent"]
|
||
LOG --> PID["Enregistrement PID<br/>dans state.json"]
|
||
PID --> EVENT["Émission événement start"]
|
||
|
||
STOP["am stop <agent>"] --> SIGTERM["SIGTERM"]
|
||
SIGTERM --> WAIT{"Processus terminé ?"}
|
||
WAIT -->|Non| SIGKILL["SIGKILL après timeout"]
|
||
WAIT -->|Oui| CLEAN["PID effacé"]
|
||
```
|
||
|
||
- Démarrage avant-plan (`-f`) ou arrière-plan (`-b`, `--background`)
|
||
- Variables d'environnement injectées via `--env KEY=VALUE`
|
||
- Secrets via `--env KEY=@secret` (résolu depuis le trousseau OS)
|
||
- Arrêt gracieux avec timeout configurable (défaut 5 s)
|
||
- Notifications desktop optionnelles (`--notify`)
|
||
|
||
---
|
||
|
||
## 📋 Commandes détaillées
|
||
|
||
### 🔍 Découvrir
|
||
|
||
| Commande | Description |
|
||
|----------|-------------|
|
||
| `am list` | Agents installés + détectés sur le PATH |
|
||
| `am list --all` | Tout le catalogue avec état |
|
||
| `am search <mot>` | Recherche fuzzy avec suggestions |
|
||
| `am info <agent>` | Fiche détaillée |
|
||
| `am status [agent]` | État, version, PID, logs |
|
||
|
||
### 📦 Cycle de vie
|
||
|
||
| Commande | Description |
|
||
|----------|-------------|
|
||
| `am install <agent>` | Installe un agent et ses dépendances |
|
||
| `am install <agent> --method pip` | Choisit la méthode |
|
||
| `am uninstall <agent> [--purge]` | Désinstalle et nettoie |
|
||
| `am update <agent>` / `--all` | Met à jour |
|
||
| `am start [agent]` | Lance en avant-plan |
|
||
| `am start <agent> -b` | Lance en arrière-plan |
|
||
| `am stop <agent>` | Arrêt gracieux |
|
||
| `am restart <agent>` | Redémarrage |
|
||
| `am run <agent> [args...]` | Exécution directe sans gestion de PID |
|
||
|
||
### 👁️ Observer
|
||
|
||
| Commande | Description |
|
||
|----------|-------------|
|
||
| `am logs <agent>` | Tail du log agent |
|
||
| `am log [agent]` | Journal des événements `am` |
|
||
| `am timeline` | Vue chronologique unifiée |
|
||
| `am sessions [agent]` | Registre des sessions |
|
||
| `am stats [agent] --period 7d` | Statistiques d'utilisation |
|
||
| `am top --period 30d` | Top 10 agents |
|
||
| `am report --last-week` | Rapport markdown |
|
||
| `am projects [nom]` | Agents par projet |
|
||
| `am dashboard` | Dashboard TUI temps réel |
|
||
| `am watch <agent> --restart` | Supervision et relance automatique |
|
||
|
||
### 🎯 Personnaliser
|
||
|
||
| Commande | Description |
|
||
|----------|-------------|
|
||
| `am favorite <agent>` | Marquer comme favori |
|
||
| `am note <agent> <texte>` | Ajouter une note |
|
||
| `am tag <agent> <tag>` | Taguer |
|
||
| `am tags [agent]` | Lister les tags |
|
||
| `am profile list/show <name>` | Profils d'environnement |
|
||
| `am alias add <nom> <cible>` | Créer un alias |
|
||
| `am secret set <nom> --agent <a> --value <v>` | Secret dans le trousseau |
|
||
|
||
### 🛠️ Système
|
||
|
||
| Commande | Description |
|
||
|----------|-------------|
|
||
| `am doctor [--fix]` | Diagnostic environnement |
|
||
| `am config show/path/edit/validate/set` | Gestion config |
|
||
| `am completion <shell>` | Script de complétion |
|
||
| `am man [commande]` | Page de manuel |
|
||
| `am open <agent>` | Ouvrir le répertoire d'installation |
|
||
| `am export/import` | Sauvegarde/restauration |
|
||
| `am self-update [--check]` | Mise à jour de `am` |
|
||
| `am self-uninstall` | Désinstallation complète |
|
||
| `am version` | Version et build |
|
||
| `am` (sans commande) | REPL interactif |
|
||
|
||
### 🤖 Copilote & plateforme (v0.7.0 / v1.0)
|
||
|
||
| Commande | Description |
|
||
|----------|-------------|
|
||
| `am ask "<demande>"` | Langage naturel → commande(s) am : règles locales FR/EN hors-ligne, raffinement LLM optionnel (`settings.ask`), confirmation avant exécution |
|
||
| `am providers list/add/remove/set-token` | Registre LLM centralisé (base_url, modèles, clé par provider au keyring, résolution `@secret`) |
|
||
| `am registry publish/search/install` | Registre communautaire de catalogues (Gitea, manifeste + checksum sha256 vérifié) |
|
||
| `am serve --token [--port]` | API HTTP + WebSocket authentifiée : stats, run, start, stop, ask — rate limiting par IP, TLS derrière reverse proxy |
|
||
| `am web [--port]` | Dashboard web local en lecture seule (127.0.0.1), contrats `--json` réutilisés |
|
||
| `am ai "<prompt>" [--exec] [--files <path>]` | **Shell AI** : langage naturel → commande/action shell via agent léger (AIChat) ; `--dry-run` par défaut, confirmation avant exécution |
|
||
| `am lab --agents a,b --task <f>` | Benchmark comparatif (durée, exit, coût) sur tâches YAML versionnables |
|
||
| `am sync [--message]` | Sauvegarde git de l'état (journal, sessions, config — secrets exclus) |
|
||
| `am migrate export/import` | Bundle de transfert machine A → B (config + état + historique) |
|
||
| `am schedule add/list/remove/run` | Planification de commandes am (cron / Task Scheduler, issue #56) |
|
||
| `am service install <agent>` | Service système (systemd / launchd / tâche Windows, autostart) |
|
||
| `am monitor [--json]` | TUI temps réel des processus gérés (CPU/RSS/uptime) + alertes de seuils |
|
||
| `am models [--prune]` | Inventaire des modèles locaux (ollama, llama.cpp, LM Studio) |
|
||
| `am audit` | Qui a modifié quoi, quand (checksums config + journal) |
|
||
| `am plugins [--test <nom>]` | Scripts d'extension sur les événements (contrat JSON stdin/stdout) |
|
||
|
||
---
|
||
|
||
## 🌐 Options globales
|
||
|
||
Disponibles avant ou après la sous-commande.
|
||
|
||
| Option | Effet |
|
||
|--------|-------|
|
||
| `-c, --config <FILE>` | Fichier de configuration alternatif |
|
||
| `-v, --verbose` | Affiche chaque commande exécutée |
|
||
| `-q, --quiet` | Seules les erreurs sont affichées |
|
||
| `-y, --yes` | Oui à toutes les confirmations |
|
||
| `--dry-run` | Simulation sans modification |
|
||
| `--json` | Sortie JSON structurée |
|
||
| `--no-color` | Désactive les couleurs |
|
||
| `--theme <THEME>` | Thème de couleur |
|
||
|
||
---
|
||
|
||
## 🎨 Fonctionnalités avancées
|
||
|
||
### Alias
|
||
|
||
```yaml
|
||
aliases:
|
||
cc: claude-code
|
||
gemini: gemini-cli
|
||
```
|
||
|
||
`am start cc` démarre `claude-code`.
|
||
|
||
### Groupes
|
||
|
||
```yaml
|
||
groups:
|
||
dev: [claude-code, aider, codex]
|
||
```
|
||
|
||
`am start group:dev` démarre tous les agents du groupe en arrière-plan.
|
||
|
||
### Profils d'environnement
|
||
|
||
```yaml
|
||
profiles:
|
||
dev:
|
||
agent: claude-code
|
||
env: { API_ENV: dev }
|
||
args: [--verbose]
|
||
```
|
||
|
||
`am start --profile dev` lance `claude-code` avec les variables et arguments du profil.
|
||
|
||
### Projets
|
||
|
||
```yaml
|
||
projects:
|
||
mon-projet:
|
||
root: ~/projets/mon-projet
|
||
default_agent: claude-code
|
||
```
|
||
|
||
Dans le répertoire du projet, `am start` sans argument lance l'agent par défaut du projet.
|
||
|
||
### Secrets
|
||
|
||
Les secrets sont stockés dans le trousseau du système d'exploitation (via `keyring`), jamais en clair dans la config.
|
||
|
||
```bash
|
||
am secret set OPENAI_API_KEY --agent claude-code --value sk-...
|
||
am start claude-code --env OPENAI_API_KEY=@secret
|
||
```
|
||
|
||
### Hooks
|
||
|
||
Commandes exécutées automatiquement aux étapes clés du cycle de vie :
|
||
|
||
- `on_install`
|
||
- `on_start`
|
||
- `on_stop`
|
||
- `on_update`
|
||
|
||
Définissables globalement dans `settings.hooks` ou par projet.
|
||
|
||
### Shell interactif (REPL)
|
||
|
||
Lancé par `am` sans sous-commande :
|
||
|
||
- Complétion Tab personnalisée (commandes, agents, alias, groupes, flags, shells, thèmes)
|
||
- Historique des commandes
|
||
- Passerelle système : commandes inconnues exécutées dans le shell actif
|
||
- Commandes internes : `ls`, `dir`, `cd`, `ps`, `where`, `get`, `shell`, `theme`, `exit`, `/help`
|
||
- Bannière ASCII art
|
||
|
||
---
|
||
|
||
## 📊 Dashboard TUI
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
DASH["am dashboard"] --> OVER["Overview"]
|
||
DASH --> ACT["Activité"]
|
||
DASH --> STATS["Statistiques"]
|
||
DASH --> SESS["Sessions"]
|
||
DASH --> PROJ["Projets"]
|
||
```
|
||
|
||
- Navigation : `Tab` / `←` / `→` pour les onglets
|
||
- Défilement : `j` / `k` ou flèches
|
||
- Quitter : `q`
|
||
- Données agrégées depuis `state.json`, le journal d'événements, les sessions et les projets
|
||
|
||
---
|
||
|
||
## 🧪 Tests
|
||
|
||
### Organisation
|
||
|
||
- **Tests unitaires** : dans chaque module `src/*.rs` sous `#[cfg(test)]`
|
||
- **Tests d'intégration** : dans `tests/`
|
||
|
||
### Fichiers de tests notables
|
||
|
||
| Fichier | Couverture |
|
||
|---------|------------|
|
||
| `annotations_test.rs` | Favoris, notes, tags |
|
||
| `config_test.rs` | Chargement/validation/fusion |
|
||
| `dashboard_test.rs` | Dashboard |
|
||
| `doctor_test.rs` | `am doctor` |
|
||
| `dry_run_test.rs` | Mode `--dry-run` |
|
||
| `events_test.rs` | Journal d'événements |
|
||
| `history_test.rs` | Historique |
|
||
| `process_test.rs` | Processus |
|
||
| `profiles_test.rs` | Profils |
|
||
| `projects_test.rs` | Projets |
|
||
| `sessions_test.rs` | Sessions |
|
||
| `stats_test.rs` | Statistiques |
|
||
|
||
Lancer les tests :
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Packaging et distribution
|
||
|
||
```
|
||
dist/ Binaires précompilés
|
||
├── am-linux-x86_64
|
||
├── am-linux-aarch64
|
||
├── am-windows-x86_64.zip
|
||
├── am_0.4.3_amd64.deb
|
||
└── ...
|
||
|
||
packaging/ Scripts de packaging
|
||
├── deb/
|
||
├── rpm/
|
||
├── homebrew/
|
||
├── scoop/
|
||
└── winget/
|
||
|
||
completions/ Scripts de complétion
|
||
├── _am zsh
|
||
├── _am.ps1 PowerShell
|
||
├── am.bash bash
|
||
├── am.elv elvish
|
||
└── am.fish fish
|
||
|
||
man/ Pages de manuel générées
|
||
```
|
||
|
||
- `build.rs` enregistre le commit et la branche git pour `am version`
|
||
- `scripts/build-release.ps1` construit les releases multiplateformes
|
||
- `scripts/render-manifests.ps1` génère les manifests de packaging
|
||
|
||
---
|
||
|
||
## 🗂️️ Arborescence des données utilisateur
|
||
|
||
### Windows
|
||
|
||
```
|
||
%LOCALAPPDATA%\agent-manager\
|
||
├── agents\ installations
|
||
├── logs\ logs agents
|
||
└── state\ state.json, events-*.jsonl, probe-cache.json
|
||
```
|
||
|
||
### Linux
|
||
|
||
```
|
||
~/.local/share/agent-manager/ données
|
||
~/.local/state/agent-manager/ logs, state, events, cache
|
||
~/.config/agent-manager/ config.yaml
|
||
```
|
||
|
||
### macOS
|
||
|
||
```
|
||
~/Library/Application Support/agent-manager/ données
|
||
~/.local/state/agent-manager/ logs, state, events, cache
|
||
~/.config/agent-manager/ config.yaml
|
||
```
|
||
|
||
Variables d'environnement de débogage/test :
|
||
|
||
- `AGENT_MANAGER_DATA` : remplace le répertoire de données
|
||
- `AGENT_MANAGER_STATE` : remplace le répertoire d'état
|
||
|
||
---
|
||
|
||
## 🔐 Sécurité
|
||
|
||
- Mode `--dry-run` universel pour simuler sans modifier
|
||
- Checksums `sha256` pour les binaires téléchargés
|
||
- Confirmation avant exécution des scripts d'installation
|
||
- Secrets dans le trousseau OS, jamais dans les logs ni le journal
|
||
- Installation isolée : aucune modification système
|
||
|
||
---
|
||
|
||
## 🔁 Résumé du flux de données
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
CONFIG["📄 YAML config"] --> CATALOG["📚 Catalog"]
|
||
CATALOG --> INSTALL["📦 Installateurs"]
|
||
INSTALL --> STATE["💾 state.json"]
|
||
STATE --> PROCESS["⚙️ Processus"]
|
||
PROCESS --> EVENTS["📝 Journal JSONL"]
|
||
EVENTS --> STATS["📊 Stats / Dashboard"]
|
||
EVENTS --> SESSIONS["📅 Sessions"]
|
||
EVENTS --> PROJECTS["🗂️️ Projets"]
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ Shell AI
|
||
|
||
`am ai` (alias `am shell`) est une commande dédiée aux **actions shell via langage naturel**. Elle repose sur un agent léger (par défaut **AIChat**, installé comme n'importe quel autre agent via le catalogue) et réutilise le registre de providers LLM (`providers.rs`) pour choisir le modèle le plus rapide/cheap.
|
||
|
||
### Flux d'exécution
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant User
|
||
participant cli as cli.rs
|
||
participant shell_ai as shell_ai.rs
|
||
participant catalog as catalog.rs
|
||
participant providers as providers.rs
|
||
participant runner as runner.rs
|
||
participant aichat as aichat (agent)
|
||
|
||
User->>cli: am ai "traite les JSON"
|
||
cli->>shell_ai: parse args (--exec, --files)
|
||
shell_ai->>catalog: agent "aichat" installé ?
|
||
catalog-->>shell_ai: Ok / install
|
||
shell_ai->>providers: provider & modèle par défaut
|
||
providers-->>shell_ai: config (ollama / cheap cloud)
|
||
shell_ai->>shell_ai: injecte cwd + fichiers (--files)
|
||
shell_ai->>runner: exec aichat -f . -e "..."
|
||
runner->>aichat: lancement processus
|
||
aichat-->>runner: commande générée / exécutée
|
||
runner-->>shell_ai: output + exit code
|
||
shell_ai->>shell_ai: journalise événement shell_ai
|
||
shell_ai-->>User: résultat ou confirmation
|
||
```
|
||
|
||
### Sécurité
|
||
|
||
| Règle | Détail |
|
||
|---|---|
|
||
| `--dry-run` par défaut | Aucune commande modifiante n'est exécutée sans confirmation |
|
||
| Classification risk/certainty | Inspiré d'AI CLI : chaque commande est classée `safe` ou `risky` |
|
||
| Confirmation utilisateur | Les commandes `risky` demandent une validation explicite |
|
||
| Mode local possible | Support d'Ollama via `providers.rs` pour ne pas sortir les données |
|
||
|
||
### Dépendances
|
||
|
||
- `src/shell_ai.rs` : parsing du prompt, gestion des flags, appel à l'agent
|
||
- `src/providers.rs` : résolution du provider/modèle
|
||
- `src/runner.rs` : exécution du binaire `aichat`
|
||
- `src/events.rs` : journalisation `shell_ai` dans le journal JSONL
|
||
- `config.yaml` : définition de l'agent `aichat` + alias `ai`
|
||
|
||
---
|
||
|
||
## 📚 Références
|
||
|
||
- `src/lib.rs:4` : documentation d'architecture du crate
|
||
- `src/cli.rs:24` : options globales
|
||
- `src/cli.rs:61` : énumération des commandes
|
||
- `src/app.rs:16` : struct `App`
|
||
- `src/config.rs:25` : struct `Config`
|
||
- `src/config.rs:148` : struct `AgentDef`
|
||
- `src/config.rs:241` : enum `InstallType`
|
||
- `src/state.rs:12` : struct `StateFile`
|
||
- `src/events.rs:57` : struct `Event`
|
||
- `README.md` : documentation utilisateur complète
|
||
|
||
---
|
||
|
||
*Document généré pour agent-manager v0.4.3* 🚀
|