Skip to content

一块黑板撑起 Agent 蜂群:Antigravity /swarm 的协调底座 ​

一句话定义:多 Agent 协作不一定需要一套调度服务。一块只追加的黑板、每人一组楼层游标,再加一个阻止"刚闭眼就漏消息"的停止钩子,就能让一群 Agent 零空转地接力干活。


问题:主 Agent 变成了传话筒 ​

跨模块的活最容易把单个 Agent 撑爆。一个 PDF 导出工具的乱码问题,要读完打印脚本、6 套模板和 CSS 规范,再跑真机测试,上下文很快塞满。

换成传统 Subagent 也有代价:拆给两个人查、一个人验,主 Agent 得先把几千字排查日志读一遍,再转述给验证员。协调者成了带宽瓶颈——它不干活,却要为每一条信息付一次上下文。

Antigravity 的 /swarm 走的是另一条路:把黑板直接交给所有成员,谁都不必经过主 Agent 转述。

四种模式,差别在"结果交给谁" ​

同一个 PDF 乱码问题,四种入口解决的是不同形状的活:

模式适合的活结果交给谁
invoke_subagent只确认一个疑点,主 Agent 继续查别处子代理把证据发回主 Agent
/boost一个难复现的 bug,要围绕同一问题多跑几轮每轮挑前一轮的漏洞,编排器独立复核
/teamwork整套链路分阶段重做,按里程碑推进独立角色审核阶段成果
/swarm多条线可分头查,但验收要拿同一份样本交叉复核直接贴到共享黑板,点名交接

/teamwork 和 /swarm 的分界很实际:前者是阶段串行,后者是并行排查 + 统一验收。需要"两个人各自查、第三个人拿两边证据复测"时,串行的里程碑结构反而会拖慢。

底座:三个纯文本文件 ​

一整场 Swarm 的共享状态,落在 <appData>/brain/<coordinatorConv>/.system_generated/swarm/ 下的三个文件里:

文件作用内容
board.jsonl只追加的公告栏每行一条帖子:全局递增楼层 seq、发帖人 agent、正文 text、时间 time
members.json花名册 + 阅读签到表会话 ID、角色、模型、工作区模式,以及四个楼层游标
swarm.json门牌锚点版本号、后端类型(本地为 local)、swarm_id

简化后的真实结构大致是这样:

json
// board.jsonl —— 每行一条追加记录
{"seq":5,"agent":"template-dom","text":"HTML 模板排查结果如下,请 @verifier 交叉核验...","time":"2026-11-14 13:21:59"}
{"seq":7,"agent":"verifier","text":"@coordinator 已完成全部实测核验(基于 #5 与 #6)...","time":"2026-11-14 13:43:55"}

// members.json —— 单个成员的状态节选
"fixer-templates": {
  "role": "worker",
  "desired_state": "RUNNING",
  "phase": "RUNNING",
  "desired_model": "flagship-model",
  "applied_model": "flagship-model",
  "workspace_mode": "inherit",
  "wake_mode": "working",
  "wait_since": 20,
  "last_read_seq": 20,
  "last_nudged_seq": 20,
  "last_park_blocked_seq": 16,
  "killed": false
}

这套设计的价值不在"简单",而在可检查:任何时候都能用文本工具打开看现场,出问题能逐行回放,不需要连数据库、翻服务日志。

频道不是配置表,是日志里的事件 ​

成员超过 8 个、模块一多,黑板可以拆成 #parser、#ui 这样的频道,成员默认只看 main 和自己订阅的频道。

但频道的创建、订阅、退订、归档没有单独的配置表——它们作为 control 控制消息,写进同一条 board.jsonl。要算"某个成员在历史某条帖子发出时能不能看见",靠重放日志里的 control 帧(channelsAt() / activeAt());members.json 里的频道列表只是缓存。

同一套日志还能直接支撑跨机器:源码里已经埋了 remote_board 协议——swarm.json 指向远端后端时,面板用 swarm --json --watch 订阅 NDJSON 增量流,给成员挂 <identity>@<host> 的归属徽章;一旦增量楼层接不上本地最新楼层,就杀掉旧 watcher、拉全量快照重同步。本地三个文件,将来切多机,上层协议不用改。

