Que fait BV - Beads Viewer ?
Un moteur de triage orienté graphe pour les projets Beads (.beads/beads.jsonl). Calcule 9 métriques de graphe, génère des plans d'exécution et fournit des recommandations déterministes. Interface TUI humaine pour la navigation ; flags robot pour les agents IA.
Pourquoi BV vs Beads bruts
| Capacité | beads.jsonl brut | Mode Robot BV |
|---|---|---|
| Requête | "Lister tous les problèmes" | "Lister les 5 principaux goulots d'étranglement bloquant la version" |
| Coût contextuel | Élevé (linéaire avec le nombre de problèmes) | Faible (structure résumée fixe) |
| Logique de graphe | L'agent doit calculer | Pré-calculé (PageRank, intermédiarité, cycles) |
| Sécurité | L'agent pourrait oublier les cycles | Cycles explicitement signalés |
Utilisez BV au lieu d'analyser directement les beads.jsonl. Il calcule les métriques de graphe de manière déterministe.
CRITIQUE : Mode Robot pour les Agents
N'exécutez jamais bv nu. Il lance une interface TUI interactive qui bloque votre session.
Utilisez toujours les flags --robot-* :
bv --robot-triage # LA MÉGA-COMMANDE : commencez ici
bv --robot-next # Minimal : juste le meilleur choix unique
bv --robot-plan # Pistes d'exécution parallèles
bv --robot-insights # Métriques de graphe complètes
Les 9 Métriques de Graphe
BV calcule ces métriques pour révéler les dynamiques cachées du projet :
| Métrique | Ce qu'elle mesure | Information clé |
|---|---|---|
| PageRank | Importance récursive des dépendances | Bloqueurs fondamentaux |
| Intermédiarité | Trafic sur le chemin le plus court | Goulots d'étranglement et ponts |
| HITS | Dualité Hub/Autorité | Epics vs utilitaires |
| Chemin critique | Chaîne de dépendance la plus longue | Pierres angulaires sans marge |
| Vecteur propre | Influence via les voisins | Dépendances stratégiques |
| Degré | Nombre de connexions directes | Bloqueurs/bloqués immédiats |
| Densité | Rapport arêtes/sommets | Santé du couplage du projet |
| Cycles | Dépendances circulaires | Erreurs structurelles (à corriger !) |
| Tri topologique | Ordre d'exécution valide | Base de la file de travail |
Analyse en Deux Phases
BV utilise un calcul asynchrone avec timeout :
- Phase 1 (instantanée) : degré, tri topologique, densité
- Phase 2 (timeout de 500 ms) : PageRank, intermédiarité, HITS, vecteur propre, cycles
Vérifiez toujours le champ status dans la sortie. Pour les grands graphes (>500 nœuds), certaines métriques peuvent être approx ou skipped.
Référence des Commandes Robot
Triage & Planification
bv --robot-triage # Triage complet : recommandations, gains rapides, bloqueurs à lever
bv --robot-next # Meilleur choix unique avec commande de réclamation
bv --robot-plan # Pistes d'exécution parallèles avec listes de déblocage
bv --robot-priority # Détection de désalignement de priorité
Analyse de Graphe
bv --robot-insights # Métriques complètes : PageRank, intermédiarité, HITS, cycles, etc.
bv --robot-label-health # Santé par étiquette : healthy|warning|critical
bv --robot-label-flow # Matrice de flux de dépendances inter-étiquettes
bv --robot-label-attention # Étiquettes classées par attention
Historique & Modifications
bv --robot-history # Corrélations bead-commit
bv --robot-diff --diff-since <ref> # Changements depuis ref
Autres Commandes
bv --robot-burndown <sprint> # Burndown du sprint, changements de périmètre
bv --robot-forecast <id|all> # Prédictions d'ETA
bv --robot-alerts # Problèmes stagnants, cascades de blocage
bv --robot-suggest # Hygiène : doublons, dépendances manquantes, casses de cycles
bv --robot-graph # Export du graphe de dépendances (JSON, DOT, Mermaid)
bv --export-graph <file.html> # Visualisation HTML interactive autonome
Cadrage & Filtrage
bv --robot-plan --label backend # Cadrer au sous-graphe de l'étiquette
bv --robot-insights --as-of HEAD~30 # Point historique dans le temps
bv --recipe actionable --robot-plan # Pré-filtre : prêt à travailler
bv --recipe high-impact --robot-triage # Pré-filtre : top PageRank
bv --robot-triage --robot-triage-by-track # Grouper par pistes de travail parallèles
bv --robot-triage --robot-triage-by-label # Grouper par domaine
Recettes Intégrées
| Recette | Objectif |
|---|---|
default | Tous les problèmes ouverts triés par priorité |
actionable | Prêt à travailler (aucun bloqueur) |
high-impact | Scores PageRank les plus élevés |
blocked | En attente de dépendances |
stale | Ouvert mais inchangé depuis 30+ jours |
triage | Trié par score de triage calculé |
quick-wins | Éléments P2/P3 faciles sans bloqueurs |
bottlenecks | Nœuds à haute intermédiarité |
Structure de Sortie Robot
Tout JSON robot inclut :
data_hash- Empreinte de beads.jsonl (vérifier la cohérence)status- État par métrique :computed|approx|timeout|skippedas_of/as_of_commit- Présent lors de l'utilisation de--as-of
Sortie --robot-triage
{
"quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
"recommendations": [
{ "id": "bd-123", "score": 0.85, "reason": "Débloque 5 tâches", "unblock_info": {...} }
],
"quick_wins": [...],
"blockers_to_clear": [...],
"project_health": { "distributions": {...}, "graph_metrics": {...} },
"commands": { "claim": "bd claim bd-123", "view": "bv --bead bd-123" }
}
Sortie --robot-insights
{
"bottlenecks": [{ "id": "bd-123", "value": 0.45 }],
"keystones": [{ "id": "bd-456", "value": 12.0 }],
"influencers": [...],
"hubs": [...],
"authorities": [...],
"cycles": [["bd-A", "bd-B", "bd-A"]],
"clusterDensity": 0.045,
"status": { "pagerank": "computed", "betweenness": "computed", ... }
}
Référence Rapide jq
bv --robot-triage | jq '.quick_ref' # Résumé en un coup d'œil
bv --robot-triage | jq '.recommendations[0]' # Meilleure recommandation
bv --robot-plan | jq '.plan.summary.highest_impact' # Meilleure cible de déblocage
bv --robot-insights | jq '.status' # Vérifier l'état des métriques
bv --robot-insights | jq '.cycles' # Dépendances circulaires (à corriger !)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
Modèle de Flux de Travail Agent
# 1. Commencer par le triage
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')
# 2. Vérifier d'abord les cycles (erreurs structurelles)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
echo "Corriger d'abord les cycles : $CYCLES"
fi
# 3. Réclamer la tâche
bd claim "$NEXT_TASK"
# 4. Travailler dessus...
# 5. Fermer une fois terminé
bd close "$NEXT_TASK"
Vues TUI (pour les Humains)
Lorsque vous exécutez bv de manière interactive (pas pour les agents) :
| Touche | Vue |
|---|---|
l | Vue liste (par défaut) |
b | Tableau Kanban |
g | Vue graphe (DAG de dépendances) |
E | Vue arborescente (hiérarchie parent-enfant) |
i | Tableau de bord d'informations (6 panneaux de métriques) |
h | Vue historique (corrélation bead-commit) |
a | Plan actionnable (pistes parallèles) |
f | Matrice de flux (dépendances inter-étiquettes) |
] | Vue attention (classement de priorité des étiquettes) |
Intégration avec la CLI bd
BV lit depuis .beads/beads.jsonl créé par la CLI bd :
bd init # Initialiser les beads dans le projet
bd create "Titre de la tâche" # Créer un bead
bd list # Lister les beads
bd ready # Afficher les beads actionnables
bd claim bd-123 # Réclamer un bead
bd close bd-123 # Fermer un bead
Intégration avec le Courrier Agent
Utilisez les IDs des beads comme identifiants de fil de discussion pour la coordination :
file_reservation_paths(..., reason="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] Démarrage...")
Formats d'Export de Graphe
bv --robot-graph # JSON (par défaut)
bv --robot-graph --graph-format=dot # Graphviz DOT
bv --robot-graph --graph-format=mermaid # Diagramme Mermaid
bv --robot-graph --graph-root=bd-123 --graph-depth=3 # Sous-graphe
bv --export-graph report.html # HTML interactif
Voyage Temporel
Comparez avec des états historiques :
bv --as-of HEAD~10 # Il y a 10 commits
bv --as-of v1.0.0 # À un tag
bv --as-of "2024-01-15" # À une date
bv --robot-diff --diff-since HEAD~30 # Changements dans les 30 derniers commits
Pièges Courants
| Problème | Correction |
|---|---|
| TUI bloque l'agent | Utilisez uniquement les flags --robot-* |
| Métriques obsolètes | Vérifiez le champ status, résultats mis en cache par data_hash |
| Cycles manquants | Exécutez --robot-insights, vérifiez .cycles |
| Mauvaises recommandations | Utilisez --recipe actionable pour filtrer le travail prêt |
Notes de Performance
- Métriques de Phase 1 (degré, topo, densité) : instantanées
- Métriques de Phase 2 (PageRank, intermédiarité, etc.) : timeout de 500 ms
- Résultats mis en cache par
data_hash - Préférez
--robot-planà--robot-insightsquand la vitesse compte