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-2（holder-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 Handoff）
Agent 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结构化扇出的进阶方案：对于正式的大型 epic，bd swarm可以创建一个 swarm molecule 来编排并跟踪并行工作（见 cmd/bd/swarm.go）：
bd swarm create bd-epic-123 # 为 epic 创建 swarm bd swarm create bd-epic-123 --coordinator=observer/ # 指定协调者身份 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 而不是 assign：
bd 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）：
| 字段 | 含义 |
|---|---|
status=open | slot 可用 |
status=in_progress | slot 被持有 |
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），仅供参考