零空转,还不漏消息 ​

多 Agent 系统最容易把账单跑炸的地方是轮询:每隔几秒醒来问一句"有新活没",模型空转,token 哗哗掉。/swarm 把轮询整个砍掉,靠三层配合。

一、把"等待"做成一个结束回合的工具 ​

成员交完活,调用 swarm_wait{since: N}。这条工具结果返回 DONE 时,底层的 wait-check hook 直接结束该成员这一轮的模型回合——会话挂起,没有死循环,没有心跳推理,真正 0 token 待机。

默认是 mentions_only:只有别人发帖点到你的名字(@name)、全员广播(@all)、或点到你所在的频道(@#channel),系统才往你的对话里塞一条唤醒消息。

二、停止钩子拦住"刚闭眼、新帖到了" ​

这里有一个经典竞态:成员读完 #10,判断没事可做,调 swarm_wait(since: 10) 准备休眠;就在这一两秒里,黑板上落了 #11。如果直接睡着,这条消息就漏了。

运行时的做法是在下一次模型请求前再检查一次黑板。作者的运行日志里抓到了现场:第 65 步刚调完 swarm_wait,#11 落地;第 67 步休眠请求被硬拦下来,并往会话里注入一行提示:

text
Stop hook blocked termination: [board] new messages arrived; read_board before waiting again

同时把花名册里的 last_park_blocked_seq 更新成 11。可以把它想成地铁闸机:你刚刷卡准备出站,系统发现新工单进来了,先锁住闸机,逼你回板上看完再决定睡不睡。

三、判活看执行痕迹,不信登记簿 ​

members.json 里虽然记着 wake_mode(mentions / anything / working),但判断成员到底在干活还是在睡觉,不能只看这个字段。原因很现实:一个睡在黑板上的成员,可能被后台命令回调或用户手动发消息叫醒了,这时登记簿里仍写着 mentions,人其实已经在跑工具。

所以侧边栏直接解析每个成员自己会话的 transcript.jsonl 尾部:最后停在无工具调用的回复,或者包含 swarm_wait 且返回 DONE 的工具批次,才判成 waiting,否则一律算 working。顺带还能从最新的思考块和工具调用里抽出"正在读哪个文件、跑哪条命令",实时推到面板。

这也解释了四个楼层游标各管什么:

游标含义
last_read_seq实际读到哪一楼。调 swarm_wait 必须传自己真正看过的号,不能传黑板最新楼层,否则忙活期间冒出来的帖子会被跳过
wait_since从哪一楼开始等唤醒
last_nudged_seq系统注入 "[board] the latest message is #N" 增量催读提醒推到了哪一楼
last_park_blocked_seq最近一次想休眠却被停止钩子拦住的楼层号

一场真实运行:24 帖、两波、7 个成员 ​

PDF 乱码那场任务跑了 2 小时 7 分钟,分两波、共 7 个干活成员,黑板上留下 24 条帖子。

模型先混搭:Coordinator 和巡检员只负责拆任务、盯状态、发提醒,配轻量模型省额度;真正查链路、改 6 套模板、写测试跑验收的,全员旗舰推理模型。

第一波只读排查(#1~#8,约 32 分钟):pdf-pipeline 查导出脚本与字形映射,template-dom 查模板的 DOM 文本流与打印样式,verifier 只做实测复现与交叉核验,后台再挂一个 monitor 防死锁。因为这一波只读不改文件,全员共用主工作区(inherit)。9 分钟后 template-dom 交出 #5,15 分钟后 pdf-pipeline 交出 #6;verifier 顺着 #5、#6 用 Playwright 在在线与断网双环境渲染 6 套模板,再用 pypdf 实测复现,在 #7 把证据交给 @coordinator,#8 结案后全员被 kill 清场,避免旧上下文拖累后面的修改。

第二波并行修复与回归(#9~#24,约 1.5 小时):新开 fixer-templates(只动模板与样式)、fixer-code(只动打印链路与校验脚本)、verifier-fix(只查不改)和 monitor-2。被 kill 的成员名字永久锁死,新巡检员只能顺延叫 monitor-2。

真正决定这场任务没翻车的是中间三次插曲:

  1. #13~#14 同步边界:fixer-code 上手发现工作区部分目录被移走,测试路径全对不上,立刻发帖 @coordinator;Coordinator 从 git 恢复目录后,在 #14 一次性通知三个人统一按根目录路径改。
  2. #15~#19 巡检员两次抓死锁:#14 之后过了 38 分钟 fixer-templates 一直没发帖,monitor-2 在 #15 精准催醒;fixer-code 在 #16 交完代码、Coordinator 3 分钟没读,monitor-2 又在 #17 点名协调者,还顺带判断"旗舰模型可能额度耗尽,或者大家在等 fixer-templates"。
  3. #21~#23 验收员点对点打回:verifier-fix 拿 6 套模板跑真机联调时发现,校验脚本在中英混排的字体切换处会因为多出伪空格误报失败。它没有回找 Coordinator 传话,直接在 #21 点名 @fixer-code 贴出错行打回;9 分钟后修完补单测,全量复跑通过,#23 交卷。

Graph 加 Board 的组合是这套系统最实用的部分:先看拓扑图确认哪一轮发生了打回返工、谁跟谁交过手,再回 Board 点进 #21、#22、#23 核对原始测试输出。只写一句"全部已验证"的汇总,是不敢直接合并的。

五道护栏与两个兜底 ​

长线多 Agent 最怕三件事:上下文雪球越滚越大、半路卡死或额度爆掉、两个人抢改同一个文件。

五道防膨胀护栏:

  • 公开 Brief 当唯一账本:每次建人都把派活书以 @name <brief> 贴到黑板。验收员随时能对照原始要求验货;Coordinator 即使上下文被压缩,回头翻黑板也不丢分工。
  • 新成员跳过开局噪音:启动时只把自己的 Brief 塞进第一条消息,黑板游标直接设在所有 Brief 之后,省得一睁眼先吃掉别人几千字任务书。
  • #seq 引用,@ 只当门铃:规范严禁把 A 的报告复制转述给 B,全部用 #5、#6 引用楼层;每次 @ 都会触发对方一整轮推理,所以交接直接互点,不无脑抄送 Coordinator。批量分片时 add 传 tasks / n 一次拉出 worker-1..N,@worker 呼全组、@worker-1 呼单人;多频道用 @#parser 精准唤醒一个模块组,@#main 会被拒绝,防变相 @all。
  • 读写分离 + 工作副本隔离:每 2~4 个作者配 1 个只查不改的 verifier,验货的人只报错、作者自己修。只读排查用 inherit 省资源;并发改代码时给作者开 share(共享底层对象的独立工作副本,类似 git worktree)或 branch(完整克隆)。kill 成员会连带删掉它的独立工作区,清理前必须先把改动合并或 cherry-pick 回来。
  • 热克隆 fork 与受限招人:成员已摸清半个代码库、要兵分两路时,加人带 fork: "<member>" 直接克隆对话历史,不用冷启动重读仓库。Worker 自己也能招帮手,但只能 kill 自己招的人;Coordinator kill 一个 Worker 时不会顺手清理它招的帮手,收尾要自己留意。

两个保命兜底:

  • 巡检员自己也会休眠。monitor 是独立 Agent,挂着 IsDaemon 的三分钟定时闹钟(IsDaemon 是为了不让定时器把主对话一直标成运行中),每 3 分钟检查 5 种卡死:结果没 @ 任何人、Coordinator 留了未读帖、被 @ 却迟迟没发帖、成员环状互等、全员空等。判断"被 @ 却没动静"看的是 last_post_seq 而不是 wait_since——一次失败的模型回合也会推进 wait_since,只有发帖号能揪出静默挂掉的人。同一死锁最多提醒 3 次;连续 5 轮(约 15 分钟)黑板没动静,或收到 [done],它就自己停掉闹钟、切到 swarm_wait(mentions_only: false) 零耗电休眠,等新消息再重建。
  • 额度耗尽原地热切模型。members.json 刻意把 desired_model 和 applied_model 分开:成员额度耗尽后不用 kill 重来,等它回到 waiting,调 swarm{action:"model"} 换一个还有额度的模型,保留全部对话记忆接着干;事前还能用 swarm{action:"models"} 查剩余额度和重置时间。

撞到的一堵墙:Worker 没有子代理权限 ​

在一场用 Swarm 写初稿的任务里,让写作 Worker 顺手调生图工具配两张信息图,它查完工具列表直接报阻塞:Swarm Worker 会话默认没有 <subagents> 权限,既调不了 image-generator 也调不了浏览器子代理,只能发帖让 Coordinator 代调,生完图再交还。

需要穿插生图或浏览器自动化时,这一步得留给 Coordinator 统筹,别指望 Worker 自己调通。

源码里的转向:砍掉常驻解说员 ​

初代设计里有一个常驻角色 narrator:用 swarm_wait(mentions_only: false) 盯住每条帖子,把零散聊天整理成按目标分组的 view.json,甚至允许 AI 自己写 view.html 渲染到 Overview 面板。

因为 view.html 是模型生成的不可信代码,安全工程做得极重:view.json / view.html 硬限 64 KB,超限或 JSON 写坏直接退回上一版;sanitizeView 逐条核对引用,楼层号超过最新 head 标 ⚠ unverified,没标出处标 uncited,文件跳转只放行 brain/ 下的真实常规文件,外链走白名单;页面跑在 sandbox="allow-scripts"、全断网 CSP 的 iframe 里,跳转请求要通过四道门禁——浏览器激活态、iframe 持有焦点、父页面 5.5 秒内无输入、延迟 100 毫秒复核,外加 250 毫秒节流。

结果最新版 swarm_pane/SKILL.md 开头只有一句:

Don't add a narrator; this Overview replaces it.

官方在示例 JSON 里写得更直白:Always-on member adds token cost。黑板每蹦一条消息就叫醒一个大模型重写摘要,token 烧得肉疼,更新还永远慢黑板半拍。

替代方案克制得多:Coordinator 只在开工和改分工时写一份几十行的静态 plan.json(目标、线程分组、各人任务名),UI 侧的 hive.js 用确定性前端代码把 board.jsonl、成员 transcript.jsonl 里的实时工具步骤和 [done] 标记拼成动态看板。如果是前端改动,Worker 按 Screenshot: <路径> | <改动说明> 发帖,看板还能自动拼出可拖拽的前后对比进度条。

这条转向和 Always-on Agent 的判断是同一个方向:能靠静态协议加确定性代码算出来的视图,绝不多养一个常驻 LLM 去盯。

什么时候值得开 Swarm ​

只看两个条件:

  1. 任务能不能拆出至少两条互不打架的独立线?
  2. 拆完的结果,值不值得让第三个人拿真实样本交叉复核?

跨模块排障、多文件并行改造加回归、需要反复打回返工的工程任务,共享黑板能把上下文隔离和过程溯源做得很干净。

反过来的情况同样明确:单线明确的小改动,或者两个人上来就得抢着改同一个核心函数,交给单个 Agent 更快。

成本边界也要心里有数:多开一个成员就多一份完整会话和推理消耗;建人时如果省略 model,默认全员沿用主会话的模型——主会话开着高配模型直接盲冲,额度掉得会非常快。

边界 ​

  • 这是对内置插件源码与 6 场真实运行日志的拆解,不是官方文档;字段名与默认值随后续版本变化。
  • 样本量小:24 帖、7 个成员、一场 2 小时的任务,够说明机制,不足以证明收益。
  • 三个文件是本地后端的形态;跨机器协议已经写进源码,但公开材料没有给出多机运行的实测数据。
  • 大量行为依赖运行时规范(谁该 @ 谁、什么时候 kill),换成别的产品不能照搬。

参考资料 ​

关联词条 ​