---
title: "feat: E2E能力分析框架改进与路由智能化提升"
type: feat
status: superseded
superseded_by: "2026-06-16-005-refactor-routing-architecture-plan"
superseded_reason: "路由智能化提升部分已被 SimpleRouter 架构简化替代。E2E 能力分析框架部分可合并到 2026-06-16-005 的 U5 回测验证单元。"
closed: 2026-06-16
created: 2026-06-15
plan-depth: standard
---

# E2E能力分析框架改进与路由智能化提升

## Summary

改进E2E能力分析框架，解决当前基准数据集与实际技能不对应、覆盖面窄（仅19条）、指标判断过于简化等核心问题。同时将ExpertTeamRouter集成到CostAwareRouter自动触发链路，增加路由器直接回测层，并将基准用例扩展至60条，使召回率/F1/过拟合检测等指标具备统计意义。

## Problem Frame

当前E2E能力分析框架存在四个关键问题：

1. **基准数据与实际技能脱节**：`benchmark_dataset.py` 中的 `expected_skill`（如 `email_composer`、`i18n_translator`）与 `configs/skills/` 中的15个实际技能不对应，导致路由回测结果无意义
2. **覆盖面过窄**：仅19条基准用例，PRF统计不稳定；缺少 SemanticRouter、ExpertTeamRouter、AlignmentGuard 的专项基准
3. **指标判断粗糙**：`complexity_correct` 直接等于 `execution_mode_correct`，无法独立评估复杂度估算；改进策略中的 `target_module` 引用了旧文件名
4. **团队路由未自动集成**：`ExpertTeamRouter` 与 `CostAwareRouter` 独立运行，`TEAM_COLLAB` 模式无法自动触发

## Requirements

- R1: 基准数据集中的 `expected_skill` 必须与 `configs/skills/` 中的实际技能一一对应
- R2: 基准用例数量扩展至60条，覆盖路由/执行/团队/一致性/对齐守卫五个维度
- R3: 增加路由器直接回测层（不经过HTTP API），能区分路由错误与API层错误
- R4: `complexity_correct` 独立于 `execution_mode_correct`，基于 HeuristicClassifier 分数与期望复杂度的映射判断
- R5: ExpertTeamRouter 集成到 CostAwareRouter.route() 中，高复杂度任务自动触发 TEAM_COLLAB
- R6: 增加 SemanticRouter 专项基准（相似度分数分布、三档精确率）
- R7: 增加 AlignmentGuard 约束检查基准
- R8: 修正改进策略中的 target_module 文件路径
- R9: 报告输出保持中文

## Key Technical Decisions

### KTD1: 双层回测架构

**决策**：在现有HTTP API层E2E测试之上，增加路由器直接回测层。

**理由**：纯API测试无法区分"路由器选错了技能"和"API层传递参数出错"两种失败模式。直接回测层调用 `CostAwareRouter.route()` 方法，记录 `SkillRoutingResult` 的完整字段（`match_method`、`match_confidence`、`execution_trace`），使根因分析能精确定位到具体路由层。

**替代方案**：保持纯API层测试 → 被否决，因为无法满足R3的精确诊断需求。

### KTD2: ExpertTeamRouter 集成方式

**决策**：在 `CostAwareRouter._route_layer2()` 末尾增加 ExpertTeamRouter 检查点。当 Layer 2 判定 `execution_mode=REACT` 且 `complexity >= 0.7` 时，调用 `ExpertTeamRouter.resolve()` 判断是否升级为 `TEAM_COLLAB`。

**理由**：保持三层路由的递进式架构不变，仅在 Layer 2 出口处增加团队模式升级逻辑，最小化对现有路由流程的侵入。

### KTD3: 复杂度正确性判断策略

**决策**：基于 HeuristicClassifier 返回的浮点复杂度分数与期望复杂度等级的映射区间判断：`low=[0, 0.3)`、`medium=[0.3, 0.7)`、`high=[0.7, 1.0]`。

