---
date: 2026-06-14
status: active
origin: docs/brainstorms/2026-06-14-expert-team-mode-requirements.md
---

## Summary

实现专家团模式（Expert Team Mode），在对话框中引入多专家协作能力。底层采用 Plan-Execute 协作模式（结构化协作计划 + 去中心化执行），前端以多角色对话流呈现协作过程。Expert 是比 Skill 更高的角色抽象，聚合多个 Skill 并包含人格和协作策略。支持用户手动指定专家团和系统自动组建两种触发方式，支持子任务级并行和竞标式并行两种并行模式，支持全程用户干预。

## Problem Frame

当前 AgentKit 的多 Agent 协作依赖 Orchestrator-Worker 集中式编排或 Pipeline DAG 流程驱动，无法支撑多专家自主协作、实时讨论、动态调整的复杂任务场景。用户在对话框中只能与单个 Agent 交互，无法获得多视角、多专长的协作产出。专家团模式填补这一空白——让多个 Expert 以目标为导向，自主分析、分工、执行、验证、汇报。

## Requirements

Source: `docs/brainstorms/2026-06-14-expert-team-mode-requirements.md`

Key requirements traced to origin R-IDs:

- Expert 定义与管理 (R1-R5)
- 专家团组建 (R6-R10)
- 协作计划 (R11-R15)
- 去中心化协作 (R16-R19)
- 并行执行与结果合并 (R20-R24)
- 用户干预 (R25-R28)
- 前端展示 (R29-R32)
- 触发与路由 (R33-R36)

## Key Technical Decisions

- **KTD1: Expert 是 Agent 的配置层** — ExpertConfig 继承 AgentConfig，运行时通过 AgentPool 创建 ConfigDrivenAgent 实例。Expert 本身不是 Agent 实例，而是角色定义 + Skill 聚合 + 协作策略的配置单元。Expert 运行时包装器（Expert 类）持有 ConfigDrivenAgent 引用并添加团队感知行为。(see origin: Key Decisions Updated)

- **KTD2: Plan-Execute 协作模式** — CollaborationPlan 定义阶段和里程碑（粗粒度），Expert 在阶段内自主决定具体步骤（细粒度），但必须通过里程碑检查点。这平衡了灵活性和可控性。

- **KTD3: HandoffTransport 抽象层** — 引入 HandoffTransport 协议，两个实现：RedisHandoffTransport（提取现有 Redis pub/sub 逻辑）和 InProcessHandoffTransport（asyncio.Queue，用于同进程 Expert 团队）。HandoffManager 根据上下文自动选择 Transport。

- **KTD4: 前端多角色对话流** — 扩展 IChatMessage 增加 expert_id/expert_name/expert_color 字段，WebSocket 消息增加 team_* 事件类型。多个 Expert 的消息通过 expert_id 标签复用同一 WebSocket 通道，前端按 Expert 过滤展示。

- **KTD5: 降级策略** — 协作计划失败时先重试 1 次（调整分解策略），仍失败则回退到单 Agent 模式继续完成任务。

- **KTD6: 计划修改权限** — Lead Expert 和用户可直接修改 CollaborationPlan；普通 Expert 可提议修改，需 Lead Expert 审批后生效。

- **KTD7: 上下文管理** — 采用摘要共享策略：长内容自动摘要后广播给全体 Expert，原始内容存入 SharedWorkspace 按需获取。避免上下文窗口膨胀。

## High-Level Technical Design

### Expert Team 架构总览

```
┌─────────────────────────────────────────────────────┐
│                    Frontend                          │
│  ExpertTeamView ── ExpertMessage ── PlanViz          │
│       │                │               │             │
│       └────────────────┼───────────────┘             │
│                        │ WebSocket (team_* events)   │
└────────────────────────┼────────────────────────────┘
                         │
┌────────────────────────┼────────────────────────────┐
│                    Server                            │
│  TeamSessionManager ── ExpertTeamRouter              │
│       │                                              │
│       ▼                                              │
│  ┌──────────┐  manages  ┌──────────────┐            │
│  │ExpertTeam│──────────▶│   Expert[]   │            │
│  │          │           │  (wrappers)  │            │
│  │  Plan    │           └──────┬───────┘            │
│  │  Context │                  │ creates            │
│  └────┬─────┘                  ▼                    │
│       │              ┌──────────────────┐           │
│       │              │ ConfigDrivenAgent│           │
│       │              │   (AgentPool)    │           │
│       │              └──────────────────┘           │
│       │                                              │
│  ┌────▼─────────────────────────────┐               │
│  │       TeamOrchestrator           │               │
│  │  execute_plan / merge / retry    │               │
│  └──────────────────────────────────┘               │
│       │              │                              │
│       ▼              ▼                              │
│  HandoffTransport  SharedWorkspace                  │
│  (InProcess/Redis)  (Redis/InMemory)                │
└─────────────────────────────────────────────────────┘
```

