# Decisions — rag-quality-score-unify

## sm-flow meta

- **Checkpoint**: Discover（clarify + context + propose + grill）
- **Scale**: standard
- **Capability**: sm-flow 内置协议；openspec CLI `new change`；grill 使用内置协议（conversation-confirmed + evidence-driven），标注 fallback：未调用外部 `grill-with-docs` skill 文件执行器
- **Slug**: `rag-quality-score-unify`
- **OpenSpec path**: `openspec/changes/rag-quality-score-unify/`

## Clarify summary

| 项 | 内容 |
|---|---|
| 问题 | hybrid 已 RRF 融合，后处理仍 L2 伪装 + 关键词 boost 改序，质量信号不统一 |
| 期望 | label 仅 dense/hybrid；toQualityScore 唯一归一化；后处理保 rank、去 boost 改序 |
| 影响代码 | `MilvusHybridKnowledgeStore`, `VectorSearchService`, `KnowledgeEvidencePostProcessor`, retrieval 包新类, DTO 注释, 测试, 架构文档 |
| 非目标 | 精排/rewrite/邻块、删 dense mode、改 ACI 字段结构、改 schema |

## Context summary (devflow)

| 来源 | 结论 | 需进 OpenSpec |
|---|---|---|
| `devflow/index.md` | rag-chunk-identity / bm25-hybrid / hybrid-rrf 均 archived | 是：承接不回退 |
| `rag-bm25-hybrid-drop-sdk/decisions.md` | 曾要求 dense L2 enrichment 兼容阈值 | **是：本 change 废止该 decision** |
| glossary | lookup_knowledge 为证据工具；不在此改 ACI 主结构 | 是：非目标 |
| 架构文档 §6.0 | mode dense=对照，hybrid=主路径 | 是：保留 |

**index 使用状态**: 已命中相关 RAG 条目。

## Question pool (grill)

| ID | 维度 | 模式 | 问题 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | user-interview（对话已确认） | 一级 scoreLabel 是否只有 dense/hybrid，bm25_only 不作正式 label？ | **已确认** |
| Q2 | 边界 | user-interview（对话已确认） | 后处理是否去掉关键词 contains 加分改序，仅保 originalRank？ | **已确认** |
| Q3 | 边界 | user-interview（对话已确认） | 归一化是否唯一 toQualityScore；后处理 label-agnostic？ | **已确认** |
| Q4 | 验收 | user-interview（对话已确认） | dense mode 保留作召回对照；主路径 hybrid？ | **已确认** |
| Q5 | 技术 | evidence-driven | 当前代码是否仍 L2 回填 + boost 重排？ | **已查证** |
| Q6 | 技术 | evidence-driven | Agent ACI 是否暴露 scoreLabel？ | **已查证** |
| Q7 | 验收 | user-interview（对话已确认） | 接受 relevance_level / retry 分布变化？ | **已确认** |
| Q8 | 边界 | user-interview | hybrid quality 切片 1 是否采用**纯 rank 映射**（不做 max(rank,denseSim)）？ | **已确认** |

### Q1–Q4, Q7 用户确认摘录（本会话）

- Label：「应该只有 hybrid 和 dense」「bm25_only 不是第三种」→ 同意收成两种。
- 归一化：「抽取抽象转换…后处理抽象统一」→ 同意。
- 后处理：「关键词打分不合理」「可以，就按照这个」（去 boost 改序 + 归一化一起做）。
- mode：保留 dense 作对照，写入架构 §6.0。
- 行为变化：讨论中已说明 hybrid 顺序/等级/retry 会变，用户要求按该方案实施（经 sm-flow）。

### Q5 evidence-driven

- `MilvusHybridKnowledgeStore.searchHybrid`：RRF 后仍 dense 回填 L2 / `bm25_only_no_dense`。
- `KnowledgeEvidencePostProcessor.score`：`normalizeL2` + domain/entity/keyword/source_type 加分，按 `finalScore` 降序。
- `LookupKnowledgeTool`：`isLowQuality` 看 `topSimilarity`（来自 baseScore）。

### Q6 evidence-driven

- Agent 主契约 `RagToolResult` / projector 暴露 evidence 列表与 relevance_level，不依赖 scoreLabel 字符串；改 label 为内部/L2 影响。

### Q8 用户确认（2026-07-28）

- **问题原文**: hybrid 的 qualityScore（切片 1）采用哪种映射？
- **用户选择**: 纯 rank 映射（推荐）
- **确认状态**: 已确认
- **实现约束**: `toQualityScore(hybrid)` = `rankToQuality(originalRank, batchSize)`；不看 RRF 原分量纲；不做 `max(rank, denseSim)`；不在 hybrid 路径为质量闸门再查/回填 dense L2。

---

## Discover status

- [x] clarify
- [x] context
- [x] propose (`proposal.md`)
- [x] grill 完成（Q1–Q8 均已关闭）

**Discover checkpoint: 完成。**

---

## Commit checkpoint

### Capability

- specify: sm-flow 内置 + openspec status/instructions（fallback：按 template 手写 design/specs/tasks）
- audit: sm-flow 内置协议（未调用外部 zoom-out）
- commit gate: 文件完整性 + 一致性检查后写入 `.committed`

### Cross-artifact 对齐

| 链路 | 状态 |
|---|---|
| brief/proposal 目标范围 → design | 已对齐 |
| design 决策（label/normalizer/保序/去 boost/纯 rank）→ specs | 已对齐 |
| specs 可观察行为 → tasks 可执行切片 | 已对齐 |
| decisions Q1–Q8 → proposal/design/specs | 已对齐 |

### Audit（≤5 句）

1. 链路仍是 Tool→Retriever→Store→Post→Pack→Project，无新外部系统。  
2. 分数所有权上收 store 发射 + normalizer；后处理只裁剪与质量闸门。  
3. 废止 bm25-hybrid 的「dense L2 enrichment」决策，属有意行为变化（L2 接口影响）。  
4. 风险主要是 hybrid 序数 quality 与阈值标定，已记入 design Risks。  
5. 不触及 Agent ACI 字段名与 Milvus schema。

### Commit gate checklist

- [x] proposal / design / specs / tasks / brief 存在
- [x] 核心概念在 design 有对应
- [x] design 关键决策在 tasks 有任务
- [x] tasks 可验证（checkbox 纵向切片）
- [x] 无未确认 user-interview
- [x] `.committed` 已创建

**Commit checkpoint: 完成。Committed OpenSpec 就绪。**

**下一步**: 等待用户明确授权 **Apply**（例如「开始 apply / 实现」）。未授权前不改业务接线代码。

---

## Apply checkpoint

- **Capability**: openspec-apply-change + Committed OpenSpec tasks
- **授权**: 用户「实现」
- **完成**: tasks.md 全部勾选
- **验证**:
  - `RetrievalScoreNormalizerTest` 4 passed
  - `KnowledgeEvidencePostProcessorTest` 6 passed
  - `LookupKnowledgeToolTest` 7 passed
  - `VectorSearchServiceTest` 2 passed
  - `VectorKnowledgeSearchAdapterHybridTest` 1 passed
- **已知限制**: hybrid quality 为本轮 rank 序数映射，跨 query 绝对值不可比；阈值可能需后续标定
- **行为变化**: 已落地（去 L2 回填、去 boost 改序、label dense/hybrid）

**Apply checkpoint: 完成。** 可进入 Archive（需用户确认是否 archive OpenSpec）。