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 | 枢纽/权威二元性 | 史诗任务与实用任务 |
| 关键路径 | 最长依赖链 | 零松弛关键点 |
| 特征向量 | 通过邻居的影响 | 战略依赖 |
| 度 | 直接连接数 | 直接阻塞/被阻塞 |
| 密度 | 边与节点比率 | 项目耦合健康度 |
| 循环 | 循环依赖 | 结构错误（必须修复！） |
| 拓扑排序 | 有效执行顺序 | 工作队列基础 |
两阶段分析
BV 使用带超时的异步计算：
- 阶段 1（即时）： 度、拓扑排序、密度
- 阶段 2（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> # 预计完成时间预测
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（超时）|skipped（跳过）as_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 | 历史视图（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
与 Agent Mail 集成
使用 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 过滤到可执行工作 |
性能说明
- 阶段 1 指标（度、拓扑、密度）：即时
- 阶段 2 指标（PageRank、介数等）：500 毫秒超时
- 结果由
data_hash缓存 - 在速度优先时，优先选择
--robot-plan而非--robot-insights