### CollaborationPlan 执行流程

```
用户任务 → ExpertTeamRouter → 创建 ExpertTeam
                              │
                              ▼
                    Lead Expert 生成 CollaborationPlan
                              │
                              ▼
                    用户确认计划 ──否──▶ 修改计划
                              │
                              是
                              ▼
                    TeamOrchestrator.execute_plan()
                              │
                 ┌────────────┼────────────┐
                 ▼            ▼            ▼
            Phase 1       Phase 2       Phase 3
           (串行)      (子任务并行)   (竞标并行)
                 │            │            │
                 ▼            ▼            ▼
            里程碑检查    里程碑检查    里程碑检查
                 │            │            │
                 └────────────┼────────────┘
                              │
                              ▼
                    Lead Expert 汇总最终结果
                              │
                              ▼
                    ExpertTeam 解散，临时 Expert 回收
```

### Expert 间协作消息流

```
Expert A ──send_message()──▶ TeamChannel ──broadcast──▶ Expert B, C, D
Expert A ──request_assist()──▶ InProcessHandoff ──▶ Expert B
Expert A ──propose_modification()──▶ Lead Expert ──approve──▶ Plan Update ──broadcast──▶ All Experts
User ──intervene()──▶ TeamChannel ──broadcast──▶ All Experts + Lead re-plans
```

---

## Implementation Units

### U1. ExpertConfig & ExpertTemplate & Registry

**Goal:** 建立 Expert 的数据模型层——ExpertConfig 配置、ExpertTemplate 模板、ExpertTemplateRegistry 注册中心。

**Requirements:** R1, R2, R3, R4

**Dependencies:** None

**Files:**
- `src/agentkit/experts/__init__.py` (create)
- `src/agentkit/experts/config.py` (create)
- `src/agentkit/experts/registry.py` (create)
- `tests/unit/experts/__init__.py` (create)
- `tests/unit/experts/test_config.py` (create)
- `tests/unit/experts/test_registry.py` (create)

**Approach:**
- `ExpertConfig` 继承 `AgentConfig`，新增字段：`persona`（人格描述）、`thinking_style`（思维方式）、`collaboration_strategy`（协作策略偏好）、`bound_skills`（绑定的 Skill 名称列表）、`avatar`（头像标识）、`color`（颜色标识）、`is_lead`（是否为 Lead Expert）
- `ExpertTemplate` 是 `ExpertConfig` 的可复用预设包装，包含 `name`、`config`、`is_builtin`、`description` 字段
- `ExpertTemplateRegistry` 提供 `register(template)`、`get(name)`、`list()`、`search(query)` 方法，内存字典存储，支持从 YAML 目录批量加载
- 遵循 `SkillConfig` 继承 `AgentConfig` 的模式（see `src/agentkit/skills/base.py`）

**Patterns to follow:** `SkillConfig` extending `AgentConfig` in `src/agentkit/skills/base.py`; `SkillRegistry` pattern in `src/agentkit/skills/registry.py`

**Test scenarios:**
- Happy path: 创建 ExpertConfig 并验证所有字段
- Happy path: ExpertConfig 继承 AgentConfig 的基础字段
- Happy path: ExpertTemplate 注册和查询
- Happy path: ExpertTemplateRegistry 从 YAML 目录加载模板
- Edge case: bound_skills 为空列表时默认行为
- Edge case: search 查询无匹配结果返回空列表
- Error path: 注册同名 ExpertTemplate 覆盖旧模板

**Verification:** ExpertConfig 可实例化并序列化；ExpertTemplateRegistry 可注册、查询、搜索模板

---

### U2. CollaborationPlan Data Model

**Goal:** 定义协作计划的数据结构——阶段、角色分工、依赖关系、并行类型、合并策略、里程碑。

**Requirements:** R11, R12, R13

**Dependencies:** U1

