多代理编排引擎 v8.0 (Multi-Agent Orchestrator)

v8.0 核心变更: Tokens消耗优化（节省25-30%）+ 强约束JSON输出 + 失败边界机制

v8.0 新增功能

🎯 Tokens优化（第一阶段完成）

• 提示词精简: 从 ~800行 → ~80行（减少90%）
• JSON强约束输出: 提升流程遵循性，降低输出不确定性
• 失败边界机制: skip/fallback/partial/retry 四种策略
• 精简版执行引擎: executorLite.js 可选使用

使用方式

# 精简版（默认JSON输出，节省25-30% tokens）
多代理 run_lite --goal "研究主题"

# 完整版（Markdown输出，向后兼容）
多代理 run --goal "研究主题"

Tokens节省估算

环境依赖

启动前检查：多代理 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 覆盖启发式推断：

{
  "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

可用命令列表

命令参数

• --goal "描述" — 任务目标描述
• --workflow <名称> — 指定工作流（可选，默认使用 default）
• --dry_run — 干运行模式（仅 clean 命令）

完整工作流示例

# 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. 模型配置（可用的模型池）

📁 工作区目录检查

系统会详细检查以下目录及其作用：

配置检查结果

• ✅ 全部通过：直接开始执行任务
• ⚠️ 有警告：提示可选配置项，但继续执行
• ❌ 有错误：生成详细配置指南，等待用户确认后自动配置

自动配置说明

如果检测到必需配置缺失，系统会：

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 新增）

子代理完成检查函数

/**
 * 检查子代理状态，检测交互消息
 * @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 };
}

使用示例

// 在等待完成事件时，定期检查子代理状态
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/                          # 归档目录

命令速查

代理管理： 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 修复）

重要区别：

交互消息特征：

• 以询问句结尾（"是否需要..."、"请确认..."、"是否继续..."）
• 需要主代理做出决策或提供指令
• 不是任务完成通知，而是需要主代理介入

处理规则：

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（提纲确认、复杂度评估、超时预设、降级协议、看板体系、分层目录等完整规范）