# feat: Agent 间结构化辩论协作

**日期**: 2026-06-24
**状态**: active
**范围**: Deep — feature
**Origin**: `docs/brainstorms/2026-06-24-agent-debate-collaboration-requirements.md`

---

## Summary

在 `@team` 多 Agent 协作模式中引入"Lead 主导的结构化辩论"能力。当前专家隔离执行、无互动，本计划让 Lead 能在关键决策点发起辩论（指定专家交锋→裁决），支持自动检测分歧触发 + 用户手动触发。同时修复 CLI 完全缺失多 Agent 入口的问题，并顺带补齐 `@team` 执行期间的用户干预通道（当前无 `/stop`）。

---

## Problem Frame

当前 `TeamOrchestrator`（`src/agentkit/experts/orchestrator.py`）是 hub-and-spoke 模式：Lead 分解任务 → 专家隔离执行 → Lead 汇总。`HandoffTransport` 只做事件广播，专家间无通信通道。用户反馈"体现不出多 Agent 协同"——本质是"并行单 Agent"而非协作。

同时存在三个已知缺口：
1. `ExecutionMode.TEAM_COLLAB` 是死代码（`src/agentkit/chat/skill_routing.py:35`，全代码库无产生点）
2. CLI 完全没有多 Agent 入口（`src/agentkit/cli/chat.py` 不处理 `@team`/`@board` 前缀）
3. `@team` 执行期间无用户干预通道（`ExpertTeam.broadcast_user_message()` 方法存在但 `TeamOrchestrator.execute()` 从不检查）

---

## Requirements

源自 `docs/brainstorms/2026-06-24-agent-debate-collaboration-requirements.md`：

- **R1**: 用户在 `@team` 任务执行中，能看到专家间就某个分歧点来回辩论（不是各自独立发言）
- **R2**: Lead 能自动检测专家产出间的冲突/分歧，并触发辩论
- **R3**: 用户能在执行期间手动请求就某个点发起辩论
- **R4**: 辩论有明确收敛：Lead 裁决，产出喂给下一阶段
- **R5**: CLI 用户能使用 `@team`/`@board`，且能触发辩论
- **R6**: 简单任务可以跳过辩论，不强制增加延迟

---

## Key Technical Decisions

### KTD1: 辩论作为 `DEBATE` 阶段类型，而非独立编排器

在 `PlanPhase` 上新增 `phase_type` 字段（`EXECUTION` | `DEBATE`），而非创建独立的 `DebateOrchestrator`。辩论阶段复用现有流水线的拓扑排序、依赖管理、SharedWorkspace 机制。

**理由**：最小架构改动。辩论阶段与其他阶段一样有 `depends_on`，只是执行逻辑不同。避免引入第二套编排引擎导致状态管理分裂。

**代价**：`TeamOrchestrator._execute_phase()` 需要按 `phase_type` 分派，增加一个分支。可接受。

### KTD2: 辩论执行逻辑借鉴 `BoardOrchestrator`，但不复用其类

`BoardOrchestrator`（`src/agentkit/experts/board_orchestrator.py`）已实现"成员并行发言→主持人小结"的多轮循环。辩论阶段借鉴这个模式（Lead 开场→专家轮流发言→Lead 裁决），但作为 `TeamOrchestrator._execute_debate_phase()` 方法内联，不实例化 `BoardOrchestrator`。

**理由**：`BoardOrchestrator` 绑定 `BoardTeam`（独立容器、独立历史、独立状态机），强行复用会引入两套状态同步。内联一个方法比桥接两个编排器简单。

### KTD3: 用户干预通道复用 `ExpertTeam.broadcast_user_message()` + 新增 WS 消息类型

`ExpertTeam` 已有 `broadcast_user_message()` 方法（`src/agentkit/experts/team.py:253`），但 `TeamOrchestrator.execute()` 从不检查。方案：
- WS 新增 `team_intervention` 消息类型，`chat.py` 收到后调用 `team.broadcast_user_message()`
- `TeamOrchestrator` 在阶段边界检查干预队列（与 `BoardOrchestrator` 检查 `consume_user_interventions()` 一致）
- 干预消息可以是 `/stop`（停止团队）、`/debate <topic>`（触发辩论）、或普通文本（追加上下文）

