@agentunion/kite 1.5.0 → 1.6.1

package/extensions/services/dataclaw/server.py

@@ -0,0 +1,759 @@
+"""
+DataClaw V2.0 主服务器
+"""
+import asyncio
+import json
+import os
+import time
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+
+import uvicorn
+import websockets
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+_THIS_DIR = Path(__file__).parent
+
+# 预导入所有 API routers（避免在 uvicorn 启动时导入）
+import sys
+sys.path.insert(0, str(_THIS_DIR))
+
+_api_routers = {}
+
+try:
+    from api.identity import router as identity_router
+    _api_routers['identity'] = identity_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: identity router not loaded: {e}")
+
+try:
+    from api.feeds import router as feeds_router
+    _api_routers['feeds'] = feeds_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: feeds router not loaded: {e}")
+
+try:
+    from api.data import router as data_router
+    _api_routers['data'] = data_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: data router not loaded: {e}")
+
+try:
+    from api.subscriptions import router as subs_router
+    _api_routers['subscriptions'] = subs_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: subscriptions router not loaded: {e}")
+
+try:
+    from api.search import router as search_router
+    _api_routers['search'] = search_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: search router not loaded: {e}")
+
+try:
+    from api.demands import router as demands_router
+    _api_routers['demands'] = demands_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: demands router not loaded: {e}")
+
+try:
+    from api.credits import router as credits_router
+    _api_routers['credits'] = credits_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: credits router not loaded: {e}")
+
+try:
+    from api.reviews import router as reviews_router
+    _api_routers['reviews'] = reviews_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: reviews router not loaded: {e}")
+
+try:
+    from api.notifications import router as notif_router
+    _api_routers['notifications'] = notif_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: notifications router not loaded: {e}")
+
+try:
+    from api.copyright import router as copyright_router
+    _api_routers['copyright'] = copyright_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: copyright router not loaded: {e}")
+
+try:
+    from api.admin import router as admin_router
+    _api_routers['admin'] = admin_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: admin router not loaded: {e}")
+
+try:
+    from ws.handler import router as ws_router
+    _api_routers['ws'] = ws_router
+except ImportError as e:
+    print(f"[dataclaw] WARNING: ws router not loaded: {e}")
+
+class DataClawServer:
+    def __init__(self, token: str, kernel_port: int, advertise_ip: str, port: int, data_dir: str = "", max_connections: int = 1,
+                 gateway_url: str = "", kite_token: str = "", module_config: dict = None):
+        self.token = token
+        self.kernel_port = kernel_port
+        self.advertise_ip = advertise_ip
+        self.port = port
+        self.data_dir = data_dir
+        self.max_connections = max_connections
+        self.module_config = module_config or {}
+        self.gateway_url = gateway_url
+        self.kite_token = kite_token
+        self._ws: Optional[websockets.WebSocketClientProtocol] = None
+        self._ws_task: Optional[asyncio.Task] = None
+        self._pending_rpc: dict = {}
+        self._shutdown = False
+        self._exit_code = 0
+        self._auth_failed = False
+        self._uv_server = None  # 由 entry.py 设置，用于优雅退出
+        self._config = {}
+        self._t0 = time.monotonic()
+        self._extra_ws: dict = {}           # slot → WebSocket
+        self._extra_ws_tasks: dict = {}     # slot → recv loop Task
+        self._has_registered = False
+
+    def build_app(self) -> FastAPI:
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            # 启动时
+            await self._startup()
+            yield
+            # 关闭时
+            await self._shutdown_cleanup()
+
+        app = FastAPI(
+            title="DataClaw API",
+            version="2.0.0",
+            description="Agent 数据共享平台 — 一次采集，万次复用",
+            lifespan=lifespan,
+            docs_url="/docs",
+            redoc_url="/redoc",
+            openapi_url="/v1/openapi.json",
+        )
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        self._register_routes(app)
+        return app
+
+    async def _startup(self):
+        """初始化：加载配置、连接数据库、启动 WS 连接 Kernel"""
+        from core.config import init_config
+        from core.database import init_db
+        from core.auth import configure_jwt
+
+        # 1. 加载配置（通过 module_config 的 business_config）
+        self._config = init_config(self.module_config)
+
+        # 2. 初始化数据库
+        db_cfg = self._config.get("database", {})
+        init_db(db_cfg)
+
+        # 3. 配置 JWT
+        jwt_cfg = self._config.get("jwt", {})
+        configure_jwt(
+            secret=jwt_cfg.get("secret_key", "dataclaw-secret"),
+            algorithm=jwt_cfg.get("algorithm", "HS256"),
+            expire_hours=jwt_cfg.get("access_token_expire_hours", 24),
+        )
+
+        # 4. 连接 Kernel WebSocket（如果有 kernel_port）
+        if self.kernel_port:
+            self._ws_task = asyncio.create_task(self._ws_loop())
+
+        elapsed = int((time.monotonic() - self._t0) * 1000)
+        print(f"[dataclaw] startup complete in {elapsed}ms")
+
+    async def _shutdown_cleanup(self):
+        self._shutdown = True
+        if self._ws_task:
+            self._ws_task.cancel()
+        # 关闭所有附加连接
+        for _s, _w in list(self._extra_ws.items()):
+            try:
+                await _w.close(code=1000, reason="shutdown")
+            except Exception:
+                pass
+        for _t in self._extra_ws_tasks.values():
+            _t.cancel()
+        self._extra_ws.clear()
+        self._extra_ws_tasks.clear()
+        from core.database import close_db
+        await close_db()
+        print("[dataclaw] shutdown complete")
+
+    async def _ws_loop(self):
+        """维持与 Kernel 的 WebSocket 长连接"""
+        ws_url = f"ws://127.0.0.1:{self.kernel_port}/ws?id=dataclaw"
+        backoff = 1.0
+        conn_refused_count = 0
+        while not self._shutdown:
+            try:
+                async with websockets.connect(
+                    ws_url,
+                    ping_interval=30,
+                    ping_timeout=10,
+                    close_timeout=5,
+                ) as ws:
+                    self._ws = ws
+                    backoff = 1.0
+                    conn_refused_count = 0
+                    print(f"[dataclaw] connected to kernel at port {self.kernel_port}")
+
+                    # 启动 receiver task，确保连接阶段的 RPC 响应也能被处理
+                    recv_task = asyncio.create_task(self._receiver_loop(ws))
+
+                    try:
+                        # 认证
+                        auth_resp = await self._rpc_call(ws, "auth", {"token": self.token}, timeout=5.0)
+                        if "error" in auth_resp:
+                            print(f"[dataclaw] auth failed: {auth_resp['error']}")
+                            self._auth_failed = True
+                            self._exit_code = 1
+                            break
+
+                        # subscribe/register/module.ready 由 _do_init 在收到 system.require_init 后执行
+
+                        # 等待 receiver task 结束（连接断开时自然退出）
+                        await recv_task
+                    finally:
+                        recv_task.cancel()
+                        # 断连清理：取消所有 pending RPC futures
+                        for _rid, _fut in self._pending_rpc.items():
+                            if not _fut.done():
+                                _fut.cancel()
+                        self._pending_rpc.clear()
+
+            except asyncio.CancelledError:
+                break
+            except (ConnectionRefusedError, ConnectionResetError, OSError) as e:
+                # Windows 的 [WinError 1225] 是 OSError 不是 ConnectionRefusedError
+                if isinstance(e, OSError) and getattr(e, 'winerror', None) != 1225 and not isinstance(e, (ConnectionRefusedError, ConnectionResetError)):
+                    raise
+                if self._shutdown:
+                    break
+                conn_refused_count += 1
+                if conn_refused_count >= 3:
+                    print(f"[dataclaw] Kernel 持续不可达 ({conn_refused_count} 次)，正常退出")
+                    self._shutdown = True
+                    break
+                print(f"[dataclaw] Kernel 连接失败，{backoff:.0f}s 后重试 ({conn_refused_count}/3)")
+                self._ws = None
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 30)
+            except Exception as e:
+                if self._shutdown:
+                    break
+                conn_refused_count += 1
+                if conn_refused_count >= 10:
+                    print(f"[dataclaw] 连续 {conn_refused_count} 次连接失败，正常退出")
+                    self._shutdown = True
+                    break
+                print(f"[dataclaw] ws disconnected: {e}, retry in {backoff:.0f}s")
+                self._ws = None
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 30)
+
+        # ws_loop 退出后，通知 uvicorn 退出
+        if self._uv_server:
+            self._uv_server.should_exit = True
+
+    async def _receiver_loop(self, ws):
+        """WebSocket 接收循环：分发所有消息到 _handle_ws_msg。"""
+        async for raw in ws:
+            # 检测 system.require_init 事件，触发注册流程
+            try:
+                msg = json.loads(raw)
+                if "method" in msg and "id" not in msg:
+                    params = msg.get("params", {})
+                    event = params.get("event", "")
+                    if event == "system.require_init":
+                        asyncio.create_task(self._do_init(ws))
+                        continue
+            except Exception:
+                pass
+            asyncio.create_task(self._handle_ws_msg(ws, raw))
+
+    async def _do_init(self, ws):
+        """收到 system.require_init 后执行：订阅 + 注册 + module.ready"""
+        try:
+            reason = "startup" if not self._has_registered else "recovery"
+
+            # 注册
+            await self._rpc_call(ws, "registry.register", {
+                "module_id": "dataclaw",
+                "module_type": "service",
+                "launcher_id": "launcher",
+                "base_url": f"http://127.0.0.1:{self.port}",
+                "health_path": "/health",
+                "display": {
+                    "urls": {
+                        "DataClaw 数据共享平台": f"http://127.0.0.1:{self.port}"
+                    }
+                },
+                "events_publish": {
+                    "feed": {
+                        "created": {"description": "新 Feed 注册"},
+                        "data_published": {"description": "Feed 数据更新"},
+                    },
+                    "demand": {
+                        "fulfilled": {"description": "需求被满足"},
+                    },
+                },
+                "events_subscribe": ["module.exiting", "module.shutdown"],
+            }, wait_response=False)
+
+            # 订阅事件
+            await self._rpc_call(ws, "event.subscribe", {
+                "events": ["module.ready", "module.shutdown"],
+            })
+
+            # 发布 module.ready
+            await self._publish_event(ws, "module.ready", {
+                "module_id": "dataclaw",
+                "port": self.port,
+                "startup_time": round(time.monotonic() - self._t0, 3),
+                "graceful_shutdown": True,
+                "reason": reason,
+            })
+            print(f"[dataclaw] module.ready published (reason={reason})")
+            self._has_registered = True
+
+            # module.ready 之后异步检查数据库连通性（不阻塞启动）
+            asyncio.create_task(self._check_db_connectivity())
+        except Exception as e:
+            print(f"[dataclaw] _do_init failed: {e}")
+            self._has_registered = False
+
+    async def _check_db_connectivity(self):
+        """module.ready 后异步检查数据库连通性，失败时红色报错"""
+        from core.database import check_connection
+        db_ok, db_err = await check_connection()
+        if not db_ok:
+            db_cfg = self._config.get("database", {})
+            print(f"\033[31m[dataclaw] ✖ 数据库连接失败: {db_err}\033[0m")
+            print(f"\033[31m[dataclaw]   配置: {db_cfg.get('host', '?')}:{db_cfg.get('port', '?')}/{db_cfg.get('database', '?')}\033[0m")
+        else:
+            print(f"[dataclaw] ✓ 数据库连接正常")
+
+    async def _rpc_call(self, ws, method: str, params: dict = None,
+                        wait_response: bool = True, timeout: float = 3.0) -> dict:
+        """JSON-RPC 2.0 request。默认等待响应。"""
+        rpc_id = str(uuid.uuid4())
+        msg = {"jsonrpc": "2.0", "id": rpc_id, "method": method}
+        if params:
+            msg["params"] = params
+        if not wait_response:
+            await ws.send(json.dumps(msg))
+            return {}
+        future = asyncio.get_event_loop().create_future()
+        self._pending_rpc[rpc_id] = future
+        await ws.send(json.dumps(msg))
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self._pending_rpc.pop(rpc_id, None)
+            return {"error": {"code": -32000, "message": f"RPC timeout: {method} ({timeout}s)"}}
+
+    def _handle_rpc_response(self, msg: dict):
+        """处理 RPC 响应，匹配 pending future。"""
+        rpc_id = msg.get("id")
+        future = self._pending_rpc.pop(rpc_id, None)
+        if future and not future.done():
+            future.set_result(msg)
+
+    async def _publish_event(self, ws, event: str, data: dict = None):
+        """Publish event via event.publish RPC (fire-and-forget)."""
+        await self._rpc_call(ws, "event.publish", {
+            "event_id": str(uuid.uuid4()),
+            "event": event,
+            "data": data or {},
+        }, wait_response=False)
+
+    async def _handle_ws_msg(self, ws, raw: str):
+        try:
+            msg = json.loads(raw)
+        except Exception:
+            return
+        rpc_id = msg.get("id")
+        method = msg.get("method", "")
+
+        # Route 1: RPC 响应（有 id，无 method → 是对我们请求的回复）
+        if rpc_id and not method:
+            self._handle_rpc_response(msg)
+            return
+
+        # Route 2: RPC 请求（有 id + method，且不是事件通知）
+        if method and rpc_id and method != "event":
+            await self._handle_rpc_request(ws, rpc_id, method, msg.get("params", {}))
+            return
+
+        # Route 3: 事件推送
+        if method == "event":
+            params = msg.get("params", {})
+            event = params.get("event", "")
+            data = params.get("data", {})
+            if event == "system.ping":
+                await self._handle_ping_event(ws, data)
+            elif event == "module.shutdown":
+                await self._handle_shutdown(ws)
+            elif event == "module.exiting":
+                print(f"[dataclaw] received module.exiting, shutting down")
+                self._shutdown = True
+            elif event == "system.connection.offer":
+                await self._handle_connection_offer(data)
+            elif event == "system.connection.release":
+                await self._handle_connection_release(data)
+
+    async def _handle_rpc_request(self, ws, rpc_id: str, method: str, params: dict):
+        """处理来自 kernel 转发的 RPC 请求（如 watchdog 健康检查）。"""
+        handlers = {
+            "health": self._rpc_health,
+            "status": self._rpc_status,
+        }
+        handler = handlers.get(method)
+        if handler:
+            try:
+                result = await handler(params)
+                await ws.send(json.dumps({"jsonrpc": "2.0", "id": rpc_id, "result": result}))
+            except Exception as e:
+                await ws.send(json.dumps({
+                    "jsonrpc": "2.0", "id": rpc_id,
+                    "error": {"code": -32603, "message": str(e)}
+                }))
+        else:
+            await ws.send(json.dumps({
+                "jsonrpc": "2.0", "id": rpc_id,
+                "error": {"code": -32601, "message": f"Method not found: {method}"}
+            }))
+
+    async def _rpc_health(self, params: dict) -> dict:
+        """RPC: health"""
+        from core.database import check_connection
+        db_ok, db_err = await check_connection()
+        result = {
+            "status": "healthy" if db_ok else "unhealthy",
+            "uptime_seconds": round(time.time() - self._t0),
+        }
+        if not db_ok:
+            result["error"] = db_err
+        return result
+
+    async def _rpc_status(self, params: dict) -> dict:
+        """RPC: status"""
+        return {
+            "module": "dataclaw",
+            "status": "running",
+            "uptime_seconds": round(time.time() - self._t0),
+        }
+
+    async def _handle_ping_event(self, ws, data: dict):
+        """处理 system.ping 事件并回复 system.pong"""
+        t1 = data.get("ping_time")
+        t2 = time.time()
+        await self._publish_event(ws, "system.pong", {
+            "module_id": "dataclaw",
+            "ping_time": t1,
+            "pong_time": t2,
+        })
+
+    async def _handle_connection_offer(self, data):
+        """处理 Kernel 下发的 slot token，建立附加连接。"""
+        slots = data.get("slots", {})
+        for slot_str, info in slots.items():
+            slot = int(slot_str)
+            token = info.get("token", "")
+            if not token or slot in self._extra_ws:
+                continue
+            asyncio.create_task(self._connect_slot(slot, token))
+
+    async def _connect_slot(self, slot, token):
+        """建立单个 slot 附加连接。"""
+        ws_url = f"ws://127.0.0.1:{self.kernel_port}/ws"
+        try:
+            ws = await websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=5)
+            auth_req = {"jsonrpc": "2.0", "id": f"auth-slot-{slot}", "method": "auth", "params": {"token": token}}
+            await ws.send(json.dumps(auth_req))
+            resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5))
+            if "error" in resp:
+                await ws.close()
+                return
+            self._extra_ws[slot] = ws
+            self._extra_ws_tasks[slot] = asyncio.create_task(self._slot_recv_loop(slot, ws))
+            print(f"[dataclaw] Slot {slot} connected")
+        except Exception as e:
+            print(f"[dataclaw] Slot {slot} connect failed: {e}")
+
+    async def _slot_recv_loop(self, slot, ws):
+        """附加连接的接收循环：与主连接平等处理所有消息。"""
+        try:
+            async for raw in ws:
+                try:
+                    await self._handle_ws_msg(ws, raw)
+                except Exception as e:
+                    print(f"[dataclaw] Slot {slot} 消息处理异常: {e}")
+        except Exception as e:
+            print(f"[dataclaw] Slot {slot} 接收循环异常: {e}")
+        finally:
+            self._extra_ws.pop(slot, None)
+            self._extra_ws_tasks.pop(slot, None)
+
+    async def _handle_connection_release(self, data):
+        """Kernel 请求释放 slot，优雅关闭。"""
+        for slot in data.get("slots", []):
+            ws = self._extra_ws.pop(slot, None)
+            task = self._extra_ws_tasks.pop(slot, None)
+            if ws:
+                try:
+                    await ws.close(code=1000, reason="release")
+                except Exception:
+                    pass
+            if task:
+                task.cancel()
+
+    async def _handle_shutdown(self, ws):
+        """Handle module.shutdown: ack → exiting → cleanup → ready → exit."""
+        print("[dataclaw] Received module.shutdown")
+        self._shutdown = True
+
+        try:
+            # Step 1: Send ack
+            await self._publish_event(ws, "module.shutdown.ack", {
+                "module_id": "dataclaw", "estimated_cleanup": 2,
+            })
+            print("[dataclaw] shutdown ack sent")
+
+            # Step 2: Send module.exiting
+            await self._publish_event(ws, "module.exiting", {
+                "module_id": "dataclaw", "action": "none",
+            })
+
+            # Step 3: Send shutdown.ready（必须在关闭连接之前发送）
+            await self._publish_event(ws, "module.shutdown.ready", {
+                "module_id": "dataclaw",
+            })
+            print("[dataclaw] Shutdown ready sent")
+        except Exception as e:
+            print(f"[dataclaw] shutdown signal send failed (WS may be closed): {e}")
+
+        # Step 4: 等待 Kernel 处理 shutdown.ready
+        await asyncio.sleep(0.01)
+
+        # Step 5: Cleanup - 关闭所有附加连接
+        for _s, _w in list(self._extra_ws.items()):
+            try:
+                await _w.close(code=1000, reason="shutdown")
+            except Exception:
+                pass
+        for _t in self._extra_ws_tasks.values():
+            _t.cancel()
+        self._extra_ws.clear()
+        self._extra_ws_tasks.clear()
+
+        # Step 6: Close main WebSocket
+        try:
+            await ws.close(code=1000, reason="Graceful shutdown")
+            print("[dataclaw] WebSocket closed")
+        except Exception as e:
+            print(f"[dataclaw] shutdown finalize failed (WS may be closed): {e}")
+
+        # Step 6: 通知 uvicorn 退出（无论前面是否失败都必须执行）
+        if self._uv_server:
+            self._uv_server.should_exit = True
+
+    def _register_routes(self, app: FastAPI):
+        """注册所有路由"""
+        # ── 服务发现 ──
+        @app.get("/.well-known/agent-data-exchange.json", tags=["discovery"])
+        async def discovery():
+            return {
+                "platform": "DataClaw",
+                "version": "2.0",
+                "description": "Agent 数据共享平台 — 一次采集，万次复用",
+                "endpoints": {
+                    "http_api": f"http://localhost:{self.port}/v1",
+                    "websocket": f"ws://localhost:{self.port}/ws",
+                },
+                "api_spec": f"http://localhost:{self.port}/v1/openapi.json",
+                "capabilities": [
+                    "feed_registry", "data_query", "subscription",
+                    "timeline", "demand_board", "credit_system",
+                    "search", "review", "copyright", "websocket"
+                ],
+                "quick_start": {
+                    "step_1_register": "POST /v1/identity/register",
+                    "step_2_discover": "GET /v1/search/feeds?q={keyword}",
+                    "step_3_subscribe": "POST /v1/subscriptions",
+                    "step_4_consume": "GET /v1/timeline",
+                },
+                "rate_limits": {"anonymous": "10/min", "authenticated": "600/min"},
+            }
+
+        # ── 健康检查 ──
+        @app.get("/health", tags=["system"])
+        async def health():
+            from core.database import check_connection
+            db_ok, db_err = await check_connection()
+            result = {
+                "ok": db_ok,
+                "service": "dataclaw",
+                "version": "2.0",
+                "database": "ok" if db_ok else "error",
+                "uptime_ms": int((time.monotonic() - self._t0) * 1000),
+            }
+            if not db_ok:
+                result["database_error"] = db_err
+            return result
+
+        # ── 注册各模块路由 ──
+        self._mount_api_routes(app)
+        self._mount_ws_routes(app)
+        self._mount_static_and_pages(app)
+
+    def _mount_api_routes(self, app: FastAPI):
+        """挂载所有 /v1 API 路由（使用预导入的 router）"""
+        if 'identity' in _api_routers:
+            app.include_router(_api_routers['identity'], prefix="/v1/identity", tags=["identity"])
+
+        if 'feeds' in _api_routers:
+            app.include_router(_api_routers['feeds'], prefix="/v1/feeds", tags=["feeds"])
+
+        if 'data' in _api_routers:
+            app.include_router(_api_routers['data'], prefix="/v1/feeds", tags=["data"])
+
+        if 'subscriptions' in _api_routers:
+            app.include_router(_api_routers['subscriptions'], prefix="/v1", tags=["subscriptions"])
+
+        if 'search' in _api_routers:
+            app.include_router(_api_routers['search'], prefix="/v1", tags=["search"])
+
+        if 'demands' in _api_routers:
+            app.include_router(_api_routers['demands'], prefix="/v1/demands", tags=["demands"])
+
+        if 'credits' in _api_routers:
+            app.include_router(_api_routers['credits'], prefix="/v1/credits", tags=["credits"])
+
+        if 'reviews' in _api_routers:
+            app.include_router(_api_routers['reviews'], prefix="/v1/feeds", tags=["reviews"])
+
+        if 'notifications' in _api_routers:
+            app.include_router(_api_routers['notifications'], prefix="/v1/notifications", tags=["notifications"])
+
+        if 'copyright' in _api_routers:
+            app.include_router(_api_routers['copyright'], prefix="/v1/copyright", tags=["copyright"])
+
+        if 'admin' in _api_routers:
+            app.include_router(_api_routers['admin'], prefix="/v1/admin", tags=["admin"])
+
+    def _mount_ws_routes(self, app: FastAPI):
+        """挂载 WebSocket 端点（使用预导入的 router）"""
+        if 'ws' in _api_routers:
+            app.include_router(_api_routers['ws'])
+
+    def _mount_static_and_pages(self, app: FastAPI):
+        """挂载静态文件和多页面前端"""
+        static_dir = _THIS_DIR / "static"
+        templates_dir = _THIS_DIR / "templates"
+
+        if static_dir.exists():
+            app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+        if templates_dir.exists():
+            templates = Jinja2Templates(directory=str(templates_dir))
+            self._templates = templates
+            self._register_page_routes(app, templates)
+
+    def _register_page_routes(self, app: FastAPI, templates: "Jinja2Templates"):
+        """注册多页面路由"""
+        @app.get("/", response_class=HTMLResponse, tags=["pages"])
+        async def index(request: Request):
+            return templates.TemplateResponse("index.html", {"request": request})
+
+        @app.get("/login", response_class=HTMLResponse, tags=["pages"])
+        async def login(request: Request):
+            return templates.TemplateResponse("login.html", {"request": request})
+
+        @app.get("/register", response_class=HTMLResponse, tags=["pages"])
+        async def register(request: Request):
+            return templates.TemplateResponse("register.html", {"request": request})
+
+        @app.get("/dashboard", response_class=HTMLResponse, tags=["pages"])
+        async def dashboard(request: Request):
+            return templates.TemplateResponse("dashboard.html", {"request": request})
+
+        @app.get("/feeds", response_class=HTMLResponse, tags=["pages"])
+        async def feeds_page(request: Request):
+            return templates.TemplateResponse("feeds/list.html", {"request": request})
+
+        @app.get("/feeds/create", response_class=HTMLResponse, tags=["pages"])
+        async def feeds_create(request: Request):
+            return templates.TemplateResponse("feeds/create.html", {"request": request})
+
+        @app.get("/feeds/{feed_id}", response_class=HTMLResponse, tags=["pages"])
+        async def feed_detail(request: Request, feed_id: str):
+            return templates.TemplateResponse("feeds/detail.html", {"request": request, "feed_id": feed_id})
+
+        @app.get("/feeds/{feed_id}/manage", response_class=HTMLResponse, tags=["pages"])
+        async def feed_manage(request: Request, feed_id: str):
+            return templates.TemplateResponse("feeds/manage.html", {"request": request, "feed_id": feed_id})
+
+        @app.get("/subscriptions", response_class=HTMLResponse, tags=["pages"])
+        async def subscriptions_page(request: Request):
+            return templates.TemplateResponse("subscriptions/list.html", {"request": request})
+
+        @app.get("/demands", response_class=HTMLResponse, tags=["pages"])
+        async def demands_page(request: Request):
+            return templates.TemplateResponse("demands/list.html", {"request": request})
+
+        @app.get("/demands/create", response_class=HTMLResponse, tags=["pages"])
+        async def demands_create(request: Request):
+            return templates.TemplateResponse("demands/create.html", {"request": request})
+
+        @app.get("/demands/{demand_id}", response_class=HTMLResponse, tags=["pages"])
+        async def demand_detail(request: Request, demand_id: str):
+            return templates.TemplateResponse("demands/detail.html", {"request": request, "demand_id": demand_id})
+
+        @app.get("/credits", response_class=HTMLResponse, tags=["pages"])
+        async def credits_page(request: Request):
+            return templates.TemplateResponse("credits/balance.html", {"request": request})
+
+        @app.get("/credits/history", response_class=HTMLResponse, tags=["pages"])
+        async def credits_history(request: Request):
+            return templates.TemplateResponse("credits/history.html", {"request": request})
+
+        @app.get("/credits/deposit", response_class=HTMLResponse, tags=["pages"])
+        async def credits_deposit(request: Request):
+            return templates.TemplateResponse("credits/deposit.html", {"request": request})
+
+        @app.get("/settings", response_class=HTMLResponse, tags=["pages"])
+        async def settings_page(request: Request):
+            return templates.TemplateResponse("settings/profile.html", {"request": request})
+
+        @app.get("/settings/api-keys", response_class=HTMLResponse, tags=["pages"])
+        async def settings_api_keys(request: Request):
+            return templates.TemplateResponse("settings/profile.html", {"request": request})
+
+        @app.get("/settings/notifications", response_class=HTMLResponse, tags=["pages"])
+        async def settings_notifications(request: Request):
+            return templates.TemplateResponse("settings/notifications.html", {"request": request})
+
+        @app.get("/admin", response_class=HTMLResponse, tags=["pages"])
+        async def admin_page(request: Request):
+            return templates.TemplateResponse("admin/index.html", {"request": request})