工程化技术概括
说一个项目是企业级，肯定得看实际的工程质量。Super Agent 不是"能跑通就行"的 Demo 项目，而是在每一个工程细节上都对标真实生产系统的标准来做。从几个维度来评估：
工程规范
- 分层架构：business / common / framework 三层职责清晰，AI 业务逻辑、通用 Web 能力、基础设施组件互不耦合
- 统一异常处理：全局异常拦截 + 统一响应格式 ApiResponse，业务代码不需要到处 try-catch
- 自动装配机制：基础组件通过 Spring Boot Starter 方式封装，引入依赖即可使用，零配置代码
- MyBatis-Plus 自动填充：创建时间、更新时间等公共字段自动处理，不需要每个 Mapper 手动设置
- API 文档规范：Knife4j 增强的 Swagger 文档，接口定义即文档
Super Agent 的代码组织不是简单的 MVC 三层，而是按照领域职责做了更细粒度的拆分：
- super-agent-business：纯业务逻辑层，包含聊天、文档管理等业务模块
- super-agent-common：通用能力层，包含 Web 框架能力和通用工具
- super-agent-*-framework：基础设施层，包含 Redis 分布式能力、ID 生成器等基础组件
这种拆分方式使得每一层都可以独立演进和复用。比如 Redis 分布式能力框架，不仅在聊天场景中用于会话锁定，在文档处理场景中同样可以直接复用。
分层架构的模块职责
| 模块 | 职责 | 关键组件 |
|---|---|---|
| super-agent-business-chat | AI 对话业务 | Controller、执行器、编排器、检索服务 |
| super-agent-common-frame | 框架层能力 | 统一响应、全局异常、自动填充 |
| super-agent-common-web | Web 通用能力 | 请求拦截、跨域配置、参数校验 |
| super-agent-id-generator-framework | 分布式 ID | 雪花算法、集群安全的 ID 生成 |
| super-agent-redisson-framework | Redis 分布式 | 分布式锁、租约管理、延迟队列、重复执行限制 |
集群安全与并发控制
这是很多开源项目完全忽略的部分，但在生产环境中至关重要。一个 AI 对话系统如果不做并发控制，很容易出现同一条消息被多个实例重复处理、长对话锁超时被其他实例抢占等问题。
- Redis 租约互斥：
RedisLeaseManager实现集群级别的会话锁定，防止同一条消息被多个实例重复处理 - JVM 级任务注册：
ChatRuntimeRegistry维护进程内的任务注册表，防止同进程重入 - 租约续期：执行过程中自动续期，防止长对话超时导致锁释放后被其他实例抢占
- 优雅降级：无论成功还是失败，统一触发清理流程，不会留下孤儿锁
只用 Redis 分布式锁能防止跨实例重复处理，但不能防止同一个 JVM 内的并发重入。只用 JVM 级锁能防止进程内重入，但不能防止集群间的重复。两层锁配合使用，才能在分布式环境下做到万无一失。
并发控制的完整生命周期
一次对话请求的并发控制流程如下：
- 请求进入：先在
ChatRuntimeRegistry中注册 JVM 级任务，防止同进程重入 - 获取租约：通过
RedisLeaseManager获取集群级分布式租约，防止跨实例重复处理 - 自动续期：对话执行过程中，后台线程自动续期租约，防止长对话超时
- 执行完毕：主动释放 Redis 租约 + 注销 JVM 任务注册
- 异常保护：任何环节出现异常，finally 块统一触发清理，不留孤儿锁
这套机制确保了在多实例部署的生产环境中，每条消息都只会被一个实例处理一次，即使实例宕机或重启也不会出现数据不一致。
设计模式实战
项目中落地了多种经典设计模式，不是为了用模式而用，每个都解决了实际的扩展性或解耦问题：
| 设计模式 | 应用场景 | 解决的问题 |
|---|---|---|
| 策略模式 | 三种会话记忆策略、四种切块策略 | 不同策略可插拔替换，新增策略不改已有代码 |
| 工厂模式 | 检索通道创建、切块器创建 | 复杂对象的创建逻辑集中管理 |
| 模板方法 | 文档处理流水线各节点 | 统一执行流程，子类只关注核心逻辑 |
| 责任链模式 | RAG 前置编排器的五步决策链 | 多个处理步骤按顺序串联，灵活组合 |
| 观察者模式 | SSE 流式输出回调 | 流式事件的异步通知与推送 |
| AOP | 重复执行限制、全局异常拦截 | 横切关注点与业务代码解耦 |
设计模式的具体落地细节
会话记忆模块定义了统一的策略接口，三种实现（无记忆、滑动窗口、摘要压缩）各自独立。系统通过配置项决定使用哪种策略，运行时通过工厂方法获取对应实现。如果未来需要新增一种记忆策略（比如基于 RAG 的长期记忆），只需要新增一个实现类，不需要修改任何已有代码。这就是开闭原则在实际项目中的落地。
责任链模式在前置编排器中的应用尤为典型。五步决策链（路由判定 → 问题改写 → 歧义检测 → 子问题拆分 → 知识域收缩）的每一步都是一个独立的处理节点，节点之间通过链式调用串联。这种设计使得：
- 每个节点可以独立开发和测试
- 可以灵活调整节点的执行顺序
- 可以按需跳过某些节点（比如简单问题不需要子问题拆分）
- 新增决策步骤只需要加一个节点，不影响已有流程
模板方法在文档处理中的应用同样精巧。文档处理流水线的每个阶段（解析、策略推荐、切块、向量化、索引构建）都遵循统一的模板：前置检查 → 核心逻辑 → 状态更新 → 日志记录。子类只需要实现核心逻辑部分，其他环节由模板统一处理，确保了整个流水线的一致性和可追踪性。
可扩展性
核心模块都预留了扩展点，这是企业级项目和 Demo 项目最本质的区别：
- 新增检索通道：实现检索通道接口，注册为 Spring Bean，自动参与双通道检索
- 新增切块策略：实现切块策略接口，可加入组合流水线的任意位置
- 新增记忆策略：实现记忆策略接口，系统自动识别并可配置使用
- 新增工具调用：给 ReactAgent 注册新的 Tool，自动参与工具选择
- 新增 MCP Server：部署符合 MCP 协议的 Server，Agent 自动发现并注册
- 新增 Skill：在 Skills 目录下放入 SKILL.md 配置文件，零配置即刻生效
不需要改框架代码，加个实现类或配置文件就完事了。这才是面向接口编程和插件化架构的正确打开方式。
Super Agent 的可扩展性不是"留了几个接口"这么简单，而是贯穿整个系统的依赖倒置原则——核心逻辑依赖抽象而非具体实现。检索引擎不关心具体有几个通道、每个通道怎么实现，它只关心"通道接口"。切块引擎不关心具体有几种策略，它只关心"策略接口"。这种设计使得系统可以在不修改核心代码的前提下，持续扩展新能力。
扩展点的完整清单
| 扩展点 | 接口 / 协议 | 扩展方式 | 生效方式 |
|---|---|---|---|
| 检索通道 | 检索通道接口 | 新增 Spring Bean | 自动参与检索 |
| 切块策略 | 切块策略接口 | 新增实现类 | 加入组合流水线 |
| 记忆策略 | 记忆策略接口 | 新增实现类 | 配置切换 |
| Agent 工具 | Tool 注册 | 注册新 Tool | 自动参与工具选择 |
| MCP 工具 | MCP 协议 | 部署 MCP Server | Agent 自动发现 |
| Skills 能力 | SKILL.md | 放入目录 | 零配置生效 |
全链路可观测
基于 AOP 的全链路追踪，每个环节的耗时、输入输出、决策结果都有记录。思考过程、检索通道使用情况、证据来源、工具调用记录——全部可视化呈现在管理后台的观测面板中。出了问题不用猜，直接看 Trace 就知道哪一步出了问题。
可观测的具体维度
| 观测维度 | 记录内容 | 用途 |
|---|---|---|
| 编排决策 | 路由结果、改写前后对比、子问题列表 | 分析编排逻辑是否合理 |
| 检索过程 | 各通道命中数、分数分布、融合结果 | 优化检索参数 |
| 证据评估 | 证据数量、质量评分、预算使用情况 | 调整证据阈值 |
| 模型调用 | 输入 Token 数、输出 Token 数、响应延迟 | 成本分析和性能优化 |
| 工具调用 | 调用次数、成功率、平均耗时 | 工具可靠性监控 |
| 端到端延迟 | 各阶段耗时、总延迟 | 性能瓶颈定位 |
在生产环境中，用户反馈"回答不准确"或"响应太慢"时，传统做法是翻日志、加断点、猜测问题。有了全链路追踪后，可以直接打开观测面板，看到这次请求的完整链路：编排器判断走了哪个分支、检索了哪些文档、证据评分是多少、模型用了多少 Token。问题根因一目了然，大幅缩短排查时间。
和其他普通的 Agent 项目有什么区别
市面上大多数 Agent 项目，说白了就是跑通一个示例就完事了。Super Agent 和这些项目的差距在哪？直接对比一下：
| 对比维度 | 普通 RAG 项目 | Super Agent |
|---|---|---|
| 检索方式 | 单路向量检索 | 双通道并行（PGVector + ES）+ RRF 融合 + 可选 Rerank |
| 问题处理 | 原始问题直接检索 | 改写 + 子问题拆分 + 知识域收缩 |
| 意图判断 | 无 | 前置编排器五步决策 + 歧义主动追问 |
| 执行策略 | 所有问题走同一个模型 | 三层执行器按场景分流（追问 / 知识问答 / Agent） |
| 会话记忆 | 全量塞给模型或不带 | 无记忆 / 滑动窗口 / 摘要压缩三种策略 |
| 文档切块 | 固定长度一刀切 | 四种策略组合流水线 + 系统自动推荐 |
| 文档入库 | 同步处理，无日志 | Kafka 异步流水线 + 分步骤任务日志 |
| Agent 能力 | 无或仅简单对话 | ReAct 循环 + 联网搜索 + 工具调用 + Checkpoint 持久化 |
| 证据控制 | 无 | 预算裁剪 + 无证据短路防幻觉 |
| 检索粒度 | 命中什么用什么 | Parent-Child 块聚合，检索用小块、回答用大块 |
| 流式输出 | 简单 SSE 推文本 | 正文 + 引用来源 + 推荐追问 + 停止生成 |
| Agent 安全 | 无限制 | 模型调用次数 Hook + 工具调用次数 Hook + 重试兜底 |
| MCP 协议 | 无或硬编码 Function Call | MCP 标准协议 + 动态发现 + 多工具编排 + 安全沙箱 |
| 能力扩展 | 固定能力，改代码才能加 | Skills 声明式定义 + 自动加载 + 热插拔扩展 |
| 集群安全 | 单机运行 | Redis 租约互斥 + JVM 任务注册 + 租约续期 |
| 可观测性 | 无 | 全链路 Trace + 可视化观测面板 |
| 知识路由 | 无，全库检索 | 三级漏斗（Scope → Topic → Document）+ 混合打分自动锁定文档 |
| 文档结构 | 无 | Neo4j 图数据库构建 Document → Section → Item 层级图谱 |
| 路由质量观测 | 无 | 影子路由静默对比 + 命中率追踪 + 持续优化闭环 |
一句话：每个环节都不是调个 API 就完事的，而是有完整的设计和工程考量。
在面试中聊项目对比时，不要只列功能差异，更要讲清楚"为什么要这么做"。比如不是简单说"我们用了双通道检索"，而是说"纯向量检索对精确匹配天然弱势，用户问一个订单号向量检索完全找不到，所以我们加了关键词检索通道，两路并行后用 RRF 融合排序"。讲清楚问题 → 方案 → 权衡，比列功能清单有说服力得多。
用到的技术一览
技术选型背后的考量
每个技术的选型都不是随意的，背后都有明确的工程考量：
为什么选 PGVector + Elasticsearch 双引擎，而不是只用一个？
向量数据库擅长语义理解但对精确匹配弱，倒排索引擅长精确匹配但缺乏语义理解能力。两者互补才能覆盖用户检索的所有场景。PGVector 的优势是和 PostgreSQL 深度集成，既是关系型数据库又支持向量检索，运维成本低。Elasticsearch 则是倒排索引领域的工业标准，性能和功能都久经验证。
为什么用 Kafka 做异步解耦？
文档处理流水线是典型的长耗时任务（解析 → 切块 → 向量化 → 索引），如果同步处理用户要等很久。用 Kafka 做异步解耦后，上传操作秒级完成，后续处理在后台异步进行。同时 Kafka 提供了可靠的消息投递保证，即使处理实例宕机也不会丢失任务。
为什么选 Spring AI 而不是 LangChain4j？
Spring AI 是 Spring 官方出品，和 Spring Boot 生态深度集成，自动配置、依赖注入等 Spring 开发者熟悉的能力都可以无缝使用。对于 Java 开发者来说，学习曲线最平滑。Spring AI Alibaba 在此基础上提供了阿里云 DashScope 适配和 ReactAgent 实现，进一步降低了接入门槛。
为什么选 Redisson 做分布式能力？
Redisson 不仅提供了分布式锁，还有完善的租约（Lease）机制、看门狗（Watchdog）自动续期、可重入锁等高级特性。在 Super Agent 的集群并发控制场景中，这些能力都是必不可少的。相比直接用 Redis 命令手写分布式锁，Redisson 更安全、更稳定、经过了大量生产环境的验证。
总结
Super Agent 的工程化水平体现在方方面面：从分层架构的模块解耦，到集群环境下的并发安全；从设计模式的恰当运用，到全链路可观测的调试能力；从面向接口的扩展性设计，到每一个技术选型背后的工程权衡。
这不是一个"能跑通就行"的项目，而是一个你可以在面试中逐层展开、越聊越深的项目。 不管面试官从哪个角度切入——架构设计、并发控制、设计模式、技术选型——你都能给出有深度、有细节的回答。这才是"企业级"三个字真正的含义。