BV - Beads Viewer
Um mecanismo de triagem consciente de grafos para projetos Beads (.beads/beads.jsonl). Calcula 9 métricas de grafos, gera planos de execução e fornece recomendações determinísticas. TUI humana para navegação; flags robô para agentes de IA.
Por que BV vs Beads Bruto
| Capacidade | beads.jsonl Bruto | Modo Robô BV |
|---|---|---|
| Consulta | "Listar todos os problemas" | "Listar os 5 principais gargalos que bloqueiam o lançamento" |
| Custo de Contexto | Alto (linear com o número de problemas) | Baixo (estrutura de resumo fixa) |
| Lógica de Grafo | Agente deve calcular | Pré-calculado (PageRank, intermediação, ciclos) |
| Segurança | Agente pode perder ciclos | Ciclos explicitamente sinalizados |
Use BV em vez de analisar beads.jsonl diretamente. Ele calcula métricas de grafos de forma determinística.
CRÍTICO: Modo Robô para Agentes
Nunca execute bv sem flags. Ele inicia uma TUI interativa que bloqueia sua sessão.
Sempre use as flags --robot-*:
bv --robot-triage # O MEGA-COMANDO: comece aqui
bv --robot-next # Mínimo: apenas a melhor escolha única
bv --robot-plan # Trilhas de execução paralela
bv --robot-insights # Métricas completas do grafo
As 9 Métricas do Grafo
O BV calcula estas métricas para revelar dinâmicas ocultas do projeto:
| Métrica | O Que Mede | Insight Chave |
|---|---|---|
| PageRank | Importância recursiva das dependências | Bloqueadores fundamentais |
| Intermediação | Tráfego do caminho mais curto | Gargalos e pontes |
| HITS | Dualidade Hub/Autoridade | Épicos vs utilidades |
| Caminho Crítico | Maior cadeia de dependências | Pedras angulares com folga zero |
| Autovetor | Influência via vizinhos | Dependências estratégicas |
| Grau | Contagens de conexão direta | Bloqueadores/bloqueados imediatos |
| Densidade | Proporção aresta/nó | Saúde do acoplamento do projeto |
| Ciclos | Dependências circulares | Erros estruturais (devem ser corrigidos!) |
| Ordenação Topológica | Ordem de execução válida | Base da fila de trabalho |
Análise em Duas Fases
O BV usa computação assíncrona com timeouts:
- Fase 1 (instantânea): grau, ordenação topológica, densidade
- Fase 2 (timeout de 500ms): PageRank, intermediação, HITS, autovetor, ciclos
Sempre verifique o campo status na saída. Para grafos grandes (>500 nós), algumas métricas podem ser approx ou skipped.
Referência de Comandos Robô
Triagem e Planejamento
bv --robot-triage # Triagem completa: recomendações, quick_wins, blockers_to_clear
bv --robot-next # Melhor escolha única com comando de reivindicação
bv --robot-plan # Trilhas de execução paralela com listas de desbloqueio
bv --robot-priority # Detecção de desalinhamento de prioridade
Análise de Grafo
bv --robot-insights # Métricas completas: PageRank, intermediação, HITS, ciclos, etc.
bv --robot-label-health # Saúde por rótulo: healthy|warning|critical
bv --robot-label-flow # Matriz de fluxo de dependência entre rótulos
bv --robot-label-attention # Rótulos ordenados por atenção
Histórico e Mudanças
bv --robot-history # Correlações bead-commit
bv --robot-diff --diff-since <ref> # Mudanças desde a referência
Outros Comandos
bv --robot-burndown <sprint> # Burndown da sprint, mudanças de escopo
bv --robot-forecast <id|all> # Previsões de ETA
bv --robot-alerts # Problemas obsoletos, cascatas de bloqueio
bv --robot-suggest # Higiene: duplicatas, dependências ausentes, quebra de ciclos
bv --robot-graph # Exportação do grafo de dependências (JSON, DOT, Mermaid)
bv --export-graph <file.html> # Visualização HTML interativa autocontida
Escopo e Filtragem
bv --robot-plan --label backend # Escopo para o subgrafo do rótulo
bv --robot-insights --as-of HEAD~30 # Ponto histórico no tempo
bv --recipe actionable --robot-plan # Pré-filtro: pronto para trabalhar
bv --recipe high-impact --robot-triage # Pré-filtro: maior PageRank
bv --robot-triage --robot-triage-by-track # Agrupar por fluxos de trabalho paralelos
bv --robot-triage --robot-triage-by-label # Agrupar por domínio
Receitas Embutidas
| Receita | Propósito |
|---|---|
default | Todos os problemas abertos ordenados por prioridade |
actionable | Pronto para trabalhar (sem bloqueadores) |
high-impact | Maiores pontuações de PageRank |
blocked | Aguardando dependências |
stale | Aberto mas sem alterações por 30+ dias |
triage | Ordenado pela pontuação de triagem calculada |
quick-wins | Itens P2/P3 fáceis, sem bloqueadores |
bottlenecks | Nós com alta intermediação |
Estrutura da Saída Robô
Todo JSON robô inclui:
data_hash- Impressão digital de beads.jsonl (verificar consistência)status- Estado por métrica:computed|approx|timeout|skippedas_of/as_of_commit- Presente quando se usa--as-of
Saída --robot-triage
{
"quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
"recommendations": [
{ "id": "bd-123", "score": 0.85, "reason": "Desbloqueia 5 tarefas", "unblock_info": {...} }
],
"quick_wins": [...],
"blockers_to_clear": [...],
"project_health": { "distributions": {...}, "graph_metrics": {...} },
"commands": { "claim": "bd claim bd-123", "view": "bv --bead bd-123" }
}
Saída --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", ... }
}
Referência Rápida jq
bv --robot-triage | jq '.quick_ref' # Resumo rápido
bv --robot-triage | jq '.recommendations[0]' # Melhor recomendação
bv --robot-plan | jq '.plan.summary.highest_impact' # Melhor alvo de desbloqueio
bv --robot-insights | jq '.status' # Verificar prontidão das métricas
bv --robot-insights | jq '.cycles' # Dependências circulares (corrigir!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
Padrão de Fluxo de Trabalho do Agente
# 1. Comece com triagem
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')
# 2. Verifique ciclos primeiro (erros estruturais)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
echo "Corrija os ciclos primeiro: $CYCLES"
fi
# 3. Reivindique a tarefa
bd claim "$NEXT_TASK"
# 4. Trabalhe nela...
# 5. Feche quando concluído
bd close "$NEXT_TASK"
Visualizações TUI (para Humanos)
Ao executar bv interativamente (não para agentes):
| Tecla | Visualização |
|---|---|
l | Visualização em lista (padrão) |
b | Quadro Kanban |
g | Visualização do grafo (DAG de dependências) |
E | Visualização em árvore (hierarquia pai-filho) |
i | Painel de insights (6 painéis de métricas) |
h | Visualização do histórico (correlação bead-commit) |
a | Plano acionável (trilhas paralelas) |
f | Matriz de fluxo (dependências entre rótulos) |
] | Visualização de atenção (ranking de prioridade de rótulos) |
Integração com o CLI bd
O BV lê de .beads/beads.jsonl criado pelo CLI bd:
bd init # Inicializar beads no projeto
bd create "Título da tarefa" # Criar um bead
bd list # Listar beads
bd ready # Mostrar beads acionáveis
bd claim bd-123 # Reivindicar um bead
bd close bd-123 # Fechar um bead
Integração com o Mail do Agente
Use IDs de beads como IDs de thread para coordenação:
file_reservation_paths(..., reason="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] Iniciando...")
Formatos de Exportação do Grafo
bv --robot-graph # JSON (padrão)
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 interativo
Viagem no Tempo
Compare com estados históricos:
bv --as-of HEAD~10 # 10 commits atrás
bv --as-of v1.0.0 # Na tag
bv --as-of "2024-01-15" # Na data
bv --robot-diff --diff-since HEAD~30 # Mudanças nos últimos 30 commits
Armadilhas Comuns
| Problema | Correção |
|---|---|
| TUI bloqueia o agente | Use apenas flags --robot-* |
| Métricas obsoletas | Verifique o campo status, resultados em cache por data_hash |
| Ciclos ausentes | Execute --robot-insights, verifique .cycles |
| Recomendações erradas | Use --recipe actionable para filtrar para trabalho pronto |
Notas de Desempenho
- Métricas da Fase 1 (grau, topo, densidade): instantâneas
- Métricas da Fase 2 (PageRank, intermediação, etc.): timeout de 500ms
- Resultados em cache por
data_hash - Prefira
--robot-planem vez de--robot-insightsquando a velocidade for importante