@agentunion/kite 1.4.0 → 1.5.0

package/core/env_checker.py

@@ -0,0 +1,490 @@
+"""
+Kite 环境检查器（版本锁定）
+
+负责检查和准备 Python 运行环境：
+1. 检查 Python 版本是否与 python_version.json 一致
+2. 检查虚拟环境是否存在
+3. 检查依赖库是否与 dependencies_lock.json 一致
+4. 维护状态记录文件 ~/.kite/env_status.json
+
+状态记录机制：
+- 成功时：记录 status = "success"，下次启动跳过检查
+- 失败时：记录 status = "failed" + 结构化错误信息，下次启动进行完整诊断
+"""
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+
+def get_kite_data_path() -> Path:
+    """获取 KITE_DATA 路径"""
+    return Path.home() / ".kite"
+
+
+def get_venv_path() -> Path:
+    """获取虚拟环境路径"""
+    return get_kite_data_path() / "venv"
+
+
+def get_status_file_path() -> Path:
+    """获取状态记录文件路径"""
+    return get_kite_data_path() / "env_status.json"
+
+
+def get_requirements_path() -> Path:
+    """获取 requirements.txt 路径（已废弃，使用 dependencies_lock.json）"""
+    return Path(__file__).parent.parent / "requirements.txt"
+
+
+def get_dependencies_lock_path() -> Path:
+    """获取依赖锁定文件路径"""
+    return Path(__file__).parent.parent / "dependencies_lock.json"
+
+
+def get_python_version_file_path() -> Path:
+    """获取 Python 版本文件路径"""
+    return Path(__file__).parent.parent / "python_version.json"
+
+
+def load_dependencies_lock() -> Optional[Dict]:
+    """加载依赖锁定文件"""
+    lock_file = get_dependencies_lock_path()
+
+    if not lock_file.exists():
+        return None
+
+    try:
+        with open(lock_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"[环境检查] 读取依赖锁定文件失败: {e}")
+        return None
+
+
+def get_required_python_version() -> Optional[str]:
+    """获取要求的 Python 版本"""
+    version_file = get_python_version_file_path()
+
+    if not version_file.exists():
+        return None
+
+    try:
+        with open(version_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            return data.get("version")
+    except Exception as e:
+        print(f"[环境检查] 读取 Python 版本文件失败: {e}")
+        return None
+
+
+def calculate_requirements_hash() -> str:
+    """计算 dependencies_lock.json 的 hash"""
+    lock_file = get_dependencies_lock_path()
+
+    if not lock_file.exists():
+        return ""
+
+    with open(lock_file, "rb") as f:
+        return hashlib.sha256(f.read()).hexdigest()[:16]
+
+
+def load_status() -> Optional[Dict]:
+    """加载状态记录"""
+    status_file = get_status_file_path()
+
+    if not status_file.exists():
+        return None
+
+    try:
+        with open(status_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"[环境检查] 读取状态文件失败: {e}")
+        return None
+
+
+def save_status(status_data: Dict):
+    """保存状态记录"""
+    status_file = get_status_file_path()
+    status_file.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(status_file, "w", encoding="utf-8") as f:
+        json.dump(status_data, f, indent=2, ensure_ascii=False)
+
+
+def check_python_version() -> Tuple[bool, str, str]:
+    """
+    检查 Python 版本是否与要求一致
+
+    Returns:
+        (is_match, current_version, required_version)
+    """
+    current_version = sys.version_info
+    current_version_str = f"{current_version.major}.{current_version.minor}.{current_version.micro}"
+
+    required_version = get_required_python_version()
+
+    if not required_version:
+        # 没有版本要求文件，降级为 3.8+ 检查
+        if current_version.major == 3 and current_version.minor >= 8:
+            return True, current_version_str, "3.8+"
+        else:
+            return False, current_version_str, "3.8+"
+
+    # 精确版本匹配
+    if current_version_str == required_version:
+        return True, current_version_str, required_version
+    else:
+        return False, current_version_str, required_version
+
+
+def check_venv_exists() -> Tuple[bool, str]:
+    """检查虚拟环境是否存在"""
+    venv_path = get_venv_path()
+
+    if not venv_path.exists():
+        return False, "虚拟环境目录不存在"
+
+    # 检查关键文件
+    if os.name == "nt":  # Windows
+        python_exe = venv_path / "Scripts" / "python.exe"
+        pip_exe = venv_path / "Scripts" / "pip.exe"
+    else:  # Linux / macOS
+        python_exe = venv_path / "bin" / "python"
+        pip_exe = venv_path / "bin" / "pip"
+
+    if not python_exe.exists():
+        return False, "虚拟环境 python 不存在"
+
+    if not pip_exe.exists():
+        return False, "虚拟环境 pip 不存在"
+
+    return True, "虚拟环境正常"
+
+
+def create_venv() -> bool:
+    """创建虚拟环境"""
+    venv_path = get_venv_path()
+
+    print(f"[环境检查] 正在创建虚拟环境: {venv_path}")
+
+    try:
+        venv_path.parent.mkdir(parents=True, exist_ok=True)
+
+        subprocess.run(
+            [sys.executable, "-m", "venv", str(venv_path)],
+            check=True,
+            capture_output=True,
+            text=True
+        )
+
+        print(f"[环境检查] 虚拟环境创建成功")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"[环境检查] 虚拟环境创建失败: {e.stderr}")
+        return False
+
+
+def get_venv_pip() -> Path:
+    """获取虚拟环境的 pip 路径"""
+    venv_path = get_venv_path()
+
+    if os.name == "nt":  # Windows
+        return venv_path / "Scripts" / "pip.exe"
+    else:  # Linux / macOS
+        return venv_path / "bin" / "pip"
+
+
+def check_dependencies_installed() -> Tuple[bool, str, Dict]:
+    """
+    检查依赖是否与 dependencies_lock.json 一致
+
+    Returns:
+        (all_ok, message, details)
+    """
+    lock_data = load_dependencies_lock()
+
+    if not lock_data:
+        return True, "无依赖锁定文件", {}
+
+    dependencies = lock_data.get("dependencies", {})
+
+    if not dependencies:
+        return True, "无依赖要求", {}
+
+    pip_path = get_venv_pip()
+
+    if not pip_path.exists():
+        return False, "pip 不存在", {}
+
+    # 检查每个依赖（使用虚拟环境的 pip）
+    missing = []
+    version_mismatch = []
+
+    for package_name, package_info in dependencies.items():
+        required_version = package_info.get("version")
+
+        # 使用虚拟环境的 pip show 检查包
+        try:
+            result = subprocess.run(
+                [str(pip_path), "show", package_name],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+
+            if result.returncode != 0:
+                # 包不存在
+                missing.append({
+                    "package": package_name,
+                    "required": required_version
+                })
+            else:
+                # 解析 pip show 输出获取版本
+                installed_version = None
+                for line in result.stdout.split('\n'):
+                    if line.startswith('Version:'):
+                        installed_version = line.split(':', 1)[1].strip()
+                        break
+
+                if installed_version and installed_version != required_version:
+                    version_mismatch.append({
+                        "package": package_name,
+                        "required": required_version,
+                        "installed": installed_version
+                    })
+
+        except subprocess.TimeoutExpired:
+            # 超时视为缺失
+            missing.append({
+                "package": package_name,
+                "required": required_version
+            })
+        except Exception:
+            # 其他错误视为缺失
+            missing.append({
+                "package": package_name,
+                "required": required_version
+            })
+
+    if missing or version_mismatch:
+        details = {
+            "missing": missing,
+            "version_mismatch": version_mismatch
+        }
+
+        msg_parts = []
+        if missing:
+            msg_parts.append(f"{len(missing)} 个缺失")
+        if version_mismatch:
+            msg_parts.append(f"{len(version_mismatch)} 个版本不匹配")
+
+        return False, ", ".join(msg_parts), details
+
+    return True, "依赖正常", {}
+
+
+def install_dependencies() -> bool:
+    """安装依赖（根据 dependencies_lock.json）"""
+    lock_data = load_dependencies_lock()
+
+    if not lock_data:
+        print("[环境检查] 无依赖锁定文件，跳过依赖安装")
+        return True
+
+    dependencies = lock_data.get("dependencies", {})
+
+    if not dependencies:
+        print("[环境检查] 无依赖要求，跳过依赖安装")
+        return True
+
+    pip_path = get_venv_pip()
+
+    if not pip_path.exists():
+        print(f"[环境检查] pip 不存在: {pip_path}")
+        return False
+
+    print(f"[环境检查] 正在安装 {len(dependencies)} 个依赖...")
+
+    # 构建安装列表
+    install_list = [
+        f"{package}=={info['version']}"
+        for package, info in dependencies.items()
+    ]
+
+    try:
+        subprocess.run(
+            [str(pip_path), "install"] + install_list,
+            check=True,
+            capture_output=False,  # 显示安装进度
+            text=True
+        )
+
+        print("[环境检查] 依赖安装完成")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"[环境检查] 依赖安装失败")
+        return False
+
+
+def run_full_check() -> Tuple[bool, Dict]:
+    """运行完整的环境检查"""
+    print("[环境检查] 开始完整诊断...")
+
+    # 1. 检查 Python 版本
+    py_ok, py_version, required_version = check_python_version()
+    if not py_ok:
+        error_data = {
+            "type": "wrong_version",
+            "message": f"Python 版本不匹配: {py_version}（需要 {required_version}）",
+            "details": {
+                "current": py_version,
+                "required": required_version
+            }
+        }
+        return False, error_data
+
+    print(f"[环境检查] ✓ Python 版本: {py_version}")
+
+    # 2. 检查虚拟环境
+    venv_ok, venv_msg = check_venv_exists()
+    if not venv_ok:
+        print(f"[环境检查] ✗ 虚拟环境: {venv_msg}")
+
+        # 尝试创建虚拟环境
+        if not create_venv():
+            error_data = {
+                "type": "venv_failed",
+                "message": "虚拟环境创建失败",
+                "details": {"reason": venv_msg}
+            }
+            return False, error_data
+
+        venv_ok, venv_msg = check_venv_exists()
+
+    print(f"[环境检查] ✓ 虚拟环境: {venv_msg}")
+
+    # 3. 检查依赖
+    deps_ok, deps_msg, deps_details = check_dependencies_installed()
+    if not deps_ok:
+        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'])} 个")
+
+        # 尝试安装依赖
+        if not install_dependencies():
+            error_data = {
+                "type": "missing_dependencies",
+                "message": "依赖安装失败",
+                "details": deps_details
+            }
+            return False, error_data
+
+        deps_ok, deps_msg, deps_details = check_dependencies_installed()
+
+    print(f"[环境检查] ✓ 依赖库: {deps_msg}")
+
+    print("[环境检查] 完整诊断通过")
+    return True, {}
+
+
+def should_run_full_check(status: Optional[Dict]) -> Tuple[bool, str]:
+    """判断是否需要运行完整检查"""
+
+    # 1. 状态文件不存在
+    if status is None:
+        return True, "首次运行"
+
+    # 2. 上次检查失败
+    if status.get("status") != "success":
+        return True, "上次检查失败"
+
+    # 3. dependencies_lock.json hash 变化
+    current_hash = calculate_requirements_hash()
+    saved_hash = status.get("dependencies", {}).get("lock_hash", "")
+
+    if current_hash != saved_hash:
+        return True, "依赖锁定文件已更新"
+
+    # 4. 虚拟环境目录被删除
+    venv_ok, _ = check_venv_exists()
+    if not venv_ok:
+        return True, "虚拟环境不存在"
+
+    return False, "环境正常"
+
+
+def check_environment() -> bool:
+    """
+    检查环境是否就绪
+
+    Returns:
+        True if ready, False otherwise
+    """
+    # 1. 加载状态
+    status = load_status()
+
+    # 2. 判断是否需要完整检查
+    need_check, reason = should_run_full_check(status)
+
+    if not need_check:
+        print(f"[环境检查] 跳过检查（{reason}）")
+        return True
+
+    print(f"[环境检查] 需要完整检查（{reason}）")
+
+    # 3. 运行完整检查
+    success, error_data = run_full_check()
+
+    # 4. 保存状态
+    py_ok, py_version, required_version = check_python_version()
+    venv_path = get_venv_path()
+
+    status_data = {
+        "version": "1.0",
+        "last_check": datetime.now(timezone.utc).isoformat(),
+        "status": "success" if success else "failed",
+        "python": {
+            "path": str(venv_path / ("Scripts/python.exe" if os.name == "nt" else "bin/python")),
+            "version": py_version,
+            "required_version": required_version,
+            "system_python": sys.executable
+        },
+        "venv": {
+            "path": str(venv_path),
+            "exists": venv_path.exists(),
+            "valid": success
+        },
+        "dependencies": {
+            "installed": success,
+            "lock_hash": calculate_requirements_hash()
+        },
+        "error": error_data if not success else None
+    }
+
+    save_status(status_data)
+
+    if success:
+        print("[环境检查] 环境就绪")
+    else:
+        print(f"[环境检查] 环境检查失败: {error_data.get('message')}")
+
+    return success
+
+
+if __name__ == "__main__":
+    # 可以单独运行此脚本进行环境检查
+    success = check_environment()
+    sys.exit(0 if success else 1)

