@agentunion/kite 1.3.2 → 1.5.0

package/kernel/server.py

@@ -33,9 +33,13 @@ class KernelServer:
     - Event notifications (delivered to subscribers)
     """
 
-    def __init__(self, launcher_token: str = None, advertise_ip: str = "127.0.0.1"):
+    def __init__(self, launcher_token: str = None, advertise_ip: str = "127.0.0.1", module_id: str = None, boot_t0: float = 0):
+        if module_id is None:
+            raise ValueError("module_id is required")
+        self.module_id = module_id
         self.advertise_ip = advertise_ip
         self.port: int = 0  # set by entry.py before uvicorn.run
+        self.boot_t0 = boot_t0  # Startup time for ready event
 
         # Core components
         self.registry = RegistryStore(launcher_token)  # Can be None
@@ -54,7 +58,6 @@ class KernelServer:
         )
 
         # Background tasks
-        self._ttl_task: asyncio.Task | None = None
         self._dedup_task: asyncio.Task | None = None
         self._uvicorn_server = None  # set by entry.py for graceful shutdown
         self._shutting_down = False
@@ -64,11 +67,25 @@ class KernelServer:
         self._launcher_subscribed = False
         self._ready_published = False
 
+        # Subscribe to events that Kernel needs to handle
+        # Kernel 通过订阅机制接收事件（与其他模块一致）
+        self.event_hub.handle_subscribe(self.module_id, ["module.shutdown", "system.pong"])
+
+        # Register internal event callback for Kernel
+        # Kernel 自身没有 WebSocket 连接，通过回调机制接收订阅的事件
+        self.event_hub.register_internal_callback(self.module_id, self._handle_internal_event)
+
         # Debounce timers for disconnected modules (module_id -> asyncio.Task)
         self._debounce_tasks: dict[str, asyncio.Task] = {}
         # Launcher loss timer (35s after launcher offline)
         self._launcher_loss_task: asyncio.Task | None = None
 
+        # Ping/Pong tracking
+        self._ping_sent_times: dict[str, float] = {}  # module_id -> last ping sent time (t1)
+        self._pong_latencies: dict[str, dict] = {}  # module_id -> {"outbound": ms, "inbound": ms, "last_update": timestamp}
+        self._pong_status: dict[str, str] = {}  # module_id -> "ok" | "timeout" | "never"
+        self._ping_task: asyncio.Task | None = None  # Global ping broadcast task
+
         # Build FastAPI app
         self.app = self._create_app()
 
@@ -80,15 +97,16 @@ class KernelServer:
 
         @app.on_event("startup")
         async def _startup():
-            server._ttl_task = asyncio.create_task(server._ttl_loop())
+            server.event_hub.start_internal_senders()
             server._dedup_task = asyncio.create_task(server._dedup_loop())
+            server._ping_task = asyncio.create_task(server._ping_broadcast_loop())
 
         @app.on_event("shutdown")
         async def _shutdown():
-            if server._ttl_task:
-                server._ttl_task.cancel()
             if server._dedup_task:
                 server._dedup_task.cancel()
+            if server._ping_task:
+                server._ping_task.cancel()
 
         # ── WebSocket endpoint ──
 
@@ -138,9 +156,9 @@ class KernelServer:
                     print(f"[kernel] launcher reconnected, cancelled loss timer")
                 print(f"[kernel] launcher connected")
 
-            # Renew heartbeat on connect
-            if module_id in server.registry.modules:
-                server.registry.heartbeat(module_id)
+            # Initialize ping status for new connection
+            if module_id not in server._pong_status:
+                server._pong_status[module_id] = "never"
 
             try:
                 while True:
@@ -231,17 +249,54 @@ class KernelServer:
 
     # ── Background loops ──
 
-    async def _ttl_loop(self):
-        """Check heartbeat TTL every 10s and publish offline events."""
+    async def _ping_broadcast_loop(self):
+        """Broadcast system.ping event every 20s to all connected modules."""
+        import time
+        import uuid
         while True:
-            await asyncio.sleep(10)
             try:
-                expired = self.registry.check_ttl()
-                for mid in expired:
-                    self.event_hub.publish_internal(
-                        "module.offline", {"module_id": mid})
+                await asyncio.sleep(20)
+
+                # Record ping send time for all connected modules
+                t1 = time.time()
+                for module_id in list(self.connections.keys()):
+                    self._ping_sent_times[module_id] = t1
+                    # Mark as timeout if previous ping didn't get pong
+                    if module_id in self._pong_status:
+                        if self._pong_status[module_id] == "ok":
+                            # Previous was ok, now waiting for new pong
+                            pass
+                        elif self._pong_status[module_id] == "never":
+                            # Still never received pong
+                            pass
+                        # If was timeout, keep it as timeout until pong arrives
+
+                # Broadcast system.ping event
+                self.event_hub.publish_internal(
+                    "system.ping",
+                    {"ping_time": t1},
+                    source=self.module_id
+                )
+
+                # Check for timeouts after 20s
+                await asyncio.sleep(20)
+                t_check = time.time()
+                for module_id in list(self.connections.keys()):
+                    if module_id in self._ping_sent_times:
+                        # If no pong received within 20s, mark as timeout
+                        if module_id not in self._pong_latencies or \
+                           self._pong_latencies[module_id].get("last_update", 0) < self._ping_sent_times[module_id]:
+                            if self._pong_status.get(module_id) == "never":
+                                # Keep as "never" if never received
+                                pass
+                            else:
+                                self._pong_status[module_id] = "timeout"
+                                print(f"[kernel] {module_id} ping timeout (no pong in 20s)")
+
+            except asyncio.CancelledError:
+                break
             except Exception as e:
-                print(f"[kernel] TTL loop error: {e}")
+                print(f"[kernel] Ping broadcast loop error: {e}")
 
     async def _dedup_loop(self):
         """Clean up dedup table every 30s."""
@@ -265,7 +320,7 @@ class KernelServer:
         # 5s elapsed, module did not reconnect — mark offline
         self._debounce_tasks.pop(module_id, None)
         self.registry.set_offline(module_id)
-        self.event_hub.publish_internal("module.offline", {"module_id": module_id})
+        self.event_hub.publish_internal("module.offline", {"module_id": module_id}, source=self.module_id)
         print(f"[kernel] {module_id} offline (5s debounce expired)")
 
         # If launcher went offline, start 35s launcher loss timer
@@ -289,7 +344,7 @@ class KernelServer:
         # Publish module.shutdown with reason launcher_lost to all modules
         self.event_hub.publish_internal("module.shutdown", {
             "reason": "launcher_lost",
-        })
+        }, source=self.module_id)
 
         # Wait for modules to clean up (up to 10s)
         await asyncio.sleep(10)
@@ -302,7 +357,7 @@ class KernelServer:
     def self_register(self):
         """Register Kernel itself in the registry (in-memory, no RPC needed)."""
         self.registry.register_module({
-            "module_id": "kernel",
+            "module_id": self.module_id,
             "module_type": "infrastructure",
             "api_endpoint": f"http://{self.advertise_ip}:{self.port}",
             "health_endpoint": "/health",
@@ -313,25 +368,266 @@ class KernelServer:
 
     def publish_ready(self):
         """Publish module.ready event for Kernel (internal, no WS needed)."""
+        import time
+        startup_time = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
         self.event_hub.publish_internal("module.ready", {
-            "module_id": "kernel",
+            "module_id": self.module_id,
             "ws_endpoint": f"ws://{self.advertise_ip}:{self.port}/ws",
             "graceful_shutdown": True,
-        })
+            "startup_time": startup_time,
+        }, source=self.module_id)
+
+    async def _handle_internal_event(self, event_type: str, data: dict):
+        """内部事件处理器（通过 EventHub 回调机制调用）
+
+        Kernel 自身没有 WebSocket 连接，通过此回调接收发送给自己的事件。
+
+        Args:
+            event_type: 事件类型（如 "module.shutdown"）
+            data: 事件数据
+
+        Note:
+            此方法由 EventHub 的 _invoke_callback_safe 包装调用，异常会被捕获并记录。
+        """
+        try:
+            # 处理 Kernel 订阅的事件
+            if event_type == "module.shutdown":
+                await self.handle_shutdown_event(data)
+            elif event_type == "system.pong":
+                await self._handle_pong_event(data)
+            # 忽略系统广播事件（Kernel 没有订阅但会收到广播）
+            elif event_type in ("module.ready", "module.registered", "module.started",
+                                "module.stopped", "module.crashed", "module.exiting",
+                                "module.offline", "system.ready", "registry.updated"):
+                # 这些是系统事件，会广播给所有模块，Kernel 收到是正常的
+                pass
+            else:
+                # 收到未知事件，可能是订阅了但忘记实现处理器
+                print(f"[kernel] Warning: Received unhandled event: {event_type}")
+        except Exception as e:
+            # 双重保险：即使 EventHub 的包装器失败，这里也捕获
+            print(f"[kernel] Error handling internal event {event_type}: {e}")
+            import traceback
+            traceback.print_exc()
+            raise  # 重新抛出，让 EventHub 的包装器记录
+
+    async def _handle_pong_event(self, data: dict):
+        """处理 system.pong 事件，计算往返延迟
+
+        Args:
+            data: {
+                "module_id": str,
+                "ping_time": float,  # t1 - Kernel 发送 ping 的时间
+                "pong_time": float,  # t2 - 模块收到 ping 并发送 pong 的时间
+            }
+        """
+        import time
+        module_id = data.get("module_id")
+        t1 = data.get("ping_time")  # Kernel 发送 ping 的时间
+        t2 = data.get("pong_time")  # 模块收到 ping 并发送 pong 的时间
+        t3 = time.time()  # Kernel 收到 pong 的时间
+
+        if not module_id or t1 is None or t2 is None:
+            print(f"[kernel] Invalid pong event data: {data}")
+            return
+
+        # 验证 ping_time 是否匹配
+        if module_id not in self._ping_sent_times:
+            print(f"[kernel] Received pong from {module_id} but no ping record")
+            return
+
+        expected_t1 = self._ping_sent_times[module_id]
+        if abs(t1 - expected_t1) > 0.1:  # 允许 100ms 误差
+            print(f"[kernel] Pong from {module_id} has mismatched ping_time (expected {expected_t1}, got {t1})")
+            return
+
+        # 计算两个延迟
+        outbound_ms = (t2 - t1) * 1000  # 去程：Kernel → 模块
+        inbound_ms = (t3 - t2) * 1000   # 回程：模块 → Kernel
+
+        self._pong_latencies[module_id] = {
+            "outbound": round(outbound_ms, 2),
+            "inbound": round(inbound_ms, 2),
+            "last_update": t3,
+        }
+        self._pong_status[module_id] = "ok"
+
+    async def handle_shutdown_event(self, event_data):
+        """处理 module.shutdown 事件（标准优雅退出流程）
+
+        Args:
+            event_data: 事件数据，应包含 module_id 字段
+
+        Note:
+            仅响应针对 Kernel 的 shutdown 事件（module_id == "kernel"）。
+            防御性检查：验证数据完整性，防止重复处理。
+        """
+        # 防御性检查：验证数据类型
+        if not isinstance(event_data, dict):
+            print(f"[kernel] Warning: Invalid shutdown event data type: {type(event_data)}")
+            return
+
+        # 防御性检查：验证 module_id
+        target_module = event_data.get("module_id")
+        if target_module != self.module_id:
+            print(f"[kernel] Warning: Received shutdown for wrong module: {target_module}")
+            return
+
+        # 防御性检查：防止重复处理
+        if self._shutting_down:
+            print("[kernel] Warning: Shutdown already in progress, ignoring duplicate event")
+            return
+
+        reason = event_data.get("reason", "unknown")
+        print(f"[kernel] 收到 shutdown 事件 (reason={reason})，开始优雅退出")
+
+        try:
+            # Step 1: 立即发送 ack
+            self.event_hub.publish_internal("module.shutdown.ack", {
+                "module_id": self.module_id
+            }, source=self.module_id)
+            print("[kernel] 已发送 shutdown.ack")
+
+            # Step 2: 发送 exiting
+            self.event_hub.publish_internal("module.exiting", {
+                "module_id": self.module_id,
+                "type": "passive",
+                "reason": f"响应 shutdown ({reason})",
+                "restart": "auto",
+                "action": "none",
+                "timeout": 5.0
+            }, source=self.module_id)
+            print("[kernel] 已发送 exiting")
+
+            # Step 3: 执行清理
+            await self._do_cleanup()
+
+            # Step 4: 发送 ready
+            self.event_hub.publish_internal("module.shutdown.ready", {
+                "module_id": self.module_id
+            }, source=self.module_id)
+            print("[kernel] 已发送 shutdown.ready")
+
+            # Step 5: 等待一小段时间确保事件发送完成
+            await asyncio.sleep(0.2)
+
+            # Step 6: 关闭所有 WebSocket 连接（包括 Launcher）
+            close_tasks = []
+            for mid, ws in list(self.connections.items()):
+                try:
+                    close_tasks.append(ws.close(code=1000, reason="Graceful shutdown complete"))
+                except Exception as e:
+                    print(f"[kernel] 关闭 {mid} 连接失败: {e}")
+
+            if close_tasks:
+                await asyncio.gather(*close_tasks, return_exceptions=True)
+                print(f"[kernel] 已关闭 {len(close_tasks)} 个 WebSocket 连接")
+
+            # Step 7: 触发 uvicorn 关闭
+            if self._uvicorn_server:
+                print("[kernel] 触发 uvicorn 关闭")
+                self._uvicorn_server.should_exit = True
+            else:
+                print("[kernel] uvicorn 引用未设置，直接退出")
+                import sys
+                sys.exit(0)
+
+        except Exception as e:
+            # 如果优雅退出失败，强制退出
+            print(f"[kernel] 优雅退出过程中发生错误: {e}")
+            import traceback
+            traceback.print_exc()
+            print("[kernel] 强制退出")
+            import sys
+            sys.exit(1)
+
+    async def _do_cleanup(self):
+        """执行清理工作（从原 shutdown() 方法提取）"""
+        if self._shutting_down:
+            return
+
+        self._shutting_down = True
+        print("[kernel] 执行清理工作...")
+
+        # 取消所有 debounce 任务
+        if self._debounce_tasks:
+            print(f"[kernel] 取消 {len(self._debounce_tasks)} 个 debounce 任务")
+            for task in self._debounce_tasks.values():
+                if not task.done():
+                    task.cancel()
+            self._debounce_tasks.clear()
+
+        # 取消 launcher loss 计时器
+        if self._launcher_loss_task and not self._launcher_loss_task.done():
+            print("[kernel] 取消 launcher loss 计时器")
+            self._launcher_loss_task.cancel()
+            self._launcher_loss_task = None
+
+        # 关闭其他模块的 WebSocket 连接（保留 Launcher 连接）
+        other_connections = {mid: ws for mid, ws in self.connections.items() if mid != "launcher"}
+        if other_connections:
+            print(f"[kernel] 关闭 {len(other_connections)} 个其他模块的 WebSocket 连接")
+            for module_id, ws in other_connections.items():
+                try:
+                    await ws.close(code=1001, reason="Server shutting down")
+                except Exception as e:
+                    print(f"[kernel] 关闭连接失败 {module_id}: {e}")
+
+        # 清空 RPC 转发队列
+        pending_count = len(self.rpc_router._pending)
+        if pending_count > 0:
+            print(f"[kernel] 清空 {pending_count} 个待处理的 RPC 转发")
+            self.rpc_router._pending.clear()
+
+        print("[kernel] 清理完成")
 
     async def shutdown(self):
-        """Shutdown Kernel gracefully. Called by Launcher via RPC."""
+        """Shutdown Kernel gracefully (legacy method for launcher_lost scenario).
+
+        This method is kept for the launcher_lost timeout scenario where Kernel
+        must shut down autonomously without receiving a shutdown event.
+        """
         if self._shutting_down:
             return
 
         self._shutting_down = True
-        print("[kernel] Shutting down...")
+        print("[kernel] Shutting down (launcher_lost)...")
+
+        # Cancel all debounce tasks
+        print(f"[kernel] Cancelling {len(self._debounce_tasks)} debounce tasks...")
+        for task in self._debounce_tasks.values():
+            if not task.done():
+                task.cancel()
+        self._debounce_tasks.clear()
+
+        # Cancel launcher loss timer
+        if self._launcher_loss_task and not self._launcher_loss_task.done():
+            print("[kernel] Cancelling launcher loss timer...")
+            self._launcher_loss_task.cancel()
+            self._launcher_loss_task = None
+
+        # Close all WebSocket connections
+        print(f"[kernel] Closing {len(self.connections)} WebSocket connections...")
+        for module_id, ws in list(self.connections.items()):
+            try:
+                await ws.close(code=1001, reason="Server shutting down")
+            except Exception as e:
+                print(f"[kernel] Failed to close connection for {module_id}: {e}")
+        self.connections.clear()
 
-        # Brief delay to ensure RPC response is sent
-        await asyncio.sleep(0.1)
+        # Clear pending RPC forwards
+        pending_count = len(self.rpc_router._pending)
+        if pending_count > 0:
+            print(f"[kernel] Clearing {pending_count} pending RPC forwards...")
+            self.rpc_router._pending.clear()
 
         # Trigger uvicorn shutdown
         if self._uvicorn_server:
+            print("[kernel] Triggering uvicorn graceful shutdown...")
             self._uvicorn_server.should_exit = True
         else:
-            print("[kernel] Warning: uvicorn server reference not set")
+            print("[kernel] Warning: uvicorn server reference not set, forcing exit")
+            import sys
+            sys.exit(0)
+
+        print("[kernel] Shutdown complete")

package/kite_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Kite CLI - 模块安装管理工具"""
+
+__version__ = "1.0.0"

