@agentunion/kite 1.5.0 → 1.6.0

package/.claude/skills/kite/templates/python/server_http.py

@@ -0,0 +1,433 @@
+"""
+{{DISPLAY_NAME}} — HTTP service with WebSocket client to Kernel.
+Uses FastAPI + uvicorn for HTTP, connects to Kernel via WebSocket JSON-RPC 2.0.
+"""
+
+import asyncio
+import json
+import os
+import random
+import time
+import uuid
+
+try:
+    import websockets
+except ImportError:
+    raise ImportError("websockets is required: pip install websockets")
+
+from fastapi import FastAPI
+
+
+class {{SERVER_CLASS}}:
+    def __init__(self, token, kernel_port, host, port, boot_t0,
+                 max_connections=1, max_instances=1, instance_elastic=False,
+                 gateway_url="", kite_token=""):
+        self.token = token
+        self._kernel_port = kernel_port
+        self._host = host
+        self._port = port
+        self._boot_t0 = boot_t0
+        self._max_connections = max_connections
+        self._max_instances = max_instances
+        self._instance_elastic = instance_elastic
+        self._gateway_url = gateway_url
+        self._kite_token = kite_token
+
+        self._module_name = "{{MODULE_NAME}}"
+        self._module_type = "{{MODULE_TYPE}}"
+        self._display_name = "{{DISPLAY_NAME}}"
+
+        self._ws = None
+        self._ws_task = None
+        self._test_task = None
+        self._uvicorn_server = None
+        self._shutting_down = False
+        self._exit_code = 0
+        self._start_time = time.time()
+        self._pending_rpc: dict[str, asyncio.Future] = {}
+        self._extra_ws: dict = {}
+        self._extra_ws_tasks: dict = {}
+        self._handler_capacity = 100
+        self._active_handlers = 0
+
+        self.app = self._create_app()
+
+    def _create_app(self) -> FastAPI:
+        app = FastAPI(title=self._module_name)
+        server = self
+
+        @app.on_event("startup")
+        async def _startup():
+            server._ws_task = asyncio.create_task(server._ws_loop())
+            server._test_task = asyncio.create_task(server._test_event_loop())
+
+        @app.on_event("shutdown")
+        async def _shutdown():
+            server._shutting_down = True
+            if server._ws_task:
+                server._ws_task.cancel()
+            if server._test_task:
+                server._test_task.cancel()
+            if server._ws:
+                try: await server._ws.close()
+                except Exception: pass
+
+        @app.get("/health")
+        async def health():
+            return {"status": "ok", "module": server._module_name}
+
+        # TODO: Add your routes here
+        # from fastapi import APIRouter
+        # router = APIRouter(prefix="/api")
+        # @router.get("/example")
+        # async def example():
+        #     return {"message": "hello"}
+        # app.include_router(router)
+
+        return app
+
+    # ── WebSocket Connection ──
+
+    async def _ws_loop(self):
+        retry_delay = 0.3
+        max_delay = 5.0
+        max_retries = 10
+
+        for attempt in range(max_retries):
+            try:
+                uri = f"ws://127.0.0.1:{self._kernel_port}/ws"
+                async with websockets.connect(uri, max_size=16 * 1024 * 1024) as ws:
+                    self._ws = ws
+                    retry_delay = 0.3
+                    await self._ws_connect(ws)
+            except websockets.ConnectionClosedError as e:
+                if e.code in (4001, 4003, 4004, 1008, 4010):
+                    print(f"[{self._module_name}] Fatal close code={e.code}")
+                    return
+                if e.code == 4020:
+                    await asyncio.sleep(10)
+                    continue
+            except (ConnectionRefusedError, OSError) as e:
+                if hasattr(e, 'winerror') and e.winerror == 1225:
+                    pass
+                elif isinstance(e, ConnectionRefusedError):
+                    pass
+                else:
+                    print(f"[{self._module_name}] Connection error: {e}")
+            except Exception as e:
+                print(f"[{self._module_name}] Unexpected error: {e}")
+
+            if self._shutting_down:
+                return
+
+            for rid, fut in self._pending_rpc.items():
+                if not fut.done():
+                    fut.set_exception(ConnectionError("Disconnected"))
+            self._pending_rpc.clear()
+
+            jitter = retry_delay * 0.2 * random.random()
+            await asyncio.sleep(retry_delay + jitter)
+            retry_delay = min(retry_delay * 2, max_delay)
+
+    async def _ws_connect(self, ws):
+        auth_id = str(uuid.uuid4())
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0", "id": auth_id,
+            "method": "auth", "params": {"token": self.token},
+        }))
+        resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        if resp.get("error") or not resp.get("result", {}).get("ok"):
+            print(f"[{self._module_name}] Auth failed: {resp}")
+            return
+
+        print(f"[{self._module_name}] Authenticated")
+
+        async for raw in ws:
+            msg = json.loads(raw)
+            has_method = "method" in msg
+            has_id = "id" in msg
+            has_result = "result" in msg
+            has_error = "error" in msg
+
+            if has_method and has_id:
+                asyncio.create_task(self._handle_rpc_request(ws, msg))
+            elif has_method and not has_id:
+                asyncio.create_task(self._handle_event_notification(msg))
+            elif has_id and (has_result or has_error):
+                self._handle_rpc_response(msg)
+
+    # ── RPC (identical to server.py) ──
+
+    async def _rpc_call(self, ws, method: str, params: dict = None,
+                        wait_response: bool = True, timeout: float = 3.0):
+        req_id = str(uuid.uuid4())
+        msg = {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params or {}}
+        await ws.send(json.dumps(msg))
+        if not wait_response:
+            return None
+        future = asyncio.get_event_loop().create_future()
+        self._pending_rpc[req_id] = future
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self._pending_rpc.pop(req_id, None)
+            return {"error": {"code": -32002, "message": f"Timeout: {method}"}}
+
+    def _handle_rpc_response(self, msg: dict):
+        req_id = msg.get("id")
+        future = self._pending_rpc.pop(req_id, None)
+        if future and not future.done():
+            if "error" in msg:
+                future.set_result(msg)
+            else:
+                future.set_result(msg.get("result", {}))
+
+    async def _handle_rpc_request(self, ws, msg: dict):
+        method = msg.get("method", "")
+        params = msg.get("params", {})
+        req_id = msg.get("id")
+        bare = method.split(".")[-1] if "." in method else method
+
+        handlers = {
+            "health": self._rpc_health,
+            "status": self._rpc_status,
+        }
+
+        handler = handlers.get(bare)
+        if not handler:
+            await ws.send(json.dumps({
+                "jsonrpc": "2.0", "id": req_id,
+                "error": {"code": -32601, "message": f"Method not found: {method}"},
+            }))
+            return
+
+        self._active_handlers += 1
+        try:
+            result = await handler(params)
+            await ws.send(json.dumps({"jsonrpc": "2.0", "id": req_id, "result": result}))
+        except Exception as e:
+            await ws.send(json.dumps({
+                "jsonrpc": "2.0", "id": req_id,
+                "error": {"code": -32603, "message": str(e)},
+            }))
+        finally:
+            self._active_handlers -= 1
+
+    async def _rpc_health(self, params: dict) -> dict:
+        try:
+            import psutil
+            mem_mb = round(psutil.Process(os.getpid()).memory_info().rss / 1024 / 1024, 1)
+        except Exception:
+            mem_mb = -1
+
+        fw = {
+            "uptime": time.time() - self._start_time,
+            "connections": 1 + len(self._extra_ws),
+            "pending_rpc": len(self._pending_rpc),
+            "active_handlers": self._active_handlers,
+            "handler_capacity": self._handler_capacity,
+            "pressure": self._compute_pressure_level(),
+            "memory_mb": mem_mb,
+        }
+        biz = self._check_business_health()
+        return {
+            "healthy": biz["healthy"] and fw["pressure"] != "critical",
+            "framework": fw,
+            "business": biz,
+        }
+
+    def _check_business_health(self) -> dict:
+        return {"healthy": True, "message": "正常运行中", "details": []}
+
+    def _compute_pressure_level(self) -> str:
+        depth = self._active_handlers + len(self._pending_rpc)
+        ratio = depth / self._handler_capacity if self._handler_capacity > 0 else 0
+        if ratio >= 0.9: return "critical"
+        elif ratio >= 0.5: return "overload"
+        elif depth > 0: return "normal"
+        return "idle"
+
+    async def _rpc_status(self, params: dict) -> dict:
+        return {
+            "module": self._module_name, "state": "running",
+            "connections": 1 + len(self._extra_ws),
+            "pending_rpc": len(self._pending_rpc),
+            "http_port": self._port,
+        }
+
+    # ── Events (identical to server.py) ──
+
+    async def _publish_event(self, ws, event: str, data: dict = None):
+        await self._rpc_call(ws, "event.publish", {
+            "event_id": str(uuid.uuid4()), "event": event, "data": data or {},
+        }, wait_response=False)
+
+    async def _handle_event_notification(self, msg: dict):
+        params = msg.get("params", {})
+        event_type = params.get("event", "")
+        data = params.get("data", {})
+
+        if event_type == "system.require_init":
+            asyncio.create_task(self._do_init(self._ws))
+            return
+        if event_type == "system.ping":
+            await self._handle_ping(data)
+            return
+        if event_type == "system.connection.offer":
+            asyncio.create_task(self._handle_connection_offer(data))
+            return
+        if event_type == "system.connection.release":
+            asyncio.create_task(self._handle_connection_release(data))
+            return
+        if event_type == "module.shutdown":
+            await self._handle_shutdown(self._ws)
+            return
+
+        _IGNORE = {
+            "module.ready", "module.registered", "module.started", "module.stopped",
+            "module.crashed", "module.exiting", "module.offline",
+            "module.shutdown.ack", "module.shutdown.ready",
+            "system.ready", "registry.updated",
+            "system.instance.started", "system.instance.stopped",
+        }
+        if event_type in _IGNORE:
+            return
+
+        print(f"[{self._module_name}] Event: {event_type}")
+
+    # ── Initialization ──
+
+    async def _do_init(self, ws):
+        await self._rpc_call(ws, "event.subscribe", {
+            "events": [
+                "module.started", "module.stopped", "module.crashed",
+                "module.ready", "module.exiting", "module.shutdown",
+                "module.shutdown.ack", "module.shutdown.ready",
+                "system.ping",
+            ]
+        })
+
+        await self._rpc_call(ws, "registry.register", {
+            "module_id": self._module_name,
+            "module_type": self._module_type,
+            "name": self._display_name,
+            "port": self._port,
+            "base_url": f"http://{self._host}:{self._port}",
+            "tools": {
+                "rpc": {
+                    "module": {
+                        "health": {"description": "健康检查"},
+                        "status": {"description": "状态查询"},
+                    }
+                }
+            },
+            "events_publish": {
+                self._module_name: {
+                    "test": {"description": "测试事件"},
+                }
+            },
+            "events_subscribe": [
+                "module.started", "module.stopped", "module.shutdown",
+            ],
+        })
+
+        await self._publish_event(ws, "module.ready", {"module_id": self._module_name})
+        print(f"[{self._module_name}] Ready (HTTP on :{self._port})")
+
+    # ── Ping/Pong ──
+
+    async def _handle_ping(self, data: dict):
+        await self._publish_event(self._ws, "system.pong", {
+            "module_id": self._module_name,
+            "ping_time": data.get("ping_time"),
+            "pong_time": time.time(),
+        })
+
+    # ── Graceful Shutdown ──
+
+    async def _handle_shutdown(self, ws):
+        print(f"[{self._module_name}] Received module.shutdown")
+        self._shutting_down = True
+
+        await self._publish_event(ws, "module.shutdown.ack", {
+            "module_id": self._module_name, "estimated_cleanup": 2,
+        })
+        await self._publish_event(ws, "module.exiting", {
+            "module_id": self._module_name, "action": "none",
+        })
+        await self._publish_event(ws, "module.shutdown.ready", {
+            "module_id": self._module_name,
+        })
+        await asyncio.sleep(0.01)
+
+        for slot, extra_ws in list(self._extra_ws.items()):
+            try: await extra_ws.close(code=1000, reason="shutdown")
+            except Exception: pass
+        self._extra_ws.clear()
+
+        try:
+            await ws.close(code=1000, reason="Graceful shutdown")
+        except Exception: pass
+
+        if self._uvicorn_server:
+            self._uvicorn_server.should_exit = True
+
+    # ── Multi-connection ──
+
+    async def _handle_connection_offer(self, data: dict):
+        slot = data.get("slot")
+        slot_token = data.get("token")
+        if slot is None or not slot_token or slot in self._extra_ws:
+            return
+        try:
+            uri = f"ws://127.0.0.1:{self._kernel_port}/ws"
+            ws = await websockets.connect(uri, max_size=16 * 1024 * 1024)
+            await ws.send(json.dumps({
+                "jsonrpc": "2.0", "id": str(uuid.uuid4()),
+                "method": "auth", "params": {"token": slot_token},
+            }))
+            resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            if resp.get("error") or not resp.get("result", {}).get("ok"):
+                await ws.close()
+                return
+            self._extra_ws[slot] = ws
+            self._extra_ws_tasks[slot] = asyncio.create_task(self._slot_recv_loop(ws, slot))
+        except Exception as e:
+            print(f"[{self._module_name}] Slot {slot} failed: {e}")
+
+    async def _slot_recv_loop(self, ws, slot: int):
+        try:
+            async for raw in ws:
+                msg = json.loads(raw)
+                if "method" in msg and "id" in msg:
+                    asyncio.create_task(self._handle_rpc_request(ws, msg))
+                elif "method" in msg:
+                    asyncio.create_task(self._handle_event_notification(msg))
+                elif "id" in msg:
+                    self._handle_rpc_response(msg)
+        except websockets.ConnectionClosedError:
+            pass
+        finally:
+            self._extra_ws.pop(slot, None)
+            self._extra_ws_tasks.pop(slot, None)
+
+    async def _handle_connection_release(self, data: dict):
+        slot = data.get("slot")
+        ws = self._extra_ws.pop(slot, None)
+        if ws:
+            try: await ws.close(code=1000, reason="released")
+            except Exception: pass
+        task = self._extra_ws_tasks.pop(slot, None)
+        if task: task.cancel()
+
+    # ── Test Event Loop ──
+
+    async def _test_event_loop(self):
+        while not self._shutting_down:
+            await asyncio.sleep(12)
+            if self._shutting_down:
+                break
+            if self._ws:
+                await self._publish_event(self._ws, f"{self._module_name}.test", {
+                    "timestamp": time.time(),
+                })

