# feat: SemanticRouter 启用与回测体系升级

```yaml
title: feat: SemanticRouter 启用与回测体系升级
status: superseded
superseded_by: "2026-06-16-005-refactor-routing-architecture-plan"
superseded_reason: "SimpleRouter 已替代 CostAwareRouter，不再需要 SemanticRouter 作为路由层组件。LLM 在 REACT agent loop 中看到完整工具描述后自主决策，无需 embedding 做意图路由。如未来工具数量 >50，可参考 Codex 的 tool_search（BM25）做工具发现。"
closed: 2026-06-16
```

## Summary

启用 Layer 1.5 SemanticRouter 提升路由召回率，并升级回测体系从"仅测路由层"扩展到"测路由+执行质量"，真正衡量 Agent 智能化程度。

## Problem Frame

当前回测暴露两个核心瓶颈：
1. **关键词匹配 F1 仅 33.33%** — 手工枚举关键词覆盖面极窄，多技能共享关键词导致歧义
2. **回测只测路由层** — 没有验证路由后执行结果的质量，无法衡量真实智能化程度

SemanticRouter 已完整实现（`src/agentkit/chat/semantic_router.py`），但配置未启用（`agentkit.yaml` 中 `router.semantic` 段不存在）。启用后，关键词未命中的查询可走向量相似度匹配，预期 F1 大幅提升。

## Requirements

- R1: 启用 SemanticRouter，使回测中关键词未命中的查询有语义路由兜底
- R2: 回测体系增加 L3 输出质量评估 — 路由后实际执行，评估输出与预期的语义相似度
- R3: 回测体系增加 L5 自适应能力测试 — 同一意图不同表达（正式/口语/中英混合）
- R4: 生成对比报告：SemanticRouter 启用前 vs 启用后

## Key Technical Decisions

### KTD-1: SemanticRouter 阈值选择

默认阈值 similarity_high=0.85 / similarity_low=0.6。回测中先使用默认值，根据结果微调。

理由：0.85 高阈值确保高置信度匹配的精确性，0.6 低阈值过滤噪声。这是业内常见配置。

### KTD-2: L3 输出质量评估方法

使用 LLM-as-Judge 方案：将路由后的执行输出与预期输出传给 LLM，让 LLM 评估语义相似度（1-5分）。

理由：BLEU/ROUGE 等字面匹配指标不适合评估 Agent 输出的语义质量。LLM-as-Judge 是业内主流方案（OpenAI、Anthropic 均采用）。

### KTD-3: L3 评估范围

仅对 keyword_match 和 semantic_match 类别的用例执行 L3 评估。DIRECT_CHAT 类别（问候/闲聊）不需要执行质量评估。

理由：DIRECT_CHAT 的输出质量主要取决于 LLM 本身，与路由无关。评估路由对执行质量的影响才是目标。

## Implementation Units

### U1. 启用 SemanticRouter 并集成到回测

**Goal:** 在回测中构建并启用 SemanticRouter，使 Layer 1.5 语义路由生效

**Requirements:** R1

**Dependencies:** 无

**Files:**
- `tests/e2e/test_capability_router_direct.py` — 构建 SemanticRouter 并传入 CostAwareRouter
- `agentkit.yaml` — 添加 `router.semantic.enabled: true` 配置

**Approach:**
1. 在 `_build_real_components()` 中构建 SemanticRouter：从 LLMGateway 获取 embedder，构建索引
2. 将 semantic_router 传入 CostAwareRouter 构造函数
3. 在 `agentkit.yaml` 中添加 semantic 配置段
4. 回测结果中记录 match_method 为 "semantic_high" / "semantic_medium" 的用例

**Test scenarios:**
- 运行回测，验证 SemanticRouter 成功构建索引（15个技能）
- 验证 match_method 包含 "semantic_high" 或 "semantic_medium" 的用例
- 验证关键词未命中的用例中，部分被 SemanticRouter 兜底匹配

**Verification:** 回测通过，keyword_match F1 提升，出现 semantic_match 类别

### U2. 增加语义路由专项测试

**Goal:** 验证 SemanticRouter 在各种查询模式下的表现

**Requirements:** R1

**Dependencies:** U1

**Files:**
- `tests/e2e/test_capability_router_direct.py` — 增加 semantic routing 测试类

**Approach:**
1. 新增 `TestSemanticRouting` 测试类
2. 测试场景：同义词查询、口语化表达、中英混合、技能描述相关查询
3. 每个测试记录 match_method 和 confidence

**Test scenarios:**
- "帮我看看代码有没有问题" → 匹配 code_reviewer（语义匹配）
- "市场怎么样" → 匹配 trend_agent 或 competitor_analyzer（语义匹配）
- "写一篇关于AI的文章" → 匹配 content_generator（语义匹配）
- "这个引用对不对" → 匹配 citation_detector（语义匹配）

