AI 这波浪潮来得太快了。

半年前面试还在聊微服务和高并发，现在面试官张口就是：RAG 怎么做的？Agent 的执行链路是什么样的？你的检索策略是怎么设计的？会话记忆怎么控制 Token 成本？

这些问题已经不是加分项了，而是越来越多 JD 里的硬性要求。

但现实是，大部分人接触 AI 的方式还停留在"调 API"的阶段——跟着教程往向量库里塞点数据，让大模型吐一段话，截个图发朋友圈说自己"做过 RAG 了"。面试官稍微追问两句就露馅：文档怎么切的？检索召回率低怎么办？幻觉怎么控制？一问三不知。

跑通一个 Demo 和做出一个能上线的系统，中间差的不是几行代码，而是对每个环节的深入理解和工程化设计。

这就是我做 Super Agent 的初衷。

Super Agent 是什么

Super Agent 是一个企业级 AI 智能体对话平台。说"企业级"不是随便贴个标签，而是从架构设计到每一个技术细节，都对标真实生产环境的复杂度。

它覆盖的能力包括：智能对话、文档知识问答、联网搜索、RAG 检索增强生成、MCP 工具协议、Skills 能力扩展、文档全生命周期管理。

• GitHub 开源地址：https://github.com/java-up-up/super-agent
• 项目详细讲解：https://javaup.chat/super-agent/overview/project-intro

先看一下对话界面的效果：

整个项目的技术全景可以用这张思维导图来概括：

看起来内容很多，别急，下面我会把每个核心模块拆开来讲。

为什么不能只是"调个 API"

在深入技术细节之前，我想先聊几个很多人都会踩的坑。这些坑不搞清楚，后面的设计你可能看不懂为什么要这么做。

第一个坑：以为 RAG 就是"检索 + 生成"

Retrieval-Augmented Generation 这个名字确实容易误导人。但你真正去做一个 RAG 系统就会发现，光是"检索"这两个字背后就藏着一堆工程问题：

• 文档格式五花八门，PDF 里有表格、有扫描件、有双栏排版，光是把它们解析成干净文本就够喝一壶的
• 文档切块切太大，检索不精准；切太小，上下文丢失。而且不同类型的文档可能需要完全不同的切块策略
• 用户问"那它怎么配置？"，"它"是什么？不结合上下文，系统根本不知道在问啥
• 纯向量检索对精确匹配天然弱势，用户问一个订单号，向量检索可能完全找不到
• 20 轮对话全塞给模型，Token 成本扛不住；只带最近几轮，又可能丢掉关键上下文

第二个坑：只盯着模型，忽略工程能力

同样的大模型，检索策略不同、Prompt 设计不同、分块粒度不同，最终效果可以天差地别。举个例子：用户问"打印机墨盒怎么换"，文档里写的是"墨盒更换步骤"。关键词搜索直接匹配不上，但向量检索能理解它们语义相近。这背后是 Embedding 模型的选型、向量数据库的调优、检索结果的重排序——每一步都是工程决策，不是换个更贵的模型就能搞定的。

第三个坑：用框架套一套就觉得是企业级

Spring AI、LangChain4j 确实是好工具，但它们提供的是基础能力。执行器路由、前置编排器五步决策链、双通道检索融合、Parent-Child 块聚合、证据预算控制与无证据短路、组合式切块引擎、摘要压缩记忆、集群级租约互斥、全链路观测追踪——这些能力框架里都没有，但恰恰是一个 AI 系统能不能上生产的关键。在 Super Agent 中，这些全都有完整实现。

搞清楚这些坑，再来看 Super Agent 的设计，你就能理解每个决策背后的"为什么"了。

一条消息进来，系统到底经历了什么

用户在输入框里敲了一句话，点了发送。看起来就是一个简单的请求-响应，但在 Super Agent 内部，这条消息要穿过一条精心设计的处理链路，才能变成一个靠谱的回答。

先看整体流程图，有个全局印象：

整个系统的核心设计理念只有一句话：不是让 Agent 自己决定所有事情，而是先用确定性的编排逻辑把决策做好，再把执行交给最合适的引擎。

