@agentunion/kite 1.3.1 → 1.4.0

package/kernel/server.py

@@ -33,7 +33,10 @@ 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):
+        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
 
@@ -64,6 +67,19 @@ 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"])
+
+        # 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
+
         # Build FastAPI app
         self.app = self._create_app()
 
@@ -75,6 +91,7 @@ class KernelServer:
 
         @app.on_event("startup")
         async def _startup():
+            server.event_hub.start_internal_senders()
             server._ttl_task = asyncio.create_task(server._ttl_loop())
             server._dedup_task = asyncio.create_task(server._dedup_loop())
 
@@ -110,13 +127,27 @@ class KernelServer:
 
             await ws.accept()
 
+            # Cancel debounce timer if module is reconnecting within 5s window
+            old_debounce = server._debounce_tasks.pop(module_id, None)
+            if old_debounce:
+                old_debounce.cancel()
+                print(f"[kernel] {module_id} reconnected within debounce window")
+
             # Register connection in both EventHub and shared connections table
             server.event_hub.add_connection(module_id, ws)
             server.connections[module_id] = ws
 
+            # Set connected status in registry (if module exists)
+            server.registry.set_connected(module_id)
+
             # Track Launcher connection
             if module_id == "launcher":
                 server._launcher_connected = True
+                # Cancel launcher loss timer if reconnecting
+                if server._launcher_loss_task:
+                    server._launcher_loss_task.cancel()
+                    server._launcher_loss_task = None
+                    print(f"[kernel] launcher reconnected, cancelled loss timer")
                 print(f"[kernel] launcher connected")
 
             # Renew heartbeat on connect
@@ -163,12 +194,19 @@ class KernelServer:
                 if "not connected" not in err and "closed" not in err:
                     print(f"[kernel] WebSocket error for {module_id}: {e}")
             finally:
-                # Cleanup
+                # Cleanup connection but DON'T immediately set offline — debounce
                 server.event_hub.remove_connection(module_id)
                 server.connections.pop(module_id, None)
-                server.registry.set_offline(module_id)
-                server.event_hub.publish_internal(
-                    "module.offline", {"module_id": module_id})
+
+                # Cancel existing debounce for this module (if reconnecting fast)
+                old_task = server._debounce_tasks.pop(module_id, None)
+                if old_task:
+                    old_task.cancel()
+
+                # Start 5s debounce timer
+                server._debounce_tasks[module_id] = asyncio.create_task(
+                    server._debounce_offline(module_id)
+                )
 
         # ── HTTP endpoints (debug only) ──
 
@@ -180,7 +218,7 @@ class KernelServer:
                 "module_count": len(server.registry.modules),
                 "online_count": sum(
                     1 for m in server.registry.modules.values()
-                    if m.get("status") == "online"
+                    if m.get("status") in ("registered", "ready")
                 ),
                 "event_stats": eh_health.get("details", {}),
             }
@@ -213,7 +251,7 @@ class KernelServer:
                 expired = self.registry.check_ttl()
                 for mid in expired:
                     self.event_hub.publish_internal(
-                        "module.offline", {"module_id": mid})
+                        "module.offline", {"module_id": mid}, source=self.module_id)
             except Exception as e:
                 print(f"[kernel] TTL loop error: {e}")
 
@@ -227,12 +265,56 @@ class KernelServer:
             except Exception as e:
                 print(f"[kernel] Dedup cleanup error: {e}")
 
+    # ── Debounce & Launcher loss ──
+
+    async def _debounce_offline(self, module_id: str):
+        """Wait 5s after WS disconnect. If module doesn't reconnect, mark offline."""
+        try:
+            await asyncio.sleep(5)
+        except asyncio.CancelledError:
+            return  # Module reconnected within 5s — cancelled by ws_endpoint
+
+        # 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}, source=self.module_id)
+        print(f"[kernel] {module_id} offline (5s debounce expired)")
+
+        # If launcher went offline, start 35s launcher loss timer
+        if module_id == "launcher":
+            self._launcher_connected = False
+            if not self._launcher_loss_task:
+                self._launcher_loss_task = asyncio.create_task(
+                    self._launcher_loss_timeout()
+                )
+
+    async def _launcher_loss_timeout(self):
+        """35s after launcher goes offline (post-debounce). Trigger graceful shutdown."""
+        try:
+            await asyncio.sleep(30)  # 5s debounce already elapsed, total = 35s
+        except asyncio.CancelledError:
+            return  # Launcher reconnected
+
+        print("[kernel] Launcher lost for 35s, triggering graceful shutdown")
+        self._launcher_loss_task = None
+
+        # 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)
+
+        # Shutdown Kernel itself
+        await self.shutdown()
+
     # ── Self-registration ──
 
     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",