**Files:**
- `src/agentkit/experts/plan.py` (create)
- `tests/unit/experts/test_plan.py` (create)

**Approach:**
- `CollaborationPlan` 包含 `phases`（PlanPhase 列表）、`variables`（共享变量）、`status`（计划状态）
- `PlanPhase` 包含：`id`、`name`、`assigned_expert`（Expert 名称）、`task_description`、`depends_on`（依赖的 Phase ID 列表）、`parallel_type`（ParallelType 枚举）、`merge_strategy`（MergeStrategy 枚举，仅竞标式并行时使用）、`milestone`（里程碑检查点描述）、`status`（PhaseStatus 枚举）
- `ParallelType` 枚举：SERIAL、SUBTASK_PARALLEL、COMPETITIVE_PARALLEL
- `MergeStrategy` 枚举：BEST、VOTE、FUSION
- `PhaseStatus` 枚举：PENDING、IN_PROGRESS、COMPLETED、FAILED
- `PlanStatus` 枚举：DRAFT、CONFIRMED、EXECUTING、COMPLETED、FAILED、FALLBACK
- 提供序列化/反序列化方法（to_dict/from_dict），供 SharedWorkspace 存储

**Patterns to follow:** `PipelineStage`/`Pipeline` in `src/agentkit/orchestrator/pipeline_schema.py`

**Test scenarios:**
- Happy path: 创建 CollaborationPlan 并添加 phases
- Happy path: 串行 phase 的依赖关系正确
- Happy path: 子任务级并行 phase 标注
- Happy path: 竞标式并行 phase 带合并策略
- Edge case: 依赖关系形成 DAG（无环）
- Edge case: 竞标式并行 phase 未指定 merge_strategy 时默认 BEST
- Error path: 依赖关系有环时验证失败
- Integration: to_dict/from_dict 往返序列化

**Verification:** CollaborationPlan 可构建、验证、序列化；依赖环检测正确

---

### U3. HandoffTransport Abstraction

**Goal:** 抽象 Handoff 传输层，支持 Redis 和进程内两种模式，使 Expert 间交接不依赖 Redis。

**Requirements:** R16

**Dependencies:** None

**Files:**
- `src/agentkit/core/handoff_transport.py` (create)
- `tests/unit/core/test_handoff_transport.py` (create)

**Approach:**
- 定义 `HandoffTransport` 协议（Protocol）：`send(channel, message)`、`listen(channel) -> AsyncIterator`、`register_handler(channel, handler)`
- `RedisHandoffTransport`：提取 `BaseAgent.handoff()` 中的 Redis pub/sub 逻辑，封装为独立类
- `InProcessHandoffTransport`：基于 `asyncio.Queue` 的进程内传输，每个 channel 对应一个 Queue，支持多消费者广播
- `HandoffManager` 重构：接受 `HandoffTransport` 注入，`send_handoff`/`listen_for_handoffs`/`register_handler` 委托给 transport
- 向后兼容：`HandoffManager()` 无参构造时自动创建 `RedisHandoffTransport`

**Patterns to follow:** `SharedWorkspace` 的双模式模式（Redis + 内存降级）in `src/agentkit/core/shared_workspace.py`

**Test scenarios:**
- Happy path: InProcessHandoffTransport 发送和接收消息
- Happy path: InProcessHandoffTransport 多消费者广播
- Happy path: HandoffManager 使用 InProcessHandoffTransport
- Edge case: InProcessHandoffTransport 队列为空时 listen 阻塞等待
- Error path: 发送到不存在的 channel 不抛异常（消息丢弃）
- Integration: HandoffManager 向后兼容（无参构造使用 Redis）

**Verification:** InProcessHandoffTransport 可在同进程内传递消息；HandoffManager 向后兼容

---

### U4. Expert Runtime Wrapper

**Goal:** 实现 Expert 运行时包装器——ExpertConfig → AgentPool 创建 ConfigDrivenAgent，添加团队感知行为。

**Requirements:** R1, R2, R5, R16, R17, R19

**Dependencies:** U1, U3

**Files:**
- `src/agentkit/experts/expert.py` (create)
- `tests/unit/experts/test_expert.py` (create)

