Agentic RAG 改造执行计划#

本文档是 DocMind 向《企业技术文档 Agent 最佳实践》对齐的多 Phase 执行计划。每个 Phase 在独立会话窗口中完成。会话开始前先读本文档定位当前进度。

进度跟踪#

每完成一个 Step，把状态从 ⏳ 改为 ✅；每完成一个 Phase，记录日期与 commit。

⚠️ Phase 6 之后的架构现状（2026-06-07 四刀改造 A/C/B/E 落地）：对标 Anthropic / Glean 做了四刀收敛——B 用真·LLM 工具调用的 agentic 检索循环（AgenticSearchOrchestrator）替换早期 Plan-and-Execute / Query Decomposition / 自研串行多跳三条手写分支；A 加结构化引用（CitationParser 纯 Java，置信度 = 引用覆盖率 × rerank-top1）；C 删 Self-Reflection（含切题度检查，生成即终态）；E 分类器瘦身（删 needDecompose / multiHop，applyDeterministicSignals 现在只把多焦点信号升级 complexity 以路由进 agentic 循环）；D 权限下推暂缓。详见 19-对标主流产品改造报告.md / 20-改造实现设计.md。下方各 Phase 记录是历史，凡涉及自反思 / 子问题拆解 / 串行多跳 / Plan-and-Execute 的”现状”描述均已被四刀改造取代，本文逐处加了迁移注记。

差距对比总览#

高级 RAG 维度（来源：最佳实践第三章查询流程）#

Agentic RAG 维度（来源：最佳实践 1.3 节）#

📌 四刀改造迁移注记（2026-06-07）：上表”DocMind 现状”列描述的是 Phase 2 落地时的状态。四刀改造（B）后，主检索路径是真·LLM 工具调用的 agentic 循环（AgenticSearchOrchestrator，模型自驱拆 / 跳 / 补 / 停，max_iterations=4 兜底，只暴露 3 个读工具）；并行 Worker 编排（SupervisorAgent.oneShotRetrieval）保留为 RULE_PLANNER 简单查询路径 + agentic 异常 / 空结果的兜底。

Phase 1：基础铺垫#

目标：先把检索质量打扎实，让后续 Agentic 改造的每个 Worker 都基于可靠输出运作。 风险：低；改动局部。

Step 1：扩大检索候选池 Top-20 → Top-50#

• 修改文件：
  • src/main/java/com/simon/DocMind/service/rag/VectorRetriever.java — DEFAULT_TOP_K 改 50
  • src/main/java/com/simon/DocMind/service/rag/BM25Retriever.java — DEFAULT_TOP_K 改 50
  • src/main/java/com/simon/DocMind/config/AiConfigHolder — 增加 retrieve_top_k_candidate=50、rerank_top_k_final=8
  • docs/docmind.sql — sys_ai_config 增加默认值
  • src/main/java/com/simon/DocMind/service/rag/CrossEncoderReranker.java — 重排输出读 rerank_top_k_final
• 依赖：无
• 验证：跑现有 query，对比改动前后召回 chunk 数与最终引用质量
• 文档同步：03-检索与排序链路.md、04-优化迭代记录.md

Step 2：MMR 多样性重排#

• 新增文件：src/main/java/com/simon/DocMind/service/rag/MMRDiversifier.java
• 修改文件：
  • src/main/java/com/simon/DocMind/agent/DocMindAgent.java — 在 CrossEncoderReranker 之后调用 MMRDiversifier
  • AiConfigHolder — 增加 mmr_lambda=0.7、mmr_enabled=true
• 算法：MMR = λ * relevance(q,d) - (1-λ) * max sim(d, selected)；相似度可用 chunk embedding cosine 或 Jaccard
• 依赖：Step 1
• 验证：构造 Top-K 全来自同一文档的查询，验证 MMR 后能拉入其他文档
• 文档同步：03-检索与排序链路.md、04-优化迭代记录.md、11-面试高频质疑应答.md

Step 3：丰富 Chunk 元数据#