知识问答这种需要"稳"和"可追溯"的场景，走证据驱动生成；只有真正需要联网搜索、多步推理的开放式问题，才交给 Agent 去自由探索。

下面按照消息的流转顺序，逐个拆解每个环节。

三层执行器：凭什么说"不是所有问题都该交给 Agent"

这是整个系统最核心的设计决策。

很多 AI 项目的做法是：不管什么问题，统统丢给 Agent 去处理。但这样做有一个致命问题——不可控。用户问"退款规则是什么"，你希望系统从文档里精准找到答案，结果 Agent 可能跑去联网搜索了一堆无关内容。

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

不同类型的问题，需要不同的处理方式。所以 Super Agent 设计了三层执行器，按场景精准分流：

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

这套分层调度机制，是整个系统的核心竞争力。

Agent 执行引擎：不只是能聊天

当系统判定一个问题需要走 Agent 路径时，背后是一套完整的 ReAct（Reasoning + Acting）执行引擎在工作。

面试中聊 Agent，面试官真正想听的不是"我用了 ReactAgent"，而是你对这些工程问题的思考和解决方案：

Agent 死循环了怎么办？

这是 Agent 系统最常见的问题。Super Agent 用了双层限制：ModelCallLimitHook 限制单次运行最多调用模型 8 次，ToolCallLimitHook 限制 Tavily 搜索最多调 6 次。单个会话线程累计也有上限，分别是 40 次和 30 次。不会出现 Agent 无限循环烧 Token 的情况。

联网搜索调用失败了怎么处理？

ToolRetryInterceptor 做指数退避重试，最多重试 2 次，初始延迟 200ms，最大延迟 1200ms，带随机抖动防止雪崩。如果最终还是失败，ToolErrorInterceptor 做兜底处理，不让异常直接抛给用户。

对话状态怎么持久化？

用 Spring AI Alibaba 的 MysqlSaver 把 ReactAgent 的 Checkpoint 存到 MySQL。应用重启、服务迁移，用户都能继续之前的对话，不会丢失上下文。

并行工具执行怎么做？

ReactAgent 配置了 parallelToolExecution，最多 4 个工具并行执行，提升响应速度。

这些设计在代码里都有对应实现，不是停留在概念层面的东西。

来看 Agent 的执行流程图：

前置编排器：模型回答之前，先把决策做完

这是 Super Agent 和大多数 AI 项目拉开差距的关键环节。

很多项目的做法是：用户问了什么，就直接拿去检索或者丢给模型。但 Super Agent 在模型回答之前，会先跑一轮完整的编排决策链，确保每一次检索都是精准的。

这个编排器一共做五件事：

第一步：路由判定

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

第二步：问题改写

用户的问题往往不适合直接拿去检索。比如"那它怎么配置？"——"它"指的是什么？得结合前几轮对话才知道。问题改写就是把这些省略的、指代不明的信息补回来，让检索系统能真正找到相关内容。

来看一下问题改写的实际效果：

第三步：子问题拆分

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

第四步：意图解析与知识域收缩

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

第五步：歧义检测

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

五步走完，编排器会产出一个完整的执行计划，包含路由方向、改写后的问题、拆分后的子问题列表、知识域范围等，交给对应的执行器去执行。

来看前置编排器的决策链路图：

检索链路：远不止"查个向量库"那么简单

很多人以为 RAG 的检索就是"往向量库里查一下，把结果丢给模型"。但在 Super Agent 里，从问题进来到证据组装完毕，中间经历的环节比你想象的多得多。

先看整体的检索链路图：

知识路由：先锁定文档，再进入检索

用户提问后，系统不是直接对全库发起检索，而是先走一轮 Scope → Topic → Document 的三级排序漏斗。

这个漏斗通过语义相似度、词法匹配、关键词实体三种信号的混合打分，自动锁定最相关的文档，然后才进入后续的检索链路。如果路由的置信度不够高，系统会主动降级到更宽的检索范围，而不是硬猜一个可能不相关的文档。

更有意思的是 影子路由质量观测：当用户手动选择了某个文档时，系统会在后台静默跑一遍完整的知识路由流程，对比"系统会选什么"和"用户实际选了什么"。命中率、置信度、候选排名这些数据全部记录下来，用于持续评估和优化路由模型。整个过程对用户完全无感，但对系统的持续改进至关重要。

