back
loading skill details...
多代理编排引擎 - 目标驱动的深度研究与项目协作系统。支持任务分解、分支执行、验证审核、返工迭代、智能决策。遵循第一性原理，实现主代理与分支代理的双向通信。触发词：多代理、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.