@agentunion/kite 1.4.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/CHANGELOG.md

@@ -1,3 +1,105 @@
+# v1.5.0
+
+**发布日期**：2026-03-09
+**上一版本**：v1.4.0
+**版本级别**：minor
+
+---
+
+## 核心变更
+
+本次发布新增 **Evol 账户管理模块**（`extensions/services/evol/`），提供完整的 Evol AI 平台账户管理、设备配对、中转服务和 Web UI。同时新增 **环境管理系统**（`core/env_checker.py`、`scripts/env-manager.js`），实现 Python 环境自动检测、依赖安装和版本锁定，确保跨平台一致性。Kite CLI 新增 `prepare` 命令，支持依赖扫描和锁定文件生成。
+
+---
+
+## 变更统计
+
+| 类型 | 数量 | 说明 |
+|------|------|------|
+| 新增 | 368 | evol 模块（36 个）+ 环境管理（6 个）+ kite_cli 命令（4 个）+ 其他 |
+| 删除 | 2 | CHANGELOG.md、package.json（版本更新） |
+| 修改 | 21 | 核心入口、模块定义、服务实现 |
+
+---
+
+## 关键变更
+
+### 新增模块
+
+**`extensions/services/evol/`** (36 个文件)
+- **账户管理**：`auth_manager.py` (登录认证), `evol_api.py` (API 封装), `config_loader.py` (配置加载)
+- **设备配对**：`pairing.py` (配对码管理), `pairing_codes.jsonl` (持久化存储), `migrate_tokens.py` (Token 迁移)
+- **中转服务**：`relay.py` (Kernel WebSocket 中转), `relay_config.json5` (中转配置)
+- **路由系统**：`routes_management_ws.py` (WebSocket 管理), `routes_rpc.py` (RPC 转发), `routes_test.py` (测试接口)
+- **Web UI**：完整的前端界面（HTML/CSS/JS），支持登录、配对、中转测试
+- **配置文件**：`config.yaml`, `evol_config.json5` (多层配置系统)
+
+**`core/` 环境管理** (2 个文件)
+- `env_checker.py` — Python 环境检测、依赖安装、版本验证
+- `dependency_checker.py` — 依赖扫描和锁定文件生成
+
+**`scripts/` 环境脚本** (4 个文件)
+- `env-manager.js` — Node.js 环境管理器（PYTHONPATH 修复）
+- `python-env.js` — Python 环境检测和安装
+- `setup-python-env.js` — npm postinstall 钩子
+- `scan_dependencies.py` — 依赖扫描工具
+
+**`kite_cli/commands/`** (4 个文件)
+- `prepare.py` — 打包准备命令（依赖锁定 + Python 版本记录）
+- 其他命令增强
+
+### 删除内容
+
+- **`CHANGELOG.md`** — 将被新版本覆盖
+- **`package.json`** — 版本号更新为 1.5.0
+
+### 入口变更
+
+**`main.py`** — 行数变化：18 行 → 21 行
+- 新增环境检查逻辑
+- 优化启动流程
+
+**`cli.js`** — 新增环境管理器调用
+- 启动前检查 Python 环境
+- 自动修复 PYTHONPATH
+
+---
+
+## 架构演进
+
+| 版本 | 核心模块 | CLI 命令 | 服务模块 | 包文件数 |
+|------|---------|---------|---------|---------|
+| v1.3.2 | 2 (kernel, launcher) | 10 | 5 | 88 |
+| v1.4.0 | 2 (kernel, launcher) | 11 | 5 | 134 |
+| v1.5.0 | 2 (kernel, launcher) | 12 | 6 (新增 evol) | 499 |
+
+---
+
+## 设计原则
+
+- ✅ **零共享代码依赖** — evol 模块可独立拷贝使用
+- ✅ **跨平台兼容** — 环境管理支持 Windows/Linux/macOS
+- ✅ **版本锁定** — `dependencies_lock.json` + `python_version.json` 确保环境一致性
+- ✅ **自动化安装** — npm postinstall 自动检测和安装 Python 依赖
+
+---
+
+## 包信息
+
+- **文件数**：499（+365 vs v1.4.0）
+- **打包大小**：待验证
+- **解压大小**：待验证
+
+---
+
+## 兼容性说明
+
+本次发布为 minor 版本，向后兼容。新增功能不影响现有模块运行。
+
+- ✅ CLI 接口保持兼容（`kite` 命令）
+- ✅ Kernel WebSocket 协议保持兼容
+- ✅ 现有模块无需修改即可运行
+- ✅ 新增 `kite prepare` 命令，不影响现有命令
 # v1.4.0
 
 **发布日期**：2026-03-07

