Openclaw

Multi-agent collaborative industry research for OpenClaw. Dynamically assigns research roles, runs parallel research via sessions_spawn with codex/gemini/claude CLI augmentation, iterative quality review, merge & converge, outputs structured Markdown report. All parameters are configurable via environment variables or interactive setup. Trigger: /research, 行业调研, industry research, 调研报告

# 多智能体协同行业调研（OpenClaw 版）

协调多个 sub-agent 并行完成行业调研，通过迭代审核和合并收敛产出高质量报告。

## Commands

```
/research <topic>                    # 启动行业调研（如：/research AI Agent 行业现状）
/research <topic> --depth=deep       # 深度调研模式
/research <topic> --depth=quick      # 快速概览模式
```

## Prerequisites

- **OpenClaw** — 主 agent 运行时（需启用 `sessions_spawn` 和 `exec` 工具）
- **Codex CLI** (`codex`) — 可选，提供 OpenAI 模型补充视角
- **Gemini CLI** (`gemini`) — 可选，提供 Google 模型补充视角
- **Claude CLI** (`claude`) — 可选，提供 Anthropic 模型补充视角
- CLI 工具未安装不影响核心流程，仅跳过补充视角

## 可配置参数

优先级：**环境变量 > 启动时用户选择 > 默认值**

| 参数 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| 研究 agent 数量 | `RESEARCH_AGENT_COUNT` | `auto` | 设为数字则固定，`auto` 则动态分配 |
| 研究迭代上限 | `RESEARCH_MAX_ROUNDS` | `3` | 研究阶段最多迭代几轮 |
| 合并迭代上限 | `MERGE_MAX_ROUNDS` | `2` | 合并阶段最多迭代几轮 |
| 质量总分阈值 | `QUALITY_THRESHOLD` | `35` | 满分 50，总分需达到此值 |
| 单项最低分 | `QUALITY_MIN_PER_DIM` | `6` | 满分 10，每个维度不低于此值 |
| 交叉验证模式 | `RESEARCH_CROSS_MODEL` | `cli` | `cli` / `native` / `both` / `none`，见下方说明 |
| 启用 CLI 工具 | `RESEARCH_CLI_TOOLS` | `codex,gemini,claude` | 可选值：`codex`、`gemini`、`claude`、`none` 或组合 |
| CLI 超时 | `RESEARCH_CLI_TIMEOUT` | `600` | 秒 |
| Native 模型列表 | `RESEARCH_MODELS` | _(空)_ | 如 `anthropic/claude-sonnet-4-6,google/gemini-2.5-pro,openai-codex/gpt-5.4` |
| 输出语言 | `RESEARCH_LANG` | `zh` | `zh` 中文 / `en` 英文 |
| 报告深度 | `RESEARCH_DEPTH` | `standard` | `quick` / `standard` / `deep` |

### 交叉验证模式

不同 AI 模型有不同的知识覆盖、推理偏好和盲区。让多个模型分别分析同一问题，能有效提升调研质量。

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `cli` | 研究 agent 在自己的分析完成后，**必须**调用 CLI 工具（codex/gemini/claude）对关键发现做交叉验证。CLI 使用订阅账号，无额外 API 费用。**这是默认模式。** | 没有购买多个模型 API 的用户 |
| `native` | 不同研究 agent 通过 `sessions_spawn` 的 `model` 参数使用不同模型原生运行。每个 agent 拥有完整工具链。需要配置 `RESEARCH_MODELS`。 | 已购买多个模型 API key 的用户 |
| `both` | 结合两者：不同 agent 用不同模型 + agent 内部再用 CLI 交叉验证 | 追求最高质量的用户 |
| `none` | 所有 agent 使用默认模型，不做交叉验证 | 快速调研或预算有限 |

**native 模式下的模型分配策略**：
- 将 `RESEARCH_MODELS` 中的模型轮询分配给研究 agent
- Reviewer 使用与多数研究 agent 不同的模型
- Merger 使用与 Reviewer 不同的模型
- 示例：`RESEARCH_MODELS=anthropic/claude-sonnet-4-6,google/gemini-2.5-pro,openai-codex/gpt-5.4`

### 深度预设

| 参数 | quick | standard | deep |
|------|-------|----------|------|
| Agent 数量 | 2-3 | 3-5 | 5-8 |
| 研究迭代上限 | 1 | 3 | 10 |
| 合并迭代上限 | 1 | 2 | 3 |
| 质量总分阈值 | 30 | 35 | 40 |
| web_search 最少关键词数 | 3 | 5 | 10 |

## 工作流

### 阶段 0：配置加载与确认

收到调研主题后，**先完成配置再开始调研**：