**理由**：复用已有方法，不引入新队列。与 `BoardOrchestrator` 的干预检查模式一致，降低认知成本。

### KTD4: 分歧检测作为 Lead 的 LLM 判断，带"是否值得辩论"的明确标准

自动触发不依赖复杂的一致性算法，而是 Lead 在阶段完成后用 LLM 判断"该阶段产出是否与其他阶段/约束冲突，是否值得辩论"。Prompt 给出明确判断标准（见 U3）。

**理由**：YAGNI——不引入冲突检测框架。LLM 判断够用，误报由"跳过辩论"逃生舱兜底。若不可靠，降级为纯手动触发（需求文档已记录此假设）。

### KTD5: CLI 复用 `ExpertTeamRouter`/`BoardRouter` + Rich 渲染

CLI 在 `chat.py` 的 chat loop 中，于 skill routing 之前拦截 `@team`/`@board` 前缀，复用 Web 侧的 `ExpertTeamRouter.resolve()` 和 `BoardRouter.resolve()`。辩论过程用 Rich 的 `Panel` + 不同颜色渲染专家发言。

**理由**：路由逻辑已存在，CLI 只需接入。不重复实现前缀解析。

---

## High-Level Technical Design

### 辩论阶段在流水线中的位置

```
Lead 分解任务 → phases[]
  ├── [可选] 方案评审辩论 (DEBATE phase, depends_on: 无, 在执行前)
  │     Lead 开场 → 专家质疑方案 → Lead 修订 → 产出"确认的方案"
  │
  ├── 执行阶段 A (EXECUTION phase)
  ├── 执行阶段 B (EXECUTION phase, depends_on: A)
  │
  ├── [自动] 决策点辩论 (DEBATE phase, depends_on: B, Lead 检测分歧后动态插入)
  │     Lead 陈述分歧 → 专家 A/B 交锋 → Lead 裁决 → 产出"辩论结论"
  │
  └── 执行阶段 C (EXECUTION phase, depends_on: 辩论结论)
```

### 辩论阶段执行流程（内联于 TeamOrchestrator）

```
_execute_debate_phase(phase, plan):
  1. 解析 phase.debate_config: {topic, participants, max_rounds}
  2. Lead 开场：陈述分歧点 + 上下文 → broadcast debate_started
  3. for round in 1..max_rounds:
       a. 检查用户干预（/stop 则提前结束）
       b. 参与专家并行发言（基于历史 + 角色）→ broadcast expert_argument
       c. Lead 小结本轮 → broadcast debate_round_summary
  4. Lead 裁决：采纳/折中/搁置 → broadcast debate_resolved
  5. 结论写入 SharedWorkspace ({plan_id}/phase/{phase_id}/output)
  6. phase.status = COMPLETED
```

### 用户干预通道数据流

```
Web 用户 → WS message {type: "team_intervention", content: "/debate 前端框架选型"}
  → chat.py _handle_chat_message 检测团队执行中
  → team.broadcast_user_message(content)
  → TeamOrchestrator 在阶段边界检查 team.consume_user_interventions()
  → 识别 /debate 命令 → 动态插入 DEBATE phase

CLI 用户 → 输入 /debate 前端框架选型
  → cli/chat.py 检测团队执行中
  → team.broadcast_user_message(content)
  → 同上
```

---

## Implementation Units

### U1. 数据模型：PhaseType 枚举 + PlanPhase 扩展

**Goal**: 为 `PlanPhase` 增加 `phase_type` 字段和辩论配置，使流水线能区分执行阶段和辩论阶段。

**Requirements**: 支撑 R1, R4

**Dependencies**: 无

**Files**:
- `src/agentkit/experts/plan.py` (修改)
- `tests/unit/experts/test_plan.py` (新建或修改)