package/cli.js

@@ -272,10 +272,44 @@ child.on('exit', (code, signal) => {
   if (code !== 0 && code !== null) {
     console.error(`[kite] Python 进程异常退出，退出码: ${code}`);
 
-    // 常见的环境相关错误码
-    if (code === 1 || code === 127) {
-      console.error(`[kite] 可能是环境问题，下次启动将重新检查环境`);
-      markEnvFailed('python_runtime_error');
+    // 读取 Kernel 日志，检查是否是依赖问题
+    // KITE_INSTANCE_DIR 由 Launcher 设置，格式为 ~/.kite/workspace/Kite
+    const workspaceDir = path.join(kiteHome, 'workspace');
+    const instanceDir = path.join(workspaceDir, 'Kite');
+    const kernelLog = path.join(instanceDir, 'kernel', 'log', 'latest.log');
+
+    let isDependencyIssue = false;
+
+    if (fs.existsSync(kernelLog)) {
+      try {
+        const log = fs.readFileSync(kernelLog, 'utf-8');
+
+        // 检测依赖相关错误
+        const depErrors = [
+          'ImportError',
+          'ModuleNotFoundError',
+          'not installed',
+          'cannot parse module.md',
+          'No module named',
+          'Failed to import'
+        ];
+
+        for (const errorPattern of depErrors) {
+          if (log.includes(errorPattern)) {
+            isDependencyIssue = true;
+            console.error(`[kite] 检测到依赖问题: ${errorPattern}`);
+            break;
+          }
+        }
+      } catch (e) {
+        // 读取日志失败，忽略
+      }
+    }
+
+    // 如果检测到依赖问题，或者是常见的环境错误码
+    if (isDependencyIssue || code === 1 || code === 127) {
+      console.error(`[kite] 下次启动将重新检查环境`);
+      markEnvFailed(isDependencyIssue ? 'dependency_import_error' : 'python_runtime_error');
     }
   }
 

package/core/env_checker.py

@@ -291,6 +291,84 @@ def check_dependencies_installed() -> Tuple[bool, str, Dict]:
     return True, "依赖正常", {}
 
 
+def verify_imports() -> Tuple[bool, str, list]:
+    """
+    验证关键依赖是否能被 import
+
+    Returns:
+        (all_ok, message, failed_list)
+    """
+    lock_data = load_dependencies_lock()
+
+    if not lock_data:
+        return True, "无依赖锁定文件", []
+
+    dependencies = lock_data.get("dependencies", {})
+
+    if not dependencies:
+        return True, "无依赖要求", []
+
+    # import 名称映射（与 scan_dependencies.py 保持一致）
+    IMPORT_TO_PACKAGE = {
+        'yaml': 'pyyaml',
+        'dotenv': 'python-dotenv',
+        'cv2': 'opencv-python',
+        'PIL': 'pillow',
+        'sklearn': 'scikit-learn',
+        'bs4': 'beautifulsoup4',
+        'dateutil': 'python-dateutil',
+        'OpenSSL': 'pyopenssl',
+        'nacl': 'pynacl',
+        'jwt': 'pyjwt',
+        'Crypto': 'pycryptodome',
+        'magic': 'python-magic',
+        'docx': 'python-docx',
+        'MySQLdb': 'mysqlclient',
+        'psycopg2': 'psycopg2-binary',
+        'bson': 'pymongo',
+        'serial': 'pyserial',
+        'gi': 'pygobject',
+    }
+
+    # 反向映射：package -> import
+    PACKAGE_TO_IMPORT = {v: k for k, v in IMPORT_TO_PACKAGE.items()}
+
+    # 关键依赖（kernel/launcher 必需）
+    critical_packages = {'pyyaml', 'fastapi', 'uvicorn', 'starlette', 'websockets', 'pydantic'}
+
+    failed = []
+
+    for package_name in dependencies.keys():
+        # 只验证关键依赖
+        if package_name not in critical_packages:
+            continue
+
+        # 获取 import 名称
+        import_name = PACKAGE_TO_IMPORT.get(package_name, package_name)
+
+        try:
+            __import__(import_name)
+        except ImportError as e:
+            failed.append({
+                "package": package_name,
+                "import_name": import_name,
+                "error": str(e)
+            })
+        except Exception as e:
+            # 其他异常也记录
+            failed.append({
+                "package": package_name,
+                "import_name": import_name,
+                "error": f"Unexpected error: {e}"
+            })
+
+    if failed:
+        msg = f"{len(failed)} 个关键依赖无法导入"
+        return False, msg, failed
+
+    return True, "导入验证通过", []
+
+
 def install_dependencies() -> bool:
     """安装依赖（根据 dependencies_lock.json）"""
     lock_data = load_dependencies_lock()
@@ -396,6 +474,24 @@ def run_full_check() -> Tuple[bool, Dict]:
 
     print(f"[环境检查] ✓ 依赖库: {deps_msg}")
 
+    # 4. 验证关键依赖能否导入
+    import_ok, import_msg, import_failed = verify_imports()
+    if not import_ok:
+        print(f"[环境检查] ✗ 导入验证: {import_msg}")
+
+        if import_failed:
+            for item in import_failed:
+                print(f"  {item['package']} ({item['import_name']}): {item['error']}")
+
+        error_data = {
+            "type": "import_failed",
+            "message": "关键依赖无法导入",
+            "details": {"failed": import_failed}
+        }
+        return False, error_data
+
+    print(f"[环境检查] ✓ 导入验证: {import_msg}")
+
     print("[环境检查] 完整诊断通过")
     return True, {}