---
date: 2026-06-14
topic: expert-team-mode
---

## Summary

在对话框中引入专家团模式（Expert Team Mode），支持用户手动指定或系统自动组建多专家协作团队。底层采用 Plan-Execute 协作模式（结构化协作计划 + 去中心化执行），前端以多角色对话流呈现协作过程。Expert 是比 Skill 更高的角色抽象，聚合多个 Skill 并包含人格、思维方式和协作策略。

## Problem Frame

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

## Key Decisions

- **Plan-Execute 而非纯 Swarm**：结构化协作计划保证任务收敛和可预测性，Expert 在职责范围内自主协作（去中心化），但整体框架由计划约束。纯 Swarm 模式自由度最高但收敛风险大。

- **Expert 聚合 Skill**：Expert 是比 Skill 更高的角色抽象。一个 Expert 聚合多个 Skill，并包含人格设定、思维方式、协作策略。Skill 是能力单元，Expert 是角色单元。

- **混合 Agent 生成**：核心角色从预定义专家模板库选择（保证质量），辅助角色由 LLM 根据任务现场动态生成（保持灵活性）。

- **前端对话流展示**：协作过程以多角色对话流呈现给用户，每个 Expert 有独立头像和颜色标识。底层是结构化计划驱动，前端是对话式体验。

- **两种并行模式统一支持**：子任务级并行（各做各的，结果汇总）和竞标式并行（同一任务多人做，取最优/融合）都在协作计划中标注，执行引擎按类型处理。

## Actors

- A1. **用户** — 发起任务、指定专家团成员、干预协作过程（调整分工、增减 Expert、修改方向）
- A2. **Lead Expert** — 首个加入团队的 Expert 或用户指定的负责人，负责初始任务分解、协作计划生成、最终结果汇总
- A3. **Expert** — 具有特定专长的角色，在职责范围内自主工作，可与其他 Expert 直接交互和交接
- A4. **ExpertTeam** — 专家团容器，管理 Expert 的加入/退出、共享上下文、协作计划的生命周期
- A5. **ExpertTemplate Registry** — 专家模板注册中心，存储预定义的 Expert 模板供选择和组装

## Requirements

### Expert 定义与管理

- R1. Expert 配置包含：名称、人格描述、思维方式、绑定的 Skill 列表、协作策略偏好、头像/颜色标识
- R2. Expert 可聚合一个或多个已注册 Skill，执行时按 SkillConfig 驱动
- R3. ExpertTemplate 是可复用的 Expert 预设，存储在 YAML 配置或注册中心中，包含完整的 Expert 配置
- R4. ExpertTemplate Registry 支持模板的注册、查询、列表展示
- R5. 临时 Expert 由 LLM 根据任务分析动态生成 ExpertConfig，包含角色名称、职责描述、建议绑定的 Skill

### 专家团组建

- R6. 用户可通过对话框手动指定专家团成员（选择 ExpertTemplate 或指定角色描述）
- R7. Lead Expert 在接收任务后评估复杂度，建议升级为专家团模式（需用户确认，不自动强制升级）
- R8. 自动组建时，Lead Expert 分析任务后生成协作计划，计划中包含需要的 Expert 角色定义
- R9. 自动组建采用混合模式：核心角色从模板库匹配，辅助角色动态生成
- R10. 专家团组建后，所有 Expert 的角色信息对用户可见

### 协作计划

- R11. CollaborationPlan 定义专家团的结构化协作蓝图，包含：任务分解、角色分工、依赖关系、并行节点、合并策略
- R12. 协作计划中的每个节点标注执行类型：串行、子任务级并行、竞标式并行
- R13. 竞标式并行节点需指定评判策略：取最优、投票、融合
- R14. 协作计划可由 Lead Expert 或用户动态修改；普通 Expert 可提议修改，需 Lead Expert 审批后生效
- R15. 计划修改后，受影响的 Expert 立即感知变更并调整行为

### 去中心化协作

- R16. Expert 之间可直接交互、请求协助、交接任务，无需经过 Lead Expert 中转
- R17. Expert 间的交互通过共享对话流进行，所有消息对团队内所有 Expert 可见；上下文管理采用摘要共享策略（长内容自动摘要后广播，原始内容存入 SharedWorkspace 按需获取）
- R18. Lead Expert 负责初始分解和最终汇总，但不控制中间流程
- R19. Expert 通过共享上下文中的角色描述了解其他 Expert 的专长，可据此发起协作请求

