@agentunion/kite 1.3.1 → 1.4.0

package/extensions/services/watchdog/monitor.py

@@ -6,10 +6,21 @@ Launcher handles process-level crashes; Watchdog handles app-level failures
 
 import asyncio
 import json
+import os
+import subprocess
+import sys
 import time
 from datetime import datetime, timezone
 
 
+# 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",
+}
+
 # Module health states
 HEALTHY = "healthy"
 UNHEALTHY = "unhealthy"
@@ -85,6 +96,12 @@ class HealthMonitor:
         self._system_ready_event = asyncio.Event()
         self._crash_counts: dict[str, int] = {}         # module_id -> consecutive crash count
 
+        # Launcher loss tracking
+        self._launcher_offline = False
+        self._launcher_had_exiting = False  # True if module.exiting was received for launcher
+        self._launcher_restart_requested = False  # True if launcher requested restart
+        self._launcher_startup_info = None  # Startup info from launcher (python, argv, cwd, env)
+
     # ── Module discovery ──
 
     async def discover_modules(self):
@@ -147,23 +164,28 @@ class HealthMonitor:
     # ── Health check ──
 
     async def _check_one(self, status: ModuleStatus):
-        """Check a single module's /health endpoint."""
+        """Check a single module's health via RPC."""
         if not status.api_endpoint:
             return  # Not yet registered in Registry, will be picked up on next discover
-        url = f"{status.api_endpoint}{status.health_endpoint}"
+
         status.last_check = time.time()
 
         try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(url, timeout=self.HEALTH_TIMEOUT)
-                if resp.status_code == 200:
-                    body = resp.json()
-                    if body.get("status") == "healthy":
-                        await self._mark_healthy(status)
-                        return
-                    status.last_error = f"unhealthy response: {body.get('status')}"
-                else:
-                    status.last_error = f"HTTP {resp.status_code}"
+            # Call module.health via RPC
+            resp = await self.rpc_call(f"{status.module_id}.health", {})
+
+            # Check if RPC call succeeded
+            if "error" in resp:
+                error = resp["error"]
+                status.last_error = f"RPC error: {error.get('message', 'unknown')}"
+            elif "result" in resp:
+                result = resp["result"]
+                if result.get("status") == "healthy":
+                    await self._mark_healthy(status)
+                    return
+                status.last_error = f"unhealthy response: {result.get('status')}"
+            else:
+                status.last_error = "Invalid RPC response"
         except Exception as e:
             status.last_error = str(e)
 
@@ -364,13 +386,37 @@ class HealthMonitor:
             self._system_ready_event.set()
             return
 
+        # module.offline — track launcher state
+        if event_type == "module.offline":
+            if module_id == "launcher":
+                print("[watchdog] Received module.offline(launcher)")
+                self._launcher_offline = True
+            return
+
+        # module.shutdown with reason launcher_lost — decide whether to start new instance
+        if event_type == "module.shutdown":
+            reason = data.get("reason", "")
+            if reason == "launcher_lost":
+                print("[watchdog] Received module.shutdown(reason=launcher_lost)")
+                await self._handle_launcher_lost()
+                return
+            target = data.get("module_id", "")
+            if not target:
+                # Broadcast shutdown — check reason
+                if reason == "system_shutdown":
+                    print(f"[watchdog] Received system_shutdown signal")
+                    self._system_shutting_down = True
+            return
+
         if not module_id or module_id == "watchdog":
             return
 
         if event_type == "module.started":
             print(f"[watchdog] Received module.started: {module_id}")
             self._crash_counts.pop(module_id, None)
-            await self.discover_modules()
+            # Don't await discover_modules() here - it blocks event processing!
+            # Schedule it as a background task instead
+            asyncio.create_task(self.discover_modules())
 
         elif event_type == "module.stopped":
             print(f"[watchdog] Received module.stopped: {module_id}")
@@ -379,27 +425,45 @@ class HealthMonitor:
 
         elif event_type == "module.exiting":
             action = data.get("action", "none")
-            print(f"[watchdog] Received module.exiting: {module_id}, action={action}")
+            reason = data.get("reason", "")
+            print(f"[watchdog] Received module.exiting: {module_id}, action={action}, reason={reason}")
             self._exit_intents[module_id] = action
