feat(voice): 新增基于 WebSocket 连接池的流式 TTS 消息播放

bootstrap/src/main/resources/application.yaml

@@ -114,6 +114,19 @@ rag:
       lease-seconds: 30
       poll-interval-ms: 200
 
+  voice:
+    executors:
+      websocket-lifecycle:
+        core-pool-size: 2
+        max-pool-size: 32
+        keep-alive-seconds: 60
+        thread-name-prefix: websocket_lifecycle_executor_
+      playback:
+        core-pool-size: 2
+        max-pool-size: 8
+        keep-alive-seconds: 60
+        thread-name-prefix: voice_playback_executor_
+
   memory:
     history-keep-turns: 8
     summary-enabled: true
@@ -199,9 +212,11 @@ ai:
     bailian:
       url: https://dashscope.aliyuncs.com
       api-key: ${BAILIAN_API_KEY:}
+      workspace: ${BAILIAN_WORKSPACE:}
       endpoints:
         chat: /compatible-mode/v1/chat/completions
         rerank: /api/v1/services/rerank/text-rerank/text-rerank
+        tts: /api-ws/v1/inference
     aihubmix:
       url: https://aihubmix.com
       api-key: ${AIHUBMIX_API_KEY:}
@@ -297,6 +312,25 @@ ai:
         provider: bailian
         model: qwen-vl-max
 
+  tts:
+    default-model: cosyvoice-v3-flash
+    timeout-ms: 3000
+    candidates:
+      - id: cosyvoice-v3-flash
+        provider: bailian
+        model: cosyvoice-v3-flash
+        priority: 1
+        voice: longxiaochun_v3
+
+  websocket:
+    connect-timeout-ms: 10000
+    task-start-timeout-ms: 10000
+    task-packet-idle-timeout-ms: 10000
+    max-total-per-model: 8
+    max-idle-per-model: 8
+    idle-timeout-ms: 25000
+    eviction-interval-ms: 30000
+
 # MinerU SaaS API 配置（PDF / Word / PPT 走 MinerU 解析）
 mineru:
   api-url: https://mineru.net/api/v4

bootstrap/src/test/java/com/nageoffer/ai/ragent/rag/service/handler/VoicePlaybackEventHandlerTest.java

@@ -0,0 +1,97 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.nageoffer.ai.ragent.rag.service.handler;
+
+import com.nageoffer.ai.ragent.framework.web.StreamTaskManager;
+import com.nageoffer.ai.ragent.infra.chat.StreamCancellationHandle;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+
+class VoicePlaybackEventHandlerTest {
+
+    private static final String TASK_ID = "task-1";
+
+    @Test
+    void sendsAudioAndCompletesThroughSse() throws Exception {
+        SseEmitter emitter = mock(SseEmitter.class);
+        StreamTaskManager taskManager = mock(StreamTaskManager.class);
+        VoicePlaybackEventHandler handler = new VoicePlaybackEventHandler(emitter, TASK_ID, taskManager);
+
+        handler.onAudio(new byte[]{1, 2});
+        handler.onComplete();
+
+        verify(taskManager).register(any(String.class), any(Runnable.class));
+        verify(emitter, times(3)).send(any(SseEmitter.SseEventBuilder.class));
+        verify(taskManager).unregister(TASK_ID);
+        verify(emitter).complete();
+    }
+
+    @Test
+    void reportsOnlyFirstError() {
+        SseEmitter emitter = mock(SseEmitter.class);
+        StreamTaskManager taskManager = mock(StreamTaskManager.class);
+        VoicePlaybackEventHandler handler = new VoicePlaybackEventHandler(emitter, TASK_ID, taskManager);
+        RuntimeException failure = new RuntimeException("failed");
+
+        handler.onError(failure);
+        handler.onError(new RuntimeException("duplicate"));
+
+        verify(taskManager).unregister(TASK_ID);
+        verify(emitter).completeWithError(failure);
+    }
+
+    @Test
+    void cancelsTaskWhenEmitterCompletes() {
+        SseEmitter emitter = mock(SseEmitter.class);
+        StreamTaskManager taskManager = mock(StreamTaskManager.class);
+        new VoicePlaybackEventHandler(emitter, TASK_ID, taskManager);
+        ArgumentCaptor<Runnable> callbacks = ArgumentCaptor.forClass(Runnable.class);
+        verify(emitter, times(2)).onCompletion(callbacks.capture());
+
+        List<Runnable> completionCallbacks = callbacks.getAllValues();
+        completionCallbacks.get(1).run();
+
+        verify(taskManager).cancel(TASK_ID);
+        verify(taskManager, never()).unregister(TASK_ID);
+    }
+
+    @Test
+    void bindsProviderCancellationHandleToTask() {
+        SseEmitter emitter = mock(SseEmitter.class);
+        StreamTaskManager taskManager = mock(StreamTaskManager.class);
+        StreamCancellationHandle providerHandle = mock(StreamCancellationHandle.class);
+        VoicePlaybackEventHandler handler = new VoicePlaybackEventHandler(emitter, TASK_ID, taskManager);
+        ArgumentCaptor<Runnable> handle = ArgumentCaptor.forClass(Runnable.class);
+
+        handler.onTaskStarted(providerHandle);
+        verify(taskManager).bindHandle(eq(TASK_ID), handle.capture());
+        handle.getValue().run();
+
+        verify(providerHandle).cancel();
+    }
+}