**Verification:** 语义路由测试通过，match_method 包含 "semantic_*"

### U3. L3 输出质量评估框架

**Goal:** 构建输出质量评估框架，路由后实际执行并评估输出质量

**Requirements:** R2

**Dependencies:** U1

**Files:**
- `tests/e2e/capability_metrics.py` — 增加 OutputQualityObservation 和评估方法
- `tests/e2e/test_capability_router_direct.py` — 增加 L3 评估逻辑

**Approach:**
1. 新增 `OutputQualityObservation` 数据类：query, expected_output, actual_output, quality_score(1-5), judge_reasoning
2. 新增 `evaluate_output_quality()` 方法：使用 LLM-as-Judge 评估
3. L3 评估仅对 keyword_match 和 semantic_match 类别执行
4. 报告增加"输出质量评估"章节

**Test scenarios:**
- 路由到 code_reviewer 的查询，输出应包含代码审查相关内容
- 路由到 content_generator 的查询，输出应包含生成内容
- 路由失败的查询，不执行 L3 评估

**Verification:** 报告包含输出质量评分，平均分 > 3.0

### U4. L5 自适应能力测试

**Goal:** 测试同一意图不同表达的路由稳定性

**Requirements:** R3

**Dependencies:** U1

**Files:**
- `tests/e2e/benchmark_dataset.py` — 增加自适应测试用例
- `tests/e2e/test_capability_router_direct.py` — 增加自适应测试类

**Approach:**
1. 选取 5 个核心技能，每个技能设计 3 种表达变体：正式/口语/中英混合
2. 同一技能的 3 种表达应路由到同一技能
3. 计算自适应率：同一技能不同表达路由一致的比例

**Test scenarios:**
- code_reviewer: "审查代码" / "帮我看看代码" / "review this code"
- trend_agent: "分析趋势" / "最近行情怎么样" / "market trend analysis"
- content_generator: "生成内容" / "帮我写点东西" / "write an article"
- citation_detector: "检测引用" / "引用对不对" / "check citations"
- competitor_analyzer: "竞品分析" / "对手怎么样" / "competitor analysis"

**Verification:** 自适应率 > 60%（5个技能 x 3种表达 = 15个用例，至少9个路由一致）

### U5. 对比报告与基准更新

**Goal:** 生成 SemanticRouter 启用前后的对比报告，更新基准

**Requirements:** R4

**Dependencies:** U1, U2, U3, U4

**Files:**
- `tests/e2e/capability_metrics.py` — 增加对比报告生成
- `test-results/e2e/capability_report.txt` — 更新报告

**Approach:**
1. 运行完整回测（含 SemanticRouter）
2. 与启用前基准对比：执行模式准确率、技能路由F1、keyword_match F1
3. 报告增加"SemanticRouter 效果对比"章节
4. 报告增加"L3 输出质量"和"L5 自适应能力"章节

**Verification:** 报告包含前后对比数据，技能路由F1 > 80%

## Scope Boundaries

### In Scope
- 启用 SemanticRouter
- L3 输出质量评估（LLM-as-Judge）
- L5 自适应能力测试
- 对比报告生成

### Out of Scope
- L4 对话连贯性测试（多轮对话，需要会话管理改造）
- L6 压力边界测试（模糊/对抗输入，需要专门的对抗测试框架）
- 意图分类微调（需要标注数据和训练流程）
- 关键词自动扩充（从 examples 提取高频词）

### Deferred to Follow-Up Work
- 多轮对话回测框架
- 对抗性输入测试
- 意图分类微调流水线
- 关键词自动扩充工具
- **[待办] 提供 Embedding API Key** — 当前百炼 Coding Plan key (sk-sp-*) 不支持 embedding API，需要：
  - 方案 A：在 DashScope 控制台单独开通 embedding 服务，获取标准 sk- 前缀 key
  - 方案 B：配置本地 embedding 模型（BGE-large-zh-v1.5 via Xinference）
  - 方案 C：使用其他支持 embedding 的 provider（智谱/火山等）
  - 配置位置：agentkit.yaml → llm.providers 增加 embedding 专用 provider
  - 预期效果：SemanticRouter 真正工作，口语化查询无需手动扩充关键词

## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Embedding API 不可用 | Medium | High | 回测跳过 SemanticRouter，降级到纯关键词路由 |
| LLM-as-Judge 评分不稳定 | Medium | Medium | 多次评估取平均，使用结构化评分 prompt |
| SemanticRouter 阈值需调优 | High | Low | 先用默认值，根据回测结果微调 |