🗣️ 深度专家讨论

Multi-agent deep discussion with intelligent Orchestrator coordination. Uses agenda checklist to track progress. Each agenda item goes through 3 rounds (Diverge → Discuss → Converge). Use for complex problems requiring diverse perspectives. Triggers on "深入讨论", "深度讨论", "专家讨论".

# Deep Discussion Skill

Multi-agent deep discussion through **intelligent Orchestrator coordination** with **agenda checklist tracking**.

---

## Quick Start

```
User: "深入讨论预制菜行业现状，使用 5 个专家"

Assistant:
1. Check maxSpawnDepth
2. Align topic (自然对话式)
3. Confirm experts
4. Spawn Orchestrator subagent (thinking: "high")
```

**Result**: Agenda items × 3 rounds = 根据议程数量而定

---

## 输出文件

每个讨论会生成以下文件（保存到 `workspace/deep-discussion/{topic-slug}/`）：

| 文件 | 内容 |
|------|------|
| `agenda.md` | **议程清单（checklist 格式）**，追踪讨论进度 |
| `discussion-log.md` | **完整讨论记录**，包含所有专家的原始输出（必须！） |
| `report.md` | 结构化报告，提炼关键决策和行动计划 |
| `action-plan.md` | 详细行动计划，包含时间线和负责人 |

**⚠️ 讨论完成后不要创建其他文件（如 discussion.md），避免与 discussion-log.md 重复。**

## ⚠️ agenda.md 规范

**议程清单采用 checklist 格式，追踪讨论进度：**

```markdown
# 议程清单 - {topic}

## Phase 1: 价值定位
- [ ] 1. 讨论是否要修改议程
- [ ] 2. 学习规划功能的价值主张是什么？
- [ ] 3. 与自适应引擎如何协同？

## Phase 2: 实现方式
- [ ] 4. 时长预测技术路径？
- [ ] 5. 数据需求与特征工程？
...

## 讨论进度
- 总议题数：{N}
- 已完成：{M}
- 进行中：{K}
```

**Orchestrator 职责**：
- 讨论前创建 `agenda.md`
- 议程第 1 项：讨论是否要修改议程
- 根据专家反馈**更新议程**（考虑依赖关系）
- 每完成一项 → 打勾 ✅
- 实时更新讨论进度

## ⚠️ discussion-log.md 规范

**必须包含所有专家的原始输出！**

```markdown
# 完整讨论记录 - {topic}

## Phase 1: 价值定位

### 议题 2: 学习规划功能的价值主张是什么？

#### Round 1: 发表观点

##### 专家 1: {角色名}
{专家 1 的完整原始输出}

---

##### 专家 2: {角色名}
{专家 2 的完整原始输出}

---

...

#### Round 2: 互相讨论

##### 专家 3 回应专家 1 的问题
{专家 3 的完整原始输出}

---

...

#### Round 3: 收敛共识

##### Orchestrator 总结
{共识总结}

---

### 议题 3: 与自适应引擎如何协同？
...

```

**Orchestrator 职责**：
- 每次 spawn 专家后，**立即**将专家输出追加到 discussion-log.md
- 不要只保存到单独文件，必须汇总到一个文件
- 按 Phase → 议题 → Round → Expert 组织

---

## ⚠️ Pre-flight Checks

### Check 1: maxSpawnDepth

```bash
openclaw config get agents.defaults.subagents.maxSpawnDepth
```

| Value | Orchestrator 运行位置 | 说明 |
|-------|----------------------|------|
| `≥2` | **Orchestrator: Subagent** ⭐ | 启动独立 Orchestrator subagent 协调专家 |
| `=1` | **Orchestrator: Main** | 主 Session 直接作为 Orchestrator 管理专家 |
| `0` | ❌ Blocked | 需要先更新配置 |

> 💡 不管什么模式都需要 Orchestrator 角色，区别只是运行位置。

### Check 2: Topic Alignment

**⚠️ 重要：话题对齐不是固定问题，而是自然对话式理解。**

根据讨论主题灵活调整问题，目标是理解：
- 讨论目标是什么？
- 需要哪些视角/专业知识？
- 期望产出是什么？

**示例：**

| 主题 | 话题对齐问题 |
|------|-------------|
| 预制菜行业 | "是做投资研究、产品规划、还是市场调研？" |
| 技术选型 | "是要做架构决策，还是技术调研报告？" |
| 产品功能 | "是解决具体问题，还是探索新方向？" |

**避免机械地问 5 个固定问题！**

### Check 3: Expert Confirmation + Final Go

基于话题对齐，推荐专家角色供用户确认：

```
🎯 推荐专家（{N} 位）：

1. {角色 1} - {职责说明}
2. {角色 2} - {职责说明}
3. {角色 3} - {职责说明}
...

调整或确认？[y/N 或修改]
```