双通道并行检索：向量 + 关键词，两条腿走路

为什么不能只用向量检索？因为语义相似度对精确匹配天然弱势。用户问一个订单号、一个配置项名称，向量检索很可能完全找不到——这些精确信息在语义空间里没有明显的近邻关系。

所以 Super Agent 用了双通道并行的方案：向量检索（PGVector）和关键词检索（Elasticsearch） 同时出发，互不阻塞。向量通道擅长语义理解，关键词通道擅长精确匹配，两者互补。

但两路结果的分数量纲完全不同——向量检索返回的是余弦相似度，关键词检索返回的是 BM25 分数，不能直接放在一起比大小。系统用 RRF（Reciprocal Rank Fusion） 按排名倒数法做融合排序，向量通道设了最低相似度阈值，关键词通道用相对阈值，低于阈值的弱命中直接过滤掉，避免噪声干扰。

融合之后还可以接外部 Rerank 精排（支持 SiliconFlow 兼容协议），在已经比较干净的候选集上进一步优化排序，把最相关的结果推到最前面。

Parent-Child 块聚合：检索用小块，回答用大块

这是整个检索链路中我觉得最精巧的设计。

检索阶段用 Child 小块来保证命中率——小块语义集中，更容易被向量检索精准命中。但如果回答阶段也只用小块，上下文往往不完整，模型可能因为缺少前后文而给出片面的回答。

所以系统在命中 Child 块之后，会自动向上聚合到 Parent 大块，把完整的上下文信息带给模型。检索用小块保精度，回答用大块保完整性。 这个设计在业界也属于比较前沿的实践。

Neo4j 文档结构图谱：沿着文档结构精准导航

每份文档在索引构建时，系统会同步在 Neo4j 图数据库中生成 Document → Section → Item 的层级图结构。这意味着检索不再只靠向量匹配这一条路，还能沿着文档的天然结构进行精准导航——章节编号定位、邻接遍历、子节点展开，这些图查询能力让检索的维度更加丰富。

证据预算控制与无证据短路：从架构层面杜绝幻觉

检索到证据之后，还有两道关卡：

无证据短路

如果最终没有找到任何有效证据，系统直接短路返回，明确告诉用户"当前文档中没有检索到足够证据"。绝不让模型在没有依据的情况下凭空编造，这是防止幻觉最直接、最有效的手段。

证据预算控制

如果证据太多，也不能全塞给模型——上下文窗口是有限的。系统对单个子问题的证据字符数、全部证据的总预算、单个父块的最大字符数都有严格限制，确保模型拿到的是精炼的、高质量的证据，而不是一堆冗余信息。

最终回答的组装

证据准备好之后，系统按子问题的边界分别组织证据，注入到 Prompt 中，模型按编号逐一回答。要求模型在引用证据时标注来源编号 [1][2]，让用户能追溯每一句话的依据。

答案通过 SSE 实时流式推送给前端，正文分片推送保证用户能第一时间看到内容。回答结束时，补发引用来源列表和最多 3 个推荐追问问题，引导用户继续深入探索。支持用户主动停止生成，体验对标主流 AI 产品。

文档处理流水线：从上传到可检索的完整旅程

很多项目的文档处理就是"固定长度切一刀 → 向量化 → 塞进去"，三步完事。但实际上不同文档的差异非常大——一份结构清晰的技术文档和一份排版混乱的扫描 PDF，用同样的策略处理，效果能差十万八千里。

Super Agent 的文档处理是一条完整的异步流水线，每一步都有独立的状态追踪和任务日志：

上传与多格式解析

文件上传到 MinIO 对象存储后，通过 Kafka 异步触发解析任务，不会阻塞用户操作。Apache Tika 负责处理 PDF、Word、PPT 等各种格式，把五花八门的文档统一转成干净的文本。PDF 里的表格、扫描件、双栏排版——每一个都是坑，Tika 帮你踩过了大部分。

上传时还可以配置知识域编码、知识域名称、业务分类、文档标签等元信息，这些信息在后续的知识路由和检索分析中都能派上用场。

