UserContext
用户上下文容器（基于 TTL 传递当前线程的登录用户）。
该类提供线程隔离的用户信息存储与访问能力，支持在异步线程池中透传用户上下文。 基于阿里巴巴的 TransmittableThreadLocal（TTL）实现，相比普通 ThreadLocal， TTL 能在线程池异步任务中自动传递上下文，适用于 @Async、CompletableFuture 等异步场景。
核心功能：
设置用户：set(LoginUser) - 在拦截器中设置当前登录用户
获取用户：get() / requireUser() - 获取当前线程的登录用户信息
快捷方法：getUserId() / getUsername() / getRole() / getAvatar() - 获取用户的特定字段
清理上下文：clear() - 在请求结束时清理，防止内存泄漏
判断登录：hasUser() - 判断当前线程是否存在用户上下文
典型使用场景：
拦截器中设置：UserContextInterceptor.preHandle 从 Sa-Token 获取用户信息后调用 set()
Service 层获取：业务逻辑中通过 requireUser() 获取当前操作用户 ID/角色
请求结束清理：UserContextInterceptor.afterCompletion 调用 clear() 避免内存泄漏
异步场景透传：在 @Async 或 CompletableFuture 中自动传递用户上下文
使用示例：
// 1. 在拦截器中设置用户上下文
LoginUser loginUser = LoginUser.builder()
    .userId("1234567890")
    .username("admin")
    .role("admin")
    .avatar("https://...")
    .build();
UserContext.set(loginUser);

// 2. 在 Service 层获取当前用户
LoginUser user = UserContext.requireUser();
String userId = user.getUserId();
String role = user.getRole();

// 3. 或者使用快捷方法
String userId = UserContext.getUserId();
String username = UserContext.getUsername();

// 4. 在请求结束时清理（通常在拦截器的 finally 块中）
try {
    // 业务逻辑
} finally {
    UserContext.clear();
}

// 5. 异步场景中自动透传（无需额外处理）
@Async
public void asyncMethod() {
    // 这里可以正常获取用户上下文
    LoginUser user = UserContext.get();
}
重要注意事项：
必须清理：必须在请求结束时调用 clear() 清理上下文，否则在线程池复用场景下可能导致用户信息错乱
线程安全：所有方法都是线程安全的，不同线程之间的上下文互不影响
异步透传：使用 TTL 后，在 @Async、CompletableFuture 等异步场景中会自动传递上下文
空值处理：get() 可能返回 null，如果业务要求必须登录，应使用 requireUser()
不可变性：LoginUser 对象创建后不应修改，保证上下文的一致性

ChatQueueLimiter
SSE 流式对话全局并发限流与排队处理器。
基于 Redis 实现公平队列和信号量限流，保证系统在高并发场景下的稳定性。
核心功能：
全局限流：通过 Redis PermitExpirableSemaphore 控制全局最大并发数
公平排队：使用 Redis SortedSet 实现 FIFO 队列，按入队顺序分配 permit
原子抢锁：通过 Lua 脚本保证队列检查和 permit 获取的原子性，避免竞态条件
超时拒绝：等待超过最大时长后返回友好提示，并记录到对话历史
实时通知：permit 释放时通过 Redis Topic 广播，通知排队中的请求立即重试
优雅关闭：应用关闭时清理监听器、定时任务和资源
技术架构：
Redis 数据结构：
Semaphore: rag:global:chat - 控制并发数的信号量
SortedSet: rag:global:chat:queue - 排队队列，score 为入队序号
AtomicLong: rag:global:chat:queue:seq - 生成单调递增的入队序号
Topic: rag:global:chat:queue:notify - permit 释放时的广播通道
Lua 脚本：lua/queue_claim_atomic.lua - 原子性地检查队列头部并移除
定时任务：ScheduledThreadPoolExecutor - 定期轮询队列，尝试获取 permit
通知机制：PollNotifier - 收到广播后立即触发所有排队请求重试

