# Evidence: executor-action-memory-relevance

## Evidence-driven 结论

### E1: relevanceLevel 三等级语义清晰度

- **来源**: Grill 阶段 Question Pool #1
- **查证结果**: 三个等级语义明确，边界清晰：
  - PRECISE：L0 唯一精确匹配，LLM 应直接使用
  - HIGHLY_RELEVANT：归一化 similarity ≥ 0.75，高度相关
  - REFERENCE：归一化 similarity ≥ 0.5，相关参考
- **结论**: LLM 误解风险低，语义边界足够清晰

### E2: L1 Score 值域与归一化阈值

- **来源**: Grill 阶段 Question Pool #2
- **查证结果**:
  - L1 score 是 L2 距离，值域 [0, +∞)
  - BGE-M3 输出为 L2 归一化单位向量（实测范数=1.00000002），L2 距离数学硬上界 = 2.0
  - Min-Max 归一化公式：`similarity = 1 - min(l2Score, 2.0) / 2.0`
- **结论**: 使用 `maxL2Distance=2.0` 作为归一化上界，阈值 yml 可配置

### E3: L1 Domain 提取兜底路径

- **来源**: Grill 阶段 Question Pool #3
- **查证结果**:
  - L0 的 domain 可从 `KnowledgeEntry.getCategory()` 直接获取
  - L1 结果的 domain 需解析 `SearchResult.metadata` JSON 字符串
  - 当前知识库设计下 L0 大概率先命中，L1 domain 提取作为兜底
- **结论**: 先尝试 L0 category，失败时解析 L1 metadata JSON（try-catch 兜底）

### E4: 历史数据不回填

- **来源**: Grill 阶段 Question Pool #5
- **查证结果**: 新列 `relevance_level` 和 `dedup_reason` 均为 nullable，不影响现有查询
- **结论**: 历史记录保持 null，不需要回填迁移

### E5: BGE-M3 L2 归一化实测验证

- **来源**: Specify 阶段 + FullPipelineSmokeTest
- **查证结果**:
  - embeddingBgeM3Works() 测试新增 L2 范数断言
  - 实测范数 = 1.00000002，误差 < 0.01
  - 测试通过，BGE-M3 输出确认为 L2 归一化单位向量
- **结论**: L2 距离上界 = 2.0 的数学依据成立

### E6: V010 迁移验证

- **来源**: Apply 阶段运行时验证
- **查证结果**:
  - Flyway V010 迁移成功执行
  - `relevance_level` VARCHAR(20) 列可空，已正确写入
  - `dedup_reason` VARCHAR(32) 列可空，已正确写入
  - `retrieval_details` JSON 扩展字段（l1_top_similarity、relevance_level、completeness_hint、retrieved_domains、dedup_reason）全部写入
- **结论**: 入库可观测性符合设计

### E7: 数据库数据校验

- **来源**: Apply 阶段运行时验证
- **查证结果**:
  - session `b66d799e` 共 10 条 lookup_knowledge 调用
  - id=138: L2=0.383 → similarity=0.8085 → HIGHLY_RELEVANT（符合预期）
  - id=139-147: 主要为 REFERENCE，doc_retrieved 去重正常触发
  - retrieved_domains 域追踪：`[infrastructure]` → `[infrastructure, api]` 正常扩展
- **结论**: 归一化、行动记忆、去重机制数据层面全部验证通过