自组织智能体集群 Hercules-debug/dsh-flock

dsh-flock

为 DeepSeek Harness 打造的自组织多智能体集群：N 个真实 DSH 智能体通过共享的追加式日志协同，没有编排器。

你只写一个方向文件。没人分配任务，没人声明角色，没人构建依赖图。智能体自己决定做什么，在彼此的产出上继续构建、互相批评，最后全部进入空闲状态，自然收敛。

两种协同模式 —— 用黑板

插件自带两种。先用 board_run；只有当你明确想要固定的对等集合和自动收敛规则时，才去用 flock_run。

两者的区别只有一点：谁来决定智能体了解同伴的哪些信息。

| | board_run —— 黑板 （推荐） | flock_run —— 快照集群 |
| 提示词里包含什么 | 什么都不包含 —— 只有一个路径和一句 shell 惯用法 | harness 读取每个邻居的最后一行日志，直接写进去 |
| 智能体何时读取同伴 | 想读就读，想读几次读几次 | 唤醒时读一次；视图永不刷新 |
| 拓扑 | 没有 —— 就是一份日志，grep 就是过滤器 | 环形 / 网状 / 蜂群，由你选 |
| 谁决定停止 | 智能体自己，而且它只会被派发一次 | harness，靠 idle 握手 |
| 轮次 | 没有 | 反复进行，直到所有可见智能体都报告空闲 |

为什么黑板是更好的默认选择。 智能体就是一次函数调用，所以「读读同伴做了什么」也应该是它随时能发起的调用 —— 而不是别人递给它一次、然后就冻结的快照。实践中，快照模式的收敛规则也正是它的弱点：它依赖智能体主动报告自己空闲，而我们测过的每一次运行里它们都没报，集群只能手动停掉。黑板没有这种需要满足的规则。

什么时候用快照模式：你想要一个有界、可预测的对等集合（无定形的环形会给每个智能体切出固定的一片集群，所以 N 增长时每个智能体的上下文保持不变），并且乐意让 harness 决定工作何时完成。它也更接近 AWS 原版的移植，正因如此，针对上游的差分测试才有意义。

试一试

board_run(
direction: "Survey the failure modes of log-based agent coordination.",
agents: 4
)

然后用 board_status(board: "...") 读它们写了什么。

这是 aws-samples/sample-kiro-flock 的移植版。AWS 原版在 EC2 上跑无头 Kiro CLI 会话，对接 S3 存储桶；这里智能体是 DSH 子代理，协同平面是一个目录。黑板模式是偏离原版的地方：AWS 的协同方式是让每个智能体定时读取邻居的日志，这行得通，因为它们的智能体是廉价的短命 CLI 调用。DSH 智能体一跑就是几分钟，同样的设计产出的快照在智能体行动时已经过期，收敛规则也从未触发。这个移植版本新增的，是给智能体自己的读写工具。

EC2 instances + S3 bucket -> DSH subagents + a directory
headless Kiro CLI session -> ctx.subagents.startContinuable()
timer-driven neighbour read -> agent-driven blackboard read/write
systemd reap -> one dispatch per agent

为什么用子代理，而不是调用模型

这个移植版本的早期实现，调用的是一个裸 /chat/completions 端点。每个智能体只有一轮模型交互，没有工具，所以它只能叙述自己从未做过的工作：它会记录 Wrote environment/foo.md，而 environment/ 里却空空如也。黑板上有消息，没有内容。

通过 ctx.subagents.startContinuable() 派发，从根上解决了这个问题。每个智能体都是真正的 DSH 子智能体，拥有宿主的完整工具集、自己的会话、自己的系统提示词。它自己写产物，而且因为它有 bash，它能运行自己写的东西并修好它。产物是真的；产出的脚本是执行过的，不只是描述过。

循环从不会替智能体编造日志行。它检查磁盘，看实际出现了什么——所以「智能体什么都没产出」是可观察的结果，而不是无法验证的说法。

安装

dsh plugin --profile <name> add /path/to/dsh-flock
then restart the profile's harness process and refresh the browser

bundle 补丁（cordis.patch.yml）把插件挂载到配置档的宿主组合里。它向共享工具注册表注册六个工具，并向全局系统提示词注册一个用法段落。

使用

该配置档里的任何会话都能用自然语言启动集群（「启动一个 4 个智能体的看板来审查这个代码库」），也可以直接调用工具。

| 工具 | 用途 |
| board_run | 启动黑板集群。 智能体拿到日志路径，自己决定何时读、何时写。 |
| board_status | 读取看板：条目数、主题、作者、最近条目、文件。 |
| board_direct | 替换看板的方向，或暂停/停止它。 |
| flock_run | 从一个方向启动快照集群。阻塞直到收敛或到达截止时间。 |
| flock_status | 查看集群：状态、每个智能体最后一行日志、磁盘上的产物。 |
| flock_direct | 操控运行中的集群：切换算法、重写方向、暂停/停止。 |

board_run(
direction: "Survey the failure modes of log-based agent coordination.",
agents: 4
)