### 并行执行与结果合并

- R20. 子任务级并行：多个 Expert 同时执行不同子任务，结果由 Lead Expert 或指定 Expert 汇总
- R21. 竞标式并行：多个同类型 Expert 独立完成同一子任务，结果按评判策略处理
- R22. 评判策略"取最优"：由 Lead Expert 或指定评审 Expert 选择最佳结果
- R23. 评判策略"投票"：所有 Expert 投票选择最佳结果，平局时由 Lead Expert 仲裁
- R24. 评判策略"融合"：由 Lead Expert 或指定 Expert 将多个结果融合为统一产出

### 用户干预

- R25. 用户可随时在对话流中插入指令，指令对全体 Expert 可见
- R26. 用户可调整专家团分工（修改协作计划）
- R27. 用户可增减 Expert（添加新 Expert 或移除已有 Expert）
- R28. 用户可修改任务方向或补充需求，Lead Expert 据此重新规划

### 前端展示

- R29. 协作过程以多角色对话流形式呈现，每个 Expert 的消息带有独立头像和颜色标识
- R30. 协作计划以可视化方式展示（分工图/时间线），用户可展开查看详情
- R31. 并行执行时，多个 Expert 的消息流通过消息标签（expert_id）复用同一 WebSocket 通道同时更新，用户可按 Expert 切换关注焦点
- R32. Expert 间的交接、请求协助等交互以特殊消息类型展示（区别于普通对话）

### 触发与路由

- R33. Lead Expert 在接收任务后评估复杂度，建议升级为专家团模式（与 R7 一致）
- R34. 用户可通过 `@team` 或类似指令主动触发专家团模式
- R35. 用户指定专家团成员时，跳过自动分析，直接进入协作计划生成
- R36. 专家团任务完成后，团队自动解散，临时 Expert 被回收；临时 Expert 的产出保留在 SharedWorkspace 中不随实例销毁丢失

## Key Decisions (Updated)

- **Expert 与 Agent 的关系**：Expert 是 Agent 的配置层（ExpertConfig），运行时通过 AgentPool 创建对应的 ConfigDrivenAgent 实例。Expert 本身不是 Agent 实例，而是角色定义 + Skill 聚合 + 协作策略的配置单元。

## Key Flows

- F1. 手动组建专家团
  - **Trigger:** 用户在对话框中指定专家团成员
  - **Actors:** A1, A4, A2
  - **Steps:** 用户指定 ExpertTemplate 或角色描述 → ExpertTeam 创建 → Lead Expert 生成 CollaborationPlan → 计划展示给用户确认 → Expert 按计划开始协作
  - **Covered by:** R6, R10, R11, R35

- F2. 自动组建专家团
  - **Trigger:** 系统检测到高复杂度任务或用户请求专家团
  - **Actors:** A1, A4, A2, A5
  - **Steps:** Lead Expert 分析任务 → 识别需要的 Expert 角色 → 核心角色从模板库匹配、辅助角色动态生成 → 生成 CollaborationPlan → 计划展示给用户确认 → Expert 按计划开始协作
  - **Covered by:** R7, R8, R9, R11

- F3. 去中心化协作执行
  - **Trigger:** CollaborationPlan 确认后开始执行
  - **Actors:** A2, A3, A4
  - **Steps:** Expert 按计划执行各自任务 → Expert 间可直接交互和交接 → 并行节点同时执行 → 结果按合并策略处理 → Lead Expert 汇总最终产出
  - **Covered by:** R16, R17, R18, R20, R21

- F4. 用户干预协作
  - **Trigger:** 用户在对话流中插入指令
  - **Actors:** A1, A4, A2
  - **Steps:** 用户发出指令 → 指令对全体 Expert 可见 → Lead Expert 评估影响 → 修改 CollaborationPlan（如需要） → 受影响 Expert 调整行为
  - **Covered by:** R25, R26, R27, R28

- F5. 竞标式并行执行
  - **Trigger:** CollaborationPlan 中某节点标注为竞标式并行
  - **Actors:** A3, A2
  - **Steps:** 多个同类型 Expert 独立完成同一子任务 → 各自提交结果 → 按评判策略处理（取最优/投票/融合） → 产出最终结果
  - **Covered by:** R21, R22, R23, R24

