Beads 多 Agent 协作指南任务分配、工作交接与冲突序列化【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本指南面向使用 Beads 驱动多个 AI Agent 协同工作的场景围绕 docs/multi-agent/coordination.md 展开讲解如何在 Agent 之间分配与原子认领claim工作、通过评论与标签完成交接、用 merge slot 串行化冲突密集的合并工作以及跨仓库协调任务依赖。读完本文你将掌握一套可落地的多 Agent 编排命令组合并能理解这些命令在 Beads 存储层internal/storage/merge_slot.go背后的原子性保证。工作分配Assign 与 Claim多 Agent 协作的第一步是确定谁做什么。Beads 提供两条互补的路径指派assign由协调者决定归属认领claim由 Agent 自主抢占。# 把 issue 指派给某个 Agent bd assign bd-42 agent-1 # 原子地认领一个 issue把 assignee 设为自己状态置为 in_progress bd update bd-42 --claim # 认领第一个匹配你过滤条件的 ready issue bd ready --claim --json # 释放已认领的 issue bd assign bd-42 # 清空 assignee bd update bd-42 --status open # 让它重新可被认领从源码看bd assign实际上是bd update id --assignee name的简写形式cmd/bd/assign.go参数名传空字符串即可清空 assignee。它附带一个重要的安全选项# 仅当当前 assignee 是 agent-1 时才转移给 agent-2holder-aware 转移避免覆盖他人 bd update bd-42 --if-assignee agent-1 -a agent-2 # 强制覆盖他人 in_progress 的认领仅限确认对方已崩溃、租约过期等废弃场景 bd assign bd-42 agent-2 --force--force的注释明确警告它用于abandoned claims崩溃的 Agent、过期的租约并优先推荐bd reclaim走正规回收流程。日常协作中应尽量避免覆盖其他 Agent 的活跃认领。检查已分配的工作# agent-1 正在做什么 bd list --assignee agent-1 --status in_progress # 什么工作对 agent-1 是就绪的 bd ready --assignee agent-1 # JSON 输出方便 Agent 解析 bd list --assignee agent-1 --json--json在整个 CLI 中普遍可用是 Agent 消费结构化数据的标准接口——例如 merge-slot 的check/acquire/release、ready 的--claim都支持 JSON 输出见 cmd/bd/merge_slot.go 中jsonOutput分支。交接模式顺序、并行与扇出扇入顺序交接Sequential HandoffAgent A 完成工作后用评论说明上下文再把 assignee 转移给 Agent B# Agent A bd comment bd-42 API complete, ready for review bd assign bd-42 agent-b # Agent B 接手 bd list --assignee agent-b # 看到 bd-42 bd update bd-42 --claim并行工作Parallel Work协调者把不同 issue 分给不同 Agent各 Agent 独立认领后并行推进协调者用一条命令持续监控# 协调者 bd assign bd-42 agent-a bd assign bd-43 agent-b bd assign bd-44 agent-c # 每个 Agent 认领自己的 issue 独立工作 bd update bd-42 --claim # 协调者监控进度 bd list --status in_progress --json扇出 / 扇入Fan-Out / Fan-In把一个大任务拆成多个部分并行执行再汇聚回一个合并点# 扇出在 epic 下创建子任务 bd create Part A --parent bd-epic bd create Part B --parent bd-epic bd create Part C --parent bd-epic bd assign bd-epic.1 agent-a bd assign bd-epic.2 agent-b bd assign bd-epic.3 agent-c # 扇入等待所有部分完成一次调用只加一条依赖 bd dep add bd-merge bd-epic.1 bd dep add bd-merge bd-epic.2 bd dep add bd-merge bd-epic.3关于 epic 上的 size/effort 标签bd create --parent默认会把父级的标签继承到子级详见 docs/core-concepts/labels.md。如果bd-epic带有large或sp:13这类规模标签子任务也会继承它导致bd list -l large返回整棵子树而失去筛选意义。需要按子任务单独估算时创建时传入--no-inherit-labels即可bd create Part A --parent bd-epic --no-inherit-labels -l small结构化扇出的进阶方案对于正式的大型 epicbd swarm可以创建一个 swarm molecule 来编排并跟踪并行工作见 cmd/bd/swarm.gobd swarm create bd-epic-123 # 为 epic 创建 swarm bd swarm create bd-epic-123 --coordinatorobserver/ # 指定协调者身份 bd swarm status gt-swarm-456 # 通过 swarm molecule 查看状态swarm molecule 与 epic 之间通过 relate-to 依赖关联对单个任务使用bd swarm create bd-task-456会自动将其包装成 swarm源码注释为 Auto-wrap single issue。这比手工多次bd create --parent更适合需要跟踪整体进度的场景。Agent 发现没有注册表靠状态聚合Beads没有 Agent 注册表——assignee 只是普通字符串不存在Agent 上线/下线的概念。想知道当前哪些 Agent 活跃按 assignee 聚合 in_progress 的工作即可bd list --status in_progress --json这个设计意味着任何字符串都可以作为 assignee 使用Agent 身份完全由工作数据派生天然支持异构 Agent不同工具链、不同会话在同一仓库里协作。冲突预防原子认领与 Merge Slot原子认领Atomic Claims多个 Agent 从同一个 ready 队列取活时--claim是原子的第一个认领者胜出且重复认领自己已持有的 issue 是幂等的。因此当 Agent 自主挑选工作时优先用 claim 而不是 assignbd ready --claim --json底层实现上bd ready --claim走的是ReadyClaimer角色cmd/bd/ready.go它通过 store 的ReadyClaimer()拿到 claimer 后调用ClaimNext。而 issueops/claimer.go 中明确ClaimRequest 描述的是one atomic compare-and-set claim整个请求作为一个原子操作提交——这正是第一个认领者胜出的保证来源。使用限制源码中直接校验--claim不能与--gated、--mol、--explain组合使用同时会触发只读检查CheckReadonly(ready --claim)。Merge Slot冲突密集工作的独占串行化对于谁先合并谁这类天然冲突密集的工作典型如 merge-queue 的冲突解决Beads 提供merge slot——一种独占访问原语同一时刻只允许一个 Agent 持有。每个项目只有一个 merge slot bead命名由 issue 前缀推导而来例如bd-merge-slot# 为当前项目创建 merge slot bd merge-slot create # 检查可用性 bd merge-slot check # 开始前获取完成后释放 bd merge-slot acquire bd merge-slot release状态模型来自 cmd/bd/merge_slot.go 与 internal/storage/merge_slot.go字段含义statusopenslot 可用statusin_progressslot 被持有metadata.holder当前持有者metadata.waiters按优先级排序的等待队列实现细节ID 推导MergeSlotID读取配置issue_prefix如gt拼出prefix-merge-slot未配置时回退为bd-merge-slot。可发现性标签每个 slot bead 都带gt:slot标签工具无需知道确切 ID 就能定位它。幂等创建create重复执行不会报错直接返回已存在的 slot。原子获取acquire在RunInTransaction内完成检查状态 → 置为 in_progress → 写入 holder的原子 check-and-set两个 Agent 不可能同时拿到 slot。等待队列slot 被占时acquire默认失败并提示Use --wait to add yourself to the waiters queue传入--wait则把自己加入 waiters去重并返回排队位置。# 指定获取者身份默认取 BEADS_ACTOR 环境变量 bd merge-slot acquire --holder agent-1 # slot 被占用时排队等待 bd merge-slot acquire --wait # 释放时校验持有者防止误释放他人占用的 slot bd merge-slot release --holder agent-1# 释放校验失败的示例slot 被 agent-1 持有agent-2 无法释放 $ bd merge-slot release --holder agent-2 slot held by agent-1, not agent-2释放操作同样是幂等的slot 已是 open 时重复 release 直接返回成功。JSON 输出可用于 Agent 编程式判断available、holder、waiters、acquired、waiting、position等字段。需要留意merge-slot 系列命令在 proxied-server 模式下不可用源码中四个子命令均显式拒绝。通信模式评论与标签通过评论Comments评论是 Agent 之间传递上下文的主要载体评论内容会进入完整的事件历史# Agent A 留下说明 bd comment bd-42 Completed API, needs frontend integration # Agent B 读取 bd comments bd-42通过标签Labels标签适合做可过滤的状态信号配合--label-any让下游 Agent 精准拉取自己关心的批次# 标记为待评审 bd update bd-42 --add-label needs-review # Agent B 按标签过滤 bd list --label-any needs-review推荐的状态标签约定needs-review、blocked、ready详见本文末尾最佳实践。跨仓库协调Agent 可以协调跨越多个仓库的工作当一个 issue 依赖另一个项目交付的能力时使用external:前缀的外部引用依赖cmd/bd/dep.go# 依赖由另一个项目交付的能力 bd dep add bd-42 external:backend:api-ready更多跨仓库的路由multi-repo routing、聚合视图以及贡献者/团队工作流参见 docs/multi-agent/routing.md 与 docs/multi-agent/multi-repo-migration.md。最佳实践清单明确归属Clear ownership——用 assign 或 claim 让每个 issue 恰好有一个负责人避免三个和尚没水喝。交接留痕Document handoffs——用评论说明上下文让接手的 Agent 无需考古就能继续。用标签表达状态Use labels for status——统一使用needs-review、blocked、ready等约定标签配合--label-any做队列筛选。主动避免冲突Avoid conflicts——Agent 自主取活时优先原子 claim冲突密集的工作如合并冲突解决用 merge slot 串行化杜绝多个 Agent 同时改同一处导致冲突雪崩。持续监控进度Monitor progress——定期用bd list --status in_progress --json汇总在途工作。会话结束同步Sync at session end——每个 Agent 工作结束时运行bd dolt push让其他 Agent 立刻看到你的更新同步机制详见 docs/core-concepts/sync-concepts.md。小结Beads 的多 Agent 协调能力建立在三个核心机制之上assign/claim 双通道归属控制、评论标签的轻量通信、merge slot 的独占串行化。其中原子 claim 由 ReadyClaimer 角色的 compare-and-set 保证merge slot 由事务内的 check-and-set 保证两者都直接落在 Dolt 存储层internal/storage/merge_slot.go因此无论多少个 Agent 并发操作状态都不会错乱。配合bd swarm编排大型 epic、external:依赖打通跨仓库协作这套模式足以支撑从两三个 Agent 的小团队到多仓库、多 Agent 的规模化并行开发。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 多 Agent 协作指南：任务分配、工作交接与冲突序列化
Beads 多 Agent 协作指南任务分配、工作交接与冲突序列化【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本指南面向使用 Beads 驱动多个 AI Agent 协同工作的场景围绕 docs/multi-agent/coordination.md 展开讲解如何在 Agent 之间分配与原子认领claim工作、通过评论与标签完成交接、用 merge slot 串行化冲突密集的合并工作以及跨仓库协调任务依赖。读完本文你将掌握一套可落地的多 Agent 编排命令组合并能理解这些命令在 Beads 存储层internal/storage/merge_slot.go背后的原子性保证。工作分配Assign 与 Claim多 Agent 协作的第一步是确定谁做什么。Beads 提供两条互补的路径指派assign由协调者决定归属认领claim由 Agent 自主抢占。# 把 issue 指派给某个 Agent bd assign bd-42 agent-1 # 原子地认领一个 issue把 assignee 设为自己状态置为 in_progress bd update bd-42 --claim # 认领第一个匹配你过滤条件的 ready issue bd ready --claim --json # 释放已认领的 issue bd assign bd-42 # 清空 assignee bd update bd-42 --status open # 让它重新可被认领从源码看bd assign实际上是bd update id --assignee name的简写形式cmd/bd/assign.go参数名传空字符串即可清空 assignee。它附带一个重要的安全选项# 仅当当前 assignee 是 agent-1 时才转移给 agent-2holder-aware 转移避免覆盖他人 bd update bd-42 --if-assignee agent-1 -a agent-2 # 强制覆盖他人 in_progress 的认领仅限确认对方已崩溃、租约过期等废弃场景 bd assign bd-42 agent-2 --force--force的注释明确警告它用于abandoned claims崩溃的 Agent、过期的租约并优先推荐bd reclaim走正规回收流程。日常协作中应尽量避免覆盖其他 Agent 的活跃认领。检查已分配的工作# agent-1 正在做什么 bd list --assignee agent-1 --status in_progress # 什么工作对 agent-1 是就绪的 bd ready --assignee agent-1 # JSON 输出方便 Agent 解析 bd list --assignee agent-1 --json--json在整个 CLI 中普遍可用是 Agent 消费结构化数据的标准接口——例如 merge-slot 的check/acquire/release、ready 的--claim都支持 JSON 输出见 cmd/bd/merge_slot.go 中jsonOutput分支。交接模式顺序、并行与扇出扇入顺序交接Sequential HandoffAgent A 完成工作后用评论说明上下文再把 assignee 转移给 Agent B# Agent A bd comment bd-42 API complete, ready for review bd assign bd-42 agent-b # Agent B 接手 bd list --assignee agent-b # 看到 bd-42 bd update bd-42 --claim并行工作Parallel Work协调者把不同 issue 分给不同 Agent各 Agent 独立认领后并行推进协调者用一条命令持续监控# 协调者 bd assign bd-42 agent-a bd assign bd-43 agent-b bd assign bd-44 agent-c # 每个 Agent 认领自己的 issue 独立工作 bd update bd-42 --claim # 协调者监控进度 bd list --status in_progress --json扇出 / 扇入Fan-Out / Fan-In把一个大任务拆成多个部分并行执行再汇聚回一个合并点# 扇出在 epic 下创建子任务 bd create Part A --parent bd-epic bd create Part B --parent bd-epic bd create Part C --parent bd-epic bd assign bd-epic.1 agent-a bd assign bd-epic.2 agent-b bd assign bd-epic.3 agent-c # 扇入等待所有部分完成一次调用只加一条依赖 bd dep add bd-merge bd-epic.1 bd dep add bd-merge bd-epic.2 bd dep add bd-merge bd-epic.3关于 epic 上的 size/effort 标签bd create --parent默认会把父级的标签继承到子级详见 docs/core-concepts/labels.md。如果bd-epic带有large或sp:13这类规模标签子任务也会继承它导致bd list -l large返回整棵子树而失去筛选意义。需要按子任务单独估算时创建时传入--no-inherit-labels即可bd create Part A --parent bd-epic --no-inherit-labels -l small结构化扇出的进阶方案对于正式的大型 epicbd swarm可以创建一个 swarm molecule 来编排并跟踪并行工作见 cmd/bd/swarm.gobd swarm create bd-epic-123 # 为 epic 创建 swarm bd swarm create bd-epic-123 --coordinatorobserver/ # 指定协调者身份 bd swarm status gt-swarm-456 # 通过 swarm molecule 查看状态swarm molecule 与 epic 之间通过 relate-to 依赖关联对单个任务使用bd swarm create bd-task-456会自动将其包装成 swarm源码注释为 Auto-wrap single issue。这比手工多次bd create --parent更适合需要跟踪整体进度的场景。Agent 发现没有注册表靠状态聚合Beads没有 Agent 注册表——assignee 只是普通字符串不存在Agent 上线/下线的概念。想知道当前哪些 Agent 活跃按 assignee 聚合 in_progress 的工作即可bd list --status in_progress --json这个设计意味着任何字符串都可以作为 assignee 使用Agent 身份完全由工作数据派生天然支持异构 Agent不同工具链、不同会话在同一仓库里协作。冲突预防原子认领与 Merge Slot原子认领Atomic Claims多个 Agent 从同一个 ready 队列取活时--claim是原子的第一个认领者胜出且重复认领自己已持有的 issue 是幂等的。因此当 Agent 自主挑选工作时优先用 claim 而不是 assignbd ready --claim --json底层实现上bd ready --claim走的是ReadyClaimer角色cmd/bd/ready.go它通过 store 的ReadyClaimer()拿到 claimer 后调用ClaimNext。而 issueops/claimer.go 中明确ClaimRequest 描述的是one atomic compare-and-set claim整个请求作为一个原子操作提交——这正是第一个认领者胜出的保证来源。使用限制源码中直接校验--claim不能与--gated、--mol、--explain组合使用同时会触发只读检查CheckReadonly(ready --claim)。Merge Slot冲突密集工作的独占串行化对于谁先合并谁这类天然冲突密集的工作典型如 merge-queue 的冲突解决Beads 提供merge slot——一种独占访问原语同一时刻只允许一个 Agent 持有。每个项目只有一个 merge slot bead命名由 issue 前缀推导而来例如bd-merge-slot# 为当前项目创建 merge slot bd merge-slot create # 检查可用性 bd merge-slot check # 开始前获取完成后释放 bd merge-slot acquire bd merge-slot release状态模型来自 cmd/bd/merge_slot.go 与 internal/storage/merge_slot.go字段含义statusopenslot 可用statusin_progressslot 被持有metadata.holder当前持有者metadata.waiters按优先级排序的等待队列实现细节ID 推导MergeSlotID读取配置issue_prefix如gt拼出prefix-merge-slot未配置时回退为bd-merge-slot。可发现性标签每个 slot bead 都带gt:slot标签工具无需知道确切 ID 就能定位它。幂等创建create重复执行不会报错直接返回已存在的 slot。原子获取acquire在RunInTransaction内完成检查状态 → 置为 in_progress → 写入 holder的原子 check-and-set两个 Agent 不可能同时拿到 slot。等待队列slot 被占时acquire默认失败并提示Use --wait to add yourself to the waiters queue传入--wait则把自己加入 waiters去重并返回排队位置。# 指定获取者身份默认取 BEADS_ACTOR 环境变量 bd merge-slot acquire --holder agent-1 # slot 被占用时排队等待 bd merge-slot acquire --wait # 释放时校验持有者防止误释放他人占用的 slot bd merge-slot release --holder agent-1# 释放校验失败的示例slot 被 agent-1 持有agent-2 无法释放 $ bd merge-slot release --holder agent-2 slot held by agent-1, not agent-2释放操作同样是幂等的slot 已是 open 时重复 release 直接返回成功。JSON 输出可用于 Agent 编程式判断available、holder、waiters、acquired、waiting、position等字段。需要留意merge-slot 系列命令在 proxied-server 模式下不可用源码中四个子命令均显式拒绝。通信模式评论与标签通过评论Comments评论是 Agent 之间传递上下文的主要载体评论内容会进入完整的事件历史# Agent A 留下说明 bd comment bd-42 Completed API, needs frontend integration # Agent B 读取 bd comments bd-42通过标签Labels标签适合做可过滤的状态信号配合--label-any让下游 Agent 精准拉取自己关心的批次# 标记为待评审 bd update bd-42 --add-label needs-review # Agent B 按标签过滤 bd list --label-any needs-review推荐的状态标签约定needs-review、blocked、ready详见本文末尾最佳实践。跨仓库协调Agent 可以协调跨越多个仓库的工作当一个 issue 依赖另一个项目交付的能力时使用external:前缀的外部引用依赖cmd/bd/dep.go# 依赖由另一个项目交付的能力 bd dep add bd-42 external:backend:api-ready更多跨仓库的路由multi-repo routing、聚合视图以及贡献者/团队工作流参见 docs/multi-agent/routing.md 与 docs/multi-agent/multi-repo-migration.md。最佳实践清单明确归属Clear ownership——用 assign 或 claim 让每个 issue 恰好有一个负责人避免三个和尚没水喝。交接留痕Document handoffs——用评论说明上下文让接手的 Agent 无需考古就能继续。用标签表达状态Use labels for status——统一使用needs-review、blocked、ready等约定标签配合--label-any做队列筛选。主动避免冲突Avoid conflicts——Agent 自主取活时优先原子 claim冲突密集的工作如合并冲突解决用 merge slot 串行化杜绝多个 Agent 同时改同一处导致冲突雪崩。持续监控进度Monitor progress——定期用bd list --status in_progress --json汇总在途工作。会话结束同步Sync at session end——每个 Agent 工作结束时运行bd dolt push让其他 Agent 立刻看到你的更新同步机制详见 docs/core-concepts/sync-concepts.md。小结Beads 的多 Agent 协调能力建立在三个核心机制之上assign/claim 双通道归属控制、评论标签的轻量通信、merge slot 的独占串行化。其中原子 claim 由 ReadyClaimer 角色的 compare-and-set 保证merge slot 由事务内的 check-and-set 保证两者都直接落在 Dolt 存储层internal/storage/merge_slot.go因此无论多少个 Agent 并发操作状态都不会错乱。配合bd swarm编排大型 epic、external:依赖打通跨仓库协作这套模式足以支撑从两三个 Agent 的小团队到多仓库、多 Agent 的规模化并行开发。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考