# Agent 间结构化辩论协作

**日期**: 2026-06-24
**状态**: 待规划
**范围**: Deep — feature

## 背景与问题

当前 `@team` 多 Agent 协作是 hub-and-spoke 模式：Lead 分解任务 → 专家隔离执行 → Lead 汇总。专家之间不对话、不质疑、不补充。`HandoffTransport` 只做事件广播，无 Agent 间通信通道。

用户反馈"体现不出多 Agent 协同"——核心痛点是 **看不到 Agent 间互动**。当前流程本质是"并行单 Agent"，不是"协作"。

同时存在两个已知缺口：
- `ExecutionMode.TEAM_COLLAB` 是死代码（定义于 `src/agentkit/chat/skill_routing.py:35`，全代码库无产生点）
- CLI 完全没有多 Agent 入口（`src/agentkit/cli/chat.py` 不处理 `@team`/`@board` 前缀，会被当普通文本送给 LLM）

## 目标

让"Lead 主导的结构化辩论"成为 `@team` 模式的通用能力：Lead 能在关键决策点发起辩论，指定专家就分歧点交锋，裁决后继续执行。用户也能手动触发辩论。

**不是**：Agent 间自由点对点通信。保持 Lead 主导的可控性。

## 成功标准

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

## 方案方向：A + C 混合

以方向 A（Debate Phase）为主体，吸收方向 C（方案先辩论再执行）作为可选模式。

### 两个辩论插入点

1. **方案评审辩论**（来自 C）：Lead 提出任务分解方案后，先让相关专家质疑/补充方案本身，收敛后才开始执行。可选，由 Lead 判断是否需要。
2. **决策点辩论**（来自 A）：执行过程中，Lead 在关键阶段完成后检测分歧，触发辩论阶段。指定专家就该阶段产出交锋，Lead 裁决。

两者都是 `DEBATE` 类型的 `PlanPhase`，只是插入位置不同。

### 辩论阶段执行流程

```
Lead 开场：陈述分歧点 + 上下文
  → 专家 A 发言（论证立场）
  → 专家 B 发言（反驳或补充）
  → （可选）专家 A 回应
  → （可选）专家 B 回应
  → Lead 裁决：采纳/折中/搁置，产出辩论结论
  → 结论写入 SharedWorkspace，喂给下一阶段
```

### 触发机制

- **自动**：Lead 在方案评审点和阶段完成后运行分歧检测（LLM 判断），检测到冲突时插入辩论阶段
- **手动**：用户通过 WS 消息（Web）或命令（CLI）请求辩论，指定主题和参与专家，Lead 插入辩论阶段

## 范围边界

### 包含

- `TeamOrchestrator` 新增 `DEBATE` 阶段类型及执行器
- Lead 的分歧检测能力（prompt + 判断逻辑）
- `@team` 执行期间用户干预通道（前置工程，顺带修复无 `/stop` 缺口）
- 新增 WebSocket 事件：`debate_started`、`expert_argument`、`debate_resolved`
- 前端辩论过程可视化（专家交锋气泡、裁决结果）
- CLI `@team`/`@board` 前缀处理 + 辩论触发命令
- "跳过辩论"逃生舱（简单任务/用户显式跳过）

### 不包含

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

### 延后

- 方向 C 全量（辩论优先作为默认模式）：先验证 A+C 混合的价值，再考虑是否默认化
- 自定义团队模板保存：用户在 UI 选的专家组合无法存为模板复用，独立需求
- `orchestrator/` 子系统与团队流程打通：`PipelineEngine`/`SagaOrchestrator` 等通用编排能力与团队流程的整合，独立规划

## 依赖与假设

### 依赖

- **用户干预通道是前置工程**：当前 `@team` 执行期间用户消息被当新任务处理（`src/agentkit/server/routes/chat.py:_handle_chat_message`）。手动触发辩论要求先建立"执行期间用户干预"通道。这顺带修复团队模式无 `/stop` 的缺口。

### 假设

- **Lead 的分歧检测能力可靠**：自动触发依赖 Lead（LLM）判断"是否值得辩论"。误报浪费 token，漏报错过辩论。需要好的 prompt 和判断标准。若不可靠，降级为纯手动触发。
- **辩论的延迟和成本可接受**：方案评审辩论可能让任务启动延迟 30s-1min。目标用户能接受这个代价换取更高质量的协作。
- **CLI 用户需要多 Agent 能力**：假设 CLI 用户与 Web 用户一样需要多 Agent 协作，而非只用于快速交互。

## 关键决策记录

| 决策 | 选择 | 理由 |
|------|------|------|
| 互动形态 | Lead 主导的结构化辩论 | 复用 hub-and-spoke 架构，可控且能收敛，不做点对点通信 |
| 触发机制 | 自动 + 手动结合 | 兼顾智能和可控，用户随时能介入 |
| 方案方向 | A + C 混合 | A 最小改动，C 的方案评审辩论提升协作质感，两者都是 DEBATE 阶段类型 |
| CLI 纳入 | 是 | 多 Agent 协作应全端可用，不只在 Web |
| 辩论位置 | 阶段边界 | 不在专家执行中途打断，状态清晰，避免级联重跑 |

## 风险

1. **分歧检测质量**：Lead 判断失误（误报/漏报）影响体验。缓解：提供"是否值得辩论"的明确标准，允许用户关闭自动触发。
2. **辩论不收敛**：专家反复争论无法收敛。缓解：限制辩论轮次（默认 2 轮，最多 4 轮），Lead 有强制裁决权。
3. **成本上升**：辩论增加 token 消耗。缓解：逃生舱机制，简单任务跳过；后续可加成本预算阈值。
4. **CLI 交互复杂度**：终端展示多 Agent 辩论不如 Web 直观。缓解：用 Rich 库的 Panel/Live 渲染，专家发言用不同颜色区分。

## 待规划时深入的问题

以下问题留给 `ce-plan` 阶段，不在本需求文档展开：

- `DEBATE` 阶段类型的具体数据结构（`PlanPhase` 扩展字段）
- 分歧检测 prompt 的具体设计
- 用户干预通道的 WS 协议设计（新消息类型？复用现有？）
- 前端辩论可视化的组件设计
- CLI `@team`/`@board` 路由的代码路径（复用 Web 侧的 `ExpertTeamRouter`/`BoardRouter`？）
- 辩论结论如何写入 `SharedWorkspace`（键名约定、与阶段产出的关系）

## 参考文件

- 团队流水线执行器: `src/agentkit/experts/orchestrator.py`
- 团队容器: `src/agentkit/experts/team.py`
- 阶段/计划模型: `src/agentkit/experts/plan.py`
- 私董会讨论引擎（可借鉴多轮发言模式）: `src/agentkit/experts/board_orchestrator.py`
- WebSocket 拦截入口: `src/agentkit/server/routes/chat.py`（`_execute_team_collab` 第 321 行）
- 死枚举 ExecutionMode: `src/agentkit/chat/skill_routing.py:35`
- CLI chat（无多 Agent）: `src/agentkit/cli/chat.py`
- 前端聊天输入: `src/agentkit/server/frontend/src/components/chat/ChatInput.vue`
- 前端事件处理: `src/agentkit/server/frontend/src/stores/chat.ts`（第 870-1200 行）
- 团队模板: `configs/experts/dev_team.yaml`