Was macht BV - Beads Viewer?
Eine graph-bewusste Triage-Engine für Beads-Projekte (.beads/beads.jsonl). Berechnet 9 Graphmetriken, generiert Ausführungspläne und liefert deterministische Empfehlungen. Menschliche TUI zum Durchsuchen; Roboter-Flags für KI-Agenten.
Warum BV vs. Rohes Beads
| Fähigkeit | Rohes beads.jsonl | BV Roboter-Modus |
|---|---|---|
| Abfrage | "Alle Probleme auflisten" | "Die 5 wichtigsten Engpässe auflisten, die die Veröffentlichung blockieren" |
| Kontextkosten | Hoch (linear mit Anzahl der Probleme) | Niedrig (feste Zusammenfassungsstruktur) |
| Graphlogik | Agent muss berechnen | Vorberechnet (PageRank, Betweenness, Zyklen) |
| Sicherheit | Agent könnte Zyklen übersehen | Zyklen explizit gekennzeichnet |
Verwenden Sie BV anstelle von direktem Parsen von beads.jsonl. Es berechnet Graphmetriken deterministisch.
KRITISCH: Roboter-Modus für Agenten
Führen Sie niemals nacktes bv aus. Es startet eine interaktive TUI, die Ihre Sitzung blockiert.
Verwenden Sie immer die --robot-*-Flags:
bv --robot-triage # DER MEGA-BEFEHL: hier beginnen
bv --robot-next # Minimal: nur der eine Top-Pick
bv --robot-plan # Parallele Ausführungsspuren
bv --robot-insights # Vollständige Graphmetriken
Die 9 Graphmetriken
BV berechnet diese Metriken, um versteckte Projektdynamiken aufzudecken:
| Metrik | Was sie misst | Wichtige Erkenntnis |
|---|---|---|
| PageRank | Rekursive Abhängigkeitsbedeutung | Fundamentale Blocker |
| Betweenness | Verkehr auf kürzesten Pfaden | Engpässe und Brücken |
| HITS | Hub/Authority-Dualität | Epics vs. Hilfsmittel |
| Kritischer Pfad | Längste Abhängigkeitskette | Ecksteine mit null Spielraum |
| Eigenvektor | Einfluss über Nachbarn | Strategische Abhängigkeiten |
| Grad | Direkte Verbindungsanzahlen | Sofortige Blocker/Blockierte |
| Dichte | Kanten-zu-Knoten-Verhältnis | Projektkopplungsgesundheit |
| Zyklen | Zirkuläre Abhängigkeiten | Strukturfehler (muss behoben werden!) |
| Topologische Sortierung | Gültige Ausführungsreihenfolge | Grundlage für Arbeitswarteschlange |
Zwei-Phasen-Analyse
BV verwendet asynchrone Berechnung mit Zeitüberschreitungen:
- Phase 1 (sofort): Grad, topologische Sortierung, Dichte
- Phase 2 (500ms Zeitüberschreitung): PageRank, Betweenness, HITS, Eigenvektor, Zyklen
Überprüfen Sie immer das Feld status in der Ausgabe. Bei großen Graphen (>500 Knoten) können einige Metriken approx oder skipped sein.
Referenz der Roboter-Befehle
Triage & Planung
bv --robot-triage # Vollständige Triage: Empfehlungen, schnelle Erfolge, zu lösende Blocker
bv --robot-next # Einzelner Top-Pick mit Anspruch-Befehl
bv --robot-plan # Parallele Ausführungsspuren mit Entblockungslisten
bv --robot-priority # Erkennung von Prioritätskonflikten
Graphanalyse
bv --robot-insights # Vollständige Metriken: PageRank, Betweenness, HITS, Zyklen, usw.
bv --robot-label-health # Gesundheit pro Label: healthy|warning|critical
bv --robot-label-flow # Labelübergreifende Abhängigkeitsflussmatrix
bv --robot-label-attention # Nach Aufmerksamkeit gereihte Labels
Verlauf & Änderungen
bv --robot-history # Bead-zu-Commit-Korrelationen
bv --robot-diff --diff-since <ref> # Änderungen seit Referenz
Andere Befehle
bv --robot-burndown <sprint> # Sprint-Burndown, Umfangsänderungen
bv --robot-forecast <id|all> # ETA-Vorhersagen
bv --robot-alerts # Veraltete Probleme, blockierende Kaskaden
bv --robot-suggest # Hygiene: Duplikate, fehlende Abhängigkeiten, Zyklusbrüche
bv --robot-graph # Abhängigkeitsgraphen-Export (JSON, DOT, Mermaid)
bv --export-graph <file.html> # Eigenständige interaktive HTML-Visualisierung
Bereichs- & Filterung
bv --robot-plan --label backend # Auf das Teilgraph des Labels beschränken
bv --robot-insights --as-of HEAD~30 # Historischer Zeitpunkt
bv --recipe actionable --robot-plan # Vorfilter: bereit zur Arbeit
bv --recipe high-impact --robot-triage # Vorfilter: höchster PageRank
bv --robot-triage --robot-triage-by-track # Nach parallelen Arbeitsströmen gruppieren
bv --robot-triage --robot-triage-by-label # Nach Domäne gruppieren
Integrierte Rezepte
| Rezept | Zweck |
|---|---|
default | Alle offenen Probleme, nach Priorität sortiert |
actionable | Bereit zur Arbeit (keine Blocker) |
high-impact | Höchste PageRank-Werte |
blocked | Warten auf Abhängigkeiten |
stale | Offen, aber seit 30+ Tagen unbearbeitet |
triage | Sortiert nach berechnetem Triage-Wert |
quick-wins | Einfache P2/P3-Elemente ohne Blocker |
bottlenecks | Knoten mit hoher Betweenness |
Struktur der Roboter-Ausgabe
Alle Roboter-JSON-Ausgaben enthalten:
data_hash- Fingerabdruck von beads.jsonl (Konsistenzprüfung)status- Zustand pro Metrik:computed|approx|timeout|skippedas_of/as_of_commit- Vorhanden bei Verwendung von--as-of
--robot-triage Ausgabe
{
"quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
"recommendations": [
{ "id": "bd-123", "score": 0.85, "reason": "Entblockt 5 Aufgaben", "unblock_info": {...} }
],
"quick_wins": [...],
"blockers_to_clear": [...],
"project_health": { "distributions": {...}, "graph_metrics": {...} },
"commands": { "claim": "bd claim bd-123", "view": "bv --bead bd-123" }
}
--robot-insights Ausgabe
{
"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", ... }
}
jq Kurzreferenz
bv --robot-triage | jq '.quick_ref' # Zusammenfassung auf einen Blick
bv --robot-triage | jq '.recommendations[0]' # Top-Empfehlung
bv --robot-plan | jq '.plan.summary.highest_impact' # Bestes Entblockungsziel
bv --robot-insights | jq '.status' # Metrikbereitschaft prüfen
bv --robot-insights | jq '.cycles' # Zirkuläre Abhängigkeiten (muss repariert werden!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
Agenten-Workflow-Muster
# 1. Mit Triage beginnen
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')
# 2. Zuerst auf Zyklen prüfen (Strukturfehler)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
echo "Zuerst Zyklen beheben: $CYCLES"
fi
# 3. Aufgabe anfordern
bd claim "$NEXT_TASK"
# 4. Daran arbeiten...
# 5. Schließen, wenn erledigt
bd close "$NEXT_TASK"
TUI-Ansichten (für Menschen)
Bei interaktivem Ausführen von bv (nicht für Agenten):
| Taste | Ansicht |
|---|---|
l | Listenansicht (Standard) |
b | Kanban-Board |
g | Graphansicht (Abhängigkeits-DAG) |
E | Baumansicht (Eltern-Kind-Hierarchie) |
i | Einblicke-Dashboard (6-Feld-Metriken) |
h | Verlaufsansicht (Bead-zu-Commit-Korrelation) |
a | Umsetzbarer Plan (parallele Spuren) |
f | Flussmatrix (labelübergreifende Abhängigkeiten) |
] | Aufmerksamkeitsansicht (Label-Prioritätsranking) |
Integration mit der bd CLI
BV liest aus der von der bd CLI erstellten Datei .beads/beads.jsonl:
bd init # Beads im Projekt initialisieren
bd create "Aufgabentitel" # Ein Bead erstellen
bd list # Beads auflisten
bd ready # Umsetzbare Beads anzeigen
bd claim bd-123 # Ein Bead anfordern
bd close bd-123 # Ein Bead schließen
Integration mit Agent Mail
Verwenden Sie Bead-IDs als Thread-IDs zur Koordination:
file_reservation_paths(..., reason="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] Start...")
Graph-Export-Formate
bv --robot-graph # JSON (Standard)
bv --robot-graph --graph-format=dot # Graphviz DOT
bv --robot-graph --graph-format=mermaid # Mermaid-Diagramm
bv --robot-graph --graph-root=bd-123 --graph-depth=3 # Teilgraph
bv --export-graph report.html # Interaktives HTML
Zeitreise
Vergleichen mit historischen Zuständen:
bv --as-of HEAD~10 # Vor 10 Commits
bv --as-of v1.0.0 # Bei Tag
bv --as-of "2024-01-15" # Bei Datum
bv --robot-diff --diff-since HEAD~30 # Änderungen in den letzten 30 Commits
Häufige Fallstricke
| Problem | Lösung |
|---|---|
| TUI blockiert Agent | Nur --robot-*-Flags verwenden |
| Veraltete Metriken | Feld status prüfen, Ergebnisse durch data_hash gecacht |
| Fehlende Zyklen | --robot-insights ausführen, .cycles prüfen |
| Falsche Empfehlungen | --recipe actionable zur Filterung auf bereite Arbeit verwenden |
Leistungshinweise
- Phase-1-Metriken (Grad, topologische Sortierung, Dichte): sofort
- Phase-2-Metriken (PageRank, Betweenness, usw.): 500ms Zeitüberschreitung
- Ergebnisse durch
data_hashgecacht --robot-plandem--robot-insightsvorziehen, wenn Geschwindigkeit wichtig ist