**用户确认后 → 直接 spawn Orchestrator，不再追问！**

**示例：**

```
🎯 推荐专家（5 位）：

1. 行业分析师 - 市场规模、趋势分析
2. 供应链专家 - 成本结构、效率优化
3. 消费研究员 - 用户需求、行为分析
4. 政策顾问 - 法规风险、合规建议
5. 投资专家 - 估值逻辑、投资回报

调整或确认？[y/N 或修改]
```

用户回复 "确认" 或 "y" → 立即启动 Orchestrator

---

## Core Concepts

### 议程清单（Agenda Checklist）

**议程清单是讨论的核心追踪工具：**

```markdown
# 议程清单 - {topic}

## Phase 1: 价值定位
- [ ] 1. 讨论是否要修改议程
- [ ] 2. 学习规划功能的价值主张是什么？
- [ ] 3. 与自适应引擎如何协同？

## Phase 2: 实现方式
- [ ] 4. 时长预测技术路径？
...
```

**关键规则：**

1. **第一项必须是"讨论是否要修改议程"**
2. **Phase 是议程的逻辑分组**（不是独立阶段）
3. **每完成一项 → 打勾 ✅**
4. **Orchestrator 根据依赖关系编排议程顺序**

### 三轮讨论机制（每个议题）

每个议题都经历三轮讨论：

| Round | 目标 | 方式 | 结束条件 |
|-------|------|------|---------|
| **Round 1: Diverge** | 发表观点 | 并行 spawn 所有专家 | 全部完成 |
| **Round 2: Discuss** | 互相讨论 | 依次 spawn（动态轮数） | 无争议点 AND 无未回答问题 |
| **Round 3: Converge** | 收敛共识 | Orchestrator 总结 | 达成共识 → 打勾 ✅ |

**议题完成后 → 进入下一议题**

### 议程依赖关系

**Orchestrator 在修改议程时需要考虑依赖关系：**

```
正确的议程顺序：
1. 问题定义 → 2. 技术方案 → 3. 实施计划

错误的议程顺序：
1. 实施计划 → 2. 问题定义 → 3. 技术方案
（实施依赖于问题定义和技术方案）
```

**依赖关系示例：**
- "技术方案" 依赖于 "问题定义"
- "实施计划" 依赖于 "技术方案" 和 "资源评估"
- "测试策略" 依赖于 "技术方案"

---

## Orchestrator 工作流程

### 架构

```
主 Session（深度 0）
   │
   └─→ Orchestrator（深度 1）[运行在 Subagent 或 Main]
          │
          ├─→ 1. 创建 agenda.md（议程清单）
          │
          ├─→ 2. 议程第 1 项：讨论是否要修改议程
          │       ├─ 并行 spawn 所有专家发表看法
          │       ├─ 根据反馈更新议程（考虑依赖关系）
          │       └─ 打勾 ✅
          │
          └─→ 3. 按议程逐项讨论：
                  ├─ Round 1: 并行 spawn 所有专家发表观点
                  ├─ Round 2: 依次 spawn 专家讨论（动态轮数）
                  ├─ Round 3: 收敛共识
                  └─ 打勾 ✅ → 下一议题
```

### 议程第 1 项：讨论是否要修改议程

```
议程第 1 项：
├── 1. 并行 spawn 所有专家
│      task: "请审视议程草案，提出修改建议"
├── 2. 收集专家反馈
├── 3. 根据反馈更新议程
│      - 考虑依赖关系编排顺序
│      - 合并相似议题
│      - 拆分复杂议题
│      - 添加遗漏议题
├── 4. 更新 agenda.md
└── 5. 打勾 ✅
```

### 每个议题的讨论流程

```
议题 N：
├── Round 1: 发表观点（并行 spawn）
│      所有专家同时发表对议题 N 的看法
│      追加到 discussion-log.md
│
├── Round 2: 互相讨论（依次 spawn）
│      检测争议点和未回答问题
│      依次 spawn 专家回应
│      直到无争议点 AND 无未回答问题
│
├── Round 3: 收敛共识
│      Orchestrator 总结共识
│      记录未解决争议
│
└── 打勾 ✅ → 更新 agenda.md → 进入议题 N+1
```

### Round 1: 发表观点（并行 spawn）

```javascript
// 并行 spawn 所有专家（必须启用 thinking: "high"）
const experts = [1, 2, 3, 4, 5];
experts.forEach(id => sessions_spawn({
  label: `expert-${id}`,
  mode: "run",
  runtime: "subagent",
  thinking: "high",  // ⚠️ 必须启用
  task: `针对议题 {current_topic}，发表你的观点。`
}));
// 等待所有专家完成
// 追加到 discussion-log.md
```

### Round 2: 互相讨论（依次 spawn）