**Approach:**
- `Expert` 类持有 `ExpertConfig` 和 `ConfigDrivenAgent` 引用
- `Expert.create(config, pool)` → 调用 `AgentPool.create_agent()` 创建 ConfigDrivenAgent，注入团队上下文到 system prompt（角色描述、其他 Expert 的角色摘要）
- `Expert.send_message(channel, content)` → 通过 TeamChannel 广播消息给全体 Expert（摘要共享，原始内容存 SharedWorkspace）
- `Expert.request_assist(target_expert, task)` → 通过 InProcessHandoff 向目标 Expert 交接任务
- `Expert.propose_plan_modification(plan_id, modification)` → 提交修改提议给 Lead Expert
- `Expert.get_capabilities_summary()` → 返回角色描述 + 绑定 Skill 列表，供其他 Expert 了解
- `Expert.destroy()` → 调用 `AgentPool.remove_agent()` 清理，产出保留在 SharedWorkspace

**Patterns to follow:** `ConfigDrivenAgent` lifecycle in `src/agentkit/core/config_driven.py`; `BaseAgent.handoff()` in `src/agentkit/core/base.py`

**Test scenarios:**
- Happy path: Expert.create 从 ExpertConfig 创建 ConfigDrivenAgent
- Happy path: Expert.send_message 广播到 TeamChannel
- Happy path: Expert.request_assist 通过 Handoff 交接任务
- Happy path: Expert.get_capabilities_summary 返回角色摘要
- Edge case: Expert 绑定多个 Skill 时全部注入 Agent
- Error path: Expert.create 时 AgentPool 中同名 Agent 已存在
- Integration: Expert 销毁后 ConfigDrivenAgent 被移除

**Verification:** Expert 可创建、发送消息、请求协助、销毁

---

### U5. ExpertTeam Container

**Goal:** 实现 ExpertTeam 容器——管理 Expert 生命周期、共享上下文、协作计划、团队状态。

**Requirements:** R4, R6, R8, R9, R10, R14, R15, R25, R27, R36

**Dependencies:** U1, U2, U4

**Files:**
- `src/agentkit/experts/team.py` (create)
- `tests/unit/experts/test_team.py` (create)

**Approach:**
- `ExpertTeam` 管理一组 Expert 实例，持有 `CollaborationPlan`、`SharedWorkspace` 引用、`TeamChannel`
- 团队生命周期：FORMING → PLANNING → EXECUTING → SYNTHESIZING → COMPLETED
- `create_team(lead_config, member_configs)` → 创建 Lead Expert + 成员 Expert，设置 InProcessHandoff
- `add_expert(config_or_template)` → 动态添加 Expert（R27）
- `remove_expert(name)` → 动态移除 Expert（R27）
- `update_plan(plan)` → Lead Expert 或用户修改计划（R14），广播变更给受影响 Expert（R15）
- `get_shared_context()` → 返回团队共享上下文（通过 SharedWorkspace）
- `broadcast_user_message(content)` → 用户干预消息广播给全体 Expert（R25）
- `dissolve()` → 解散团队，临时 Expert 回收，产出保留（R36）
- `generate_plan(task)` → Lead Expert 生成 CollaborationPlan（混合模式：核心角色从模板匹配，辅助角色动态生成）

**Patterns to follow:** `AgentPool` lifecycle management in `src/agentkit/core/agent_pool.py`

**Test scenarios:**
- Happy path: 创建 ExpertTeam 并设置 Lead Expert
- Happy path: 添加和移除 Expert
- Happy path: update_plan 广播变更给受影响 Expert
- Happy path: broadcast_user_message 对全体 Expert 可见
- Happy path: dissolve 回收临时 Expert
- Edge case: 移除 Lead Expert 时自动指定新 Lead
- Edge case: dissolve 时临时 Expert 产出保留在 SharedWorkspace
- Error path: 向已解散的 ExpertTeam 添加 Expert 抛异常
- Integration: generate_plan 混合模式（模板 + 动态生成）

**Verification:** ExpertTeam 可创建、管理 Expert、更新计划、广播消息、解散

---

### U6. TeamOrchestrator

**Goal:** 实现团队编排引擎——驱动 CollaborationPlan 执行、并行策略、结果合并、重试与降级。

**Requirements:** R12, R13, R18, R20, R21, R22, R23, R24

**Dependencies:** U2, U4, U5

**Files:**
- `src/agentkit/experts/orchestrator.py` (create)
- `tests/unit/experts/test_team_orchestrator.py` (create)

