feat(rag): modularize knowledge retrieval pipeline

src/main/java/com/superbiz/agent/dto/ContextPack.java

@@ -0,0 +1,26 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * Agent-facing packed context assembled from final evidence blocks.
+ */
+@Data
+@Builder
+public class ContextPack {
+
+    private String packedText;
+
+    private String strategy;
+
+    private Integer charBudget;
+
+    private Integer usedChars;
+
+    private List<String> includedSources;
+
+    private List<String> omittedSources;
+}

src/main/java/com/superbiz/agent/dto/EvidencePostprocessResult.java

@@ -0,0 +1,32 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * Output of post-retrieval processing before context packing.
+ */
+@Data
+@Builder
+public class EvidencePostprocessResult {
+
+    private Integer candidateCount;
+
+    private Integer evidenceBlockCount;
+
+    private List<EvidenceBlock> evidenceBlocks;
+
+    private String relevanceLevel;
+
+    private String completenessHint;
+
+    private RerankTrace rerankTrace;
+
+    private Double topSimilarity;
+
+    public boolean hasUsableEvidence() {
+        return evidenceBlocks != null && !evidenceBlocks.isEmpty();
+    }
+}

src/main/java/com/superbiz/agent/dto/KnowledgeQuery.java

@@ -0,0 +1,30 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * Query understanding output used by the knowledge retrieval pipeline.
+ */
+@Data
+@Builder
+public class KnowledgeQuery {
+
+    private String originalQuery;
+
+    private String rewrittenQuery;
+
+    private List<String> domainHints;
+
+    private List<String> matchedKeywords;
+
+    private List<String> entities;
+
+    private String categoryFilter;
+
+    private List<String> l0Titles;
+
+    private Integer l0MatchCount;
+}

src/main/java/com/superbiz/agent/dto/LookupResult.java

@@ -17,21 +17,26 @@ public class LookupResult {
      */
     private boolean found;
 
-    /**
-     * 主要结果（L0 精确匹配）
-     */
-    private PrimaryResult primary;
-
-    /**
-     * 补充结果（L1 语义检索）
-     */
-    private SupplementResult supplement;
-
     /**
      * Structured evidence blocks after retrieval post-processing.
      */
     private List<EvidenceBlock> evidenceBlocks;
 
+    /**
+     * Packed Agent-facing context assembled from evidence blocks.
+     */
+    private ContextPack contextPack;
+
+    /**
+     * Retrieval attempts and fallback trace.
+     */
+    private RetrievalTrace retrievalTrace;
+
+    /**
+     * Rule-based rerank explanation.
+     */
+    private RerankTrace rerankTrace;
+
     /**
      * Candidate count before evidence deduplication.
      */

src/main/java/com/superbiz/agent/dto/PrimaryResult.java

@@ -1,39 +0,0 @@
-package com.superbiz.agent.dto;
-
-import lombok.Builder;
-import lombok.Data;
-
-import java.util.List;
-
-/**
- * L0 精确匹配结果
- */
-@Data
-@Builder
-public class PrimaryResult {
-
-    /**
-     * 文档内容（前 2000 字符）
-     */
-    private String content;
-
-    /**
-     * 文档来源路径
-     */
-    private String source;
-
-    /**
-     * 匹配类型（exact_L0）
-     */
-    private String matchType;
-
-    /**
-     * 置信度（high / low）
-     */
-    private String confidence;
-
-    /**
-     * 可用的章节列表（预留字段，MVP 返回 null）
-     */
-    private List<String> availableSections;
-}

src/main/java/com/superbiz/agent/dto/RerankTrace.java

@@ -0,0 +1,26 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * Rule-based rerank explanation for final evidence blocks.
+ */
+@Data
+@Builder
+public class RerankTrace {
+
+    private List<Item> items;
+
+    @Data
+    @Builder
+    public static class Item {
+        private Integer finalRank;
+        private String source;
+        private Double baseScore;
+        private Double finalScore;
+        private List<String> boostReasons;
+    }
+}

src/main/java/com/superbiz/agent/dto/RetrievalTrace.java

@@ -0,0 +1,45 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Trace of retrieval attempts used by lookup_knowledge.
+ */
+@Data
+@Builder
+public class RetrievalTrace {
+
+    private String originalQuery;
+
+    private String rewrittenQuery;
+
+    private String categoryFilter;
+
+    private String selectedAttempt;
+
+    private String fallbackReason;
+
+    private String evidenceStatus;
+
+    private Map<String, Object> queryHints;
+
+    private List<Attempt> attempts;
+
+    @Data
+    @Builder
+    public static class Attempt {
+        private String name;
+        private String query;
+        private String categoryFilter;
+        private Integer candidateCount;
+        private Boolean usable;
+        private String errorMessage;
+        private Integer durationMs;
+        private Double topScore;
+        private Double topSimilarity;
+    }
+}

src/main/java/com/superbiz/agent/dto/RetrievedEvidenceCandidate.java

@@ -0,0 +1,41 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Normalized vector retrieval candidate before evidence post-processing.
+ */
+@Data
+@Builder
+public class RetrievedEvidenceCandidate {
+
+    private String id;
+
+    private String source;
+
+    private String title;
+
+    private String breadcrumb;
+
+    private String content;
+
+    private String retrievalLayer;
+
+    private String retrievalAttempt;
+
+    private Double score;
+
+    private Double rawScore;
+
+    private String scoreLabel;
+
+    private Integer originalRank;
+
+    private Map<String, String> metadata;
+
+    private List<String> hitReasons;
+}

src/main/java/com/superbiz/agent/dto/SupplementResult.java

@@ -1,27 +0,0 @@
-package com.superbiz.agent.dto;
-
-import lombok.Builder;
-import lombok.Data;
-
-/**
- * L1 语义检索补充结果
- */
-@Data
-@Builder
-public class SupplementResult {
-
-    /**
-     * 文档内容片段
-     */
-    private String content;
-
-    /**
-     * 文档来源
-     */
-    private String source;
-
-    /**
-     * 匹配类型（semantic_L1）
-     */
-    private String matchType;
-}