整体流程（8 个阶段 + 3 个短路分支）
   1. 记忆加载     —— 读历史 + 追加当前消息，两级记忆（滑动窗口原文 + 摘要压缩）
   2. 查询重写     —— LLM 改写 + 规则兜底，输出改写结果和子问题列表
   3. 意图识别     —— 意图树 + LLM 分类 + 置信度门控，输出每个子问题的意图匹配
   ├─ 短路1：歧义反问 —— 最高置信度低于阈值时生成澄清问题反问用户，不继续后续阶段
   ├─ 短路2：系统直答 —— 所有意图均为 SYSTEM 类型时跳过检索，用节点模板直接生成回复
   4. 多通道检索   —— 外层按子问题并行编排（KB 检索 + MCP 工具调用），内层两通道并行
   ├─ 短路3：空结果 —— 检索返回空时直接回复"未检索到相关文档"，不浪费 LLM 调用
   5. 后处理链     —— 去重 + Rerank 精排（在 RetrievalEngine 内部完成）
   6. 提示词构建   —— 系统指令 + 长期记忆 + 短期记忆 + 检索上下文 + 用户问题
   7. LLM 流式推理 —— 模型路由 + 首包探活 + 故障转移，逐 token 通过 SSE 推送前端
 
短路设计
三个短路分支用 handleXxx 方法实现，返回 true 表示"已处理，流程终止"， 返回 false 表示"不满足短路条件，继续后续阶段"。这个模式避免了深层嵌套的 if-else，每个短路分支的触发条件和处理逻辑都在独立方法内，新增短路路径只需加一个 handle 方法并在 execute 中调用。
上下文传递
所有中间状态通过 StreamChatContext 在阶段间传递——它既是入参容器（用户问题、 会话ID、深度思考开关），也是出参容器（历史消息、重写结果、意图列表、检索上下文）。 每个阶段从 ctx 读取上一阶段的输出，处理后将结果写回 ctx，下一阶段继续消费。 这样做的好处是阶段之间零耦合——任一阶段的实现变更不影响其他阶段。
容错策略
不在此类内部做 try-catch。每个阶段的异常由调用方统一捕获并处理。这样编排器保持简洁，错误处理集中管理。

RetrievalEngine
 
检索引擎。
负责协调多通道检索（知识库）和 MCP（模型控制协议）工具的调用，并对检索结果进行重排序和格式化，最终生成用于 LLM 的上下文。
核心功能：
多子问题并行：对多个子问题并发执行检索，提升效率
知识库检索：调用 MultiChannelRetrievalEngine 执行多通道检索
MCP 工具调用：并行执行多个 MCP 工具获取动态数据
上下文格式化：将检索结果格式化为 LLM 可读的 Markdown 文本
异常容错：单个子问题或工具失败不影响整体流程

MultiChannelRetrievalEngine
 
多通道检索引擎。
负责协调多个检索通道和后置处理器，实现智能的多路召回策略。
核心功能：
并行检索：并发执行所有启用的检索通道，提升检索效率
后置处理链：依次执行去重、Rerank 等后置处理器
异常容错：单个通道或处理器失败不影响整体流程
详细统计：记录每个通道和处理器的执行情况

MCPParameterExtractor
 
MCP 参数提取器接口。
定义从用户问题中提取 MCP 工具调用所需参数的标准方法，支持默认提示词和自定义提示词两种模式。
核心功能：
参数提取：根据工具定义从用户问题中提取参数
自定义提示词：支持传入自定义参数提取提示词模板

MCPToolExecutor
 
MCP 工具执行器接口。
定义 MCP 工具的执行标准，包括获取工具定义、执行调用和请求匹配等功能。
核心功能：
工具定义：获取工具的元数据信息
工具执行：根据请求执行工具调用并返回响应
请求匹配：判断是否支持某个请求

MCPToolRegistry
 
MCP 工具注册表接口。
定义 MCP 工具执行器的注册、注销和查询标准，支持动态管理工具生命周期。
核心功能：
工具注册：注册和注销工具执行器
工具查询：按 toolId 查询、列表查询、存在性检查
统计信息：获取已注册工具数量

SearchChannel
 
检索通道抽象接口。
每个通道代表一种独立召回策略，例如全局向量检索或意图定向检索。多通道检索引擎会并发执行它们， 再统一合并结果。
核心功能：
通道标识：提供名称、优先级和类型用于调度和监控
启用判断：根据上下文动态决定是否参与本次检索
执行检索：返回当前通道的召回结果及统计信息

IntentDirectedSearchChannel
 
意图定向检索通道。
基于意图识别结果，在特定知识库中进行定向检索。这是最精确的检索方式，优先级最高。
核心功能：
意图过滤：只提取 KB 类型的意图节点
并行检索：对多个意图对应的知识库并发执行检索
动态 TopK：根据配置倍率扩大检索范围
异常容错：检索失败时返回空结果，不影响其他通道

VectorGlobalSearchChannel
 
