Nexus Agent 是一个 企业级 的 AI 智能体对话平台，覆盖智能对话、文档知识问答、联网搜索、RAG 检索、MCP 工具协议、Skills 能力扩展、Harness 工程化控制、会话记忆管理、等完整能力。

项目从对话入口开始，到意图分析、检索决策、多路知识召回、证据驱动生成，再到会话记忆管理、MCP 外部工具集成和文档治理，每一个环节都不是简单调个接口就完事的，而是经过深度设计和反复打磨的工程化实现。

快速导航

项目核心亮点

• ReAct Agent 智能体的完整实现：不只是能聊天，而是支持联网搜索、工具调用、多步推理、Checkpoint 持久化，真正能自主决策和行动的 Agent。
• 三层执行器体系：系统不是把所有问题都交给 Agent，而是先做确定性编排，再按场景选择歧义追问、知识问答或开放式 Agent。
• Neo4j 文档结构图谱：每份文档在索引构建时生成 Document -> Section -> Item 层级图结构，支持章节定位、邻接遍历和结构化导航。
• 知识路由三级漏斗：用户提问后先走 Scope -> Topic -> Document 三级排序漏斗，自动锁定最相关的知识范围，再进入检索链路。
• 影子路由质量观测：用户手动选择文档时，系统在后台静默运行知识路由，对比系统推荐和用户实际选择，用于持续评估和优化路由质量。
• RAG 前置编排引擎：路由判定、问题改写、子问题拆分、知识域收缩、歧义澄清，在模型回答前先把检索计划做好。
• 双通道混合检索：向量检索和关键词检索并行执行，RRF 融合排序，可选外部 Rerank 精排，召回率和精准度兼顾。
• 证据预算控制与无证据短路：多子问题证据需要严格裁剪；没有找到相关证据时直接告知用户，不让模型凭空编造。
• Parent-Child 块聚合：检索粒度用 Child 小块保证命中率，回答阶段聚合到 Parent 大块保证上下文完整性。
• 三种会话记忆策略：无记忆、滑动窗口、摘要压缩，完整展示生产环境下如何平衡 Token 成本和上下文完整性。
• MCP 工具协议集成：Agent 可以动态发现和调用外部工具，不再局限于硬编码 Function Call。
• Skills 能力扩展体系：通过 SKILL.md 声明式定义技能，支持目录化管理、自动加载、引用脚本和参考资料。
• 文档从上传到可检索的完整链路：Tika 多格式解析、组合式切块、向量化、向量数据库 + 倒排索引双引擎构建，每一步都有任务日志。
• 组合式切块引擎：结构切块做主干、递归分块做兜底、语义分块做边界优化、LLM 智能切块处理疑难文档。
• 联网搜索与工具调用保护：集成 Tavily 搜索，支持工具重试、指数退避、异常兜底，模型调用和工具调用都有 Hook 限制。
• 推荐追问问题生成：主回答完成后额外生成最多 3 个可继续追问的问题，引导用户深入探索。
• SSE 流式输出协议：正文分片实时推送，结束时补发引用来源和推荐问题，支持主动停止生成。

前端层负责会话执行和运营控制台，接口与流式层负责请求、SSE、鉴权和中断控制，核心链路串起会话记忆、Query 改写、知识路由、图谱导航、多通道检索和 Prompt 组装。

底层再由 MySQL、PGVector、Elasticsearch、Neo4j、Redis、Kafka、MinIO、Tika 等基础设施共同提供能力。也就是说，项目亮点不是只在某个单独 Agent 里，而是分布在整条 AI 应用链路上。

核心架构

Nexus Agent 不是单点能力堆叠，而是围绕 对话编排中心、三层执行器、知识底座、检索证据、工具扩展、工程化护栏 这几块协同工作的完整体系：

系统整体是怎么跑的

用户在输入框里敲了一句话，点了发送。看起来很简单，但在 Nexus Agent 内部，这条消息要经过一条远比你想象中复杂的链路，才能变成一个靠谱的回答。

先看对话执行链路，后面再逐块拆解每个环节的设计细节：

核心思路是：不是让 Agent 自己决定所有事情，而是先用确定性的编排逻辑做好决策，再把执行交给最合适的引擎。 知识问答走稳定的证据驱动生成，开放式问题才走 Agent 自由探索。

为什么需要这个项目？

大多数人学 AI 的方式是跟着教程调一下 API，往向量库里塞点数据，让模型输出一段话——结束了。这顶多算跑通了一个 Demo，一旦追究细节就露馅了。真正的 AI 应用和调 API 之间，差的不是代码量，是对每个环节的深入理解和工程化设计。