**Approach**:
- 新增 `PhaseType(str, enum.Enum)`: `EXECUTION = "execution"`, `DEBATE = "debate"`
- `PlanPhase` 新增字段：
  - `phase_type: PhaseType = PhaseType.EXECUTION`（默认执行，向后兼容）
  - `debate_config: dict[str, Any] | None = None`（辩论阶段专用：`topic`, `participants: list[str]`, `max_rounds: int = 2`）
- `to_dict()` / `from_dict()` 序列化新字段
- `topological_sort()` 无需改动（辩论阶段也有 `depends_on`，与其他阶段一视同仁）

**Patterns to follow**: 现有 `PlanPhase` 的 dataclass + enum 模式（`src/agentkit/experts/plan.py`）

**Test scenarios**:
- Happy path: 创建 `DEBATE` 类型 phase，序列化/反序列化后字段保留
- 向后兼容: 不带 `phase_type` 的旧 dict 反序列化后默认为 `EXECUTION`
- 边界: `debate_config` 为 None 时不影响 EXECUTION 阶段
- 拓扑排序: 混合 EXECUTION + DEBATE 阶段的依赖图能正确分层

**Verification**: `pytest tests/unit/experts/test_plan.py -x -q` 通过

---

### U2. 辩论阶段执行器（TeamOrchestrator）

**Goal**: 在 `TeamOrchestrator` 中实现辩论阶段的执行逻辑，借鉴 `BoardOrchestrator` 的多轮发言模式。

**Requirements**: R1, R4, R6

**Dependencies**: U1

**Files**:
- `src/agentkit/experts/orchestrator.py` (修改)
- `tests/unit/experts/test_orchestrator_debate.py` (新建)

**Approach**:
- `_execute_phase()` 入口按 `phase.phase_type` 分派：
  - `EXECUTION` → 现有 `_execute_phase()` 逻辑（重命名为 `_execute_execution_phase()`）
  - `DEBATE` → 新增 `_execute_debate_phase()`
- `_execute_debate_phase(phase, plan)`:
  1. 从 `phase.debate_config` 解析 topic/participants/max_rounds
  2. Lead 开场（LLM 生成，陈述分歧点）→ emit `debate_started`
  3. 循环 max_rounds 轮：
     - 检查 `team.consume_user_interventions()`（/stop 提前结束）
     - 参与专家并行发言（LLM 生成，基于历史 + 角色 prompt）→ emit `expert_argument`
     - Lead 小结 → emit `debate_round_summary`
  4. Lead 裁决（LLM 生成，JSON: `decision`, `rationale`, `conclusion`）→ emit `debate_resolved`
  5. 结论写入 SharedWorkspace，`phase.status = COMPLETED`
- 辩论 prompt 借鉴 `BoardOrchestrator._generate_expert_speech()` 的角色注入模式（persona + thinking_style + speaking_style + history）
- **逃生舱**: `debate_config` 可设 `skip: true`，或 Lead 判断"无分歧"时直接跳过（`phase.status = COMPLETED`, result = "无需辩论"）

**Technical design** (directional):
```python
async def _execute_debate_phase(self, phase: PlanPhase, plan: TeamPlan) -> dict[str, Any]:
    config = phase.debate_config or {}
    topic = config.get("topic", phase.task_description)
    participants = config.get("participants", [])
    max_rounds = min(config.get("max_rounds", 2), 4)  # 硬上限 4 轮

    # Lead 开场
    lead = self._team.lead_expert
    opening = await self._generate_debate_opening(lead, topic, phase)
    await self._broadcast_event("debate_started", {...})

    history = [{"expert": lead.config.name, "content": opening, "round": 0}]

    for round_num in range(1, max_rounds + 1):
        # 检查用户干预
        interventions = self._team.consume_user_interventions()
        if self._has_stop_command(interventions):
            break

        # 参与专家并行发言
        experts = [self._team.get_expert(name) for name in participants if self._team.get_expert(name)]
        speeches = await asyncio.gather(
            *[self._generate_debate_argument(e, topic, history, round_num) for e in experts],
            return_exceptions=True,
        )
        for expert, speech in zip(experts, speeches):
            if not isinstance(speech, Exception):
                history.append({"expert": expert.config.name, "content": speech, "round": round_num})
                await self._broadcast_event("expert_argument", {...})

        # Lead 小结
        summary = await self._generate_debate_summary(lead, topic, history, round_num)
        history.append({"expert": lead.config.name, "content": summary, "round": round_num})
        await self._broadcast_event("debate_round_summary", {...})

    # Lead 裁决
    verdict = await self._generate_debate_verdict(lead, topic, history)
    await self._broadcast_event("debate_resolved", {...})

    # 写入 SharedWorkspace
    result = {"content": verdict.get("conclusion", ""), "verdict": verdict}
    phase.status = PhaseStatus.COMPLETED
    phase.result = result
    return result
```

