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

Modular RAG Pipeline — Evidence

代码证据

关键入口：

• src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java
• src/main/java/com/superbiz/agent/service/ToolInvocationRecorder.java
• src/main/java/com/superbiz/agent/dto/LookupResult.java

新增模块：

• KnowledgeQueryTransformer：复用 KnowledgeIndexService.analyzeQuery，把 L0 转成 query hints 和可选 categoryFilter。
• KnowledgeDocumentRetriever：封装 VectorSearchService.searchSimilarDocuments(query, topK, category)，统一 filtered / unfiltered attempt。
• KnowledgeEvidencePostProcessor：归一化 L2、创建 evidence blocks、source dedup、规则 rerank、输出 RerankTrace。
• KnowledgeContextPacker：按字符预算打包 evidence，保留 source/title/breadcrumb/hit reasons。
• LookupResultAssembler：统一组装 evidence-first result、no-evidence result、session dedup result。

设计证据

已有文档约束：

• mvp/architecture/rag-architecture.md：RAG 应表达为可解释 pipeline，而不是一坨工具逻辑。
• mvp/architecture/retrieval-observability.md：L0 是 hint/explainability 层，L1 是语义检索主路径。
• devflow/glossary/CONTEXT.md：lookup_knowledge 是显式 Agent evidence tool，tool_invocation 是 trace / verifier / eval 的证据来源。

OpenSpec 对齐：

• openspec/changes/modular-rag-pipeline/proposal.md
• openspec/changes/modular-rag-pipeline/design.md
• openspec/changes/modular-rag-pipeline/specs/rag-knowledge-retrieval/spec.md
• openspec/changes/modular-rag-pipeline/tasks.md

用户确认

• 一次到位做模块化 RAG，而不是只做小补丁。
• L0 不再作为事实证据兜底。
• filtered L1 不准时，MVP 降级为 raw query unfiltered L1 retry。
• 可以新增字段，并删除旧字段以换取后续流程清晰。

Review 发现

Review 中发现一个非阻塞但应修复的问题：

• 会话去重命中时，返回 found=false 但仍带 evidenceBlocks/contextPack，可能导致 Agent 重复消费同一份证据。

修复：

• LookupResultAssembler.deduped 清空可消费 evidence/context，只保留 message、trace、relevance hint 和 session domain memory。
• 新增 LookupKnowledgeToolTest.sessionDedupDoesNotReturnConsumableEvidenceAgain。

非阻塞观察

• MilvusConnectionTest 仍直接依赖 MILVUS_TOKEN 环境变量；主配置中已有 token，但测试不读 Spring 配置。
• 测试日志仍有 ANTLR 版本 warning，不影响测试通过。
• 控制台在部分命令输出中仍会出现中文编码显示问题，但源码按 UTF-8 读取时关键用户提示文本正常。