feat: add unified WebSocket connection manager and routing

- Implemented UnifiedWebSocketManager for managing WebSocket connections, including subscription handling and message sending.
- Created unified WebSocket router to handle client messages, including authentication, subscription, and chat session management.
- Added support for logging and plugin progress subscriptions.
- Enhanced error handling and response structure for WebSocket operations.

src/webui/routers/plugin/progress.py

@@ -1,12 +1,15 @@
+"""插件进度实时推送支持。"""
+
+from typing import Any, Dict, Optional, Set
 import asyncio
 import json
-from typing import Any, Dict, Optional, Set
 
 from fastapi import APIRouter, Query, WebSocket, WebSocketDisconnect
 
 from src.common.logger import get_logger
 from src.webui.core import get_token_manager
 from src.webui.routers.websocket.auth import verify_ws_token
+from src.webui.routers.websocket.manager import websocket_manager
 
 logger = get_logger("webui.plugin_progress")
 
@@ -25,25 +28,29 @@ current_progress: Dict[str, Any] = {
 }
 
 
+def get_current_progress() -> Dict[str, Any]:
+    """获取当前插件进度快照。
+
+    Returns:
+        Dict[str, Any]: 当前插件进度数据副本。
+    """
+    return current_progress.copy()
+
+
 async def broadcast_progress(progress_data: Dict[str, Any]) -> None:
+    """向统一连接层广播插件进度更新。
+
+    Args:
+        progress_data: 插件进度数据。
+    """
     global current_progress
     current_progress = progress_data.copy()
-
-    if not active_connections:
-        return
-
-    message = json.dumps(progress_data, ensure_ascii=False)
-    disconnected: Set[WebSocket] = set()
-
-    for websocket in active_connections:
-        try:
-            await websocket.send_text(message)
-        except Exception as e:
-            logger.error(f"发送进度更新失败: {e}")
-            disconnected.add(websocket)
-
-    for websocket in disconnected:
-        active_connections.discard(websocket)
+    await websocket_manager.broadcast_to_topic(
+        domain="plugin_progress",
+        topic="main",
+        event="update",
+        data={"progress": progress_data},
+    )
 
 
 async def update_progress(
@@ -56,6 +63,18 @@ async def update_progress(
     total_plugins: int = 0,
     loaded_plugins: int = 0,
 ) -> None:
+    """更新当前插件进度并广播。
+
+    Args:
+        stage: 当前阶段。
+        progress: 当前进度百分比。
+        message: 进度说明消息。
+        operation: 当前操作类型。
+        error: 可选的错误信息。
+        plugin_id: 当前处理的插件 ID。
+        total_plugins: 总插件数量。
+        loaded_plugins: 已处理插件数量。
+    """
     progress_data = {
         "operation": operation,
         "stage": stage,
@@ -74,6 +93,12 @@ async def update_progress(
 
 @router.websocket("/ws/plugin-progress")
 async def websocket_plugin_progress(websocket: WebSocket, token: Optional[str] = Query(None)) -> None:
+    """旧版插件进度 WebSocket 入口。
+
+    Args:
+        websocket: FastAPI WebSocket 对象。
+        token: 可选的一次性握手 Token。
+    """
     is_authenticated = False
 
     if token and verify_ws_token(token):
@@ -105,17 +130,22 @@ async def websocket_plugin_progress(websocket: WebSocket, token: Optional[str] =
                 data = await websocket.receive_text()
                 if data == "ping":
                     await websocket.send_text("pong")
-            except Exception as e:
-                logger.error(f"处理客户端消息时出错: {e}")
+            except Exception as exc:
+                logger.error(f"处理客户端消息时出错: {exc}")
                 break
 
     except WebSocketDisconnect:
         active_connections.discard(websocket)
         logger.info(f"📡 插件进度 WebSocket 客户端已断开，当前连接数: {len(active_connections)}")
-    except Exception as e:
-        logger.error(f"❌ WebSocket 错误: {e}")
+    except Exception as exc:
+        logger.error(f"❌ WebSocket 错误: {exc}")
         active_connections.discard(websocket)
 
 
 def get_progress_router() -> APIRouter:
+    """获取旧版插件进度路由对象。
+
+    Returns:
+        APIRouter: 插件进度路由对象。
+    """
     return router