**Approach:**
- `TeamOrchestrator` 持有 `ExpertTeam` 引用，驱动 `CollaborationPlan` 执行
- `execute_plan(plan)` → 按 phase 依赖关系拓扑排序，逐层执行
- 串行 phase：直接执行，完成后检查里程碑
- 子任务级并行 phase：`asyncio.gather` 并行执行，结果由 Lead Expert 汇总（R20）
- 竞标式并行 phase：`asyncio.gather` 并行执行，结果按 MergeStrategy 处理（R21-R24）
  - BEST：Lead Expert 选择最佳结果
  - VOTE：所有 Expert 投票，平局时 Lead Expert 仲裁（R23）
  - FUSION：Lead Expert 融合多个结果
- 里程碑检查：phase 完成后 Expert 必须通过检查点才能进入下一阶段
- 失败处理：重试 1 次（调整分解策略），仍失败则回退单 Agent（KTD5）
- 执行事件：每个 phase 状态变更、并行结果合并都通过 TeamChannel 广播

**Patterns to follow:** `PipelineEngine._topological_group()` + `asyncio.gather` in `src/agentkit/orchestrator/pipeline_engine.py`; adversarial loop (Worker-Verifier) pattern

**Test scenarios:**
- Happy path: 串行 phase 依次执行
- Happy path: 子任务级并行 phase 并行执行后汇总
- Happy path: 竞标式并行 BEST 策略
- Happy path: 竞标式并行 VOTE 策略（含平局仲裁）
- Happy path: 竞标式并行 FUSION 策略
- Happy path: 里程碑检查通过后进入下一阶段
- Edge case: 并行 phase 部分失败时的处理
- Error path: phase 失败后重试 1 次
- Error path: 重试仍失败回退单 Agent
- Integration: 完整计划执行（串行+并行混合）

**Verification:** TeamOrchestrator 可执行计划、处理并行、合并结果、重试降级

---

### U7. Expert Team Routing

**Goal:** 扩展路由系统支持专家团模式——@team 触发、复杂度评估升级、团队路由。

**Requirements:** R7, R33, R34, R35

**Dependencies:** U5, U6

**Files:**
- `src/agentkit/experts/router.py` (create)
- `src/agentkit/chat/skill_routing.py` (modify)
- `tests/unit/experts/test_router.py` (create)

**Approach:**
- 扩展 `ExecutionMode` 枚举新增 `TEAM_COLLAB`
- `ExpertTeamRouter` 解析用户输入：
  - `@team` 前缀 → 触发专家团模式（R34）
  - `@team:analyst,strategist` → 指定专家团成员（R35）
  - 无前缀 → Lead Expert 评估复杂度后建议升级（R7, R33）
- 修改 `CostAwareRouter.route()`：当 `execution_mode == TEAM_COLLAB` 时，委托给 `ExpertTeamRouter`
- `ExpertTeamRouter.resolve()` → 返回 `ExpertTeamRoutingResult`（包含 team 配置、plan、execution_mode）
- 复杂度评估：在 `quick_classify` 返回高复杂度（>0.7）时，附加 team_suggestion 标记

**Patterns to follow:** `CostAwareRouter` three-layer routing in `src/agentkit/chat/skill_routing.py`

**Test scenarios:**
- Happy path: @team 前缀触发专家团模式
- Happy path: @team:analyst,strategist 指定专家团成员
- Happy path: 高复杂度任务建议升级为专家团
- Happy path: 低复杂度任务不触发专家团
- Edge case: @team 后无成员描述时自动组建
- Edge case: 指定的 ExpertTemplate 不存在时回退到动态生成
- Integration: CostAwareRouter 集成 TEAM_COLLAB 模式

**Verification:** @team 触发、复杂度升级、指定成员路由均正确工作

---

### U8. Frontend Data Model & WebSocket Protocol

**Goal:** 扩展前端数据模型和 WebSocket 协议支持专家团消息流。

**Requirements:** R29, R31, R32

**Dependencies:** U6

**Files:**
- `src/agentkit/server/frontend/src/types/chat.ts` (modify)
- `src/agentkit/server/routes/portal.py` (modify)
- `src/agentkit/server/routes/chat.py` (modify)
- `src/agentkit/server/frontend/src/stores/chat.ts` (modify)

