Beads bd merge-slot 完全指南用互斥合并槽串行化多 Agent 冲突解决【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd merge-slot是 Beads 提供给编码 Agent 的排他访问原语exclusive access primitive每个 rig 只能有一个 Agent 同时持有合并槽从而把合并队列中的冲突解决过程串行化避免多个 Agent 同时抢着解决冲突而制造级联冲突。本文以 docs/cli-reference/merge-slot.md 为骨架结合cmd/bd/merge_slot.go的命令实现与internal/storage/merge_slot.go的存储层实现完整讲解create / check / acquire / release四个子命令、--holder与--wait两个关键参数以及槽位状态机、等待队列与事务级原子性保证读完即可在自己的多 Agent 协作工作流中直接落地使用。一、为什么需要 merge-slot串行化冲突解决在多 Agent 并行协作的场景下多个 Agent文档中戏称为 polecats可能同时检测到合并冲突并争相解决。如果它们各自基于同一份冲突现场做修改结果往往是互相覆盖、冲突越解决越多——这就是文档中所说的 monkey knife fights猴群抢刀混战以及级联冲突cascading conflicts。bd merge-slot正是为此设计的排他访问机制一个合并槽同一时刻只允许一个 Agent 持有。谁持有槽谁才有资格进行冲突解决其他人要么等待要么排队。这样冲突解决被强制串行化从根源上消除了并发写冲突。在 Beads 的存储接口定义中这一原语被明确注释为serialized conflict resolution primitive见 internal/storage/storage.go属于Storage接口能力之一与DoltStore、EmbeddedDoltStore两种存储实现均兼容。二、merge slot 的数据模型合并槽不是一个独立实体而是以issue珠子 bead的形式存储在仓库中的每个 rig 恰好有一个合并槽珠子槽 IDprefix-merge-slot其中 prefix 取自配置键issue_prefix。例如issue_prefixgt时槽 ID 为gt-merge-slot未配置时回退为bd-merge-slot。该规则由MergeSlotID实现见 internal/storage/merge_slot.go。标签所有合并槽统一打上gt:slot标签常量mergeSlotLabel便于工具无需知道精确 ID 就能通过标签检索到槽位见 internal/storage/merge_slot.go。标题与描述创建时标题为Merge Slot描述为 Exclusive access slot for serialized conflict resolution in the merge queue.类型为TypeTask见 internal/storage/merge_slot.go。槽位状态通过两个字段联合表达字段取值含义statusopen槽位可用等待被获取statusin_progress槽位已被某个 Agent 持有metadata.holder字符串当前持有者的身份标识metadata.waiters字符串数组按优先级排序的等待者队列其中metadata内部序列化为 JSON结构为type slotMeta struct { Holder string json:holder,omitempty Waiters []string json:waiters,omitempty }见 internal/storage/merge_slot.go。parseSlotMeta负责从 issue 的Metadata字段反序列化出持有者与等待队列internal/storage/merge_slot.go。三、命令总览bd merge-slot是挂在根命令下的子命令组属于issues命令分组GroupID: issues完整用法bd merge-slot [flags]常用示例bd merge-slot create # 为当前 rig 创建合并槽 bd merge-slot check # 检查槽位是否可用 bd merge-slot acquire # 尝试获取槽位 bd merge-slot release # 释放槽位命令组下共四个子命令create、check、acquire、release全部通过 cobra 注册见 cmd/bd/merge_slot.go。四个子命令均声明Args: cobra.NoArgs即不接受位置参数同时设置了SilenceUsage与SilenceErrors错误信息会走统一的错误处理通道。四、bd merge-slot create创建槽位为当前 rig 创建用于串行化冲突解决的合并槽珠子bd merge-slot create [flags]要点槽 ID 根据 beads 前缀自动生成如gt-merge-slot规则见上文MergeSlotID。创建后槽位状态为statusopen可用。幂等如果槽位已存在直接返回现有槽位而不报错见 internal/storage/merge_slot.go可以放心重复执行。成功输出示例✓ Created merge slot: gt-merge-slot使用 JSON 输出--json时返回{id: ..., status: open}。注意create属于写操作代码中先调用CheckReadonly(merge-slot create)在只读模式下会被拒绝cmd/bd/merge_slot.go。五、bd merge-slot check检查槽位状态检查合并槽当前是可用还是被持有bd merge-slot check [flags]返回三种结果available槽位可被获取statusopenheld by holder槽位正被某 Agent 持有not found当前 rig 尚不存在合并槽。not found时命令会打印槽 ID 并提示先执行bd merge-slot create不会以错误退出cmd/bd/merge_slot.go。槽位被持有时非 JSON 输出会展示持有者与等待队列cmd/bd/merge_slot.go○ Merge slot held: gt-merge-slot Holder: agent-a Waiters: 3 1. agent-b 2. agent-c 3. agent-dJSON 输出结构为{id, available, holder, waiters}其中空holder会被规范化为nullnilIfEmpty见 cmd/bd/merge_slot.go。六、bd merge-slot acquire获取槽位核心尝试获取合并槽以获得排他访问权bd merge-slot acquire [flags]Flags--holder string Who is acquiring the slot (default: BEADS_ACTOR) --wait Add to waiters list if slot is held行为规则槽位可用statusopen直接获取成功——status置为in_progressholder设为请求者身份。槽位被持有statusin_progress命令失败退出码非 0并提示slot held by: holder Use --wait to add yourself to the waiters queue.除非传入--wait此时请求者会被加入等待队列。--holder用于指定谁在获取默认取BEADS_ACTOR环境变量若两者都为空命令直接报错no holder specified; use --holder or set BEADS_ACTOR env varcmd/bd/merge_slot.go。成功获取的输出✓ Acquired merge slot: gt-merge-slot Holder: agent-a--wait入队后的输出注意此时命令以静默退出码结束SilentExit()○ Slot held by agent-a, added to waiters queue (position 2)JSON 模式下成功返回{id, acquired: true, holder}入队返回{id, acquired: false, waiting: true, holder, position}获取失败返回{id, acquired: false, holder}。原子性为什么不会两个 Agent 同时拿到槽acquire的关键在于原子 check-and-set。存储层实现MergeSlotAcquireImpl将整个读取槽位 → 判断状态 → 更新状态/元数据过程包在RunInTransaction事务中见 internal/storage/merge_slot.go确保两个 Agent 并发调用时只有一个能观察到open状态并成功置为in_progress另一个必然看到in_progress而走失败/排队分支。这正是排他语义的底层保障事务描述字符串形如bd: acquire merge slot gt-merge-slot for agent-a。此外入队逻辑自带去重若--wait的请求者已在waiters中不会重复追加internal/storage/merge_slot.go。七、bd merge-slot release释放槽位冲突解决完成后释放合并槽bd merge-slot release [flags]Flags--holder string Who is releasing the slot (for verification)行为规则将status置回open并清空holder字段--holder用于身份校验若传入的持有者与当前metadata.holder不一致释放失败并报错slot held by X, not Y见 internal/storage/merge_slot.go若槽位本身已是open释放为幂等操作直接成功返回释放时保留waiters队列newMeta : slotMeta{Waiters: meta.Waiters}因为等待者仍需要排队文档明确建议若有等待者应由优先级最高的等待者随后获取acquire槽位。成功输出✓ Released merge slot: gt-merge-slotJSON 输出为{id, released: true}。与create、acquire一样release也是写操作受只读模式保护CheckReadonly(merge-slot release)cmd/bd/merge_slot.go。八、存储层实现两种后端共享同一套逻辑Beads 的存储抽象由DoltStore与EmbeddedDoltStore两种后端实现二者都满足Storage接口因此合并槽的全部业务逻辑被抽到internal/storage包中的共享实现函数两个后端只是薄薄地转发internal/storage/dolt/merge_slot.goDoltStore的四个方法全部委托给MergeSlot*Implinternal/storage/embeddeddolt/merge_slot.goEmbeddedDoltStore同样委托给同一组共享实现。而MergeSlotStatusSlotID / Available / Holder / Waiters与MergeSlotResultSlotID / Acquired / Waiting / Holder / Position两个返回结构定义在 internal/storage/storage.goPosition为 1 起始的等待队列位置。这种接口 共享实现 后端适配的结构意味着无论底层是独立 Dolt 服务还是嵌入式 Doltbd merge-slot的命令行语义与事务保证完全一致。九、典型多 Agent 工作流将上述命令串起来就是一个标准的串行化冲突解决协作流程# 0. 初始化仅需一次幂等可重复执行 bd merge-slot create # 1. 进入合并队列的 Agent 先检查槽位 bd merge-slot check # 2. 尝试获取排他访问权被占用时选择排队等待 bd merge-slot acquire --holder agent-a --wait # 3. 拿到槽位后执行冲突解决、合并等写操作…… # 4. 完成后释放槽位可校验持有者身份 bd merge-slot release --holder agent-a # 5. 释放后等待队列中优先级最高的 Agent 应随即 acquire 接管需要特别说明的两个环境前提--holder默认取BEADS_ACTOR环境变量多 Agent 场景下务必保证每个 Agent 设置了唯一且稳定的身份值否则 acquire/release 的持有者校验无法生效当前版本的bd merge-slot四个子命令在proxied-server 模式客户端代理服务器模式下均不支持会直接返回 merge-slot ... is not supported in proxied-server mode见 cmd/bd/merge_slot.go 等处的usesProxiedServer()守卫请确认运行环境为直接/嵌入式模式。十、小结bd merge-slot是 Beads 多 Agent 协作体系中解决冲突解决本身发生冲突的关键原语以prefix-merge-slot珠子承载互斥状态用statusmetadata.holdermetadata.waiters表达可用/被持有/排队三态靠RunInTransaction保证 acquire 的原子 check-and-set并通过--holder身份校验与--wait排队机制让多个 Agent 有序接力。理解并善用这四个子命令即可在自己的多 Agent 合并队列中彻底规避级联冲突。如需查阅命令行原始文档可直接阅读 docs/cli-reference/merge-slot.md由bd help --doc merge-slot自动生成请勿手动编辑命令实现见 cmd/bd/merge_slot.go存储层共享实现见 internal/storage/merge_slot.go。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考