@agentunion/kite 1.4.0 → 1.5.0

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,51 @@ 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}`);
+
+    // 常见的环境相关错误码
+    if (code === 1 || code === 127) {
+      console.error(`[kite] 可能是环境问题，下次启动将重新检查环境`);
+      markEnvFailed('python_runtime_error');
+    }
+  }
+
+  process.exit(code ?? 0);
+});
 
 for (const sig of ['SIGINT', 'SIGTERM']) {
   process.on(sig, () => child.kill(sig));

package/core/dependency_checker.py

@@ -0,0 +1,250 @@
+"""
+依赖检查和自动安装模块
+
+在 Kite 启动前检查 requirements.txt 中的依赖是否满足，
+不满足则自动安装到用户级虚拟环境 ~/.kite/venv/
+"""
+
+import os
+import sys
+import subprocess
+from pathlib import Path
+from typing import List, Tuple, Optional
+
+
+def get_venv_path() -> Path:
+    """获取 Kite 虚拟环境路径"""
+    return Path.home() / ".kite" / "venv"
+
+
+def get_site_packages_path() -> Optional[Path]:
+    """获取虚拟环境的 site-packages 路径"""
+    venv_path = get_venv_path()
+
+    if os.name == "nt":  # Windows
+        site_packages = venv_path / "Lib" / "site-packages"
+    else:  # Linux / macOS
+        python_version = f"python{sys.version_info.major}.{sys.version_info.minor}"
+        site_packages = venv_path / "lib" / python_version / "site-packages"
+
+    return site_packages if site_packages.exists() else None
+
+
+def activate_venv():
+    """将虚拟环境的 site-packages 添加到 sys.path"""
+    site_packages = get_site_packages_path()
+
+    if site_packages and site_packages not in sys.path:
+        sys.path.insert(0, str(site_packages))
+        print(f"[依赖] 已激活虚拟环境: {site_packages}")
+
+
+def ensure_venv_exists() -> bool:
+    """确保虚拟环境存在，不存在则创建"""
+    venv_path = get_venv_path()
+
+    if venv_path.exists():
+        return True
+
+    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 parse_requirements(requirements_file: Path) -> List[Tuple[str, str]]:
+    """
+    解析 requirements.txt
+
+    Returns:
+        List of (package_name, version_spec) tuples
+        例如: [("fastapi", ">=0.115.0"), ("uvicorn", ">=0.32.0")]
+    """
+    requirements = []
+
+    with open(requirements_file, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+
+            # 跳过注释和空行
+            if not line or line.startswith("#"):
+                continue
+
+            # 解析包名和版本
+            if ">=" in line:
+                package, version = line.split(">=", 1)
+                requirements.append((package.strip(), f">={version.strip()}"))
+            elif "==" in line:
+                package, version = line.split("==", 1)
+                requirements.append((package.strip(), f"=={version.strip()}"))
+            else:
+                requirements.append((line.strip(), ""))
+
+    return requirements
+
+
+def check_package_installed(package_name: str, version_spec: str) -> bool:
+    """
+    检查包是否已安装且版本满足要求
+
+    Args:
+        package_name: 包名
+        version_spec: 版本要求，如 ">=0.115.0"
+
+    Returns:
+        True if installed and version matches, False otherwise
+    """
+    try:
+        import importlib.metadata
+
+        # 检查包是否存在
+        try:
+            installed_version = importlib.metadata.version(package_name)
+        except importlib.metadata.PackageNotFoundError:
+            return False
+
+        # 如果没有版本要求，只要安装了就行
+        if not version_spec:
+            return True
+
+        # 简单的版本比较（只支持 >= 和 ==）
+        if version_spec.startswith(">="):
+            required_version = version_spec[2:].strip()
+            return _version_gte(installed_version, required_version)
+        elif version_spec.startswith("=="):
+            required_version = version_spec[2:].strip()
+            return installed_version == required_version
+
+        return True
+
+    except Exception as e:
+        print(f"[依赖] 检查包 {package_name} 时出错: {e}")
+        return False
+
+
+def _version_gte(v1: str, v2: str) -> bool:
+    """简单的版本比较：v1 >= v2"""
+    try:
+        parts1 = [int(x) for x in v1.split(".")[:3]]
+        parts2 = [int(x) for x in v2.split(".")[:3]]
+
+        # 补齐到 3 位
+        while len(parts1) < 3:
+            parts1.append(0)
+        while len(parts2) < 3:
+            parts2.append(0)
+
+        return parts1 >= parts2
+    except:
+        return True  # 解析失败时假设满足
+
+
+def install_packages(packages: List[str]) -> bool:
+    """
+    使用虚拟环境的 pip 安装包
+
+    Args:
+        packages: 包列表，如 ["fastapi>=0.115.0", "uvicorn>=0.32.0"]
+
+    Returns:
+        True if success, False otherwise
+    """
+    pip_path = get_venv_pip()
+
+    if not pip_path.exists():
+        print(f"[依赖] pip 不存在: {pip_path}")
+        return False
+
+    print(f"[依赖] 正在安装 {len(packages)} 个包...")
+
+    try:
+        # 使用 pip install 安装所有缺失的包
+        cmd = [str(pip_path), "install"] + packages
+
+        result = subprocess.run(
+            cmd,
+            check=True,
+            capture_output=True,
+            text=True
+        )
+
+        print(f"[依赖] 安装成功")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"[依赖] 安装失败: {e.stderr}")
+        return False
+
+
+def check_and_install_dependencies(requirements_file: Path) -> bool:
+    """
+    检查并安装依赖
+
+    Args:
+        requirements_file: requirements.txt 文件路径
+
+    Returns:
+        True if all dependencies satisfied, False otherwise
+    """
+    if not requirements_file.exists():
+        print(f"[依赖] requirements.txt 不存在: {requirements_file}")
+        return True  # 没有依赖文件就跳过
+
+    # 1. 确保虚拟环境存在
+    if not ensure_venv_exists():
+        print("[依赖] 无法创建虚拟环境，跳过依赖检查")
+        return False
+
+    # 2. 激活虚拟环境（添加到 sys.path）
+    activate_venv()
+
+    # 3. 解析 requirements.txt
+    requirements = parse_requirements(requirements_file)
+
+    if not requirements:
+        print("[依赖] requirements.txt 为空")
+        return True
+
+    # 4. 检查哪些包需要安装
+    missing_packages = []
+
+    for package_name, version_spec in requirements:
+        if not check_package_installed(package_name, version_spec):
+            spec = f"{package_name}{version_spec}" if version_spec else package_name
+            missing_packages.append(spec)
+            print(f"[依赖] 缺失: {spec}")
+
+    # 5. 如果有缺失的包，安装它们
+    if missing_packages:
+        print(f"[依赖] 发现 {len(missing_packages)} 个缺失的包，开始安装...")
+
+        if not install_packages(missing_packages):
+            print("[依赖] 安装失败，Kite 可能无法正常运行")
+            return False
+
+        print("[依赖] 所有依赖已安装")
+    else:
+        print("[依赖] 所有依赖已满足")
+
+    return True