by java-up-up
企业级 AI 智能体 Agent 平台,覆盖智能对话、文档知识问答、联网搜索、RAG 检索、MCP 工具协议、Skills 扩展等完整能力。三层执行器体系、双通道混合检索、组合式切块引擎、会话记忆管理、全链路可观测,每个环节都经过深 度设计和工程化打磨。
# Add to your Claude Code skills
git clone https://github.com/java-up-up/super-agentNo comments yet. Be the first to share your thoughts!
开源不易,还请您点个 Star 多谢!🎉
Super Agent 是一个 企业级 的 AI 智能体对话平台,覆盖了智能对话、文档知识问答、联网搜索、RAG 详细检索、MCP 工具协议、Skills 能力扩展、文档全生命周期管理等完整能力。
项目从对话入口开始,到意图分析、检索决策、多路知识召回、证据驱动生成,再到会话记忆管理、MCP 外部工具集成和文档治理,每一个环节都不是简单调个接口就完事的,而是经过深度设计和反复打磨的工程化实现。
现在的 Java 面试,光靠八股文和 CRUD 项目已经越来越难了。微服务、高并发这些之前算是亮点的东西,现在也慢慢成了标配。面试官开始问:RAG 是什么?Agent 怎么实现的?会话记忆怎么设计?向量检索用的什么方案?你做过文档问答吗? 这些问题已经从加分项变成了必答题。
但问题是,大多数人学 AI 的方式是跟着教程调一下 API,往向量库里塞点数据,让模型输出一段话——结束了。这顶多算跑通了一个 Demo,面试官一追问就露馅。真正的 AI 应用和调 API 之间,差的不是代码量,是对每个环节的深入理解和工程化设计。
而 Super Agent 就是为了解决这个问题:它覆盖了 Agent 智能体、RAG 检索增强生成、MCP 工具协议、Skills 能力扩展、会话记忆管理、文档生命周期治理 这些 AI 应用层的核心技术,每一块都有完整的设计和代码实现,复杂度对标真实企业级系统。不管是学生还是工作了几年的同学,学完之后面试中都能真正聊得起来,而且聊得有深度。
很多人觉得自己"会 RAG 了"、"懂 Agent 了",但面试一深入就露馅。在正式介绍项目之前,先把几个常见误区理清楚。
很多教程的套路是:调一下 Embedding 接口,往向量数据库里塞点数据,再用大模型生成答案——完事了。这顶多算跑通了一个 Demo。
真正的 RAG 系统要考虑的问题多得多:文档怎么切分效果最好?检索召回率不够怎么办?多路召回怎么融合排序?幻觉怎么控制?这些才是面试官会追问的点。跑通 Demo 和做出能上线的系统之间,差的不是代码量,是对每个环节的深入理解。
Retrieval-Augmented Generation 这个名字容易让人觉得就是检索加生成。但实际工程中,一个能用的 RAG 系统至少涉及这些环节:
每一环都有坑,每一环都值得深挖。面试的时候能把这些讲清楚,比背概念有用得多。
RAG 项目的核心竞争力不在于你用了多强的模型,而在于工程化能力。同样的模型,检索策略不同、Prompt 设计不同、分块粒度不同,最终效果可以天差地别。
举个例子:用户问 "打印机墨盒怎么换",文档里写的是 "墨盒更换步骤"。关键词搜索直接匹配不上,但向量检索能理解它们是一回事。这背后是 Embedding 模型的选型、向量数据库的调优、检索结果的重排序——每一步都是工程决策,不是换个更贵的模型就能解决的。
Spring AI / LangChain4j 是好工具,但直接拿来用是远远不够!
执行器路由、前置编排器五步决策链、双通道检索融合、Parent-Child 块聚合、证据预算控制与无证据短路、组合式切块引擎、摘要压缩记忆、集群级租约互斥、全链路观测追踪。这些构成项目核心竞争力的能力,这些框架并不具备的能力,在此项目中全都有实现。

