BV - Beads Viewer
Un motor de triaje basado en grafos para proyectos Beads (.beads/beads.jsonl). Calcula 9 métricas de grafo, genera planes de ejecución y ofrece recomendaciones deterministas. Interfaz TUI para humanos; indicadores robot para agentes de IA.
Por qué BV frente a beads.jsonl sin procesar
| Capacidad | beads.jsonl sin procesar | Modo Robot BV |
|---|---|---|
| Consulta | "Listar todas las incidencias" | "Listar los 5 cuellos de botella principales que bloquean el lanzamiento" |
| Coste de Contexto | Alto (lineal con el número de incidencias) | Bajo (estructura resumida fija) |
| Lógica de Grafo | El agente debe calcularla | Precalculada (PageRank, intermediación, ciclos) |
| Seguridad | El agente podría pasar por alto ciclos | Los ciclos se marcan explícitamente |
Utilice BV en lugar de analizar beads.jsonl directamente. Calcula las métricas de grafo de forma determinista.
CRÍTICO: Modo Robot para Agentes
Nunca ejecute bv sin indicadores. Inicia una TUI interactiva que bloqueará su sesión.
Utilice siempre los indicadores --robot-*:
bv --robot-triage # EL MEGA-COMANDO: empiece aquí
bv --robot-next # Mínimo: solo la mejor opción
bv --robot-plan # Pistas de ejecución en paralelo
bv --robot-insights # Métricas de grafo completas
Las 9 Métricas de Grafo
BV calcula estas métricas para revelar dinámicas ocultas del proyecto:
| Métrica | Qué Mide | Información Clave |
|---|---|---|
| PageRank | Importancia recursiva de dependencias | Bloqueadores fundamentales |
| Intermediación | Tráfico de caminos más cortos | Cuellos de botella y puentes |
| HITS | Dualidad Hub/Autoridad | Épicas vs utilidades |
| Ruta Crítica | Cadena de dependencias más larga | Piedras angulares con margen cero |
| Eigenvector | Influencia a través de vecinos | Dependencias estratégicas |
| Grado | Conteo de conexiones directas | Bloqueadores/bloqueados inmediatos |
| Densidad | Relación aristas/nodos | Salud de acoplamiento del proyecto |
| Ciclos | Dependencias circulares | Errores estructurales (¡debe arreglarse!) |
| Orden Topológico | Orden de ejecución válido | Base de la cola de trabajo |
Análisis en Dos Fases
BV utiliza computación asíncrona con tiempos de espera:
- Fase 1 (instantánea): grado, orden topológico, densidad
- Fase 2 (tiempo de espera de 500ms): PageRank, intermediación, HITS, eigenvector, ciclos
Verifique siempre el campo status en la salida. Para grafos grandes (>500 nodos), algunas métricas pueden ser approx o skipped.
Referencia de Comandos Robot
Triaje y Planificación
bv --robot-triage # Triaje completo: recomendaciones, ganancias rápidas, bloqueadores a eliminar
bv --robot-next # Única mejor opción con comando de reclamación
bv --robot-plan # Pistas de ejecución en paralelo con listas de desbloqueo
bv --robot-priority # Detección de desalineación de prioridades
Análisis de Grafo
bv --robot-insights # Métricas completas: PageRank, intermediación, HITS, ciclos, etc.
bv --robot-label-health # Salud por etiqueta: saludable|advertencia|crítico
bv --robot-label-flow # Matriz de flujo de dependencias entre etiquetas
bv --robot-label-attention # Etiquetas ordenadas por atención
Historial y Cambios
bv --robot-history # Correlaciones bead-commit
bv --robot-diff --diff-since <ref> # Cambios desde la referencia
Otros Comandos
bv --robot-burndown <sprint> # Burndown del sprint, cambios de alcance
bv --robot-forecast <id|all> # Predicciones de ETA
bv --robot-alerts # Incidencias estancadas, cascadas de bloqueo
bv --robot-suggest # Higiene: duplicados, dependencias faltantes, ruptura de ciclos
bv --robot-graph # Exportación de grafo de dependencias (JSON, DOT, Mermaid)
bv --export-graph <file.html> # Visualización HTML interactiva autocontenida
Alcance y Filtrado
bv --robot-plan --label backend # Limitar al subgrafo de la etiqueta
bv --robot-insights --as-of HEAD~30 # Punto histórico en el tiempo
bv --recipe actionable --robot-plan # Prefiltro: listo para trabajar
bv --recipe high-impact --robot-triage # Prefiltro: PageRank más alto
bv --robot-triage --robot-triage-by-track # Agrupar por pistas de trabajo en paralelo
bv --robot-triage --robot-triage-by-label # Agrupar por dominio
Recetas Integradas
| Receta | Propósito |
|---|---|
default | Todas las incidencias abiertas ordenadas por prioridad |
actionable | Listo para trabajar (sin bloqueadores) |
high-impact | Puntuaciones PageRank más altas |
blocked | Esperando dependencias |
stale | Abiertas pero sin tocar durante 30+ días |
triage | Ordenadas por puntuación de triaje calculada |
quick-wins | Elementos P2/P3 fáciles sin bloqueadores |
bottlenecks | Nodos con alta intermediación |
Estructura de Salida del Robot
Todo JSON de robot incluye:
data_hash- Huella digital de beads.jsonl (verificar consistencia)status- Estado por métrica:computed|approx|timeout|skippedas_of/as_of_commit- Presente cuando se usa--as-of
Salida de --robot-triage
{
"quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
"recommendations": [
{ "id": "bd-123", "score": 0.85, "reason": "Desbloquea 5 tareas", "unblock_info": {...} }
],
"quick_wins": [...],
"blockers_to_clear": [...],
"project_health": { "distributions": {...}, "graph_metrics": {...} },
"commands": { "claim": "bd claim bd-123", "view": "bv --bead bd-123" }
}
Salida de --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", ... }
}
Referencia Rápida de jq
bv --robot-triage | jq '.quick_ref' # Resumen de un vistazo
bv --robot-triage | jq '.recommendations[0]' # Mejor recomendación
bv --robot-plan | jq '.plan.summary.highest_impact' # Mejor objetivo de desbloqueo
bv --robot-insights | jq '.status' # Verificar preparación de métricas
bv --robot-insights | jq '.cycles' # Dependencias circulares (¡debe arreglarse!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
Patrón de Flujo de Trabajo del Agente
# 1. Empezar con triaje
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')
# 2. Verificar ciclos primero (errores estructurales)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
echo "Arreglar ciclos primero: $CYCLES"
fi
# 3. Reclamar la tarea
bd claim "$NEXT_TASK"
# 4. Trabajar en ella...
# 5. Cerrar cuando esté listo
bd close "$NEXT_TASK"
Vistas TUI (para Humanos)
Al ejecutar bv de forma interactiva (no para agentes):
| Tecla | Vista |
|---|---|
l | Vista de lista (predeterminada) |
b | Tablero Kanban |
g | Vista de grafo (DAG de dependencias) |
E | Vista de árbol (jerarquía padre-hijo) |
i | Panel de información (6 paneles de métricas) |
h | Vista de historial (correlación bead-commit) |
a | Plan accionable (pistas en paralelo) |
f | Matriz de flujo (dependencias entre etiquetas) |
] | Vista de atención (ranking de prioridad de etiquetas) |
Integración con la CLI bd
BV lee de .beads/beads.jsonl creado por la CLI bd:
bd init # Inicializar beads en el proyecto
bd create "Título de la tarea" # Crear un bead
bd list # Listar beads
bd ready # Mostrar beads accionables
bd claim bd-123 # Reclamar un bead
bd close bd-123 # Cerrar un bead
Integración con el Correo del Agente
Utilice los IDs de bead como IDs de hilo para la coordinación:
file_reservation_paths(..., reason="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] Empezando...")
Formatos de Exportación de Grafo
bv --robot-graph # JSON (predeterminado)
bv --robot-graph --graph-format=dot # Graphviz DOT
bv --robot-graph --graph-format=mermaid # Diagrama Mermaid
bv --robot-graph --graph-root=bd-123 --graph-depth=3 # Subgrafo
bv --export-graph report.html # HTML interactivo
Viaje en el Tiempo
Comparar contra estados históricos:
bv --as-of HEAD~10 # Hace 10 commits
bv --as-of v1.0.0 # En una etiqueta
bv --as-of "2024-01-15" # En una fecha
bv --robot-diff --diff-since HEAD~30 # Cambios en los últimos 30 commits
Errores Comunes
| Problema | Solución |
|---|---|
| La TUI bloquea al agente | Utilice solo indicadores --robot-* |
| Métricas obsoletas | Verifique el campo status, resultados cacheados por data_hash |
| Ciclos faltantes | Ejecute --robot-insights, verifique .cycles |
| Recomendaciones incorrectas | Utilice --recipe actionable para filtrar a trabajo listo |
Notas de Rendimiento
- Métricas de Fase 1 (grado, topo, densidad): instantáneas
- Métricas de Fase 2 (PageRank, intermediación, etc.): tiempo de espera de 500ms
- Resultados cacheados por
data_hash - Prefiera
--robot-plansobre--robot-insightscuando la velocidad importe