1. **检查历史调研残留（防污染）**：
   用 `exec` 扫描工作目录下是否存在历史调研产出：
   ```bash
   ls -d */round-1 */merged */output 2>/dev/null | sed 's|/.*||' | sort -u
   ```
   - **如果发现历史调研目录**：向用户列出这些目录及其创建时间，并询问：
     > 检测到以下历史调研目录，它们可能干扰本次调研（旧报告内容可能被误引用、旧 progress/task_plan 可能干扰状态判断）：
     > - `{dir1}/` ({date1})
     > - `{dir2}/` ({date2})
     >
     > 是否清理？
     > - **A：归档到 `_archive/` 后开始**（推荐 — 移走但不删除）
     > - **B：直接删除后开始**
     > - **C：保留，直接开始**（不推荐）
   - 同时检查工作目录根下的孤立状态文件（`progress.md`、`task_plan.md`、`findings.md`、`tmp/`、`generated/`），一并列入清理范围。
   - 用户选 A 时：`mkdir -p _archive && mv {dirs} _archive/`，同时移走孤立状态文件。
   - 用户选 B 时：`rm -rf {dirs}` 及孤立状态文件。
   - 用户选 C 或无历史残留时：跳过，继续下一步。
   - **重要：等待用户回复后再继续。**

2. 用 `exec` 读取环境变量：
```bash
echo "RESEARCH_DEPTH=${RESEARCH_DEPTH:-standard}"
echo "RESEARCH_AGENT_COUNT=${RESEARCH_AGENT_COUNT:-auto}"
echo "RESEARCH_MAX_ROUNDS=${RESEARCH_MAX_ROUNDS:-}"
echo "MERGE_MAX_ROUNDS=${MERGE_MAX_ROUNDS:-}"
echo "QUALITY_THRESHOLD=${QUALITY_THRESHOLD:-}"
echo "QUALITY_MIN_PER_DIM=${QUALITY_MIN_PER_DIM:-}"
echo "RESEARCH_CROSS_MODEL=${RESEARCH_CROSS_MODEL:-cli}"
echo "RESEARCH_CLI_TOOLS=${RESEARCH_CLI_TOOLS:-codex,gemini,claude}"
echo "RESEARCH_CLI_TIMEOUT=${RESEARCH_CLI_TIMEOUT:-600}"
echo "RESEARCH_MODELS=${RESEARCH_MODELS:-}"
echo "RESEARCH_LANG=${RESEARCH_LANG:-zh}"
```

3. 如果设置了 `RESEARCH_DEPTH`，先应用对应预设，再用环境变量中的具体参数覆盖

4. 检查 CLI 工具可用性：
```bash
command -v codex && codex --version || echo "CODEX_UNAVAILABLE"
command -v gemini && gemini --version || echo "GEMINI_UNAVAILABLE"
command -v claude && claude --version || echo "CLAUDE_UNAVAILABLE"
```
如果配置了某 CLI 但不可用，自动从 `RESEARCH_CLI_TOOLS` 中移除并提示用户。

5. **检测当前 session 模型（模型继承）**：
   子 agent 必须继承主 session 当前使用的模型，而非回退到 openclaw.json 默认值。
   你（主 agent）应当知道自己当前运行的模型 ID（例如 `openai-codex/gpt-5.3-codex-spark`、`openai-codex/gpt-5.4`、`google/gemini-2.5-pro` 等）。
   如果不确定，可用 `exec` 尝试获取：
   ```bash
   curl -s http://localhost:18789/api/session/info 2>/dev/null | python3 -c "import json,sys; print(json.load(sys.stdin).get('model','UNKNOWN'))" || echo "UNKNOWN"
   ```
   将模型 ID 记录为 `inheritedModel`，写入 config.md。
   **后续所有 `sessions_spawn` 调用必须传入 `model: {inheritedModel}`，确保子 agent 与主 session 使用同一模型。**

6. 向用户展示配置表并请求确认（直接输出，等待用户回复）：
   - 选项 A：使用当前配置开始
   - 选项 B：调整参数（逐项询问需修改的值）
   - 选项 C：切换为深度调研模式
   - 选项 D：切换为快速调研模式

**重要：输出选项后停止，等待用户回复再继续执行。**

7. 创建项目目录，将最终配置写入 `{topic-slug}/config.md`：
```bash
mkdir -p "{topic-slug}/round-1" "{topic-slug}/merged" "{topic-slug}/output"
```

### 阶段 1 + 2：主题分析 → 立即 spawn 研究 agent

**关键：阶段 1 和阶段 2 必须在同一个 turn 内连续完成，不得中间回复用户后停下。**

用户确认配置后，在同一个 turn 中完成以下所有步骤：

1. **分析主题**：拆解调研领域，识别 3-8 个关键维度
2. **动态生成角色**，每个角色包含：
   - 角色名称和代号（如 `market-analyst`、`tech-trend`）
   - 调研范围和具体任务描述
   - 关键问题清单（3-5 个必答问题）
   - 推荐 CLI 工具（Codex/Gemini/Claude/仅 web_search）
