fischer-agentkit/docs/plans/2026-06-17-003-feat-team-pipeline-integration-plan.md

title	type	status	created	completed	origin	requirements
feat: @team 流水线模式集成与基线修复	feat	completed	2026-06-17	2026-06-18	docs/brainstorms/2026-06-17-expert-team-evolution-roadmap-requirements.md	R0 R1

feat: @team 流水线模式集成与基线修复

Summary

将 @team 任务分解模式从死代码状态集成到 WebSocket 流程，并修复基线问题。工作分两个阶段：R0 基线修复（修复 ExpertTeamRouter 模板引用 bug、损坏的集成测试、过时的 AGENTS.md 文档），R1 流水线集成（重写 TeamPlan 支持阶段依赖图、重写 TeamOrchestrator 为流水线模式、新增 _execute_team_collab 到 chat.py、新增 5 个编程专家模板、适配前端）。

完成后用户可通过 @team 开发用户登录功能 触发流水线执行（规划 → 前端 → 后端 → QA → 评审），与 @board 群聊讨论模式形成"决策→执行"互补闭环。

---

Problem Frame

当前状态

@team 路由的 ExpertTeamRouter、TeamOrchestrator、ExpertTeam 代码完整但从未被调用（死代码）。chat.py 中 TEAM_COLLAB 执行模式仅记录 warning 并回退到 REACT。此外存在多个基线问题：

1. ExpertTeamRouter 模板引用 bug — resolve_expert_configs 中 template.config 是引用（非 deepcopy），is_lead 赋值会污染共享模板（与 BoardRouter 修复前的 P1 bug 相同）
2. 集成测试损坏 — tests/integration/test_expert_team.py 导入 6 个已移除的类（CollaborationPlan, MergeStrategy, ParallelType, PhaseStatus, PlanPhase），会 ImportError
3. 前后端数据模型不一致 — 后端 TeamPlan.subtasks（扁平）vs 前端 team.ts 的 plan_phases（阶段概念）
4. AGENTS.md 文档过时 — 描述的"CostAwareRouter 三层路由"、"serial/parallel/competitive + merge"已与代码不符
5. TeamOrchestrator 仅 hub-and-spoke — 并行子任务无依赖，不支持流水线串行阶段
6. 硬编码 model="default" — 两处 LLM 调用不读取 ExpertConfig.llm

核心问题

@team 代码完整但不可用，且现有 hub-and-spoke 编排不支持用户选择的流水线模式（对标 Qoder 的 Team Lead + 阶段依赖）。需要重写编排引擎和计划模型，然后集成到 WebSocket。

---

Requirements Traceability

需求 ID	描述	实现单元
R0	修复死代码与前后端不一致	U1, U2, U3
R1.1	流水线编排引擎（阶段依赖图）	U4, U5
R1.2	上下文隔离	U5（内嵌）
R1.3	WebSocket 集成	U6
R1.4	路由支持（@team / @team:experts / @team:dev_team）	U6, U7
R2（部分）	5 个核心编程专家模板	U7

Origin 文档：docs/brainstorms/2026-06-17-expert-team-evolution-roadmap-requirements.md（R0 和 R1 章节）

---

Key Technical Decisions

KTD1: 恢复阶段依赖图（PlanPhase），与前端 plan_phases 对齐

决策：后端恢复 PlanPhase 和 PhaseStatus 类，支持阶段依赖图（depends_on），与前端 team.ts 的 plan_phases 概念自然对齐。

理由：

• 前端已有 plan_phases 和 ITeamPlanPhase 类型，恢复后端阶段概念可避免前端大改
• 流水线模式天然需要"阶段"概念（规划→前端→后端→QA→评审）
• 恢复 PlanPhase 比扩展现有 SubTask 语义更清晰

约束：

• 不恢复 VOTE/FUSION 合并策略（仅保留 BEST）
• 不恢复 ParallelType 枚举（阶段内并行通过 asyncio.gather 隐式实现）
• PlanPhase 包含：id, name, assigned_expert, task_description, depends_on: list[str], status, result

KTD2: 流水线编排逻辑 — Lead 分解为阶段而非子任务

决策：TeamOrchestrator._decompose_task 改为让 Lead Expert 分解任务为阶段（phases），每个阶段有 assigned_expert 和 depends_on。执行时按依赖拓扑排序，无依赖的阶段并行，有依赖的串行。

理由：

• 对标 Qoder 的 Team Lead + 流水线协作
• Lead Expert 用 LLM 生成阶段 JSON（包含 name, assigned_expert, task_description, depends_on）
• 阶段间数据通过 SharedWorkspace 传递（{task_id}/phase/{phase_id}/output）

流程：

1. Lead 分解任务为阶段（LLM 生成 JSON）
2. 拓扑排序阶段（按 depends_on）
3. 按拓扑序执行：同层无依赖阶段并行（asyncio.gather），层间串行
4. 每个阶段完成后，输出写入 SharedWorkspace
5. Lead 汇总所有阶段结果（BEST 策略）