来看文档管理界面：

智能策略推荐

解析完成后，系统不会让用户面对一堆参数盲选切块算法。而是根据文档的类型、结构特征、内容质量，自动推荐最优的切块策略组合。用户可以直接采用推荐方案，也可以根据实际情况手动调整——比如文档质量不太好，可以额外开启 LLM 智能切块来处理疑难段落。

组合式切块引擎：四种策略各司其职

这里的设计思路不是"四选一"，而是让四种策略组成一条协作流水线，各自发挥所长：

一句话总结：结构负责保留文档天然边界，递归负责控制块大小，语义负责优化切分点，大模型负责处理疑难场景。

切块完成后可以预览验证效果：

向量化与双引擎索引构建

确认切块策略后，系统通过 Kafka 异步执行向量化和索引构建。向量数据写入 PGVector，关键词数据写入 Elasticsearch，为后续的双通道并行检索打好基础。

整个流水线的每一步都有独立的任务日志和状态追踪，哪一步成功了、哪一步失败了、失败的原因是什么，都能精确定位。不会出现"文档入库失败了但不知道哪里出了问题"的情况。

会话记忆：在 Token 成本和上下文完整性之间找平衡

这是生产环境下绕不开的问题。

20 轮对话的完整历史全塞给模型？Token 成本直接爆炸。只带最近两三轮？用户前面说过的关键信息可能就丢了，模型的回答会让人觉得"它什么都不记得"。

Super Agent 实现了三种记忆策略，覆盖不同场景的需求：

无记忆模式

每轮对话完全独立，不携带任何历史。适合一次性的简单查询，Token 成本最低。

滑动窗口模式

保留最近 N 轮的完整对话内容。适合短期连续追问的场景，实现简单，效果直观。

摘要压缩模式

这是生产环境下最推荐的方案。最近 4 轮 原文始终保留不做压缩，保证近期上下文的完整性；更早的历史通过增量摘要进行压缩，单次最多推进 6 轮，避免一次处理超长历史。最近原文窗口最大 2200 字符，长期摘要最大 1400 字符。既控制了 Token 成本，又不会丢失关键的历史信息。

所有记忆数据都持久化到 MySQL，应用重启不会丢失。

三种策略在项目中都有完整实现和对比演示，你可以直观地看到不同策略在实际对话中的表现差异。

MCP 工具协议：让 Agent 的工具能力即插即用

Agent 的价值不只是能聊天，更在于能调用外部工具完成实际任务。传统的做法是用 Function Call 硬编码——每接入一个新工具，就要改一次业务代码，写一套参数解析逻辑。工具一多，维护成本直线上升。

Super Agent 基于 MCP（Model Context Protocol） 标准协议实现了完整的工具调用链路。MCP 是 Anthropic 提出的开放协议标准，定义了模型与外部工具之间的通信规范。

具体实现了这些能力：

• 动态工具发现：Agent 启动时自动扫描并注册所有可用的 MCP 工具，不需要在代码里硬编码工具列表
• 标准化通信：工具的输入输出遵循 MCP 协议规范，支持 Stdio 和 SSE 两种传输模式，兼容主流 MCP Server 生态
• 参数自动提取：模型根据用户的意图自动识别需要调用哪个工具，并从对话中提取所需参数，用户不需要手动指定
• 多工具编排：单次对话中可以串联调用多个 MCP 工具，前一个工具的输出可以作为后一个工具的输入
• 安全沙箱：所有工具调用都在受控环境中执行，有超时限制和异常隔离，防止恶意工具或异常工具影响主流程

新增一个工具不需要改任何业务代码，只需要部署一个符合 MCP 协议的 Server，Agent 就能自动发现并使用它。这才是真正的即插即用。

Skills 能力扩展：让 Agent 持续成长

如果说 MCP 解决的是"Agent 怎么调用工具"的问题，那 Skills 解决的是"Agent 怎么获得特定领域的专业能力"。

每个 Skill 通过 SKILL.md 配置文件声明式定义能力边界、触发条件和执行逻辑，结构清晰易维护。Skills 按领域组织成目录结构，支持嵌套分类；系统启动时自动扫描 Skills 目录，新增 Skill 只需要放入对应目录，零配置即刻生效。

