feat(harness,rag): dual LLM audit fields, run conclusion, and hybrid quality
Persist provider reasoning and assistant text separately on agent_reasoning_audit (DeepSeekAssistantMessage path), extract diagnosis_run.conclusion, enrich RAG tool audit (step_id/query/qualityScore), gate empty mysql tools, drop devtools, and align MVP docs after live E2E verification.
This commit is contained in:
zhuyongxin
@@ -0,0 +1,136 @@
|
||||
# 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）。
|
||||
Reference in New Issue
Block a user