private final CustomerSupportAssistant agent;

public AssistantController(CustomerSupportAssistant agent) {
    this.agent = agent;
}

@RequestMapping(path = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> chat(@RequestParam(name = "chatId") String chatId,
                         @RequestParam(name = "userMessage") String userMessage) {
    return agent.chat(chatId, userMessage);
}

public Flux<String> chat(String chatId, String userMessageContent)

/**
 * 构造方法，注入聊天模型构建器、向量知识库和聊天记忆
 * @param modelBuilder 聊天模型构建器
 * @param vectorStore 向量知识库
 * @param chatMemory 聊天记忆
 */
public CustomerSupportAssistant(ChatClient.Builder modelBuilder, VectorStore vectorStore, ChatMemory chatMemory) {

    // 使用建造者模式配置 ChatClient
    this.chatClient = modelBuilder
            // 设置系统提示，定义AI角色、语气、业务范围和操作规范
            .defaultSystem("""
                        您是“Funnair”航空公司的客户聊天支持代理。请以友好、乐于助人且愉快的方式来回复。
                        您正在通过在线聊天系统与客户互动。
                        您能够支持已有机票的预订详情查询、机票日期改签、机票预订取消等操作，其余功能将在后续版本中添加，如果用户问的问题不支持请告知详情。
                          在提供有关机票预订详情查询、机票日期改签、机票预订取消等操作之前，您必须始终从用户处获取以下信息：预订号、客户姓名。
                          在询问用户之前，请检查消息历史记录以获取预订号、客户姓名等信息，尽量避免重复询问给用户造成困扰。
                          在更改预订之前，您必须确保条款允许这样做。
                          如果更改需要收费，您必须在继续之前征得用户同意。
                          使用提供的功能获取预订详细信息、更改预订和取消预订。
                          如果需要，您可以调用相应函数辅助完成。
                          请讲中文。
                          今天的日期是 {current_date}.
                    """)
            // 配置默认顾问（插件），包括聊天记忆、知识检索和日志
            .defaultAdvisors(
                    new PromptChatMemoryAdvisor(chatMemory), // 聊天记忆顾问，支持多轮对话
                    // new VectorStoreChatMemoryAdvisor(vectorStore)), // 可选：基于向量的聊天记忆

                    new QuestionAnswerAdvisor(vectorStore, SearchRequest.builder().topK(4).similarityThresholdAll().build()), // 知识检索顾问，RAG能力
                    // new QuestionAnswerAdvisor(vectorStore, SearchRequest.defaults()
                    //     .withFilterExpression("'documentType' == 'terms-of-service' && region in ['EU', 'US']")), // 可选：带过滤条件的知识检索

                    new SimpleLoggerAdvisor() // 日志顾问，记录对话日志
            )
            // 配置AI可调用的后端函数
            .defaultTools("getBookingDetails", "changeBooking", "cancelBooking")
            // 构建 ChatClient 实例
            .build();
}

/**
 * 聊天主方法，处理用户输入并返回AI回复（流式）
 * @param chatId 会话唯一标识
 * @param userMessageContent 用户消息内容
 * @return AI回复的响应式流
 */
public Flux<String> chat(String chatId, String userMessageContent) {

    // 创建对话上下文，注入当前日期、用户消息、会话ID等参数，流式返回AI回复
    return this.chatClient.prompt()
            .system(s -> s.param("current_date", LocalDate.now().toString())) // 注入当前日期参数
            .user(userMessageContent) // 前端请求参数，注入用户消息
            .advisors(
                    a -> a.param(CHAT_MEMORY_CONVERSATION_ID_KEY, chatId)
                            .param(CHAT_MEMORY_RETRIEVE_SIZE_KEY, 100)) // 绑定会话ID，检索最近100条对话
            .stream() // 以流式方式输出
            .content(); // 获取AI回复内容
}

@Override
public ChatClientRequestSpec prompt() {
    return new DefaultChatClientRequestSpec(this.defaultChatClientRequest);
}

public DefaultChatClientRequestSpec(ChatModel chatModel, @Nullable String userText,
                                    Map<String, Object> userParams, @Nullable String systemText, Map<String, Object> systemParams,
                                    List<ToolCallback> toolCallbacks, List<Message> messages, List<String> toolNames, List<Media> media,
                                    @Nullable ChatOptions chatOptions, List<Advisor> advisors, Map<String, Object> advisorParams,
                                    ObservationRegistry observationRegistry,
                                    @Nullable ChatClientObservationConvention observationConvention, Map<String, Object> toolContext,
                                    @Nullable TemplateRenderer templateRenderer) {
    // ...
    // 赋值 chatModel
    this.chatModel = chatModel;
    // 赋值 chatOptions，优先用传入的，否则用模型默认的
    this.chatOptions = chatOptions != null ? chatOptions.copy()
            : (chatModel.getDefaultOptions() != null) ? chatModel.getDefaultOptions().copy() : null;

    // 赋值用户消息文本
    this.userText = userText;
    // 复制用户参数
    this.userParams.putAll(userParams);
    // 赋值系统消息文本
    this.systemText = systemText;
    // 复制系统参数
    this.systemParams.putAll(systemParams);

    // 复制工具名称
    this.toolNames.addAll(toolNames);
    // 复制工具回调
    this.toolCallbacks.addAll(toolCallbacks);
    // 复制消息
    this.messages.addAll(messages);
    // 复制媒体资源
    this.media.addAll(media);
    // 复制顾问
    this.advisors.addAll(advisors);
    // 复制顾问参数
    this.advisorParams.putAll(advisorParams);
    // 赋值观测注册器
    this.observationRegistry = observationRegistry;
    // 赋值观测约定，优先用传入的，否则用默认
    this.observationConvention = observationConvention != null ? observationConvention
            : DEFAULT_CHAT_CLIENT_OBSERVATION_CONVENTION;
    // 复制工具上下文
    this.toolContext.putAll(toolContext);
    // 赋值模板渲染器，优先用传入的，否则用默认
    this.templateRenderer = templateRenderer != null ? templateRenderer : DEFAULT_TEMPLATE_RENDERER;
}

var systemSpec = new DefaultPromptSystemSpec();

this.systemText =StringUtils.

hasText(systemSpec.text())?systemSpec.

text() :this.systemText;

this.systemParams.putAll(systemSpec.params());

var advisorSpec = new DefaultAdvisorSpec();

this.advisorParams.putAll(advisorSpec.getParams());

this.advisors.addAll(advisorSpec.getAdvisors());

public StreamResponseSpec stream() {
    // 构建顾问链（Advisor Chain），包含所有需要在流式请求中依次执行的顾问逻辑（如记忆、检索、日志等），
    // 并在链尾自动加入 ChatModelCallAdvisor 和 ChatModelStreamAdvisor，确保最终能调用底层大模型。
    BaseAdvisorChain advisorChain = buildAdvisorChain();

    // 将当前请求规范（DefaultChatClientRequestSpec）转换为 AdvisedRequest，
    // 再用模板渲染器（templateRenderer）生成标准的 ChatClientRequest，
    // 并结合顾问链、观测注册表和观测约定，创建并返回一个流式响应规范（DefaultStreamResponseSpec）。
    // 这个对象负责后续的流式响应处理（如 SSE、WebSocket）。
    return new DefaultStreamResponseSpec(
            toAdvisedRequest(this).toChatClientRequest(this.templateRenderer),
            advisorChain,
            observationRegistry,
            observationConvention
    );
}

/**
 * 构建对话请求处理的顾问链（Advisor Chain）。
 * 该链条会依次应用所有自定义和系统内置的顾问，确保请求最终能被正确处理并发送到底层大模型。
 *
 * @return BaseAdvisorChain 顾问链对象，用于后续对话请求的处理流程。
 */
private BaseAdvisorChain buildAdvisorChain() {
    // 在顾问列表末尾添加 ChatModelCallAdvisor，负责同步调用底层大模型，生成完整回复。
    this.advisors.add(ChatModelCallAdvisor.builder().chatModel(this.chatModel).build());
    // 在顾问列表末尾添加 ChatModelStreamAdvisor，负责流式调用底层大模型，实现边生成边推送。
    this.advisors.add(ChatModelStreamAdvisor.builder().chatModel(this.chatModel).build());

    // 使用 DefaultAroundAdvisorChain 构建顾问链，将所有顾问按顺序压入链中，并设置模板渲染器。
    return DefaultAroundAdvisorChain.builder(this.observationRegistry)
            .pushAll(this.advisors)           // 压入所有顾问（自定义+系统自动添加）
            .templateRenderer(this.templateRenderer) // 设置模板渲染器
            .build();                         // 构建并返回顾问链对象
}

/**
 * DefaultAroundAdvisorChain 构造方法
 *
 * 该构造方法负责初始化一个完整的顾问链，提供 AI 交互过程中的拦截处理能力。
 * 顾问链采用责任链模式，支持同步和流式两种交互模式的拦截器队列管理。
 *
 * @param observationRegistry 观测注册表，提供全链路监控和指标收集能力
 * @param templateRenderer 模板渲染器，负责处理模板内容，支持为空（会使用默认实现）
 * @param callAroundAdvisors 同步调用顾问队列，按优先级处理同步请求
 * @param streamAroundAdvisors 流式调用顾问队列，按优先级处理流式请求
 */
DefaultAroundAdvisorChain(ObservationRegistry observationRegistry, @Nullable TemplateRenderer templateRenderer,
                          Deque<CallAroundAdvisor> callAroundAdvisors, Deque<StreamAroundAdvisor> streamAroundAdvisors) {
    //...
    // 成员变量初始化部分：设置实例属性
    // 设置观测注册表，用于后续的链路监控和性能指标收集
    this.observationRegistry = observationRegistry;
    // 设置模板渲染器，如果传入为空则使用默认的 StTemplateRenderer 实现
    // 这种设计既提供了灵活性（允许自定义），又确保了系统的健壮性（总有可用实现）
    this.templateRenderer = templateRenderer != null ? templateRenderer : DEFAULT_TEMPLATE_RENDERER;
    // 设置同步顾问队列，用于处理同步请求的拦截和处理逻辑
    this.callAroundAdvisors = callAroundAdvisors;
    // 设置流式顾问队列，用于处理流式请求的拦截和处理逻辑
    this.streamAroundAdvisors = streamAroundAdvisors;
    // 创建同步顾问队列的不可变快照，用于后续查询和调试
    // 使用 List.copyOf 确保返回的是不可变集合，防止外部修改内部状态
    this.originalCallAdvisors = List.copyOf(callAroundAdvisors);
    // 创建流式顾问队列的不可变快照，同样用于后续查询和调试
    // 这种设计保留了原始配置，即使工作队列在处理中被修改，原始状态仍可访问
    this.originalStreamAdvisors = List.copyOf(streamAroundAdvisors);
}

@Override
public Flux<String> content() {
   // @formatter:off
   return doGetObservableFluxChatResponse(this.request)
     // 从 ChatClientResponse 中提取 ChatResponse 对象，忽略可能的 null 值
     // 这确保了流中只包含有效的响应对象，增强了处理链的稳定性
     .mapNotNull(ChatClientResponse::chatResponse)
     // 将每个 ChatResponse 对象映射为其中包含的文本内容
     // 使用链式路径验证确保安全地处理可能的空值情况
     .map(r -> {
      // 检查响应结构完整性，返回空字符串代替 null，避免流中断
      if (r.getResult() == null || r.getResult().getOutput() == null
        || r.getResult().getOutput().getText() == null) {
       return "";
      }
      // 从完整响应中提取纯文本内容，这是大语言模型生成的实际文本部分
      return r.getResult().getOutput().getText();
     })
     // 过滤掉空字符串，只保留有实际内容的文本片段
     // 使用 SpringFramework 的工具类确保统一的空值检查行为
     .filter(StringUtils::hasLength);
   // @formatter:on
}

private Flux<ChatClientResponse> doGetObservableFluxChatResponse(ChatClientRequest chatClientRequest) {
   // 使用deferContextual创建响应式流，它允许访问上游的Reactor上下文，实现跨组件的数据传递
   // 这种延迟创建方式确保了流的懒加载特性，只有订阅时才会执行实际操作
   return Flux.deferContextual(contextView -> {

    // 创建观测上下文，包含请求信息、流式顾问列表和流式标志
    // 这个上下文对象将被传递给观测工具，用于记录和监控整个流程
    ChatClientObservationContext observationContext = ChatClientObservationContext.builder()
     .request(chatClientRequest)
     .advisors(advisorChain.getStreamAdvisors())
     .stream(true)
     .build();

    // 创建观测实例，使用配置的或默认的观测约定
    // 观测实例将记录流式请求的性能指标、执行状态等信息
    Observation observation = ChatClientObservationDocumentation.AI_CHAT_CLIENT.observation(
      observationConvention, DEFAULT_CHAT_CLIENT_OBSERVATION_CONVENTION, () -> observationContext,
      observationRegistry);

    // 设置父观测实例并启动当前观测
    // 如果上下文中存在父观测，则建立关联，形成观测树，支持分布式追踪
    observation.parentObservation(contextView.getOrDefault(ObservationThreadLocalAccessor.KEY, null))
     .start();

    // @formatter:off
    // 应用顾问链，处理流式请求
    // 通过advisorChain.nextStream方法启动整个责任链模式的处理过程
    // 顾问链最终会以ChatModelStreamAdvisor结束，它负责调用实际的AI模型
    return advisorChain.nextStream(chatClientRequest)
      // 注册错误处理器，将错误传播到观测系统
      // 确保任何异常都被正确记录，便于问题诊断
      .doOnError(observation::error)
      // 注册完成处理器，无论流以何种方式终止都会停止观测
      // 这确保了资源的正确释放和指标的完整性
      .doFinally(s -> observation.stop())
      // 将当前观测写入上下文，使下游操作可以访问
      // 这种上下文传播机制是实现全链路追踪的关键
      .contextWrite(ctx -> ctx.put(ObservationThreadLocalAccessor.KEY, observation));
    // @formatter:on
   });
  }

public static <T> Flux<T> deferContextual(
    Function<ContextView, ? extends Publisher<T>> contextualPublisherFactory)

// 普通 defer 无法访问上下文
Flux.defer(() -> Flux.just("hello"));

// deferContextual 可以访问上下文
Flux.deferContextual(ctx -> {
    String user = ctx.get("user");
    return Flux.just("欢迎, " + user);
});

Flux<String> dataStream = Flux.deferContextual(ctx -> {
    String role = ctx.getOrDefault("role", "guest");

    if ("admin".equals(role)) {
        return Flux.just("敏感数据1", "敏感数据2", "敏感数据3");
    } else {
        return Flux.just("普通数据A", "普通数据B");
    }
})
.contextWrite(Context.of("role", "admin"));  // 设置上下文

dataStream.subscribe(System.out::println);
// 输出: 敏感数据1, 敏感数据2, 敏感数据3

Flux<String> messages = Flux.deferContextual(ctx -> {
    String language = ctx.getOrDefault("language", "zh_CN");

    Map<String, List<String>> translations = Map.of(
        "en_US", List.of("Hello", "Welcome"),
        "zh_CN", List.of("你好", "欢迎"),
        "ja_JP", List.of("こんにちは", "ようこそ")
    );

    return Flux.fromIterable(translations.getOrDefault(language, translations.get("zh_CN")));
});

// 使用日语上下文订阅
messages.contextWrite(Context.of("language", "ja_JP"))
        .subscribe(System.out::println);
// 输出: こんにちは, ようこそ