Beads 依赖图可视化实战：深入解析 `bd graph` 与 `bd graph check`

Beads 依赖图可视化实战：深入解析bd graph与bd graph check

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

bd graph是 Beads 中用于可视化 Issue 依赖关系的核心命令，它以分层 DAG（有向无环图）的形式呈现"谁先做、谁依赖谁、谁可以并行"，帮助开发者和 AI Agent 快速读懂任务依赖拓扑。本文以 docs/cli-reference/graph.md 为主线，结合 cmd/bd/graph.go、cmd/bd/graph_visual.go、cmd/bd/graph_export.go 等源码实现，从命令用法、六种输出格式到分层布局与环检测的底层原理，带你完整掌握 Beads 依赖图的查看、导出与体检能力。

一、bd graph是什么：一张图看清任务依赖

Beads 用 Issue 承载任务，而 Issue 之间存在多种依赖关系：blocks（阻塞）、parent-child（父子）、relates-to（关联）等（定义见 internal/types/types.go）。bd graph把这种关系网络渲染成可读的图，其作用范围分为三种：

• 针对普通 Issue：展示该 Issue 及其直接依赖；
• 针对 Epic：展示其所有子任务（children）及这些子任务各自的依赖；
• 配合--all：展示全部未关闭（open）Issue，并按连通分量分组。

从源码看，该命令属于deps命令组，注册于 cmd/bd/graph.go，同时支持部分 ID 解析（utils.ResolvePartialID），因此你既可以传完整 ID 也可以传前缀。

二、命令语法与 Flags 速查

bd graph [issue-id] [flags]

参数的合法性检查（见 cmd/bd/graph.go）：

• --all与issue-id不能同时出现（报错：cannot specify issue ID with --all flag）；
• 不使用--all时必须提供issue-id（报错：issue ID required，并提示可改用--all）。

三、分层语义：Layer 即执行顺序

bd graph输出的核心是分层（Layer）概念，它直接反映执行顺序：

• Layer 0（最左列）：没有任何依赖的 Issue，标注(ready)，可以立即开始；
• 更高层：依赖更低层，即"更高层必须等低层完成"；
• 同一层的节点：互不依赖，可以并行执行。

这一语义正是图布局算法刻意设计的产物。computeLayout在 cmd/bd/graph.go 中实现：先只取blocks类型的依赖构建dependsOn映射，再通过"最长路径"迭代为每个节点赋值层号——无依赖节点为 Layer 0，所有依赖都已分层的节点取"最大依赖层 + 1"；对无法分层的节点（环或孤立节点）兜底为 Layer 0。

值得注意的一个细节是子任务上浮规则（源码注释记为 GH#1748）：父 Epic 若被阻塞在高 Layer，其子任务不会孤零零地漂在 Layer 0，而是被提升到与父任务同层（仅当子任务自身没有更高的阻塞依赖时才提升）。这一行为在 cmd/bd/graph_test.go 的TestComputeLayout中有明确测试佐证。

四、六种显示格式：从终端到浏览器

1. 默认格式：终端原生 DAG

bd graph issue-id

默认输出是"列 = Layer、行 = 节点"的纵向分列 DAG：每一层是一列节点盒子，列与列之间的 gutter 区域用盒线字符（─、│、╮、╰、┼、▶）绘制连线。渲染逻辑在 cmd/bd/graph_visual.go 中：每个节点盒 4 行高（上边框 / 状态图标+标题 / ID+优先级 / 下边框），dagMergeRune负责在交叉、T 形交汇处合并字符。所有节点盒子宽度统一（至少 18 字符），跨层边会在中间 gutter 做"贯穿"处理，保证长链依赖也能画得整齐。

2.--box：ASCII 盒分层视图

bd graph --box issue-id

每个 Issue 渲染为一个完整的 ASCII 盒（┌─┐结构），额外显示blocks:N（该 Issue 阻塞了几个任务）与needs:N（该 Issue 被几个任务阻塞）两个计数，帮助你一眼看出"瓶颈节点"。实现见 cmd/bd/graph.go，计数由computeDependencyCounts计算（cmd/bd/graph.go），它刻意排除了 parent-child 关系和根节点自身，以降低认知噪声。

3.--compact：单行树形

bd graph --compact issue-id

每行一个 Issue，格式为状态图标 ID 优先级 标题，用├──/└──/│树形连接符组织父子层级，并按优先级 + ID 排序（cmd/bd/graph.go）。适合终端里快速扫读、以及把结果直接粘贴给 LLM 分析。

4.--dot：Graphviz 管道导出

bd graph --dot issue-id | dot -Tsvg > graph.svg bd graph --dot issue-id | dot -Tpng > graph.png

输出标准 DOT 语法：rankdir=LR（从左到右），节点按 Layer 用cluster_layer_N+rank=same对齐，不同状态有不同填充色（open 浅蓝、in_progress 浅黄、blocked 浅红、closed 浅绿等），blocks边为实线、parent-child边为灰色虚线（cmd/bd/graph_export.go）。渲染前需确保已安装 Graphviz 的dot命令。

5.--html：D3.js 交互式视图

bd graph --html issue-id > graph.html bd graph --all --html > all.html