向量全局检索通道。
在所有知识库中进行向量检索，作为意图定向检索的兜底策略。当没有识别出意图或意图置信度较低时启用。
核心功能：
全量检索：在所有 KB collection 中并行执行向量检索
智能启用：根据意图置信度动态决定是否启用
异常容错：检索失败时返回空结果，不影响其他通道


AbstractParallelRetriever<T>
 
并行检索抽象模板类。
封装通用的并行检索逻辑，采用模板方法模式，子类只需实现具体的检索任务创建逻辑。
核心功能：
并行执行：使用 CompletableFuture 并发提交多个检索任务到线程池
结果收集：等待所有任务完成并合并结果
异常容错：单个任务失败不影响其他任务，记录失败日志
统计信息：记录成功/失败数量和总 Chunk 数
子类需要实现三个抽象方法：
createRetrievalTask - 创建单个检索任务
getTargetIdentifier - 获取目标标识（用于日志）
getStatisticsName - 获取统计名称（用于日志）
类型形参:
<T> – 检索目标类型（如 NodeScore、String）

PgRetrieverService
 
PostgreSQL pgVector 向量检索服务实现。
基于 PostgreSQL 的 pgVector 扩展实现向量相似度检索，支持 HNSW 索引和余弦距离计算。
核心功能：
向量嵌入：使用 EmbeddingService 将文本转换为向量
向量归一化：对嵌入向量进行 L2 归一化
HNSW 检索：设置 ef_search 参数提升召回率
余弦相似度：使用 <=> 运算符计算余弦距离

ModelSelector
 
模型选择器，负责按能力类型、优先级、思考模式和健康状态筛选可用候选。
核心功能：
能力分类：支持 Chat、Embedding、Rerank 三种能力的模型选择
深度思考：根据是否需要深度思考，选择不同的聊天模型
优先级排序：按首选模型、优先级分数、ID 顺序进行多级排序
健康过滤：自动跳过被熔断或不可用的模型
配置校验：检查提供商配置是否存在，缺失时记录警告并跳过
选择流程：
从 AIModelProperties 获取对应能力的模型组配置
解析首选模型 ID（深度思考时使用 deepThinkingModel，否则使用 defaultModel）
过滤候选列表：排除已禁用的模型，深度思考模式下只保留支持思考的模型
排序候选列表：首选模型排第一，然后按优先级降序，最后按 ID 升序
构建 ModelTarget：为每个候选创建包含完整配置的 ModelTarget 对象
健康检查：跳过已被判定为不可用的模型
提供商校验：检查提供商配置是否存在，缺失时记录警告
使用场景：
Chat 服务：RoutingChatService 调用 selectChatCandidates() 获取聊天模型列表
Embedding 服务：RoutingEmbeddingService 调用 selectEmbeddingCandidates() 获取嵌入模型列表
Rerank 服务：RoutingRerankService 调用 selectRerankCandidates() 获取重排序模型列表
设计原则：
灵活性：支持通过配置动态调整候选列表和优先级，无需修改代码
容错性：配置缺失或模型不可用时自动降级，不会导致整个服务失败
可扩展性：新增能力类型只需添加对应的 selectXXXCandidates() 方法
性能优化：在构建阶段就过滤掉不可用模型，避免在执行阶段快速失败
典型用法：
// 1. 选择聊天模型候选（非深度思考模式）
List<ModelTarget> chatCandidates = modelSelector.selectChatCandidates(false);

// 2. 选择聊天模型候选（深度思考模式）
List<ModelTarget> deepChatCandidates = modelSelector.selectChatCandidates(true);

// 3. 选择 embedding 模型候选
List<ModelTarget> embeddingCandidates = modelSelector.selectEmbeddingCandidates();

// 4. 选择 rerank 模型候选
List<ModelTarget> rerankCandidates = modelSelector.selectRerankCandidates();

// 5. 遍历候选列表，按顺序尝试调用
for (ModelTarget target : chatCandidates) {
    String modelId = target.id();
    ModelCandidate candidate = target.candidate();
    ProviderConfig provider = target.provider();
    
    // 构建客户端并调用模型...
}


ProbeStreamBridge
 