**Patterns to follow**:
- `BoardOrchestrator._generate_expert_speech()` 的角色 prompt 模式（`src/agentkit/experts/board_orchestrator.py:268`）
- `BoardOrchestrator._has_stop_command()` 的停止命令检查（`src/agentkit/experts/board_orchestrator.py:486`）
- `TeamOrchestrator._broadcast_event()` 的事件广播模式

**Test scenarios**:
- Happy path: 2 轮辩论，2 个专家参与，Lead 裁决产出结论，phase 状态变为 COMPLETED
- 边界: max_rounds=1 时只辩论一轮就裁决
- 边界: participants 为空时，Lead 直接给出结论（无辩论）
- 用户停止: 辩论中收到 /stop，提前结束并裁决
- 逃生舱: `debate_config.skip=true` 时直接跳过，phase 状态 COMPLETED，result="无需辩论"
- 错误路径: LLM 不可用时，Lead 用模板文本裁决，不抛异常
- 集成: 辩论结论写入 SharedWorkspace，后续 EXECUTION 阶段能读取

**Verification**: `pytest tests/unit/experts/test_orchestrator_debate.py -x -q` 通过

---

### U3. 分歧检测 + 方案评审辩论（自动触发）

**Goal**: Lead 在阶段完成后自动检测分歧，动态插入辩论阶段；在分解任务后可选发起方案评审辩论。

**Requirements**: R2, R6

**Dependencies**: U1, U2

**Files**:
- `src/agentkit/experts/orchestrator.py` (修改)
- `tests/unit/experts/test_divergence_detection.py` (新建)

**Approach**:
- 新增 `_detect_divergence(lead, completed_phase, plan) -> bool`:
  - Lead 用 LLM 判断该阶段产出是否与其他已完成阶段冲突，或是否存在多个可行方案
  - Prompt 给出明确标准："以下情况值得辩论：1) 两个阶段产出矛盾 2) 阶段产出与任务约束冲突 3) 存在多个合理方案。其他情况返回 false。"
  - LLM 不可用或判断失败时返回 false（宁可漏报不误报）
- `execute()` 主循环修改：每层执行完成后，对每个 completed phase 运行分歧检测，若 true 则动态插入一个 `DEBATE` phase（`depends_on` 指向该 phase），加入下一层
- 方案评审辩论（可选）：`_decompose_task()` 返回 phases 后，Lead 判断"该任务是否需要方案评审"，若需要则在 phases 头部插入一个 `DEBATE` phase（topic="方案评审", participants=所有成员, depends_on=[]）
- **跳过逻辑**: `MAX_DEBATES = 3` 限制单次执行最多插入 3 个辩论阶段（防止成本失控）；简单任务（phases <= 2）默认跳过方案评审

**Patterns to follow**: `TeamOrchestrator._decompose_task()` 的 LLM prompt + JSON 解析模式

**Test scenarios**:
- Happy path: 两个阶段产出矛盾，分歧检测返回 true，自动插入辩论阶段
- Happy path: 阶段产出一致，分歧检测返回 false，不插入辩论
- 边界: phases <= 2 时跳过方案评审
- 边界: 已插入 3 个辩论后不再插入（MAX_DEBATES 上限）
- 错误路径: LLM 不可用时分歧检测返回 false
- 集成: 插入的辩论阶段能被 `topological_sort()` 正确分层，后续阶段能依赖辩论结论