生成自包含的单个 HTML 文件，内嵌 D3.js v7 力导向图：节点按状态着色，支持拖拽、滚轮缩放、Fit View / Reset View / Toggle Labels 三个控制按钮，悬停节点弹出含 ID、状态、优先级、类型、Assignee、Layer 的 Tooltip（模板见 cmd/bd/graph_export.go）。数据以 JSON 注入（节点含id/title/status/priority/type/layer/assignee），因此文件脱离网络也能打开基本页面（D3 库默认走 CDN，离线浏览时需自行替换为本地 d3.v7.min.js）。--all --html时多个连通分量会被合并成一份 HTML 文档输出（mergeSubgraphsForHTML，cmd/bd/graph.go）。

6.--open：过滤后的紧凑层视图

bd graph --open issue-id bd graph --all --open

只保留 open / in_progress / blocked 三类"可执行"状态（isOpenStatus，cmd/bd/graph.go），自动切换为紧凑分层格式，专为 LLM 阅读优化。过滤时有一个重要细节：若 open 节点 A 通过一个已关闭节点 B 间接阻塞 open 节点 C，filterSubgraphOpen会计算传递闭包并合成一条 A→C 的阻塞边，保证过滤后仍然保留间接阻塞语义（示例：A(open) 阻塞 B(closed) 阻塞 C(open) ⇒ 过滤图中出现合成边 A→C）。该行为在 cmd/bd/graph_test.go 的TestFilterSubgraphOpen中有完整用例覆盖，包括"直接边 + 传递路径同时存在时只保留一条边、不产生重复"（cmd/bd/graph_test.go）。

附：JSON 输出

配合全局--json时，单图输出root / issues / layout结构，--all输出子图数组，bd graph check输出clean / cycles / summary结构——适合被脚本与自动化流水线消费。

五、状态图标与配色语义

图中所有节点统一使用以下状态图标（终端与导出格式共用同一套语义，见 cmd/bd/graph_export.go 的statusPlainIcon）：

内置状态全集定义于 internal/types/types.go，除上述外还有pinned（常驻珠）与hooked（被 worker 认领）等。渲染策略遵循"仅可执行状态上色、已关闭节点淡化"的原则（如closed整行灰显），具体样式由internal/ui包统一提供，保证跨命令的视觉一致性。

六、底层原理：子图如何被加载

单 Issue 子图：双向 BFS

loadGraphSubgraph（cmd/bd/graph.go）以目标 Issue 为根，同时向两个方向做 BFS：

• GetDependents：找出"依赖当前节点"的 Issue（反向边）；
• GetDependencies：找出"当前节点依赖的" Issue（正向边）；

这样无论从链条的哪一端发起查询，都能拿到完整连通子图。随后加载子图内所有GetDependencyRecords，但只保留两端都在子图内的依赖。此外源码注释标记了外部依赖处理（bd-k0pfm）：对形如external:前缀的依赖 ID，会通过resolveAndGetIssueWithRouting跨库路由解析目标 Issue 并重写依赖 ID，保证跨数据库的依赖也能画进图里。

--all：连通分量划分

loadAllGraphSubgraphs（cmd/bd/graph.go）先按 open / in_progress / blocked 三种状态分别SearchIssues，汇总后通过 BFS 求连通分量（cmd/bd/graph.go），每个连通分量生成一个子图。分量按"尺寸降序 → 首节点优先级升序"排序；每个分量的根节点选择遵循Epic 优先 → 优先级最高 → 最早创建的规则。

行数上限防护

源码注释（be-x42v）说明了--max-rows/BEADS_MAX_ROWS在两种模式下的差异（cmd/bd/graph.go）：

• 单图模式（无--all）：BFS 遍历完整个连通分量后，对最终节点数做事后检查，超限即报ErrTooManyRows（退出码 2）；
• --all模式：对 open / in_progress / blocked 三个状态各自独立检查上限，因此在任一状态触限前，总量最多可加载到 3 倍上限。

这与bd dep tree的行为一致（都是"先走完整棵图再检查"），属于防御性行数护栏。

七、bd graph check：依赖图体检

bd graph check [flags]

对依赖图执行完整性检查，检测环（cycle）、孤儿节点（orphan）及其他完整性问题：

• 图干净：退出码0，输出✓ Graph integrity check passed与✓ No dependency cycles；
• 发现问题：退出码1，输出✗ Graph integrity issues found与⚠ Cycles (N)，随后逐条列出环路径（如A → B → A）。

从源码看（cmd/bd/graph.go），它调用存储层的store.DetectCycles获取所有环，renderGraphCheck负责格式化与退出码判定。底层实现可追溯到 internal/storage/dolt/cycle_detector.go 与 internal/storage/embeddeddolt/dependencies.go：在单个读事务快照中完成图读取与环报告（DetectCycleReportInTx），保证一致性。

八、实战组合与使用建议

需要说明的是，图内只呈现blocks阻塞边与parent-child父子边两类（relates-to等弱关联不会画入主图，仅保留在数据层）。因此 Layer 语义严格对应"阻塞链"，阅读时请勿把父子关系误读为执行顺序约束——父子边只影响"子任务上浮到父层"的排版，不参与分层计算。

九、延伸阅读

• 命令文档： docs/cli-reference/graph.md（本文内容由其自动生成，来源为bd help --doc graph）
• 命令主实现： cmd/bd/graph.go（子图加载、布局计算、--open过滤、graph check）
• 终端 DAG 渲染： cmd/bd/graph_visual.go
• DOT / HTML 导出： cmd/bd/graph_export.go
• 单元测试佐证： cmd/bd/graph_test.go（布局分层、传递闭包、节点盒渲染、标题截断等）
• 状态与依赖类型定义： internal/types/types.go
• 环检测底层实现： internal/storage/dolt/cycle_detector.go、internal/storage/embeddeddolt/dependencies.go

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads