Beads 依赖图可视化实战深入解析bd graph与bd graph check【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd 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展示全部未关闭openIssue并按连通分量分组。从源码看该命令属于deps命令组注册于 cmd/bd/graph.go同时支持部分 ID 解析utils.ResolvePartialID因此你既可以传完整 ID 也可以传前缀。二、命令语法与 Flags 速查bd graph [issue-id] [flags]Flag说明默认--all显示所有 open 状态 Issue 的依赖图按连通分量分组关闭--box使用 ASCII 盒子展示分层信息更详细关闭--compact树形格式每个 Issue 一行更易扫读关闭--dot输出 Graphviz DOT 格式可管道给dot渲染成 SVG/PNG关闭--html输出自包含的交互式 HTML内含 D3.js 可视化重定向到文件后可在浏览器打开关闭--open仅展示 open/可执行 Issue强制使用紧凑分层格式LLM 友好关闭参数的合法性检查见 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. 默认格式终端原生 DAGbd graph issue-id默认输出是列 Layer、行 节点的纵向分列 DAG每一层是一列节点盒子列与列之间的 gutter 区域用盒线字符─、│、╮、╰、┼、▶绘制连线。渲染逻辑在 cmd/bd/graph_visual.go 中每个节点盒 4 行高上边框 / 状态图标标题 / ID优先级 / 下边框dagMergeRune负责在交叉、T 形交汇处合并字符。所有节点盒子宽度统一至少 18 字符跨层边会在中间 gutter 做贯穿处理保证长链依赖也能画得整齐。2.--boxASCII 盒分层视图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.--dotGraphviz 管道导出bd graph --dot issue-id | dot -Tsvg graph.svg bd graph --dot issue-id | dot -Tpng graph.png输出标准 DOT 语法rankdirLR从左到右节点按 Layer 用cluster_layer_Nranksame对齐不同状态有不同填充色open 浅蓝、in_progress 浅黄、blocked 浅红、closed 浅绿等blocks边为实线、parent-child边为灰色虚线cmd/bd/graph_export.go。渲染前需确保已安装 Graphviz 的dot命令。5.--htmlD3.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 文档输出mergeSubgraphsForHTMLcmd/bd/graph.go。6.--open过滤后的紧凑层视图bd graph --open issue-id bd graph --all --open只保留 open / in_progress / blocked 三类可执行状态isOpenStatuscmd/bd/graph.go自动切换为紧凑分层格式专为 LLM 阅读优化。过滤时有一个重要细节若 open 节点 A 通过一个已关闭节点 B 间接阻塞 open 节点 CfilterSubgraphOpen会计算传递闭包并合成一条 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图标状态说明○open打开、可认领◐in_progress进行中●blocked被阻塞✓closed已关闭❄deferred已延期冻结内置状态全集定义于 internal/types/types.go除上述外还有pinned常驻珠与hooked被 worker 认领等。渲染策略遵循仅可执行状态上色、已关闭节点淡化的原则如closed整行灰显具体样式由internal/ui包统一提供保证跨命令的视觉一致性。六、底层原理子图如何被加载单 Issue 子图双向 BFSloadGraphSubgraphcmd/bd/graph.go以目标 Issue 为根同时向两个方向做 BFSGetDependents找出依赖当前节点的 Issue反向边GetDependencies找出当前节点依赖的 Issue正向边这样无论从链条的哪一端发起查询都能拿到完整连通子图。随后加载子图内所有GetDependencyRecords但只保留两端都在子图内的依赖。此外源码注释标记了外部依赖处理bd-k0pfm对形如external:前缀的依赖 ID会通过resolveAndGetIssueWithRouting跨库路由解析目标 Issue 并重写依赖 ID保证跨数据库的依赖也能画进图里。--all连通分量划分loadAllGraphSubgraphscmd/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单图模式无--allBFS 遍历完整个连通分量后对最终节点数做事后检查超限即报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保证一致性。八、实战组合与使用建议场景推荐命令快速查看某个 Epic 的完整任务拓扑bd graph epic-123找出全仓马上能做的任务bd graph --all关注 Layer 0 (ready) 列定位阻塞链与瓶颈bd graph --box issue-id看blocks:/needs:计数汇报/文档配图bd graph --dot issue-id | dot -Tsvg graph.svg团队共享、浏览器交互浏览bd graph --all --html all.html喂给 LLM 做任务拆解分析bd graph --open --compact issue-idCI 或提交前自检依赖健康bd graph check非零退出码即拦截需要说明的是图内只呈现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.goDOT / 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考