**Verification**: `pytest tests/unit/experts/test_divergence_detection.py -x -q` 通过

---

### U4. 用户干预通道 + 手动辩论触发（WS + CLI 共用）

**Goal**: 建立 `@team` 执行期间的用户干预通道，支持 `/stop`、`/debate <topic>`、普通文本追加上下文。

**Requirements**: R3, R5

**Dependencies**: U1, U2

**Files**:
- `src/agentkit/experts/team.py` (修改：补齐干预队列，参考 BoardTeam 模式)
- `src/agentkit/server/routes/chat.py` (修改：`_execute_team_collab` 增加 WS 干预消息处理)
- `src/agentkit/cli/chat.py` (修改：团队执行期间拦截 `/debate`、`/stop` 命令)
- `tests/unit/experts/test_team_intervention.py` (新建)

**Approach**:
- `ExpertTeam` 补齐干预队列（参考 `BoardTeam` 的 `add_user_intervention()` / `consume_user_interventions()`，`src/agentkit/experts/board.py`）：
  - `_interventions: asyncio.Queue` (bounded, maxsize=64)
  - `add_user_intervention(msg: str)` / `consume_user_interventions() -> list[str]`
  - `broadcast_user_message()` 已存在，改为同时入队干预队列
- WS 侧（`chat.py _execute_team_collab`）：
  - 团队执行期间，`_handle_chat_message` 收到的消息若来自当前 session，识别为干预
  - 新增 WS 消息类型 `team_intervention`，或复用 `message` 类型 + session 匹配
  - 调用 `team.add_user_intervention(content)`
- CLI 侧（`cli/chat.py`）：
  - 团队执行期间，用户输入以 `/` 开头时识别为命令：`/stop`、`/debate <topic>`
  - 调用 `team.add_user_intervention(content)`
- `TeamOrchestrator` 在阶段边界（每层执行前 + 辩论每轮前）检查 `consume_user_interventions()`：
  - `/stop` → 终止执行，走 fallback
  - `/debate <topic>` → 动态插入 DEBATE phase
  - 其他文本 → 追加到 Lead 上下文（影响后续分解/裁决）

**Patterns to follow**:
- `BoardTeam.add_user_intervention()` / `consume_user_interventions()`（`src/agentkit/experts/board.py`）
- `BoardOrchestrator._has_stop_command()`（`src/agentkit/experts/board_orchestrator.py:486`）

**Test scenarios**:
- Happy path: 用户发送 `/debate 前端框架选型`，团队在下一阶段边界插入辩论
- Happy path: 用户发送 `/stop`，团队终止执行并走 fallback
- Happy path: 用户发送普通文本，Lead 在后续裁决中参考
- 边界: 干预队列为空时 `consume_user_interventions()` 返回空列表
- 边界: 多条干预消息累积，一次性消费
- 集成: WS 干预消息能从 `chat.py` 传到 `ExpertTeam` 再到 `TeamOrchestrator`

**Verification**: `pytest tests/unit/experts/test_team_intervention.py -x -q` 通过

---

### U5. 前端辩论可视化

**Goal**: 前端展示辩论过程，专家交锋有独立气泡样式，裁决结果清晰可见。

**Requirements**: R1

**Dependencies**: U1, U2, U4

**Files**:
- `src/agentkit/server/frontend/src/stores/chat.ts` (修改：处理新事件)
- `src/agentkit/server/frontend/src/components/chat/` (修改：辩论气泡组件)
- `src/agentkit/server/frontend/src/types/chat.ts` (修改：新增辩论事件类型)

