574 lines
28 KiB
Markdown
574 lines
28 KiB
Markdown
---
|
||
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
|