package/cli.js

@@ -20,6 +20,7 @@ const { spawn, execSync } = require('child_process');
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { ensureEnvironment, markEnvFailed } = require('./scripts/env-manager');
 
 // Timestamped console.log with delta + color
 const _origLog = console.log.bind(console);
@@ -125,7 +126,7 @@ if (args[0] === 'start') {
 
   // Only execute if we have a valid working directory
   if (fs.existsSync(path.join(cliWorkDir, 'kite_cli', '__init__.py'))) {
-    // Delegate to kite_cli
+    // Use system Python (env_checker will handle venv)
     const python = process.platform === 'win32' ? 'python' : 'python3';
     const cliArgs = ['-m', 'kite_cli', ...args];
     const result = spawn(python, cliArgs, {
@@ -209,6 +210,13 @@ if (!fs.existsSync(path.join(versionDir, 'main.py'))) {
   install();
 }
 
+// 环境检查和准备（Node.js 层）
+console.log('[kite] 检查环境...');
+if (!ensureEnvironment(versionDir)) {
+  console.error('[kite] 环境准备失败，无法启动');
+  process.exit(1);
+}
+
 const kiteCwd = cwdOverride || process.cwd();
 
 console.log(`[kite] 版本:     ${useVersion}`);
@@ -228,20 +236,85 @@ const env = {
   PYTHONUTF8: '1',
 };
 
-const python = process.platform === 'win32' ? 'python' : 'python3';
+// Use venv Python (确保使用虚拟环境)
+const venvPath = path.join(kiteHome, 'venv');
+const python = process.platform === 'win32'
+  ? path.join(venvPath, 'Scripts', 'python.exe')
+  : path.join(venvPath, 'bin', 'python');
+
+// 检查虚拟环境 Python 是否存在
+if (!fs.existsSync(python)) {
+  console.error(`[kite] 虚拟环境 Python 不存在: ${python}`);
+  console.error(`[kite] 环境准备可能失败，请重新运行 kite start`);
+  process.exit(1);
+}
+
+console.log(`[kite] Python:   ${python}`);
+
 const child = spawn(
   python,
-  ['-m', 'launcher', ...pythonArgs],
+  [path.join(versionDir, 'main.py'), ...pythonArgs],
   { cwd: versionDir, env, stdio: 'inherit' }
 );
 
 child.on('error', err => {
   console.error(`[kite] 启动 Python 失败: ${err.message}`);
-  console.error(`[kite] 请确认 '${python}' 在 PATH 中且依赖已安装`);
+  console.error(`[kite] 请确认 Python 3.8+ 已安装`);
+  console.error(`[kite] 或运行: npm install 重新准备环境`);
+
+  // 标记环境失败
+  markEnvFailed('python_launch_failed');
   process.exit(1);
 });
 
-child.on('exit', code => process.exit(code ?? 0));
+child.on('exit', (code, signal) => {
+  // 如果是异常退出，检查是否是环境问题
+  if (code !== 0 && code !== null) {
+    console.error(`[kite] Python 进程异常退出，退出码: ${code}`);
+
+    // 读取 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');
+    }
+  }
+
+  process.exit(code ?? 0);
+});
 
 for (const sig of ['SIGINT', 'SIGTERM']) {
   process.on(sig, () => child.kill(sig));