**Approach**:
- 新增 WS 事件类型声明：`debate_started`、`expert_argument`、`debate_round_summary`、`debate_resolved`
- `chat.ts` 事件处理（参考现有 `expert_step`/`expert_result` 处理，约第 870-1200 行）：
  - `debate_started`: 显示"辩论开始"分隔线 + 分歧主题
  - `expert_argument`: 专家发言气泡，带"辩论中"标签和轮次标记
  - `debate_round_summary`: Lead 小结，缩进显示
  - `debate_resolved`: 裁决结果，高亮显示（采纳/折中/搁置 + 理由）
- 辩论气泡与普通专家发言气泡视觉区分：边框颜色/图标不同
- 用户干预入口：团队执行期间，ChatInput 显示"辩论"按钮（发送 `/debate` 命令）

**Patterns to follow**:
- 现有 `expert_step`/`expert_result` 事件处理模式（`src/agentkit/server/frontend/src/stores/chat.ts`）
- 现有专家气泡组件样式（`src/agentkit/server/frontend/src/components/chat/`）

**Test scenarios**:
- Happy path: 收到 `debate_started` 后显示辩论分隔线和主题
- Happy path: 收到 `expert_argument` 后显示带轮次标记的专家辩论气泡
- Happy path: 收到 `debate_resolved` 后高亮显示裁决结果
- 边界: 辩论中 WebSocket 断开，已显示的辩论内容保留
- 集成: 团队执行期间点击"辩论"按钮，发送 `/debate` 命令

**Verification**: `npm run typecheck` 通过；手动验证辩论过程可视化

---

### U6. CLI 多 Agent 入口 + 辩论支持

**Goal**: CLI 支持 `@team`/`@board` 前缀触发多 Agent 协作，辩论过程用 Rich 渲染。

**Requirements**: R5

**Dependencies**: U1, U2, U4

**Files**:
- `src/agentkit/cli/chat.py` (修改)
- `tests/unit/cli/test_chat_multiagent.py` (新建)

**Approach**:
- chat loop 中，在 skill routing 之前拦截 `@team`/`@board` 前缀：
  - 复用 `ExpertTeamRouter.resolve()` / `BoardRouter.resolve()` 解析前缀
  - 构建 `ExpertTeam` / `BoardTeam`（复用 Web 侧逻辑，但不经过 WS）
  - 注册事件回调：用 Rich 渲染而非 WS 广播
- 事件渲染（Rich）：
  - `team_formed`: Panel 显示团队成员
  - `phase_started`/`expert_step`: 带颜色的专家名 + 任务
  - `expert_result`: Markdown 渲染专家产出
  - `debate_started`: 分隔线 + "辩论: {topic}"
  - `expert_argument`: 带轮次标记的专家发言 Panel（不同专家不同颜色）
  - `debate_resolved`: 高亮裁决结果 Panel
  - `team_synthesis`: 最终结果 Markdown 渲染
- 团队执行期间，用户输入 `/debate`/`/stop` 走干预通道（U4）
- 帮助文本（`_print_help`）补充 `@team`/`@board` 说明

**Patterns to follow**:
- 现有 CLI chat loop 的 Rich 渲染模式（`src/agentkit/cli/chat.py`）
- `BoardOrchestrator` 的事件广播模式（改为回调而非 WS）

**Test scenarios**:
- Happy path: 输入 `@team 开发登录功能`，CLI 显示团队组建 + 阶段执行 + 最终结果
- Happy path: 输入 `@board 讨论微服务 vs 单体`，CLI 显示多轮讨论 + 总结
- Happy path: 团队执行中输入 `/debate 前端框架`，CLI 显示辩论过程
- Happy path: 团队执行中输入 `/stop`，CLI 显示终止 + fallback 结果
- 边界: `@team` 无任务描述时提示用法
- 边界: 专家名称不存在时提示错误
- 集成: CLI `@team` 流程能触发自动分歧检测和辩论（U3）

**Verification**: `pytest tests/unit/cli/test_chat_multiagent.py -x -q` 通过

---

## Scope Boundaries

### 包含

