bv - Beads Viewer은(는) 무엇을 하나요?
Beads 프로젝트(.beads/beads.jsonl)를 위한 그래프 인식 트라이지 엔진입니다. 9가지 그래프 메트릭을 계산하고, 실행 계획을 생성하며, 결정론적 권장 사항을 제공합니다. 사람을 위한 TUI; AI 에이전트를 위한 로봇 플래그.
BV vs raw Beads
| 기능 | Raw beads.jsonl | BV 로봇 모드 |
|---|---|---|
| 질의 | "모든 이슈 나열" | "릴리스를 막는 상위 5개 병목 현상 나열" |
| 컨텍스트 비용 | 높음 (이슈 수에 선형) | 낮음 (고정 요약 구조) |
| 그래프 로직 | 에이전트가 계산해야 함 | 사전 계산됨 (PageRank, 매개 중심성, 사이클) |
| 안전성 | 에이전트가 사이클을 놓칠 수 있음 | 사이클이 명시적으로 표시됨 |
Beads JSONL을 직접 파싱하는 대신 BV를 사용하세요. 그래프 메트릭을 결정론적으로 계산합니다.
중요: 에이전트를 위한 로봇 모드
절대로 bv를 단독으로 실행하지 마세요. 대화형 TUI가 시작되어 세션을 차단합니다.
항상 --robot-* 플래그를 사용하세요:
bv --robot-triage # 메가 명령어: 여기서 시작
bv --robot-next # 최소: 단일 최상위 선택
bv --robot-plan # 병렬 실행 트랙
bv --robot-insights # 전체 그래프 메트릭
9가지 그래프 메트릭
BV는 프로젝트의 숨겨진 동적을 표면화하기 위해 다음 메트릭을 계산합니다:
| 메트릭 | 측정 대상 | 주요 인사이트 |
|---|---|---|
| PageRank | 재귀적 의존성 중요도 | 기초 차단 항목 |
| 매개 중심성 | 최단 경로 트래픽 | 병목 현상 및 브릿지 |
| HITS | 허브/권위 이중성 | 에픽 대 유틸리티 |
| 중요 경로 | 가장 긴 의존성 체인 | 여유 시간이 없는 핵심 요소 |
| 고유 벡터 중심성 | 이웃을 통한 영향력 | 전략적 의존성 |
| 차수 | 직접 연결 수 | 즉각적인 차단/차단된 항목 |
| 밀도 | 간선 대 노드 비율 | 프로젝트 결합 상태 |
| 사이클 | 순환 의존성 | 구조적 오류 (반드시 수정!) |
| 위상 정렬 | 유효한 실행 순서 | 작업 큐 기반 |
두 단계 분석
BV는 타임아웃과 함께 비동기 계산을 사용합니다:
- 1단계 (즉시): 차수, 위상 정렬, 밀도
- 2단계 (500ms 타임아웃): PageRank, 매개 중심성, HITS, 고유 벡터 중심성, 사이클
출력에서 항상 status 필드를 확인하세요. 대규모 그래프(500노드 초과)의 경우 일부 메트릭이 approx 또는 skipped일 수 있습니다.
로봇 명령어 참조
트라이지 및 계획
bv --robot-triage # 전체 트라이지: 권장 사항, 퀵윈, 해결해야 할 차단 항목
bv --robot-next # 클레임 명령어가 포함된 단일 최상위 선택
bv --robot-plan # 언블록 목록이 포함된 병렬 실행 트랙
bv --robot-priority # 우선순위 불일치 감지
그래프 분석
bv --robot-insights # 전체 메트릭: PageRank, 매개 중심성, HITS, 사이클 등
bv --robot-label-health # 레이블별 상태: healthy|warning|critical
bv --robot-label-flow # 교차 레이블 의존성 흐름 행렬
bv --robot-label-attention # 주의 순위별 레이블
히스토리 및 변경 사항
bv --robot-history # 비드-커밋 상관 관계
bv --robot-diff --diff-since <ref> # 참조 이후 변경 사항
기타 명령어
bv --robot-burndown <sprint> # 스프린트 번다운, 범위 변경
bv --robot-forecast <id|all> # ETA 예측
bv --robot-alerts # 오래된 이슈, 차단 캐스케이드
bv --robot-suggest # 위생: 중복, 누락된 의존성, 사이클 해제
bv --robot-graph # 의존성 그래프 내보내기 (JSON, DOT, Mermaid)
bv --export-graph <file.html> # 자체 포함된 대화형 HTML 시각화
범위 지정 및 필터링
bv --robot-plan --label backend # 레이블의 서브그래프로 범위 지정
bv --robot-insights --as-of HEAD~30 # 과거 시점
bv --recipe actionable --robot-plan # 사전 필터: 작업 준비 완료
bv --recipe high-impact --robot-triage # 사전 필터: 상위 PageRank
bv --robot-triage --robot-triage-by-track # 병렬 작업 스트림별 그룹화
bv --robot-triage --robot-triage-by-label # 도메인별 그룹화
내장 레시피
| 레시피 | 목적 |
|---|---|
default | 모든 열린 이슈를 우선순위별로 정렬 |
actionable | 작업 준비 완료 (차단 항목 없음) |
high-impact | 상위 PageRank 점수 |
blocked | 의존성 대기 중 |
stale | 30일 이상 열려 있지만 수정되지 않음 |
triage | 계산된 트라이지 점수별 정렬 |
quick-wins | 차단 항목이 없는 쉬운 P2/P3 항목 |
bottlenecks | 높은 매개 중심성 노드 |
로봇 출력 구조
모든 로봇 JSON에는 다음이 포함됩니다:
data_hash- beads.jsonl의 지문 (일관성 확인)status- 메트릭별 상태:computed|approx|timeout|skippedas_of/as_of_commit---as-of사용 시 표시
--robot-triage 출력
{
"quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
"recommendations": [
{ "id": "bd-123", "score": 0.85, "reason": "5개 작업 차단 해제", "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 출력
{
"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 빠른 참조
bv --robot-triage | jq '.quick_ref' # 한눈에 보는 요약
bv --robot-triage | jq '.recommendations[0]' # 최상위 권장 사항
bv --robot-plan | jq '.plan.summary.highest_impact' # 최고 차단 해제 대상
bv --robot-insights | jq '.status' # 메트릭 준비 상태 확인
bv --robot-insights | jq '.cycles' # 순환 의존성 (반드시 수정!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
에이전트 워크플로우 패턴
# 1. 트라이지로 시작
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')
# 2. 먼저 사이클 확인 (구조적 오류)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
echo "사이클을 먼저 수정하세요: $CYCLES"
fi
# 3. 작업 클레임
bd claim "$NEXT_TASK"
# 4. 작업 수행...
# 5. 완료 시 종료
bd close "$NEXT_TASK"
TUI 보기 (사람용)
bv를 대화형 모드로 실행할 때 (에이전트용 아님):
| 키 | 보기 |
|---|---|
l | 목록 보기 (기본값) |
b | 칸반 보드 |
g | 그래프 보기 (의존성 DAG) |
E | 트리 보기 (상위-하위 계층) |
i | 인사이트 대시보드 (6패널 메트릭) |
h | 히스토리 보기 (비드-커밋 상관 관계) |
a | 실행 가능한 계획 (병렬 트랙) |
f | 흐름 행렬 (교차 레이블 의존성) |
] | 주의 보기 (레이블 우선순위 순위) |
bd CLI와의 통합
BV는 bd CLI가 생성한 .beads/beads.jsonl에서 읽습니다:
bd init # 프로젝트에서 비드 초기화
bd create "작업 제목" # 비드 생성
bd list # 비드 나열
bd ready # 실행 가능한 비드 표시
bd claim bd-123 # 비드 클레임
bd close bd-123 # 비드 종료
에이전트 메일과의 통합
비드 ID를 협업을 위한 스레드 ID로 사용하세요:
file_reservation_paths(..., reason="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] 시작...")
그래프 내보내기 형식
bv --robot-graph # JSON (기본값)
bv --robot-graph --graph-format=dot # Graphviz DOT
bv --robot-graph --graph-format=mermaid # Mermaid 다이어그램
bv --robot-graph --graph-root=bd-123 --graph-depth=3 # 서브그래프
bv --export-graph report.html # 대화형 HTML
시간 여행
과거 상태와 비교:
bv --as-of HEAD~10 # 10커밋 전
bv --as-of v1.0.0 # 태그 시점
bv --as-of "2024-01-15" # 날짜 기준
bv --robot-diff --diff-since HEAD~30 # 최근 30커밋의 변경 사항
일반적인 문제
| 문제 | 해결 방법 |
|---|---|
| TUI가 에이전트 차단 | --robot-* 플래그만 사용 |
| 오래된 메트릭 | status 필드 확인, 결과는 data_hash로 캐시됨 |
| 누락된 사이클 | --robot-insights 실행, .cycles 확인 |
| 잘못된 권장 사항 | --recipe actionable을 사용하여 준비된 작업으로 필터링 |
성능 참고 사항
- 1단계 메트릭 (차수, 위상, 밀도): 즉시
- 2단계 메트릭 (PageRank, 매개 중심성 등): 500ms 타임아웃
- 결과는
data_hash로 캐시됨 - 속도가 중요할 때는
--robot-insights보다--robot-plan을 선호