```javascript
// 检测争议点和未回答问题
while (hasUnansweredQuestions() || hasControversies()) {
  // 选择下一个发言的专家
  const { expertId } = selectNextExpert();

  // 依次 spawn 该专家（必须启用 thinking: "high"）
  sessions_spawn({
    label: `expert-${expertId}-round2`,
    mode: "run",
    runtime: "subagent",
    thinking: "high",  // ⚠️ 必须启用
    task: `请回应以下讨论：
           - 专家 A 问了你：xxx
           - 专家 B 和 C 对 xxx 有分歧
           - 讨论历史：{context}`
  });
  // ⚠️ 等待该专家完成后再 spawn 下一位

  // 追加到 discussion-log.md
  // 更新讨论状态
}
```

### Round 3: 收敛共识

```
├── 总结共识点
├── 记录未解决争议点
├── 判断是否达成共识
└── 打勾 ✅ → 更新 agenda.md → 进入下一议题
```

### 状态追踪

Orchestrator 需要维护讨论状态：

```json
{
  "current_phase": "Phase 1: 价值定位",
  "current_topic": "议题 2: 学习规划功能的价值主张",
  "current_round": 2,
  "agenda_status": {
    "议题 1": "completed",
    "议题 2": "in_progress",
    "议题 3": "pending"
  },
  "questions": [{asker, target, question, answered}],
  "controversies": [{topic, experts, positions}],
  "consensus": [{topic, agreedBy}],
  "statistics": {
    "topic_durations": {
      "议题 1": {"start": "10:00", "end": "10:15", "duration_min": 15},
      "议题 2": {"start": "10:15", "end": null, "duration_min": null}
    },
    "expert_speeches": {
      "专家 1": {"total": 5, "by_topic": {"议题 1": 2, "议题 2": 3}},
      "专家 2": {"total": 4, "by_topic": {"议题 1": 2, "议题 2": 2}},
      ...
    }
  }
}
```

### 智能专家选择（Round 2）

```
优先级：未回答问题 → 争议调解 → 未发言专家 → 轮换
```

---

## Orchestrator 运行模式

| 方面 | Subagent ⭐ | Main |
|------|------------|------|
| 运行位置 | 独立 subagent | 主 Session |
| 专家 spawn | Round 1 并行，Round 2 依次 | 同左 |
| 状态管理 | Orchestrator 内部维护 | 主 Session 维护 |
| 启动命令 | sessions_spawn(...) | 主 Session 直接执行 |
| 适用条件 | maxSpawnDepth ≥ 2 | maxSpawnDepth = 1 |

### Orchestrator: Subagent 启动命令

**⚠️ 重要：Orchestrator 必须使用 `mode: "session"`，而非 `mode: "run"`！**

| mode | 行为 | 适用场景 |
|------|------|----------|
| `"run"` | 一次性执行，spawn 子任务后立即返回 | 简单任务，不需要协调 |
| `"session"` ⭐ | 持久会话，持续追踪子任务，可等待/轮询结果 | 多轮协调、需要收集结果 |

**为什么 Orchestrator 需要 `mode: "session"`？**

- Orchestrator 需要 spawn 多个专家，并等待他们完成
- 需要收集专家输出，写入 discussion-log.md
- 需要持续追踪讨论进度（哪个议题、哪个 Round）
- `mode: "run"` 会立即返回，无法等待子任务结果

**⚠️ 平台限制**：`mode: "session"` 需要 `thread: true`，但飞书插件暂不支持 thread 模式。

**替代方案**：在 `mode: "run"` 模式下，Orchestrator spawn 专家后调用 `sessions_yield()` 等待子任务完成，系统会在所有子任务完成后通知继续。

```javascript
sessions_spawn({
  label: "orchestrator-{topic-slug}",
  runtime: "subagent",
  model: "bailian/qwen3.5-plus",
  thinking: "high",  // ⚠️ 必须启用
  mode: "run",       // 飞书不支持 session 模式，用 run + yield 替代
  runTimeoutSeconds: 14400,  // 4 小时超时
  task: `...

## ⚠️ 关键：如何等待子任务完成

当你 spawn 专家后，必须等待他们完成：

1. spawn 专家
2. 调用 sessions_yield({ message: "等待专家完成..." })
3. 系统会在所有子任务完成后通知你
4. 继续处理结果
...`
});
  task: `你是 Deep Discussion Orchestrator。

## 基本信息
- 主题：{topic}
- 用户背景：{user_context}
- 专家列表：{experts}
- 输出目录：workspace/deep-discussion/{topic-slug}/

## ⚠️ 核心流程

### 1. 创建议程清单
创建 agenda.md，初始议程包含：
- 第一项：讨论是否要修改议程
- 后续议题：根据讨论主题设计

### 2. 议程第 1 项：讨论是否要修改议程
- 并行 spawn