---
feature_id: "AISVC"
iteration_id: "v0.8.0-intent-hybrid-routing"
title: "意图识别混合路由优化 - 任务清单"
status: "draft"
version: "0.8.0"
created_at: "2026-03-08"
inputs:
  - "spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/requirements.md"
  - "spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/design.md"
---

# 意图识别混合路由优化 - Tasks（v0.8.0）

## 1. 任务拆分原则

- **原子性**：每个任务仅解决一个具体技术点或功能逻辑
- **可验证性**：任务完成后必须可通过单元测试、接口冒烟或契约校验
- **弱模型可执行**：任务描述清晰，不依赖 AI 猜测业务逻辑
- **AC 关联**：每个任务关联明确的验收标准 ID

---

## 2. 任务状态说明

- ⏳ 待处理
- 🔄 进行中
- ✅ 已完成
- ❌ 已取消

---

## 3. 任务执行计划

### Phase 17.1: 数据模型扩展

- [ ] T17.1 扩展 `IntentRule` 实体：新增 `intent_vector`（JSONB）、`semantic_examples`（JSONB）字段 `[AC-AISVC-114]`
  - 修改文件: `app/models/entities.py`
  - 新增字段定义与注释
  - 数据库迁移: `alembic revision --autogenerate -m "add_intent_vector_fields"`

- [ ] T17.2 创建 `FusionConfig` 配置模型：定义融合权重与阈值参数 `[AC-AISVC-116]`
  - 新增文件: `app/services/intent/models.py`
  - 定义 `FusionConfig` dataclass

- [ ] T17.3 创建 `RouteTrace` 追踪模型：定义三路打分日志结构 `[AC-AISVC-122]`
  - 修改文件: `app/services/intent/models.py`
  - 定义 `RouteTrace`、`FusionResult` 等 dataclass

- [ ] T17.4 扩展 `ChatMessage` 实体：新增 `route_trace`（JSONB）字段 `[AC-AISVC-123]`
  - 修改文件: `app/models/entities.py`
  - 数据库迁移: `alembic revision --autogenerate -m "add_route_trace_field"`

---

### Phase 17.2: RuleMatcher 改造

- [ ] T17.5 创建 `RuleMatchResult` 数据类：封装规则匹配结果（含 score） `[AC-AISVC-112]`
  - 修改文件: `app/services/intent/models.py`
  - 定义 `RuleMatchResult` dataclass

- [ ] T17.6 改造 `IntentRouter` 为 `RuleMatcher`：增加 score 输出，保留 `match()` 向后兼容 `[AC-AISVC-112]`
  - 修改文件: `app/services/intent/router.py`
  - 重构现有匹配逻辑，封装为 `RuleMatcher` 类
  - 输出 `RuleMatchResult` 而非 `IntentMatchResult`

---

### Phase 17.3: SemanticMatcher 实现

- [ ] T17.7 实现 `SemanticMatcher` 类：初始化方法，注入 EmbeddingProvider 和配置 `[AC-AISVC-113]`
  - 新增文件: `app/services/intent/semantic_matcher.py`
  - 定义 `SemanticMatcher` 类
  - 实现 `__init__` 方法

- [ ] T17.8 实现 `SemanticMatcher.match()`：模式 A（预置向量）相似度计算 `[AC-AISVC-114]`
  - 修改文件: `app/services/intent/semantic_matcher.py`
  - 实现 `_calculate_similarity` 方法
  - 实现 `_cosine_similarity` 方法

- [ ] T17.9 实现 `SemanticMatcher.match()`：模式 B（示例句动态计算）平均相似度 `[AC-AISVC-114]`
  - 修改文件: `app/services/intent/semantic_matcher.py`
  - 支持从 `semantic_examples` 动态计算向量

- [ ] T17.10 实现 `SemanticMatcher` 异常处理：Embedding/Qdrant 失败时跳过并记录原因 `[AC-AISVC-113]`
  - 修改文件: `app/services/intent/semantic_matcher.py`
  - 添加超时控制
  - 添加异常捕获与日志记录

---

### Phase 17.4: LlmJudge 实现

- [ ] T17.11 实现 `LlmJudge` 类：初始化方法，注入 LLMClient 和配置 `[AC-AISVC-119]`
  - 新增文件: `app/services/intent/llm_judge.py`
  - 定义 `LlmJudge` 类
  - 定义 `JUDGE_PROMPT` 模板

- [ ] T17.12 实现 `LlmJudge.should_trigger()`：判断是否满足触发条件（冲突/灰区/多意图） `[AC-AISVC-118]`
  - 修改文件: `app/services/intent/llm_judge.py`
  - 实现三种触发条件判断

- [ ] T17.13 实现 `LlmJudge.judge()`：构建仲裁 Prompt，调用 LLM，解析结果 `[AC-AISVC-119]`
  - 修改文件: `app/services/intent/llm_judge.py`
  - 实现 `_build_candidates_text` 方法
  - 实现 `_parse_response` 方法