- F6. 专家团解散
  - **Trigger:** 任务完成或用户主动解散
  - **Actors:** A4, A1
  - **Steps:** Lead Expert 汇总最终结果 → 结果呈现给用户 → 临时 Expert 被回收 → ExpertTeam 销毁 → 模板 Expert 保留在注册中心
  - **Covered by:** R36

## Acceptance Examples

- AE1. **手动组建 + 子任务并行**
  - **Covers R6, R20.** Given 用户输入"帮我分析这份市场报告，叫上数据分析师和战略顾问", When 系统创建 ExpertTeam 并生成计划, Then 数据分析师和战略顾问各自独立分析，Lead Expert 汇总两份分析为统一报告

- AE2. **自动组建 + 竞标并行**
  - **Covers R7, R21, R22.** Given 用户输入一个复杂的技术方案评审任务, When 系统自动升级为专家团模式, Then Lead Expert 生成 3 个架构师 Expert 竞标式并行出方案，Lead Expert 选择最优方案

- AE3. **用户干预调整方向**
  - **Covers R25, R26, R28.** Given 专家团正在执行任务, When 用户在对话流中说"重点看成本优化，别管性能了", Then Lead Expert 修改计划，受影响 Expert 调整分析方向

- AE4. **Expert 间直接协作**
  - **Covers R16, R17.** Given 数据分析师 Expert 需要行业数据, When 数据分析师直接请求行业研究员 Expert 协助, Then 行业研究员提供数据，无需 Lead Expert 中转

- AE5. **动态增减 Expert**
  - **Covers R27.** Given 专家团正在执行, When 用户说"再加一个法律顾问", Then 系统从模板库匹配或动态生成法律顾问 Expert，加入团队并更新计划

## Success Criteria

- 专家团能在 5 分钟内完成一个需要 3+ 专家协作的中等复杂度任务
- 用户能清晰追踪每个 Expert 的工作状态和产出
- 用户干预后，Expert 在 1 轮交互内感知并响应变更
- 临时 Expert 在任务完成后被完全回收，不残留资源

## Scope Boundaries

**Deferred for later:**
- Expert 间的学习与进化机制（经验共享、能力提升）
- 跨会话的 Expert 持久化和记忆共享
- Expert 市场和共享模板库
- 专家团的 A/B 测试和效果评估

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

## Dependencies / Assumptions

- 依赖现有 `AgentPool` 管理 Agent 实例的创建和销毁
- 依赖现有 `MessageBus` 支持 Expert 间的消息通信
- 依赖现有 `HandoffManager` 支持 Expert 间的任务交接（需扩展为进程内模式）
- 依赖现有 `Orchestrator` 的任务分解能力（GoalPlanner + LLM 分解）
- 依赖现有 `PipelineEngine` 的并行执行和拓扑排序
- 假设 LLM 能生成质量合格的 CollaborationPlan（含角色定义、依赖关系、并行标注）
- 假设前端 WebSocket 能支持多路并发消息流

## Outstanding Questions

**Resolve Before Planning:**
- 协作计划的粒度：定义大阶段和角色分工（粗粒度，灵活调整）还是精确到每步操作（细粒度，强约束）
- 协作计划失败时的降级策略：回退到单 Agent 还是重试
- HandoffManager 进程内模式的实现策略：扩展现有 HandoffManager 还是新建 InProcessHandoff

**Deferred to Planning:**
- ExpertTemplate 的 YAML Schema 设计
- 协作计划的可视化组件选型
- 并行消息流的前端渲染策略
- 竞标式并行执行引擎的扩展设计（当前 PipelineEngine 仅支持拓扑排序并行）

## Sources / Research

- `src/agentkit/core/orchestrator.py` — Orchestrator-Worker 编排模式，三级任务分解降级
- `src/agentkit/orchestrator/pipeline_engine.py` — DAG 拓扑并行执行、Saga 补偿、对抗闭环
- `src/agentkit/orchestrator/handoff.py` — Redis Pub/Sub 点对点任务转交
- `src/agentkit/orchestrator/dynamic_pipeline.py` — 条件/嵌套/循环动态 Pipeline
- `src/agentkit/core/agent_pool.py` — 运行时 Agent 实例管理
- `src/agentkit/core/shared_workspace.py` — Redis 共享状态 + 分布式锁
- `src/agentkit/chat/skill_routing.py` — CostAwareRouter 三层路由
- `src/agentkit/skills/base.py` — SkillConfig 定义，ExpertConfig 可参考扩展
