Files

T

zhuyongxin 7ae9707a3b 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.

2026-07-28 19:43:13 +08:00

6.4 KiB

Raw Blame History

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

clarify
context
propose (proposal.md)
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 句）

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

Commit gate checklist

proposal / design / specs / tasks / brief 存在
核心概念在 design 有对应
design 关键决策在 tasks 有任务
tasks 可验证（checkbox 纵向切片）
无未确认 user-interview
.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）。

6.4 KiB Raw Blame History Unescape Escape