+            # Track launcher exiting intent
+            if module_id == "launcher":
+                self._launcher_had_exiting = True
+                if action == "restart_launcher":
+                    print(f"[watchdog] Launcher 请求计划内重启 (reason={reason})")
+                    self._launcher_restart_requested = True
+                    # Save startup info for restart
+                    self._launcher_startup_info = data.get("startup_info")
+                    # 启动快速检测任务
+                    asyncio.create_task(self._quick_check_launcher_exit())
 
         elif event_type == "module.ready":
             graceful = bool(data.get("graceful_shutdown"))
             print(f"[watchdog] Received module.ready: {module_id}, graceful_shutdown={graceful}")
             self._graceful_modules[module_id] = graceful
+            # Reset launcher loss tracking when launcher reconnects
+            if module_id == "launcher":
+                self._launcher_offline = False
+                self._launcher_had_exiting = False
 
-        elif event_type == "module.shutdown":
-            reason = data.get("reason", "")
-            if reason == "system_shutdown":
-                print(f"[watchdog] Received system_shutdown signal")
-                self._system_shutting_down = True
+        # Layer 2: 忽略系统广播事件
+        elif event_type in SYSTEM_BROADCAST_EVENTS:
+            pass
+
+        # Layer 3: 警告未知事件
+        else:
+            print(f"[watchdog] Warning: Received unhandled event: {event_type}")
 
     async def _handle_module_stopped(self, module_id: str, data: dict):
         """Restart decision engine — called when module.stopped is received.
 
         Priority:
         1. System shutting down → no restart
-        2. Has exit_intent → follow the declared action (none/restart/restart_delay)
-        3. No intent (crash) → increment crash count, restart up to MAX_RESTARTS
+        2. stop_type == "graceful_stop" → Launcher主动停止，不重启
+        3. stop_type == "process_exit" + has exit_intent → 按 intent 处理
+        4. stop_type == "process_exit" + no intent → 崩溃，重启
         """
         # Sync graceful_shutdown from Launcher (covers missed module.ready)
         if "graceful_shutdown" in data:
@@ -409,6 +473,18 @@ class HealthMonitor:
             print(f"[watchdog] {module_id} stopped during shutdown, skipping restart")
             return
 
+        # Check stop_type first (most reliable indicator)
+        stop_type = data.get("stop_type", "unknown")
+
+        if stop_type == "graceful_stop":
+            # Launcher主动停止（通过RPC或shutdown流程）
+            reason = data.get("reason", "unknown")
+            print(f"[watchdog] {module_id} stopped by Launcher (stop_type=graceful_stop, reason={reason}), no restart")
+            self._crash_counts.pop(module_id, None)
+            self._exit_intents.pop(module_id, None)  # 清理可能残留的intent
+            return
+
+        # stop_type == "process_exit": 进程自行退出，需要判断是否崩溃
         intent = self._exit_intents.pop(module_id, None)
         if intent is not None:
             if intent == "none":
@@ -443,6 +519,146 @@ class HealthMonitor:
                 "message": f"{module_id} exceeded {self.MAX_RESTARTS} crash restarts",
             })
 
