SuperBizAgent-java/devflow/projects/2026-07-06-modular-rag-pipeline/decisions.md

Modular RAG Pipeline — Decisions

D1: lookup_knowledge 保持显式工具

不把知识检索做成隐式 Advisor。Agent 仍显式调用 lookup_knowledge(query)，这样 trace、Verifier、Eval 都能看到工具调用边界。

D2: L0 只做 query understanding

L0 产出：

• domainHints
• matchedKeywords
• entities
• categoryFilter
• l0Titles
• l0MatchCount

L0 不再直接转成 fact evidence。L0 hint 可以影响 filter、rerank、trace，但不能在 L1 失败时冒充知识证据。

D3: MVP 降级策略采用 unfiltered L1 retry

流程：

filtered L1 with L0 category filter
  -> empty / no final evidence / below reference threshold
  -> raw query unfiltered L1 retry
  -> still no evidence => no_evidence

取舍：

• 简单、可解释、适合 MVP。
• 避免引入 BM25/RRF/multi-query/cross-encoder 的复杂度。
• 代价是低质量场景多一次向量查询，已通过 trace 记录 attempt duration。

D4: 删除 primary/supplement

这是一次 L4 breaking interface change。

删除原因：

• primary/supplement 绑定旧语义：L0 primary、L1 supplement。
• 新设计中事实证据来自 evidenceBlocks/contextPack。

迁移结果：

• LookupResult 暴露 evidence-first 字段。
• PrimaryResult / SupplementResult 已删除。
• 生产代码和测试不再引用 getPrimary() / getSupplement()。

D5: Trace 表结构保持稳定

tool_invocation 表不新增列。新增信息写入 retrieval_details JSON：

• query_transform
• retrieval_trace
• context_pack_summary
• rerank_trace
• fallback_reason
• evidence_blocks

原因：当前 trace、Verifier、Eval 已经以 tool_invocation 为证据入口，JSON details 足够承载 RAG 细节，避免 schema churn。

D6: 会话去重不返回可消费证据

Review 后修正：

• dedup result 的 found=false 必须和 evidence/context 语义一致。
• 返回消息说明文档已检索过。
• 不再返回 evidenceBlocks/contextPack，避免 Agent 重复使用同一证据。
• 保留 retrievalTrace 和 retrievedDomainsThisSession 便于可观测。