• 修改文件：
  • entity/KbChunk.java — 增加 tags(JSON 数组)、docVersion、effectiveDate、sourceFileName
  • docs/docmind.sql — kb_chunk 表 ALTER 增加列；提供迁移 SQL
  • src/main/java/com/simon/DocMind/service/knowledge/TextChunker.java — 元数据生成填充新字段
  • Milvus schema 增加 tags (VARCHAR) 用于过滤
  • VectorRetriever.java — 支持 tags 过滤表达式
  • src/main/java/com/simon/DocMind/service/rag/PromptAssembler.java — 引用注入新元数据
• 新增：tags 自动提取小工具（基于章节标题 + 关键词抽取）
• 依赖：建议 Step 1/2 后做
• 风险：DB schema 变更需迁移脚本，可能需重建部分历史索引
• 验证：上传新文档，确认 tags、docVersion 入库且可被检索过滤
• 文档同步：03-检索与排序链路.md、04-优化迭代记录.md

Phase 2：Agentic RAG 核心改造#

目标：把单体 Agent 改造为 Supervisor-Worker 编排架构，引入条件编排与动态规划。 风险：高；架构级改动；建议每个 Step 单独 commit。

Step 4：Supervisor-Worker 拓扑骨架#

• 新增包：agent/supervisor/、agent/worker/
• 新增文件：
  • agent/supervisor/SupervisorAgent.java
  • agent/worker/Worker.java（接口：execute(WorkerRequest) → WorkerResult）
  • agent/worker/RetrievalWorker.java（封装 vector + BM25 + RRF + 重排 + MMR）
  • agent/worker/WebWorker.java（封装 WebSearchTool）
  • agent/worker/MemoryWorker.java（封装 MemoryTool）
  • agent/worker/AnalysisWorker.java（新：多文档对比/综合）
  • agent/state/AgentState.java（共享状态）
  • agent/state/Evidence.java（标准证据结构）
• 重构：DocMindAgent 内部链路拆解，原逻辑迁移到对应 Worker
• 保留：MCP 工具暴露不变；DocMindAgent 作为 SupervisorAgent 的薄壳保持外部签名
• 依赖：Step 1-3
• 验证：原 SSE 主链路功能不退化，所有现有测试通过
• ⚠️ 风险点：建议拆 3-4 个 commit（接口 → 各 Worker 迁移 → Supervisor 重构）
• 文档同步：01-项目全景与架构设计.md（架构图替换）、02-Agentic-RAG核心设计.md（核心改写）、04-优化迭代记录.md、07-项目深度扩展方向.md（移除已实现项）

Step 5：7 阶段顺序流水线 + AgentState#

⚠️ 四刀改造迁移注记（2026-06-07）：本 Step 的”7 阶段固定流水线（…→ 生成 → 反思）“是历史形态。四刀后末段”反思”阶段删除（生成即终态）；检索段不再固定一次性走 Worker 流水线，而是按 routePath 分三模式（SELECTED_DOC 直读 / RULE_PLANNER 一次性检索 / AGENTIC 工具调用循环）。

• 修改：
  • SupervisorAgent.java — 固定 7 阶段顺序流水线（理解 → 范畴 → 路径 → 检索 → 评分 → 生成 → 反思）
  • AgentState.java — 共享执行上下文：triedStrategies、accumulatedEvidence、confidenceTrajectory、查询分类
• 设计：非循环，每阶段顺序执行一次；CRAG 评分 AMBIGUOUS 时条件触发 WebWorker 补偿检索
• 依赖：Step 4
• 验证：标准查询走完 7 阶段；AMBIGUOUS 时触发补偿检索
• 文档同步：02-Agentic-RAG核心设计.md、04-优化迭代记录.md

Step 6：Plan-and-Execute 模式#

⚠️ 已移除（2026-06）：本 Step 产出的 PlanGenerator / PlanExecutor / ExecutionPlan 已在链路精简中删除——它规划早于检索、处理不了链式多跳，且与 Query Decomposition 能力重叠。链式多跳改用串行有界迭代（Self-Ask/MultiStep）。详见 04-优化迭代记录 #21。

• 新增：
  • agent/supervisor/PlanGenerator.java（LLM 产出结构化 ExecutionPlan）
  • agent/supervisor/ExecutionPlan.java（数据模型）
  • agent/supervisor/PlanExecutor.java（按计划调度 Workers）
  • prompts/plan_generation.txt
