docs: U3+U10 更新 AGENTS.md 流水线模式文档 + 计划状态改为 completed
- AGENTS.md: 更新 Expert Team Mode 为 Pipeline 模式，补充 PlanPhase/TeamPlan/topological_sort 说明 - AGENTS.md: 新增 Pipeline Flow、Event Sequence、Team Templates 说明 - AGENTS.md: WebSocket 事件新增 phase_started/phase_completed/phase_failed - AGENTS.md: Conventions 新增专家模板和团队模板配置说明 - 计划文档状态从 active 改为 completed
This commit is contained in:
chiguyong
parent
871e20876f
commit
cdd5212751
34
AGENTS.md
34
AGENTS.md
|
|
@ -77,18 +77,33 @@ BaseAgent (core/base.py) — abstract, execute() is final
|
||||||
+-- StandaloneAgent (core/standalone.py) — standalone runner
|
+-- StandaloneAgent (core/standalone.py) — standalone runner
|
||||||
```
|
```
|
||||||
|
|
||||||
### Expert Team Mode
|
### Expert Team Mode (Pipeline)
|
||||||
|
|
||||||
```
|
```
|
||||||
ExpertConfig (extends AgentConfig) -> Expert (wraps ConfigDrivenAgent via AgentPool)
|
ExpertConfig (extends AgentConfig) -> Expert (wraps ConfigDrivenAgent via AgentPool)
|
||||||
ExpertTeam: manages experts, shared workspace, collaboration plan
|
ExpertTeam: manages experts, shared workspace, team status (FORMING→PLANNING→EXECUTING→SYNTHESIZING→COMPLETED)
|
||||||
TeamOrchestrator: executes plan (serial/parallel/competitive + merge)
|
TeamOrchestrator: pipeline execution — Lead decomposes task into PlanPhase with depends_on, topological sort, parallel layers
|
||||||
CollaborationPlan: phases with dependencies, parallel types, merge strategies
|
PlanPhase: id, name, assigned_expert, task_description, depends_on, status (PENDING/RUNNING/COMPLETED/FAILED)
|
||||||
ExpertTeamRouter: @team prefix routing, name validation, MAX_EXPERTS=10
|
TeamPlan: phases with dependencies, topological_sort() returns execution layers (Kahn's algorithm)
|
||||||
HandoffTransport: InProcess (asyncio.Queue) + Redis Pub/Sub
|
ExpertTeamRouter: @team prefix routing, @team:dev_team template expansion, name validation, MAX_EXPERTS=10
|
||||||
|
HandoffTransport: InProcess (asyncio.Queue) + Redis Pub/Sub — used for event broadcasting only
|
||||||
```
|
```
|
||||||
|
|
||||||
Lifecycle: FORMING -> PLANNING -> EXECUTING -> SYNTHESIZING -> COMPLETED
|
**Pipeline Flow**:
|
||||||
|
1. `@team` prefix triggers team mode (or `@team:dev_team` for template, `@team:expert1,expert2` for explicit)
|
||||||
|
2. `ExpertTeam.create_team()` sets status to PLANNING
|
||||||
|
3. Lead Expert decomposes task into phases via LLM (fallback to single phase on failure)
|
||||||
|
4. `topological_sort()` arranges phases into layers (same-layer parallel, inter-layer serial)
|
||||||
|
5. Each phase creates an isolated `ConfigDrivenAgent` via `AgentPool.create_agent` (context isolation, KTD3)
|
||||||
|
6. Phase outputs passed via `SharedWorkspace` (`{plan_id}/phase/{phase_id}/output`)
|
||||||
|
7. Lead synthesizes results (BEST strategy)
|
||||||
|
8. On all-phases-fail: fallback to single agent mode
|
||||||
|
|
||||||
|
**Event Sequence**: `team_formed` → `plan_update` → `phase_started` → `expert_step` → `expert_result` → `phase_completed` → `team_synthesis` → `team_dissolved`
|
||||||
|
|
||||||
|
**Team Templates**: `configs/experts/dev_team.yaml` stores member list in `bound_skills` field (tech_lead, frontend_engineer, backend_engineer, qa_engineer, code_reviewer)
|
||||||
|
|
||||||
|
Lifecycle: FORMING -> PLANNING -> EXECUTING -> SYNTHESIZING -> COMPLETED -> DISSOLVED
|
||||||
On failure: fallback to single-agent mode (lead or first active expert).
|
On failure: fallback to single-agent mode (lead or first active expert).
|
||||||
|
|
||||||
### Module Map
|
### Module Map
|
||||||
|
|
@ -134,7 +149,7 @@ On failure: fallback to single-agent mode (lead or first active expert).
|
||||||
|
|
||||||
Client -> Server: `message`, `reply`, `confirmation_reply`, `cancel`, `ping`
|
Client -> Server: `message`, `reply`, `confirmation_reply`, `cancel`, `ping`
|
||||||
Server -> Client: `connected`, `token`, `thinking`, `step`, `final_answer`, `skill_match`, `confirmation_request`, `confirmation_result`, `ask_human`, `error`, `pong`
|
Server -> Client: `connected`, `token`, `thinking`, `step`, `final_answer`, `skill_match`, `confirmation_request`, `confirmation_result`, `ask_human`, `error`, `pong`
|
||||||
Expert Team events: `team_formed`, `expert_step`, `expert_result`, `plan_update`, `team_synthesis`, `team_dissolved`
|
Expert Team events: `team_formed`, `expert_step`, `expert_result`, `plan_update`, `phase_started`, `phase_completed`, `phase_failed`, `team_synthesis`, `team_dissolved`
|
||||||
|
|
||||||
### Frontend Pages
|
### Frontend Pages
|
||||||
|
|
||||||
|
|
@ -154,7 +169,8 @@ Config search: `--config` path > `./agentkit.yaml` > `~/.agentkit/agentkit.yaml`
|
||||||
- Skill configs: `configs/skills/*.yaml` (15 presets)
|
- Skill configs: `configs/skills/*.yaml` (15 presets)
|
||||||
- LLM configs: `agentkit.yaml` llm section (unified with server config)
|
- LLM configs: `agentkit.yaml` llm section (unified with server config)
|
||||||
- Pipeline configs: `configs/pipelines/*.yaml`
|
- Pipeline configs: `configs/pipelines/*.yaml`
|
||||||
- Expert templates: registered via `ExpertTemplateRegistry`
|
- Expert templates: `configs/experts/*.yaml` (5 programming experts + dev_team team template), registered via `ExpertTemplateRegistry`
|
||||||
|
- Team templates: `bound_skills` field stores member list (e.g., `dev_team.yaml` lists tech_lead, frontend_engineer, backend_engineer, qa_engineer, code_reviewer)
|
||||||
- All Pydantic models use `model_config = ConfigDict(...)` not `class Config`
|
- All Pydantic models use `model_config = ConfigDict(...)` not `class Config`
|
||||||
- Test files: `tests/unit/` and `tests/integration/`
|
- Test files: `tests/unit/` and `tests/integration/`
|
||||||
- Frontend stores: Pinia, one per domain (chat, team, settings)
|
- Frontend stores: Pinia, one per domain (chat, team, settings)
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,796 @@
|
||||||
|
---
|
||||||
|
title: "feat: @team 流水线模式集成与基线修复"
|
||||||
|
type: feat
|
||||||
|
status: completed
|
||||||
|
created: 2026-06-17
|
||||||
|
completed: 2026-06-18
|
||||||
|
origin: docs/brainstorms/2026-06-17-expert-team-evolution-roadmap-requirements.md
|
||||||
|
requirements: [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] | None`，U5 的 `_get_model` 应读 `expert.config.llm.get("model", "default")` if `llm` else `"default"` |
|
||||||
|
|
||||||
|
### 新增测试场景（补充到 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）：
|
||||||
|
```typescript
|
||||||
|
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）：
|
||||||
|
```typescript
|
||||||
|
| { 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 分支：
|
||||||
|
```typescript
|
||||||
|
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（不修改）
|
||||||
|
- 记忆系统（不修改）
|
||||||
|
- 自进化系统（不修改）
|
||||||
Loading…
Reference in New Issue