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

Modular RAG Pipeline — Brief

背景

lookup_knowledge 已经能返回知识库证据，但实现集中在 LookupKnowledgeTool 内部：L0 查询分析、L1 向量召回、相关性归一化、证据组装、会话去重和 trace 入库耦合在一起。

旧返回契约 primary/supplement 也延续了“L0 是主结果、L1 是补充”的语义，和当前设计目标不一致。新的目标是让 L0 只作为 query understanding / filter / rerank / trace 信号，让 L1 向量检索成为事实证据来源。

目标

• 将 lookup_knowledge 改造成模块化 RAG pipeline。
• 保留显式 Agent tool 边界，不改工具名和 query 参数。
• L0 只提供领域、关键词、实体、category filter 和 trace hint。
• L1 filtered vector retrieval 失败或低质量时，降级为 raw query unfiltered L1 retry。
• 输出 evidence-first contract：evidenceBlocks、contextPack、retrievalTrace、rerankTrace。
• 保持 tool_invocation 表结构稳定，把新 trace 写入 retrieval_details JSON。

范围

已完成：

• 新增 pipeline DTO：KnowledgeQuery、RetrievedEvidenceCandidate、ContextPack、RetrievalTrace、RerankTrace、EvidencePostprocessResult。
• 新增 pipeline service：KnowledgeQueryTransformer、KnowledgeDocumentRetriever、KnowledgeEvidencePostProcessor、KnowledgeContextPacker、LookupResultAssembler。
• 重构 LookupKnowledgeTool 为薄 orchestration 层。
• 迁移 LookupResult，删除 primary/supplement 字段和 PrimaryResult / SupplementResult 类。
• 更新 ToolInvocationRecorder，记录 query transform、retrieval trace、context pack summary、rerank trace、fallback reason 和 evidence summaries。
• 更新 executor prompt 和 RAG 架构文档。
• 补充 lookup、recorder、fallback、rerank、context pack、session dedup 测试。

非目标：

• 不引入 implicit Advisor。
• 不引入 cross-encoder、BM25、RRF、Elasticsearch、OpenSearch。
• 不改文档上传、chunk、embedding 写入、Milvus schema。
• 不改变 Agent 何时调用 lookup_knowledge。

关联 OpenSpec

• openspec/changes/archive/2026-07-06-modular-rag-pipeline

接口影响

级别：L4 breaking interface。

原因：

• 删除旧 LookupResult.primary / LookupResult.supplement。
• lookup_knowledge tool JSON 输出形状变化。

缓解：

• 工具名和输入参数保持不变。
• in-repo 消费方、测试和 prompt 同步迁移。
• tool_invocation 表结构不变。