BV - Beads Viewer
一個專為 Beads 專案（.beads/beads.jsonl）設計的圖感知分流引擎。計算 9 種圖形指標、產生執行計畫，並提供確定性建議。人類使用 TUI 瀏覽；AI 代理人使用機器人旗標。
為什麼選擇 BV 而非原始 Beads
| 能力 | 原始 beads.jsonl | BV 機器人模式 |
|---|---|---|
| 查詢 | 「列出所有問題」 | 「列出阻擋發佈的前 5 大瓶頸」 |
| 上下文成本 | 高（隨問題數線性成長） | 低（固定摘要結構） |
| 圖形邏輯 | 代理人需自行計算 | 預先計算（PageRank、中介中心性、循環） |
| 安全性 | 代理人可能遺漏循環 | 循環被明確標記 |
請使用 BV 而非直接解析 beads.jsonl。它能確定性地計算圖形指標。
關鍵：代理人的機器人模式
絕對不要直接執行 bv。它會啟動一個互動式 TUI，佔用你的工作階段。
一律使用 --robot-* 旗標：
bv --robot-triage # 超級指令：從這裡開始
bv --robot-next # 最簡模式：僅單一最佳選項
bv --robot-plan # 平行執行軌道
bv --robot-insights # 完整圖形指標
9 種圖形指標
BV 計算以下指標以揭露隱藏的專案動態：
| 指標 | 衡量內容 | 關鍵洞察 |
|---|---|---|
| PageRank | 遞迴的依賴重要性 | 基礎性阻擋者 |
| 中介中心性 | 最短路徑流量 | 瓶頸與橋樑 |
| HITS | 樞紐/權威二元性 | Epics 與工具類任務 |
| 關鍵路徑 | 最長依賴鏈 | 零寬裕的關鍵任務 |
| 特徵向量中心性 | 透過鄰居的影響力 | 策略性依賴 |
| 度中心性 | 直接連線數量 | 直接阻擋者/被阻擋者 |
| 密度 | 邊與節點的比例 | 專案耦合健康度 |
| 循環 | 循環相依 | 結構性錯誤（務必修復！） |
| 拓撲排序 | 有效的執行順序 | 工作佇列基礎 |
兩階段分析
BV 使用非同步計算並設有超時：
- 第一階段（即時）： 度中心性、拓撲排序、密度
- 第二階段（500 毫秒超時）： 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 # Bead 到提交的關聯
bv --robot-diff --diff-since <ref> # 自某參考點以來的變更
其他指令
bv --robot-burndown <sprint> # 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 | Kanban 看板 |
g | 圖形檢視（依賴 DAG） |
E | 樹狀檢視（父子階層） |
i | 洞察儀表板（6 面板指標） |
h | 歷史檢視（bead 到提交關聯） |
a | 可行動計畫（平行軌道） |
f | 流向矩陣（跨標籤依賴） |
] | 關注度檢視（標籤優先級排名） |
與 bd CLI 整合
BV 讀取由 bd CLI 建立的 .beads/beads.jsonl：
bd init # 在專案中初始化 beads
bd create "任務標題" # 建立 bead
bd list # 列出 beads
bd ready # 顯示可行動的 beads
bd claim bd-123 # 認領 bead
bd close bd-123 # 關閉 bead
與代理人郵件整合
使用 bead 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 過濾出準備好的工作 |
效能備註
- 第一階段指標（度中心性、拓撲排序、密度）：即時
- 第二階段指標（PageRank、中介中心性等）：500 毫秒超時
- 結果由
data_hash快取 - 當速度重要時，優先使用
--robot-plan而非--robot-insights