@agentunion/kite 1.3.2 → 1.5.0

package/extensions/services/watchdog/monitor.py

@@ -13,6 +13,14 @@ 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"
@@ -47,6 +55,8 @@ class ModuleStatus:
         self.memory_samples: list[float] = []  # last 5 memory_rss samples
         self.recovery_since: float = 0  # when recovery observation started
         self.last_metrics: dict = {}
+        # Startup metrics
+        self.startup_time: float = 0  # module startup time in seconds (from module.ready event)
 
 
 class HealthMonitor:
@@ -91,6 +101,8 @@ class HealthMonitor:
         # 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 ──
 
@@ -154,23 +166,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)
 
@@ -394,42 +411,71 @@ class HealthMonitor:
             return
 
         if not module_id or module_id == "watchdog":
+            # Handle registry.updated (no module_id)
+            if event_type == "registry.updated":
+                # Registry changed, re-discover modules
+                asyncio.create_task(self.discover_modules())
             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}")
             self.modules.pop(module_id, None)
+            # Re-discover to update module list
+            asyncio.create_task(self.discover_modules())
             await self._handle_module_stopped(module_id, data)
 
         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}")
+            startup_time = data.get("startup_time", 0)
+            print(f"[watchdog] Received module.ready: {module_id}, graceful_shutdown={graceful}, startup_time={startup_time:.3f}s")
             self._graceful_modules[module_id] = graceful
+            # Save startup time to module status
+            if module_id in self.modules:
+                self.modules[module_id].startup_time = startup_time
             # Reset launcher loss tracking when launcher reconnects
             if module_id == "launcher":
                 self._launcher_offline = False
                 self._launcher_had_exiting = False
 
+        # 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:
@@ -439,6 +485,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":
@@ -473,6 +531,27 @@ 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.
 
@@ -489,32 +568,73 @@ class HealthMonitor:
             sys.exit(0)
 
     def _start_new_instance(self):
-        """Start a new Kite instance by running python main.py in the project directory."""
-        project_dir = os.environ.get("KITE_PROJECT", "")
-        if not project_dir:
-            print("[watchdog] ERROR: KITE_PROJECT not set, cannot start new instance")
-            return
+        """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]
 
-        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
+            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}")
 
-        print(f"[watchdog] Starting new Kite instance: 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", sys.executable, main_py],
-                    cwd=project_dir,
+                    ["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", main_py],
-                    cwd=project_dir,
+                    ["open", "-a", "Terminal"] + cmd,
+                    cwd=cwd,
+                    env=new_env,
                 )
             else:
                 # Linux: try common terminal emulators
@@ -528,8 +648,9 @@ class HealthMonitor:
                 for term_cmd in terminals:
                     try:
                         subprocess.Popen(
-                            term_cmd + [sys.executable, main_py],
-                            cwd=project_dir,
+                            term_cmd + cmd,
+                            cwd=cwd,
+                            env=new_env,
                             start_new_session=True,
                         )
                         launched = True
@@ -540,8 +661,9 @@ class HealthMonitor:
                     # Fallback: headless start
                     print("[watchdog] WARNING: No terminal emulator found, starting headless")
                     subprocess.Popen(
-                        [sys.executable, main_py],
-                        cwd=project_dir,
+                        cmd,
+                        cwd=cwd,
+                        env=new_env,
                         start_new_session=True,
                         stdin=subprocess.DEVNULL,
                     )
@@ -584,10 +706,15 @@ class HealthMonitor:
             return
         print("[watchdog] system.ready received, starting health checks")
 
-        while self._running:
-            # Re-discover every cycle to pick up newly started/stopped modules
-            await self.discover_modules()
+        # Initial discovery (first time)
+        await self.discover_modules()
 
+        # Track discovery count and last discovery time
+        discovery_count = 1
+        last_discovery = asyncio.get_event_loop().time()
+        discovery_interval = 300.0  # 5 minutes after first 2 discoveries
+
+        while self._running:
             if self.modules:
                 tasks = []
                 for s in self.modules.values():
@@ -599,6 +726,18 @@ class HealthMonitor:
             interval = self._min_interval()
             await asyncio.sleep(interval)
 
+            # Periodic re-discovery
+            now = asyncio.get_event_loop().time()
+            if discovery_count < 2:
+                # First 2 times: discover every cycle
+                await self.discover_modules()
+                discovery_count += 1
+                last_discovery = now
+            elif now - last_discovery >= discovery_interval:
+                # After that: discover every 5 minutes
+                await self.discover_modules()
+                last_discovery = now
+
     def _min_interval(self) -> float:
         """Return the shortest check interval needed across all modules."""
         if not self.modules:
@@ -622,6 +761,7 @@ class HealthMonitor:
                 "last_error": s.last_error,
                 "resource_state": s.resource_state,
                 "metrics": s.last_metrics,
+                "startup_time": s.startup_time,
             }
             for mid, s in self.modules.items()
         }

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)