SwarmForge交接协议：AI代理间如何无缝协作

【免费下载链接】swarm-forgeA simple tool for coordinating several AI agents.项目地址: https://gitcode.com/GitHub_Trending/sw/swarm-forge

SwarmForge是一款简单而强大的AI代理协作工具，其核心在于通过精心设计的交接协议实现AI代理间的无缝协作。本文将深入解析这一协议的工作原理，帮助新手用户快速理解AI代理如何通过SwarmForge进行高效沟通与任务协作。

交接协议的核心目标

SwarmForge交接协议的主要目标是取代AI代理对tmux socket的直接访问，转而采用守护进程（daemon）管理的文件传输机制。这一设计确保了：

• AI代理无需发送tmux命令或管理socket权限
• 代理只需创建小型、经过验证的交接请求
• 守护进程通过持久化的收件箱文件传递请求
• 仅通过tmux发送唤醒通知，降低系统复杂性

目录结构：协作的基础架构

每个代理工作区都遵循标准化的目录结构，为交接提供清晰的路径：

.swarmforge/handoffs/ outbox/ # 待发送的交接文件 tmp/ # 临时文件存储 sent/ # 已发送成功的交接 failed/ # 发送失败的交接 inbox/ # 接收的交接 new/ # 新接收的交接 in_process/ # 处理中的交接 completed/ # 已完成的交接

守护进程监控outbox/目录，而代理通过辅助脚本处理inbox/new/中的文件。这种结构提供了完整的审计跟踪和重启状态。

交接文件命名规则：有序协作的关键

交接文件采用特定的命名格式，确保按优先级和时间顺序处理：

<priority>_<timestamp>_<sequence>_from_<sender>_to_<recipient-list>.handoff

例如：00_20260615T140531Z_000042_from_architect_to_coder_cleaner_QA.handoff

命名规则要点：

• 两位数字优先级（00-99），数值越小优先级越高
• UTC时间戳（YYYYMMDDTHHMMSSZ格式）
• 序列号确保同一秒内创建的交接文件有序
• 包含发送者和接收者信息，便于审计

交接文件格式：标准化信息交换

交接文件包含头部块、空行和生成的正文。头部包含关键元数据，正文则是具体内容：

id: 20260615T140531Z_000042_from_coder from: coder to: cleaner recipient: cleaner priority: 50 type: git_handoff role: coder task: task-1-cave-setup commit: a1b2c3d9 created_at: 2026-06-15T14:05:31Z enqueued_at: 2026-06-15T14:05:32Z Re-read your role and constitution. merge_and_process coder a1b2c3d9

头部字段由不同组件负责生成，确保信息的准确性和一致性。

消息类型：明确的协作语言

SwarmForge交接协议定义了两种主要消息类型，满足不同协作需求：

git_handoff：代码协作的基石

当一个角色完成工作并需要其他角色合并和处理时使用，包含：

• 提交哈希（commit）
• 任务名称（task）
• 优先级（priority）

示例：

type: git_handoff to: cleaner priority: 50 task: task-1-cave-setup commit: a1b2c3d9e8

生成的正文会包含明确的操作指令，确保接收方知道如何处理。

note：简短通知的理想选择

用于发送简短的自由格式消息，应谨慎使用，通常用于状态更新：

type: note to: architect,QA priority: 70 message: Waiting on QA result before merging cleanup branch.

note消息限制为单行且不超过80字符，确保简洁明了。

辅助脚本：简化协作流程

SwarmForge提供了一系列辅助脚本，处理交接的各个环节：

swarm_handoff.sh：严格的出站协议 gatekeeper

位于swarmforge/scripts/swarm_handoff.sh，负责：

• 验证交接文件字段
• 生成必要的元数据
• 确保提交哈希有效
• 原子性地将文件安装到outbox/

队列管理脚本

• ready_for_next.sh：根据接收模式（task或batch）调度到相应的准备脚本
• done_with_current.sh：完成当前任务并移动文件到completed/
• ready_for_next_task.sh：处理单个任务
• done_with_current_task.sh：完成单个任务
• ready_for_next_batch.sh：处理批量任务
• done_with_current_batch.sh：完成批量任务

这些脚本位于swarmforge/scripts/目录下，共同构成了代理协作的核心工作流。

交接守护进程：协作的隐形协调者

交接守护进程(handoffd)是SwarmForge的核心组件，使用Babashka实现，负责：

• 发现配置的代理和工作区
• 轮询每个代理的outbox/目录
• 将交接文件复制到每个接收者的inbox/new/
• 向每个接收者发送tmux唤醒消息
• 处理发送成功和失败的交接文件

唤醒消息设计为通用形式，避免引导接收者偏向特定文件，确保按队列顺序处理：

You have new handoff mail. If idle, run ready_for_next.sh.

代理队列规则：有序工作的保障

协议规定了代理应遵循的工作循环：

1. 收到通知时运行ready_for_next.sh
2. 根据配置的接收模式处理任务
3. 处理完成后运行done_with_current.sh
4. 任务完成后自动检查并处理下一个任务

这种机制确保代理以有序、可预测的方式协作，即使在系统重启后也能恢复到正确状态。

审计跟踪：透明协作的基础

文件系统状态和交接文件头部共同构成了完整的审计跟踪，关键头部包括：

• id：全局唯一标识符
• from/to：发送者/接收者
• priority：优先级
• type：交接类型
• created_at/enqueued_at/dequeued_at/completed_at：生命周期时间戳

这些信息由不同组件在交接过程中自动添加，提供了完整的可追溯性。

结语：无缝协作的未来

SwarmForge交接协议通过精心设计的文件结构、命名规则、消息类型和辅助工具，为AI代理间的协作提供了坚实基础。这一协议消除了直接tmux访问带来的复杂性，通过文件系统和守护进程实现了可靠、有序、可审计的代理协作。

无论是简单的任务交接还是复杂的批量处理，SwarmForge都能确保AI代理团队像一个协调一致的整体一样工作，大大提高了自动化工作流的可靠性和效率。通过掌握这一协议，用户可以更好地配置和管理自己的AI代理团队，实现更高效的协作。

【免费下载链接】swarm-forgeA simple tool for coordinating several AI agents.项目地址: https://gitcode.com/GitHub_Trending/sw/swarm-forge