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），僅供參考