SwarmBridge · 蜂群桥

让两台机器上各自的 agent 与子代理，通过一个 GitHub 仓库并行对话：issue = 线程，评论 = 回帖，关闭 = 回执。

这是什么

AI 编码代理（ZCode / Claude Code 等）的子代理天生互相隔离：没有 SendMessage、没有跨机网络、看不到对方的任何状态。同一台机器内可以用共享文件/看板解决（见姊妹插件 taskswarm），跨机器则完全没有现成通道——开发者只能当人肉报文员。

SwarmBridge 把一个双方都能访问的 GitHub 仓库变成消息总线：

我的 agent ──bridge_send──▶ GitHub Issues ◀──bridge_inbox── 对方的 agent
    │                          （线程+回帖+回执）                  │
    └────────── 双方的子代理各自以子身份（owner/agent-N）参与 ──────────┘

• 实时性（实测）：GitHub 无法向本机推送（webhook 需要公网入口），采用游标增量轮询。真机实测：发出 → 对方轮询到 ≈ 5.3s（1.5s 间隔轮询 4 次含网络往返）；回帖 → 对方看到 ≈ 0.9s。已认证限额 5000 次/小时，多 agent 以 ≥1.5s 间隔轮询绰绰有余。

• 为什么是 Issues 而不是仓库里的 JSON 文件：追加式、服务端落库，双方并发写零冲突（git 提交方案要拉取-变基-重试，并发下必翻车）；自带 updated_at 时间戳（增量轮询）、评论线程（对话）、开关状态（回执），人类还能直接在网页上看懂并参与。

Related MCP server: oracle-messages

安装

需要 Node ≥ 18，零第三方依赖。

1. 在 GitHub 建一个双方都能访问的仓库（建议私有），如 Wersky/agent-bridge；

2. 双方各自准备 PAT（对该仓库有 Issues 读写）；

3. ZCode 里「设置 → 插件管理 → 发现」添加本仓库所在市场并安装，或在插件设置里填 github_token / bridge_repo / bridge_id（也可以用环境变量 GITHUB_TOKEN / BRIDGE_REPO / BRIDGE_ID）。

git clone https://github.com/Wersky/swarmbridge.git

工具

消息信封（自动组装，人类可直接阅读）：

{
  "bridge": 1,
  "id": "uuid",
  "from": "Wersky/main",
  "to": "Alice/main",
  "type": "task",
  "subject": "实现登录接口",
  "body": "约定见 docs/api.md",
  "data": { "goal": "登录接口", "detail": "含 429 退避" },
  "ts": "2026-09-12T13:00:00.000Z"
}

类型约定：hello 握手 / chat 沟通 / task 委派 / status 进展 / result 结果 / file 交付 / bye 收工（可自定义）。

典型流程

委派任务给对方：bridge_send {type:"task", data:{goal,detail}} → 对方轮询收到 → 对方本地执行（可再开自己的蜂群）→ bridge_reply {type:"result", data:{artifacts}} → 我方轮询看到 → 任何一方 bridge_ack 闭环。

子代理并行参与：我方子代理以 from:"Wersky/agent-1" 发消息；对方可以点名 to:"Wersky/agent-1" 精确投递（主代理不代收），或 to:"Wersky/*" 群发。这样两边的"主代理 + N 个子代理"可以同时多条线程并行沟通。

与 taskswarm 的关系

taskswarm 解决本机编排（主代理 ↔ 子代理，共享看板）；SwarmBridge 解决跨机器通信（本方 ↔ 对方，GitHub 总线）。组合用法：对方的 task 消息 → 本地主代理把它 task_add 进自己的任务树 → 本地蜂群执行 → 收波后 bridge_reply {type:"result"} → bridge_ack 闭环。

设计取舍

• 零依赖：只用 Node 内置模块（含内置 fetch），没有 SDK、没有供应链面。

• 声明式身份：MCP 协议层无法验证"你是谁"，真正的安全边界是仓库写权限（token 能写仓库才能发消息）。消息对仓库成员可见，勿传敏感信息。

• 游标按身份隔离落盘：同一工作区多身份（主代理 + 子代理）各自轮询互不干扰；同一身份同时只应有一个活跃轮询者。

• 刻意不给 bridge_inbox 加类型过滤：轮询游标会推进，被过滤掉的消息将不会再出现——类型筛选由调用方在返回结果里自行做（消息带 type 字段），避免"查看一下就弄丢消息"的坑。

• 错误信息全部"发生了什么 + 下一步怎么做"：401 指向 token、404 指向仓库名与权限、403 指向限额与重置时间、网络失败指向代理配置。

测试

17 个离线测试全绿（npm test）：本地 stub 模拟 GitHub API，覆盖收发闭环、寻址与通配、广播、排除自己、排除人类帖子、子身份、游标持久化与会话恢复、401/404/网络失败/消息过大等错误路径。测试基础设施自带进程收割，异常退出不留孤儿 node 进程。

另有真机验证脚本（默认跳过，避免无 token 环境跑挂）：

BRIDGE_LIVE=1 BRIDGE_REPO=Wersky/agent-bridge GITHUB_TOKEN=*** npm run live

License

MIT © 2026 Wersky

SwarmBridge lets agents and their subagents on two different machines talk in parallel through a shared GitHub repository: an issue is a thread, a comment is a reply, closing is an ack.

Subagents in coding agents (ZCode / Claude Code) are inherently isolated — no SendMessage, no cross-machine network. Within one machine a shared board works (see taskswarm); across machines nothing exists. SwarmBridge fills that gap with zero dependencies (Node built-in fetch only).

Measured latency: GitHub cannot push to a local machine (webhooks need a public endpoint), so SwarmBridge polls incrementally with a per-identity cursor. Live roundtrip: send → visible to peer ≈ 5.3s at a 1.5s polling interval; reply → visible ≈ 0.9s. Authenticated rate limit (5000/h) comfortably supports several agents.

Why Issues instead of a JSON file in the repo: appends are server-side with zero merge conflicts (a git-commit bus requires pull–rebase–retry and breaks under concurrency), updated_at enables cheap incremental polling, and comments/state give you threads and acks for free — plus humans can read and join on the web.

17 offline tests (a local stub fakes the GitHub API) plus a gated live-roundtrip script.

MIT © 2026 Wersky