@agentunion/kite 1.5.0 → 1.6.0

package/extensions/services/gateway/entry.py

@@ -0,0 +1,964 @@
+"""
+Gateway 模块入口 - 远程接入网关
+
+从 stdin 读 boot_info → 连接 Kernel → auth → registry.register → 启动 WS 服务器 → module.ready → 消息循环
+"""
+
+import builtins
+import json
+import os
+import sys
+import threading
+import re
+import time
+from datetime import datetime, timezone
+
+import asyncio
+import traceback
+import uuid
+import random
+
+import websockets
+
+
+# System broadcast events
+SYSTEM_BROADCAST_EVENTS = {
+    "module.ready", "module.registered", "module.started", "module.stopped",
+    "module.crashed", "module.exiting", "module.offline",
+    "module.shutdown.ack", "module.shutdown.ready",
+    "system.ready", "registry.updated",
+    "system.instance.started", "system.instance.stopped",
+}
+
+
+# ── Module configuration ──
+
+def _load_module_config() -> dict:
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+    project_root = os.environ.get("KITE_PROJECT", "")
+    if project_root and _this_dir.startswith(project_root):
+        rel_path = os.path.relpath(_this_dir, project_root)
+    else:
+        rel_path = _this_dir
+    result = {"name": "", "preferred_port": 0, "advertise_ip": "0.0.0.0"}
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: module.md not found")
+        sys.exit(1)
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Missing YAML frontmatter")
+            sys.exit(1)
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed")
+            sys.exit(1)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Missing 'name' field")
+            sys.exit(1)
+        raw_name = str(fm["name"]).strip()
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+        if sanitized != raw_name or not sanitized:
+            print(f"[{rel_path}] ERROR: Invalid module name '{raw_name}'")
+            sys.exit(1)
+        result["name"] = sanitized
+        if "preferred_port" in fm:
+            try:
+                result["preferred_port"] = int(fm["preferred_port"])
+            except (ValueError, TypeError):
+                pass
+        if "advertise_ip" in fm:
+            result["advertise_ip"] = str(fm["advertise_ip"])
+        # max_connections（弹性连接上限）
+        try:
+            result["max_connections"] = max(1, min(10, int(fm.get("max_connections", 1))))
+        except (ValueError, TypeError):
+            result["max_connections"] = 1
+    except SystemExit:
+        raise
+    except Exception as e:
+        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
+        sys.exit(1)
+    return result
+
+_module_config = _load_module_config()
+MODULE_NAME = _module_config["name"]
+PREFERRED_PORT = _module_config["preferred_port"]
+ADVERTISE_IP = _module_config["advertise_ip"]
+
+
+# ── Safe stdout/stderr ──
+
+class _SafeWriter:
+    def __init__(self, stream):
+        self._stream = stream
+    def write(self, s):
+        try:
+            self._stream.write(s)
+        except (BrokenPipeError, OSError):
+            pass
+    def flush(self):
+        try:
+            self._stream.flush()
+        except (BrokenPipeError, OSError):
+            pass
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+sys.stdout = _SafeWriter(sys.stdout)
+sys.stderr = _SafeWriter(sys.stderr)
+
+
+# ── Timestamped print + log file writer ──
+
+_builtin_print = builtins.print
+_start_ts = time.monotonic()
+_last_ts = time.monotonic()
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+_log_lock = threading.Lock()
+_log_latest_path = None
+_log_daily_path = None
+_log_daily_date = ""
+_log_dir = None
+_crash_log_path = None
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+def _resolve_daily_log_path():
+    global _log_daily_path, _log_daily_date
+    if not _log_dir:
+        return
+    today = datetime.now().strftime("%Y-%m-%d")
+    if today == _log_daily_date and _log_daily_path:
+        return
+    month_dir = os.path.join(_log_dir, today[:7])
+    os.makedirs(month_dir, exist_ok=True)
+    _log_daily_path = os.path.join(month_dir, f"{today}.log")
+    _log_daily_date = today
+
+def _write_log(plain_line: str):
+    with _log_lock:
+        if _log_latest_path:
+            try:
+                with open(_log_latest_path, "a", encoding="utf-8") as f:
+                    f.write(plain_line)
+            except Exception:
+                pass
+        _resolve_daily_log_path()
+        if _log_daily_path:
+            try:
+                with open(_log_daily_path, "a", encoding="utf-8") as f:
+                    f.write(plain_line)
+            except Exception:
+                pass
+
+def _write_crash(exc_type, exc_value, exc_tb, thread_name=None, severity="critical", handled=False):
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "module": MODULE_NAME,
+        "thread": thread_name or threading.current_thread().name,
+        "exception_type": exc_type.__name__ if exc_type else "Unknown",
+        "exception_message": str(exc_value),
+        "traceback": "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
+        "severity": severity, "handled": handled,
+        "process_id": os.getpid(), "platform": sys.platform,
+        "runtime_version": f"Python {sys.version.split()[0]}",
+    }
+    if exc_tb:
+        tb_entries = traceback.extract_tb(exc_tb)
+        if tb_entries:
+            last = tb_entries[-1]
+            record["context"] = {"function": last.name, "file": os.path.basename(last.filename), "line": last.lineno}
+    line = json.dumps(record, ensure_ascii=False) + "\n"
+    if _crash_log_path:
+        try:
+            with open(_crash_log_path, "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+    if _log_dir:
+        try:
+            today = datetime.now().strftime("%Y-%m-%d")
+            archive_dir = os.path.join(_log_dir, "crashes", today[:7])
+            os.makedirs(archive_dir, exist_ok=True)
+            with open(os.path.join(archive_dir, f"{today}.jsonl"), "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+
+def _setup_exception_hooks():
+    _orig = sys.excepthook
+    def _excepthook(exc_type, exc_value, exc_tb):
+        _write_crash(exc_type, exc_value, exc_tb, severity="critical", handled=False)
+        _orig(exc_type, exc_value, exc_tb)
+    sys.excepthook = _excepthook
+    if hasattr(threading, "excepthook"):
+        def _thread_excepthook(args):
+            _write_crash(args.exc_type, args.exc_value, args.exc_traceback,
+                        thread_name=args.thread.name if args.thread else "unknown",
+                        severity="error", handled=False)
+        threading.excepthook = _thread_excepthook
+
+def _tprint(*args, **kwargs):
+    global _last_ts
+    now = time.monotonic()
+    elapsed = now - _start_ts
+    delta = now - _last_ts
+    _last_ts = now
+    elapsed_str = f"{elapsed*1000:.0f}ms" if elapsed < 1 else (f"{elapsed:.1f}s" if elapsed < 100 else f"{elapsed:.0f}s")
+    delta_str = "" if delta < 0.001 else (f"+{delta*1000:.0f}ms" if delta < 1 else (f"+{delta:.1f}s" if delta < 100 else f"+{delta:.0f}s"))
+    _builtin_print(*args, **kwargs)
+    if _log_latest_path or _log_daily_path:
+        sep = kwargs.get("sep", " ")
+        end = kwargs.get("end", "\n")
+        text = sep.join(str(a) for a in args)
+        ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+        prefix = f"[{elapsed_str:>6}] {ts} {delta_str:>8} "
+        _write_log(prefix + _strip_ansi(text) + end)
+
+builtins.print = _tprint
+
+_project_root = os.environ.get("KITE_PROJECT") or os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+if _project_root not in sys.path:
+    sys.path.insert(0, _project_root)
+
+
+def _fmt_elapsed(t0: float) -> str:
+    d = time.monotonic() - t0
+    if d < 1: return f"{d*1000:.0f}ms"
+    if d < 10: return f"{d:.1f}s"
+    return f"{d:.0f}s"
+
+
+def _read_stdin_kite_message(expected_type: str, timeout: float = 10) -> dict | None:
+    result = [None]
+    def _read():
+        try:
+            line = sys.stdin.readline().strip()
+            if line:
+                msg = json.loads(line)
+                if isinstance(msg, dict) and msg.get("kite") == expected_type:
+                    result[0] = msg
+        except Exception:
+            pass
+    t = threading.Thread(target=_read, daemon=True)
+    t.start()
+    t.join(timeout=timeout)
+    return result[0]
+
+
+# ── Global state ──
+
+_ws_global = None
+_shutting_down = False
+_exit_code = 0
+_gateway_ws_server = None
+_pending_rpc: dict[str, asyncio.Future] = {}  # id -> Future for RPC responses
+
+_has_registered = False
+
+# 弹性多连接
+_extra_ws: dict = {}           # slot → WebSocket（附加连接）
+_extra_ws_tasks: dict = {}     # slot → recv loop Task
+_kernel_port_cached = ""       # 缓存 kernel_port，供 offer handler 使用
+
+
+# ── RPC call with response awaiting ──
+
+async def _rpc_call(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()
+    _pending_rpc[rpc_id] = future
+    await ws.send(json.dumps(msg))
+    try:
+        return await asyncio.wait_for(future, timeout=timeout)
+    except asyncio.TimeoutError:
+        _pending_rpc.pop(rpc_id, None)
+        return {"error": {"code": -32000, "message": f"RPC timeout: {method} ({timeout}s)"}}
+
+
+async def _rpc_call_await(method: str, params: dict = None, timeout: float = 10) -> dict:
+    """RPC call that waits for response. Used by ws_server to call Auth/Launcher.
+    Returns unwrapped result dict; raises on error."""
+    if not _ws_global:
+        raise Exception("Not connected to Kernel")
+    rpc_id = str(uuid.uuid4())
+    msg = {"jsonrpc": "2.0", "id": rpc_id, "method": method}
+    if params:
+        msg["params"] = params
+
+    fut = asyncio.get_event_loop().create_future()
+    _pending_rpc[rpc_id] = fut
+    try:
+        await _ws_global.send(json.dumps(msg))
+        resp = await asyncio.wait_for(fut, timeout=timeout)
+        # _handle_rpc_response sets the whole message; extract result or raise
+        if "error" in resp:
+            err = resp["error"]
+            raise Exception(f"[{err.get('code', -32603)}] {err.get('message', 'RPC error')}")
+        return resp.get("result", {})
+    except asyncio.TimeoutError:
+        print(f"[gateway] RPC timeout: {method} (id={rpc_id[:8]}..., timeout={timeout}s)")
+        raise
+    finally:
+        _pending_rpc.pop(rpc_id, None)
+
+
+def _handle_rpc_response(msg: dict):
+    """处理 RPC 响应，resolve 对应的 pending future。"""
+    rpc_id = msg.get("id")
+    future = _pending_rpc.pop(rpc_id, None)
+    if future and not future.done():
+        future.set_result(msg)
+
+
+async def _do_init(ws):
+    """收到 system.require_init 后执行：subscribe + register + module.ready"""
+    global _has_registered, _gateway_ws_server
+    reason = "startup" if not _has_registered else "recovery"
+    print(f"[gateway] Received system.require_init (reason={reason})")
+
+    # 1. Subscribe
+    await _rpc_call(ws, "event.subscribe", {
+        "events": ["module.ready", "module.shutdown", "auth.token.revoked"],
+    }, wait_response=False)
+    print(f"[gateway] Subscribed to events")
+
+    # 2. Start WS server BEFORE register (need actual port for registration)
+    if _gateway_ws_server is None:
+        from ws_server import GatewayWSServer
+        listen_port = int(os.environ.get("KITE_MODULE_PORT", "0")) or PREFERRED_PORT
+        _gateway_ws_server = GatewayWSServer(
+            host="0.0.0.0",
+            port=listen_port,
+            kernel_port=_kernel_port_cached,
+            rpc_call_fn=_rpc_call_await,
+            publish_event_fn=_publish_event_global,
+        )
+        await _gateway_ws_server.start()
+        print(f"[gateway] WS server started on port {listen_port}")
+    else:
+        listen_port = _gateway_ws_server.port
+
+    # 3. Register with endpoint info
+    await _rpc_call(ws, "registry.register", {
+        "module_id": "gateway",
+        "module_type": "service",
+        "launcher_id": "launcher",
+        "base_url": f"ws://{ADVERTISE_IP}:{listen_port}",
+        "display": {
+            "urls": {
+                "Gateway WS": f"ws://127.0.0.1:{listen_port}",
+            }
+        },
+        "tools": {
+            "rpc": {
+                "module": {
+                    "health": {"method": "health", "description": "健康检查"},
+                    "status": {"method": "status", "description": "状态查询"},
+                }
+            }
+        },
+        "events_publish": {},
+        "events_subscribe": ["module.ready", "module.shutdown", "auth.token.revoked"],
+    }, wait_response=False)
+    print(f"[gateway] Registered to Kernel")
+
+    # 4. module.ready
+    if not _shutting_down:
+        await _publish_event(ws, "module.ready", {
+            "module_id": "gateway",
+            "graceful_shutdown": True,
+            "startup_time": time.monotonic() - _start_ts,
+            "reason": reason,
+        })
+        print(f"[gateway] module.ready published (reason={reason})")
+
+    _has_registered = True
+
+
+async def _publish_event(ws, event: str, data: dict = None):
+    """发布事件到 Kernel（fire-and-forget）。"""
+    await _rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": event,
+        "data": data or {},
+    }, wait_response=False)
+
+
+async def _publish_event_global(event: str, data: dict = None):
+    """供 ws_server 使用的事件发布。"""
+    if _ws_global:
+        await _publish_event(_ws_global, event, data)
+
+
+# ── Event + RPC handlers ──
+
+async def _handle_ping_event(data: dict):
+    if _ws_global:
+        await _publish_event(_ws_global, "system.pong", {
+            "module_id": MODULE_NAME, "ping_time": data.get("ping_time"), "pong_time": time.time(),
+        })
+
+
+async def _handle_event_notification(msg: dict):
+    params = msg.get("params", {})
+    event_type = params.get("event", "")
+    data = params.get("data", {})
+
+    if event_type == "system.ping":
+        await _handle_ping_event(data)
+        return
+
+    # 弹性连接 offer/release
+    if event_type == "system.connection.offer":
+        asyncio.create_task(_handle_connection_offer(data))
+        return
+    if event_type == "system.connection.release":
+        asyncio.create_task(_handle_connection_release(data))
+        return
+
+    if event_type == "module.shutdown":
+        target = data.get("module_id", "")
+        reason = data.get("reason", "")
+        if target == "gateway" or not target or reason == "launcher_lost":
+            await _handle_shutdown()
+            return
+
+    # auth.token.revoked → 踢掉对应会话
+    if event_type == "auth.token.revoked" and _gateway_ws_server:
+        token_prefix = data.get("token_prefix", "")
+        if token_prefix:
+            _gateway_ws_server.remove_session_by_token_prefix(token_prefix)
+        return
+
+    if event_type in SYSTEM_BROADCAST_EVENTS:
+        return
+
+
+async def _handle_rpc_request(ws, msg: dict):
+    rpc_id = msg.get("id", "")
+    method = msg.get("method", "")
+    params = msg.get("params", {})
+
+    handlers = {
+        "health": lambda p: _rpc_health(),
+        "status": lambda p: _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() -> dict:
+    sessions = len(_gateway_ws_server._sessions) if _gateway_ws_server else 0
+    return {"status": "healthy", "details": {"uptime_seconds": round(time.monotonic() - _start_ts), "active_sessions": sessions}}
+
+
+async def _rpc_status() -> dict:
+    sessions = len(_gateway_ws_server._sessions) if _gateway_ws_server else 0
+    return {"module": "gateway", "status": "running", "uptime_seconds": round(time.monotonic() - _start_ts), "active_sessions": sessions}
+
+
+# ── WebSocket connection + message loop ──
+
+def _print_crash_summary_sync(exc_type, exc_tb, thread_name=None):
+    """Print crash summary to console (red highlight)."""
+    RED = "\033[91m"
+    RESET = "\033[0m"
+    if exc_tb:
+        tb_entries = traceback.extract_tb(exc_tb)
+        if tb_entries:
+            last = tb_entries[-1]
+            location = f"{os.path.basename(last.filename)}:{last.lineno}"
+        else:
+            location = "unknown"
+    else:
+        location = "unknown"
+    prefix = f"[{MODULE_NAME}]"
+    if thread_name:
+        _builtin_print(f"{prefix} {RED}线程 {thread_name} 崩溃: {exc_type.__name__} in {location}{RESET}")
+    else:
+        _builtin_print(f"{prefix} {RED}崩溃: {exc_type.__name__} in {location}{RESET}")
+    if _crash_log_path:
+        _builtin_print(f"{prefix} 崩溃日志: {_crash_log_path}")
+
+
+async def _ws_loop(token: str, kernel_port: int, _t0: float):
+    global _shutting_down, _exit_code
+    retry_delay = 0.5
+    max_delay = 10.0
+    attempt = 0
+    cooldown_attempts = 0
+    conn_refused_count = 0
+
+    while not _shutting_down:
+        try:
+            await _ws_connect(token, kernel_port, _t0)
+            retry_delay = 0.5
+            attempt = 0
+            cooldown_attempts = 0
+            conn_refused_count = 0
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            if _shutting_down:
+                return
+            code = _get_close_code(e)
+            if code in (4001, 4003, 4004, 1008, 4010):
+                print(f"[gateway] 致命错误 (code {code})，退出")
+                _exit_code = 1
+                _shutting_down = True
+                return
+            if code == 4020:
+                cooldown_attempts += 1
+                if cooldown_attempts >= 5:
+                    print(f"[gateway] 速率限制重试 5 次，退出")
+                    _exit_code = 1
+                    _shutting_down = True
+                    return
+                print(f"[gateway] 速率限制，10s 后重试 ({cooldown_attempts}/5)")
+                await asyncio.sleep(10.0)
+                continue
+
+            # 连接被拒绝/重置 — Kernel 可能正在关闭
+            # Windows 的 [WinError 1225] 是 OSError 不是 ConnectionRefusedError
+            _is_conn_refused = isinstance(e, (ConnectionRefusedError, ConnectionResetError))
+            if not _is_conn_refused and isinstance(e, OSError) and getattr(e, 'winerror', None) == 1225:
+                _is_conn_refused = True
+            if _is_conn_refused:
+                conn_refused_count += 1
+                if conn_refused_count >= 3:
+                    print(f"[gateway] Kernel 持续不可达 ({conn_refused_count} 次)，正常退出")
+                    _exit_code = 0
+                    _shutting_down = True
+                    return
+                jitter = retry_delay * 0.2 * random.random()
+                sleep_time = retry_delay + jitter
+                print(f"[gateway] Kernel 连接失败: {type(e).__name__}, {sleep_time:.1f}s 后重试 ({conn_refused_count}/3)")
+            else:
+                conn_refused_count = 0
+                attempt += 1
+                jitter = retry_delay * 0.2 * random.random()
+                sleep_time = retry_delay + jitter
+                _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
+                print(f"[gateway] 连接错误: {e}, {sleep_time:.1f}s 后重试 (attempt {attempt})")
+                if attempt >= 10:
+                    print(f"[gateway] 连续 {attempt} 次连接失败，正常退出")
+                    _exit_code = 0
+                    _shutting_down = True
+                    return
+
+        _ws_global_clear()
+        if _shutting_down:
+            return
+        await asyncio.sleep(sleep_time if 'sleep_time' in locals() else retry_delay)
+        retry_delay = min(retry_delay * 2, max_delay)
+
+
+def _get_close_code(e: Exception) -> int:
+    if hasattr(e, 'rcvd') and e.rcvd is not None:
+        return getattr(e.rcvd, 'code', 0)
+    return 0
+
+
+def _ws_global_clear():
+    global _ws_global
+    _ws_global = None
+    # 清理所有 pending RPC futures
+    for fut in _pending_rpc.values():
+        if not fut.done():
+            fut.set_exception(Exception("Connection lost"))
+    _pending_rpc.clear()
+
+
+async def _ws_connect(token: str, kernel_port: int, _t0: float):
+    global _ws_global, _gateway_ws_server, _kernel_port_cached
+    _kernel_port_cached = kernel_port
+
+    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?id=gateway"
+    print(f"[gateway] Connecting to Kernel: {ws_url}")
+
+    async with websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=10) as ws:
+        # Auth
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0", "id": "auth", "method": "auth",
+            "params": {"token": token}
+        }))
+        auth_resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5))
+        if "error" in auth_resp:
+            raise Exception(f"Auth failed: {auth_resp['error']}")
+
+        _ws_global = ws
+        print(f"[gateway] Connected to Kernel ({_fmt_elapsed(_t0)})")
+
+        # Message loop — wait for system.require_init to trigger _do_init
+        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 = "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(_do_init(ws))
+                        continue
+                    asyncio.create_task(_handle_event_notification(msg))
+                elif has_method and has_id:
+                    asyncio.create_task(_handle_rpc_request(ws, msg))
+                elif has_id and has_result:
+                    _handle_rpc_response(msg)
+            except Exception as e:
+                print(f"[gateway] 消息处理异常（已忽略）: {e}")
+
+
+async def _handle_connection_offer(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 _extra_ws:
+            continue
+        asyncio.create_task(_connect_slot(slot, token))
+
+
+async def _connect_slot(slot, token):
+    """建立单个 slot 附加连接。"""
+    ws_url = f"ws://127.0.0.1:{_kernel_port_cached}/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
+        _extra_ws[slot] = ws
+        _extra_ws_tasks[slot] = asyncio.create_task(_slot_recv_loop(slot, ws))
+        print(f"[gateway] Slot {slot} connected")
+    except Exception as e:
+        print(f"[gateway] Slot {slot} connect failed: {e}")
+
+
+async def _slot_recv_loop(slot, ws):
+    """附加连接的接收循环：与主连接平等处理所有消息。"""
+    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 = "result" in msg or "error" in msg
+
+                if has_method and not has_id:
+                    asyncio.create_task(_handle_event_notification(msg))
+                elif has_method and has_id:
+                    asyncio.create_task(_handle_rpc_request(ws, msg))
+                elif has_id and has_result:
+                    _handle_rpc_response(msg)
+            except Exception as e:
+                print(f"[gateway] Slot {slot} 消息处理异常（已忽略）: {e}")
+    except Exception as e:
+        print(f"[gateway] Slot {slot} 接收循环异常: {e}")
+    finally:
+        _extra_ws.pop(slot, None)
+        _extra_ws_tasks.pop(slot, None)
+
+
+async def _handle_connection_release(data):
+    """Kernel 请求释放 slot，优雅关闭。"""
+    for slot in data.get("slots", []):
+        ws = _extra_ws.pop(slot, None)
+        task = _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():
+    global _shutting_down
+    print("[gateway] Received shutdown request")
+    _shutting_down = True
+
+    # 停止 WS 服务器
+    if _gateway_ws_server:
+        await _gateway_ws_server.stop()
+
+    # 关闭所有附加连接
+    for _s, _w in list(_extra_ws.items()):
+        try:
+            await _w.close(code=1000, reason="shutdown")
+        except Exception:
+            pass
+    for _t in _extra_ws_tasks.values():
+        _t.cancel()
+    _extra_ws.clear()
+    _extra_ws_tasks.clear()
+
+    await _publish_event(_ws_global, "module.shutdown.ack", {"module_id": "gateway"})
+    await _publish_event(_ws_global, "module.exiting", {
+        "module_id": "gateway", "type": "passive",
+        "reason": "shutdown_requested", "restart": "auto",
+        "action": "none", "timeout": 5.0, "restart_delay": 0.0,
+    })
+    await _publish_event(_ws_global, "module.shutdown.ready", {"module_id": "gateway"})
+    print("[gateway] Shutdown ready, exiting")
+    await asyncio.sleep(0.1)
+    if _ws_global:
+        try:
+            await _ws_global.close(code=1000, reason="Graceful shutdown")
+        except Exception:
+            pass
+
+
+# ── Startup ──
+
+def _init_logs(log_base_dir: str = None, suffix: str = ""):
+    """初始化日志系统（本地/远程共用）。"""
+    global _log_dir, _log_latest_path, _crash_log_path
+
+    if log_base_dir:
+        _log_dir = os.path.join(log_base_dir, "log")
+        os.makedirs(_log_dir, exist_ok=True)
+        _log_latest_path = os.path.join(_log_dir, f"latest{suffix}.log")
+        try:
+            with open(_log_latest_path, "w", encoding="utf-8") as f: pass
+        except Exception: _log_latest_path = None
+        _crash_log_path = os.path.join(_log_dir, f"crashes{suffix}.jsonl")
+        try:
+            with open(_crash_log_path, "w", encoding="utf-8") as f: pass
+        except Exception: _crash_log_path = None
+        _resolve_daily_log_path()
+
+    _setup_exception_hooks()
+
+
+def _run_local_mode(kernel_port: int):
+    """本地模式：从 stdin 读 boot_info，连接 Kernel。"""
+    module_data = os.environ.get("KITE_MODULE_DATA")
+    suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
+    _init_logs(log_base_dir=module_data, suffix=suffix)
+
+    _t0 = time.monotonic()
+    line = sys.stdin.readline().strip()
+    if not line:
+        print(f"[{MODULE_NAME}] ERROR: stdin closed"); sys.exit(1)
+    try: msg = json.loads(line)
+    except json.JSONDecodeError as e:
+        print(f"[{MODULE_NAME}] ERROR: Invalid JSON: {e}"); sys.exit(1)
+    if "error" in msg:
+        print(f"[{MODULE_NAME}] 启动失败: {msg.get('message')}"); sys.exit(1)
+    token = msg.get("token", "")
+    if not token:
+        print(f"[{MODULE_NAME}] ERROR: No token"); sys.exit(1)
+
+    print(f"[{MODULE_NAME}] Local mode: port={kernel_port}")
+    try:
+        asyncio.run(_ws_loop(token, kernel_port, _t0))
+    except (ConnectionRefusedError, ConnectionResetError, OSError) as e:
+        if isinstance(e, OSError) and getattr(e, 'winerror', None) != 1225 and not isinstance(e, (ConnectionRefusedError, ConnectionResetError)):
+            raise
+        print(f"[{MODULE_NAME}] Kernel 不可达，正常退出")
+        sys.exit(0)
+    except Exception as e:
+        _write_crash(type(e), e, e.__traceback__, severity="critical", handled=True)
+        _print_crash_summary_sync(type(e), e.__traceback__)
+        sys.exit(1)
+    sys.exit(_exit_code)
+
+
+def _run_remote_mode(gateway_url: str):
+    """远程模式：通过 Gateway 连接 Kernel。"""
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    data_dir = os.path.join(home, ".kite", "remote", MODULE_NAME)
+    os.makedirs(data_dir, exist_ok=True)
+    _init_logs(log_base_dir=data_dir)
+
+    _t0 = time.monotonic()
+    kite_token = _get_kite_token(MODULE_NAME, gateway_url)
+    print(f"[{MODULE_NAME}] Remote mode: gateway={gateway_url}")
+
+    try:
+        asyncio.run(_remote_ws_loop(gateway_url, kite_token, _t0))
+    except Exception as e:
+        _write_crash(type(e), e, e.__traceback__, severity="critical", handled=True)
+        _print_crash_summary_sync(type(e), e.__traceback__)
+        sys.exit(1)
+    sys.exit(_exit_code)
+
+
+async def _remote_ws_loop(gateway_url: str, kite_token: str, _t0: float):
+    """远程模式重连循环。"""
+    global _shutting_down, _exit_code
+    retry_delay = 0.5
+    max_delay = 10.0
+
+    while not _shutting_down:
+        try:
+            await _remote_connect(gateway_url, kite_token, _t0)
+            retry_delay = 0.5
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            if _shutting_down: return
+            _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
+            jitter = retry_delay * 0.2 * random.random()
+            print(f"[{MODULE_NAME}] 远程连接错误: {e}, {retry_delay + jitter:.1f}s 后重试")
+            await asyncio.sleep(retry_delay + jitter)
+            retry_delay = min(retry_delay * 2, max_delay)
+
+        _ws_global_clear()
+        if _shutting_down: return
+
+
+async def _remote_connect(gateway_url: str, kite_token: str, _t0: float):
+    """远程模式：连接 Gateway 并走认证+注册+启动 WS 服务器流程。"""
+    global _ws_global, _gateway_ws_server
+
+    print(f"[{MODULE_NAME}] Connecting to Gateway: {gateway_url}")
+    async with websockets.connect(gateway_url, open_timeout=10, ping_interval=None, close_timeout=10) as ws:
+        # 1. 接收 challenge
+        challenge = json.loads(await asyncio.wait_for(ws.recv(), timeout=10))
+        nonce = challenge.get("params", {}).get("nonce", "")
+
+        # 2. 发送 auth.connect
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0", "id": "auth-connect",
+            "method": "auth.connect",
+            "params": {
+                "nonce": nonce,
+                "module_id": MODULE_NAME,
+                "auth": {"method": "kite_token", "token": kite_token},
+                "client": {"type": "module"}
+            }
+        }))
+
+        # 3. 等待认证响应
+        resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=10))
+        if "error" in resp:
+            error = resp["error"]
+            code = error.get("code", 0)
+            if code in (4001, 4010, 4011):
+                _clear_token_cache(MODULE_NAME, gateway_url)
+                print(f"[{MODULE_NAME}] Token 无效，请重新配对")
+                sys.exit(1)
+            raise Exception(f"Gateway 认证失败: {error}")
+
+        _ws_global = ws
+        print(f"[{MODULE_NAME}] Connected via Gateway ({_fmt_elapsed(_t0)})")
+
+        # Message loop — wait for system.require_init to trigger _do_init
+        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 = "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(_do_init(ws))
+                        continue
+                    asyncio.create_task(_handle_event_notification(msg))
+                elif has_method and has_id:
+                    asyncio.create_task(_handle_rpc_request(ws, msg))
+                elif has_id and has_result:
+                    _handle_rpc_response(msg)
+            except Exception as e:
+                print(f"[{MODULE_NAME}] 消息处理异常: {e}")
+
+
+# ── Token 管理（远程模式）──
+
+def _gateway_to_filename(gateway_url: str) -> str:
+    try:
+        from urllib.parse import urlparse
+        parsed = urlparse(gateway_url)
+        host = parsed.hostname or "unknown"
+        port = parsed.port or (443 if parsed.scheme == "wss" else 80)
+        return f"{host}-{port}.json".replace(":", "-").replace("/", "-")
+    except Exception: return "default.json"
+
+def _load_token_cache(module_name: str, gateway_url: str) -> dict | None:
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    token_file = os.path.join(home, ".kite", "remote", module_name, "tokens", _gateway_to_filename(gateway_url))
+    if not os.path.exists(token_file): return None
+    try:
+        with open(token_file, "r") as f: return json.load(f)
+    except Exception: return None
+
+def _clear_token_cache(module_name: str, gateway_url: str):
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    token_file = os.path.join(home, ".kite", "remote", module_name, "tokens", _gateway_to_filename(gateway_url))
+    try: os.remove(token_file)
+    except Exception: pass
+
+def _get_kite_token(module_name: str, gateway_url: str) -> str:
+    token = os.environ.get("KITE_TOKEN")
+    if token: return token
+    cache = _load_token_cache(module_name, gateway_url)
+    if cache: return cache["token"]
+    print(f"[{module_name}] No token for {gateway_url}")
+    print(f"  export KITE_TOKEN=<token>")
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    kernel_port = os.environ.get("KITE_KERNEL_PORT")
+    if kernel_port:
+        _run_local_mode(int(kernel_port))
+    else:
+        config = _load_module_config()
+        gateway_url = config.get("gateway_url") or os.environ.get("KITE_GATEWAY_URL")
+        if gateway_url:
+            _run_remote_mode(gateway_url)
+        else:
+            print(f"[{MODULE_NAME}] ERROR: No KITE_KERNEL_PORT and no gateway_url")
+            sys.exit(1)