--- 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