Beadsbd blocked命令详解依赖阻塞检测与阻塞队列管理实战【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 的bd blocked命令用于列出当前仓库中所有处于被阻塞状态的工作项issue是 Beads 依赖图驱动的工程流中排查卡住的工作的核心入口。本文以 docs/cli-reference/blocked.md 为骨架结合命令实现cmd/bd/ready.go、存储层查询逻辑internal/storage/issueops/blocked.go与多套测试用例完整讲解bd blocked的语义、输出格式、过滤参数、底层判定原理与常见实战用法。一、命令总览bd blocked是 Beads CLI 中一个只读的查询命令用于列出当前被阻塞的 issuebd blocked [flags]它与其他只读查询命令bd ready、bd list、bd search、bd show等一起构成 Beads 的依赖就绪度检查工具族。与bd ready回答哪些工作可以开工互补bd blocked回答哪些工作正在被别的 issue 卡住。该命令的Short描述为 Show blocked issuescmd/bd/ready.go。命令入口挂载在根命令下位于 cmd/bd/ready.go而帮助文档正是由bd help --doc blocked自动生成见原文档头部注释因此本文档与命令行为保持同步。核心能力速览能力说明依据检测被阻塞 issue找出所有is_blocked 1且未关闭、未钉住的工作项internal/storage/issueops/blocked.go显示阻塞者每个结果携带BlockedByCount与BlockedBy阻塞它的 issue ID 列表internal/types/types.go继承阻塞被阻塞父项的子孙也会被计入父项为 epic 时internal/storage/issueops/blocked.go两种输出模式人类可读文本与--json结构化输出cmd/bd/ready.go四种过滤维度--parent、--label、--label-any、--exclude-labelcmd/bd/ready.go二、阻塞的判定语义什么算被阻塞bd blocked不是简单读取 issue 的status字段而是基于**依赖图中的阻塞边blocking edges**推导。这是 Beads 与普通任务清单的关键区别阻塞状态是依赖关系的派生结果而不是用户手动填写的状态值。1. 阻塞边的三种类型在 internal/types/types.go 中定义了三种会触发阻塞的依赖类型依赖类型常量语义blocksDepBlocksA 阻塞 BB 只有等 A 完成才能开工conditional-blocksDepConditionalBlocksB 仅在 A 失败时运行条件性阻塞waits-forDepWaitsFor扇出门控等待动态子项完成在查询时loadBlockingDepsForIssueIDsInTx 会同时扫描dependencies与wisp_dependencies两张边表过滤出type blocks OR type waits-for OR type conditional-blocks的边internal/storage/issueops/blocked.go。2. 只有活跃的阻塞者才算数找到阻塞边之后查询还会检查阻塞者被依赖方的当前状态如果阻塞者已关闭closed或被钉住pinned则它不再阻塞任何工作该边会被跳过internal/storage/issueops/blocked.go。这一点在测试TestGetBlockedIssues_ExcludesClosedBlockersinternal/storage/dolt/queries_test.go中有明确验证关闭阻塞者后依赖者应被解除阻塞。3. 继承阻塞transitive blocking如果一个 issue 没有直接的阻塞边却带有is_blocked 1标记说明它的阻塞是从父项继承的——父项epic被阻塞则其子工作项也视为被阻塞。此时查询会向上寻找父级 ID 填入BlockedBy并在BlockedByCount中计 1internal/storage/issueops/blocked.go。这一语义在 conformance 测试中被严格钉死requireBlockedWithNoDirectBlockerEdges断言flag 为 1 但无直接阻塞边的组合正是继承阻塞的唯一合法形态backend/conformance/blocked_state.go防止实现退化成只测直接阻塞的错误形态。4. 底层标记is_blocked列is_blocked是一个**派生且持久化derived AND persisted**的列它由依赖图变化时的事务内重算recompute写入数据库。conformance 测试用裸 SQL 读取该列SELECT CAST(COALESCE(is_blocked, 0) AS SIGNED) ...而非调用角色接口正是为了验证后端确实持久化了该标记而非仅在内存中计算backend/conformance/blocked_state.go。三、输出格式详解1. 人类可读文本输出无 issue 被阻塞时✨ No blocked issues存在被阻塞 issue 时 Blocked issues (N): [priority] id: Title Blocked by 2 open dependencies: [bd-1 bd-2] [priority] id: Title Blocked by 1 open dependencies: [bd-3]输出逻辑位于 cmd/bd/ready.go直连模式与 cmd/bd/ready_proxied_server.go代理服务模式第一行显示计数每个 issue 一行包含按优先级渲染的标识、ID 与标题缩进行显示Blocked by N open dependencies及其 ID 列表。2. JSON 结构化输出bd blocked --json输出一个BlockedIssue对象数组结构定义于 internal/types/types.go[ { id: test-abc123, title: Second issue, status: open, priority: 0, blocked_by_count: 1, blocked_by: [test-def456] } ]BlockedIssue内嵌了完整的Issue结构因此 JSON 中除阻塞信息外还包含该 issue 的全部常规字段。空结果时返回空数组[]cmd/bd/ready.go。--json的开关由全局配置config.yaml、环境变量或--json标志统一控制cmd/bd/ready.go。四、过滤参数原文档仅列出了--parent一个标志但从源码看bd blocked实际支持四个过滤参数cmd/bd/ready.go参数别名语义示例--parent string—只显示该 bead/epic 的后代中的被阻塞项递归bd blocked --parent ep-42--label strings-l按标签过滤AND必须同时拥有全部标签bd blocked -l theme:alpha -l urgent--label-any strings—按标签过滤OR至少拥有其中一个标签bd blocked --label-any theme:alpha,theme:beta--exclude-label strings—排除带有任一这些标签的 issuebd blocked --exclude-label theme:alpha这些参数统一由 blockedFilterFromFlags 组装成types.WorkFilter并同时服务于直连与代理服务两条执行路径避免两条路径因新增过滤参数而行为漂移cmd/bd/ready.go。1.--parent聚焦某个 epic/bead 的后代--parent过滤是递归的它收集指定 issue 的全部子孙节点只有落在该集合内的被阻塞项才会显示internal/storage/issueops/blocked.go。注意其判定还包含一个便捷规则ID 以parentID.前缀开头的 issue 也会被视作后代internal/storage/issueops/blocked.go。该能力对大规模仓库尤为有用——当一个 epic 被阻塞时你可以立刻定位到该 epic 之下所有被连带卡住的工作项。2. 标签过滤的精确语义重要标签过滤有一个容易踩坑的细节它只作用于被阻塞的 issue 本身绝不作用于阻塞者。也就是说bd blocked --label X返回的是带有标签 X 且被阻塞的 issue而不是被带有标签 X 的 issue 所阻塞的项。即使阻塞者身上带着theme:blocker-only标签用它过滤也不会返回任何被它阻塞的 issuecmd/bd/blocked_embedded_test.go 明确钉死了这一行为。此外标签过滤实现了归一化normalization前导空格会被修剪--label theme:alpha与--label theme:alpha等价。若不修剪pflag 的 CSV 分割会在--label a, b这种日常写法中留下前导空格导致精确匹配静默漏报cmd/bd/ready.go空元素不会摧毁过滤器--label theme:alpha,,urgent中的空元素会被安全忽略而不是生成label 这样的永假子句cmd/bd/blocked_embedded_test.go。这些细节由测试 TestEmbeddedBlockedLabelFilters 全面覆盖包括 AND 语义、OR 语义、排除语义与组合使用。五、命令执行链路与两种后端路径bd blocked的执行入口会依据当前是否启用代理服务器proxied server分派到两条路径cmd/bd/ready.go1. 直连embedded模式blockedCmd.RunE └─ blockedFilterFromFlags(cmd) // 组装 WorkFilter └─ store.GetBlockedIssues(ctx, filter) // 存储层 └─ withReadTx // 只读事务 └─ issueops.GetBlockedIssuesInTx // 核心查询GetBlockedIssues在 internal/storage/dolt/queries.go 中实现通过只读事务调用核心查询函数。2. 代理服务proxied模式blockedCmd.RunE └─ usesProxiedServer() true └─ runBlockedProxiedServer(cmd, ctx) // cmd/bd/ready_proxied_server.go:72 └─ uowProvider.NewUOW(ctx) └─ uw.IssueUseCase().GetBlockedIssues(ctx, filter)代理路径复用同一个blockedFilterFromFlags保证两种模式下过滤行为完全一致cmd/bd/ready_proxied_server.go。代理路径走 UnitOfWork 的 IssueUseCase 实现internal/storage/domain/issue.go直连路径走 Dolt 存储实现internal/storage/dolt/queries.go两者共享issueops.GetBlockedIssuesInTx核心逻辑。3. 核心查询的完整流水线GetBlockedIssuesInTx 的执行分为六步扫描被阻塞 ID分别在 issues 与 wisps 两张表中查找is_blocked 1 AND status closed AND status pinned的记录并在源头应用标签过滤issues 与 wisps 的标签存放在不同表中源头过滤可省去后续工作internal/storage/issueops/blocked.go加载阻塞边查出这些 ID 的全部阻塞型出边blocks/waits-for/conditional-blocks剔除失效阻塞者阻塞者已关闭或钉住的边被丢弃补齐继承阻塞没有直接阻塞边却带标记的 issue向上查找父级填入原因批量水合一次性批量拉取所有涉及的 issue 完整记录GetIssuesByIDsInTx避免逐条 N1 查询应用--parent过滤并排序最终按优先级升序、创建时间倒序排序internal/storage/issueops/blocked.go。其中第 2 步查询对 wisp 边表做了容错处理若表不存在未启用 wisp 功能直接跳过而不报错internal/storage/issueops/blocked.go。六、实战用法1. 快速查看当前有哪些工作被卡住bd blocked这是最常用的形式进入 Beads 仓库目录后直接执行即可看到所有被阻塞的工作项及其阻塞者。2. 为自动化脚本/Agent 提供结构化输入bd blocked --jsonBeads 的编程 Agent 可通过--json输出获取被阻塞项的结构化信息ID、标题、阻塞者列表进而做出决策例如在bd ready拿不到可开工项时检查bd blocked的阻塞者是否已被其他 Agent 处理。3. 聚焦某个 epic 的后代bd blocked --parent ep-42只显示ep-42这个 epic 下所有被递归阻塞的工作项适合 epic 级进度评审。4. 结合标签定位特定主题的阻塞# 显示同时带 theme:alpha 和 urgent 两个标签的被阻塞项AND bd blocked --label theme:alpha --label urgent # 显示带 theme:alpha 或 theme:beta 任一标签的被阻塞项OR bd blocked --label-any theme:alpha,theme:beta # 排除带 theme:alpha 标签的被阻塞项 bd blocked --exclude-label theme:alpha5. 用依赖创建复现一个被阻塞场景bd blocked的输出依赖依赖图。要快速验证命令行为可以参照 cmd/bd/testdata/blocked.txt 中的端到端脚本bd init --prefix test bd create First issue # 创建阻塞者 bd create Second issue --deps $(提取第一个issue的ID) # 创建依赖者 bd blocked # 此时 Second issue 应出现在输出中也可以使用bd dep add显式添加阻塞边对应 cmd/bd/blocked_embedded_test.go 的测试场景bd create Blocker --type task bd create I am blocked --type task bd dep add blocked-ID blocker-ID # blocked 依赖 blocker即 blocker 阻塞 blocked bd blocked # 输出应包含 I am blocked七、行为保证与测试验证bd blocked的行为由多层测试保护1. CLI 层测试cmd/bd/testdata/blocked.txttxtar 风格端到端脚本验证创建依赖后bd blocked能看到被阻塞项cmd/bd/blocked_embedded_test.go嵌入式模式测试覆盖空库、有阻塞项、--json输出合法性、8 并发读取、标签过滤全套语义cmd/bd/blocked_proxied_integration_test.go代理服务模式下的等价测试含--deps depends-on:语法创建阻塞关系cmd/bd/protocol/blocked_test.go 与 cmd/bd/protocol/blocked_status_test.go协议层验证blocked --json与list --status blocked的一致性。2. 存储层测试internal/storage/dolt/queries_test.go 中的TestGetBlockedIssues_*系列覆盖空库、带阻塞者返回、关闭阻塞者后解除、多阻塞者、被阻塞父项的子项也被计入继承阻塞。3. Conformance 契约测试backend/conformance/blocked_state.go 是阻塞状态的一致性命题测试套件issueops.BlockedStateInvariant它确立了几条关键契约fixture 永不直接写is_blocked所有状态必须通过角色动词创建、依赖编辑、关闭、认领等挣得该标记第 67-69 行每个用例必须发生翻转flipblockedStateFlip会拒绝动词执行前值已等于断言值的用例防止测试空转backend/conformance/blocked_state.go重算不得扰动updated_atis_blocked是派生状态翻转它不应修改用户编辑时间戳backend/conformance/blocked_state.go每种用例都带对照组控制组必须在动词执行后保持不动证明重算没有扩散到影响集之外backend/conformance/blocked_state.go。这些契约同时也约束着bd blocked的数据来源只有is_blocked列被正确持久化、随依赖图变化正确翻转查询命令才能给出可靠答案。八、与相关命令的配合bd blocked通常不是孤立使用的它处于 Beads 就绪度工具族中bd ready列出可以开工的 issue与bd blocked互补。从统计口径看ReadyIssues OpenIssues - BlockedIssues下限截断为 0见 backend/conformance/audit_search-counts-stats.gobd dep管理依赖边bd dep add/bd dep remove是产生/解除阻塞状态的源头操作bd list --status blocked按显式状态值过滤的列表命令与bd blocked按依赖推导是两个不同维度——前者看状态字段后者看阻塞边推导结果cmd/bd/protocol/blocked_status_test.gobd stats仓库级统计中的BlockedIssues计数正是由is_blocked 1推导见 backend/conformance/audit_search-counts-stats.go。九、注意事项与边界只读命令bd blocked不产生任何写入可在并发环境中安全重复调用cmd/bd/blocked_embedded_test.go 用 8 个并发 worker 验证了这一点状态过滤的隐含规则closed与pinned状态的项即使带有is_blocked 1标记也不会出现在结果中internal/storage/issueops/blocked.go相应地阻塞者处于closed/pinned时也不再算作阻塞internal/storage/issueops/blocked.go标签过滤只作用于被阻塞项本身过滤条件永远不会作用到阻塞者身上这与--parent递归后代过滤的语义不同使用时需注意区分wisp 表的可选性若仓库未启用 wisp 功能相关边表不存在时查询会静默跳过不影响正常 issue 的阻塞检测internal/storage/issueops/blocked.go。总结bd blocked是 Beads 依赖驱动工作流中不可或缺的阻塞雷达它以is_blocked派生列为数据源结合blocks/waits-for/conditional-blocks三种阻塞边与继承阻塞语义准确回答谁被谁卡住了。通过--parent、--label、--label-any、--exclude-label四个过滤参数它可以灵活收敛到特定 epic 或主题通过--json输出它可以无缝接入 Agent 与自动化脚本。理解其底层判定逻辑活跃阻塞者、继承阻塞、派生标记的持久化能帮助你更准确地在 Beads 仓库中诊断依赖阻塞并配合bd dep、bd ready等命令高效推进工作流。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考