流式首包探测桥接器。
在真正把内容转发给下游前，先短暂缓冲首批事件，用于判断当前模型是否“成功开始输出”。 路由层据此决定是认定本次流调用成功，还是切到下一个候选模型重试，避免首包前失败直接暴露给前端。
核心功能：
首包探测：等待第一个内容或思考片段到达，确认模型正常响应
事件缓冲：在首包确认前缓冲所有事件，避免下游看到半截输出
故障转移支持：如果首包超时或出错，路由层可以切换到备选模型
线程安全：使用 synchronized 保证缓冲和提交的原子性
工作流程：
创建 ProbeStreamBridge，包装下游回调
将桥接器传递给 ChatClient.streamChat()
当收到 onContent() 或 onThinking() 时，标记首包成功并缓冲事件
路由层调用 awaitFirstPacket() 等待首包结果
如果首包成功，调用 commit() 将缓冲事件按顺序转发给下游
如果首包失败/超时，路由层可以选择切换到备选模型
使用场景：
多模型路由：主模型无响应时自动切换到备选模型
用户体验优化：避免前端长时间等待后显示错误
容错处理：在网络不稳定或服务异常时提供降级方案
设计模式：
装饰器模式：包装下游 StreamCallback，添加首包探测功能
桥接模式：连接上游模型调用和下游业务回调
观察者模式：通过 CompletableFuture 通知等待者首包结果
注意事项：
该类是包级私有，仅供内部路由逻辑使用
必须在独立的线程中调用 streamChat()，避免阻塞主线程
awaitFirstPacket() 会阻塞当前线程，直到首包到达或超时
一旦 commit() 被调用，后续事件会直接转发给下游，不再缓冲
如果首包失败，缓冲的事件不会被转发，路由层应该切换到备选模型

AbstractOpenAIStyleChatClient

OpenAI 兼容协议聊天客户端抽象基类。
用于沉淀基于 OpenAI 风格 HTTP 协议的大模型调用公共逻辑，包括请求体构建、 鉴权头设置、同步响应解析、流式 SSE 读取以及异常封装。不同提供商只需覆写少量钩子方法 即可复用整体调用链路。
核心功能：
模板方法模式：定义同步和流式调用的标准流程，子类只需实现特定钩子方法
请求体构建：自动构建符合 OpenAI 协议的 JSON 请求体
鉴权处理：自动添加 Authorization 头（Bearer Token）
同步调用：支持阻塞式问答，返回完整响应内容
流式调用：支持 SSE 流式响应，实时推送思考内容和回答内容
异常封装：统一将 HTTP 错误、网络异常封装为 ModelClientException
Thinking 支持：支持解析 reasoning_content 字段（如 DeepSeek-R1）
设计模式：
模板方法模式：doChat() 和 doStreamChat() 定义算法骨架，子类可定制部分步骤
钩子方法：isReasoningEnabledForStream()、customizeRequestBody()、requiresApiKey()
策略模式：通过 StreamCallback 接口支持不同的流式处理策略
使用示例：
// 1. 实现具体提供商客户端
public class DeepSeekChatClient extends AbstractOpenAIStyleChatClient {
    public DeepSeekChatClient(OkHttpClient syncClient, OkHttpClient streamClient, Executor executor) {
        super(syncClient, streamClient, executor);
    }

    @Override
    public String provider() {
        return "deepseek";
    }

    @Override
    protected void customizeRequestBody(JsonObject body, ChatRequest request) {
        super.customizeRequestBody(body, request);
        // 添加 DeepSeek 特有参数
        if (request.getTemperature() != null) {
            body.addProperty("temperature", request.getTemperature());
        }
    }
}

// 2. 同步调用
ChatRequest request = ChatRequest.builder()
    .messages(List.of(
        ChatMessage.system("你是一个助手"),
        ChatMessage.user("你好")
    ))
    .build();
ModelTarget target = new ModelTarget("deepseek-chat", List.of("deepseek-chat"));
String response = client.chat(request, target);

// 3. 流式调用
client.streamChat(request, new StreamCallback() {
    @Override
    public void onThinking(String thinking) {
        System.out.print(thinking);  // 打印思考过程
    }

    @Override
    public void onContent(String content) {
        System.out.print(content);  // 打印回答内容
    }

    @Override
    public void onComplete() {
        System.out.println("\n完成");
    }

    @Override
    public void onError(Throwable error) {
        error.printStackTrace();
    }
}, target);
注意事项：
该抽象类不是线程安全的，但每个实例可以被多个线程共享使用
同步和流式调用使用不同的 OkHttpClient 实例，避免连接池冲突
流式调用在独立的线程池中执行，不会阻塞主线程
子类必须实现 provider() 方法返回提供商名称
如果提供商不需要 API Key，可以覆写 requiresApiKey() 返回 false