direction 说明的是要达成什么，而不是怎么拆解——拆解由智能体自己决定，替它规定就失去了意义。

什么时候用。 工作能拆成许多近乎独立的贡献，而且智能体比你更清楚该做什么、什么时候该沟通。

什么时候不用。 任务树已知且顺序严格，或者步骤之间需要验证关卡——那种情况用普通委派更好。两个工具描述里已经写明了这一点，所以模型不会把这个模式用过头。

有一个坑，值得先说清楚。 Board 智能体没有唤醒通道：派发一次，干完就结束。在这次派发里，它们想读多少次、写多少次 board 都行，但派发一结束，就真的结束了。prompts/board/board-loop.md 把这一点讲得很直白，并要求它们把没做完的事留在 board 上，别指望还有下一轮。这样能跑通，但一个长任务，拆到两块 board 上，比硬塞进一次派发里指望它做完要好。

三种算法

每一轮迭代都从同一个问题开始——我该读谁的工作？——答案就是协调算法。三种算法全部从 AWS 的 neighbourSelector.ts 逐字移植。

| 算法 | 每个智能体读什么 | 优势 | 上限 |
| amorphous | 环形邻居里一个固定窗口（radius） | N 增长时每个智能体的开销恒定；多样性保得住，因为每个人只看到自己那一小片 | 信号每轮迭代只走一跳，所以收敛慢 |
| mesh | 所有人 | 对齐快 | 多样性会塌缩到第一个信号上；到约 30 个智能体还算舒服 |
| swarm | 最近活跃的 K 个同伴 | 跟着能量走；能扩到 100 以上 | 如果 N 在涨而 K 一直很小，智能体会全挤到同一个子任务上 |

高效的顺序是三种都用上：先用 amorphous 打开局面做探索，方向成形后切到 swarm，最后用 mesh 收尾对齐。flock_direct 能在跑着的集群上切换拓扑（迭代之间热重载）。

AWS 那篇文章里的收敛算术：在环上，一轮迭代把信号推进 2R 个位置，所以传播需要 ceil(N / 2R) 轮，达成共识大约是这个数的两到三倍。

失效模式与对应的控制手段

AWS 那篇文章点了四种；在这里每一种都是一个设计选择，而不是事后补上的防护。

| 失效模式 | 来源 | 控制手段 |
| 群体思维 | mesh 的可见性塌缩到第一个信号上 | 用 amorphous 开局；只在需要对齐时才切到 mesh |
| 漂移 | 会话历史一直留着，会积累行为惯性 | 每轮迭代都换新的子智能体；状态只活在日志里 |
| 热点 | swarm 的 K 太小，子任务会饿死 | 调大 K，或者切回 amorphous |
| 残留 | 过期文件被当成当前上下文读进来 | 每次启动都把 environment/ 归档到 history/ |

漂移这条值得多说一句。每个智能体回合都是一个全新的子智能体，对上一回合毫无记忆——在这里，这是 spawn 语义自然带来的结果，不是模拟出来的。听起来很浪费；但正是这个控制手段，让上千个独立循环还能被驾驭。

协调不是 send_message

子代理的消息通道只限于直接的父子链（kind: "ancestor"），表达不了「读我的环形邻居」这件事。所以智能体的协调方式和 AWS 原版一样——通过磁盘上的共享日志，这个与拓扑无关。这也是 AWS 版本用 bucket 而不是消息总线的同一个原因，也正是它让 ring 和 swarm 拓扑得以表达。

Blackboard 模式：并发写入如何做到安全

多个智能体往同一个文件追加，没有锁、没有 CAS、没有事务。这能成立，是因为冲突在设计上就被消除，而不是靠仲裁：

1. 只追加。 条目永不编辑、永不删除，所以两个写入者不可能互相覆盖。历史就是状态。
2. 一行一次写入。 O_APPEND 让单次 write 在本地文件系统上成为原子操作。把一行拆成两次写入，就会和并发写入者的内容交错。
3. 容忍撕裂读。 读取者可能读到写到一半的行。解析失败的行直接跳过，绝不致命——下一次读就能看到完整的它。

规则 2 是承重结构，测试套件测量它，而不是断言它：

| 负载 | 结果 |
| 8 个写入者 × 200 行，一行一次写入 | 1600 条条目，0 条损坏 |
| 6 个写入者 × 50 行，每行拆成两次写入 | 300 条中 187 条损坏 |

失败的那个用例被保留为测试，这样规则就不会悄悄烂掉。

这在本地文件系统上成立。 O_APPEND 在 NFS/SMB 上并不可靠地原子，而 S3 这类对象存储根本没有 append——这正是 AWS 原版改成每个智能体写一个对象的原因。

因为 harness 不会往 board 智能体的提示词里推任何东西，写入协议必须以指令形式送到智能体手上。prompts/board/board-loop.md 给了它一份可直接复制的模板，把正文走一遍 json.dumps，这样引号、换行和反斜杠都不会破坏这一行；还给了那条真正要紧的规则：把条目读回来，确认它是你的，因为 >> 会在运行命令之前就创建重定向目标，所以一次失败的写入看起来是成功的。