+
+    async def _quick_check_launcher_exit(self):
+        """快速检测 Launcher 退出（0.2s 间隔，最多 5s，5s 后强制重启）"""
+        print("[watchdog] 开始快速检测 Launcher 退出（0.2s 间隔，最多 5s）")
+        for i in range(25):  # 25 * 0.2s = 5s
+            try:
+                await self.rpc_call("launcher.list_modules", {})
+                await asyncio.sleep(0.2)
+            except Exception:
+                # Launcher 已退出
+                print(f"[watchdog] Launcher 已退出（检测 {(i+1)*0.2:.1f}s），启动新实例")
+                self._start_new_instance()
+                print("[watchdog] 新实例已启动，watchdog 退出")
+                sys.exit(0)
+
+        # 5s 后仍未退出，强制重启
+        print("[watchdog] Launcher 5s 内未退出，强制重启")
+        self._start_new_instance()
+        print("[watchdog] 新实例已启动，watchdog 退出")
+        sys.exit(0)
+
+    async def _handle_launcher_lost(self):
+        """Handle launcher_lost: decide whether to start a new Kite instance.
+
+        - If launcher sent module.exiting before going offline → normal exit, follow suit
+        - If launcher did NOT send module.exiting → crash/unexpected, start new instance
+        """
+        if self._launcher_had_exiting:
+            print("[watchdog] Launcher had sent module.exiting before loss → normal exit, following suit")
+            sys.exit(0)
+        else:
+            print("[watchdog] Launcher lost without module.exiting → crash detected, starting new instance")
+            self._start_new_instance()
+            print("[watchdog] New instance started, exiting")
+            sys.exit(0)
+
+    def _start_new_instance(self):
+        """Start a new Kite instance using saved startup info from launcher."""
+        # Use startup info if available (from module.exiting event)
+        if self._launcher_startup_info:
+            python_exe = self._launcher_startup_info.get("python", sys.executable)
+            argv = self._launcher_startup_info.get("argv", [])
+            cwd = self._launcher_startup_info.get("cwd", os.environ.get("KITE_PROJECT", ""))
+            env = self._launcher_startup_info.get("env", {})
+
+            # Build command based on argv[0]
+            if argv:
+                # Check if argv[0] is executable (e.g., kite.exe or python script)
+                argv0 = argv[0]
+                if os.path.isabs(argv0) and os.path.exists(argv0):
+                    # argv[0] is absolute path to executable/script, use it directly
+                    cmd = argv
+                elif argv0.endswith(('.py', '.pyw')):
+                    # argv[0] is a Python script, prepend Python interpreter
+                    cmd = [python_exe] + argv
+                else:
+                    # argv[0] might be a command in PATH (e.g., 'kite'), use it directly
+                    cmd = argv
+            else:
+                # Fallback to main.py
+                main_py = os.path.join(cwd, "main.py")
+                cmd = [python_exe, main_py]
+
+            print(f"[watchdog] Starting new instance with saved startup info:")
+            print(f"[watchdog]   Command: {' '.join(cmd)}")
+            print(f"[watchdog]   CWD: {cwd}")
+
+            # Use saved environment variables
+            new_env = env
+
+        else:
+            # Fallback: use current environment (old behavior)
+            project_dir = os.environ.get("KITE_PROJECT", "")
+            if not project_dir:
+                print("[watchdog] ERROR: KITE_PROJECT not set, cannot start new instance")
+                return
+
+            main_py = os.path.join(project_dir, "main.py")
+            if not os.path.exists(main_py):
+                print(f"[watchdog] ERROR: {main_py} not found, cannot start new instance")
+                return
+
+            python_exe = sys.executable
+            cmd = [python_exe, main_py]
+            cwd = project_dir
+            new_env = os.environ.copy()
+            print(f"[watchdog] Starting new instance (fallback mode): python {main_py}")
+
+        try:
+            # Start detached process with new console window
+            if sys.platform == "win32":
+                # Use 'start' command to force visible console window
+                subprocess.Popen(
+                    ["cmd", "/c", "start", "Kite"] + cmd,
+                    cwd=cwd,
+                    env=new_env,
+                    shell=False,
+                )
+            elif sys.platform == "darwin":
+                # macOS: use 'open -a Terminal' to launch in new Terminal window
+                subprocess.Popen(
+                    ["open", "-a", "Terminal"] + cmd,
+                    cwd=cwd,
+                    env=new_env,
+                )
+            else:
+                # Linux: try common terminal emulators
+                terminals = [
+                    ["x-terminal-emulator", "-e"],  # Debian/Ubuntu default
+                    ["gnome-terminal", "--"],       # GNOME
+                    ["konsole", "-e"],              # KDE
+                    ["xterm", "-e"],                # Fallback
+                ]
+                launched = False
+                for term_cmd in terminals:
+                    try:
+                        subprocess.Popen(
+                            term_cmd + cmd,
+                            cwd=cwd,
+                            env=new_env,
+                            start_new_session=True,
+                        )
+                        launched = True
+                        break
+                    except FileNotFoundError:
+                        continue
+                if not launched:
+                    # Fallback: headless start
+                    print("[watchdog] WARNING: No terminal emulator found, starting headless")
+                    subprocess.Popen(
+                        cmd,
+                        cwd=cwd,
+                        env=new_env,
+                        start_new_session=True,
+                        stdin=subprocess.DEVNULL,
+                    )
+            print("[watchdog] New Kite instance started successfully")
+        except Exception as e:
+            print(f"[watchdog] Failed to start new instance: {e}")
+
     async def _restart_module_by_id(self, module_id: str, reason: str = "restart"):
         """Restart a module via Launcher RPC by module_id."""
         print(f"[watchdog] Requesting restart for {module_id} (reason={reason})")

package/extensions/services/web/WEBSOCKET_STATUS.md