bootstrap/src/test/java/com/nageoffer/ai/ragent/rag/service/handler/VoicePlaybackTaskRunnerTest.java

@@ -0,0 +1,86 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.nageoffer.ai.ragent.rag.service.handler;
+
+import com.nageoffer.ai.ragent.infra.voice.tts.TtsService;
+import org.junit.jupiter.api.Test;
+
+import java.util.concurrent.Executor;
+import java.util.concurrent.RejectedExecutionException;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+class VoicePlaybackTaskRunnerTest {
+
+    private static final String TEXT = "你好";
+
+    @Test
+    void startsTtsThroughPlaybackExecutor() {
+        TtsService ttsService = mock(TtsService.class);
+        VoicePlaybackEventHandler callback = mock(VoicePlaybackEventHandler.class);
+        VoicePlaybackTaskRunner runner = new VoicePlaybackTaskRunner(ttsService, Runnable::run);
+
+        runner.run(TEXT, callback);
+
+        verify(ttsService).synthesize(TEXT, callback, callback);
+    }
+
+    @Test
+    void skipsTtsWhenTaskWasCancelled() {
+        TtsService ttsService = mock(TtsService.class);
+        VoicePlaybackEventHandler callback = mock(VoicePlaybackEventHandler.class);
+        when(callback.isCancelled()).thenReturn(true);
+        VoicePlaybackTaskRunner runner = new VoicePlaybackTaskRunner(ttsService, Runnable::run);
+
+        runner.run(TEXT, callback);
+
+        verify(ttsService, never()).synthesize(TEXT, callback, callback);
+    }
+
+    @Test
+    void delegatesStartFailureToCallback() {
+        TtsService ttsService = mock(TtsService.class);
+        VoicePlaybackEventHandler callback = mock(VoicePlaybackEventHandler.class);
+        RuntimeException failure = new RuntimeException("failed");
+        doThrow(failure).when(ttsService).synthesize(TEXT, callback, callback);
+        VoicePlaybackTaskRunner runner = new VoicePlaybackTaskRunner(ttsService, Runnable::run);
+
+        runner.run(TEXT, callback);
+
+        verify(callback).onStartFailure(failure);
+    }
+
+    @Test
+    void delegatesExecutorRejectionToCallback() {
+        TtsService ttsService = mock(TtsService.class);
+        VoicePlaybackEventHandler callback = mock(VoicePlaybackEventHandler.class);
+        Executor rejectingExecutor = command -> {
+            throw new RejectedExecutionException("busy");
+        };
+        VoicePlaybackTaskRunner runner = new VoicePlaybackTaskRunner(ttsService, rejectingExecutor);
+
+        runner.run(TEXT, callback);
+
+        verify(callback).onRejected(any(RejectedExecutionException.class));
+    }
+}

