两个 JSON 文件和一个日志,撑起 Antigravity 的 /swarm
Chasen 翻完源码发现,Antigravity /swarm 的共享黑板只有三个纯文本文件。他拆解了这套极简架构如何做到零空转、防死锁,以及真实任务中 7 个 Agent 是怎么接力跑完的。
Antigravity 的 /swarm,被很多人当成一个复杂系统。Chasen 翻完源码后说,撑起那块共享黑板的,就两个 JSON 文件和一个 JSONL 日志。
他在 X 上发了一篇万字拆解,从自己修一个 PDF 导出工具的经历讲起。当时问题是页面显示正常,复制和 OCR 却乱码、缺字、顺序颠倒。单个 Agent 处理这种跨模块排查,上下文很快塞满。他用 /swarm 拆成两波 7 个成员跑,2 小时 7 分钟,黑板上留下 24 条帖子。跑完之后他好奇底层实现,直接翻了内置插件 swarm_board 的源码。
三个文件就是全部
打开本地目录 <appData>/brain/<coordinatorConv>/.system_generated/swarm/,整场 Swarm 的共享状态只有三个纯文本文件:
board.jsonl:只追加的日志,一行一条帖子,带全局递增的 seq、发帖人 agent、正文 text 和时间 timemembers.json:花名册,记录每个成员的会话 ID、角色、模型、工作区模式,以及四个跟踪进度的楼层游标swarm.json:门牌锚点,记录版本号、后端类型和 swarm_id
board.jsonl 里的一行长这样:
{"seq":5,"agent":"template-dom","text":"HTML 模板排查结果如下,请 @verifier 交叉核验...","time":"2026-11-14 13:21:59"}
Chasen 在源码里挖出两个工程设计。第一,多频道不用配置表,频道创建、订阅、退订、归档全部作为 control 消息写进同一条 board.jsonl。侧边栏要算某个成员当时能不能看见某条帖子,靠重放日志里的 control 帧,members.json 里的频道列表只是缓存。第二,源码已经埋好跨机器分布式 Swarm 的协议:swarm.json 指向远端后端时,侧边栏会拉起 swarm --json --watch 订阅 NDJSON 增量流,成员挂 <identity>@<host> 归属徽章。增量楼层对不上就杀掉 watcher 重新拉全量快照。本地三个纯文本文件跑轻量,将来切多机云端协同,上层协议不用改。
零空转,但一条消息不漏
多 Agent 系统最怕轮询烧 Token。Antigravity Swarm 的做法是直接砍掉轮询。
成员交完活,调一句 swarm_wait{since: N}。返回 DONE 后,底层的 wait-check hook 直接结束这个成员这一轮的模型回合,会话彻底挂起,0 Token 待机。默认按 mentions_only 休眠,只有被 @name、@all 或 @#channel 点名时,系统才往对话里塞一条唤醒消息。
这里有个经典竞态漏洞。成员读完 #10,调 swarm_wait(since: 10) 准备休眠,结果这期间黑板上落了 #11。直接睡过去就漏了。Chasen 在自己的日志里抓到过这个场景:第 65 步巡检员刚调完 swarm_wait,#11 落地;第 67 步运行时把休眠请求拦下来,注入一行提示:
Stop hook blocked termination: [board] new messages arrived; read_board before waiting again
同时 last_park_blocked_seq 被更新成 11。他把这比作地铁出站闸机:你刷卡准备下班,系统发现新工单进来,直接锁住闸机,逼你先看完新帖再决定睡不睡。
还有一个细节:判断成员是在干活还是睡觉,不信任 members.json 里的 wake_mode。因为成员可能被后台命令或用户手动消息叫醒,登记簿还没更新。侧边栏直接去解析每个成员自己会话的 transcript.jsonl 尾部,看到最后停在无工具调用的回复、或包含 swarm_wait 且返回 DONE 的工具批次,才判成 waiting,否则一律算 working。
members.json 里那四个游标分别是:last_read_seq 记录实际读到的楼层,wait_since 记录从哪楼开始等唤醒,last_nudged_seq 记录催读提醒推到了哪楼,last_park_blocked_seq 记录最近一次想休眠却被 Stop Hook 拦下的楼层。
24 帖的实战复盘
那场 PDF 排查任务分两波。
第一波只读排查(#1~#8,约 32 分钟),4 个人:pdf-pipeline 查导出脚本,template-dom 查模板,verifier 做实测复现,后台挂 monitor 防死锁。全员共用主工作区,因为只读不改文件。verifier 用 Playwright 双环境渲染 6 套模板,再用 pypdf 复现乱码,在 #7 把完整证据交给 coordinator。#8 发 [done],Coordinator 把 4 个人全部 kill 清场。
第二波并行修复与回归(#9~#24,约 1.5 小时):fixer-templates、fixer-code、verifier-fix、monitor-2。这里有一个规范细节:被 kill 的成员名字永久锁死,所以新巡检员只能叫 monitor-2。
决定没翻车的是三次插曲。
第一次,#13~#14。fixer-code 发现工作区部分目录被移走,发帖 @coordinator。Coordinator 从 git 恢复目录后,在 #14 一次性通知所有人按根目录路径改。
第二次,#15~#19。fixer-templates 沉默 38 分钟,monitor-2 在 #15 发帖精准催醒。fixer-code 在 #16 交完代码后 3 分钟 Coordinator 还没读,monitor-2 又在 #17 发 @coordinator [stall],甚至判断“旗舰模型可能额度耗尽”。Coordinator 被叫醒后查 git status,确认改动已落地,推动全组进入联调。
第三次,#21~#23。verifier-fix 用 6 套模板跑真机联调,抓出校验脚本在中英混排字体切换处误报。它没有回找 Coordinator 传话,直接在 #21 点名 @fixer-code 贴出报错行号打回。9 分钟后 fixer-code 在 #22 修完并补单测,全量测试通过后 #23 汇总交卷,#24 Coordinator 发 [done] 收官。
他说,如果最后汇总只写一句“全部已验证”,他不敢直接合并代码。先切 Graph 看哪轮打回返工、谁跟谁交过手,再回 Board 点进 #21 #22 #23 核对原始测试输出,哪一步糊弄了一目了然。
防失控的设计
Chasen 列出了几道护栏。
公开 Brief 当唯一账本。每次 swarm add 建人,派活书以 @name
跨角色交接用 #seq 引用楼层,禁止复制粘贴转述。@name 只当门铃,不当抄送。每次 @ 都会触发对方一整轮模型推理,所以同伴交接直接互点,不无脑抄送 Coordinator。
读写分离。官方建议每 2~4 个作者配 1 个只查不改的 verifier。并发改代码时,作者开 share 或 branch 隔离工作副本。注意 kill 成员会连带删掉它的独立工作区,动手前先把改动合并回来。
热克隆 fork。某个成员已经摸清半个代码库需要兵分两路时,加人带 fork 参数,值填成员名,直接克隆对话历史。Worker 自己也能调 swarm add 招帮手,但只能 kill 自己招的人。
死锁兜底是 monitor。它本身也是一个独立 Agent,挂 */3 * * * * 后台闹钟,每 3 分钟检查 5 种卡死:结果没 @ 任何人、Coordinator 留了未读帖、被 @ 却迟迟没发帖、成员环状互等、全员空等。同一个死锁最多提醒 3 次。如果连续 5 轮黑板没动静或 Coordinator 发了 [done],它会停掉闹钟,切到零耗电休眠,等新消息再自动复活。
额度耗尽可以原地热切模型。members.json 把 desired_model 和 applied_model 拆成两个字段,成员额度耗尽后不用 kill 重来,等它回到 waiting,调 swarm 并指定 action 为 model,换一个还有额度的模型,对话记忆全部保留。
还有一个真实边界。在 11 月 13 日那场写稿任务里,写作 Worker 想调生图工具,发现 Swarm Worker 会话默认没有
砍掉常驻 narrator
翻源码时最意外的是谷歌对“战情看板”的一次转向。初代设计里,Swarm 会配一个常驻 narrator 解说员,盯着黑板每条帖子,把聊天记录整理成 view.json,甚至允许 AI 写 view.html 定制页面。因为 view.html 是模型生成的不可信代码,谷歌焊了一整套零信任沙箱:硬限 64 KB、逐条核对引用、iframe 断网 CSP、跳转请求要过四道门禁。
但最新版 SKILL.md 开头直接写:Don't add a narrator; this Overview replaces it. 别再加 narrator 了,新版内置 Overview 已经把它替掉了。官方在示例 JSON 里也写得很诚实:Always-on member adds token cost。黑板每蹦一条消息就叫醒一个大模型重写一遍 JSON 摘要,Token 烧得太肉疼,而且更新永远慢黑板半拍。
新方案克制得多。Coordinator 只写一份几十行的静态 plan.json,UI 侧用确定性前端代码把 board.jsonl 和成员 transcript 拼成动态看板。前端改动时,Worker 按 Screenshot: <路径> | <改动说明> 格式发帖,看板还能自动拼出可拖拽的前后对比进度条。
他的结论:能靠静态协议加确定性代码算出来的视图,绝不多养一个常驻 LLM 去盯。
什么时候开 /swarm
他说自己只看两个条件:能不能拆出至少两条互不打架的独立线?拆完的结果值不值得让第三个人拿真实样本交叉复核?
跨模块排障、多文件并行改造加回归测试、需要反复打回返工的工程任务,共享黑板能把上下文隔离和过程溯源做得干净。但单线明确的小改动,或者两个人上来就得抢着改同一个核心函数的活,直接交给单个 Agent 更快。多开一个成员就多一份完整会话和推理消耗。建人时如果省略 model,默认全员沿用主会话模型,主会话开着高配模型直接盲冲,额度掉得会非常快。
发布时间: 2026-11-23 06:10