3. 用 `write` 写入 `brief.md`
4. **不要停下，不要等待用户确认角色方案，立即执行下一步：**

5. **立即用 `sessions_spawn` 逐个启动 N 个研究 agent**（每个用不同 label）。这是必须调用的工具，不可跳过：

**cli 模式**（默认）：所有 agent 继承主 session 模型，prompt 中包含 CLI 交叉验证指令
```
sessions_spawn({ task: "...(含 CLI 交叉验证指令)", label: "researcher-market-analyst", model: "{inheritedModel}", mode: "run", runTimeoutSeconds: 900 })
sessions_spawn({ task: "...(含 CLI 交叉验证指令)", label: "researcher-tech-trend", model: "{inheritedModel}", mode: "run", runTimeoutSeconds: 900 })
```

**native 模式**：每个 agent 指定不同 model（从 RESEARCH_MODELS 轮询分配）
```
sessions_spawn({ task: "...", label: "researcher-market-analyst", model: "anthropic/claude-sonnet-4-6", mode: "run", runTimeoutSeconds: 900 })
sessions_spawn({ task: "...", label: "researcher-tech-trend", model: "google/gemini-2.5-pro", mode: "run", runTimeoutSeconds: 900 })
sessions_spawn({ task: "...", label: "researcher-app-scenario", model: "openai-codex/gpt-5.4", mode: "run", runTimeoutSeconds: 900 })
```

**both 模式**：指定不同 model + prompt 中包含 CLI 交叉验证指令

6. 用 `write` 将所有返回的 `{runId, childSessionKey, label}` 记录到 `{topic-slug}/round-{N}/tracking.md`

7. 回复用户通知："已启动 N 个研究 agent，正在并行调研，完成后我会汇总。"

8. **等待 announce 消息**：每个 sub-agent 完成后会自动发送 announce 回主 session。收到 announce 时：
   - 用 `read` 读取该 agent 的产出文件 `{topic-slug}/round-{N}/agent-{role-slug}.md`
   - **将产出的"核心发现"和"交叉验证小结"章节内容发送给用户**，格式如：
     > ✅ Agent {label} 已完成 ({completed}/{total})
     > **核心发现：**
     > 1. xxx
     > 2. xxx
     > **交叉验证：** {一致/矛盾要点}
   - 这样用户可以实时检查每个 agent 的产出质量

9. **兜底机制**：如果等待超过合理时间，用 `sessions_list` 检查未完成 agent 状态

10. **收到所有 announce 后（包括失败的），立即执行以下操作，不得停下：**
    - 用 `exec` 检查 `{topic-slug}/round-{N}/` 下有哪些 `agent-*.md` 文件
    - 统计成功/失败数量，通知用户
    - 如果 ≥50% agent 有产出 → **立即 spawn reviewer**（进入阶段 3）
    - 不要说"我会接着收口"然后停下——这会中断整个流程

### 阶段 3：审核与迭代

1. 用 `sessions_spawn` 启动 reviewer agent：
```
sessions_spawn：
  task: {Reviewer Prompt}
  label: "reviewer-round-{N}"
  model: "{inheritedModel}"
  mode: "run"
  runTimeoutSeconds: 600
```

2. 等待 reviewer 的 announce 消息
3. 用 `read` 读取 `{topic-slug}/round-{N}/review.md`，**将评审结果发送给用户**：
   > 📋 **第 {N} 轮评审结果：{通过/不通过} — 总分 {X}/50**
   > | 维度 | 得分 |
   > |------|------|
   > | （各维度评分表） |
   > **需改进：** {关键修改指令摘要}
4. 根据评分决策：
   - **通过**（总分 ≥ `QUALITY_THRESHOLD` 且单项 ≥ `QUALITY_MIN_PER_DIM`）→ 进入阶段 4
   - **不通过且轮次 < `RESEARCH_MAX_ROUNDS`** → 回到阶段 2（spawn 新 agent，prompt 中包含上轮产出 + 反馈）
   - **不通过且已达上限** → 通知用户并等待决策

### 阶段 4：合并收敛

1. 用 `sessions_spawn` 启动 merger agent：
```
sessions_spawn：
  task: {Merger Prompt}
  label: "merger-{M}"
  model: "{inheritedModel}"
  mode: "run"
  runTimeoutSeconds: 900
```

2. 等待 merger 的 announce，用 `read` 读取合并稿，**将执行摘要发送给用户**：
   > 📄 **合并稿已完成**，执行摘要：
   > {执行摘要内容}
3. 用 `sessions_spawn` 启动 reviewer 审核合并稿，写入 `{topic-slug}/merged/review-{M}.md`
4. **将合并稿审核结果发送给用户**（同阶段 3 格式）
5. 判断逻辑同阶段 3，上限为 `MERGE_MAX_ROUNDS`

### 阶段 5：