**Approach:**
- 扩展 `IChatMessage` 接口：新增 `expert_id?: string`、`expert_name?: string`、`expert_color?: string`、`message_type?: 'chat' | 'handoff' | 'assist_request' | 'plan_update' | 'milestone'`
- 新增 WebSocket 事件类型：
  - `team_formed`：专家团组建完成，包含 Expert 列表和 Plan
  - `expert_step`：Expert 执行步骤（带 expert_id 标签）
  - `expert_result`：Expert 完成子任务
  - `plan_update`：协作计划变更
  - `team_synthesis`：Lead Expert 汇总最终结果
  - `team_dissolved`：专家团解散
- 服务端：新增 `TeamSessionManager` 管理 ExpertTeam 实例，与 `SessionManager` 协同
- `chat.ts` store 扩展：处理 team_* 事件，维护 team 状态

**Patterns to follow:** Existing WebSocket event handling in `src/agentkit/server/routes/chat.py`; `IChatMessage` interface in `src/agentkit/server/frontend/src/types/chat.ts`

**Test scenarios:**
- Happy path: team_formed 事件正确解析 Expert 列表
- Happy path: expert_step 事件带 expert_id 标签
- Happy path: plan_update 事件触发前端状态更新
- Edge case: 非专家团消息不受影响（向后兼容）
- Integration: 完整 team 事件流（formed → step → result → synthesis → dissolved）

**Verification:** 前端可接收和解析所有 team_* 事件；非专家团消息不受影响

---

### U9. ExpertTeam UI Components

**Goal:** 实现专家团前端组件——多角色对话流、计划可视化、Expert 过滤。

**Requirements:** R29, R30, R31, R32

**Dependencies:** U8

**Files:**
- `src/agentkit/server/frontend/src/components/chat/ExpertTeamView.vue` (create)
- `src/agentkit/server/frontend/src/components/chat/ExpertMessage.vue` (create)
- `src/agentkit/server/frontend/src/components/chat/PlanVisualization.vue` (create)
- `src/agentkit/server/frontend/src/stores/team.ts` (create)

**Approach:**
- `ExpertTeamView.vue`：专家团状态栏，显示活跃 Expert 列表（头像+颜色+状态），计划可视化切换按钮
- `ExpertMessage.vue`：扩展 ChatMessage，添加 Expert 头像、颜色标识、角色 badge；handoff/assist_request 消息类型用特殊样式展示
- `PlanVisualization.vue`：协作计划时间线/DAG 可视化，显示 phase 状态、Expert 分工、依赖关系；用户可展开查看详情
- `team.ts` store：管理 team 状态（active experts, plan, phase progress），提供按 Expert 过滤消息的 computed
- ChatView 集成：当 conversation 进入专家团模式时，切换到 ExpertTeamView 布局

**Patterns to follow:** `ChatMessage.vue` component structure; `MentionDropdown.vue` for dropdown patterns; `chat.ts` store for state management

**Test scenarios:**
- Happy path: ExpertMessage 正确显示 Expert 头像和颜色
- Happy path: PlanVisualization 显示协作计划时间线
- Happy path: 按 Expert 过滤消息
- Happy path: handoff 消息特殊样式展示
- Edge case: Expert 被移除后消息保留但标记为已退出
- Edge case: 并行执行时多个 Expert 消息同时更新

**Verification:** 专家团模式下前端正确显示多角色对话流和计划可视化

---

### U10. Integration Tests

**Goal:** 端到端集成测试——验证专家团完整流程。

**Requirements:** All R-IDs

**Dependencies:** U1-U9

**Files:**
- `tests/integration/test_expert_team.py` (create)

**Approach:**
- 测试覆盖所有 Key Flows（F1-F6）和 Acceptance Examples（AE1-AE5）
- 使用 mock LLM 和 mock tools，验证编排逻辑而非 LLM 输出质量
- 测试场景：
  1. 手动组建专家团 + 子任务并行（F1, AE1）
  2. 自动组建专家团 + 竞标并行（F2, AE2）
  3. 去中心化协作执行（F3, AE4）
  4. 用户干预协作（F4, AE3）
  5. 竞标式并行执行 + 投票仲裁（F5）
  6. 专家团解散 + 产出保留（F6, AE5）
  7. 降级策略：重试 + 回退单 Agent
  8. 动态增减 Expert

**Patterns to follow:** `tests/integration/test_gap_closure.py` integration test patterns