**理由**：直接使用浮点分数比仅比较执行模式更精确，能区分"复杂度分数0.29被判为low但期望medium"和"复杂度分数0.65被判为medium且期望medium"两种情况。

### KTD4: 基准用例与实际技能对齐

**决策**：从 `configs/skills/` 的15个实际技能中提取 `intent.keywords` 和 `intent.description`，自动生成基准用例的 `expected_skill`，而非手动硬编码。

**理由**：手动维护的技能名容易与实际配置脱节（当前问题）。自动对齐确保基准数据始终反映最新的技能配置。

---

## Implementation Units

### U1. 基准数据集与实际技能对齐

**Goal**: 修复 benchmark_dataset.py 中 expected_skill 与实际技能的对应关系，扩展至60条用例

**Dependencies**: 无

**Files**:
- `tests/e2e/benchmark_dataset.py` — 重写基准数据集
- `tests/e2e/benchmark_generator.py` — 新增：从技能配置自动生成基准用例

**Approach**:
1. 新增 `BenchmarkGenerator` 类，读取 `configs/skills/*.yaml`，提取每个技能的 `intent.keywords`、`intent.description`、`intent.examples`，自动生成 `BenchmarkCase`
2. 为每个技能生成3-5条基准用例：1条原始输入 + 2-4条改写
3. 保留手动定义的边界用例（问候语、身份识别、无匹配回退）
4. 新增维度：`alignment`（对齐守卫）、`semantic_router`（语义路由专项）
5. 总目标：路由20+、执行15+、团队10+、一致性10+、对齐守卫5+

**Patterns to follow**: `BenchmarkCase` Pydantic frozen model 模式

**Test scenarios**:
- 生成的基准用例 expected_skill 全部存在于 configs/skills/ 中
- 每个技能至少有1条基准用例
- paraphrases 非空的用例占比 > 60%
- 总用例数 >= 60

**Verification**: 运行 `python -c "from tests.e2e.benchmark_dataset import ALL_BENCHMARKS; print(len(ALL_BENCHMARKS))"` 确认 >= 60

### U2. 路由器直接回测层

**Goal**: 增加不经过HTTP API的路由器直接回测，记录完整路由结果

**Dependencies**: U1

**Files**:
- `tests/e2e/test_capability_router_direct.py` — 新增：路由器直接回测
- `tests/e2e/conftest.py` — 增加 router fixture

**Approach**:
1. 在 conftest.py 中增加 `cost_aware_router` fixture，直接实例化 `CostAwareRouter`（使用 MockLLMProvider）
2. 新增 `test_capability_router_direct.py`，对每个基准用例调用 `router.route(query)` 并记录完整 `SkillRoutingResult`
3. 记录字段：`skill_name`、`execution_mode`、`complexity`、`match_method`（layer0/layer1/layer1.5/layer2）、`match_confidence`、`execution_trace`
4. 将路由器回测结果也写入 MetricsCollector，增加 `match_method` 和 `match_confidence` 字段

**Patterns to follow**: 现有 `test_capability_routing.py` 的参数化测试模式

**Test scenarios**:
- Layer 0 规则匹配：问候语 → DIRECT_CHAT，@skill:xxx → 对应技能
- Layer 1 复杂度分类：简单问答 → low，多步分析 → high
- Layer 1.5 语义路由：同义改写 → 相同技能，相似度 > 0.6
- Layer 2 能力匹配：高复杂度 → REACT/TEAM_COLLAB
- 路由器回测与API回测结果一致性 > 90%

**Verification**: 运行 `pytest tests/e2e/test_capability_router_direct.py -v` 全部通过

### U3. 指标体系增强

**Goal**: 修复 complexity_correct 判断逻辑，增加语义路由/团队路由指标，修正 target_module 路径

**Dependencies**: U1