而此项目就是为了解决这个问题：它覆盖了 Agent 智能体、RAG 检索增强生成、MCP 工具协议、Skills 能力扩展、会话记忆管理、Harness 工程化控制、文档生命周期治理 这些 AI 应用层的核心技术，每一块都有完整的设计和代码实现，复杂度对标真实企业级系统。

调个 API 不等于会 RAG

很多教程的套路是：调一下 Embedding 接口，往向量数据库里塞点数据，再用大模型生成答案——完事了。这顶多算跑通了一个 Demo。

真正的 RAG 系统要考虑的问题多得多：文档怎么切分效果最好？检索召回率不够怎么办？多路召回怎么融合排序？幻觉怎么控制？这些才是面试官会追问的点。跑通 Demo 和做出能上线的系统之间，差的不是代码量，是对每个环节的深入理解。

RAG 并不简单

一个能用的 RAG 系统至少涉及问题改写、子问题拆分、知识域收缩、混合检索、父子块聚合、引用来源、无证据短路和会话记忆。每一环都会影响最终效果。

只关注模型，忽略工程能力

RAG 项目的核心竞争力不在于你用了多强的模型，而在于工程化能力。同样的模型，检索策略不同、Prompt 设计不同、分块粒度不同，最终效果可以天差地别。

举个例子：用户问 "打印机墨盒怎么换"，文档里写的是 "墨盒更换步骤"。关键词搜索直接匹配不上，但向量检索能理解它们是一回事。这背后是 Embedding 模型的选型、向量数据库的调优、检索结果的重排序——每一步都是工程决策，不是换个更贵的模型就能解决的。

用框架套一下不等于企业级

执行器路由、前置编排器五步决策链、双通道检索融合、Parent-Child 块聚合、证据预算控制与无证据短路、组合式切块引擎、摘要压缩记忆、集群级租约互斥、全链路观测追踪。这些构成项目核心竞争力的能力，这些框架并不具备的能力，在此项目中全都有实现。

核心设计拆解

• 用户提了一个问题，系统是怎么决定用哪种方式来回答的？ 不是让模型自己选，而是先经过路由判定、问题改写、歧义检测这一整轮编排，最后才决定走哪个执行器。判断顺序是：歧义澄清 > 知识问答 > 开放式 Agent

• 为什么不是所有问题都走 Agent？ 知识问答追求"稳"和"可解释"，让 Agent 自己探索反而容易不可控。只有真正需要联网搜索、多步推理的开放式问题，才适合走 Agent

• Agent 死循环了怎么办？ 用 ModelCallLimitHook 限制单次运行最多调用模型 8 次，用 ToolCallLimitHook 限制 Tavily 搜索最多调 6 次。单个会话线程累计也有上限，分别是 40 次和 30 次

• 联网搜索调用失败了怎么处理？ ToolRetryInterceptor 做指数退避重试，最多重试 2 次，初始延迟 200ms，最大延迟 1200ms，带随机抖动。如果最终还是失败，ToolErrorInterceptor 做兜底，不让异常直接抛给用户

• 对话状态怎么持久化？ 用 Spring AI Alibaba 的 MysqlSaver 把 ReactAgent 的 Checkpoint 存到 MySQL，应用重启后能继续之前的对话

• 并行工具执行怎么做？ ReactAgent 配置了 parallelToolExecution，最多 4 个工具并行执行

三层执行器：不是所有问题都该交给 Agent

知识问答追求"稳"和"可解释"——用户问"退款规则是什么"，你需要的是从文档中精准检索证据，然后让模型基于证据生成回答。这种场景让 Agent 自己探索反而容易不可控，可能跑去联网搜索一堆无关内容。

而"今天北京天气怎么样"这种问题，知识库里根本没有答案，必须让 Agent 调用搜索工具去获取实时信息。

所以 Nexus Agent 设计了三层执行器，按场景精准分流：

判断顺序是：歧义澄清 > 知识问答 > 开放式 Agent。优先用最稳定的方式回答，只有确实需要自由探索时才启动 Agent。

在知识问答内部，系统还会继续判断问题是不是结构定位类问题。比如"第三章第二节讲了什么"、"上一节内容是什么"，会优先走 Neo4j 图查询；普通语义问答才进入向量 + 关键词的混合检索链路。这样既能处理结构化导航，也能处理开放表达的知识问答。

前置编排器到底做了什么

前面说了系统不会把所有问题直接扔给模型，而是先做一轮完整的编排。它在每次对话中做的事情远比你想象的多：