- [ ] T17.14 实现 `LlmJudge` 异常处理：LLM 调用失败时回退到 SemanticMatcher `[AC-AISVC-119]`
  - 修改文件: `app/services/intent/llm_judge.py`
  - 添加超时控制
  - 添加异常捕获与日志记录

---

### Phase 17.5: FusionPolicy 实现

- [ ] T17.15 实现 `FusionPolicy` 类：初始化方法，加载配置 `[AC-AISVC-115]`
  - 新增文件: `app/services/intent/fusion_policy.py`
  - 定义 `FusionPolicy` 类
  - 定义 `DECISION_PRIORITY` 常量

- [ ] T17.16 实现 `FusionPolicy.fuse()`：加权融合计算 `[AC-AISVC-116]`
  - 修改文件: `app/services/intent/fusion_policy.py`
  - 实现 `_calculate_weighted_confidence` 方法

- [ ] T17.17 实现 `FusionPolicy.fuse()`：决策优先级判定（规则优先→语义→LLM→无匹配） `[AC-AISVC-117]`
  - 修改文件: `app/services/intent/fusion_policy.py`
  - 实现优先级遍历与条件判断

- [ ] T17.18 实现 `FusionPolicy.fuse()`：澄清触发判定 `[AC-AISVC-121]`
  - 修改文件: `app/services/intent/fusion_policy.py`
  - 判断 `final_confidence < clarify_threshold`
  - 生成 `clarify_candidates` 列表

- [ ] T17.19 实现 `FusionPolicy.fuse()`：路由追踪日志生成 `[AC-AISVC-122]`
  - 修改文件: `app/services/intent/fusion_policy.py`
  - 构建 `RouteTrace` 对象
  - 记录三路打分详情

---

### Phase 17.6: IntentRouter 升级

- [ ] T17.20 升级 `IntentRouter`：注入 RuleMatcher、SemanticMatcher、LlmJudge、FusionPolicy `[AC-AISVC-111]`
  - 修改文件: `app/services/intent/router.py`
  - 修改 `__init__` 方法
  - 支持依赖注入

- [ ] T17.21 实现 `IntentRouter.match_hybrid()`：并行执行 RuleMatcher + SemanticMatcher `[AC-AISVC-111]`
  - 修改文件: `app/services/intent/router.py`
  - 使用 `asyncio.gather` 并行执行

- [ ] T17.22 实现 `IntentRouter.match_hybrid()`：条件触发 LlmJudge `[AC-AISVC-118]`
  - 修改文件: `app/services/intent/router.py`
  - 调用 `LlmJudge.should_trigger()`
  - 条件执行 `LlmJudge.judge()`

- [ ] T17.23 实现 `IntentRouter.match_hybrid()`：调用 FusionPolicy 返回融合结果 `[AC-AISVC-115]`
  - 修改文件: `app/services/intent/router.py`
  - 调用 `FusionPolicy.fuse()`
  - 返回 `FusionResult`

---

### Phase 17.7: Orchestrator 集成

- [ ] T17.24 修改 `Orchestrator._match_intent()`：调用 `match_hybrid()` 替代 `match()` `[AC-AISVC-111]`
  - 修改文件: `app/services/orchestrator.py`
  - 替换方法调用
  - 处理 `FusionResult` 返回值

- [ ] T17.25 修改 `Orchestrator._match_intent()`：将 `route_trace` 写入 `GenerationContext` `[AC-AISVC-122]`
  - 修改文件: `app/services/orchestrator.py`
  - 扩展 `GenerationContext` 添加 `route_trace` 字段

- [ ] T17.26 修改 `Orchestrator._build_response()`：在响应 metadata 中包含 `route_trace` `[AC-AISVC-123]`
  - 修改文件: `app/services/orchestrator.py`
  - 将 `route_trace` 写入响应 metadata

---

### Phase 17.8: 配置与 API

- [ ] T17.27 新增融合配置 API：`GET /admin/intent-rules/fusion-config` `[AC-AISVC-116]`
  - 修改文件: `app/api/admin/intent_rules.py`
  - 返回当前融合配置

- [ ] T17.28 新增融合配置 API：`PUT /admin/intent-rules/fusion-config` `[AC-AISVC-116]`
  - 修改文件: `app/api/admin/intent_rules.py`
  - 更新融合配置（支持热更新）

- [ ] T17.29 扩展意图规则 API：支持 `intent_vector` 和 `semantic_examples` 字段的 CRUD `[AC-AISVC-114]`
  - 修改文件: `app/api/admin/intent_rules.py`
  - 修改 `IntentRuleCreate`、`IntentRuleUpdate` schema
  - 修改 CRUD 方法

- [ ] T17.30 新增意图向量生成 API：`POST /admin/intent-rules/{id}/generate-vector` `[AC-AISVC-114]`
  - 修改文件: `app/api/admin/intent_rules.py`
  - 调用 EmbeddingProvider 生成向量
  - 更新规则的 `intent_vector` 字段

---

### Phase 17.9: 监控与追踪

