@agentunion/kite 1.5.0 → 1.6.1

package/extensions/services/redis/entry.py

@@ -0,0 +1,1509 @@
+"""
+Redis entry point.
+Reads boot_info from stdin, registers to Registry, starts Redis service.
+"""
+
+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 (received by all modules, may not need handling)
+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",
+}
+
+
+# ── Safe stdout/stderr: ignore BrokenPipeError after Launcher closes stdio ──
+
+
+# ── Module configuration ──
+
+def _load_module_config() -> dict:
+    """Load module configuration from module.md frontmatter.
+
+    Returns:
+        Dict with keys: name, preferred_port, advertise_ip
+
+    Raises:
+        SystemExit: If module.md is invalid or name is non-compliant
+    """
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+
+    # Calculate relative path for error messages
+    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
+
+    # Default values (will be overridden if valid config exists)
+    result = {
+        "name": "",
+        "preferred_port": 0,
+        "advertise_ip": "0.0.0.0"
+    }
+
+    # Check if module.md exists
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+        print(f"  Path: {rel_path}/module.md")
+        print(f"  Reason: File not found")
+        sys.exit(1)
+
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+
+        # Extract YAML frontmatter (between --- markers)
+        import re
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing YAML frontmatter")
+            sys.exit(1)
+
+        # Parse YAML frontmatter
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
+            sys.exit(1)
+        except Exception as e:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: YAML parse error: {e}")
+            sys.exit(1)
+
+        # Validate 'name' field (required)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing 'name' field")
+            sys.exit(1)
+
+        raw_name = str(fm["name"]).strip()
+
+        if not raw_name:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Empty module name")
+            sys.exit(1)
+
+        # Validate name characters
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+
+        if sanitized != raw_name:
+            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
+            sys.exit(1)
+
+        result["name"] = sanitized
+
+        # Extract optional fields
+        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
+
+        # business_config（从 businesses 数组取）
+        if "businesses" in fm:
+            businesses = fm["businesses"]
+            if isinstance(businesses, list) and businesses:
+                config_file = businesses[0].get("config_file") if isinstance(businesses[0], dict) else None
+                if config_file:
+                    result["business_config"] = str(config_file).strip()
+
+    except SystemExit:
+        raise  # Re-raise exit to prevent catching by outer except
+    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"]
+
+
+class _SafeWriter:
+    """Wraps a stream to silently swallow BrokenPipeError on write/flush."""
+    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 ──
+# Independent implementation per module (no shared code dependency)
+
+_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():
+    """Resolve daily log path based on current date."""
+    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):
+    """Write a plain-text line to both latest.log and daily log."""
+    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):
+    """Write crash record to crashes.jsonl + daily crash archive."""
+    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)
+            archive_path = os.path.join(archive_dir, f"{today}.jsonl")
+            with open(archive_path, "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+
+def _print_crash_summary(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} 崩溃: "
+                       f"{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}")
+
+def _setup_exception_hooks():
+    """Set up global exception hooks."""
+    _orig_excepthook = sys.excepthook
+
+    def _excepthook(exc_type, exc_value, exc_tb):
+        _write_crash(exc_type, exc_value, exc_tb, severity="critical", handled=False)
+        _print_crash_summary(exc_type, exc_tb)
+        _orig_excepthook(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)
+            _print_crash_summary(args.exc_type, args.exc_traceback,
+                                thread_name=args.thread.name if args.thread else None)
+
+        threading.excepthook = _thread_excepthook
+
+def _tprint(*args, **kwargs):
+    """Timestamped print that adds [timestamp] HH:MM:SS.mmm +delta prefix."""
+    global _last_ts
+    now = time.monotonic()
+    elapsed = now - _start_ts
+    delta = now - _last_ts
+    _last_ts = now
+
+    if elapsed < 1:
+        elapsed_str = f"{elapsed * 1000:.0f}ms"
+    elif elapsed < 100:
+        elapsed_str = f"{elapsed:.1f}s"
+    else:
+        elapsed_str = f"{elapsed:.0f}s"
+
+    if delta < 0.001:
+        delta_str = ""
+    elif delta < 1:
+        delta_str = f"+{delta * 1000:.0f}ms"
+    elif delta < 100:
+        delta_str = f"+{delta:.1f}s"
+    else:
+        delta_str = f"+{delta:.0f}s"
+
+    ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+
+    _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)
+        prefix = f"[{elapsed_str:>6}] {ts} {delta_str:>8} "
+        _write_log(prefix + _strip_ansi(text) + end)
+
+builtins.print = _tprint
+
+# Ensure project root is on sys.path (set by main.py or cli.js)
+_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:
+    """Read a single kite message of expected type from stdin with timeout."""
+    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 WS reference for publish_event callback
+_ws_global = None
+_shutting_down = False
+_exit_code = 0  # Exit code for main() to use
+
+# 弹性多连接
+_extra_ws: dict = {}           # slot → WebSocket（附加连接）
+_extra_ws_tasks: dict = {}     # slot → recv loop Task
+_kernel_port = ""              # 缓存 kernel_port，供 offer handler 使用
+_pending_rpc: dict[str, asyncio.Future] = {}  # rpc_id → Future（等待响应）
+
+_has_registered = False
+
+# Redis 特有
+_redis_impl = None  # Redis 实现实例（外部或内置）
+_redis_ready = False
+
+
+def _is_auth_failure(e: Exception) -> bool:
+    """Check if a WebSocket exception indicates authentication failure."""
+    if hasattr(e, 'rcvd') and e.rcvd is not None:
+        code = e.rcvd.code if hasattr(e.rcvd, 'code') else 0
+        return code in (4001, 4003)
+    return False
+
+
+async def main():
+    global _ws_global, _shutting_down
+    if _startup_config.get("mode") == "remote":
+        await _remote_mode_loop(_startup_config["gateway_url"], _startup_config["kite_token"], _startup_config["t0"])
+    else:
+        await _ws_loop(_startup_config["token"], _startup_config["kernel_port"], _startup_config["t0"])
+
+
+async def _ws_loop(token: str, kernel_port: int, _t0: float):
+    """Connect to Kernel with exponential backoff reconnection."""
+    global _shutting_down, _exit_code
+    retry_delay = 0.5
+    max_delay = 10.0
+    attempt = 0
+    cooldown_attempts = 0
+
+    while not _shutting_down:
+        try:
+            await _ws_connect(token, kernel_port, _t0)
+            retry_delay = 0.5
+            attempt = 0
+            cooldown_attempts = 0
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            if _shutting_down:
+                return
+
+            code = _get_close_code(e)
+
+            # never: 永不重连
+            if code in (4001, 4003, 4004, 1008, 4010):
+                print(f"[redis] 致命错误 (code {code})，退出")
+                _exit_code = 1
+                _shutting_down = True
+                return
+
+            # cooldown: 速率限制
+            if code == 4020:
+                cooldown_attempts += 1
+                if cooldown_attempts >= 5:
+                    print(f"[redis] 速率限制重试 5 次，退出")
+                    _exit_code = 1
+                    _shutting_down = True
+                    return
+                print(f"[redis] 速率限制，10.0s 后重试 ({cooldown_attempts}/5)")
+                await asyncio.sleep(10.0)
+                continue
+
+            # standard: 指数退避 + jitter
+            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"[redis] 连接错误: {e}, {sleep_time:.1f}s 后重试 (attempt {attempt})")
+
+        _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:
+    """从 websockets 异常中提取关闭码"""
+    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
+
+
+async def _do_init(ws):
+    """收到 system.require_init 后执行：启动 Redis → subscribe + register + module.ready"""
+    global _has_registered, _redis_impl, _redis_ready
+    reason = "startup" if not _has_registered else "recovery"
+    print(f"[redis] Received system.require_init (reason={reason})")
+
+    # 0. 启动 Redis 实现（如果还未启动）
+    if not _redis_impl:
+        await _start_redis_impl()
+
+    # 1. Subscribe to events
+    await _rpc_call(ws, "event.subscribe", {
+        "events": [
+            "system.ping",
+            "module.started",
+            "module.stopped",
+            "module.shutdown",
+        ],
+    })
+    print(f"[redis] Subscribed to events")
+
+    # 2. Register to Kernel Registry via RPC
+    registry_data = {
+        "module_id": "redis",
+        "module_type": "service",
+        "launcher_id": "launcher",
+        "tools": {
+            "rpc": {
+                "module": {
+                    "health": {"method": "health", "description": "健康检查"},
+                    "status": {"method": "status", "description": "状态查询"},
+                    "config": {
+                        "get": {"method": "get_settings", "description": "获取配置"},
+                        "update": {"method": "update_settings", "description": "更新配置"},
+                        "reset": {"method": "reset_settings", "description": "恢复默认配置"},
+                    }
+                },
+                "redis": {
+                    "ping": {"method": "ping", "description": "Ping Redis"},
+                    "get": {"method": "get", "description": "GET key"},
+                    "set": {"method": "set", "description": "SET key value"},
+                    "del": {"method": "del", "description": "DEL key"},
+                    "expire": {"method": "expire", "description": "EXPIRE key seconds"},
+                    "hget": {"method": "hget", "description": "HGET key field"},
+                    "hset": {"method": "hset", "description": "HSET key field value"},
+                    "hdel": {"method": "hdel", "description": "HDEL key field"},
+                    "hgetall": {"method": "hgetall", "description": "HGETALL key"},
+                    "sadd": {"method": "sadd", "description": "SADD key members"},
+                    "srem": {"method": "srem", "description": "SREM key members"},
+                    "smembers": {"method": "smembers", "description": "SMEMBERS key"},
+                    "publish": {"method": "publish", "description": "PUBLISH channel message"},
+                    "info": {"method": "info", "description": "Redis 连接信息"},
+                }
+            }
+        },
+        "events_publish": {
+            "system": {
+                "redis_ready": {"description": "Redis 服务已就绪"},
+            }
+        },
+        "events_subscribe": [
+            "module.started",
+            "module.stopped",
+            "module.shutdown",
+        ],
+    }
+
+    # 添加 Redis 连接信息（供模块直连）
+    if _redis_ready and _redis_impl:
+        registry_data["services"] = {
+            "redis": {
+                "host": _redis_impl.host,
+                "port": _redis_impl.port,
+                "protocol": "RESP",
+                "type": "external" if hasattr(_redis_impl, "_client") else "builtin",
+            }
+        }
+
+    await _rpc_call(ws, "registry.register", registry_data)
+    print(f"[redis] Registered to Kernel")
+
+    # 3. Publish module.ready
+    if not _shutting_down:
+        startup_time = time.monotonic() - _start_ts
+        await _publish_event(ws, "module.ready", {
+            "module_id": "redis",
+            "graceful_shutdown": True,
+            "startup_time": startup_time,
+            "reason": reason,
+        })
+        print(f"[redis] module.ready published (reason={reason})")
+
+    _has_registered = True
+
+    # Start test event loop in background
+    asyncio.create_task(_test_event_loop(ws))
+
+
+async def _start_redis_impl():
+    """启动 Redis 实现（外部或内置）"""
+    global _redis_impl, _redis_ready
+
+    # 从 module.md 读取业务配置文件名
+    config_file = _module_config.get("business_config")
+    config = {}
+    if config_file:
+        config_path = os.path.join(os.path.dirname(__file__), config_file)
+        if os.path.exists(config_path):
+            try:
+                import json5
+                with open(config_path, 'r', encoding='utf-8') as f:
+                    config = json5.load(f)
+            except Exception as e:
+                print(f"[redis] 配置文件读取失败: {e}")
+
+    redis_mode = config.get("redis_mode", "builtin")
+    redis_url = config.get("redis_url") or os.getenv("KITE_REDIS_URL")
+    allow_fallback = config.get("allow_fallback", True)
+    retry_initial = config.get("redis_retry_initial", 1.0)
+    retry_max = config.get("redis_retry_max", 30.0)
+
+    try:
+        if redis_mode == "external" and redis_url:
+            print(f"[redis] 尝试连接外部 Redis: {redis_url}")
+            from redis_external import ExternalRedis
+            redis_password = config.get("redis_password") or os.getenv("KITE_REDIS_PASSWORD") or None
+            _redis_impl = ExternalRedis(redis_url, password=redis_password, retry_initial=retry_initial, retry_max=retry_max)
+            # allow_fallback 时有限重试（5次），否则无限重试
+            max_attempts = 5 if allow_fallback else 0
+            await _redis_impl.start(max_attempts=max_attempts)
+            _redis_ready = True
+            GREEN = "\033[92m"
+            RESET = "\033[0m"
+            print(f"{GREEN}[redis] ✓ Redis 已就绪: 外部 Redis | {_redis_impl.host}:{_redis_impl.port}{RESET}")
+        else:
+            print(f"[redis] 使用内置 Redis")
+            from redis_builtin import BuiltinRedis
+            _redis_impl = BuiltinRedis()
+            await _redis_impl.start()
+            _redis_ready = True
+            GREEN = "\033[92m"
+            RESET = "\033[0m"
+            print(f"{GREEN}[redis] ✓ Redis 已就绪: 内置 Redis | {_redis_impl.host}:{_redis_impl.port}{RESET}")
+
+    except Exception as e:
+        if redis_mode == "external" and allow_fallback:
+            print(f"[redis] 外部 Redis 连接失败，降级到内置 Redis: {e}")
+            try:
+                from redis_builtin import BuiltinRedis
+                _redis_impl = BuiltinRedis()
+                await _redis_impl.start()
+                _redis_ready = True
+                YELLOW = "\033[93m"
+                RESET = "\033[0m"
+                print(f"{YELLOW}[redis] ⚠ Redis 已降级: 内置 Redis | {_redis_impl.host}:{_redis_impl.port}{RESET}")
+            except Exception as e2:
+                RED = "\033[91m"
+                RESET = "\033[0m"
+                print(f"{RED}[redis] ✗ Redis 启动失败: {e2}{RESET}")
+                _write_crash(type(e2), e2, e2.__traceback__, severity="error", handled=True)
+                sys.exit(1)
+        else:
+            RED = "\033[91m"
+            RESET = "\033[0m"
+            print(f"{RED}[redis] ✗ Redis 启动失败（不允许降级）: {e}{RESET}")
+            _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
+            sys.exit(1)
+
+    # 发布 system.redis_ready 事件
+    if _redis_ready and _redis_impl and _ws_global:
+        await _publish_event(_ws_global, "system.redis_ready", {
+            "host": _redis_impl.host,
+            "port": _redis_impl.port,
+            "protocol": "RESP",
+        })
+        print(f"[redis] Published system.redis_ready")
+
+
+async def _ws_connect(token: str, kernel_port: int, _t0: float):
+    """Single WebSocket session: connect → auth → start receiver → wait for system.require_init."""
+    global _ws_global, _kernel_port
+    _kernel_port = kernel_port
+
+    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?id=redis"
+    print(f"[redis] Connecting to Kernel: {ws_url}")
+
+    async with websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=10) as ws:
+        # Send auth message first
+        auth_req = {
+            "jsonrpc": "2.0",
+            "id": "auth",
+            "method": "auth",
+            "params": {"token": token}
+        }
+        await ws.send(json.dumps(auth_req))
+
+        # Wait for auth response
+        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']}")
+
+        _ws_global = ws
+        print(f"[redis] Connected to Kernel ({_fmt_elapsed(_t0)})")
+
+        # Start receiver task — wait for system.require_init to trigger _do_init
+        receiver_task = asyncio.create_task(_ws_receiver(ws))
+        try:
+            # Wait for receiver to finish (connection closed or error)
+            await receiver_task
+        finally:
+            receiver_task.cancel()
+            for fut in _pending_rpc.values():
+                if not fut.done():
+                    fut.set_result({"error": {"code": -32001, "message": "Connection lost"}})
+            _pending_rpc.clear()
+
+
+async def _ws_receiver(ws):
+    """Main connection receive loop: route events, RPC requests, and RPC responses.
+    Detects 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
+
+            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
+                # Event Notification — run in background to prevent deadlock
+                asyncio.create_task(_handle_event_notification(msg))
+            elif has_method and has_id:
+                # Incoming RPC request — run in background to prevent deadlock
+                asyncio.create_task(_handle_rpc_request(ws, msg))
+            elif not has_method and has_id:
+                _handle_rpc_response(msg)
+        except Exception as e:
+            print(f"[redis] 消息处理异常（已忽略）: {e}")
+
+
+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)"}}
+
+
+def _handle_rpc_response(msg: dict):
+    """Route JSON-RPC response to 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 _publish_event(ws, event: str, data: dict = None):
+    """Publish event via event.publish RPC (fire-and-forget)."""
+    await _rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": event,
+        "data": data or {},
+    }, wait_response=False)
+
+
+async def _handle_ping_event(data: dict):
+    """Handle system.ping event and reply with system.pong."""
+    t1 = data.get("ping_time")
+    t2 = time.time()
+
+    await _publish_event(_ws_global, "system.pong", {
+        "module_id": MODULE_NAME,
+        "ping_time": t1,
+        "pong_time": t2,
+    })
+
+
+async def _handle_event_notification(msg: dict):
+    """Handle an event notification (JSON-RPC 2.0 Notification with method='event')."""
+    params = msg.get("params", {})
+    event_type = params.get("event", "")
+    data = params.get("data", {})
+
+    # Handle system.ping event
+    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
+
+    # Special handling for module.shutdown
+    if event_type == "module.shutdown":
+        target = data.get("module_id", "")
+        reason = data.get("reason", "")
+        # Handle both targeted shutdown (module_id == "redis") and broadcast shutdown (no module_id or launcher_lost)
+        if target == "redis" or not target or reason == "launcher_lost":
+            await _handle_shutdown()
+            return
+
+    # Layer 2: 忽略系统广播事件
+    if event_type in SYSTEM_BROADCAST_EVENTS:
+        return
+
+    # Layer 3: 警告未知事件（仅开发环境）
+    if os.environ.get("KITE_ENV") == "development":
+        print(f"[redis] Debug: Unhandled event: {event_type}")
+
+
+async def _handle_rpc_request(ws, msg: dict):
+    """Handle an incoming RPC request (redis.* methods)."""
+    rpc_id = msg.get("id", "")
+    method = msg.get("method", "")
+    params = msg.get("params", {})
+
+    handlers = {
+        "health": lambda p: _rpc_health(),
+        "status": lambda p: _rpc_status(),
+        "get_settings": lambda p: _rpc_get_settings(p),
+        "update_settings": lambda p: _rpc_update_settings(p),
+        "reset_settings": lambda p: _rpc_reset_settings(p),
+        "ping": lambda p: _rpc_redis_ping(p),
+        "get": lambda p: _rpc_redis_get(p),
+        "set": lambda p: _rpc_redis_set(p),
+        "del": lambda p: _rpc_redis_del(p),
+        "expire": lambda p: _rpc_redis_expire(p),
+        "hget": lambda p: _rpc_redis_hget(p),
+        "hset": lambda p: _rpc_redis_hset(p),
+        "hdel": lambda p: _rpc_redis_hdel(p),
+        "hgetall": lambda p: _rpc_redis_hgetall(p),
+        "sadd": lambda p: _rpc_redis_sadd(p),
+        "srem": lambda p: _rpc_redis_srem(p),
+        "smembers": lambda p: _rpc_redis_smembers(p),
+        "publish": lambda p: _rpc_redis_publish(p),
+        "info": lambda p: _rpc_redis_info(p),
+    }
+    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:
+    """RPC handler for redis.health."""
+    return {
+        "status": "healthy",
+        "redis_ready": _redis_ready,
+        "details": {
+            "uptime_seconds": round(time.monotonic() - _start_ts),
+        },
+    }
+
+
+async def _rpc_status() -> dict:
+    """RPC handler for redis.status."""
+    return {
+        "module_id": "redis",
+        "status": "running",
+        "redis_ready": _redis_ready,
+        "uptime": round(time.monotonic() - _start_ts),
+        "uptime_seconds": round(time.monotonic() - _start_ts),
+    }
+
+
+# ── Configuration management helpers ──
+
+def _read_module_md() -> tuple[dict, str]:
+    """读取 module.md，返回 (frontmatter, body)"""
+    from pathlib import Path
+    md_path = Path(__file__).parent / "module.md"
+    text = md_path.read_text(encoding="utf-8")
+
+    # 提取 YAML frontmatter (--- ... ---)
+    m = re.match(r'^---\s*\n(.*?)\n---\s*\n?(.*)', text, re.DOTALL)
+    if not m:
+        return {}, text
+
+    import yaml
+    frontmatter = yaml.safe_load(m.group(1)) or {}
+    body = m.group(2)
+    return frontmatter, body
+
+
+def _write_module_md(frontmatter: dict, body: str):
+    """写入 module.md"""
+    from pathlib import Path
+    import yaml
+    md_path = Path(__file__).parent / "module.md"
+    fm_str = yaml.dump(frontmatter, allow_unicode=True, sort_keys=False, default_flow_style=False).rstrip()
+    content = f"---\n{fm_str}\n---\n{body}"
+    md_path.write_text(content, encoding="utf-8")
+
+
+# ── RPC handlers for configuration management ──
+
+async def _rpc_get_settings(params: dict) -> dict:
+    """RPC handler for redis.get_settings — 获取模块的所有设置"""
+    frontmatter, _ = _read_module_md()
+
+    config = None
+    _businesses = frontmatter.get("businesses") or []
+    config_file = (_businesses[0].get("config_file") if isinstance(_businesses[0], dict) else None) if _businesses else None
+    if config_file:
+        config_path = os.path.join(os.path.dirname(__file__), config_file)
+        if os.path.exists(config_path):
+            try:
+                import json5
+                with open(config_path, 'r', encoding='utf-8') as f:
+                    config = json5.load(f)
+            except Exception as e:
+                print(f"[redis] 读取业务配置失败: {e}")
+
+    return {
+        "name": frontmatter.get("name", "redis"),
+        "display_name": frontmatter.get("display_name", ""),
+        "type": frontmatter.get("type", ""),
+        "state": frontmatter.get("state", "enabled"),
+        "version": frontmatter.get("version", ""),
+        "runtime": frontmatter.get("runtime", ""),
+        "entry": frontmatter.get("entry", ""),
+        "preferred_port": frontmatter.get("preferred_port"),
+        "advertise_ip": frontmatter.get("advertise_ip"),
+        "monitor": frontmatter.get("monitor"),
+        "events": frontmatter.get("events"),
+        "subscriptions": frontmatter.get("subscriptions"),
+        "depends_on": frontmatter.get("depends_on"),
+        "has_config": config is not None,
+        "config": config,
+    }
+
+
+async def _rpc_update_settings(params: dict) -> dict:
+    """RPC handler for redis.update_settings — 更新模块设置"""
+    metadata = params.get("metadata", {})
+    config = params.get("config", {})
+
+    # 更新 module.md frontmatter
+    if metadata:
+        frontmatter, body = _read_module_md()
+        for key, value in metadata.items():
+            frontmatter[key] = value
+        _write_module_md(frontmatter, body)
+
+    # 更新业务配置文件
+    if config:
+        frontmatter, _ = _read_module_md()
+        _businesses = frontmatter.get("businesses") or []
+        config_file = (_businesses[0].get("config_file") if isinstance(_businesses[0], dict) else None) if _businesses else None
+        if config_file:
+            config_path = os.path.join(os.path.dirname(__file__), config_file)
+            existing = {}
+            if os.path.exists(config_path):
+                try:
+                    import json5
+                    with open(config_path, 'r', encoding='utf-8') as f:
+                        existing = json5.load(f) or {}
+                except Exception:
+                    existing = {}
+
+            for flat_key, value in config.items():
+                keys = flat_key.split('.')
+                target = existing
+                for k in keys[:-1]:
+                    if k not in target or not isinstance(target[k], dict):
+                        target[k] = {}
+                    target = target[k]
+                target[keys[-1]] = value
+
+            import json
+            with open(config_path, 'w', encoding='utf-8') as f:
+                f.write(json.dumps(existing, ensure_ascii=False, indent=2))
+
+    # 返回更新后的完整设置
+    return await _rpc_get_settings({})
+
+
+async def _rpc_reset_settings(params: dict) -> dict:
+    """RPC handler for redis.reset_settings — 恢复默认值"""
+    fields = params.get("fields", [])
+    reset_all = params.get("all", False)
+
+    # 默认值定义
+    defaults = {
+        "state": "enabled",
+        "preferred_port": 20000,
+        "advertise_ip": "127.0.0.1",
+        "monitor": True,
+    }
+
+    frontmatter, body = _read_module_md()
+
+    if reset_all:
+        # 恢复所有字段
+        for key, value in defaults.items():
+            frontmatter[key] = value
+    else:
+        # 恢复指定字段
+        for field in fields:
+            if field in defaults:
+                frontmatter[field] = defaults[field]
+
+    _write_module_md(frontmatter, body)
+
+    # 返回恢复后的设置
+    return await _rpc_get_settings({})
+
+
+# ── Redis RPC handlers ──
+
+async def _rpc_redis_ping(params: dict) -> dict:
+    """RPC: redis.ping"""
+    if not _redis_ready:
+        raise Exception("Redis not ready")
+    return {"status": "ok", "message": "PONG"}
+
+
+async def _rpc_redis_get(params: dict) -> dict:
+    """RPC: redis.get"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    if not key:
+        raise Exception("Missing key parameter")
+    value = await _redis_impl.get(key)
+    return {"key": key, "value": value}
+
+
+async def _rpc_redis_set(params: dict) -> dict:
+    """RPC: redis.set"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    value = params.get("value")
+    if not key:
+        raise Exception("Missing key parameter")
+    await _redis_impl.set(key, value)
+    return {"status": "ok"}
+
+
+async def _rpc_redis_hget(params: dict) -> dict:
+    """RPC: redis.hget"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    field = params.get("field")
+    if not key or not field:
+        raise Exception("Missing key or field parameter")
+    value = await _redis_impl.hget(key, field)
+    return {"key": key, "field": field, "value": value}
+
+
+async def _rpc_redis_hset(params: dict) -> dict:
+    """RPC: redis.hset"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    field = params.get("field")
+    value = params.get("value")
+    if not key or not field:
+        raise Exception("Missing key or field parameter")
+    await _redis_impl.hset(key, field, value)
+    return {"status": "ok"}
+
+
+async def _rpc_redis_info(params: dict) -> dict:
+    """RPC: redis.info"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    return {
+        "host": _redis_impl.host,
+        "port": _redis_impl.port,
+        "protocol": "RESP",
+        "type": "external" if hasattr(_redis_impl, "_client") else "builtin",
+    }
+
+
+async def _rpc_redis_del(params: dict) -> dict:
+    """RPC: redis.del"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    if not key:
+        raise Exception("Missing key parameter")
+    deleted = await _redis_impl.delete(key)
+    return {"deleted": deleted}
+
+
+async def _rpc_redis_expire(params: dict) -> dict:
+    """RPC: redis.expire"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    seconds = params.get("seconds")
+    if not key or seconds is None:
+        raise Exception("Missing key or seconds parameter")
+    result = await _redis_impl.expire(key, int(seconds))
+    return {"result": result}
+
+
+async def _rpc_redis_hdel(params: dict) -> dict:
+    """RPC: redis.hdel"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    field = params.get("field")
+    if not key or not field:
+        raise Exception("Missing key or field parameter")
+    deleted = await _redis_impl.hdel(key, field)
+    return {"deleted": deleted}
+
+
+async def _rpc_redis_hgetall(params: dict) -> dict:
+    """RPC: redis.hgetall"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    if not key:
+        raise Exception("Missing key parameter")
+    result = await _redis_impl.hgetall(key)
+    # 内置返回 list [k,v,k,v], 外部返回 dict — 统一为 dict
+    if isinstance(result, list):
+        d = {}
+        for i in range(0, len(result), 2):
+            d[result[i]] = result[i + 1]
+        return {"key": key, "data": d}
+    return {"key": key, "data": result if isinstance(result, dict) else {}}
+
+
+async def _rpc_redis_sadd(params: dict) -> dict:
+    """RPC: redis.sadd"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    members = params.get("members") or []
+    member = params.get("member")
+    if member and not members:
+        members = [member]
+    if not key or not members:
+        raise Exception("Missing key or member/members parameter")
+    added = await _redis_impl.sadd(key, *members)
+    return {"added": added}
+
+
+async def _rpc_redis_srem(params: dict) -> dict:
+    """RPC: redis.srem"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    members = params.get("members") or []
+    member = params.get("member")
+    if member and not members:
+        members = [member]
+    if not key or not members:
+        raise Exception("Missing key or member/members parameter")
+    removed = await _redis_impl.srem(key, *members)
+    return {"removed": removed}
+
+
+async def _rpc_redis_smembers(params: dict) -> dict:
+    """RPC: redis.smembers"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    key = params.get("key")
+    if not key:
+        raise Exception("Missing key parameter")
+    members = await _redis_impl.smembers(key)
+    return {"key": key, "members": list(members) if members else []}
+
+
+async def _rpc_redis_publish(params: dict) -> dict:
+    """RPC: redis.publish"""
+    if not _redis_ready or not _redis_impl:
+        raise Exception("Redis not ready")
+    channel = params.get("channel")
+    message = params.get("message")
+    if not channel or message is None:
+        raise Exception("Missing channel or message parameter")
+    receivers = await _redis_impl.publish(channel, message)
+    return {"receivers": receivers}
+
+
+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}/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"[redis] Slot {slot} connected")
+    except Exception as e:
+        print(f"[redis] 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
+
+                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 not has_method and has_id:
+                    _handle_rpc_response(msg)
+            except Exception as e:
+                print(f"[redis] Slot {slot} 消息处理异常（已忽略）: {e}")
+    except Exception as e:
+        print(f"[redis] 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():
+    """Handle module.shutdown event — ack → exiting → cleanup → ready → exit."""
+    global _shutting_down
+    print("[redis] Received shutdown request")
+    _shutting_down = True
+    # Step 1: Send ack (立即确认收到)
+    await _publish_event(_ws_global, "module.shutdown.ack", {"module_id": "redis"})
+    # Step 2: Send module.exiting (开始清理)
+    await _publish_event(_ws_global, "module.exiting", {
+        "module_id": "redis",
+        "type": "passive",
+        "reason": "shutdown_requested",
+        "restart": "auto",
+        "action": "none",
+        "timeout": 2.0,
+        "restart_delay": 0.0,
+    })
+    # Step 3: Cleanup - 关闭 Redis 实现
+    if _redis_impl:
+        try:
+            await _redis_impl.close()
+            print("[redis] Redis implementation closed")
+        except Exception as e:
+            print(f"[redis] Failed to close Redis: {e}")
+
+    # 关闭所有附加连接
+    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()
+    # Step 4: Send ready (清理完成)
+    await _publish_event(_ws_global, "module.shutdown.ready", {"module_id": "redis"})
+    print("[redis] Shutdown ready, exiting")
+
+    # 等待 Kernel 处理 shutdown.ready（防止 Close 帧抢先）
+    await asyncio.sleep(0.1)
+
+    # Step 5: Close WebSocket connection gracefully
+    if _ws_global:
+        try:
+            await _ws_global.close(code=1000, reason="Graceful shutdown")
+            print("[redis] WebSocket closed")
+        except Exception as e:
+            print(f"[redis] Failed to close WebSocket: {e}")
+
+    # Note: Do NOT call sys.exit() in async context
+    # Let the event loop naturally complete
+
+
+async def _test_event_loop(ws):
+    """Publish a test event every 10 seconds."""
+    try:
+        while True:
+            await asyncio.sleep(10)
+            await _publish_event(ws, "redis.test", {
+                "message": "test event from redis",
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            })
+    except Exception:
+        pass
+
+
+_startup_config = {}  # populated by _validate_and_prepare()
+
+
+def _validate_and_prepare() -> dict:
+    """同步启动验证：日志初始化、读取 token 和 kernel_port。
+    失败直接 sys.exit(1)，成功返回启动参数。在 asyncio.run() 之前调用。"""
+    t0 = time.monotonic()
+    kernel_port = os.environ.get("KITE_KERNEL_PORT")
+    if kernel_port:
+        return _prepare_local_mode(int(kernel_port), t0)
+    config = _load_module_config()
+    gateway_url = config.get("gateway_url") or os.environ.get("KITE_GATEWAY_URL")
+    if gateway_url:
+        return _prepare_remote_mode(gateway_url, t0)
+    print(f"[{MODULE_NAME}] ERROR: No KITE_KERNEL_PORT and no gateway_url")
+    sys.exit(1)
+
+def _prepare_local_mode(kernel_port: int, t0: float) -> dict:
+    global _log_dir, _log_latest_path, _crash_log_path
+    module_data = os.environ.get("KITE_MODULE_DATA")
+    if module_data:
+        _log_dir = os.path.join(module_data, "log")
+        os.makedirs(_log_dir, exist_ok=True)
+        suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
+        _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()
+    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}")
+    return {"mode": "local", "token": token, "kernel_port": kernel_port, "t0": t0}
+
+def _prepare_remote_mode(gateway_url: str, t0: float) -> dict:
+    global _log_dir, _log_latest_path, _crash_log_path
+    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)
+    _log_dir = os.path.join(data_dir, "log")
+    os.makedirs(_log_dir, exist_ok=True)
+    _log_latest_path = os.path.join(_log_dir, "latest.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, "crashes.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()
+    kite_token = _get_kite_token(MODULE_NAME, gateway_url)
+    print(f"[{MODULE_NAME}] Remote mode: gateway={gateway_url}")
+    return {"mode": "remote", "gateway_url": gateway_url, "kite_token": kite_token, "t0": t0}
+
+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))
+    if os.path.exists(token_file):
+        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)
+
+
+async def _remote_mode_loop(gateway_url: str, kite_token: str, _t0: float):
+    global _shutting_down, _exit_code
+    retry_count = 0
+    while not _shutting_down and retry_count < 10:
+        try:
+            await _remote_connect(gateway_url, kite_token, _t0)
+            retry_count = 0
+        except asyncio.CancelledError: break
+        except Exception as e:
+            if _shutting_down: break
+            retry_count += 1
+            await asyncio.sleep(min(2 ** retry_count, 60))
+    if retry_count >= 10: _exit_code = 1
+
+async def _remote_connect(gateway_url: str, kite_token: str, _t0: float):
+    global _ws_global
+    async with websockets.connect(gateway_url, open_timeout=10, ping_interval=30) as ws:
+        challenge = json.loads(await ws.recv())
+        auth_req = {"jsonrpc": "2.0", "id": "auth", "method": "auth.connect",
+                    "params": {"nonce": challenge["params"]["nonce"], "module_id": MODULE_NAME,
+                              "auth": {"method": "kite_token", "token": kite_token},
+                              "client": {"type": "module", "platform": sys.platform}}}
+        await ws.send(json.dumps(auth_req))
+        hello_resp = json.loads(await ws.recv())
+        if "error" in hello_resp:
+            error = hello_resp["error"]
+            if error.get("code") in (4001, 4010, 4011):
+                _clear_token_cache(MODULE_NAME, gateway_url)
+                print(f"[{MODULE_NAME}] Token invalid, re-authenticate")
+                sys.exit(1)
+            raise Exception(f"Connection failed: {error}")
+        print(f"[{MODULE_NAME}] Connected via Gateway")
+        _ws_global = ws
+
+        # Start receiver task — wait for system.require_init to trigger _do_init
+        receiver_task = asyncio.create_task(_ws_receiver(ws))
+        try:
+            await receiver_task
+        finally:
+            receiver_task.cancel()
+            for fut in _pending_rpc.values():
+                if not fut.done():
+                    fut.set_result({"error": {"code": -32001, "message": "Connection lost"}})
+            _pending_rpc.clear()
+
+
+if __name__ == "__main__":
+    _startup_config = _validate_and_prepare()
+    asyncio.run(main())
+    sys.exit(_exit_code)