路由判定

用户发进来的消息，首先要判断它属于哪种类型。是一个可以在知识库里找到答案的问题？还是需要联网搜索的开放式问题？还是信息不全需要先追问？这个判定不是靠关键词匹配，而是通过模型分析上下文后给出路由方向。

问题改写

用户的问题往往不适合直接检索。比如"那它怎么配置？"——"它"指的是什么？得结合前几轮对话才知道。问题改写就是把这些省略的信息补回来，让检索能找到东西。

问题改写效果：

子问题拆分

"退款规则是什么？审批流程怎么走？"这种复合问题，如果直接拿去检索，两个意图互相干扰，效果很差。系统会拆成独立子问题，每个单独走检索链路，最后合并结果。单轮最多拆 4 个子问题，避免过度切碎。

意图解析与知识域收缩

拆完子问题后，还要分析每个子问题属于哪个知识域，把检索范围从"全库"缩小到"相关领域"。这一步直接影响检索的精准度和速度。

歧义检测

如果用户的问题信息量不够，比如只说"查一下那个"，系统不会硬着头皮去检索，而是先生成澄清问题让用户补充信息。这比返回一个不相关的答案体验好得多。

所有这些步骤完成后，编排器会产出一个 执行计划，里面包含执行多种执行编排模式、改写后的问题、拆分后的子问题列表、知识域范围等，交给对应的执行器去执行。

检索链路到底有多细

很多人以为检索过程就是"查个向量库 + 让模型回答"，但实际上中间的环节比想象中多得多。下面列的这些问题，在项目中都有对应的设计：

问题进来之后怎么处理？

• 用户问"那它怎么配置？"这种省略了主语的追问，直接拿去检索什么都找不到。所以要先做问题改写，结合最近几轮历史把指代补全
• 一个问题里问了两件事，比如"退款规则是什么？审批流程怎么走？"，不能一股脑去检索。要拆成独立子问题，每个子问题单独走检索链路
• 单轮最多拆 4 个子问题，避免过度切碎

检索是怎么做的？

• 不是只用向量检索。用户问一个订单号、一个配置项名，向量检索很可能找不到。所以用了双通道并行：向量检索 + 关键词检索
• 两路结果分数量纲完全不同，不能直接比大小。用 RRF（Reciprocal Rank Fusion） 按排名倒数法融合
• 向量通道设了最低相似度，关键词通道用相对阈值，低于阈值的弱命中直接过滤掉
• 融合后可以接外部 Rerank 精排（支持 SiliconFlow 兼容协议），在较干净的候选集上继续优化排序
• 检索粒度用 Child 小块保证命中率，回答阶段通过 Parent-Child 聚合提升到 Parent 大块，保证上下文完整性

证据够不够怎么判断？

• 如果最终没有任何有效证据，直接短路返回，告诉用户"当前文档中没有检索到足够证据"。不让模型凭空编造，这是防止幻觉最直接的手段
• 如果证据太多，有预算控制：单个子问题字符、全部证据总预算，单个父块最大字符。防止把模型上下文窗口吃满

最终怎么组装回答？

• 按子问题边界分别组织证据，注入到 Prompt 里，模型按编号逐一回答
• 要求模型在引用证据时标注来源编号 [1][2]
• 答案通过 SSE 实时流式推送，结束时补发引用来源和推荐追问问题

双通道并行检索

用户问一个订单号、一个配置项名，向量检索很可能找不到——语义相似度对精确匹配天然弱势。所以 Super Nexus Agent 用了双通道并行：向量检索 + 关键词检索，两路同时出发，互不阻塞。

两路结果的分数量纲完全不同，不能直接比大小。系统用 RRF（Reciprocal Rank Fusion） 按排名倒数法融合，向量通道设了最低相似度阈值，关键词通道用相对阈值，低于阈值的弱命中直接过滤。融合后还可以接外部 Rerank 精排，在较干净的候选集上继续优化排序。

父子块聚合

这是整个检索链路中最精巧的设计之一。检索粒度用 Child 小块保证命中率——小块语义集中，更容易被向量检索命中。但回答阶段如果只用小块，上下文往往不完整。所以系统在命中 Child 块后，自动聚合提升到 Parent 大块，保证回答时有足够的上下文信息。

检索用小块保精度，回答用大块保完整性。 这个设计在业界也属于比较前沿的实践。

文档从上传到可检索经历了什么

很多项目的文档处理就是"切成固定长度 → 向量化 → 完事"。但实际上不同文档差异很大，一