**Files**:
- `tests/e2e/capability_metrics.py` — 增强指标模型和分析器
- `tests/e2e/benchmark_dataset.py` — 增加 semantic_router / alignment 类别

**Approach**:
1. `CapabilityObservation` 增加 `actual_complexity_score: float | None`、`actual_match_method: str | None`、`actual_match_confidence: float | None` 字段
2. `complexity_correct` 改为基于分数区间映射判断（KTD3）
3. `MetricsAnalyzer` 增加 `analyze_semantic_router()` 方法：按 high/medium/low 三档统计精确率
4. `MetricsAnalyzer` 增加 `analyze_team_routing()` 方法：统计 `explicit_team` vs `complexity_suggestion` 的成功率
5. 修正 `plan_improvements()` 中所有 `target_module`：`cost_aware_router.py` → `chat/skill_routing.py`
6. 报告增加"语义路由分析"和"团队路由分析"章节

**Patterns to follow**: 现有 `MetricsAnalyzer` 的分析方法模式

**Test scenarios**:
- complexity_correct 独立于 execution_mode_correct
- 语义路由三档精确率计算正确
- 团队路由成功率计算正确
- target_module 路径与实际代码对应
- 中文报告输出包含新增章节

**Verification**: 运行 `pytest tests/e2e/test_capability_routing.py tests/e2e/test_capability_react.py -v` 通过

### U4. ExpertTeamRouter 集成到 CostAwareRouter

**Goal**: 高复杂度任务自动触发 TEAM_COLLAB 模式

**Dependencies**: U2

**Files**:
- `src/agentkit/chat/skill_routing.py` — 修改 `_route_layer2()` 增加团队升级逻辑
- `src/agentkit/experts/router.py` — 增加 `can_handle()` 方法供路由器查询
- `tests/unit/chat/test_skill_routing.py` — 增加团队路由单元测试

**Approach**:
1. 在 `CostAwareRouter._route_layer2()` 末尾，当 `execution_mode == REACT` 且 `complexity >= COMPLEXITY_THRESHOLD` 时，调用 `ExpertTeamRouter.resolve(content, complexity)`
2. 如果 `ExpertTeamRouter` 返回有效结果，升级 `execution_mode` 为 `TEAM_COLLAB`，并在 `execution_trace` 中记录 `"team_upgrade": True`
3. 在 `ExpertTeamRouter` 中增加 `can_handle(content: str) -> bool` 方法，检查是否有匹配的专家模板
4. 保持向后兼容：如果 `ExpertTeamRouter` 不可用（未配置专家模板），静默跳过

**Patterns to follow**: 现有 `_route_layer2()` 的 Vickrey 拍卖路径模式

**Test scenarios**:
- 高复杂度 + 有专家模板 → TEAM_COLLAB
- 高复杂度 + 无专家模板 → 保持 REACT
- 低复杂度 → 不触发团队路由
- @team 前缀 → 直接 TEAM_COLLAB（Layer 0 处理）
- execution_trace 包含 team_upgrade 标记

**Verification**: 运行 `pytest tests/unit/chat/test_skill_routing.py -v -k team` 通过

### U5. AlignmentGuard 与 CascadeDetector 指标集成

**Goal**: 将对齐守卫约束违规和级联告警纳入E2E指标收集

**Dependencies**: U3

**Files**:
- `tests/e2e/test_capability_alignment.py` — 新增：对齐守卫基准测试
- `tests/e2e/capability_metrics.py` — 增加 alignment 维度指标

**Approach**:
1. 新增 `test_capability_alignment.py`，包含5+条对齐守卫基准用例：
   - 否定约束测试（"不要提及价格"→ 输出不含价格）
   - 肯定约束测试（"必须包含摘要"→ 输出含摘要）
   - 级联告警测试（连续5次相似查询 → 触发 CascadeAlert）