先直接列出来,小伙伴心里有数:
ReAct Agent 智能体的完整实现:不只是能聊天,而是支持联网搜索、工具调用、多步推理、Checkpoint 持久化,真正能自主决策和行动的 Agent
三层执行器体系:系统不是把所有问题都交给 Agent,而是先做确定性编排,再按场景选最合适的回答引擎(歧义追问 / 知识问答 / 开放式 Agent),这套分层调度机制是整个系统的核心竞争力
Neo4j 图数据库驱动的文档结构图谱:每份文档在索引构建时,会同步在 Neo4j 中生成 Document → Section → Item 的层级图结构,支持章节编号定位、邻接遍历、子节点展开等图查询,让检索不再只靠向量匹配,还能沿着文档结构精准导航
知识路由三级漏斗:用户提问后,系统不是直接全库检索,而是先走一轮 Scope → Topic → Document 的三级排序漏斗,通过语义 + 词法 + 关键词实体的混合打分,自动锁定最相关的文档,再进入检索链路。路由置信度不够时会主动降级,不会硬猜
影子路由质量观测:当用户手动选择文档时,系统在后台静默跑一遍完整的知识路由,对比"系统会选什么"和"用户实际选了什么",把命中率、置信度、候选排名等数据全部记录下来,用于持续评估和优化路由模型,整个过程对用户完全无感
RAG 前置编排引擎:路由判定、问题改写、子问题拆分、知识域收缩、歧义澄清,在模型回答之前把所有决策做完,确保每一次检索都是精准的
双通道混合检索:向量检索 和 关键词检索 并行执行,RRF 融合排序,可选外部 Rerank 精排,召回率和精准度兼顾
证据预算控制与无证据短路:模型上下文窗口有限,多子问题的证据量需要严格裁剪;没有找到相关证据时直接告知用户,不让模型凭空编造,从架构层面杜绝幻觉
Parent-Child 块聚合:检索粒度用 Child 小块保证命中率,回答阶段通过聚合提升到 Parent 大块,保证上下文完整性。这个设计在业界也属于比较前沿的实践
三种会话记忆策略:无记忆、滑动窗口、摘要压缩,生产环境下怎么平衡 Token 成本和上下文完整性,三种方案都有完整实现和对比演示
MCP 工具协议集成:基于 Model Context Protocol 标准协议,Agent 可以动态发现和调用外部工具,不再局限于硬编码的 Function Call,真正实现了工具能力的即插即用
Skills 能力扩展体系:通过 SKILL.md 配置文件声明式定义技能,支持目录结构化管理、自动加载、引用脚本和参考资料,让 Agent 的能力边界可以持续扩展而不需要改动核心代码
文档从上传到可检索的完整链路:Tika 多格式解析、四种切块策略组合流水线、向量化、向量数据库 + 倒排数据库 双引擎索引,每一步都有独立的任务日志和状态追踪
组合式切块引擎:—结构切块做主干、递归分块做兜底、语义分块做边界优化、LLM 智能切块处理疑难文档,系统按文档类型自动推荐最优策略组合
联网搜索与工具调用:集成 Tavily 搜索,支持工具重试、指数退避、异常兜底,模型调用次数和工具调用次数都有 Hook 限制,防止资源滥用和死循环
推荐追问问题生成:主回答完成后额外调用模型,生成最多 3 个可继续追问的问题,引导用户深入探索
SSE 流式输出协议:正文分片实时推送,结束时补发引用来源和推荐问题,支持主动停止生成,用户体验对标主流 AI 产品
用户在输入框里敲了一句话,点了发送。看起来很简单,但在 Super Agent 内部,这条消息要经过一条远比你想象中复杂的链路,才能变成一个靠谱的回答。
先看整体流程,后面再逐块拆解每个环节的设计细节:
核心思路是:不是让 Agent 自己决定所有事情,而是先用确定性的编排逻辑做好决策,再把执行交给最合适的引擎。 知识问答走稳定的证据驱动生成,开放式问题才走 Agent 自由探索。
面试中聊 Agent,面试官不想听你说"我用了 ReactAgent",他想听的是你对这些问题的思考:
用户提了一个问题,系统是怎么决定用哪种方式来回答的? 不是让模型自己选,而是先经过路由判定、问题改写、歧义检测这一整轮编排,最后才决定走哪个执行器。判断顺序是:歧义澄清 > 知识问答 > 开放式 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 调用搜索工具去获取实时信息。
所以 Super Agent 设计了三层执行器,按场景精准分流:
| 执行器 | 触发条件 | 处理方式 | | :----------------- | :--------------------------------- | :--------------------------------- | | 歧义追问执行器 | 用户问题信息量不足,无法确定意图 | 生成澄清问题,引导用户补充信息 | | RAG 知识问答执行器 | 问题可以在知识库中找到答案 | 证据驱动生成,引用来源可追溯 | | ReAct Agent 执行器 | 需要联网搜索、多步推理的开放式问题 | 自主决策 + 工具调用 + 多轮推理循环 |
判断顺序是:歧义澄清 > 知识问答 > 开放式 Agent。优先用最稳定的方式回答,只有确实需要自由探索时才启动 Agent。
前面说了系统不会把所有问题直接扔给模型,而是先做一轮完整的编排。它在每次对话中做的事情远比你想象的多:
用户发进来的消息,首先要判断它属于哪种类型。是一个可以在知识库里找到答案的问题?还是需要联网搜索的开放式问题?还是信息不全需要先追问?这个判定不是靠关键词匹配,而是通过模型分析上下文后给出路由方向。
用户的问题往往不适合直接检索。比如"那它怎么配置?"——"它"指的是什么?得结合前几轮对话才知道。问题改写就是把这些省略的信息补回来,让检索能找到东西。
"退款规则是什么?审批流程怎么走?"这种复合问题,如果直接拿去检索,两个意图互相干扰,效果很差。系统会拆成独立子问题,每个单独走检索链路,最后合并结果。单轮最多拆 4 个子问题,避免过度切碎。
拆完子问题后,还要分析每个子问题属于哪个知识域,把检索范围从"全库"缩小到"相关领域"。这一步直接影响检索的精准度和速度。
如果用户的问题信息量不够,比如只说"查一下那个",系统不会硬着头皮去检索,而是先生成澄清问题让用户补充信息。这比返回一个不相关的答案体验好得多。
所有这些步骤完成后,编排器会产出一个 执行计划,里面包含执行多种执行编排模式、改写后的问题、拆分后的子问题列表、知识域范围等,交给对应的执行器去执行。
很多人以为检索过程就是"查个向量库 + 让模型回答",但实际上中间的环节比想象中多得多。下面列的这些问题,在项目中都有对应的设计:
[1][2]用户问一个订单号、一个配置项名,向量检索很可能找不到——语义相似度对精确匹配天然弱势。所以 Super Agent 用了双通道并行:向量检索 + 关键词检索,两路同时出发,互不阻塞。
两路结果的分数量纲完全不同,不能直接比大小。系统用 RRF(Reciprocal Rank Fusion) 按排名倒数法融合,向量通道设了最低相似度阈值,关键词通道用相对阈值,低于阈值的弱命中直接过滤。融合后还可以接外部 Rerank 精排,在较干净的候选集上继续优化排序。
这是整个检索链路中最精巧的设计之一。检索粒度用 Child 小块保证命中率——小块语义集中,更容易被向量检索命中。但回答阶段如果只用小块,上下文往往不完整。所以系统在命中 Child 块后,自动聚合提升到 Parent 大块,保证回答时有足够的上下文信息。
检索用小块保精度,回答用大块保完整性。 这个设计在业界也属于比较前沿的实践。
很多项目的文档处理就是"切成固定长度 → 向量化 → 完事"。但实际上不同文档差异很大,一刀切的效果很难好。Super Agent 的文档处理是一条完整的异步流水线,每一步都有独立的状态追踪和任务日志:
文件上传到 MinIO 对象存储后,通过 Kafka 异步触发解析任务。Apache Tika 负责处理 PDF、Word、PPT 等多种格式,把五花八门的文档统一转成干净的文本。PDF 里的表格、扫描件、双栏排版——每一个都是坑,Tika 帮你踩过了。
并且可以配置 知识域编码、知识域名称、业务分类、文档标签 等元信息,后续检索和分析都能用得上。
解析完成后,系统不是让用户盲选切块算法,而是根据文档类型和内容特征自动推荐最优的切块策略组合。用户可以查看推荐结果,也可以手动调整——比如文档质量不太好,可以额外开启 LLM 智能切块。
四种切块策略不是四选一,而是各司其职的组合流水线:
| 策略 | 角色 | 什么时候用 | | :--------------- | :--- | :----------------------------------- | | 基于文档结构切块 | 主干 | 按标题/章节/段落切成语义完整的块 | | 递归分块 | 兜底 | 结构块太大时继续往下裁剪,控制块大小 | | 语义分块 | 优化 | 在结构切块基础上做边界精修 | | LLM 智能切块 | 增强 | 处理低质量文档和复杂文档,默认关闭 |
一句话:结构负责保留文档天然边界,递归负责控制块大小,语义负责优化块边界,大模型负责处理疑难场景。
确认策略后,系统通过 Kafka 异步执行向量化和索引构建。向量写入向量数据库,关键词写入倒排索引数据库,构建双通道检索的基础。每一步都有独立的任务日志,出了问题能精确定位到哪一步失败。
20 轮对话全塞给模型?Token 成本扛不住。只带最近几轮?可能丢掉关键上下文。这是生产环境下绕不开的问题。