swarm-orchestrator
Skill19 starsChanged 6 months agoMITView on GitHub
通用多智能体编排框架。用于任何需要多Agent协作的任务:研究报告、代码开发、内容创作、数据分析、设计评审等。提供稳定的Agent协调、并行执行、错误恢复和结果合并能力。当任务需要多个Agent协作时,加载此技能作为底层编排框架。
1 other project uses a version of this.
Adopted by
Most recently taken up by
- michaelwinczuk/swarm-orchestratortheir own version, first seen Apr 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- michaelwinczuk/swarm-orchestrator★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- 1nfinix-editorial-card-screenshotSkill
- anti-ai-slop-swarmSkill
- community-profilerSkill
- frontend-datavizSkill
- lab-report-writerSkill
- svg-flowchartSkill
- wechat-file-organizerSkill
- product-story-pptxSkill
- readme-first-builderSkill
The file
Files
Swarm Orchestrator — 通用多智能体编排框架
Overview
Swarm Orchestrator 是一个通用多Agent编排框架,从6个生产级Swarm技能中提取通用模式,适用于任何需要多Agent协作的任务类型。
核心思想:将复杂任务分解为文档先行规划、并行工作执行、顺序结果合并的三段式流程,通过 dim{编号}/ 目录实现零冲突隔离,通过模式选择适配不同复杂度。
与其他技能的关系:此技能提供编排的底层框架。专用技能(如 deep-research-swarm、vibecoding-webapp-swarm)可以基于此框架构建,添加领域特定的规则和工具。
路径约定
本技能不硬编码任何绝对输出路径。所有输出位置遵循以下优先级:
- 工作目录
agents.md(最高优先级):如果项目根目录存在agents.md(或CLAUDE.md),读取其中的路径约定 - 任务根目录:以当前工作目录为基准,在其下创建
{任务名}/子目录作为任务根 - Worker 隔离目录:任务根目录下以
dim01/、dim02/、... 区分各 Worker 的独立工作空间
下文中凡出现 {任务根}/ 均指上述相对路径,不要替换为绝对路径。
Core Principles (编排原则)
- Orchestrator owns coordination — 主Agent负责任务分析、模式选择、Worker部署、结果合并和最终交付。Worker只执行被分配的任务。
- Workers own execution — Worker Agent负责其被分配范围内的完整执行,包括质量控制和错误恢复。Worker不自主决定做什么,但自主决定怎么做。
- Document-first gating — 在任何执行开始前,Orchestrator必须先产出规划文档(设计文档/规格/任务分解)。文档是Gate — 未完成前不进入执行阶段。
- Directory-based isolation — 每个Worker拥有独立的
dim{编号}/目录,互不干扰。Worker之间不直接通信,只通过文件系统间接协调。 - Fidelity to specification — Worker必须忠实执行Orchestrator的规划文档,不得擅自修改接口、调整范围或改变设计。
- Graceful degradation — 单个Worker失败不影响整体流程。Orchestrator负责重试、重新分配或降级处理。
- Observable execution — 每个Worker必须将结果写入其
dim{编号}/目录,Orchestrator通过读取文件监控进度,不依赖Worker的状态报告。 - Bounded iteration over one-shot perfection — 当任务质量需要打磨时,允许 Orchestrator 在交付前运行有界精炼回路(见 Refinement Loop 章节),但循环必须满足三个硬约束:迭代上限、收敛判据、无改进即停。循环只发生在 Orchestrator 层(重新部署 Worker 修复具体缺口),单个 Worker 自身永不循环。没有终止条件的循环视为缺陷,不得交付。
Architecture
Agent Role Model
Orchestrator 根据任务需要,从Agent池中分配角色。详见 references/agent-pool.md。
| 角色 | 职责 | 典型数量 | 决策权限 |
| Orchestrator (主Agent) | 任务分析、模式选择、规划、Worker部署、合并、交付 | 1 | 全局决策 |
| Planner/Designer | 规划文档、设计文档、规格书编写 | 0-1 | 设计决策 |
| Scaffold/Setup | 基础设施搭建、共享组件、项目初始化 | 0-1 | 实现决策 |
| Worker (执行者) | 并行执行具体任务 | 1-10+ | 范围内决策 |
| Verifier | 验证、测试、质量检查 | 0-1 | 质量判定 |
Workflow Pattern
所有Swarm工作流遵循统一模板。模板选择指南见 references/template-index.md,各模板详情见 references/templates/ 目录下对应文件。Orchestrator 先读 template-index.md 选择模板,再按需加载具体模板文件。
Phase 1: 任务分析 & 模式选择 (Orchestrator)
│
▼
Phase 2: 规划 & 文档创建 (Orchestrator ± Planner)
│
▼
Phase 3: 环境搭建 (Orchestrator ± Scaffold)
│
▼
Phase 4: Worker并行部署 (Orchestrator 启动 Workers)
│
▼
Phase 5: 监控 & 自适应控制 (Orchestrator)
│
▼
Phase 6: 结果聚合 & 合并 (Orchestrator) ◄─────────────┐
│ │
▼ │
Phase 7: 验证 & 交付 (Orchestrator ± Verifier) │
│ │
├─ [可选] 精炼回路: 质量未达标 且 未到迭代上限 │
│ 且 上一轮有改进 → 选择性重部署 Worker 修复 ──┘
│
▼ 质量达标 / 触达迭代上限 / 无改进
STOP默认情况下 Phase 7 直接 STOP(稳定瀑布)。精炼回路是可选层,仅在选定模式开启时介入,见 Mode Selection 与 Refinement Loop 章节。
Error Recovery
错误恢复策略和重试规则。详见 references/error-recovery.md。
Workflow Lifecycle
Phase 1: Task Analysis & Mode Selection
Goal: 分析任务特征,选择执行模式。
Input: 用户请求、上传文件、上下文信息。
Process:
- 读取工作目录
agents.md(如果存在),获取路径约定和项目上下文 - 评估任务复杂度:子任务数量、依赖关系、领域跨度
- 检查是否有用户上传文件(影响路由选择)
- 选择执行模式(见 Mode Selection 章节)
- 初始化输出目录:
mkdir -p {任务根}/
Output: 选择的模式声明 + 理由说明。
Rules:
- [CRITICAL] 模式选择一旦确定,不得在执行过程中更改。
- 当不确定时,选择更保守的模式(更多Worker → 更精简)。
Phase 2: Planning & Document Creation
Goal: 产出规划文档,作为后续所有阶段的单一事实来源。
Input: 用户请求、Phase 1的模式选择、任何上传文件。
Process:
- 信息收集(如需要):搜索、浏览URL、分析文件,将结果写入
{任务根}/info.md - 文档创建:由Orchestrator或Planner子Agent编写规划文档。文档内容因任务类型而异:
| 任务类型 | 规划文档 | 关键内容 |
| 研究报告 | 研究计划 | 维度分解、搜索策略、来源要求 |
| 代码开发 | 规格书 | 架构、模块边界、接口定义、数据流 |
| 内容创作 | 大纲+设计 | 结构、风格、每页/章内容要点 |
| 数据分析 | 分析计划 | 数据集、分析方法、可视化要求 |
- 文档审查:Orchestrator审查规划文档的完整性和可执行性
Output: 规划文档保存至 {任务根}/plan.md。
Rules:
- [CRITICAL] 规划文档未完成前,绝不进入Phase 3。
- [CRITICAL] 规划文档是Worker的唯一输入源。Orchestrator不得在Worker执行后补充新指令。
- 规划文档必须包含Worker分配方案 — 哪些任务由哪个Worker执行,以及对应的
dim{编号}/目录。
Phase 3: Environment Setup
Goal: 搭建执行环境,确保Worker可以零冲突并行工作。
Input: Phase 2的规划文档。
Process:
- 创建隔离目录:为每个Worker创建独立的
dim{编号}/目录
mkdir -p {任务根}/dim01 {任务根}/dim02 {任务根}/dim03- 搭建共享资源(如需要,由Scaffold Agent执行):
- 将共享组件、公共配置、模板放入
{任务根}/shared/目录 - 安装依赖、配置工具链
- 生成共享资源(图片、字体等)
- 分发共享资源:将
shared/中Worker需要的文件复制到各dim{编号}/目录,或在Worker指令中指明读取shared/的路径
Output: 可工作的隔离目录 + 共享资源。
Rules:
- [CRITICAL] 每个Worker必须在自己的
dim{编号}/目录内工作,不得写入其他Worker的目录。 - [CRITICAL] Scaffold阶段完成后才能启动Worker — Worker需要继承Scaffold产出的共享资源。
shared/目录在Worker执行阶段为只读 — Worker不得修改共享资源。
Phase 4: Worker Deployment
Goal: 并行启动所有Worker,执行具体任务。
Input: 规划文档、环境设置完成的目录结构。
Process:
- 编写Worker指令:为每个Worker编写任务提示,必须包含:
- (1) Mission:任务范围、输出要求、质量指标
- (2) Context:规划文档的相关部分、前置阶段的关键发现
- (3) Workspace:工作目录路径(
{任务根}/dim{编号}/) - (4) Boundaries:不得修改的文件/范围(
shared/目录、其他Worker的dim{编号}/目录) - (5) Output:输出文件路径、格式要求
- 并行启动:在同一条消息中启动所有Worker(多个
task调用) - Worker执行:
# Worker在自己的dim目录内工作
cd {任务根}/dim{编号}
# 执行任务...
# 完成后在目录内留下产出文件Output: 每个Worker在其 dim{编号}/ 目录中产出结果文件。
Rules:
- [CRITICAL] Worker启动顺序:先启动Scaffold(如需要),Scaffold完成后再并行启动Workers。
- [CRITICAL] 每个Worker的提示必须独立完整 — Worker之间不共享上下文。
- [CRITICAL] Worker完成后必须确保所有产出文件在其
dim{编号}/目录内,然后立即返回。不得运行验证、服务器或浏览器。
Phase 5: Monitoring & Adaptive Control
Goal: 监控Worker进度,处理失败和超时。
Input: 各 dim{编号}/ 目录的文件产出状态。
Process:
- 状态检查:检查每个Worker的
dim{编号}/目录是否有预期的输出文件
ls -la {任务根}/dim01/
ls -la {任务根}/dim02/- 超时处理:Worker在合理时间内未完成 → 记录为超时,启动备用Worker
- 失败恢复:Worker失败 → 根据错误类型选择策略:
- 可重试错误(网络、临时资源不可用):重启同一Worker
- 逻辑错误(规划缺陷):记录问题,继续其他Worker,Phase 6时处理
- 环境错误(依赖缺失):修复环境后重启
- 自适应调整:如多个Worker遇到同类问题,Orchestrator应更新剩余Worker的指令
Output: 每个Worker的状态报告(成功/失败/超时 + 产出摘要)。
Rules:
- [CRITICAL] 单个Worker失败不得阻塞整体流程。Orchestrator必须继续处理其他Worker的结果。
- [CRITICAL] 不得在没有明确理由的情况下无限重试。最多重试2次。
Phase 6: Result Aggregation & Merge
Goal: 合并所有Worker的产出,解决冲突,形成统一结果。
Input: 所有 dim{编号}/ 目录的产出、Phase 5的状态报告。
Process:
- 读取产出:Orchestrator读取每个
dim{编号}/目录中的输出文件 - 合并策略选择:
| 场景 | 合并策略 | 操作 |
| 各Worker产出独立文件 | 直接汇总 | 将各 dim{编号}/ 中的文件复制到 {任务根}/output/ |
| 需要拼接为单文件 | 按序拼接 | 按规划文档顺序拼接各Worker产出 |
| 产出需要交叉整合 | 手动整合 | Orchestrator读取所有产出后,重新组织结构 |
- 冲突解决:如果多个Worker产出了重叠内容,Orchestrator手动解决,优先保留各Worker的完整产出
- 集成:连接各Worker产出的接口点 — 如路由注册、索引创建、汇总生成
Output: 合并后的统一产出,位于 {任务根}/output/ 目录。
Rules:
- [CRITICAL] 合并时,不得丢弃任何Worker的产出。有争议的部分应保留备选,由Orchestrator决定最终版本。
- [CRITICAL] 合并后必须进行集成检查 — 确保各Worker产出之间的接口正确连接。
Phase 7: Verification & Delivery
Goal: 验证最终产出质量,交付给用户。
Input: 合并后的统一产出。
Process:
- 完整性检查:确认所有规划文档中要求的产出都已包含
- 质量检查:运行测试、验证格式、检查约束条件,产出质量评分/问题清单
- 精炼判定(仅当模式开启精炼回路时):依据 Refinement Loop 章节的三条硬约束判断是否回到 Phase 6 再做一轮;否则跳过
- 最终构建(如需要):构建生产版本、生成交付物
- 交付:将最终结果输出到
agents.md指定的交付目录(或{任务根}/output/) - STOP:交付后停止。不打开URL、不截图、不做计划外验证。
Output: 最终交付物 + 完成状态报告。
Rules:
- [CRITICAL] 禁止无界的部署后循环 — 不得反复"再检查一遍"式地空转。唯一允许的循环是 Refinement Loop 章节定义的有界精炼回路(有迭代上限、收敛判据、无改进即停)。回路结束后立即 STOP。
- [CRITICAL] 精炼回路默认关闭;仅在 Phase 1 选定的模式显式开启时才可进入。
- [CRITICAL] 最终交付物必须通过完整性检查 — 缺少任何必要组件不得交付。
Refinement Loop (精炼回路)
精炼回路是一个可选、有界的"批评→修复→再合并"循环,作用在已成功合并的产出上,用于打磨质量(区别于 Error Recovery —— 后者修复的是失败的 Worker,前者改进的是成功但不够好的产出)。它把 Design-Delegate-Iterate 模板里局部的迭代能力,提升为框架级、带安全护栏的能力。
何时开启
| 情况 | 是否开启 |
| 产出有明确质量标准、需要打磨(报告、UI、标准化文档) | 建议开启 |
| 一次性产出即可、时间紧、各部件无关联 | 关闭(默认) |
| 用户明确要求"一次交付""不要反复改" | 强制关闭 |
开启方式:在 Phase 1 声明模式时一并声明 refine: on, max_iterations: N(见 Mode Selection)。
三条硬约束(缺一不可)
- 迭代上限:默认
max_iterations = 2,绝对不超过 3。达到上限即交付当前最佳版本。 - 收敛判据:每轮必须有可度量的质量信号(质量评分、问题清单条数、测试通过率等)。判据写入
{任务根}/refine_log.md。 - 无改进即停:若某轮相对上一轮质量信号无提升(或提升低于设定阈值),立即停止,不再迭代——防止抖动空转。
回路流程
Phase 7 质量检查产出 问题清单 + 质量评分
│
▼
进入精炼判定:
├─ 质量达标? → 是 → STOP 交付
├─ 已达 max_iterations? → 是 → 交付当前最佳版本 + 标注遗留问题
├─ 本轮相比上轮无改进? → 是 → 回滚到上轮最佳版本 → STOP
└─ 以上皆否 → 回到 Phase 6:
用 Mode D (Selective) 只对"有问题的 dim{编号}/"重部署 Worker 修复
→ 重新合并 → 回到 Phase 7 再评估 (iteration += 1)Rules:
- [CRITICAL] 每轮只修复问题清单里具体、已定位的缺口(选择性重部署),不得整体重做、不得借机扩大范围。
- [CRITICAL] 每轮把
iteration、质量信号、本轮改动写入{任务根}/refine_log.md,供"无改进即停"判断。 - [CRITICAL] 精炼回路不是模式变更 —— 不违反"模式一旦确定不得更改";它在选定模式内部运行。
- [CRITICAL] 回路只在 Orchestrator 层循环。被重部署的 Worker 仍是单次执行、完成即返回,绝不自带循环。
与 ReAct 式自适应的关系
Adaptive-Routing 模板提供的是执行期的"评估→重路由"自我发现(reason→act→observe→re-decide);Refinement Loop 提供的是交付期的质量迭代。两者都受同一套护栏约束——必须有上限和终止判据。可组合:执行期用 Adaptive-Routing 找对路径,交付期用 Refinement Loop 打磨质量。
Mode Selection
Orchestrator在Phase 1根据任务特征选择执行模式:
| 条件 | 模式 | Worker数 | 精炼回路默认 | 适用场景 |
| 任务复杂度高、多个独立子任务、领域跨度大 | Mode A (Full Swarm) | 3-10+ | 可开启 | 研究报告、大型项目、复杂系统 |
| 中等复杂度、子任务间有轻度依赖 | Mode B (Compact Swarm) | 2-3 | 可开启 | 中型项目、多页面网站、模块开发 |
| 简单任务或需要严格顺序执行 | Mode C (Sequential) | 1 | 关闭 | 单功能开发、简单分析 |
| 增量更新、部分重试、修复 | Mode D (Selective) | 1-N | —(本身即修复机制) | 补丁、Bug修复、部分重做 |
精炼回路声明:Phase 1 声明模式时,可附加 refine: on/off 与 max_iterations: N(默认 off;开启时 N 默认 2、上限 3)。例如:Mode A, refine: on, max_iterations: 2。Mode D 本身就是精炼回路调用的"选择性重部署"机制,无需单独开启。
模式升级/降级规则:
- Mode B在执行中发现任务比预期复杂 → 将剩余工作拆分为更多Worker
- Mode A中部分Worker因依赖关系无法并行 → 将其转为顺序执行
- [CRITICAL] 模式变更必须在Phase 2完成前决定,Phase 3后不得更改模式。
Agent Communication Protocol
Worker之间不直接通信。所有协调通过以下机制间接完成:
| 机制 | 用途 | 写入者 | 读取者 |
规划文档 (plan.md) | 任务定义和范围 | Orchestrator | 所有Worker |
dim{编号}/ 目录产出 | 进度信号和产出交付 | Worker | Orchestrator |
shared/ 目录 | 共享资源(图片、配置、模板) | Scaffold | 所有Worker(只读) |
refine_log.md | 迭代轮次、质量信号、改动记录("无改进即停"依据) | Orchestrator | Orchestrator |
| 文件命名约定 | 文件归属标识 | Worker | Orchestrator |
File & Output Conventions
目录结构
{任务根}/ # 任务根目录(相对于工作目录)
├── plan.md # 规划文档(Phase 2产出)
├── info.md # 研究/分析结果(可选)
├── refine_log.md # 精炼回路日志(仅 refine:on 时产出)
├── shared/ # 共享资源目录(Scaffold产出)
│ ├── components/ # 共享组件
│ ├── config/ # 公共配置
│ └── assets/ # 共享资源文件
├── dim01/ # Worker 01 工作目录
│ └── ... # Worker 01 的产出
├── dim02/ # Worker 02 工作目录
│ └── ... # Worker 02 的产出
├── dim03/ # Worker 03 工作目录
│ └── ... # Worker 03 的产出
└── output/ # 最终合并产出目录文件命名规范
| 文件类型 | 命名模式 | 示例 |
| Worker产出 | dim{编号}/ 内按任务自然命名 | dim01/market_analysis.md |
| 验证结果 | {任务}_verification.md | project_verification.md |
| 合并报告 | {任务}_merge_report.md | project_merge_report.md |
Quick Start Templates
启动新Swarm任务的最小流程
1. Phase 1: 读取 claude.md → 确定模式 + 是否 refine:on → 声明模式
2. Phase 2: 编写 plan.md → 保存到 {任务根}/
3. Phase 3: 创建 dim{编号}/ 目录 → 准备 shared/(如需要)
4. Phase 4: 并行启动 Workers(各自在 dim{编号}/ 内工作)
5. Phase 5: 监控 → 处理失败
6. Phase 6: 读取各 dim{编号}/ 产出 → 合并到 output/
7. Phase 7: 验证 → [若 refine:on] 未达标且未到上限且有改进 → 回 Phase 6 选择性修复 → 交付 → STOPWorker任务提示模板
工作目录:
{任务根}/dim{编号}/
任务范围:
{具体任务描述}
输入:
- 规划文档: {任务根}/plan.md
- 共享资源: {任务根}/shared/(只读)
- 相关上下文: {文件路径}
边界:
- 不得修改: shared/ 目录、其他 dim{编号}/ 目录
- 只在 dim{编号}/ 内创建/修改文件
输出:
- 文件路径: {任务根}/dim{编号}/{输出文件名}
- 格式要求: {格式说明}
完成后:
确认所有产出文件在 dim{编号}/ 目录内。
返回执行摘要。Integration with Other Skills
此技能作为底层编排框架,可与专用技能组合使用:
| 组合方式 | 说明 | 示例 |
| 作为基础框架 | 专用技能继承此框架的Phase定义,添加领域规则 | deep-research-swarm 继承7-Phase流程,添加研究维度分解和交叉验证 |
| 作为协调层 | 专用技能提供领域工具,此技能提供协调逻辑 | vibecoding-webapp-swarm 提供React工具链,此技能管理Worker部署 |
| 独立引用 | 复杂任务加载此技能获取编排指导 | 数据分析任务引用此技能分解为并行分析维度 |
加载顺序:先加载此技能获取编排框架,再加载专用技能获取领域工具。Orchestrator读取两个技能后,按此技能的Phase流程执行,在适当步骤调用专用技能的领域规则。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

