feat: add rag evidence postprocess blocks

2026-07-05 03:03:18 +08:00
parent 4a94c14feb
commit 5197712719
12 changed files with 497 additions and 1 deletions
@@ -0,0 +1,53 @@
+## Context
+
+The previous change converted L0 into a hint provider and made L0/L1 cooperate. The next step is to stop treating the tool output as an unstructured primary/supplement pair. The Agent can keep receiving compatible fields, but retrieval internals and traces should have structured evidence blocks.
+
+This change is a bridge toward later DocumentPostProcessor-style behavior. It should be small enough to archive independently and should not introduce Spring AI dependencies.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add `EvidenceBlock` DTOs to `LookupResult`.
+- Create evidence blocks from L0 matches and L1 results.
+- Deduplicate evidence by stable source key.
+- Capture source, title, breadcrumb, score, retrieval layer, hit reasons, and content preview.
+- Persist evidence blocks and postprocess counts in `tool_invocation.retrieval_details`.
+
+**Non-Goals:**
+
+- Do not implement neighbor chunk expansion yet.
+- Do not replace primary/supplement output.
+- Do not add cross-encoder or LLM rerank.
+- Do not migrate to Spring AI DocumentPostProcessor yet.
+
+## Decisions
+
+### Decision: Add evidence blocks while preserving existing result fields
+
+`LookupResult` will gain `List<EvidenceBlock> evidenceBlocks`. Existing `primary`, `supplement`, `found`, `relevanceLevel`, and `completenessHint` remain compatible.
+
+Rationale: this lets the Agent continue using the current shape while tests and traces begin validating the new evidence model.
+
+### Decision: Keep postprocess rule-based
+
+The evidence builder will use deterministic rules:
+
+- L0 entries become `L0` evidence.
+- L1 candidates become `L1` evidence.
+- Same source key is deduplicated.
+- Hit reasons are collected from L0 hints, L1 rank, category filters, and fallback state.
+
+Rationale: this is explainable, cheap, and suitable before introducing framework postprocessors.
+
+### Decision: Persist compact evidence summaries
+
+`ToolInvocationRecorder` will store compact evidence block metadata, not full content, inside `retrieval_details`.
+
+Rationale: `tool_invocation` should remain useful for trace review without duplicating large chunks.
+
+## Risks / Trade-offs
+
+- Evidence source keys may be imperfect before full metadata normalization -> fall back to file path, metadata, title, then rank.
+- Agent prompts may ignore `evidenceBlocks` initially -> keep primary/supplement compatibility.
+- Adding content previews increases tool output size -> cap evidence content length.