BV - Beads Viewer
Beadsプロジェクト(.beads/beads.jsonl)向けのグラフ認識型トリアージエンジン。9つのグラフメトリクスを計算し、実行計画を生成、確定的な推奨を行います。人間向けTUIブラウジング、AIエージェント向けロボットフラグを提供。
BVがRaw Beadsより優れている理由
| 機能 | Raw beads.jsonl | BV ロボットモード |
|---|---|---|
| クエリ | 「全Issueを一覧表示」 | 「リリースを阻むボトルネック上位5件を表示」 |
| コンテキストコスト | 高い(Issue数に比例) | 低い(固定長サマリー構造) |
| グラフロジック | エージェントが計算が必要 | 事前計算済み(PageRank、媒介中心性、サイクル) |
| 安全性 | エージェントが見逃す可能性あり | サイクルを明示的にフラグ付け |
beads.jsonlを直接パースする代わりにBVを使用してください。グラフメトリクスを確定的に計算します。
重要: エージェント向けロボットモード
bv を裸で実行しないでください。 インタラクティブなTUIが起動し、セッションをブロックします。
常に --robot-* フラグを使用してください:
bv --robot-triage # メガコマンド:ここから開始
bv --robot-next # 最小限:トップ推奨のみ
bv --robot-plan # 並列実行トラック
bv --robot-insights # 全グラフメトリクス
9つのグラフメトリクス
BVは以下のメトリクスを計算し、プロジェクトの隠れたダイナミクスを可視化します:
| メトリクス | 測定内容 | 主な洞察 |
|---|---|---|
| PageRank | 再帰的な依存関係の重要度 | 基盤となるブロッカー |
| 媒介中心性 | 最短パストラフィック | ボトルネックと橋渡し |
| HITS | ハブ/オーソリティの二重性 | エピック vs ユーティリティ |
| クリティカルパス | 最長依存チェーン | スラックゼロの要(キーストーン) |
| 固有ベクトル中心性 | 近傍を介した影響力 | 戦略的依存関係 |
| 次数 | 直接接続数 | 直接的なブロッカー/ブロック対象 |
| 密度 | エッジ/ノード比 | プロジェクト結合度の健全性 |
| サイクル | 循環依存関係 | 構造的エラー(要修正!) |
| トポロジカルソート | 有効な実行順序 | 作業キューの基盤 |
二相分析
BVはタイムアウト付きの非同期計算を使用します:
- フェーズ1(即時): 次数、トポロジカルソート、密度
- フェーズ2(500msタイムアウト): PageRank、媒介中心性、HITS、固有ベクトル中心性、サイクル
出力の status フィールドを常に確認してください。大規模グラフ(>500ノード)では、一部のメトリクスが approx または skipped になる場合があります。
ロボットコマンドリファレンス
トリアージと計画
bv --robot-triage # 完全なトリアージ:推奨、quick_wins、blockers_to_clear
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 # 停滞Issue、ブロッキングカスケード
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 | 全オープンIssue、優先度順 |
actionable | 作業準備完了(ブロッカーなし) |
high-impact | トップPageRankスコア |
blocked | 依存関係待ち |
stale | 30日以上未着手のオープンIssue |
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 # ビードをクローズ
Agent Mailとの統合
ビード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を優先