KTD3: 上下文隔离 — 独立 ConfigDrivenAgent 实例

决策：每个阶段执行时创建独立的 ConfigDrivenAgent 实例（通过 AgentPool.create_agent），不共享对话历史。阶段间通过 SharedWorkspace 传递中间产物。

理由：

• 对标 Trae Solo 的独立上下文环境和 Claude Code Subagent 的上下文隔离
• ExpertTeam 中每个 Expert 包装一个 ConfigDrivenAgent，但多个阶段可能分配给同一专家类型
• 为每个阶段创建新实例确保上下文完全隔离
• 阶段输出通过 SharedWorkspace 约定 key 传递：{task_id}/phase/{phase_id}/output

KTD4: WebSocket 事件流扩展

决策：在现有 6 个 team 事件基础上新增 3 个阶段事件。

事件流：

team_formed → plan_update（阶段计划）
→ phase_started → expert_step → expert_result → phase_completed
→ phase_started → expert_step → expert_result → phase_completed
→ ...（按拓扑序）
→ team_synthesis → team_dissolved

新增事件：

• phase_started：{phase_id, phase_name, assigned_expert, depends_on}
• phase_completed：{phase_id, phase_name, result_summary}
• phase_failed：{phase_id, phase_name, error}

KTD5: ExpertTeamRouter 模板引用修复 — deepcopy

决策：resolve_expert_configs 中使用 copy.deepcopy(template.config) 替代 template.config，与 BoardRouter 的 P1 修复保持一致。

理由：ExpertConfig 是普通 Python 类（非 Pydantic），model_copy() 不可用，使用 copy.deepcopy()。

KTD6: TeamStatus 新增 PLANNING 状态（深化审查发现）

决策：后端 TeamStatus 枚举新增 PLANNING = "planning"，在 Lead Expert 分解任务阶段设置。

理由：

• 前端 IExpertTeamState.status 已包含 'planning'（types.ts:141），但后端 TeamStatus（team.py:31-38）缺少此状态
• 流水线模式下，Lead 分解任务为阶段是一个明确的生命周期阶段（FORMING → PLANNING → EXECUTING → SYNTHESIZING → COMPLETED）
• 现有 hub-and-spoke 模式直接从 FORMING 跳到 EXECUTING，流水线模式需要 PLANNING 中间态

约束：

• ExpertTeam.create_team() 后设置 PLANNING
• TeamOrchestrator._decompose_task 完成后、开始执行阶段前设置 EXECUTING

---

Deepening Review Findings（深化审查发现）

已确认的差距（需更新实现单元）

#	发现	位置	影响单元	处理方式
F1	ITeamPlanPhase 缺少 depends_on、task_description、result 字段；parallel_type 和 milestone 应改为可选	types.ts:129-136	U8	显式更新前端类型定义
F2	WsServerMessage 联合类型缺少 phase_started/phase_completed/phase_failed 事件	types.ts:103-108	U8	新增 3 个事件类型到联合类型
F3	前端 chat.ts 的 WebSocket 事件 handler 缺少 phase 事件处理（case 'phase_started' 等）	chat.ts:570-665	U8	新增 3 个 case 分支，更新 teamStore 中对应 phase 的 status
F4	后端 TeamStatus 枚举缺少 PLANNING 状态，与前端 IExpertTeamState.status 不一致	team.py:31-38 vs types.ts:141	U5	新增 PLANNING 枚举值（KTD6）

已确认无需修改（验证通过）