- `DEBATE` 阶段类型及执行器
- Lead 分歧检测（自动触发）
- 用户干预通道（手动触发 + `/stop`）
- 前端辩论可视化
- CLI `@team`/`@board` 入口 + 辩论支持
- "跳过辩论"逃生舱

### 不包含

- Agent 间点对点自由通信（保持 Lead 主导）
- `@board` 模式改造（它已是讨论模式）
- 团队状态持久化（独立问题）
- 辩论成本优化（缓存、早停等，先验证价值）
- `ExecutionMode.TEAM_COLLAB` 死代码清理（顺手可做，非核心交付）

### 延后到后续工作

- 方向 C 全量（辩论优先作为默认模式）：先验证 A+C 混合价值
- 自定义团队模板保存：用户选的专家组合无法存为模板
- `orchestrator/` 子系统与团队流程打通
- 辩论成本预算阈值（token 上限触发跳过）

---

## Risks & Dependencies

### 风险

1. **分歧检测质量**：Lead LLM 判断失误（误报浪费 token，漏报错过辩论）。缓解：明确判断标准 prompt + `MAX_DEBATES` 上限 + 用户可关闭自动触发。
2. **辩论不收敛**：专家反复争论。缓解：硬上限 4 轮 + Lead 强制裁决权。
3. **成本上升**：辩论增加 token 消耗。缓解：逃生舱 + `MAX_DEBATES=3` + 简单任务跳过方案评审。
4. **CLI 交互复杂度**：终端展示多 Agent 辩论不如 Web 直观。缓解：Rich Panel + 颜色区分 + 轮次标记。
5. **WS 干预消息与正常消息混淆**：团队执行期间用户消息可能被当新任务。缓解：session 匹配 + `team_intervention` 消息类型显式区分。

### 依赖

- U1 是所有后续单元的基础（数据模型）
- U2 依赖 U1（辩论执行器需要 DEBATE 阶段类型）
- U3 依赖 U1 + U2（分歧检测需要插入 DEBATE phase）
- U4 依赖 U1 + U2（手动触发需要干预通道 + 辩论执行器）
- U5 依赖 U1 + U2 + U4（前端需要新事件 + 干预入口）
- U6 依赖 U1 + U2 + U4（CLI 需要路由 + 辩论 + 干预）

---

## Open Questions

以下问题留给实现阶段，不阻塞规划：

- `debate_config` 的确切 JSON schema（`participants` 是专家名列表还是 Expert 对象？倾向名字列表，执行时解析）
- WS `team_intervention` 消息的确切格式（是复用 `message` 类型 + flag，还是新类型？倾向新类型，显式优于隐式）
- 前端辩论气泡的具体样式（边框颜色、轮次标记位置）——实现时对齐现有专家气泡风格
- CLI 辩论渲染是否用 `Live` 动态更新还是逐条打印——倾向逐条打印（辩论是离散事件，不需要流式）

---

## System-Wide Impact

- **后端**: `experts/` 模块（plan.py, orchestrator.py, team.py）+ `server/routes/chat.py` + `cli/chat.py`
- **前端**: `stores/chat.ts` + `components/chat/` + `types/chat.ts`
- **测试**: 新增 4 个测试文件
- **配置**: 无新配置项（辩论参数通过 `debate_config` 在运行时传递）
- **文档**: AGENTS.md 的 ExecutionMode 描述需更新（TEAM_COLLAB 死代码清理可顺手做）

---

## Sources & Research

- 需求文档: `docs/brainstorms/2026-06-24-agent-debate-collaboration-requirements.md`
- 现有团队流水线: `src/agentkit/experts/orchestrator.py`
- 现有私董会讨论引擎（借鉴模式）: `src/agentkit/experts/board_orchestrator.py`
- 现有阶段/计划模型: `src/agentkit/experts/plan.py`
- WS 拦截入口: `src/agentkit/server/routes/chat.py`（`_execute_team_collab` 第 321 行）
- CLI chat（当前无多 Agent）: `src/agentkit/cli/chat.py`
- 前端事件处理: `src/agentkit/server/frontend/src/stores/chat.ts`（第 870-1200 行）