• 触发条件：query.complexity == COMPLEX 走 Plan-and-Execute（默认关闭）；其他走 Step 5 的固定流水线
• 依赖：Step 4 + Step 5
• 验证：复杂多跳查询能产出多步计划并按步骤执行
• 文档同步：02-Agentic-RAG核心设计.md、04-优化迭代记录.md、11-面试高频质疑应答.md

Step 7：CRAG 条件补偿与降级链（合并优化 5 / 11）#

• 修改：
  • SupervisorAgent.java — 检索后调用 RetrievalGrader 三档评分
  • agent/SelfReflection.java — 提供更结构化的 issues 给降级判断
• 新增：service/rag/RetrievalGrader.java、service/rag/GradeResult.java
• 决策图：
  • HIGH（rerank 顶分 ≥ 0.60）→ 直接生成
  • LOW（rerank 顶分 ≤ 0.25）→ 走降级 prompt，明确告知”证据不足”
  • AMBIGUOUS（灰区）→ 条件触发 WebWorker 补偿检索
• 依赖：Step 4-6
• 验证：构造低分场景验证 LOW 降级；构造灰区场景验证 Web 补偿
• 文档同步：02-Agentic-RAG核心设计.md、04-优化迭代记录.md、08-RAG系统痛点分析与优化路径.md

Phase 3：检索增强#

目标：在新架构上加 HyDE 与 Parent Document Retrieval。 风险：中；都在 RetrievalWorker 内部，不影响外部架构。

Step 8：HyDE 假设文档生成#

• 新增：service/rag/HyDEGenerator.java、prompts/hyde_generation.txt
• 修改：
  • RetrievalWorker.java — specificity == FUZZY 时先调 HyDE 生成假设答案，再用其 embedding 检索
  • AiConfigHolder — 增加 hyde_enabled=true、hyde_model=qwen-turbo
• 依赖：Step 4
• 验证：模糊查询走 HyDE，日志可见生成的假设文档
• 文档同步：03-检索与排序链路.md、04-优化迭代记录.md

Step 9：Parent Document Retrieval#

• 新增字段：kb_chunk.parent_chunk_id
• 修改：
  • TextChunker.java — 双层切块：父块 1500 字符（生成用）、子块 400 字符（检索用），子块记录 parent_id
  • Milvus schema — embedding 仅存子块；父块只存 MySQL
  • RetrievalWorker.java — 命中子块后查询父块返回到上下文
• 风险：需重建索引，提供后台任务
• 依赖：Step 4
• 验证：检索命中的 chunk 在 PromptAssembler 中显示为父块完整段落
• 文档同步：03-检索与排序链路.md、04-优化迭代记录.md

Phase 4：用户体验收尾#

Step 10：输出置信度标注 + 推荐阅读#

⚠️ 四刀改造迁移注记（2026-06-07）：本 Step 的置信度原本由 SelfReflection 的 confidence 映射等级。四刀改造（C）删除了 SelfReflection，置信度改由 CitationParser（纯 Java）派生：confidenceScore = clamp(引用覆盖率) × rerank-top1（覆盖率不可算时退回 rerank-top1），再映射为 confidenceBand。done SSE 载荷的置信度字段语义不变，但来源已从自反思换成引用覆盖率。

• 修改：
  • controller/DocMindChatController.java — done SSE 事件增加 confidenceLevel（高/中/低）、recommendations 数组
  • SelfReflection.java — confidence 数值映射等级（≥0.8 高 / ≥0.6 中 / 其他 低） → 四刀后置信度由 CitationParser 覆盖率派生（SelfReflection 已删）
  • DocMind-frontend/src/views/chat/ChatView.vue — 渲染置信度徽章 + 推荐卡片
• 新增：service/rag/RecommendationGenerator.java（基于 chunk tags/category 反查同主题文档）
• 依赖：Step 3（用 tags）+ Step 7（用 confidence）
• 验证：前端能看到”置信度: 高”标识和”延伸阅读”卡片
• 文档同步：05-工程化实践.md、04-优化迭代记录.md

Phase 5：范畴判定与检索置信度评估#

触发原因：用户在某次对话中输入”总结上面的对话”，系统把这句话的关键词拿去 Milvus 做向量检索，召回了 12 条与对话主题完全无关的切片，然后用这些无关内容生成回答，置信度 0% 仍然推送给前端。这是一个真实出现过的 bug，根因是只有一层意图分类（factoid / procedural / comparison / opinion / chitchat），五个取值都默认要去查知识库。