Skill 还可以关联外部脚本（Python、Shell 等）和参考文档，执行时自动加载上下文。多个 Skills 可以组合使用，Agent 根据任务需求自动选择最合适的 Skill 组合。

这套体系让 Agent 的能力边界不再是固定的。今天加一个"数据分析"Skill，明天加一个"代码审查"Skill，Agent 的能力就跟着增长，核心代码一行不用改。

工程质量：企业级不是靠嘴说的

说一个项目是"企业级"，不能只看功能多不多，更要看工程质量扛不扛得住。

分层架构与工程规范

项目采用 business / common / framework 三层架构，AI 业务逻辑、通用 Web 能力、基础设施组件职责清晰，互不耦合。全局异常拦截 + 统一响应格式 ApiResponse，业务代码不需要到处写 try-catch。基础组件通过 Spring Boot Starter 方式封装，引入依赖即可使用。MyBatis-Plus 自动填充公共字段，Knife4j 增强的 Swagger 文档让接口定义即文档。

集群安全与并发控制

这是很多开源项目完全忽略的部分，但在生产环境中至关重要。

RedisLeaseManager 实现集群级别的会话锁定，防止同一条消息被多个实例重复处理。ChatRuntimeRegistry 维护进程内的任务注册表，防止同进程重入。执行过程中自动续期，防止长对话超时导致锁释放后被其他实例抢占。无论成功还是失败，统一触发清理流程，不会留下孤儿锁。

设计模式的实战落地

项目中落地了多种经典设计模式，不是为了炫技，每个都解决了实际的工程问题：

全链路可观测

基于 AOP 的全链路追踪，每个环节的耗时、输入输出、决策结果都有完整记录。思考过程、检索通道使用情况、证据来源、工具调用记录——全部可视化呈现在管理后台的观测面板中。

出了问题不用猜，直接看 Trace 就知道哪一步出了问题、耗时多少、输入输出是什么。

来看执行阶段的时间线视图：

可扩展性

核心模块都预留了清晰的扩展点：新增检索通道，实现接口注册为 Spring Bean 即可自动参与检索；新增切块策略，实现接口即可加入组合流水线；新增记忆策略、新增工具调用、新增 MCP Server、新增 Skill——全都是加个实现类或配置文件就完事，不需要改框架代码。这才是面向接口编程和插件化架构的正确打开方式。

和市面上的 Agent 项目比，差距在哪

说了这么多设计细节，直接拉一张对比表，一目了然：

一句话：每个环节都不是调个 API 就完事的，而是有完整的设计思考和工程考量。

这个项目适合谁

在校生 / 校招同学

简历上已经有了商城、外卖这些常规项目，需要一个有区分度的项目来拉开差距。Super Agent 能让你在面试中聊 AI + 工程化，而不是千篇一律的 CRUD。项目基于 Java 技术栈，学习曲线平滑。大厂校招越来越看重候选人对新技术的敏感度，简历上有 AI 项目经验，能直接证明你的学习能力和技术视野。

1-3 年经验的社招同学

日常写业务代码，想往 AI 方向转型但不知道从哪下手。技术栈你都熟悉（Spring Boot、MySQL、Redis、Kafka），学的是 AI 应用层的东西，上手快。

3-5 年经验的社招同学

技术能力不差，但面试被问到 AI 相关问题答不上来，少了一个谈薪筹码。通过这个项目补上 RAG、Agent、MCP 这些知识点，面试时能聊得有深度。

想跳槽到 AI 团队的同学

越来越多的 JD 要求有 AI 相关经验，这个项目能帮你快速建立 RAG 系统和 Agent 智能体的全局认知。

学完 Super Agent，你既能跟面试官聊 RAG、Agent、MCP 的技术深度，也能证明自己的项目工程化水平。不管是校招还是社招，这个项目都能成为你简历上最有区分度的一笔。

用到的技术栈

• GitHub 开源地址：https://github.com/java-up-up/super-agent
• 项目详细讲解：https://javaup.chat/super-agent/overview/project-intro