frontend/src/components/chat/FeedbackButtons.tsx

@@ -4,6 +4,7 @@ import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
 import { ThumbDownFilledIcon, ThumbUpFilledIcon } from "@/components/chat/ThumbIcons";
+import { VoicePlayButton } from "@/components/chat/VoicePlayButton";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -19,6 +20,8 @@ interface FeedbackButtonsProps {
   messageId: string;
   feedback: FeedbackValue;
   content: string;
+  playing?: boolean;
+  onTogglePlay?: () => void;
   className?: string;
   alwaysVisible?: boolean;
 }
@@ -31,6 +34,8 @@ export function FeedbackButtons({
   messageId,
   feedback,
   content,
+  playing,
+  onTogglePlay,
   className,
   alwaysVisible
 }: FeedbackButtonsProps) {
@@ -171,6 +176,7 @@ export function FeedbackButtons({
           </DropdownMenuContent>
         </DropdownMenu>
       </div>
+      {onTogglePlay ? <VoicePlayButton playing={Boolean(playing)} onToggle={onTogglePlay} /> : null}
       <Button
         variant="ghost"
         size="icon"

frontend/src/components/chat/MessageItem.tsx

@@ -3,6 +3,7 @@ import { Brain, ChevronDown } from "lucide-react";
 
 import { FeedbackButtons } from "@/components/chat/FeedbackButtons";
 import { MarkdownRenderer } from "@/components/chat/MarkdownRenderer";
+import { useVoicePlayback } from "@/hooks/useVoicePlayback";
 import { RecommendedQuestions } from "@/components/chat/RecommendedQuestions";
 import { RecommendedQuestionsButton } from "@/components/chat/RecommendedQuestionsButton";
 import { SourcesButton } from "@/components/chat/SourcesButton";
@@ -33,6 +34,7 @@ export const MessageItem = React.memo(function MessageItem({ message }: MessageI
     Boolean(message.id) &&
     (message.messageStatus ?? "NORMAL") === "NORMAL" &&
     !message.id.startsWith("assistant-");
+  const { playingId, togglePlay } = useVoicePlayback();
   const [thinkingExpanded, setThinkingExpanded] = React.useState(false);
   const hasThinking = Boolean(message.thinking && message.thinking.trim().length > 0);
   const hasContent = message.content.trim().length > 0;
@@ -116,6 +118,8 @@ export const MessageItem = React.memo(function MessageItem({ message }: MessageI
                   messageId={message.id}
                   feedback={message.feedback ?? null}
                   content={message.content}
+                  playing={playingId === message.id}
+                  onTogglePlay={() => togglePlay(message.id)}
                   alwaysVisible
                 />
               ) : null}

frontend/src/components/chat/VoicePlayButton.tsx

@@ -0,0 +1,31 @@
+import * as React from "react";
+import { Volume2 } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+interface VoicePlayButtonProps {
+  playing: boolean;
+  onToggle: () => void;
+}
+
+/**
+ * 消息语音播放按钮 播放中高亮 点击停止
+ */
+export function VoicePlayButton({ playing, onToggle }: VoicePlayButtonProps) {
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      type="button"
+      onClick={onToggle}
+      aria-label={playing ? "停止播放" : "播放语音"}
+      className={cn(
+        "h-7 w-7 rounded-md hover:bg-[#F5F5F5]",
+        playing ? "text-[#1A1A1A]" : "text-[#999999] hover:text-[#666666]"
+      )}
+    >
+      <Volume2 className="h-4 w-4" />
+    </Button>
+  );
+}