解决思路：在原有意图分类之上加一层”要不要查知识库”的判断；在检索完成后再加一道”查到的内容跟问题对不对得上”的检查。两道闸都做了降级路径，任何一道判错或调用失败都会回到原来的流程。

Step 12：顶层范畴判定（Tier-0 规则 + Tier-1 模型）#

决定一条问题进入哪条处理路径。区分六种情况：知识检索、元对话、闲聊、超范围、知识库元查询、任务执行。

• 新增：
  • agent/ScopeDecision.java — record，包含范畴、置信度、是否走规则、判定理由
  • agent/MetaIntentDetector.java — 纯正则识别高置信度的元对话指令（“总结上面”、“翻译你刚才说的”）和闲聊（“你好”、“谢谢”）
  • agent/ScopeRouter.java — 调小模型给出范畴决策，输出 JSON
  • prompts/scope_routing.txt — 提示词，含 8 个边界示例
• 修改：
  • agent/DocMindAgent.java — 紧急词检查之后、缓存查询之前插入 decideScope()；新增 handleConversationOnly、handleChitchat、handleRefuse 三个短路方法。元对话路径完全不调用任何 Worker、不查 Milvus、不查 BM25，仅基于历史对话回答
  • agent/state/AgentState.java — 新增 scopeDecision 字段
  • 配置：scope.fast_path_enabled / scope.llm_enabled / scope.history_limit
• 降级：规则路径异常 → 让模型路径兜；模型路径异常 → 默认按知识查询走原流程
• 依赖：无
• 验证：
  • 单元测试 MetaIntentDetectorTest（11 条用例覆盖 META_CONVERSATION / CHITCHAT / 不命中）
  • 端到端：先正常问答建立历史，再问”总结上面的对话”，预期 SSE 流出现 scope=META_CONVERSATION，没有 retrieval / rerank 事件
• 文档同步：02-Agentic-RAG核心设计.md、04-优化迭代记录.md、11-面试高频质疑应答.md、13-简历素材与STAR故事.md

Step 13：检索结果三档置信度评估#

检索完成后给一道分。CRAG 论文（Yan et al. 2024）的做法是用一个独立的小模型评估检索质量，分三档触发不同后续动作。

• 新增：
  • service/rag/GradeResult.java — record（HIGH / AMBIGUOUS / LOW + topScore + avgScore + reason）
  • service/rag/RetrievalGrader.java — 三档评估器
• 修改：
  • service/rag/RetrievedChunk.java — 加 topicRelevance 字段（评估时标注用）
  • agent/worker/RetrievalWorker.java — Cross-Encoder 重排 + MMR + 父块展开之后调用 retrievalGrader.grade()，结果写入 Evidence metadata
  • agent/DocMindAgent.java — 从 metadata 提取 grader 结果，发 SSE grader 事件，LOW 档让现有 fallback 路径接管
• 评估策略（避免每条查询都额外调一次模型）：
  • 快路径：rerank 顶分 ≥ 0.60 直接判 HIGH，≤ 0.25 直接判 LOW，无需仲裁
  • 灰区四种模式：
    • cross_encoder（默认）— 把 top-3 切片拼接成一段上下文，让 reranker 对 (问题, 上下文) 这一对单独打分。一次 reranker 调用 ≈ 50ms
    • llm — 调小模型仲裁（保留为对比基线）
    • heuristic — 用分数分布规则判定（顶分与次分的差、前三平均分），零额外调用
    • disabled — 直接判 AMBIGUOUS
• 配置：grader.high_threshold / grader.low_threshold / grader.arbitration_mode
• 依赖：Step 4（Worker 接口）
• 验证：单元测试 RetrievalGraderTest（12 条用例覆盖四种模式 + 异常降级 + 旧配置兼容）
• 文档同步：02-Agentic-RAG核心设计.md、03-检索与排序链路.md、04-优化迭代记录.md

Step 14：自纠错增加切题度检查#

