编排器与角色

蜂群协作的核心是一个常驻的编排器（UI 中称「队长」）与一份它可按需派发的角色目录。理解这两者，就理解了 swarmx 如何把一句需求拆解成一支分工协作的团队。

编排器（队长）

每条工作方向都有且仅有一个编排器，从该方向创建起常驻到结束。你始终只与它对话，由它决定自己动手还是拆分派人。

它维护两份写在黑板上的台账，作为团队的共享记忆：

• 任务台账——目标、已知事实、假设、验收标准、计划（步骤依赖图）。
• 进展台账——当前状态、正在进行的步骤、派出去的活、卡点。

工作分两个阶段：

• 首次上岗：用只读方式扫描项目，写好两份台账，向你打招呼，然后停下。这一步通常 20–40 秒。
• 后续每次唤醒：感知变化 → 分诊 → 规划派发或监督迭代 → 更新台账 → 停下。

因为台账写在黑板上，即使编排器进程被重启，它也能读回台账继续工作——台账即恢复点。当进展台账标记为全部完成时，服务端据此判定该方向已收尾，不再重复拉起编排器。

何时派 worker

编排器遵循一条明确的规模原则：能自己在半分钟内做完的，就不派人；需要更多工作量时才拆分，且倾向于尽量少派。

任务规模	派发数量
单个事实 / 改个错别字 / hello world	0（自己做）
单文件 / 单接口	1
多文件（仅前端或仅后端）	1–2
全栈（前端 + 后端）	2–3
全栈 + 测试 + 端到端 + 文档	3–5
广度研究 / 「找出所有…」/「对比 X 与 Y」	5–10 并行

实现类任务按依赖顺序推进，研究类任务并行铺开。派发通过 swarm_spawn_worker 完成：编排器指定角色与具体指令，服务端据角色补齐默认引擎与模型、生成该 worker 的交接约定、接好唤醒，返回新 agent 的 id。

角色目录

worker 不是凭空捏造的，而是从一份内置角色目录中实例化。每个角色是一份职责说明（SOP）模板，声明了默认引擎、默认模型层级、擅长的领域，以及它产出的交接类型。角色与引擎解耦——同一个角色可由不同引擎承担。

角色	默认引擎	定位
编排器 Orchestrator	claude	常驻队长：扫描、规划、派发、维护台账。
前端工程师 Frontend	claude	UI 组件、样式、前端交互与可视化。
后端工程师 Backend	codex	服务端逻辑、接口、数据层、偏系统与 shell 的工作。
代码评审 Reviewer	claude	独立审阅真实 diff，找正确性缺陷、边界情况、可精简处；宜用与实现者不同的引擎以获得独立视角。
测试执行 Test Runner	codex	真实运行测试套件，报告通过/失败与根因；不改代码。
文档撰写 Docs Writer	claude	基于真实代码写文档、README、注释与说明。
研究员 Researcher	claude	代码库与资料研究、方案对比、带出处的结论与取舍。
修复工 Fixer	codex	针对某个具体失败（红测试 / 构建损坏 / bug）以最小改动定位并修复。

关于拓扑

当前默认拓扑刻意极简：建空间时只拉起一个编排器，下游全由它按任务即兴派发（不预先声明团队结构）。上表中的角色是编排器可选用的 worker 目录，而非需要你手工编排的固定流程。

类型化交接

worker 之间不靠约定俗成的文件名对接，而是靠类型化交接。每个角色声明自己产出的「类型」（默认为 done）。派发时，服务端为该 worker 生成一个规范的黑板键，并注入指令「完成后把总结写到这里，然后停下」。

下游 worker 声明依赖时，只需写「依赖某角色的某类型产出」，无需手写具体键名——服务端负责解析、校验产出方确实存在且会产出该类型（键名写错会被拒绝并给出提示），并接好唤醒。这样，谁产出、谁消费、在什么信号上唤醒，都是显式且可校验的。详见黑板与收件箱与唤醒机制。