#	验证项	位置	结论
V1	_VALID_TEAM_EVENT_TYPES 是否包含 phase 事件	chat.py:100-120	✅ 已包含 phase_started/phase_completed/phase_failed（line 109-111），U6 只需调用 emit_team_event 使用它们
V2	ExpertTeam.create_team() 签名	team.py:119-123	✅ 确认为 create_team(lead_config, member_configs)，U6 需拆分 configs：首个为 lead，其余为 members
V3	ExpertTeam.workspace 和 handoff_transport 可见性	team.py:88-109	✅ 均为 public property，U5 可直接使用 team.workspace 和 team.handoff_transport
V4	ExpertConfig.llm 字段结构	config.py	✅ 为 `dict[str, Any]

新增测试场景（补充到 U5、U9）

• LLM 分解失败容错：LLM 返回无效 JSON → fallback 到单阶段（[PlanPhase(task=原任务, assigned_expert=lead)]）
• 循环依赖检测：A→B→A 的循环依赖 → topological_sort() 抛出 ValueError
• 无效专家引用：阶段 assigned_expert 引用不存在的专家 → fallback 到 lead 专家
• TeamStatus.PLANNING 状态流转：create_team 后为 PLANNING，分解完成后为 EXECUTING

---

High-Level Technical Design

流水线编排架构

用户输入: @team 开发用户登录功能
    │
    ▼
ExpertTeamRouter.resolve() → 解析专家列表 + 任务
    │
    ▼
ExpertTeam 创建 → 注册 handoff handler
    │
    ▼
TeamOrchestrator.execute(task)
    │
    ├─ 1. 广播 team_formed
    │
    ├─ 2. Lead Expert 分解任务为阶段（LLM）
    │      输出: [
    │        {name: "规划", assigned_expert: "tech_lead", depends_on: []},
    │        {name: "前端", assigned_expert: "frontend_engineer", depends_on: ["规划"]},
    │        {name: "后端", assigned_expert: "backend_engineer", depends_on: ["规划"]},
    │        {name: "QA", assigned_expert: "qa_engineer", depends_on: ["前端", "后端"]},
    │        {name: "评审", assigned_expert: "code_reviewer", depends_on: ["QA"]},
    │      ]
    │
    ├─ 3. 广播 plan_update（阶段计划）
    │
    ├─ 4. 拓扑排序执行:
    │      Layer 0: [规划] (并行)
    │      Layer 1: [前端, 后端] (并行)
    │      Layer 2: [QA]
    │      Layer 3: [评审]
    │
    │      每个阶段:
    │      → phase_started 事件
    │      → 创建独立 ConfigDrivenAgent 实例（上下文隔离）
    │      → 读取前置阶段输出 from SharedWorkspace
    │      → expert_step 事件
    │      → 执行阶段任务
    │      → 写入阶段输出 to SharedWorkspace
    │      → expert_result 事件
    │      → phase_completed 事件
    │
    ├─ 5. Lead Expert 汇总（BEST 策略）
    │
    ├─ 6. 广播 team_synthesis
    │
    └─ 7. 广播 team_dissolved

阶段依赖图数据模型

TeamPlan
├── id: str
├── task: str
├── lead_expert: str
├── status: PlanStatus
└── phases: list[PlanPhase]
         ├── id: str
         ├── name: str
         ├── assigned_expert: str
         ├── task_description: str
         ├── depends_on: list[str]  # 前置阶段 ID
         ├── status: PhaseStatus
         └── result: dict | None

---

Implementation Units

U1. 修复 ExpertTeamRouter 模板引用 bug

Goal: 修复 resolve_expert_configs 中 template.config 引用导致的模板污染问题，与 BoardRouter 的 P1 修复保持一致。

Requirements: R0

Dependencies: 无

Files:

• src/agentkit/experts/router.py — 修改 resolve_expert_configs 方法

Approach:

• 在 router.py 顶部新增 import copy
• resolve_expert_configs 中将 configs.append(template.config) 改为 config = copy.deepcopy(template.config) 然后 configs.append(config)
• 确保 is_lead 赋值不会污染共享模板

Patterns to follow: src/agentkit/experts/board_router.py 的 resolve_expert_configs（已修复相同 bug）

Test scenarios:

• 模板不污染: 连续两次调用 resolve_expert_configs(["a", "b"]) 和 resolve_expert_configs(["b", "a"])，第一次的 is_lead 不被第二次修改
• 动态生成不受影响: 不存在的专家名仍创建动态 ExpertConfig
• Lead 正确设置: 首个专家 is_lead=True，其余 False

Verification: pytest tests/unit/experts/ -k "router" 通过，无模板污染

---

U2. 临时修复集成测试导入

Goal: 修复 tests/integration/test_expert_team.py 的 ImportError，使其能导入并运行（测试内容会在 U9 重写为流水线模式）。

Requirements: R0

Dependencies: U1

Files:

• tests/integration/test_expert_team.py — 修复导入和引用已移除类的测试

Approach:

• 移除对 CollaborationPlan, MergeStrategy, ParallelType, PhaseStatus, PlanPhase 的导入
• 改为导入 TeamPlan, SubTask, SubTaskStatus, PlanStatus
• 将使用 CollaborationPlan 的测试（test_manual_team_subtask_parallel, test_auto_team_competitive_parallel, test_plan_modification_by_user, test_vote_strategy_with_tie_break, test_fusion_strategy, test_plan_failure_triggers_retry, test_fallback_after_retry_failure）改为使用 TeamPlan 或标记为 pytest.mark.skip（U9 会重写）
• 保留不依赖已移除类的测试（TestManualTeamFormation.test_manual_team_with_templates, TestDecentralizedCollaboration, TestUserIntervention.test_user_intervention_broadcast, TestTeamDissolution, TestDynamicExpertManagement）

Test scenarios:

• 导入成功: from agentkit.experts.plan import TeamPlan, SubTask, SubTaskStatus, PlanStatus 不报错
• 保留测试通过: 不依赖已移除类的测试仍通过
• 跳过测试标记: 依赖已移除类的测试标记为 skip 并注明"U9 将重写为流水线模式"

Verification: pytest tests/integration/test_expert_team.py 不再 ImportError，保留测试通过

---

U3. 更新 AGENTS.md 文档

Goal: 更新 AGENTS.md 中与代码不符的描述，确保文档与实际状态一致。

Requirements: R0

Dependencies: 无

Files:

• AGENTS.md — 更新过时描述

Approach:

• "CostAwareRouter 三层路由" → "RequestPreprocessor（@skill 前缀 + 正则快路径 + REACT）"
• "serial/parallel/competitive + merge" → "hub-and-spoke（即将升级为流水线模式）"
• "CollaborationPlan: phases with dependencies, parallel types, merge strategies" → "TeamPlan: phases with dependencies（R1 恢复）"
• "TEAM_COLLAB" 状态更新为"R1 集成后可用"

Test expectation: none — 文档更新无行为变化

Verification: AGENTS.md 中无与代码矛盾的描述

---

U4. 重写 plan.py 恢复阶段依赖图

Goal: 重写 plan.py，恢复 PlanPhase 和 PhaseStatus 类，支持阶段依赖图（depends_on），与前端 plan_phases 概念对齐。

Requirements: R1.1

Dependencies: U2（测试已临时修复）

Files:

• src/agentkit/experts/plan.py — 重写
• tests/unit/experts/test_plan.py — 新增单元测试

Approach:

• 保留现有 MergeStrategy.BEST、PlanStatus、SubTaskStatus、SubTask
• 新增 PhaseStatus 枚举：PENDING, RUNNING, COMPLETED, FAILED
• 新增 PlanPhase dataclass：
  • id, name, assigned_expert, task_description, depends_on: list[str], status, result
  • to_dict() / from_dict() 序列化
• 重写 TeamPlan：
  • 新增 phases: list[PlanPhase] 字段（保留 subtasks 用于向后兼容，但新代码用 phases）
  • 新增 topological_sort() 方法：返回按依赖排序的执行层 list[list[PlanPhase]]
  • 新增 get_ready_phases() 方法：返回当前可执行的阶段（依赖已完成）
  • 新增 update_phase_status() 方法
  • 新增 completed_phases / failed_phases 属性

Patterns to follow: 现有 SubTask dataclass 的序列化模式

Test scenarios:

• 阶段创建: PlanPhase(name="前端", assigned_expert="frontend", depends_on=["规划"]) 正确创建
• 拓扑排序: 3 层依赖（规划→前端+后端→QA）正确排序为 [[规划], [前端, 后端], [QA]]
• 就绪阶段: 初始时只有 规划 就绪；规划 完成后 前端 和 后端 就绪
• 序列化: TeamPlan.to_dict() / from_dict() 往返一致
• 循环依赖检测: A→B→A 的循环依赖抛出 ValueError

Verification: pytest tests/unit/experts/test_plan.py 通过

---

U5. 重写 TeamOrchestrator 为流水线模式

Goal: 重写 TeamOrchestrator，从 hub-and-spoke（并行无依赖）升级为流水线模式（阶段依赖 + 拓扑排序 + 上下文隔离）。

Requirements: R1.1, R1.2

Dependencies: U4（PlanPhase 已实现）

Files:

• src/agentkit/experts/team.py — 新增 TeamStatus.PLANNING 枚举值（KTD6, F4）
• src/agentkit/experts/orchestrator.py — 重写
• tests/unit/experts/test_orchestrator.py — 新增单元测试

Approach:

team.py 修改（KTD6）：

• TeamStatus 枚举新增 PLANNING = "planning"
• create_team() 完成后设置 PLANNING（而非直接 EXECUTING）
• 现有 hub-and-spoke 模式不受影响（PLANNING 状态短暂存在）

_decompose_task 改为分解阶段：

• Lead Expert 用 LLM 生成阶段 JSON（name, assigned_expert, task_description, depends_on）
• 解析为 list[PlanPhase]
• 阶段数上限 MAX_PHASES = 10
• LLM 失败/返回无效 JSON 时 fallback 到单阶段（[PlanPhase(task=原任务, assigned_expert=lead)]）

execute 改为流水线驱动：

1. 广播 team_formed
2. 设置 TeamStatus.PLANNING，Lead 分解任务为阶段
3. 广播 plan_update（含阶段列表）
4. 设置 TeamStatus.EXECUTING，拓扑排序，按层执行：
   • 同层阶段并行（asyncio.gather）
   • 层间串行（等待上一层完成）
   • 每个阶段：广播 phase_started → 创建独立 Agent 实例 → 读取前置输出 → 执行 → 写入输出 → 广播 expert_step/expert_result/phase_completed
5. Lead 汇总（BEST 策略）
6. 广播 team_synthesis 和 team_dissolved

上下文隔离实现：

• _execute_phase 中通过 AgentPool.create_agent 创建独立 ConfigDrivenAgent
• 上下文仅包含：任务描述 + 专家 persona + 前置阶段输出（从 SharedWorkspace 读取）
• 阶段完成后写入 SharedWorkspace：{task_id}/phase/{phase_id}/output
• 使用 team.workspace 和 team.handoff_transport（均为 public property，V3 验证通过）

移除硬编码 model="default"：

• _get_model(expert) 方法：读取 expert.config.llm（V4 验证为 dict[str, Any] | None）
• 逻辑：expert.config.llm.get("model", "default") if expert.config.llm else "default"

新增事件广播（V1 验证：_VALID_TEAM_EVENT_TYPES 已包含这些事件类型，无需修改 chat.py 的 frozenset）：

• phase_started: {phase_id, phase_name, assigned_expert, depends_on}
• phase_completed: {phase_id, phase_name, result_summary}
• phase_failed: {phase_id, phase_name, error}

Fallback 保留：

• 所有阶段失败时 fallback 到单 Agent（现有 _fallback_to_single_agent 逻辑）

Patterns to follow: 现有 TeamOrchestrator._execute_subtask 的事件广播模式

Test scenarios:

• 流水线执行: 3 阶段（A→B→C）按序执行，B 在 A 完成后启动
• 并行阶段: 2 个无依赖阶段并行执行（asyncio.gather）
• 上下文隔离: 阶段 B 的 Agent 实例不包含阶段 A 的对话历史
• SharedWorkspace 传递: 阶段 A 的输出写入 workspace，阶段 B 能读取
• 阶段失败: 阶段 B 失败时，依赖 B 的阶段 C 标记为 FAILED
• 全失败 fallback: 所有阶段失败时 fallback 到单 Agent
• 事件广播: phase_started/phase_completed 事件正确发送
• 模型路由: expert.config.llm 配置的模型被使用（非 "default"）
• LLM 分解失败容错: LLM 返回无效 JSON → fallback 到单阶段（深化审查新增）
• 循环依赖检测: A→B→A 的循环依赖 → topological_sort() 抛出 ValueError（深化审查新增）
• 无效专家引用: 阶段 assigned_expert 引用不存在的专家 → fallback 到 lead 专家（深化审查新增）
• TeamStatus.PLANNING 状态流转: create_team 后为 PLANNING，分解完成后为 EXECUTING（深化审查新增）

Verification: pytest tests/unit/experts/test_orchestrator.py 通过

---

U6. 新增 _execute_team_collab 到 chat.py

Goal: 在 chat.py 中新增 _execute_team_collab 函数，将 @team 路由集成到 WebSocket 流程，参照 _execute_board_meeting 的集成模式。

Requirements: R1.3, R1.4

Dependencies: U5（TeamOrchestrator 已重写）, U7（编程专家模板已创建）

Files:

• src/agentkit/server/routes/chat.py — 新增 _execute_team_collab 函数 + 集成到 WebSocket handler
• tests/unit/server/routes/test_chat_team.py — 新增单元测试

Approach:

_execute_team_collab 函数（参照 _execute_board_meeting 模式）：

1. 从 app.state 获取 ExpertTemplateRegistry
2. 创建 ExpertTeamRouter，调用 resolve(content)
3. 若 not routing_result.matched：返回 False（继续正常管线）
4. 若 not routing_result.task_content：发送错误"团队任务需要一个描述"
5. 调用 resolve_expert_configs 解析专家配置
6. 若无专家配置：发送错误"无法解析团队成员"
7. 创建 ExpertTeam（使用 app.state.agent_pool）
8. 拆分专家配置（V2 验证）：首个为 lead_config，其余为 member_configs，调用 team.create_team(lead_config=..., member_configs=...)
9. 注册 handoff handler 中继事件到 WebSocket（_relay_team_event）— 使用 emit_team_event（V1 验证：_VALID_TEAM_EVENT_TYPES 已包含 phase 事件，无需修改 frozenset）
10. 追加用户消息到会话历史
11. 执行 TeamOrchestrator.execute(task)
12. 发送 final_answer
13. 持久化最终结果到会话历史
14. 清理团队

WebSocket handler 集成：

• 在 WebSocket message handler 中，@board 检查之后、@skill: 检查之前，新增 @team 检查
• if await _execute_team_collab(websocket, session_id, content, sm): return

TEAM_COLLAB 执行模式：

• 移除 chat.py:752-758 的 fallback 到 REACT 逻辑
• TEAM_COLLAB 现在由 _execute_team_collab 处理

Patterns to follow: src/agentkit/server/routes/chat.py 的 _execute_board_meeting（line 155-307）

Test scenarios:

• @team 触发: @team 开发登录功能 调用 _execute_team_collab，返回 True
• 非 @team 输入: 普通消息不触发，返回 False
• 无任务描述: @team 无任务内容时发送错误
• 无专家配置: 所有专家名无效时发送错误
• 事件中继: team_formed/phase_started/expert_step 等事件正确转发到 WebSocket
• final_answer 发送: 执行完成后发送 final_answer 事件
• 会话持久化: 用户消息和最终结果持久化到会话历史
• 团队清理: 执行后 team.dissolve() 被调用
• 与 @board 互不干扰: @board 和 @team 各自独立路由

Verification: pytest tests/unit/server/routes/test_chat_team.py 通过；@team 开发登录功能 在 WebSocket 中端到端可用

---

U7. 新增 5 个核心编程专家模板

Goal: 新增 5 个编程领域专家模板 + 1 个 dev_team.yaml 组合模板，为 @team 流水线提供默认编程团队。

Requirements: R1.4, R2（部分）

Dependencies: 无（可与 U4-U6 并行）

Files:

• configs/experts/tech_lead.yaml — 技术负责人
• configs/experts/frontend_engineer.yaml — 前端工程师
• configs/experts/backend_engineer.yaml — 后端工程师
• configs/experts/qa_engineer.yaml — QA 工程师
• configs/experts/code_reviewer.yaml — 代码审查员
• configs/experts/dev_team.yaml — 默认编程团队组合模板

Approach:

• 每个专家 YAML 包含：name, persona, thinking_style, speaking_style, bound_skills, avatar, color
• tech_lead: 第一性原理思维，架构决策，任务分解，is_lead: true
• frontend_engineer: 组件化思维，UI/UX 敏感，前端测试
• backend_engineer: 系统思维，API 设计，数据库操作
• qa_engineer: 边界思维，测试用例设计，缺陷验证
• code_reviewer: 批判性思维，代码规范，安全漏洞
• dev_team.yaml: 包含 5 个成员列表（tech_lead, frontend_engineer, backend_engineer, qa_engineer, code_reviewer）

Patterns to follow: configs/experts/elon_musk.yaml 的字段结构

Test scenarios:

• 模板加载: 5 个 YAML 文件能被 ExpertTemplateRegistry.load_from_directory 加载
• 专家配置正确: 每个 ExpertConfig 的 persona/thinking_style/bound_skills 非空
• dev_team 组合: dev_team.yaml 包含 5 个成员名
• @team:dev_team 路由: @team:dev_team 开发功能 能解析为 5 个专家

Verification: agentkit skill list 显示新增专家；@team:dev_team 任务 能调用默认团队

---

U8. 适配前端 ExpertTeamView.vue 和 team.ts

Goal: 适配前端组件和 store，确保与后端流水线模式的数据模型一致，正确显示阶段计划、当前阶段、专家步骤。

Requirements: R1.3

Dependencies: U4（PlanPhase 已实现）, U6（WebSocket 事件已定义）

Files:

• src/agentkit/server/frontend/src/api/types.ts — 更新 ITeamPlanPhase 和 WsServerMessage 类型（F1, F2）
• src/agentkit/server/frontend/src/stores/chat.ts — 新增 phase 事件 handler（F3）
• src/agentkit/server/frontend/src/stores/team.ts — 适配数据模型（新增 phase 状态更新方法）
• src/agentkit/server/frontend/src/components/chat/ExpertTeamView.vue — 适配阶段展示

Approach:

types.ts 修改（F1, F2 — 深化审查发现）：

ITeamPlanPhase 更新（F1）：

export interface ITeamPlanPhase {
  id: string
  name: string
  assigned_expert: string
  task_description?: string  // 新增
  depends_on: string[]       // 新增（核心字段，支持流水线依赖图）
  status: 'pending' | 'in_progress' | 'completed' | 'failed'
  result?: string            // 新增（阶段执行结果摘要）
  parallel_type?: 'serial' | 'subtask_parallel' | 'competitive_parallel'  // 改为可选（KTD1 不恢复 ParallelType 枚举）
  milestone?: string         // 改为可选
}

WsServerMessage 新增 3 个事件类型（F2）：

| { type: 'phase_started'; data: { phase_id: string; phase_name: string; assigned_expert: string; depends_on: string[] } }
| { type: 'phase_completed'; data: { phase_id: string; phase_name: string; result_summary: string } }
| { type: 'phase_failed'; data: { phase_id: string; phase_name: string; error: string } }

chat.ts 修改（F3 — 深化审查发现）：

在 team_dissolved case 之前（约 line 655），新增 3 个 case 分支：

case 'phase_started': {
  const teamStore = _getTeamStore()
  if (teamStore?.teamState) {
    teamStore.updatePhaseStatus(payload.phase_id, 'in_progress')
  }
  break
}
case 'phase_completed': {
  const teamStore = _getTeamStore()
  if (teamStore?.teamState) {
    teamStore.updatePhaseStatus(payload.phase_id, 'completed', payload.result_summary)
  }
  break
}
case 'phase_failed': {
  const teamStore = _getTeamStore()
  if (teamStore?.teamState) {
    teamStore.updatePhaseStatus(payload.phase_id, 'failed', payload.error)
  }
  break
}

team.ts 修改：

• 新增 updatePhaseStatus(phaseId: string, status: ITeamPlanPhase['status'], result?: string) 方法
• currentPhase 和 completedPhases 逻辑保持不变（已用 plan_phases）
• 现有 updatePhases(phases) 保持不变（用于 plan_update 事件）

ExpertTeamView.vue 修改：

• 新增阶段状态展示：
  • 当前阶段（status === 'in_progress'）高亮
  • 已完成阶段（status === 'completed'）标记
  • 失败阶段（status === 'failed'）红色标记
  • 阶段间依赖关系可视化（简单的箭头或缩进，基于 depends_on）
• 确认 plan_update 事件正确更新 plan_phases

Patterns to follow: src/agentkit/server/frontend/src/components/chat/BoardStatusView.vue 的状态展示模式

Test scenarios:

• 阶段计划展示: plan_update 事件后，前端显示所有阶段
• 当前阶段高亮: phase_started 事件后，对应阶段高亮
• 阶段完成标记: phase_completed 事件后，对应阶段标记为完成
• 阶段失败标记: phase_failed 事件后，对应阶段标记为失败
• 专家步骤展示: expert_step/expert_result 事件正确关联到阶段
• 类型检查通过: npm run typecheck 无错误（F1, F2 类型更新后）

Verification: npm run typecheck 通过；前端正确展示流水线阶段

---

U9. 重写集成测试覆盖流水线模式

Goal: 重写 tests/integration/test_expert_team.py，覆盖流水线模式的完整功能，替换 U2 中临时跳过的测试。

Requirements: R0, R1

Dependencies: U4（PlanPhase）, U5（TeamOrchestrator）, U6（chat.py 集成）, U7（专家模板）

Files:

• tests/integration/test_expert_team.py — 重写

Approach:

• 移除 U2 中的 pytest.mark.skip 标记
• 重写测试为流水线模式：
  • test_pipeline_execution: 3 阶段（A→B→C）按序执行
  • test_parallel_phases: 2 个无依赖阶段并行
  • test_phase_dependency: 阶段 B 依赖 A，A 失败时 B 标记为 FAILED
  • test_shared_workspace_passing: 阶段 A 输出通过 SharedWorkspace 传递给 B
  • test_context_isolation: 阶段 B 的 Agent 不包含 A 的对话历史
  • test_fallback_on_all_failure: 所有阶段失败时 fallback 到单 Agent
  • test_dev_team_template: @team:dev_team 任务 调用 5 个编程专家
  • test_explicit_experts: @team:frontend_engineer,backend_engineer 任务 调用指定专家
  • test_event_sequence: 事件顺序正确（team_formed → plan_update → phase_started → ... → team_synthesis → team_dissolved）
  • test_llm_decomposition_failure: LLM 返回无效 JSON → fallback 到单阶段（深化审查新增）
  • test_circular_dependency: A→B→A 循环依赖 → topological_sort() 抛出 ValueError（深化审查新增）
  • test_invalid_expert_reference: 阶段引用不存在的专家 → fallback 到 lead（深化审查新增）
  • test_team_status_planning: create_team 后状态为 PLANNING，分解完成后为 EXECUTING（深化审查新增）
• 保留不依赖已移除类的现有测试

Test scenarios:

• 流水线端到端: @team 开发登录功能 触发完整流水线
• 阶段依赖: 依赖阶段在前置完成后才执行
• 并行阶段: 无依赖阶段并行执行
• 上下文隔离: 子任务上下文不污染
• Fallback: 全失败时降级
• 事件序列: 事件顺序正确

Verification: pytest tests/integration/test_expert_team.py 全部通过

---

U10. 端到端验证与文档更新

Goal: 端到端验证 @team 流水线模式可用，更新相关文档。

Requirements: R1

Dependencies: U1-U9 全部完成

Files:

• docs/plans/2026-06-17-003-feat-team-pipeline-integration-plan.md — 更新 status
• AGENTS.md — 更新 @team 状态为"可用"

Approach:

• 启动 agentkit gui --port 8002
• WebSocket 连接，发送 @team 开发用户登录功能
• 验证：team_formed → plan_update → phase_started/phase_completed 序列 → team_synthesis → team_dissolved
• 验证：@board 仍正常工作
• 验证：@team:dev_team 任务 调用默认团队
• 验证：@team:frontend_engineer,backend_engineer 任务 调用指定专家
• 运行 ruff check src/ && ruff format src/
• 运行 pytest -m "not integration" 确保单元测试通过
• 运行 pytest tests/integration/test_expert_team.py 确保集成测试通过
• 运行 npm run typecheck 确保前端类型正确

Test expectation: none — 验证单元

Verification: @team 端到端可用；@board 不受影响；所有测试通过；ruff 清洁

---

Scope Boundaries

本次范围内

• R0: 修复 ExpertTeamRouter 模板引用 bug、集成测试导入、AGENTS.md 文档
• R1: 重写 TeamPlan/TeamOrchestrator 为流水线模式、WebSocket 集成、5 个编程专家模板、前端适配
• 上下文隔离（独立 ConfigDrivenAgent 实例 + SharedWorkspace 传递）

延后到后续工作

• R2 完整版: 额外 3 个可选专家（devops, security, database）
• R3 完整版: 上下文隔离的配置化（agentkit.yaml 中 isolation: context|none）
• R4: 多模型智能路由（消费 ExpertConfig.llm）— 本次仅移除硬编码，完整路由逻辑延后
• R5: 仓库级代码理解
• R6: VS Code 扩展
• git worktree 隔离: v2 路线图已决定延后
• VOTE/FUSION 合并策略: 不恢复，仅保留 BEST

不在产品身份内

• 纯代码补全
• 模型训练/微调
• 100+ 专家模板

---

Risks & Dependencies

风险

1. TeamOrchestrator 重写复杂度高 — 从 hub-and-spoke 到流水线是架构级变更

   • 缓解：U4 先建立数据模型，U5 基于模型重写，分步验证

2. 上下文隔离可能影响 AgentPool — 每个阶段创建新 Agent 实例可能增加资源消耗

   • 缓解：阶段完成后立即销毁 Agent 实例；MAX_PHASES = 10 限制

3. 前端数据模型可能仍有不一致 — ITeamPlanPhase 类型需确认与后端 PlanPhase.to_dict() 完全对齐

   • 已解决（深化审查 F1-F3）：明确 ITeamPlanPhase 需新增 depends_on/task_description/result，WsServerMessage 需新增 3 个 phase 事件，chat.ts 需新增 3 个 case 分支。U8 已显式列出所有前端修改。

4. Lead Expert 分解质量依赖 LLM — 阶段划分可能不合理

   • 缓解：_parse_phases 中验证 depends_on 引用的阶段存在；无效时 fallback 到单阶段（U5 新增 LLM 分解失败容错测试）

依赖

• ExpertTeamRouter 代码已完整（仅需 U1 修复 bug）
• ExpertTeam 代码已完整（无需修改）
• SharedWorkspace 代码已完整（仅需约定 key）
• HandoffTransport 代码已完整（无需修改）
• _execute_board_meeting 提供集成模式参考

---

Open Questions

计划时已解决

• 阶段依赖图设计: 恢复 PlanPhase（KTD1）
• 编排逻辑: Lead 分解为阶段，拓扑排序执行（KTD2）
• 上下文隔离: 独立 ConfigDrivenAgent 实例（KTD3）
• 前后端数据模型: 后端恢复 phases，与前端 plan_phases 对齐（KTD1）
• TeamStatus.PLANNING 状态: 新增枚举值，对齐前端（KTD6, 深化审查 F4）

深化审查已解决

• _VALID_TEAM_EVENT_TYPES 是否包含 phase 事件: 已包含，U6 无需修改 frozenset（V1）
• ExpertTeam.create_team() 签名: 确认为 (lead_config, member_configs)，U6 需拆分 configs（V2）
• ExpertTeam.workspace/handoff_transport 可见性: 均为 public property，U5 可直接使用（V3）
• ExpertConfig.llm 字段结构: 为 dict[str, Any] | None，U5 的 _get_model 逻辑已明确（V4）
• ITeamPlanPhase 缺少 depends_on: U8 显式新增字段（F1）
• WsServerMessage 缺少 phase 事件: U8 显式新增 3 个事件类型（F2）
• 前端 chat.ts 缺少 phase 事件 handler: U8 显式新增 3 个 case 分支（F3）

延后到实现时

• PlanPhase 的精确字段名和类型（U4 实现时确定）
• _parse_phases 的 JSON 解析容错策略（U5 实现时确定）
• AgentPool.create_agent 的资源清理时机（U5 实现时确定）
• ExpertTeamView.vue 的依赖关系可视化样式（U8 实现时确定）

---

System-Wide Impact

受影响组件

组件	影响	说明
src/agentkit/experts/router.py	修改	U1 修复模板引用 bug
src/agentkit/experts/plan.py	重写	U4 恢复阶段依赖图
src/agentkit/experts/team.py	修改	U5 新增 TeamStatus.PLANNING 枚举值（KTD6, F4）
src/agentkit/experts/orchestrator.py	重写	U5 流水线模式
src/agentkit/server/routes/chat.py	修改	U6 新增 _execute_team_collab
configs/experts/	新增	U7 新增 5 个编程专家模板
src/agentkit/server/frontend/src/api/types.ts	修改	U8 更新 ITeamPlanPhase 和 WsServerMessage（F1, F2）
src/agentkit/server/frontend/src/stores/chat.ts	修改	U8 新增 phase 事件 handler（F3）
src/agentkit/server/frontend/src/stores/team.ts	修改	U8 新增 updatePhaseStatus 方法
src/agentkit/server/frontend/src/components/chat/ExpertTeamView.vue	修改	U8 阶段展示
tests/integration/test_expert_team.py	重写	U9 流水线测试
tests/unit/experts/test_plan.py	新增	U4 单元测试
tests/unit/experts/test_orchestrator.py	新增	U5 单元测试
tests/unit/server/routes/test_chat_team.py	新增	U6 单元测试
AGENTS.md	修改	U3 文档更新

不受影响

• @board 群聊讨论模式（完全独立）
• @skill: 路由（独立）
• BoardOrchestrator / BoardTeam / BoardRouter（不修改）
• RequestPreprocessor（不修改）
• LLM Gateway（不修改）
• 记忆系统（不修改）
• 自进化系统（不修改）