- [ ] T17.31 修改监控 API：`GET /admin/monitoring/conversations/{id}` 返回 `route_trace` `[AC-AISVC-123]`
  - 修改文件: `app/api/admin/monitoring.py`
  - 扩展响应 schema

---

### Phase 17.10: 测试与验证

- [ ] T17.32 编写 `SemanticMatcher` 单元测试：Mock Embedding/Qdrant `[AC-AISVC-113, AC-AISVC-114]`
  - 新增文件: `tests/test_semantic_matcher.py`
  - 测试正常匹配、跳过场景、异常处理

- [ ] T17.33 编写 `LlmJudge` 单元测试：Mock LLM 调用 `[AC-AISVC-118, AC-AISVC-119]`
  - 新增文件: `tests/test_llm_judge.py`
  - 测试触发条件、仲裁结果、异常处理

- [ ] T17.34 编写 `FusionPolicy` 单元测试：覆盖各种融合场景 `[AC-AISVC-115~AC-AISVC-117]`
  - 新增文件: `tests/test_fusion_policy.py`
  - 测试决策优先级、加权融合、澄清触发

- [ ] T17.35 编写 `IntentRouter.match_hybrid()` 集成测试：验证完整路由链路 `[AC-AISVC-111]`
  - 新增文件: `tests/test_intent_router_hybrid.py`
  - 测试并行执行、条件触发、融合决策

- [ ] T17.36 性能测试：验证 P95 延迟满足约束 `[AC-AISVC-125]`
  - 新增文件: `tests/perf/test_intent_latency.py`
  - 测试 RuleMatcher < 10ms
  - 测试 SemanticMatcher < 100ms
  - 测试 P95 总增量延迟 < 500ms（不含 LlmJudge）

---

## 4. 任务进度追踪

| Phase | 描述 | 任务数 | 状态 |
|-------|------|--------|------|
| Phase 17.1 | 数据模型扩展 | 4 | ⏳ 待处理 |
| Phase 17.2 | RuleMatcher 改造 | 2 | ⏳ 待处理 |
| Phase 17.3 | SemanticMatcher 实现 | 4 | ⏳ 待处理 |
| Phase 17.4 | LlmJudge 实现 | 4 | ⏳ 待处理 |
| Phase 17.5 | FusionPolicy 实现 | 5 | ⏳ 待处理 |
| Phase 17.6 | IntentRouter 升级 | 4 | ⏳ 待处理 |
| Phase 17.7 | Orchestrator 集成 | 3 | ⏳ 待处理 |
| Phase 17.8 | 配置与 API | 4 | ⏳ 待处理 |
| Phase 17.9 | 监控与追踪 | 1 | ⏳ 待处理 |
| Phase 17.10 | 测试与验证 | 5 | ⏳ 待处理 |

**总任务数: 36**

---

## 5. 依赖关系

```
Phase 17.1 (数据模型)
    │
    ├──→ Phase 17.2 (RuleMatcher)
    │
    ├──→ Phase 17.3 (SemanticMatcher)
    │
    └──→ Phase 17.4 (LlmJudge)
              │
              └──→ Phase 17.5 (FusionPolicy)
                        │
                        └──→ Phase 17.6 (IntentRouter 升级)
                                  │
                                  └──→ Phase 17.7 (Orchestrator 集成)
                                            │
                                            └──→ Phase 17.8 (配置与 API)
                                                      │
                                                      └──→ Phase 17.9 (监控与追踪)
                                                                │
                                                                └──→ Phase 17.10 (测试与验证)
```

---

## 6. 文件变更汇总

### 6.1 新增文件

| 文件路径 | 说明 |
|----------|------|
| `app/services/intent/models.py` | 数据模型定义 |
| `app/services/intent/semantic_matcher.py` | 语义匹配器 |
| `app/services/intent/llm_judge.py` | LLM 仲裁器 |
| `app/services/intent/fusion_policy.py` | 融合决策策略 |
| `tests/test_semantic_matcher.py` | 语义匹配单元测试 |
| `tests/test_llm_judge.py` | LLM 仲裁单元测试 |
| `tests/test_fusion_policy.py` | 融合决策单元测试 |
| `tests/test_intent_router_hybrid.py` | 混合路由集成测试 |
| `tests/perf/test_intent_latency.py` | 性能测试 |

### 6.2 修改文件

| 文件路径 | 变更说明 |
|----------|----------|
| `app/models/entities.py` | 扩展 IntentRule、ChatMessage 实体 |
| `app/services/intent/router.py` | 新增 `match_hybrid()` 方法，封装 `RuleMatcher` |
| `app/services/orchestrator.py` | Step 3 调用 `match_hybrid()` |
| `app/api/admin/intent_rules.py` | 新增融合配置 API、向量生成 API |
| `app/api/admin/monitoring.py` | 返回 `route_trace` 字段 |

### 6.3 数据库迁移

| 迁移文件 | 说明 |
|----------|------|
| `alembic/versions/xxx_add_intent_vector_fields.py` | 新增 intent_vector、semantic_examples 字段 |
| `alembic/versions/xxx_add_route_trace_field.py` | 新增 route_trace 字段 |