@@ -244,24 +326,219 @@ class KernelServer:
     def publish_ready(self):
         """Publish module.ready event for Kernel (internal, no WS needed)."""
         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,
-        })
+        }, 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)
+            # 忽略系统广播事件（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_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/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

package/kite_cli/commands/history.py

@@ -0,0 +1,111 @@
+"""history 命令实现 - 显示最近安装的模块"""
+from kite_cli.utils.operation_log import read_operations
+from kite_cli.utils.i18n import t
+
+
+def run_history(args):
+    """执行历史查看命令"""
+    limit = args.limit if hasattr(args, 'limit') else 6
+    show_all = args.all if hasattr(args, 'all') else False
+
+    # 读取操作日志
+    operations = read_operations(limit=100)  # 读取更多记录用于过滤
+
+    if not operations:
+        print("[Info] 暂无安装记录")
+        return 0
+
+    # 只保留成功的 install 操作
+    install_ops = []
+    seen_modules = set()  # 用于去重
+
+    for op in reversed(operations):  # 从最新到最旧
+        if op.get("operation") == "install" and op.get("success"):
+            details = op.get("details", {})
+            module_name = details.get("module")
+
+            if not module_name:
+                continue
+
+            # 检查是否已被卸载(在此操作之后)
+            is_uninstalled = False
+            for later_op in operations:
+                if later_op.get("timestamp") > op.get("timestamp"):
+                    if later_op.get("operation") == "uninstall" and later_op.get("success"):
+                        uninstall_details = later_op.get("details", {})
+                        if uninstall_details.get("module") == module_name:
+                            is_uninstalled = True
+                            break
+
+            # 如果 show_all=False,只显示未卸载的;如果 show_all=True,显示所有
+            if show_all or not is_uninstalled:
+                # 去重:同一个模块只显示最近一次安装
+                if module_name not in seen_modules:
+                    seen_modules.add(module_name)
+                    install_ops.append({
+                        "timestamp": op.get("timestamp"),
+                        "module": module_name,
+                        "version": details.get("version", "unknown"),
+                        "location": details.get("location", "unknown"),
+                        "source_type": details.get("source", {}).get("type", "unknown"),
+                        "path": details.get("path", ""),
+                        "is_uninstalled": is_uninstalled
+                    })
+
+                    if len(install_ops) >= limit:
+                        break
+
+    if not install_ops:
+        print("[Info] 暂无安装记录")
+        return 0
+
+    print(f"\n[History] 最近安装的 {len(install_ops)} 个模块:\n")
+
+    for i, op in enumerate(install_ops, 1):
+        timestamp = op["timestamp"][:19].replace("T", " ")
+        module = op["module"]
+        version = op["version"]
+        location = op["location"]
+        source_type = op["source_type"]
+        is_uninstalled = op["is_uninstalled"]
+
+        # 状态标记
+        status = "[已卸载]" if is_uninstalled else "[已安装]"
+
+        # 位置标记
+        location_map = {
+            "dev": "开发",
+            "local": "本地",
+            "global": "全局"
+        }
+        location_str = location_map.get(location, location)
+
+        print(f"{i}. {module} v{version}")
+        print(f"   时间: {timestamp}")
+        print(f"   位置: {location_str} ({location})")
+        print(f"   来源: {source_type}")
+        print(f"   状态: {status}")
+
+        # 如果未卸载,显示卸载命令
+        if not is_uninstalled:
+            print(f"   卸载: kite uninstall {module}")
+            if location != "global":
+                print(f"         kite uninstall {module} -l {location}")
+
+        print()
+
+    # 显示快速卸载提示
+    if not show_all:
+        active_modules = [op["module"] for op in install_ops if not op["is_uninstalled"]]
+        if active_modules:
+            print("[Tip] 快速卸载最近安装的模块:")
+            for module in active_modules[:3]:  # 只显示前3个
+                print(f"  kite uninstall {module}")
+            print()
+
+    # 显示查看所有历史的提示
+    if not show_all and len(operations) > limit:
+        print("[Tip] 查看所有历史记录(包括已卸载): kite history --all")
+        print("[Tip] 查看更多记录: kite history -n 20")
+
+    return 0