@@ -0,0 +1,143 @@
+# Web 模块实时状态推送 — WebSocket 实现
+
+## 概述
+
+为 Web 管理后台新增 `/ws/management` WebSocket 端点，实时推送模块状态变更到前端，实现无需刷新的实时状态监控。
+
+## 架构
+
+```
+Kernel (事件源)
+  ↓ WebSocket JSON-RPC 2.0
+Web 模块 (server.py)
+  ↓ 订阅事件 → 转发
+routes_management_ws.py (广播)
+  ↓ WebSocket
+前端 (app.js)
+  ↓ 更新 UI
+模块列表页面
+```
+
+## 模块状态体系
+
+### 1. 静态状态（module.md 配置）
+- `enabled` — 自动启动
+- `manual` — 手动启动
+- `disabled` — 禁用
+
+### 2. 运行时状态（Launcher 管理）
+- `stopped` — 未运行
+- `starting` — 启动中
+- `running` — 运行中
+- `stopping` — 停止中
+- `crashed` — 崩溃
+- `restarting` — 重启中
+
+### 3. 连接状态（Kernel 连接）
+- `disconnected` — 未连接到 Kernel
+- `connected` — 已连接到 Kernel
+- `registered` — 已注册到 Kernel Registry
+
+### 4. 前端综合显示
+
+| 状态 | 颜色 | 说明 |
+|------|------|------|
+| 离线 | 灰色 | stopped |
+| 启动中 | 黄色 | starting |
+| 在线 | 绿色 | running + registered |
+| 停止中 | 黄色 | stopping |
+| 崩溃 | 红色 | crashed |
+| 未连接 | 橙色 | running 但未连接 Kernel |
+
+## 实现细节
+
+### 后端
+
+#### 1. `routes/routes_management_ws.py`（新增）
+
+- **端点**: `/ws/management`
+- **功能**:
+  - 接受前端 WebSocket 连接
+  - 维护全局连接池 `_management_clients`
+  - 提供 `broadcast_event()` 函数广播事件到所有客户端
+  - 心跳机制（30 秒）
+- **消息格式**:
+  ```json
+  {
+    "type": "module.started",
+    "data": { "module_id": "watchdog" },
+    "timestamp": "2026-03-05T16:00:00Z"
+  }
+  ```
+
+#### 2. `server.py`（修改）
+
+- **导入**: 添加 `from routes.routes_management_ws import router as management_ws_router, broadcast_event`
+- **挂载路由**: `app.include_router(management_ws_router)`
+- **事件订阅**: 扩展订阅列表，包含：
+  - `module.started`
+  - `module.stopped`
+  - `module.crashed`
+  - `module.ready`
+  - `module.exiting`
+  - `module.shutdown`
+  - `module.shutdown.ack`
+  - `module.shutdown.ready`
+- **事件转发**: 在 `_handle_event_notification()` 中调用 `broadcast_event()` 转发模块状态事件
+
+### 前端
+
+#### 1. `static/js/app.js`（修改）
+
+**新增全局变量**:
+```javascript
+let _managementWs = null;
+let _managementWsConnected = false;
+```
+
+**新增函数**:
+- `connectManagementWebSocket()` — 连接 WebSocket，自动重连（3 秒）
+- `_handleManagementEvent(msg)` — 处理收到的事件
+- `_onModuleStatusChange(moduleName, status)` — 更新模块状态缓存和 UI
+- `_updateWsIndicator()` — 更新连线状态指示器
+
+**事件处理逻辑**:
+- `module.started` / `module.ready` → 标记为 running，清除 pending，刷新 UI
+- `module.stopped` / `module.crashed` → 标记为 stopped，清除 pending，刷新 UI
+- `module.exiting` / `module.shutdown.ack` → 标记为 stopping（保持 pending）
+
+**初始化**:
+在 `DOMContentLoaded` 中调用 `connectManagementWebSocket()`
+
+#### 2. `static/index.html`（修改）
+
+在模块页面标题栏添加连线状态指示器：
+```html
+<span id="ws-indicator" style="font-size:13px;color:var(--gray-400);">○ 未连线</span>
+```
+
+- 已连线: `● 已连线` (绿色)
+- 未连线: `○ 未连线` (灰色)
+
+## 使用效果
+
+1. **实时状态更新** — 模块启动/停止/崩溃时，前端立即更新，无需手动刷新
+2. **连线状态可见** — 页面顶部显示 WebSocket 连接状态
+3. **自动重连** — 连接断开后 3 秒自动重连
+4. **心跳保活** — 每 30 秒发送心跳，保持连接活跃
+
+## 端口复用
+
+HTTP 和 WebSocket 共用同一个端口（默认 18766），通过 FastAPI 统一管理：
+- HTTP: `http://localhost:18766/api/*`
+- WebSocket: `ws://localhost:18766/ws/management`
+
+## 扩展性
+
+未来可以通过 `broadcast_event()` 推送更多实时事件：
+- 通话状态变更
+- 蓝牙连接状态
+- 配置更新通知
+- 系统告警
+
+只需在 `server.py` 的事件处理中添加对应的 `broadcast_event()` 调用即可。

