多代理编排引擎 - 目标驱动的深度研究与项目协作系统。支持任务分解、分支执行、验证审核、返工迭代、智能决策。遵循第一性原理,实现主代理与分支代理的双向通信。触发词:多代理、multi-agent、代理编排、深度研究、目标分解、任务委派、工作流、agent orchestrate、multi agent
---
name: multi-agent-orchestrator
description: 多代理编排引擎 - 目标驱动的深度研究与项目协作系统。支持任务分解、分支执行、验证审核、返工迭代、智能决策。遵循第一性原理,实现主代理与分支代理的双向通信。触发词:多代理、multi-agent、代理编排、深度研究、目标分解、任务委派、工作流、agent orchestrate、multi agent
user-invocable: true
---
# 多代理编排引擎 v8.0 (Multi-Agent Orchestrator)
> **v8.0 核心变更**: Tokens消耗优化(节省25-30%)+ 强约束JSON输出 + 失败边界机制
## v8.0 新增功能
### 🎯 Tokens优化(第一阶段完成)
- **提示词精简**: 从 ~800行 → ~80行(减少90%)
- **JSON强约束输出**: 提升流程遵循性,降低输出不确定性
- **失败边界机制**: skip/fallback/partial/retry 四种策略
- **精简版执行引擎**: `executorLite.js` 可选使用
### 使用方式
```bash
# 精简版(默认JSON输出,节省25-30% tokens)
多代理 run_lite --goal "研究主题"
# 完整版(Markdown输出,向后兼容)
多代理 run --goal "研究主题"
```
### Tokens节省估算
| 输出模式 | 提示词行数 | 预计节省 | 适用场景 |
|---------|-----------|----------|----------|
| JSON | ~80行 | 25-30% | 结构化研究、数据提取 |
| Markdown | ~400行 | 10-15% | 深度报告、叙事分析 |
## 环境依赖
| 依赖 | 最低版本 | 说明 |
|------|----------|------|
| OpenClaw | **2026.3.x+** | 需要 `sessions_spawn`、`subagents`、`sessions_send` API |
| Node.js | 20.x+ | ES Module 支持 |
| 操作系统 | Windows / macOS / Linux | 路径自动适配(`USERPROFILE` / `HOME`) |
**启动前检查**:`多代理 check_env` — 验证 OpenClaw 版本和工具可用性
## 第三方部署说明
### 兼容性保证
- ✅ **路径无关**:所有路径通过 `process.env.USERPROFILE || process.env.HOME` 动态计算
- ✅ **配置驱动**:模型池、代理配置、角色映射均从外部 JSON 读取,无硬编码
- ✅ **跨平台**:纯 Node.js + `path` 模块,Windows/macOS/Linux 兼容
- ✅ **模型自适应**:自动扫描 `openclaw.json` 中的 providers + fallbacks
### 自定义规则(可选)
在 workspace 根目录创建 `.model-selector-rules.json` 覆盖启发式推断:
```json
{
"traits": {
"your-provider/special-model": ["analysis", "research"],
"another-provider/code-model": ["coding"]
},
"tiers": {
"your-provider/paid-model": "standard",
"your-provider/free-model": "free"
},
"boost": {
"your-provider/premium-model": 20
}
}
```
### 不降级策略
本系统**不提供降级方案**。如果环境检查失败(`check_env` 返回错误),说明 OpenClaw 版本过低或缺少必需 API,必须升级 OpenClaw 到 2026.3.x+ 才能使用。
## 🎯 命令使用
### 如何调用命令
本技能支持通过以下方式调用命令:
**方式 1:通过触发词**
```
用户: 多代理 check_env
用户: 多代理 help
用户: 多代理 plan --goal "研究固态电池"
```
**方式 2:通过技能命令**(推荐)
```
用户: /skill multi-agent-orchestrator check_env
用户: /skill multi-agent-orchestrator help
```
### 可用命令列表
| 命令 | 功能 | 示例 |
|------|------|------|
| `help` | 显示帮助信息 | `多代理 help` |
| `check_env` | 检查环境配置 | `多代理 check_env` |
| `list_profiles` | 列出代理配置 | `多代理 list_profiles` |
| `list_workflows` | 列出工作流 | `多代理 list_workflows` |
| `validate_config` | 验证配置完整性 | `多代理 validate_config` |
| `show_profile` | 显示代理详情 | `多代理 show_profile Research_Analyst` |
| `show_workflow` | 显示工作流详情 | `多代理 show_workflow default` |
| `archive` | 归档工作流产出物 | `多代理 archive` |
| `clean` | 清理临时文件 | `多代理 clean` |
| `run` | 一键启动工作流 | `多代理 run --goal "研究主题"` |
| `plan` | 获取执行计划(JSON) | `多代理 plan --goal "研究主题"` |
| `run_demo` | 快速演示 | `多代理 run_demo` |
### 命令参数
- `--goal "描述"` — 任务目标描述
- `--workflow <名称>` — 指定工作流(可选,默认使用 default)
- `--dry_run` — 干运行模式(仅 clean 命令)
### 完整工作流示例
```bash
# 1. 检查环境
多代理 check_env
# 2. 查看可用代理
多代理 list_profiles
# 3. 查看工作流
多代理 list_workflows
# 4. 执行任务
多代理 run --goal "2026年中国固态电池产业发展现状研究"
# 5. 归档清理
多代理 archive_and_clean
```
## 概述
目标驱动的深度研究与项目协作系统,通过 `sessions_spawn` 实现多代理并行执行。
```
提纲确认 → 复杂度评估 → 路由 → plan → 并行执行 → 收集验证 → 重试/降级 → Critic审核 → 聚合 → 完成
```
## 📋 配置检查(首次使用必做)
### 配置检查流程
**多代理引擎在启动前会自动检查以下配置项**:
1. **OpenClaw 版本** ≥ 2026.3.x
2. **Node.js 版本** ≥ 20.5
3. **工作区目录结构**(详细检查以下目录)
4. **代理配置**(至少 1 个代理配置)
5. **工作流配置**(默认工作流)
6. **模型配置**(可用的模型池)
### 📁 工作区目录检查
系统会详细检查以下目录及其作用:
| 目录 | 必需 | 作用说明 | 缺失影响 |
|------|------|----------|----------|
| **工作区根目录** | ✅ | OpenClaw 工作区根目录,存放所有配置和输出文件 | 系统无法运行 |
| **agents/ 代理工作区** | ✅ | 各代理的独立工作区,每个代理有自己的历史研究子目录 | 子代理无法存放过程文件,任务失败 |
| **shared/ 共享输出目录** | ✅ | 共享输出根目录,存放所有研究的共享文件 | 研究成果无法共享和保存 |
| **shared/researches/ 研究目录** | ✅ | 研究任务目录,按任务名称和时间戳组织研究目录 | 不同研究任务无法隔离 |
| **shared/final/ 最终输出目录** | ✅ | 最终报告目录,存放所有研究的最终报告 | 最终报告无法保存和查看 |
| **.cache/ 缓存目录** | ⚠️ | 缓存目录,用于存储临时文件和缓存数据 | 性能可能受影响 |
| **logs/ 日志目录** | ⚠️ | 日志目录,用于存储系统运行日志 | 调试信息无法保存 |
### 配置检查结果
- **✅ 全部通过**:直接开始执行任务
- **⚠️ 有警告**:提示可选配置项,但继续执行
- **❌ 有错误**:生成详细配置指南,等待用户确认后自动配置
### 自动配置说明
如果检测到必需配置缺失,系统会:
1. **生成详细配置指南**:列出每个缺失目录的路径、作用、缺失影响
2. **等待用户确认**:用户清楚了解每个目录的作用后同意自动配置
3. **自动完成配置**:创建所有必需目录和配置文件
4. **继续执行**:配置完成后自动开始多代理任务
### 配置检查示例
```
多代理 run --goal "研究人工智能在医疗领域的应用前景"
📋 多代理编排引擎 - 配置检查报告
══════════════════════════════════════════════════════════════
## 📊 配置概览
- 总检查项: 6
- ✅ 通过: 3
- ⚠️ 警告: 0
- ❌ 错误: 3
## ❌ 需要修复的配置 (3 项)
### 代理配置
- 当前状态: 未配置
- 要求: 必需
- 说明: 配置文件不存在
📋 目录作用: 代理配置文件,定义每个代理的角色、职责和能力
⚠️ 影响说明: 没有配置文件,多代理系统无法识别和启动任何子代理
🔧 需要自动创建此配置文件才能运行多代理系统
### agents/ 代理工作区
- 当前状态: 未配置
- 要求: 必需
- 说明: 目录不存在
📋 目录作用: 各代理的独立工作区,每个代理有自己的历史研究子目录
⚠️ 影响说明: 没有代理工作区,子代理无法存放过程文件,会导致任务失败
🔧 需要自动创建代理工作区才能运行多代理系统
### shared/final/ 最终输出目录
- 当前状态: 未配置
- 要求: 必需
- 说明: 目录不存在
📋 目录作用: 最终报告目录,存放所有研究的最终报告
⚠️ 影响说明: 没有最终输出目录,研究成果无法保存和查看
🔧 需要自动创建最终输出目录才能运行多代理系统
## 🔧 自动配置选项
如果同意自动配置,系统将执行以下操作:
### 1. 创建 代理配置
**路径**: .multi-agent-profiles.json
**作用**: 代理配置文件,定义每个代理的角色、职责和能力
**影响**: 必需文件,用于配置多代理系统中的各个子代理
**操作**: 创建包含 4 个默认代理的配置文件
### 2. 创建 agents/ 代理工作区
**路径**: agents/
**作用**: 各代理的独立工作区,每个代理有自己的历史研究子目录
**影响**: 必需目录,为每个代理创建独立的工作空间
**操作**: 创建 agents/ 目录以及各个代理的子目录
### 3. 创建 shared/final/ 最终输出目录
**路径**: shared/final/
**作用**: 最终报告目录,存放所有研究的最终报告
**影响**: 必需目录,用于存放最终研究成果
**操作**: 创建最终输出目录结构
[等待用户确认...]
🔧 开始自动配置...
→ 代理配置: 创建配置文件
✅ 已完成
→ agents/ 代理工作区: 创建目录结构
✅ 已完成
→ shared/final/ 最终输出目录: 创建目录
✅ 已完成
✅ 配置完成!
✅ 配置完成,开始执行多代理任务...
```
### 🤔 用户疑虑解答
**Q**: 为什么需要这么多目录?
**A**: 这是多代理系统的架构设计,确保:
1. **代理隔离** - 每个代理独立工作,不互相影响
2. **文件组织** - 按研究、代理、输出类型分类存储
3. **可追溯性** - 历史研究记录可随时查看
**Q**: 目录创建后会影响现有文件吗?
**A**: 不会,系统只会创建缺失的目录,不会修改或删除现有文件
**Q**: 可以手动创建这些目录吗?
**A**: 可以,但建议使用自动配置功能,确保目录结构完全正确
## 🔴 铁律(不可违反)
1. **质量优先**:质量 > 速度。未经用户明确确认,不得以任何理由降低标准、裁剪流程、省略审核
2. **流程不可跳跃**:6 个 Phase 必须按顺序执行,Critic 审核为强制门禁,不可跳过
3. **看板强制输出**:每个阶段完成后必须调用看板函数并展示给用户
4. **聚合不可省略**:即使 100% 成功也必须执行聚合
## 核心能力
- **📋 提纲确认门**(v6 新增)——用户提交目标后,主代理先生成研究提纲,用户确认后才启动协同流程
- **复杂度路由**:简单任务直接完成,中等任务主代理+验证,复杂任务完整多代理并行
- **异构模型分配**:按角色+复杂度自动选择最优模型,同批次不重复
- **增强重试**:区分 6 种错误类型(超时/API错误/空输出/文件缺失/质量不合格/崩溃),针对性重试
- **双看板系统**(v6 新增)——计划看板(Plan)+ 执行看板(Execution),含调用模型/Tokens/文件验证
- **降级协议**:60%成功→主代理补做,30%→重试,<30%→全接管
- **返工机制**:Critic 审核不通过时,自动触发子代理返工循环
- **输出分层**(v6 新增)——按「研究任务/版本/交付物」三级目录隔离,不同任务互不干扰
- **归档清理**:工作流完成后一键归档产出物 + 清理临时文件
## 🛡️ 子代理状态监控(v8.1 新增)
### 子代理完成检查函数
```javascript
/**
* 检查子代理状态,检测交互消息
* @param {string} childSessionKey - 子代理会话 Key
* @param {number} recentMinutes - 最近多少分钟内的会话
* @returns {Promise<{hasInteraction: boolean, message?: string}>}
*/
async function checkSubagentStatus(childSessionKey, recentMinutes = 120) {
const result = await subagents({
action: "list",
recentMinutes: recentMinutes
});
const childSession = result.recent.find(s => s.sessionKey === childSessionKey);
if (!childSession) {
return { hasInteraction: false };
}
// 检查是否有交互消息
const interactionKeywords = [
"是否需要",
"请确认",
"是否继续",
"是否完成",
"是否承担",
"Do you need",
"Please confirm",
"Should I continue"
];
const messages = childSession.messages || [];
const interactionMessage = messages.find(msg =>
interactionKeywords.some(keyword => msg.body.includes(keyword))
);
if (interactionMessage) {
return {
hasInteraction: true,
message: interactionMessage.body
};
}
return { hasInteraction: false };
}
```
### 使用示例
```javascript
// 在等待完成事件时,定期检查子代理状态
async function waitForCompletionWithInteraction(childSessionKey, timeoutMs = 3600000) {
const startTime = Date.now();
const pollInterval = 30000; // 每 30 秒检查一次
while (Date.now() - startTime < timeoutMs) {
// 检查是否有交互消息
const status = await checkSubagentStatus(childSessionKey, 120);
if (status.hasInteraction) {
// 收到交互消息,立即处理
console.log("收到子代理交互消息:", status.message);
// 立即回复,不要等待完成事件
return { type: "interaction", message: status.message };
}
// 等待 30 秒后再次检查
await new Promise(resolve => setTimeout(resolve, pollInterval));
}
// 超时,返回完成事件
return { type: "completion" };
}
```
### 交互消息关键词库
**中文关键词**:
- "是否需要"
- "请确认"
- "是否继续"
- "是否完成"
- "是否承担"
- "需要我..."
- "我已完成..."
**英文关键词**:
- "Do you need"
- "Please confirm"
- "Should I continue"
- "Should I complete"
- "Do you want me to"
- "I have completed"
- "Can I continue"
### 监控规则
1. **定期检查**:在等待完成事件时,每 30 秒检查一次子代理状态
2. **立即处理**:如果检测到交互消息,立即回复,不要等待完成事件
3. **超时保护**:如果 1 小时内未收到完成事件也未收到交互消息,触发超时保护
4. **记录日志**:记录交互消息内容,便于后续分析
## 快速开始
### 一键启动
```
多代理 run --goal "研究人工智能在医疗领域的应用前景"
```
### 模型配置(首次使用必做)
```
多代理 setup # 查看当前配置
多代理 setup_recommended # 查看基于模型库的推荐配置
多代理 setup_confirm # 确认并保存推荐配置
```
### 高级命令
```
多代理 check_env # 检查 OpenClaw 版本和工具可用性(首次启动必做)
多代理 thinking_capabilities # 查看模型 Thinking 支持矩阵
多代理 check_changes # 检测模型池变更
```
### 分步执行
```
多代理 plan --goal "目标" # 生成 JSON 执行计划
多代理 dashboard # 查看任务看板
多代理 model_pool # 查看可用模型池
多代理 archive --workflow_id X # 归档产出物
```
## 执行流程
```
用户提交目标
↓
Phase 0: 提纲确认 ← 展示研究提纲 → 用户确认/修改/取消
↓
Phase 1: plan → 生成执行计划 + 计划看板
↓
Phase 2: spawn → 并行启动子代理 → 等待完成事件 + 监听交互消息
↓
Phase 3: collect → 检查文件 → 评估 → 降级/继续
↓
Phase 4: critic → Critic 审核 → 通过/返工
↓
Phase 5: aggregate → 融合为 FINAL_REPORT.md
↓
Phase 6: finalize → 输出执行摘要
```
### Phase 2 子代理监控规则(v8.1 修复)
**等待完成事件时,必须同时监听交互消息**:
1. **等待完成事件**:子代理任务完成后会推送完成通知
2. **监听交互消息**:子代理可能发送需要主代理决策的消息
3. **立即处理交互消息**:如果收到交互消息,立即回复,不要等待完成事件
**错误示例(v8.0)**:
```
# 等待完成事件到达...
# 忽略子代理发送的交互消息
# 结果:子代理等待回复,主代理不知道
```
**正确示例(v8.1)**:
```
# 等待完成事件到达,同时监听交互消息
if (收到交互消息) {
# 立即回复
replyToSubagent("收到,继续完成...");
}
# 所有任务完成后,输出最终答案
```
## 系统架构
```
┌─────────────────────────────────────────────────────────┐
│ 主代理 (Coordinator) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ 提纲确认 │ │ 结果验证 │ │ 降级补做 │ │ 聚合 │ │
│ └──────────┘ └──────────┘ └──────────┘ └────────┘ │
└────────┬────────────────────────────────────────────────┘
│ sessions_spawn
┌──────▼──────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐
│ Research │ │ Technical │ │ Strategy │ │ Critic │
│ _Analyst │ │ Specialist│ │ _Analyst │ │ (独立) │
└─────────────┘ └───────────┘ └───────────┘ └─────────┘
│ │ │ │
└──────────────┴──────────────┴──────────────┘
shared/researches/{slug}_{date}/v{n}/
```
## 输出目录结构
```
shared/
├── boards/ # 看板 JSON
│ ├── wf_xxx_plan.json
│ └── wf_xxx_exec.json
├── researches/ # 按研究任务隔离
│ ├── ev-overseas_20260403/ # ← 任务A
│ │ ├── v1/ # 第一轮
│ │ │ ├── Research_Analyst_report.md
│ │ │ ├── Technical_Specialist_report.md
│ │ │ ├── Strategy_Analyst_report.md
│ │ │ └── Critic_report.md
│ │ ├── v2/ # 返工轮
│ │ │ ├── Research_Analyst_report_v2.md
│ │ │ └── ...
│ │ └── final/ # 最终交付物
│ │ └── FINAL_REPORT.md
│ └── ai-healthcare_20260405/ # ← 任务B(完全隔离)
└── archive/ # 归档目录
```
## 命令速查
| 命令 | 说明 |
|------|------|
| `plan --goal "X"` | 生成 JSON 执行计划 + 看板 |
| `run --goal "X"` | 生成执行计划 + 文本指南 |
| `dashboard [--workflow_id X]` | 查看任务看板 |
| `model_pool` | 查看可用模型池 |
| `diagnose --result "X"` | 诊断失败原因 |
| `archive --workflow_id X` | 归档产出物 |
| `clean [--dry_run true]` | 清理临时文件 |
| `archive_and_clean --workflow_id X` | 一键归档+清理 |
**代理管理:** `list` / `create` / `template --type research|technical|critical|coordinator|advocate|developer`
**工作流:** `workflow_list`
**验证/聚合/决策:** `validate` / `aggregate` / `decide` / `generate_prompt` / `generate_feedback`
## 与 OpenClaw 工具的配合
本技能提供配置、验证、聚合、决策等能力,实际的代理执行使用 OpenClaw 内置工具:
```
# 创建子代理(主代理的核心调用)
sessions_spawn --task "子任务描述" --runtime subagent --mode run
# 查看子代理状态
subagents --action list
# 向子代理发送消息(向目标会话发送)
sessions_send --sessionKey "目标会话Key" --message "指令"
```
### ⚠️ 交互消息处理机制(v8.1 修复)
**重要区别**:
| 消息类型 | 推送机制 | 处理规则 | 示例 |
|---------|---------|---------|------|
| **完成事件** | push-based | 等待所有完成事件到达后输出最终答案 | "任务完成:02_hermes_analysis_v2.md" |
| **交互消息** | push-based | **立即回复**,不要等待完成事件 | "我的部分已完成。关于 X 任务,是否需要我继续完成?" |
**交互消息特征**:
- 以询问句结尾("是否需要..."、"请确认..."、"是否继续...")
- 需要主代理做出决策或提供指令
- 不是任务完成通知,而是需要主代理介入
**处理规则**:
1. 等待完成事件到达 → 所有任务完成后输出最终答案
2. 如果收到交互消息 → **立即回复**,不要等待完成事件
3. 交互消息通常以询问句结尾,需明确给出决策
**交互消息示例**:
```
I'm the Research_Analyst_2 subagent and have already completed my deliverable: `02_hermes_analysis_v2.md`.
My part is done. About `03_metrics_comparison_v2.md` (评分标准重构), that was originally assigned to another subagent (Technical_Specialist). Do you need me to continue with that?
```
**响应示例**:
```
收到,继续完成 Technical_Specialist 的任务:03_metrics_comparison_v2.md
**任务要求**:
1. 读取 `shared/researches/openclaw-hermes-comparison_20260419/v1/01_openclaw_analysis.md`
2. 读取 `memory/2026-04-*.md` 提取真实统计数据
3. 重新制定 8 维度评分标准
4. 输出:`shared/researches/openclaw-hermes-comparison_20260419/v2/03_metrics_comparison_v2.md`
开始执行!
```
## 配置存储
- 代理配置: `.multi-agent-profiles.json`
- 工作流状态: `.multi-agent-workflows.json`
## 详细文档
- **运行时操作协议**:见 [references/protocols.md](references/protocols.md)(提纲确认、复杂度评估、超时预设、降级协议、看板体系、分层目录等完整规范)
don't have the plugin yet? install it then click "run inline in claude" again.