仓库结构

lib/index.js plugin entry: registers flock_run / flock_status / flock_direct
cordis.patch.yml bundle patch that mounts the plugin into a profile
src/
store.js shared environment: append-only logs, direction, state, config
neighbours.js the three algorithms + clampRadius guard
agent.js the loop: read logs -> dispatch an agent -> read back from disk
subagent-runner.js ctx.subagents dispatch, persona, settling, artifact inspection
cluster.js launcher, concurrency limiting, snapshots
ids.js cluster-name sanitisation (a name becomes a directory)
prompts/ loop instructions + per-algorithm fragments
test/ smoke, plugin-load, subagent-dispatch, diff/

集群状态位于 <workspace>/.flock/<clusterId>/ 下：

direction.md the goal, written once by the operator
config.json algorithm / radius / swarmK (hot-reloaded)
store/state.json starting | running | paused | stopped
store/agent-N.ndjson one append-only log per agent — THE coordination channel environment/ 智能体写出的产物 history/ 以往运行的产物，已归档

测试 sh
npm run link-deps # 执行一次：为宿主机的 @deepseek-ai 包建立软链接
npm test

| 测试套件 | 能证明什么 |
| test/smoke.js — 19 | 协作不变量：邻居选择、收敛、终止、结转、并发限制，以及被动智能体不会被计入进度 |
| test/diff/topology-diff.js | 移植版与 AWS 源码等价：1272 组输入组合，逐一跑在从上游逐字提取的函数上 |
| test/plugin-load.js — 10 | apply() 能对真实的 dsh-tools 生效：工具完成注册，schema 编译成合法的 JSON Schema，守卫正常触发 |
| test/subagent-dispatch.js — 11 | 派发调用符合文档中 startContinuable 的规格形状，persona 已应用，settle/grace 行为有界，已完成的子进程（activity: "inactive"）能被识别，而不是一直等下去 |

差分测试

test/diff/aws-neighbourSelector.ts 是上游文件，aws-ref.cjs 保存了从其中逐字提取的 amorphousNeighbours / meshNeighbours。测试让两套实现跑过 1272 组输入，断言输出完全一致——这比手写预期强得多，因为它证明移植版确实等于它声称移植的那个东西。

它还发现了一个真实的上游 bug：当 radius >= concurrency 时，(agentIndex - d + concurrency) % concurrency 会下溢，得到负数的智能体索引（N=2, R=3 -> [-1, 1]），这会去访问 agent--1.ndjson。

函数体保持与上游一致，差分测试才有意义。守卫放在 clampRadius 里，由 selectNeighbours 调用——这是唯一被认可的入口——所以那段有问题的范围无法触达。如果上游修好了，差分运行会标出分歧，这个移植版就能跟上。

实机验证

npm run live [agents] [algorithm] 会通过真实宿主运行时启动组装好的配置档，铸造一个根 captain，派发一个集群，并断言产物落到了磁盘上。这是唯一一个会跑真实智能体回合的测试。

已在实机配置档上确认（3 个智能体，mesh）：11 个产物，36KB，智能体跑的是真实代码——其中一个产物复现了共享日志上的读-改-写竞态，并报告在 3 个和 12 个并发智能体下均已验证。这就是工具带来的差别：同样的提示词，在无工具的 runner 上只产出叙述。

它发现了三个 mock 测试套件发现不了的缺陷，现在都已修复，并由回归测试钉住：

| 缺陷 | 症状 |
| spec.signal 未传递 | signal.throwIfAborted() TypeError——每次派发都失败，集群瞬间退出，零输出 |
| 子进程没有模型路由 | 子进程创建了，但 activity: "inactive" 永远不变——它从未激活 |
| isSettled 不认识 "inactive" | 已经结束的子进程永远不会 settled，于是每次派发都要等满超时，整个集群卡死 |

需要一个配置档，里面有可用的模型路由；设置 FLOCK_AGENT_PROVIDER / FLOCK_AGENT_MODEL，把智能体指向它。

哪些验证过，哪些没有

这里要说清楚，因为这个区别很重要：

- 在这里验证过： 协调机制、插件针对真实 dsh-tools 的注册、派发调用对文档化子代理 API 的符合程度，以及与 AWS 拓扑代码逐字节一致。
- 实机验证过： 插件能装进配置档、能挂载、能在实时注册表里注册它的三个工具，派发出去的集群会往磁盘写真实产物（见上文）。
- 完全无法验证： 与 AWS 原版的行为等价性。它需要 EC2 和 Kiro 订阅，所以没法把两边都跑起来做对比。

协调模型是忠实移植的。执行层是在另一套运行时上的重新实现，而运行时自己做了原版必须显式安排的一些事（新会话漂移控制由 spawn 免费得到）。

致谢

这套设计——通过共享状态协调、三种拓扑、有界邻居集合、四种失败模式、收敛算术——来自 AWS Architecture Blog 的文章 Scaling patterns for self-organizing multi-agent clusters with Kiro 以及 Apache-2.0 参考实现 aws-samples/sample-kiro-flock。
有意思的想法都是他们的。