@agentunion/kite 1.4.0 → 1.6.0

package/extensions/services/proxy/server.py

@@ -0,0 +1,952 @@
+"""
+ProxyServer - Kite 模块服务器
+
+FastAPI 4 路由 + Kernel WS 客户端 + RPC 注册/处理 + 事件发布订阅。
+整合 auth_bridge、aid_manager、config_store，提供完整的代理生命周期管理。
+"""
+
+import asyncio
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+
+import websockets
+from fastapi import FastAPI, Request, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, Response
+
+from .auth_bridge import AuthBridge
+from .aid_manager import AIDManager
+from .config_store import ConfigStore
+
+
+# ==================== 并发管理器 ====================
+
+class ConcurrencyLimitManager:
+    """管理代理接口的总并发数，带自动清理超时请求"""
+
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+        self._initialized = True
+        self._active_requests = {}
+        self._count_lock = threading.Lock()
+        self._timeout_seconds = 300
+        print("[ConcurrencyLimitManager] initialized")
+
+    def acquire(self) -> tuple:
+        with self._count_lock:
+            self._cleanup_timeout_requests()
+            request_id = f"req_{int(time.time() * 1000)}_{id(threading.current_thread())}"
+            self._active_requests[request_id] = time.time()
+            return True, "", request_id
+
+    def release(self, request_id: str = None):
+        with self._count_lock:
+            if request_id and request_id in self._active_requests:
+                del self._active_requests[request_id]
+            elif not request_id and self._active_requests:
+                oldest_id = min(self._active_requests, key=self._active_requests.get)
+                del self._active_requests[oldest_id]
+
+    def _cleanup_timeout_requests(self):
+        current_time = time.time()
+        timeout_ids = [
+            rid for rid, t in self._active_requests.items()
+            if current_time - t > self._timeout_seconds
+        ]
+        for rid in timeout_ids:
+            del self._active_requests[rid]
+
+    def get_current_count(self) -> int:
+        with self._count_lock:
+            return len(self._active_requests)
+
+
+concurrency_manager = ConcurrencyLimitManager()
+
+
+# ==================== ProxyServer ====================
+
+class ProxyServer:
+    def __init__(self, token: str, kernel_port: int, host: str, port: int, boot_t0: float, max_connections: int = 1,
+                 gateway_url: str = "", kite_token: str = ""):
+        self.token = token
+        self.kernel_port = kernel_port
+        self.host = host
+        self.port = port
+        self.boot_t0 = boot_t0
+        self.max_connections = max_connections
+        self.gateway_url = gateway_url
+        self.kite_token = kite_token
+        self._ws_task: asyncio.Task | None = None
+        self._ws = None
+        self._shutting_down = False
+        self._exit_code = 0
+        self._auth_failed = False
+        self._uvicorn_server = None
+        self._start_time = time.time()
+        self._pending_rpc = {}
+        self._extra_ws: dict = {}           # slot → WebSocket
+        self._extra_ws_tasks: dict = {}     # slot → recv loop Task
+        self._has_registered = False
+
+        # 组件初始化
+        self.auth_bridge = AuthBridge()
+        self.config_store = ConfigStore()
+        self.aid_manager = AIDManager(self.auth_bridge, self.config_store)
+
+        # 注入 userPresenter / configPresenter
+        self._inject_presenters()
+
+        # AID 上线回调
+        self.aid_manager.set_on_aid_online(self._on_aid_online)
+
+        self.app = self._create_app()
+
+    def _inject_presenters(self):
+        """将 auth_bridge / aid_manager 注入到 presenter 层"""
+        try:
+            from .evol.presenter.userPresenter import userPresenter
+            from .evol.presenter.configPresenter import configPresenter
+            from .evol.presenter.apikeyPresenter import apikeyPresenter
+
+            userPresenter.set_aid_manager(self.aid_manager)
+            userPresenter.set_auth_bridge(self.auth_bridge)
+            apikeyPresenter.set_auth_bridge(self.auth_bridge)
+
+            # 同步注入 token（如果缓存中有）
+            cached = self.auth_bridge.get_cached_token()
+            if cached:
+                configPresenter.set_evol_token(cached)
+        except Exception as e:
+            print(f"[proxy] 注入 presenter 失败: {e}")
+
+    def _on_aid_online(self, aid):
+        """AID 上线回调 - 注册消息处理器"""
+        try:
+            from .evol.presenter.agentIdPresenter import agentIdPresenter
+            agentIdPresenter.evol_agentId_online(aid)
+            print(f"[proxy] AID 消息处理器已注册: {aid.id}")
+
+            # 发布事件（异步）
+            if self._ws:
+                asyncio.ensure_future(self._publish_event(
+                    self._ws, "proxy.aid_online",
+                    {"module_id": "proxy", "agent_id": aid.id},
+                ))
+        except Exception as e:
+            print(f"[proxy] AID 上线处理失败: {e}")
+
+    def _create_app(self) -> FastAPI:
+        app = FastAPI(title="Kite Proxy Module", docs_url=None, redoc_url=None)
+        server = self
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        @app.on_event("startup")
+        async def _startup():
+            if server.kernel_port:
+                server._ws_task = asyncio.create_task(server._ws_loop())
+
+        @app.on_event("shutdown")
+        async def _shutdown():
+            if server._ws_task:
+                server._ws_task.cancel()
+            if server._ws:
+                try:
+                    await server._ws.close()
+                except Exception:
+                    pass
+            print("[proxy] FastAPI shutdown complete")
+
+        # ── 健康检查 ──
+
+        @app.get("/health")
+        async def health_check():
+            agent_id = server.aid_manager.agentId
+            return {
+                "status": "ok",
+                "agent_id": agent_id.id if agent_id else None,
+                "is_online": agent_id.is_online_success if agent_id else False,
+                "active_requests": concurrency_manager.get_current_count(),
+            }
+
+        @app.get("/status")
+        async def status():
+            agent_id = server.aid_manager.agentId
+            return {
+                "module": "proxy",
+                "status": "running",
+                "kernel_connected": server._ws is not None,
+                "agent_id": agent_id.id if agent_id else None,
+                "is_online": agent_id.is_online_success if agent_id else False,
+                "uptime_seconds": round(time.time() - server._start_time),
+                "active_requests": concurrency_manager.get_current_count(),
+            }
+
+        # ── Claude Proxy 路由 ──
+
+        @app.api_route("/claude-proxy/{full_path:path}",
+                        methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"])
+        async def claude_proxy_route(request: Request, full_path: str):
+            acquired, error_msg, request_id = concurrency_manager.acquire()
+            if not acquired:
+                return Response(content=error_msg.encode("utf-8"), status_code=429)
+
+            if "v1/messages" not in full_path:
+                concurrency_manager.release(request_id)
+                raise HTTPException(status_code=200, detail="OK")
+
+            try:
+                request_body = await request.body()
+                bodyjson = await asyncio.to_thread(json.loads, request_body.decode("utf-8"))
+                model = bodyjson.get("model", "")
+                if "claude" not in model:
+                    raise HTTPException(status_code=400, detail="Unsupported model")
+
+                from .evol.server.claude_proxy_async import proxy_claude_request
+                response = await proxy_claude_request(request)
+                return response
+
+            except asyncio.CancelledError:
+                return Response(content=b"Client Closed Request", status_code=499)
+            except HTTPException:
+                raise
+            except Exception as e:
+                return Response(content=str(e).encode("utf-8"), status_code=503)
+            finally:
+                concurrency_manager.release(request_id)
+
+        # ── Codex Proxy 路由 ──
+
+        @app.api_route("/codex-proxy/{full_path:path}",
+                        methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"])
+        async def codex_proxy_route(request: Request, full_path: str):
+            acquired, error_msg, request_id = concurrency_manager.acquire()
+            if not acquired:
+                return Response(content=error_msg.encode("utf-8"), status_code=429)
+
+            try:
+                from .evol.server.claude_proxy_async import proxy_claude_request
+                response = await proxy_claude_request(request)
+                return response
+
+            except asyncio.CancelledError:
+                return Response(content=b"Client Closed Request", status_code=499)
+            except Exception as e:
+                if isinstance(e, HTTPException):
+                    return Response(content=str(e.detail).encode("utf-8"), status_code=e.status_code)
+                return Response(content=str(e).encode("utf-8"), status_code=503)
+            finally:
+                concurrency_manager.release(request_id)
+
+        # ── Gemini Proxy 路由 ──
+
+        @app.api_route("/gemini-proxy/{full_path:path}",
+                        methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"])
+        async def gemini_proxy_route(request: Request, full_path: str):
+            acquired, error_msg, request_id = concurrency_manager.acquire()
+            if not acquired:
+                return Response(content=error_msg.encode("utf-8"), status_code=429)
+
+            try:
+                from .evol.server.claude_proxy_async import proxy_claude_request
+                response = await proxy_claude_request(request)
+                return response
+
+            except asyncio.CancelledError:
+                return Response(content=b"Client Closed Request", status_code=499)
+            except Exception as e:
+                if isinstance(e, HTTPException):
+                    return Response(content=str(e.detail).encode("utf-8"), status_code=e.status_code)
+                return Response(content=str(e).encode("utf-8"), status_code=503)
+            finally:
+                concurrency_manager.release(request_id)
+
+        # ── OpenClaw Proxy 路由 ──
+
+        @app.api_route("/openclaw-proxy/{full_path:path}",
+                        methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"])
+        async def openclaw_proxy_route(request: Request, full_path: str):
+            acquired, error_msg, request_id = concurrency_manager.acquire()
+            if not acquired:
+                from .evol.server.openclaw_proxy import openai_error_response
+                return openai_error_response(error_msg, error_type="rate_limit_exceeded", status_code=429)
+
+            try:
+                if full_path == "v1/models":
+                    from .evol.server.openclaw_proxy import get_models_list
+                    return JSONResponse(get_models_list())
+                elif full_path == "v1/chat/completions":
+                    from .evol.server.openclaw_proxy import proxy_openclaw_request
+                    response = await proxy_openclaw_request(request)
+                    return response
+                else:
+                    from .evol.server.openclaw_proxy import openai_error_response
+                    return openai_error_response(
+                        f"Path not found: /{full_path}. Supported: /v1/models, /v1/chat/completions.",
+                        error_type="invalid_request_error",
+                        status_code=404,
+                    )
+
+            except asyncio.CancelledError:
+                return Response(content=b"Client Closed Request", status_code=499)
+            except Exception as e:
+                from .evol.server.openclaw_proxy import openai_error_response
+                return openai_error_response(f"Internal server error: {str(e)}", error_type="api_error", status_code=500)
+            finally:
+                concurrency_manager.release(request_id)
+
+        return app
+
+    # ── system.require_init 处理 ──
+
+    async def _do_init(self, ws):
+        """收到 system.require_init 后执行：订阅 + 注册 + module.ready"""
+        reason = "startup" if not self._has_registered else "recovery"
+        print(f"[proxy] Received system.require_init (reason={reason})")
+
+        try:
+            # 注入 RPC 调用到 auth_bridge（包装为旧签名兼容）
+            async def _rpc_caller_for_bridge(method, params=None, timeout=3.0):
+                return await self._rpc_call(self._ws, method, params, timeout=timeout)
+            self.auth_bridge.set_rpc_caller(_rpc_caller_for_bridge)
+
+            # 订阅事件
+            await self._rpc_call(ws, "event.subscribe", {
+                "events": [
+                    "module.shutdown",
+                    "module.ready",
+                    "evol.user_ready",
+                    "evol.user_logout",
+                ],
+            })
+
+            # 注册到 Kernel
+            elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
+            elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
+            await self._rpc_call(ws, "registry.register", {
+                "module_id": "proxy",
+                "module_type": "service",
+                "api_endpoint": f"http://127.0.0.1:{self.port}",
+                "health_endpoint": "/health",
+                "tools": {
+                    "rpc": {
+                        "module": {
+                            "health": {"method": "health", "description": "健康检查"},
+                            "status": {"method": "status", "description": "状态查询"},
+                        },
+                        "proxy": {
+                            "get_endpoints": {"method": "get_endpoints", "description": "获取代理端点"},
+                            "get_aid_status": {"method": "get_aid_status", "description": "AID 状态"},
+                            "reconnect_aid": {"method": "reconnect_aid", "description": "重连 AID"},
+                        },
+                    },
+                },
+                "events_publish": {
+                    "proxy": {
+                        "started": {"description": "Proxy 模块启动"},
+                        "aid_online": {"description": "AID 上线"},
+                        "aid_offline": {"description": "AID 离线"},
+                    },
+                },
+                "events_subscribe": [
+                    "module.shutdown",
+                    "module.ready",
+                    "evol.user_ready",
+                    "evol.user_logout",
+                ],
+            })
+            print(f"[proxy] Registered to Kernel{elapsed_str}")
+
+            # 发布 module.ready
+            if not self._shutting_down:
+                startup_time = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
+                await self._publish_event(ws, "module.ready", {
+                    "module_id": "proxy",
+                    "graceful_shutdown": True,
+                    "startup_time": startup_time,
+                    "reason": reason,
+                })
+                print(f"[proxy] module.ready published{elapsed_str}")
+
+                # 发布 proxy.started 事件
+                display_host = "localhost" if self.host == "0.0.0.0" else self.host
+                await self._publish_event(ws, "proxy.started", {
+                    "module_id": "proxy",
+                    "url": f"http://{display_host}:{self.port}",
+                    "endpoints": {
+                        "claude": f"/claude-proxy/",
+                        "codex": f"/codex-proxy/",
+                        "gemini": f"/gemini-proxy/",
+                        "openclaw": f"/openclaw-proxy/",
+                    },
+                })
+
+            self._has_registered = True
+
+            # 尝试初始化 AID（如果 evol 已就绪）
+            asyncio.create_task(self._try_init_aid())
+
+        except Exception as e:
+            print(f"[proxy] _do_init failed: {e}")
+
+    # ── Kernel WebSocket 客户端 ──
+
+    async def _ws_loop(self):
+        retry_delay = 0.3
+        max_delay = 5.0
+        max_retries = 10
+        attempt = 0
+        while not self._shutting_down:
+            try:
+                await self._ws_connect()
+                retry_delay = 0.3
+                attempt = 0
+            except asyncio.CancelledError:
+                print("[proxy] WS loop cancelled")
+                return
+            except Exception as e:
+                attempt += 1
+                if hasattr(e, "rcvd") and e.rcvd is not None:
+                    code = e.rcvd.code if hasattr(e.rcvd, "code") else 0
+                    if code in (4001, 4003):
+                        print(f"[proxy] Kernel 认证失败 (code {code})，退出")
+                        self._exit_code = 1
+                        self._auth_failed = True
+                        self._shutting_down = True
+                        if self._uvicorn_server:
+                            self._uvicorn_server.should_exit = True
+                        return
+                if attempt >= max_retries:
+                    print(f"[proxy] Kernel 重连失败 {max_retries} 次，退出")
+                    self._exit_code = 1
+                    self._shutting_down = True
+                    if self._uvicorn_server:
+                        self._uvicorn_server.should_exit = True
+                    return
+                if self._shutting_down:
+                    return
+                print(f"[proxy] Kernel connection error: {e}, retrying in {retry_delay:.1f}s ({attempt}/{max_retries})")
+            self._ws = None
+            if self._shutting_down:
+                return
+            await asyncio.sleep(retry_delay)
+            retry_delay = min(retry_delay * 2, max_delay)
+
+    async def _ws_connect(self):
+        url = f"ws://127.0.0.1:{self.kernel_port}/ws?id=proxy"
+        print("[proxy] WS connecting to Kernel")
+        async with websockets.connect(url, open_timeout=5, ping_interval=None, close_timeout=10) as ws:
+            self._ws = ws
+            elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
+            elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
+            print(f"[proxy] Connected to Kernel{elapsed_str}")
+
+            # 认证握手
+            auth_req = {
+                "jsonrpc": "2.0",
+                "id": "auth",
+                "method": "auth",
+                "params": {"token": self.token}
+            }
+            await ws.send(json.dumps(auth_req))
+            auth_resp_raw = await asyncio.wait_for(ws.recv(), timeout=5)
+            auth_resp = json.loads(auth_resp_raw)
+            if "error" in auth_resp:
+                raise Exception(f"Auth failed: {auth_resp['error']}")
+
+            # 启动接收循环（等待 system.require_init 触发 _do_init）
+            receiver_task = asyncio.create_task(self._ws_receiver(ws))
+
+            try:
+                # 等待接收循环结束
+                await receiver_task
+            except Exception as e:
+                receiver_task.cancel()
+                try:
+                    await receiver_task
+                except asyncio.CancelledError:
+                    pass
+                raise
+
+    async def _ws_receiver(self, ws):
+        """WebSocket 接收循环"""
+        try:
+            async for raw in ws:
+                try:
+                    msg = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+
+                try:
+                    has_method = "method" in msg
+                    has_id = "id" in msg
+                    has_result_or_error = "result" in msg or "error" in msg
+
+                    if has_method and not has_id:
+                        # 检测 system.require_init 事件
+                        params = msg.get("params", {})
+                        event_type = params.get("event", "")
+                        if event_type == "system.require_init":
+                            asyncio.create_task(self._do_init(ws))
+                            continue
+                        asyncio.create_task(self._handle_event_notification(msg))
+                    elif has_method and has_id:
+                        asyncio.create_task(self._handle_rpc_request(ws, msg))
+                    elif has_id and has_result_or_error:
+                        self._handle_rpc_response(msg)
+                except Exception as e:
+                    print(f"[proxy] 消息处理异常: {e}")
+        except Exception as e:
+            print(f"[proxy] Receive loop exited: {e}")
+        finally:
+            # 断连清理：取消所有等待中的 RPC future
+            for rpc_id, future in list(self._pending_rpc.items()):
+                if not future.done():
+                    future.set_exception(ConnectionError("WebSocket disconnected"))
+            self._pending_rpc.clear()
+
+    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)"}}
+
+    # ── 事件处理 ──
+
+    async def _handle_event_notification(self, msg: dict):
+        params = msg.get("params", {})
+        event_type = params.get("event", "")
+        data = params.get("data", {})
+
+        if event_type == "system.ping":
+            await self._handle_ping(data)
+            return
+
+        # 弹性连接 offer/release
+        if event_type == "system.connection.offer":
+            asyncio.create_task(self._handle_connection_offer(data))
+            return
+        if event_type == "system.connection.release":
+            asyncio.create_task(self._handle_connection_release(data))
+            return
+
+        if event_type == "module.shutdown":
+            target = data.get("module_id", "")
+            reason = data.get("reason", "")
+            if target == "proxy" or not target or reason == "launcher_lost":
+                await self._handle_shutdown()
+            return
+
+        if event_type == "module.ready":
+            module_id = data.get("module_id", "")
+            if module_id == "evol":
+                print("[proxy] 检测到 evol 模块就绪（框架层）")
+                self.auth_bridge.set_evol_ready(True)
+                # 不再在此触发 AID 初始化，等待 evol.user_ready 业务事件
+            return
+
+        if event_type == "evol.user_ready":
+            phone = data.get("phone", "")
+            print(f"[proxy] 收到 evol.user_ready 事件 (phone: {phone})")
+            self.auth_bridge.set_evol_ready(True)
+            asyncio.create_task(self._try_init_aid())
+            return
+
+        if event_type == "evol.user_logout":
+            print(f"[proxy] 收到用户登出事件，开始清理...")
+            asyncio.create_task(self._handle_user_logout(data))
+            return
+
+    async def _handle_user_logout(self, data: dict):
+        """处理用户登出：清缓存 → 清 Session → AID 下线"""
+        try:
+            # 1. 清除 AuthBridge token 缓存
+            self.auth_bridge.invalidate()
+
+            # 2. 清除 AsyncSessionManager 所有会话缓存
+            from .evol.server.claude_proxy_async import _clear_async_session_manager_cache
+            _clear_async_session_manager_cache()
+
+            # 3. AID 下线
+            await self.aid_manager.shutdown()
+
+            # 4. 发布 AID 离线事件
+            if self._ws:
+                await self._publish_event(self._ws, "proxy.aid_offline", {
+                    "module_id": "proxy", "reason": "user_logout",
+                })
+
+            print("[proxy] 用户登出清理完成，AID 已下线")
+        except Exception as e:
+            print(f"[proxy] 用户登出清理异常: {e}")
+
+    async def _handle_ping(self, data: dict):
+        if not self._ws:
+            return
+        await self._publish_event(self._ws, "system.pong", {
+            "module_id": "proxy",
+            "ping_time": data.get("ping_time"),
+            "pong_time": time.time(),
+        })
+
+    async def _handle_rpc_request(self, ws, msg: dict):
+        rpc_id = msg.get("id", "")
+        method = msg.get("method", "")
+        params = msg.get("params", {})
+
+        if method.startswith("proxy."):
+            method = method[6:]
+
+        handlers = {
+            "health": lambda p: self._rpc_health(),
+            "status": lambda p: self._rpc_status(),
+            "get_endpoints": lambda p: self._rpc_get_endpoints(),
+            "get_aid_status": lambda p: self._rpc_get_aid_status(),
+            "reconnect_aid": lambda p: self._rpc_reconnect_aid(),
+        }
+
+        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}"},
+            }))
+
+    # ── RPC 处理器 ──
+
+    async def _rpc_health(self) -> dict:
+        agent_id = self.aid_manager.agentId
+        return {
+            "status": "healthy",
+            "agent_id": agent_id.id if agent_id else None,
+            "is_online": agent_id.is_online_success if agent_id else False,
+            "active_requests": concurrency_manager.get_current_count(),
+        }
+
+    async def _rpc_status(self) -> dict:
+        agent_id = self.aid_manager.agentId
+        return {
+            "module": "proxy",
+            "status": "running",
+            "agent_id": agent_id.id if agent_id else None,
+            "is_online": agent_id.is_online_success if agent_id else False,
+            "uptime_seconds": round(time.time() - self._start_time),
+            "active_requests": concurrency_manager.get_current_count(),
+        }
+
+    async def _rpc_get_endpoints(self) -> dict:
+        display_host = "localhost" if self.host == "0.0.0.0" else self.host
+        base = f"http://{display_host}:{self.port}"
+        return {
+            "endpoints": {
+                "claude": f"{base}/claude-proxy/",
+                "codex": f"{base}/codex-proxy/",
+                "gemini": f"{base}/gemini-proxy/",
+                "openclaw": f"{base}/openclaw-proxy/",
+            },
+        }
+
+    async def _rpc_get_aid_status(self) -> dict:
+        agent_id = self.aid_manager.agentId
+        return {
+            "agent_id": agent_id.id if agent_id else None,
+            "is_online": agent_id.is_online_success if agent_id else False,
+            "evol_ready": self.auth_bridge._evol_ready,
+            "has_token": self.auth_bridge.is_logged_in(),
+        }
+
+    async def _rpc_reconnect_aid(self) -> dict:
+        result = await self.aid_manager.force_rebuild(bypass_cooldown=True)
+        return result
+
+    # ── AID 初始化 ──
+
+    async def _try_init_aid(self, retries: int = 0, max_retries: int = 3, retry_interval: float = 5.0):
+        """尝试初始化 AID（evol 就绪后执行）
+
+        Args:
+            retries: 当前重试次数
+            max_retries: 最大重试次数
+            retry_interval: 重试间隔（秒）
+        """
+        # 防重入：已有 AID 且在线则跳过
+        if self.aid_manager.agentId is not None and self.aid_manager.agentId.is_online_success:
+            return
+
+        # 防并发：首次调用时检查
+        if retries == 0 and self.aid_manager._aid_initializing:
+            return
+        if retries == 0:
+            self.aid_manager._aid_initializing = True
+
+        if not self.auth_bridge._evol_ready:
+            # evol 尚未就绪时，主动探测 evol 模块状态
+            if retries == 0:
+                await self._probe_evol_ready()
+            if not self.auth_bridge._evol_ready:
+                self.aid_manager._aid_initializing = False
+                return
+
+        try:
+            # 先获取 token 并注入
+            evol_token = await self.auth_bridge.get_evol_token()
+            if evol_token:
+                from .evol.presenter.configPresenter import configPresenter
+                configPresenter.set_evol_token(evol_token)
+                print(f"[proxy] evol_token 已注入 configPresenter")
+
+                # 初始化 AID
+                success = await self.aid_manager.initialize()
+                if success:
+                    # 同步 agentId 到 userPresenter
+                    from .evol.presenter.userPresenter import userPresenter
+                    userPresenter.agentId = self.aid_manager.agentId
+                    print(f"[proxy] AID 初始化成功")
+                else:
+                    print("[proxy] AID 初始化失败")
+            else:
+                # token 获取失败，有限重试
+                if retries < max_retries:
+                    print(f"[proxy] 无法获取 evol_token，{retry_interval}s 后重试 ({retries + 1}/{max_retries})")
+                    await asyncio.sleep(retry_interval)
+                    await self._try_init_aid(retries=retries + 1, max_retries=max_retries, retry_interval=retry_interval)
+                else:
+                    print("[proxy] 无法获取 evol_token，已达最大重试次数，AID 初始化延迟")
+        except Exception as e:
+            print(f"[proxy] AID 初始化异常: {e}")
+        finally:
+            self.aid_manager._aid_initializing = False
+
+    async def _probe_evol_ready(self):
+        """主动探测 evol 是否有可用 token（防止错过 evol.user_ready 事件）"""
+        if not self._ws:
+            return
+        try:
+            # 先探测 evol 框架是否就绪
+            result = await self._rpc_call(self._ws, "evol.health", timeout=3.0)
+            if result.get("status") != "healthy":
+                return
+            self.auth_bridge.set_evol_ready(True)
+
+            # 再探测是否有已登录的 token
+            token_result = await self._rpc_call(self._ws, "evol.has_evol_token", timeout=3.0)
+            if token_result.get("has_token"):
+                phone = token_result.get("phone", "")
+                print(f"[proxy] 主动探测发现 evol 已有可用 token (phone: {phone})")
+                asyncio.create_task(self._try_init_aid())
+        except Exception:
+            pass
+
+    # ── RPC 响应处理 ──
+
+    def _handle_rpc_response(self, msg: dict):
+        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_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"[proxy] Slot {slot} connected")
+        except Exception as e:
+            print(f"[proxy] Slot {slot} connect failed: {e}")
+
+    async def _slot_recv_loop(self, slot, ws):
+        """附加 slot 接收循环：与主连接平等处理所有消息。"""
+        try:
+            async for raw in ws:
+                try:
+                    msg = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+
+                try:
+                    has_method = "method" in msg
+                    has_id = "id" in msg
+                    has_result_or_error = "result" in msg or "error" in msg
+
+                    if has_method and not has_id:
+                        asyncio.create_task(self._handle_event_notification(msg))
+                    elif has_method and has_id:
+                        asyncio.create_task(self._handle_rpc_request(ws, msg))
+                    elif has_id and has_result_or_error:
+                        self._handle_rpc_response(msg)
+                except Exception as e:
+                    print(f"[proxy] Slot {slot} 消息处理异常: {e}")
+        except Exception as e:
+            print(f"[proxy] Slot {slot} recv loop exited: {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):
+        print("[proxy] Received module.shutdown")
+        self._shutting_down = True
+
+        ws = self._ws
+        if not ws:
+            return
+
+        # ack
+        try:
+            await self._publish_event(ws, "module.shutdown.ack", {
+                "module_id": "proxy",
+            })
+        except Exception:
+            pass
+
+        # exiting
+        try:
+            await self._publish_event(ws, "module.exiting", {
+                "module_id": "proxy",
+                "type": "passive",
+                "reason": "shutdown_requested",
+                "restart": "auto",
+                "action": "none",
+                "timeout": 5.0,
+                "restart_delay": 0.0,
+            })
+        except Exception:
+            pass
+
+        # AID 下线
+        try:
+            await self.aid_manager.shutdown()
+        except Exception as e:
+            print(f"[proxy] AID 关闭失败: {e}")
+
+        # AID 离线事件
+        try:
+            await self._publish_event(ws, "proxy.aid_offline", {
+                "module_id": "proxy",
+            })
+        except Exception:
+            pass
+
+        # ready（必须在关闭连接之前发送）
+        try:
+            await self._publish_event(ws, "module.shutdown.ready", {
+                "module_id": "proxy",
+            })
+        except Exception:
+            pass
+
+        # 等待 Kernel 处理 shutdown.ready
+        await asyncio.sleep(0.01)
+
+        # 关闭所有附加连接
+        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()
+
+        # 关闭 Kernel WS
+        if self._ws:
+            try:
+                await self._ws.close(code=1000, reason="Graceful shutdown")
+                print("[proxy] Kernel WebSocket closed")
+            except Exception:
+                pass
+
+        # 触发 uvicorn 退出
+        if self._uvicorn_server:
+            print("[proxy] Triggering uvicorn shutdown")
+            self._uvicorn_server.should_exit = True