feat(rag): modularize knowledge retrieval pipeline

mvp/architecture/retrieval-observability.md

@@ -1,6 +1,6 @@
 # 检索与可观测性架构
 
-**更新日期**：2026-07-05  
+**更新日期**：2026-07-06
 **状态**：当前可运行架构  
 **参考历史文档**：`archive/2026-07-05-legacy/knowledge-retrieval-architecture.md`
 
@@ -13,7 +13,7 @@
 - 检索结果如何归一化、去重、记录。
 - 如何通过 trace 和 eval 判断检索质量。
 
-当前架构与旧版最大的差异是：L0 不再因为唯一命中而默认跳过 L1。L0 是 hint 和解释信号，L1 语义检索是默认召回路径。
+当前架构与旧版最大的差异是：L0 不再因为唯一命中而默认跳过 L1，也不在 L1 失败时作为事实证据兜底。L0 是 hint 和解释信号，L1 语义检索是默认召回路径。
 
 ## 2. 检索总图
 
@@ -35,9 +35,13 @@ flowchart TD
 
     Spring --> Candidates["L1 candidates"]
     SDK --> Candidates
-    Candidates --> Normalize["relevance normalization"]
-    L0Result --> Normalize
-    Normalize --> Result["LookupResult"]
+    Candidates --> Quality{"filtered L1 usable?"}
+    Quality -->|no| Retry["raw query unfiltered L1 retry"]
+    Quality -->|yes| Post["post-retrieval processing"]
+    Retry --> Post
+    L0Result --> Post
+    Post --> Pack["context packing"]
+    Pack --> Result["LookupResult evidenceBlocks/contextPack/traces"]
 
     Result --> Dedup["RetrievedDocTracker session dedup"]
     Dedup --> Final["final tool output"]
@@ -69,6 +73,7 @@ singleDomainOrNull
 
 ```text
 matches=1 -> skip L1 -> 直接返回 L0 文档正文
+L1 无可用证据 -> 返回 L0 文档正文
 ```
 
 原因：
@@ -123,12 +128,12 @@ SDK fallback 保留的价值：
 | `rawScore` | 底层检索实现原始分数 |
 | `scoreLabel` | 原始分数语义，例如 `similarity` 或 `l2_distance` |
 
-工具层再把 L0/L1 情况归一为：
+post-retrieval 层再把检索候选归一为：
 
 | relevanceLevel | 含义 |
 |---|---|
-| `PRECISE` | L0 单命中且 L1 相似度高 |
-| `HIGHLY_RELEVANT` | L1 相似度高，或 L0 多命中且 L1 支撑强 |
+| `PRECISE` | L1 相似度高且 query hint 与候选证据互相支撑 |
+| `HIGHLY_RELEVANT` | L1 相似度高 |
 | `REFERENCE` | 可作为参考，但不足以声明强证据 |
 | `DEDUPED` | 同 session 中已检索过，不重复注入上下文 |
 
@@ -169,7 +174,7 @@ title + breadcrumb + content
 
 ```mermaid
 flowchart LR
-    LookupResult["LookupResult"] --> Agent["Agent context"]
+    LookupResult["LookupResult: evidenceBlocks/contextPack/traces"] --> Agent["Agent context"]
     LookupResult --> Recorder["ToolInvocationRecorder"]
     Recorder --> Invocation["tool_invocation"]
     Invocation --> Trace["DiagnosisTraceService"]
@@ -195,10 +200,13 @@ success
 `retrieval_details` 承载更细信息，例如：
 
 - L0 命中文档标题和路径。
-- L1 分数。
+- L1 attempts、fallback reason、分数和 similarity。
 - retrieved domains。
 - evidence status。
 - dedup reason。
+- evidence block summaries。
+- context pack summary。
+- rerank trace。
 
 ## 8. 去重与行动记忆
 
@@ -252,15 +260,15 @@ trace inspection
 
 近期优先：
 
-1. 完整 evidence block 输出。
-2. 邻居 chunk / 同章节上下文扩展。
-3. metadata taxonomy 清理。
-4. Query Transformer / MultiQuery 可回退接入。
-5. 更完整的 Recall@K、MRR、nDCG 报告。
+1. 邻居 chunk / 同章节上下文扩展。
+2. metadata taxonomy 清理。
+3. Query Transformer / MultiQuery 可回退接入。
+4. 更完整的 Recall@K、MRR、nDCG 报告。
 
 暂不优先：
 
 - 重新引入 L0 直接返回。
+- 重新引入 L0 文档作为 L1 失败时的事实证据兜底。
 - 一次性迁移所有写入路径。
-- 在没有评测收益前引入 rerank / RRF / BM25。
+- 在没有评测收益前引入模型 rerank / RRF / BM25。