package/extensions/services/web/config_example.py

@@ -0,0 +1,35 @@
+"""
+配置加载使用示例
+
+演示如何在 web 模块中使用 config_loader 加载业务配置。
+"""
+
+import os
+from config_loader import load_business_configs, get_business_config
+
+# 获取模块目录
+module_dir = os.path.dirname(os.path.abspath(__file__))
+
+# 方式 1：加载所有业务配置
+all_configs = load_business_configs(module_dir)
+
+# 访问 web_server 配置
+if 'web_server' in all_configs:
+    web_config = all_configs['web_server']['config']
+    server_host = web_config['server']['host']
+    server_port = web_config['server']['port']
+    print(f"Web server: {server_host}:{server_port}")
+
+# 访问 relay_service 配置
+if 'relay_service' in all_configs:
+    relay_config = all_configs['relay_service']['config']
+    base_module_id = relay_config['relay']['base_module_id']
+    reconnect_timeout = relay_config['relay']['reconnect_timeout']
+    print(f"Relay: base_module_id={base_module_id}, timeout={reconnect_timeout}s")
+
+# 方式 2：只加载特定业务配置
+relay_business = get_business_config(module_dir, 'relay_service')
+if relay_business:
+    relay_config = relay_business['config']
+    permissions = relay_config['permissions']
+    print(f"Relay permissions: {list(permissions.keys())}")

package/extensions/services/web/config_loader.py

@@ -0,0 +1,110 @@
+"""
+配置加载工具
+
+用于加载模块的业务配置。支持从 module.md 读取业务配置块，
+并动态加载对应的 JSON5 配置文件。
+
+零共享代码依赖 - 此文件可以独立拷贝到其他模块使用。
+"""
+
+import os
+import re
+import json5
+import yaml
+
+
+def load_module_metadata(module_dir: str) -> dict:
+    """
+    读取 module.md 的 YAML frontmatter。
+
+    Args:
+        module_dir: 模块目录路径
+
+    Returns:
+        模块元数据字典
+    """
+    md_path = os.path.join(module_dir, "module.md")
+
+    if not os.path.exists(md_path):
+        return {}
+
+    try:
+        with open(md_path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        # 提取 YAML frontmatter (--- ... ---)
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if m:
+            return yaml.safe_load(m.group(1)) or {}
+    except Exception as e:
+        print(f"[config_loader] Error loading module.md: {e}")
+
+    return {}
+
+
+def load_business_configs(module_dir: str) -> dict:
+    """
+    加载所有业务配置。
+
+    从 module.md 的 businesses 块读取业务列表，
+    然后加载每个业务的配置文件（JSON5 格式）。
+
+    Args:
+        module_dir: 模块目录路径
+
+    Returns:
+        业务配置字典，格式：
+        {
+            "business_name": {
+                "metadata": {
+                    "name": "business_name",
+                    "type": "business_type",
+                    "description": "...",
+                    "config_file": "config.json5"
+                },
+                "config": { ... }  # JSON5 配置内容
+            }
+        }
+    """
+    metadata = load_module_metadata(module_dir)
+    businesses = metadata.get('businesses', [])
+
+    configs = {}
+    for business in businesses:
+        name = business.get('name')
+        config_file = business.get('config_file')
+
+        if not name or not config_file:
+            print(f"[config_loader] Warning: Invalid business entry: {business}")
+            continue
+
+        config_path = os.path.join(module_dir, config_file)
+
+        if os.path.exists(config_path):
+            try:
+                with open(config_path, "r", encoding="utf-8") as f:
+                    configs[name] = {
+                        'metadata': business,
+                        'config': json5.load(f)
+                    }
+            except Exception as e:
+                print(f"[config_loader] Error loading {config_file}: {e}")
+        else:
+            print(f"[config_loader] Warning: Config file not found: {config_file}")
+
+    return configs
+
+
+def get_business_config(module_dir: str, business_name: str) -> dict | None:
+    """
+    获取指定业务的配置。
+
+    Args:
+        module_dir: 模块目录路径
+        business_name: 业务名称
+
+    Returns:
+        业务配置字典，如果不存在则返回 None
+    """
+    configs = load_business_configs(module_dir)
+    return configs.get(business_name)