⚠️ 四刀改造已整体移除（2026-06-07，C 刀）：本 Step 产出的 topicMismatch 切题度检查随整个 SelfReflection 子系统一并删除——生成即终态，不再有生成后的二次审查 / 条件重写 / 四维打分 / 切题度检查。检索跑题现在靠生成前的 CRAG 质量闸拦截；答案忠实度改由结构化引用覆盖率体现（无据陈述会拉低覆盖率，置信度随之走低，且每个 [n] 可点击核对）。以下为历史记录。

原 SelfReflection 只检查事实一致性、完整性、来源匹配、表达质量，无法识别”检索到的内容跟问题完全不是一个主题”。Step 13 的 LOW 档可以兜住一部分，但漏判时仍可能进入生成。在反思阶段加最后一道闸。

• 修改：
  • agent/SelfReflection.java — ReflectionResult record 加 topicMismatch + topicMismatchReason 两个字段；反思提示词追加切题度检查项
  • agent/DocMindAgent.java — 反思命中跑题时跳过重写直接走 fallback（重写救不回主题不对的引用，反而浪费一次模型调用）
• 配置：reflection.topic_check_enabled
• 依赖：Step 12 / 13
• 验证：手动触发场景——查询主题与所选知识库内容不相关，预期反思日志 topicMismatch=true，前端显示低置信度警告
• 文档同步：02-Agentic-RAG核心设计.md、04-优化迭代记录.md

Step 15：合并模式与前端可视化#

上面三步先按”独立组件、独立调用”实现，便于单独调试。可观测、可证伪后再做两个工程优化。

• 优化 1：把范畴判定合并进 QueryUnderstanding 一次模型调用
  • 把 scope 字段加到 QueryClassification 和 query_understanding.txt 提示词
  • 合并模式开启时（scope.merge_with_understanding=true，默认开），decideScope 直接调 QueryUnderstanding 拿到 scope + 改写 + 分类，结果缓存到 AgentState.cachedUnderstanding，runReActLoop 复用
  • 知识查询路径整条流程只调一次路由模型（原本 2 次：ScopeRouter + QueryUnderstanding），节省 ~250ms
  • 关闭合并时回到独立 ScopeRouter（便于排错）
• 优化 2：灰区仲裁默认走 Cross-Encoder 而不是模型生成
  • DashScope gte-rerank 单对调用 ≈ 50ms，是模型生成调用的 1/5 时延
  • 灰区命中率 ~10%，整体省 ~75% 的灰区仲裁成本
• 优化 3：前端展示范畴和检索置信度
  • ChatView.vue 监听 scope 与 grader SSE 事件
  • 气泡顶部新增两枚徽章：「范畴：元对话/闲聊/知识查询/任务执行/越界」+「检索：高/中/低」
  • 鼠标悬停展示置信度数字、判定来源（规则/模型）、判定理由
  • 推理过程列表加 scope / grader 两类步骤
• 新增单元测试：
  • MetaIntentDetectorTest（11 用例）
  • RetrievalGraderTest（12 用例覆盖四种仲裁模式 + 异常降级 + 旧配置兼容）
• 文档同步：02-Agentic-RAG核心设计.md、05-工程化实践.md、13-简历素材与STAR故事.md

Phase 5 调研依据#

实施前调研了 12 个生产级框架/产品 + 3 篇核心论文，结论汇总：

被弃用的方案：

• 纯靠模型函数调用决定是否检索：LinkedIn、Airbnb v1→v2、Microsoft Semantic Kernel 都从这个路径迁出，原因是模型容易过度检索、识别不出元对话
• 用单一阈值硬切 HIGH / LOW：CRAG 专门留了 Ambiguous 一档应对评估器不准的场景

改动清单总览#

Step 11：评测对照（每个 Phase 完成后追加）#

• 跑 09-评测体系建设.md 中的评测脚本
• 把 Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 的指标变化记录到 10-评测结果与发现.md
• 跟踪指标：Recall@5、回答正确率、平均延迟、Token 消耗

提交粒度建议#

面试文档同步对照表#

每条 04 迭代记录格式：背景痛点 → 方案设计 → 实现细节 → 数据对比 → 面试话术。

新会话续作时的引导词#

我要开始 Phase X，先读 interview-docs/12-Agentic-RAG改造执行计划.md 定位当前进度，然后按 Step 顺序执行该 Phase 的任务。每完成一个 Step 后更新进度跟踪表，并按”面试文档同步对照表”更新对应面试文档。