beads-viewer

Beads Viewer

概述

Beads Viewer（BV）是一个面向 Beads 项目的图感知分诊引擎（ .beads/beads.jsonl）。它会计算 9 项图指标、生成执行计划并提供确定性建议。

适用场景： 分诊 Beads 任务、分析依赖图、查找瓶颈、检测循环依赖、规划并行执行轨道、生成冲刺燃尽数据、比较项目历史状态。

不适用场景： 直接解析原始 beads.jsonl（BV 会预先计算图指标）、简单的 Bead 增删改查操作（请改用 bd CLI）、不包含 .beads/beads.jsonl 的项目。

功能	原始 beads.jsonl	BV 机器人模式
查询	“列出所有问题”	“列出阻碍发布的前 5 个瓶颈”
上下文成本	高（随问题数量线性增长）	低（固定的摘要结构）
图逻辑	Agent 必须自行计算	预先计算（PageRank、中介中心性、循环）
安全性	Agent 可能会漏掉循环	明确标记循环

快速参考

命令	用途	关键点
bv --robot-triage	完整分诊并提供建议	从这里开始；包含 quick_wins 和 blockers
bv --robot-next	推荐单个首选项并附带认领命令	上下文成本最低
bv --robot-plan	并行执行轨道	比 --robot-insights 更快
bv --robot-insights	完整图指标（全部 9 项）	检查 status 字段；开销较大
bv --robot-priority	检测优先级不一致	标记优先级设置不当的项目
bv --robot-alerts	长期未处理的问题、阻塞级联	主动健康检查
bv --robot-suggest	卫生检查：重复项、缺失的依赖	包含打破循环的建议
bv --robot-graph	导出依赖图	JSON、DOT 或 Mermaid 格式
bv --recipe <name> --robot-<cmd>	在运行任何机器人命令前进行预筛选	配方：actionable、high-impact、bottlenecks
bv --robot-triage --label <name>	限定为某个标签的子图	减少噪声，便于聚焦分析

重要： 切勿在 Agent 会话中直接运行 bv。它会启动交互式 TUI，阻塞会话。请始终使用 --robot-* 标志。

9 项图指标

指标	衡量内容	关键洞见
PageRank	递归依赖重要性	基础性阻塞项
Betweenness	最短路径流量	瓶颈与桥接节点
HITS	枢纽／权威双重性	史诗级任务与实用工具
Critical Path	最长依赖链	松弛时间为零的关键节点
Eigenvector	通过邻居衡量影响力	战略性依赖
Degree	直接连接数量	直接阻塞项／被阻塞项
Density	边与节点的比率	项目耦合健康度
Cycles	循环依赖	结构性错误（必须修复！）
Topo Sort	有效执行顺序	工作队列基础

指标分两个阶段计算：阶段 1（degree、topo sort、density）即时完成；阶段 2（PageRank、betweenness、HITS、eigenvector、cycles）超时设为 500ms。务必检查输出中的 status 字段。

内置方案

方案	用途
default	按优先级排序的所有未关闭问题
actionable	可立即着手处理（无阻塞项）
high-impact	PageRank 分数最高的项目
blocked	正等待依赖项的项目
stale	已打开但超过 30 天未触及的项目
triage	按计算出的分诊分数排序
quick-wins	无阻塞项的简单 P2/P3 项目
bottlenecks	Betweenness 较高的节点

机器人输出结构

所有机器人 JSON 输出都包含以下标准字段：

字段	用途
data_hash	beads.jsonl 的指纹，用于验证一致性
status	各指标的状态：computed、approx、timeout 或 skipped
as_of / as_of_commit	使用 --as-of 进行时间点查询时出现

各命令的关键输出部分：

• --robot-triage：quick_ref、recommendations、quick_wins、blockers_to_clear、project_health、commands
• --robot-insights：bottlenecks、keystones、influencers、hubs、authorities、cycles、clusterDensity
• --robot-plan：plan.tracks（并行工作流）、plan.summary.highest_impact

常见错误

错误	正确做法
在 Agent 会话中直接运行 bv	始终使用 --robot-* 标志；直接运行 bv 会启动交互式 TUI，导致 Agent 阻塞
忽略机器人输出中的 status 字段	始终检查各项指标的状态；大型图可能因 500ms 超时而出现 approx 或 skipped 指标
只需要下一个任务时使用 --robot-insights	使用 --robot-next 获取单个优先推荐项，或使用 --robot-triage 获取快速建议；insights 的开销较大
开始实现前不检查循环	运行 bv --robot-insights 并先检查 .cycles；循环依赖属于结构性错误，必须解决
将 stderr 解析为 JSON 数据	只有 stdout 包含 JSON；诊断信息和警告会输出到 stderr
bead 变更后指标过时	检查 data_hash 字段；结果按 beads.jsonl 指纹缓存
当前工作的推荐项不正确	使用 --recipe actionable，仅筛选未阻塞且可立即开始处理的条目

委派

• 分析项目依赖状况和瓶颈：使用 Task Agent 运行 BV 机器人命令并汇总图指标
• 根据分流输出规划冲刺工作：使用 Plan Agent 解读分流建议并制定执行轨道
• 搜索相关 bead 上下文：使用 Explore Agent 调查 bead 描述并查找实现模式

参考资料

• 机器人命令、输出结构和 jq 模式
• 图指标、两阶段分析和指标配方
• Agent 工作流、TUI 视图、集成和时间旅行