前后端模块划分与调用关系

这篇文档聚焦后端部分，把 Super Agent 的 Maven 模块划分、聊天业务的包结构、各层核心类的职责和调用关系都理清楚。看完之后，你拿到任何一个类名，都能快速定位它在整个架构中的位置和作用。

Maven 模块总览

Super Agent 后端采用多模块 Maven 结构，每个模块有明确的职责边界：

模块	职责
`super-agent-common`	通用基础设施：枚举定义（`ChatQueryMode`、`ChatTurnStatus`）、工具类、统一响应封装
`super-agent-id-generator-framework`	分布式 ID 生成，为会话和轮次提供全局唯一标识
`super-agent-redisson-framework`	Redis 相关能力：分布式锁、重复执行限制、会话租约管理（`RedisLeaseManager`）
`super-agent-business-chat`	聊天系统的全部业务代码，是最核心的模块

聊天业务包结构

super-agent-business-chat 是整个聊天系统的核心，内部按职责划分成多个包。下面这张图展示了包之间的层次关系：

各包职责详解

下面逐个说明每个包里装了什么、负责什么：

controller —— 请求入口

只有一个类 BusinessChatController，负责接收前端 HTTP 请求、参数校验，然后转交给 Service 层。这一层不做任何业务逻辑。

// 控制器只做两件事：接参数、转交 Service
@RestController
@RequestMapping("/api/chat")
public class BusinessChatController {
    private final BusinessChatService businessChatService;

    @PostMapping(value = "/stream", produces = "text/event-stream;charset=UTF-8")
    public Flux<String> stream(@Valid @RequestBody ChatRequestDto dto) {
        return businessChatService.openConversationStream(dto);
    }
    // 还有 stop、reset、session 等接口...
}

dto / vo —— 数据传输

dto 包：前端传入的请求参数，比如 ChatRequestDto（问题、会话 ID、聊天模式）
vo 包：返回给前端的响应结果，比如 ConversationStopVo、ConversationResetVo

service —— 业务核心

这是整个聊天系统最重要的包，核心类包括：

类名	职责
`BusinessChatService`	会话编排总控：启动、执行、停止、重置、查询的入口
`TaskInfo`	运行时上下文：聚合了一次会话执行所需的所有状态
`StreamLaunchPlan`	启动计划：规范化后的请求参数
`ChatRuntimeRegistry`	运行态注册表：跟踪当前正在执行的会话任务
`ConversationArchiveStore`	归档存储接口：会话和轮次的持久化
`MybatisConversationArchiveStore`	归档存储的 MyBatis 实现
`ConversationMemoryService`	会话记忆服务：长期摘要和最近对话窗口管理
`ConversationTraceRecorder`	执行追踪记录器：记录每个阶段的状态和耗时
`ChatCheckpointManager`	Checkpoint 管理：底层 Agent 的状态快照
`RecommendationService`	推荐追问生成
`ObservedChatModelService`	带观测的模型调用封装

rag —— 检索增强生成

这个包是 RAG 链路的核心，内部又分了几个子包：

rag/executor：执行器实现，每种执行模式对应一个执行器
- ConversationExecutorRegistry —— 执行器注册表
- RagChatExecutor —— RAG 检索问答
- ReactAgentExecutor —— 开放式 Agent
- GraphOnlyExecutor —— 纯图查询
- GraphThenEvidenceExecutor —— 图查询 + 证据补充
- ClarificationExecutor —— 澄清确认
rag/service：RAG 链路中的各个服务
- ChatPreparationOrchestrator —— 编排器，决定走哪条执行路径
- ChatQueryRewriteService —— 问题改写
- DocumentQuestionRouter —— 文档问题路由
- RagRetrievalEngine —— 检索引擎
- RagPromptAssemblyService —— Prompt 组装
- StructureGraphQueryEngine —— 结构图查询引擎
- HttpDocumentRerankPostProcessor —— 重排序后处理
rag/retrieve/channel：检索通道实现（向量检索、关键词检索等）
rag/model：执行计划、检索上下文等数据模型
- ExecutionMode —— 执行模式枚举
- ConversationExecutionPlan —— 执行计划

support —— 支撑组件

StreamEventWriter —— SSE 事件格式化和写入
SinkEmitHelper —— Reactor Sink 安全发送封装
StreamEventMetadata —— 事件元信息（会话 ID、轮次 ID）
TimeSensitiveQueryHelper —— 时效性问题判断
ChatContextKeys —— 上下文键常量

