Beads 的bd swarm基于 Epic 依赖 DAG 编排编码 Agent 并行工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd swarm是 BeadsbdCLI中用于协调 Epic 并行工作的集群swarm管理命令组。它把一个 Epic 及其子任务、以及子任务之间的依赖关系抽象成一张有向无环图DAG据此创建可被任意协调 Agentcoordinator拾取的 swarm 分子swarm molecule、实时计算集群进度、并校验 Epic 结构是否具备并行执行条件。读完本文你将掌握bd swarm create / list / status / validate四个子命令的完整用法、全部 Flags 与 JSON 输出并从源码层面理解 Ready Front就绪波次、依赖方向检查与环检测的底层实现原理。什么是 SwarmEpic 依赖 DAG 分子从官方文档与源码定义看swarm 是一个由 Epic 及其子任务构成的结构化工作体子任务之间的依赖关系形成一张 DAGdirected acyclic graph。其入口定义位于 cmd/bd/swarm.goA swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work.swarm 并不是一张独立存储的表而是一个**分子molecule**——Beads 中mol_type为swarm的特殊 Issue。在 internal/types/types.go 中可以看到三种分子类型mol_type含义swarm协调多 worker 并行工作的分子patrol周期性运维工作的分子work常规指派工作分子默认swarm 分子通过一条relates-to类型的依赖边指向它编排的 Epic从而建立分子 ↔ Epic的关联Epic 再通过parent-child依赖边挂载全部子任务。整个体系围绕依赖图工作状态由底层 beadsIssue 及其依赖关系实时计算得出而非单独存储因此任何一条 Issue 状态或依赖关系的变化都会立即反映到 swarm 的进度与就绪情况中。通用行为与前提bd swarm [flags]作为命令组其下挂载create、list、status、validate四个子命令注册见 cmd/bd/swarm.go。所有子命令都支持全局--json标志输出机器可读结果部分子命令还有自己的专属 Flags。命令需要已打开的数据库连接no database connection报错Issue ID 支持部分 ID 解析utils.ResolvePartialID即输入前缀即可匹配完整 ID。在 proxied-server代理服务模式下create与list会直接报not supported in proxied-server mode而status与validate可通过代理服务器执行见 swarm_proxied_server.go。bd swarm create创建 swarm 分子create用于为一个 Epic 创建编排并行工作的 swarm 分子。bd swarm create [epic-id] [flags]FlagsFlag类型默认值说明--coordinator stringstring空协调者地址例如my-project/witness指定后该分子可被任何协调 Agent 拾取--forceboolfalse即使已存在 swarm 分子也强制新建典型用法bd swarm create bd-epic-123 # 为 epic 创建 swarm bd swarm create bd-epic-123 --coordinatorobserver/ # 指定协调者 bd swarm create bd-task-456 # 自动包裹单个 issue行为细节输入为 Epic或 molecule时直接以该 Epic 为目标创建分子。输入为普通 Issue非 Epic时自动包裹auto-wrap先创建一个标题形如Swarm Epic: 原标题的 Epic把该 Issue 作为其唯一子任务通过parent-child依赖挂载再为这个新 Epic 创建 swarm 分子。源码路径见 cmd/bd/swarm.go。创建过程包含以下关键步骤解析输入 ID通过utils.ResolvePartialID定位 Issue类型不是 Epic/molecule 则走自动包裹逻辑。查重调用findExistingSwarmcmd/bd/swarm.go遍历 Epic 的所有依赖者找出mol_typeswarm且通过relates-to边指向该 Epic 的既有分子若已存在且未传--force则报错提示Use --force to create another.。结构预检对 Epic 调用analyzeEpicForSwarm做可 swarm 性分析若存在环等结构性错误Swarmablefalse拒绝创建并列出错误清单。创建分子生成一个mol_typeswarm、IssueTypemolecule的新 Issue标题为Swarm: Epic标题Assignee设为 coordinator可空再添加一条指向 Epic 的relates-to依赖边形成分子 → Epic的关联。--json模式下成功输出包含swarm_id、epic_id、coordinator、analysis完整 SwarmAnalysis四个字段已有分子时输出error、existing_id、existing_title。bd swarm list列出全部 swarm 及进度list列出仓库中所有 swarm 分子并附带各自进度信息。bd swarm list [flags]bd swarm list # 列表人类可读输出 bd swarm list --json # 机器可读输出列表项SwarmListItem见 cmd/bd/swarm.go包含id/title分子 ID 与标题epic_id/epic_title通过relates-to依赖追溯到的目标 Epicstatus、coordinator分子状态与协调者来自Assigneetotal_issues、completed_issues、active_issues、progress_percent由getSwarmStatus实时计算实现上list以MolTypeswarm为过滤条件调用SearchIssuescmd/bd/swarm.go随后对每个分子逐条解析relates-to边找到 Epic 并计算进度。人类可读输出形如 Active Swarms (2) gt-swarm-456 Swarm: Release 2.0 Epic: gt-epic-123 (Release 2.0) Progress: 3/8, 2 active (38%) Coordinator: observer/bd swarm status从 beads 实时计算集群状态status展示某个 swarm 的当前状态。它的输入有两种Epic ID展示该 Epic 子任务的状态或swarm 分子 ID沿relates-to边回溯找到 Epic。bd swarm status [epic-or-swarm-id] [flags]bd swarm status gt-epic-123 # 按 epic 查状态 bd swarm status gt-swarm-456 # 经分子回溯 epic bd swarm status gt-epic-123 --json四类状态分组输出将全部子任务按状态分为四组计算逻辑见getSwarmStatuscmd/bd/swarm.go分组判定规则Completed已完成状态为 Closed附closed_at时间Active进行中状态为 in_progress附assigneeReady就绪处于 Open 且所有依赖都已满足无未关闭的前置依赖Blocked阻塞处于 Open 且存在未关闭的前置依赖附blocked_by列表关键设计状态是计算出来的不是存储出来的。正如文档所述 The status is COMPUTED from beads, not stored separately. If beads changes, status changes.——只要任一 Issue 关闭或依赖解除下次执行status就会得到新结果。进度百分比为completed / total * 100--json输出完整的SwarmStatus含epic_id、epic_title、四组明细、progress_percent、各计数。人类可读输出还贴心地在 Ready 为空时汇总正在等待哪些前置任务(none - waiting for ...)。bd swarm validate校验 Epic 是否适合并行执行validate对 Epic 的结构做静态分析判断其是否满足 swarm 执行条件。bd swarm validate [epic-id] [flags]bd swarm validate gt-epic-123 # 校验 epic 结构 bd swarm validate gt-epic-123 --verbose # 输出详细 issue 图FlagFlag类型默认值说明--verboseboolfalse在输出中附上详细 issue 依赖图issues字段五类结构检查根据文档与detectStructuralIssues实现cmd/bd/swarm.go校验覆盖依赖方向检查依赖应基于需求requirement而非时间先后temporal。实现采用标题启发式——若标题含foundation/setup/base/core的基础性任务没有后继者或含integration/final/test的收尾型任务没有前置依赖则给出依赖方向可能反转的警告。孤儿问题roots with no dependents找出没有前置依赖的根节点多个根是正常的它们构成并行起点。缺失依赖leaves that should depend on something找出没有后继的叶子节点多个叶子可能意味着任务间缺少连接。环检测cycles通过三色 DFS 检测依赖环一旦发现即在Errors中记录Dependency cycle detected involving: ...并置Swarmablefalse。断连子图disconnected subgraphs从所有根节点出发 DFS 遍历无法到达的节点判为断连给出警告。此外若子任务依赖了 Epic 之外的 Issue 或external:外部引用也会产生警告。报告输出validate报告以下指标SwarmAnalysis见 cmd/bd/swarm.goready_fronts就绪波次可并行的任务浪潮每波含wave编号、issues、titlesestimated_sessions预估 worker 会话数≈ 剩余未关闭任务数max_parallelism最大并行度各波次任务数的最大值warnings/errors结构问题清单swarmable是否存在错误有环则不可 swarm人类可读输出按Wave 1 / Wave 2 ...逐波列出任务并给出Estimated worker-sessions、Max parallelism、Total waves与最终结论Swarmable: YES/NO (fix errors first)。Ready Front 的底层算法computeReadyFrontscmd/bd/swarm.go采用Kahn 算法计算拓扑波次先统计每个未关闭任务未关闭前置依赖的数量作为入度入度为 0 的任务构成 Wave 0处理完当前波后将其后继的入度递减减到 0 的任务进入下一波直到全部排完。每波即一个可并行执行的就绪前沿。一个值得注意的实现细节对应 issue GH#4564已关闭Closed的任务被排除在波次之外也不再阻塞其后继——一个已关闭的依赖被视为已满足。由 swarm_ready_fronts_test.go 中的TestComputeReadyFrontsExcludesClosed与TestAnalyzeEpicForSwarmClosedCycleDoesNotSuppressOpenFronts可以验证即使存在closed-a ↔ open-b这样的闭合-开启互环只要环中一侧已关闭环就不会被报告为结构性错误也不会抑制其他开放子任务的就绪波次。数据模型依赖类型如何影响就绪计算swarm 的就绪/阻塞判定完全建立在 Beads 依赖类型体系之上。DependencyType定义于 internal/types/types.go其中与 swarm 相关的核心类型包括依赖类型语义blocks硬阻塞前置不完成后继不能开工parent-child父子结构关系Epic → 子任务conditional-blocks条件阻塞waits-for扇出门等待动态子任务relates-to松散知识图谱边swarm 分子 → Epic 即用此类型判定哪些依赖影响就绪计算的方法AffectsReadyWorkinternal/types/types.go只认可blocks、parent-child、conditional-blocks、waits-for四种relates-to、related、replies-to等非阻塞边一律不计入就绪判定。因此 swarm 的波次计算只会被真正的阻塞依赖驱动松散关联不会拖慢进度。在分析 Epic 时源码还特别跳过子任务指向 Epic 自身的parent-child边避免把父子结构误当阻塞并且只统计 Epic 内部的依赖、对跨 Epic 依赖给出警告cmd/bd/swarm.go。测试与验证该功能具备完整的测试覆盖可作为理解行为的补充证据单元测试cmd/bd/swarm_ready_fronts_test.go用内存版fakeSwarmStorage验证已关闭任务不进波次、闭环不抑制开放波次、MaxParallelism与EstimatedSessions的数值口径。嵌入式集成测试cmd/bd/swarm_embedded_test.go通过bd graph create一个 JSON plan 文件1 个 epic 3 个 task 1 条blocks边构造可 swarm 的 DAG随后覆盖validate含--verbose/--json、create含--coordinator、--force、重复创建报错、单任务自动包裹、JSON 字段、status、list等全部路径create_force与create_error_existing用例印证了已有分子时未加--force会失败的行为。代理服务集成测试swarm_proxied_integration_test.go覆盖 proxied-server 模式下status/validate的代理执行路径。端到端使用流程示例结合上述命令一个典型的 swarm 工作流如下规划用bd graph create或bd epic建立 Epic 及子任务并通过bd dep添加blocks依赖形成 DAG。预检bd swarm validate gt-epic-123—— 查看波次划分与警告修复环、断连等结构问题直到Swarmable: YES。创建bd swarm create gt-epic-123 --coordinator observer/witness—— 生成 swarm 分子得到gt-swarm-xxx。监控bd swarm list总览所有集群进度bd swarm status gt-epic-123或bd swarm status gt-swarm-xxx查看四类状态明细。迭代协调 Agent 从 Ready 组领取任务、置为 in_progress 开工任务关闭后status自动反映新进度后继任务转入 Ready。全程无需手工维护任何集群状态表——swarm 的一切状态都实时派生自底层 beads。更完整的命令参考见 docs/cli-reference/swarm.md由bd help --doc swarm自动生成。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beads 的 `bd swarm`：基于 Epic 依赖 DAG 编排编码 Agent 并行工作流
Beads 的bd swarm基于 Epic 依赖 DAG 编排编码 Agent 并行工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd swarm是 BeadsbdCLI中用于协调 Epic 并行工作的集群swarm管理命令组。它把一个 Epic 及其子任务、以及子任务之间的依赖关系抽象成一张有向无环图DAG据此创建可被任意协调 Agentcoordinator拾取的 swarm 分子swarm molecule、实时计算集群进度、并校验 Epic 结构是否具备并行执行条件。读完本文你将掌握bd swarm create / list / status / validate四个子命令的完整用法、全部 Flags 与 JSON 输出并从源码层面理解 Ready Front就绪波次、依赖方向检查与环检测的底层实现原理。什么是 SwarmEpic 依赖 DAG 分子从官方文档与源码定义看swarm 是一个由 Epic 及其子任务构成的结构化工作体子任务之间的依赖关系形成一张 DAGdirected acyclic graph。其入口定义位于 cmd/bd/swarm.goA swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work.swarm 并不是一张独立存储的表而是一个**分子molecule**——Beads 中mol_type为swarm的特殊 Issue。在 internal/types/types.go 中可以看到三种分子类型mol_type含义swarm协调多 worker 并行工作的分子patrol周期性运维工作的分子work常规指派工作分子默认swarm 分子通过一条relates-to类型的依赖边指向它编排的 Epic从而建立分子 ↔ Epic的关联Epic 再通过parent-child依赖边挂载全部子任务。整个体系围绕依赖图工作状态由底层 beadsIssue 及其依赖关系实时计算得出而非单独存储因此任何一条 Issue 状态或依赖关系的变化都会立即反映到 swarm 的进度与就绪情况中。通用行为与前提bd swarm [flags]作为命令组其下挂载create、list、status、validate四个子命令注册见 cmd/bd/swarm.go。所有子命令都支持全局--json标志输出机器可读结果部分子命令还有自己的专属 Flags。命令需要已打开的数据库连接no database connection报错Issue ID 支持部分 ID 解析utils.ResolvePartialID即输入前缀即可匹配完整 ID。在 proxied-server代理服务模式下create与list会直接报not supported in proxied-server mode而status与validate可通过代理服务器执行见 swarm_proxied_server.go。bd swarm create创建 swarm 分子create用于为一个 Epic 创建编排并行工作的 swarm 分子。bd swarm create [epic-id] [flags]FlagsFlag类型默认值说明--coordinator stringstring空协调者地址例如my-project/witness指定后该分子可被任何协调 Agent 拾取--forceboolfalse即使已存在 swarm 分子也强制新建典型用法bd swarm create bd-epic-123 # 为 epic 创建 swarm bd swarm create bd-epic-123 --coordinatorobserver/ # 指定协调者 bd swarm create bd-task-456 # 自动包裹单个 issue行为细节输入为 Epic或 molecule时直接以该 Epic 为目标创建分子。输入为普通 Issue非 Epic时自动包裹auto-wrap先创建一个标题形如Swarm Epic: 原标题的 Epic把该 Issue 作为其唯一子任务通过parent-child依赖挂载再为这个新 Epic 创建 swarm 分子。源码路径见 cmd/bd/swarm.go。创建过程包含以下关键步骤解析输入 ID通过utils.ResolvePartialID定位 Issue类型不是 Epic/molecule 则走自动包裹逻辑。查重调用findExistingSwarmcmd/bd/swarm.go遍历 Epic 的所有依赖者找出mol_typeswarm且通过relates-to边指向该 Epic 的既有分子若已存在且未传--force则报错提示Use --force to create another.。结构预检对 Epic 调用analyzeEpicForSwarm做可 swarm 性分析若存在环等结构性错误Swarmablefalse拒绝创建并列出错误清单。创建分子生成一个mol_typeswarm、IssueTypemolecule的新 Issue标题为Swarm: Epic标题Assignee设为 coordinator可空再添加一条指向 Epic 的relates-to依赖边形成分子 → Epic的关联。--json模式下成功输出包含swarm_id、epic_id、coordinator、analysis完整 SwarmAnalysis四个字段已有分子时输出error、existing_id、existing_title。bd swarm list列出全部 swarm 及进度list列出仓库中所有 swarm 分子并附带各自进度信息。bd swarm list [flags]bd swarm list # 列表人类可读输出 bd swarm list --json # 机器可读输出列表项SwarmListItem见 cmd/bd/swarm.go包含id/title分子 ID 与标题epic_id/epic_title通过relates-to依赖追溯到的目标 Epicstatus、coordinator分子状态与协调者来自Assigneetotal_issues、completed_issues、active_issues、progress_percent由getSwarmStatus实时计算实现上list以MolTypeswarm为过滤条件调用SearchIssuescmd/bd/swarm.go随后对每个分子逐条解析relates-to边找到 Epic 并计算进度。人类可读输出形如 Active Swarms (2) gt-swarm-456 Swarm: Release 2.0 Epic: gt-epic-123 (Release 2.0) Progress: 3/8, 2 active (38%) Coordinator: observer/bd swarm status从 beads 实时计算集群状态status展示某个 swarm 的当前状态。它的输入有两种Epic ID展示该 Epic 子任务的状态或swarm 分子 ID沿relates-to边回溯找到 Epic。bd swarm status [epic-or-swarm-id] [flags]bd swarm status gt-epic-123 # 按 epic 查状态 bd swarm status gt-swarm-456 # 经分子回溯 epic bd swarm status gt-epic-123 --json四类状态分组输出将全部子任务按状态分为四组计算逻辑见getSwarmStatuscmd/bd/swarm.go分组判定规则Completed已完成状态为 Closed附closed_at时间Active进行中状态为 in_progress附assigneeReady就绪处于 Open 且所有依赖都已满足无未关闭的前置依赖Blocked阻塞处于 Open 且存在未关闭的前置依赖附blocked_by列表关键设计状态是计算出来的不是存储出来的。正如文档所述 The status is COMPUTED from beads, not stored separately. If beads changes, status changes.——只要任一 Issue 关闭或依赖解除下次执行status就会得到新结果。进度百分比为completed / total * 100--json输出完整的SwarmStatus含epic_id、epic_title、四组明细、progress_percent、各计数。人类可读输出还贴心地在 Ready 为空时汇总正在等待哪些前置任务(none - waiting for ...)。bd swarm validate校验 Epic 是否适合并行执行validate对 Epic 的结构做静态分析判断其是否满足 swarm 执行条件。bd swarm validate [epic-id] [flags]bd swarm validate gt-epic-123 # 校验 epic 结构 bd swarm validate gt-epic-123 --verbose # 输出详细 issue 图FlagFlag类型默认值说明--verboseboolfalse在输出中附上详细 issue 依赖图issues字段五类结构检查根据文档与detectStructuralIssues实现cmd/bd/swarm.go校验覆盖依赖方向检查依赖应基于需求requirement而非时间先后temporal。实现采用标题启发式——若标题含foundation/setup/base/core的基础性任务没有后继者或含integration/final/test的收尾型任务没有前置依赖则给出依赖方向可能反转的警告。孤儿问题roots with no dependents找出没有前置依赖的根节点多个根是正常的它们构成并行起点。缺失依赖leaves that should depend on something找出没有后继的叶子节点多个叶子可能意味着任务间缺少连接。环检测cycles通过三色 DFS 检测依赖环一旦发现即在Errors中记录Dependency cycle detected involving: ...并置Swarmablefalse。断连子图disconnected subgraphs从所有根节点出发 DFS 遍历无法到达的节点判为断连给出警告。此外若子任务依赖了 Epic 之外的 Issue 或external:外部引用也会产生警告。报告输出validate报告以下指标SwarmAnalysis见 cmd/bd/swarm.goready_fronts就绪波次可并行的任务浪潮每波含wave编号、issues、titlesestimated_sessions预估 worker 会话数≈ 剩余未关闭任务数max_parallelism最大并行度各波次任务数的最大值warnings/errors结构问题清单swarmable是否存在错误有环则不可 swarm人类可读输出按Wave 1 / Wave 2 ...逐波列出任务并给出Estimated worker-sessions、Max parallelism、Total waves与最终结论Swarmable: YES/NO (fix errors first)。Ready Front 的底层算法computeReadyFrontscmd/bd/swarm.go采用Kahn 算法计算拓扑波次先统计每个未关闭任务未关闭前置依赖的数量作为入度入度为 0 的任务构成 Wave 0处理完当前波后将其后继的入度递减减到 0 的任务进入下一波直到全部排完。每波即一个可并行执行的就绪前沿。一个值得注意的实现细节对应 issue GH#4564已关闭Closed的任务被排除在波次之外也不再阻塞其后继——一个已关闭的依赖被视为已满足。由 swarm_ready_fronts_test.go 中的TestComputeReadyFrontsExcludesClosed与TestAnalyzeEpicForSwarmClosedCycleDoesNotSuppressOpenFronts可以验证即使存在closed-a ↔ open-b这样的闭合-开启互环只要环中一侧已关闭环就不会被报告为结构性错误也不会抑制其他开放子任务的就绪波次。数据模型依赖类型如何影响就绪计算swarm 的就绪/阻塞判定完全建立在 Beads 依赖类型体系之上。DependencyType定义于 internal/types/types.go其中与 swarm 相关的核心类型包括依赖类型语义blocks硬阻塞前置不完成后继不能开工parent-child父子结构关系Epic → 子任务conditional-blocks条件阻塞waits-for扇出门等待动态子任务relates-to松散知识图谱边swarm 分子 → Epic 即用此类型判定哪些依赖影响就绪计算的方法AffectsReadyWorkinternal/types/types.go只认可blocks、parent-child、conditional-blocks、waits-for四种relates-to、related、replies-to等非阻塞边一律不计入就绪判定。因此 swarm 的波次计算只会被真正的阻塞依赖驱动松散关联不会拖慢进度。在分析 Epic 时源码还特别跳过子任务指向 Epic 自身的parent-child边避免把父子结构误当阻塞并且只统计 Epic 内部的依赖、对跨 Epic 依赖给出警告cmd/bd/swarm.go。测试与验证该功能具备完整的测试覆盖可作为理解行为的补充证据单元测试cmd/bd/swarm_ready_fronts_test.go用内存版fakeSwarmStorage验证已关闭任务不进波次、闭环不抑制开放波次、MaxParallelism与EstimatedSessions的数值口径。嵌入式集成测试cmd/bd/swarm_embedded_test.go通过bd graph create一个 JSON plan 文件1 个 epic 3 个 task 1 条blocks边构造可 swarm 的 DAG随后覆盖validate含--verbose/--json、create含--coordinator、--force、重复创建报错、单任务自动包裹、JSON 字段、status、list等全部路径create_force与create_error_existing用例印证了已有分子时未加--force会失败的行为。代理服务集成测试swarm_proxied_integration_test.go覆盖 proxied-server 模式下status/validate的代理执行路径。端到端使用流程示例结合上述命令一个典型的 swarm 工作流如下规划用bd graph create或bd epic建立 Epic 及子任务并通过bd dep添加blocks依赖形成 DAG。预检bd swarm validate gt-epic-123—— 查看波次划分与警告修复环、断连等结构问题直到Swarmable: YES。创建bd swarm create gt-epic-123 --coordinator observer/witness—— 生成 swarm 分子得到gt-swarm-xxx。监控bd swarm list总览所有集群进度bd swarm status gt-epic-123或bd swarm status gt-swarm-xxx查看四类状态明细。迭代协调 Agent 从 Ready 组领取任务、置为 in_progress 开工任务关闭后status自动反映新进度后继任务转入 Ready。全程无需手工维护任何集群状态表——swarm 的一切状态都实时派生自底层 beads。更完整的命令参考见 docs/cli-reference/swarm.md由bd help --doc swarm自动生成。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
