# 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

流程：

```text
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` 便于可观测。