package/kite_cli/__main__.py

@@ -0,0 +1,5 @@
+"""支持 python -m kite_cli 调用"""
+from kite_cli.main import main
+
+if __name__ == "__main__":
+    exit(main())

package/kite_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""命令模块"""

package/kite_cli/commands/clean.py

@@ -0,0 +1,101 @@
+"""clean 命令实现 - 清理临时文件和缓存"""
+import shutil
+import tempfile
+from pathlib import Path
+from kite_cli.utils.interactive import confirm_action
+from kite_cli.utils.operation_log import log_operation
+
+
+def run_clean(args):
+    """执行清理命令"""
+    skip_confirm = args.yes if hasattr(args, 'yes') else False
+    clean_all = args.all if hasattr(args, 'all') else False
+
+    cleaned_items = []
+
+    # 1. 清理系统临时目录中的 kite-install-* 目录
+    temp_dir = Path(tempfile.gettempdir())
+    kite_temp_dirs = list(temp_dir.glob("kite-install-*"))
+
+    if kite_temp_dirs:
+        print(f"[Info] 发现 {len(kite_temp_dirs)} 个临时安装目录")
+        if not skip_confirm:
+            if not confirm_action("是否清理临时安装目录？"):
+                print("[Cancelled] 已取消")
+                return 1
+
+        for temp_path in kite_temp_dirs:
+            try:
+                shutil.rmtree(temp_path, ignore_errors=True)
+                cleaned_items.append({"type": "temp_dir", "path": str(temp_path)})
+                print(f"  [Done] 已清理: {temp_path.name}")
+            except Exception as e:
+                print(f"  [Warning] 清理失败: {temp_path.name} - {e}")
+
+    # 2. 如果指定 --all，清理所有模块的 .venv 和 node_modules
+    if clean_all:
+        print("\n[Warning] --all 选项会清理所有模块的依赖环境")
+        if not skip_confirm:
+            if not confirm_action("确认清理所有模块依赖？"):
+                print("[Cancelled] 已取消清理依赖")
+            else:
+                cleaned_items.extend(clean_module_deps())
+        else:
+            cleaned_items.extend(clean_module_deps())
+
+    # 记录操作日志
+    if cleaned_items:
+        log_operation("clean", {
+            "cleaned": cleaned_items
+        }, success=True)
+
+        print(f"\n[Done] 清理完成！共清理 {len(cleaned_items)} 项")
+    else:
+        print("[Info] 没有需要清理的内容")
+
+    return 0
+
+
+def clean_module_deps() -> list:
+    """清理所有模块的依赖环境"""
+    import os
+    from kite_cli.utils.paths import get_install_path
+
+    cleaned = []
+
+    # 遍历所有安装位置
+    for location in ["dev", "local", "global"]:
+        try:
+            base_path = get_install_path(location, "")
+            if not base_path.exists():
+                continue
+
+            # 查找所有模块目录
+            for module_dir in base_path.iterdir():
+                if not module_dir.is_dir():
+                    continue
+
+                # 清理 .venv
+                venv_dir = module_dir / ".venv"
+                if venv_dir.exists():
+                    try:
+                        shutil.rmtree(venv_dir)
+                        cleaned.append({"type": "venv", "path": str(venv_dir)})
+                        print(f"  [Done] 已清理: {module_dir.name}/.venv")
+                    except Exception as e:
+                        print(f"  [Warning] 清理失败: {module_dir.name}/.venv - {e}")
+
+                # 清理 node_modules
+                node_modules = module_dir / "node_modules"
+                if node_modules.exists():
+                    try:
+                        shutil.rmtree(node_modules)
+                        cleaned.append({"type": "node_modules", "path": str(node_modules)})
+                        print(f"  [Done] 已清理: {module_dir.name}/node_modules")
+                    except Exception as e:
+                        print(f"  [Warning] 清理失败: {module_dir.name}/node_modules - {e}")
+
+        except Exception as e:
+            print(f"  [Warning] 扫描 {location} 失败: {e}")
+
+    return cleaned

package/kite_cli/commands/deps_install.py

@@ -0,0 +1,67 @@
+"""
+kite deps-install 命令
+
+只负责安装依赖库
+"""
+
+import sys
+from pathlib import Path
+
+
+def run_deps_install(args):
+    """安装依赖库"""
+    project_root = Path(__file__).parent.parent.parent
+    sys.path.insert(0, str(project_root))
+
+    from core.env_checker import (
+        check_dependencies_installed,
+        install_dependencies,
+        load_dependencies_lock
+    )
+
+    print("=" * 60)
+    print("  Kite 依赖库安装")
+    print("=" * 60)
+    print()
+
+    try:
+        # 1. 加载依赖锁定
+        lock_data = load_dependencies_lock()
+        if not lock_data:
+            print("✓ 无依赖锁定文件，跳过")
+            return 0
+
+        dependencies = lock_data.get("dependencies", {})
+        if not dependencies:
+            print("✓ 无依赖要求，跳过")
+            return 0
+
+        print(f"依赖锁定文件: {len(dependencies)} 个依赖")
+
+        # 2. 检查依赖
+        deps_ok, deps_msg, deps_details = check_dependencies_installed()
+        if deps_ok:
+            print(f"✓ 依赖库已安装且版本一致")
+            return 0
+
+        # 3. 安装依赖
+        print(f"✗ {deps_msg}")
+        if deps_details:
+            if deps_details.get("missing"):
+                print(f"  缺失: {len(deps_details['missing'])} 个")
+            if deps_details.get("version_mismatch"):
+                print(f"  版本不匹配: {len(deps_details['version_mismatch'])} 个")
+
+        print(f"\n正在安装依赖...")
+        if not install_dependencies():
+            print("✗ 依赖安装失败")
+            return 1
+
+        print(f"✓ 依赖安装成功")
+        return 0
+
+    except Exception as e:
+        print(f"\n✗ 依赖安装失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1

package/kite_cli/commands/doctor.py

@@ -0,0 +1,35 @@
+"""doctor 命令实现 - 检查下载工具状态"""
+from kite_cli.core.tool_installer import ToolInstaller
+
+
+def run_doctor(args):
+    """执行环境检查命令"""
+    print("[Doctor] 检查下载工具状态...\n")
+
+    tools = [
+        ("Python", "python"),
+        ("pip", "pip"),
+        ("Node.js", "node"),
+        ("npm", "npm"),
+        ("Git", "git")
+    ]
+
+    all_ok = True
+
+    for name, cmd in tools:
+        status = ToolInstaller.check_tool(cmd)
+        if status:
+            print(f"  [OK] {name:10} 已安装")
+        else:
+            print(f"  [Missing] {name:10} 未安装")
+            all_ok = False
+
+    print()
+
+    if all_ok:
+        print("[Done] 所有工具已就绪")
+        return 0
+    else:
+        print("[Warning] 部分工具未安装")
+        print("[Info] 使用 'kite install' 时会自动尝试安装缺失的工具")
+        return 1