2. `CapabilityObservation` 增加 `alignment_violations: int`、`cascade_alert: bool` 字段
3. `MetricsAnalyzer` 增加 `analyze_alignment()` 方法
4. 报告增加"对齐守卫分析"章节

**Patterns to follow**: 现有 `test_capability_team.py` 的测试模式

**Test scenarios**:
- 否定约束：输出不包含禁止内容
- 肯定约束：输出包含必要内容
- 级联告警：连续交互触发告警
- 无约束：正常通过

**Verification**: 运行 `pytest tests/e2e/test_capability_alignment.py -v` 通过

### U6. 运行脚本与CI集成

**Goal**: 更新运行脚本，支持分层回测和CI集成

**Dependencies**: U2, U3, U4, U5

**Files**:
- `scripts/run_e2e.sh` — 增加直接回测和分层运行选项
- `tests/e2e/conftest.py` — 确保 pytest_sessionfinish 报告生成正确

**Approach**:
1. `run_e2e.sh` 增加 `--direct` 选项（仅运行路由器直接回测）
2. `run_e2e.sh` 增加 `--alignment` 选项（仅运行对齐守卫测试）
3. `run_e2e.sh` 增加 `--full` 选项（运行全部：API + 直接 + 对齐）
4. 确保报告输出目录 `test-results/e2e/` 在 CI 中作为 artifact 上传
5. 增加 `--baseline` 选项：与上次报告对比，输出指标变化趋势

**Patterns to follow**: 现有 `run_e2e.sh` 的选项模式

**Test scenarios**:
- `--direct` 仅运行路由器直接回测
- `--alignment` 仅运行对齐守卫测试
- `--full` 运行所有能力测试
- `--analyze` 生成完整中文报告
- 报告文件正确保存到 test-results/e2e/

**Verification**: 运行 `./scripts/run_e2e.sh --direct` 和 `./scripts/run_e2e.sh --analyze` 验证

---

## Scope Boundaries

### In Scope
- 基准数据集与实际技能对齐并扩展至60条
- 路由器直接回测层
- 指标体系增强（复杂度、语义路由、团队路由）
- ExpertTeamRouter 集成到 CostAwareRouter
- AlignmentGuard 指标集成
- 运行脚本更新

### Out of Scope
- CostAwareRouter 三层架构重写
- 新增 LLM Provider
- 前端界面修改
- 生产环境部署
- intent.examples 嵌入到 SemanticRouter（可作为后续优化）
- disambiguation_keywords 配置字段（改进策略已规划，但属于技能配置层面的独立改进）

### Deferred to Follow-Up Work
- 基于用户真实查询日志的基准用例持续扩充
- 复杂度评估模型训练（替代启发式规则）
- 意图泛化CI防线的 GitHub Actions 配置
- OutputStandardizer.quality_score 与路由决策的关联分析

---

## Risks & Mitigations

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| ExpertTeamRouter 集成可能影响现有路由性能 | Layer 2 增加一次 resolve() 调用 | 仅在 complexity >= 0.7 时触发，且 can_handle() 快速返回 |
| 基准用例自动生成可能产生低质量用例 | PRF 指标失真 | 人工审核自动生成的用例，保留手动边界用例 |
| 路由器直接回测需要 MockLLMProvider 完整支持 | 某些路由路径无法测试 | 优先覆盖 Layer 0/1，Layer 1.5/2 标记为需要真实 LLM |
| 60条用例可能增加E2E运行时间 | CI 流水线变慢 | 按维度分组运行，支持 `--fast` 快速失败模式 |

---

## System-Wide Impact

- **路由层**：`skill_routing.py` 增加 ExpertTeamRouter 调用点，影响所有高复杂度请求的路由决策
- **测试层**：新增3个测试文件，conftest.py 增加2个 fixture，运行脚本增加4个选项
- **报告层**：能力分析报告增加3个章节（语义路由、团队路由、对齐守卫）
- **配置层**：无配置文件变更（disambiguation_keywords 推迟到后续）