package/dependencies_lock.json

@@ -0,0 +1,128 @@
+{
+  "scan_time": "2026-03-08T16:23:35.649703+00:00",
+  "python_version": "3.13.12",
+  "dependencies": {
+    "agentcp": {
+      "version": "0.1.47",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "aiofiles": {
+      "version": "25.1.0",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "aiohttp": {
+      "version": "3.13.3",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "certifi": {
+      "version": "2025.4.26",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "cryptography": {
+      "version": "44.0.3",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "python-dotenv": {
+      "version": "1.1.0",
+      "used_by": [
+        "launcher",
+        "extensions"
+      ]
+    },
+    "fastapi": {
+      "version": "0.124.4",
+      "used_by": [
+        "kernel",
+        "extensions"
+      ]
+    },
+    "flask": {
+      "version": "3.0.0",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "httpx": {
+      "version": "0.28.1",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "json5": {
+      "version": "0.13.0",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "openai": {
+      "version": "1.78.1",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "psutil": {
+      "version": "7.2.2",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "pydantic": {
+      "version": "2.11.4",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "requests": {
+      "version": "2.32.3",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "starlette": {
+      "version": "0.50.0",
+      "used_by": [
+        "kernel",
+        "extensions"
+      ]
+    },
+    "uvicorn": {
+      "version": "0.38.0",
+      "used_by": [
+        "kernel",
+        "extensions"
+      ]
+    },
+    "websocket-client": {
+      "version": "1.8.0",
+      "used_by": [
+        "extensions"
+      ]
+    },
+    "websockets": {
+      "version": "15.0.1",
+      "used_by": [
+        "launcher",
+        "extensions"
+      ]
+    },
+    "pyyaml": {
+      "version": "6.0.3",
+      "used_by": [
+        "kernel",
+        "launcher",
+        "extensions",
+        "kite_cli"
+      ]
+    }
+  }
+}

package/extensions/agents/assistant/server.py

@@ -89,7 +89,7 @@ class AssistantServer:
         """Single WebSocket session: connect, subscribe, register, ready, receive loop."""
         url = f"ws://127.0.0.1:{self.kernel_port}/ws?token={self.token}&id=assistant"
         print(f"[assistant] Connecting to Kernel (port {self.kernel_port})")
-        async with websockets.connect(url, open_timeout=3, ping_interval=20, ping_timeout=20, close_timeout=10) as ws:
+        async with websockets.connect(url, open_timeout=3, ping_interval=None, close_timeout=10) as ws:
             self._ws = ws
             elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
             elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
@@ -119,17 +119,18 @@ class AssistantServer:
 
             # Step 3: Publish module.ready (every reconnect)
             if not self._shutting_down:
+                startup_time = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
                 await self._rpc_call(ws, "event.publish", {
                     "event_id": str(uuid.uuid4()),
                     "event": "module.ready",
                     "data": {
                         "module_id": "assistant",
                         "graceful_shutdown": True,
+                        "startup_time": startup_time,
                     },
                 })
-                elapsed = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
-                elapsed_str = f" ({elapsed:.1f}s)" if elapsed else ""
-                print(f"[assistant] module.ready published{elapsed_str}")
+                elapsed_str = self._fmt_elapsed(self.boot_t0)
+                print(f"[assistant] module.ready published ({elapsed_str})")
 
             # Receive loop
             # CRITICAL: RPC 死锁防范
@@ -138,9 +139,6 @@ class AssistantServer:
             # - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
             # - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
 
-            # Start heartbeat loop
-            heartbeat_task = asyncio.create_task(self._heartbeat_loop(ws))
-
             async for raw in ws:
                 try:
                     msg = json.loads(raw)
@@ -157,6 +155,11 @@ class AssistantServer:
                         event_type = params.get("event", "")
                         data = params.get("data", {})
 
+                        # Handle system.ping event
+                        if event_type == "system.ping":
+                            await self._handle_ping_event(data)
+                            continue
+
                         # Layer 1: 处理订阅的事件
                         if event_type == "module.shutdown":
                             target = data.get("module_id", "")
@@ -223,16 +226,29 @@ class AssistantServer:
             msg["params"] = params
         await ws.send(json.dumps(msg))
 
-    async def _heartbeat_loop(self, ws):
-        """Send registry.heartbeat every 30 seconds to prevent TTL expiration."""
-        while True:
-            try:
-                await asyncio.sleep(30)
-                if not self._shutting_down:
-                    await self._rpc_call(ws, "registry.heartbeat", {"module_id": "assistant"})
-            except Exception as e:
-                print(f"[assistant] Heartbeat error: {e}")
-                break
+    async def _handle_ping_event(self, data: dict):
+        """Handle system.ping event and reply with system.pong."""
+        t1 = data.get("ping_time")
+        t2 = time.time()
+
+        await self._rpc_call(self._ws, "event.publish", {
+            "event_id": str(uuid.uuid4()),
+            "event": "system.pong",
+            "data": {
+                "module_id": "assistant",
+                "ping_time": t1,
+                "pong_time": t2,
+            },
+        })
+
+    def _fmt_elapsed(self, t0: float) -> str:
+        """Format elapsed time since t0."""
+        d = time.monotonic() - t0 if t0 else 0
+        if d < 1:
+            return f"{d * 1000:.0f}ms"
+        if d < 10:
+            return f"{d:.1f}s"
+        return f"{d:.0f}s"
 
     async def _publish_event(self, event: dict):
         """Publish an event via JSON-RPC event.publish."""