**Test scenarios:**
- Covers F1. 手动组建专家团
- Covers F2. 自动组建专家团
- Covers F3. 去中心化协作执行
- Covers F4. 用户干预协作
- Covers F5. 竞标式并行执行
- Covers F6. 专家团解散
- Covers AE1. 手动组建 + 子任务并行
- Covers AE2. 自动组建 + 竞标并行
- Covers AE3. 用户干预调整方向
- Covers AE4. Expert 间直接协作
- Covers AE5. 动态增减 Expert

**Verification:** 所有 Key Flows 和 Acceptance Examples 通过集成测试

---

## Scope Boundaries

**In scope:**
- Expert/ExpertTeam/CollaborationPlan 核心抽象
- HandoffTransport 进程内传输
- TeamOrchestrator 编排引擎（串行 + 两种并行 + 三种合并策略）
- ExpertTeamRouter 路由扩展
- 前端多角色对话流和计划可视化
- 端到端集成测试

**Deferred to follow-up work:**
- Expert 间的学习与进化机制
- 跨会话的 Expert 持久化和记忆共享
- Expert 市场和共享模板库
- 专家团的 A/B 测试和效果评估
- ExpertTemplate YAML 文件的标准模板集（本计划只实现框架，不提供大量预置模板）
- 计划可视化的高级交互（拖拽调整、实时编辑）
- 竞标式并行的更复杂评判策略（加权投票、多轮评审）

**Outside this product's identity:**
- 通用工作流引擎（已有 PipelineEngine）
- 人工审核节点（已有 Workflow approval）
- 实时音视频协作

## Risks & Dependencies

| Risk | Impact | Mitigation |
|------|--------|------------|
| LLM 生成的 CollaborationPlan 质量不稳定 | 高：劣质计划导致协作效率低 | Plan 验证逻辑（依赖环检测、必填字段检查）；用户确认环节；重试降级策略 |
| 去中心化协作可能陷入循环讨论 | 中：Expert 反复交互不收敛 | 里程碑检查点强制推进；最大交互轮次限制；Lead Expert 可强制推进 |
| 多 Expert 并行时上下文窗口膨胀 | 中：LLM 调用成本增加、可能超限 | 摘要共享策略（KTD7）；SharedWorkspace 按需获取原始内容 |
| 前端多路消息流渲染性能 | 低：大量并行消息可能导致 UI 卡顿 | 消息批量更新；虚拟滚动；按 Expert 过滤减少渲染量 |
| HandoffTransport 重构影响现有 Handoff | 中：可能破坏现有 Agent 间交接 | 向后兼容设计（无参构造使用 Redis）；充分单元测试 |

**Dependencies:**
- 依赖现有 `AgentPool` 管理 Agent 实例
- 依赖现有 `SharedWorkspace` 支持共享上下文
- 依赖现有 `CostAwareRouter` 三层路由架构
- 依赖前端 WebSocket 基础设施
- 依赖 LLM 能生成质量合格的 CollaborationPlan

## Open Questions

- ExpertTemplate YAML 文件的标准目录位置（建议 `config/experts/`，待确认）
- 竞标式并行中"融合"策略的具体实现——是 LLM 融合还是规则融合（建议 LLM 融合，待确认）
- 前端计划可视化组件的选型——自研还是使用第三方库（建议自研轻量时间线，待确认）

## Sources & Research

- `src/agentkit/core/base.py` — BaseAgent 生命周期、Handoff、Progress 上报
- `src/agentkit/core/config_driven.py` — ConfigDrivenAgent、AgentConfig、执行模式
- `src/agentkit/skills/base.py` — SkillConfig 继承 AgentConfig 的模式
- `src/agentkit/core/agent_pool.py` — AgentPool 生命周期管理
- `src/agentkit/core/shared_workspace.py` — SharedWorkspace 双模式（Redis + 内存）
- `src/agentkit/core/orchestrator.py` — Orchestrator-Worker 编排模式
- `src/agentkit/orchestrator/pipeline_engine.py` — DAG 拓扑并行、Saga 补偿
- `src/agentkit/orchestrator/handoff.py` — Redis Pub/Sub Handoff
- `src/agentkit/chat/skill_routing.py` — CostAwareRouter 三层路由
- `src/agentkit/server/routes/chat.py` — Chat WebSocket 消息协议
- `src/agentkit/server/frontend/src/types/chat.ts` — IChatMessage 接口
- `src/agentkit/server/frontend/src/stores/chat.ts` — Chat Pinia Store