tool —— 工具实现

Agent 可调用的外部工具，比如 TavilySearchTool（联网搜索）。

manage —— 文档管理

文档知识库的管理能力，包括文档上传、解析、索引、知识路由等。这部分虽然和聊天在同一个 Maven 模块里，但逻辑上是独立的子系统。

核心调用链路

理解了包结构之后，我们来看一次完整的聊天请求在这些类之间是怎么流转的。

主链路：从请求到响应

编排器内部的调用关系

编排器 ChatPreparationOrchestrator 是决策中枢，它内部会调用多个服务来完成执行计划的生成：

// ChatPreparationOrchestrator 的依赖注入
public class ChatPreparationOrchestrator {
    private final ChatRagProperties properties;              // RAG 配置
    private final ConversationMemoryService memoryService;   // 会话记忆
    private final AnswerHistoryContextAssembler historyAssembler; // 历史上下文组装
    private final ChatQueryRewriteService rewriteService;    // 问题改写
    private final DocumentQuestionRouter documentRouter;     // 文档问题路由
    private final KnowledgeRouteService knowledgeRouteService; // 知识范围路由
    private final DocumentKnowledgeService documentKnowledgeService; // 文档知识服务
}

它的调用顺序是：

ConversationMemoryService → 加载会话记忆（长期摘要 + 最近窗口）
AnswerHistoryContextAssembler → 组装回答用的历史上下文
ChatQueryRewriteService → 把用户问题改写成检索友好的表达
KnowledgeRouteService → 自动文档模式下，路由到目标文档
DocumentQuestionRouter → 判断走图查询还是混合检索

Service 层的依赖全景

BusinessChatService 是整个聊天系统的总控，它依赖的组件最多：

// BusinessChatService 的依赖注入（共 14 个组件）
public class BusinessChatService {

    // Agent 相关
    private final ReactAgent businessChatReactAgent;         // 底层 ReactAgent
    private final ChatCheckpointManager checkpointManager;   // Checkpoint 管理

    // 配置
    private final ChatAgentProperties chatAgentProperties;   // 聊天配置

    // 会话生命周期
    private final ConversationArchiveStore archiveStore;     // 归档存储
    private final ChatRuntimeRegistry runtimeRegistry;       // 运行态注册表
    private final ConversationMemoryService memoryService;   // 会话记忆

    // 执行编排
    private final ChatPreparationOrchestrator orchestrator;  // 编排器
    private final ConversationExecutorRegistry executorRegistry; // 执行器注册表

    // 输出与推荐
    private final StreamEventWriter streamEventWriter;       // SSE 事件写入
    private final RecommendationService recommendationService; // 推荐追问

    // 分布式控制
    private final RedisLeaseManager redisLeaseManager;       // Redis 租约

    // 观测与追踪
    private final ConversationTraceStageStore traceStageStore; // 阶段追踪存储
    private final RetrievalObserveStore retrievalObserveStore; // 检索观察存储
    private final StageBenchmarkService stageBenchmarkService; // 阶段基准

    // 文档知识
    private final DocumentKnowledgeService documentKnowledgeService; // 文档知识服务
}

设计思路

虽然 BusinessChatService 依赖的组件看起来很多，但每个组件的职责都很单一。这种"轻度的总控 + 厚度的组件"的设计，让每个组件都可以独立测试和替换，总控只负责把它们串起来。

分层架构总结

从整体来看，Super Agent 后端的聊天系统是一个清晰的分层架构：

层次	包	核心职责
接入层	`controller`	接收 HTTP 请求，参数校验，返回 SSE 流
编排层	`service`	会话生命周期管理、执行流组装、收尾落库
决策层	`rag/service`	意图分析、问题改写、知识路由、执行模式判定
执行层	`rag/executor`	按模式执行具体的检索/生成/澄清逻辑
检索层	`rag/retrieve`	多路检索通道（向量、关键词等）
支撑层	`support`	SSE 事件格式化、时效性判断、上下文管理
持久层	`data` / `mapper`	数据库实体和 MyBatis 映射
基础设施	`common` / `redisson` / `id-generator`	枚举、分布式锁、租约、ID 生成

每一层只依赖它下面的层，不会反向依赖，这保证了架构的清晰度和可维护性。

企业级项目导航：⬅️ 01-从用户提问到答案返回的总流程 | 02-前后端模块划分与调用关系 | ➡️ 03-提问到返回