@agentunion/kite 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,238 @@
+# 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
+**上一版本**：v1.3.2
+**版本级别**：minor
+
+---
+
+## 核心变更
+
+本次发布新增 **Kite CLI 模块管理工具**（`kite_cli/`），提供模块安装、卸载、更新、搜索等完整生命周期管理能力。同时 Web 模块新增**配对机制**和 **Kernel 中转服务**，支持前端通过配对码安全连接 Kernel，实现 WebSocket 双向通信和 RPC 权限控制。
+
+---
+
+## 变更统计
+
+| 类型 | 数量 | 说明 |
+|------|------|------|
+| 新增 | 46 | kite_cli 模块（28 个）+ web 功能扩展（18 个） |
+| 删除 | 1 | routes_modules.py（被 routes_management_ws.py 替代） |
+| 修改 | 30 | launcher、kernel、extensions 核心模块适配 |
+
+---
+
+## 关键变更
+
+### 新增模块
+
+**`kite_cli/`** (28 个文件)
+- **命令模块**（11 个）：install, uninstall, update, list, info, doctor, history, log, search, clean, rollback
+- **核心模块**（7 个）：checker, dependency, downloader, install_info, tool_installer, validator
+- **工具模块**（6 个）：i18n, interactive, operation_log, paths, version
+- **入口文件**：`main.py` (CLI 主入口), `__main__.py` (模块化启动)
+
+**`extensions/services/web/`** (18 个文件)
+- **配对机制**：`pairing.py` (配对码管理), `pairing_codes.jsonl` (持久化存储), `pairing.html` (配对界面)
+- **中转服务**：`relay.py` (Kernel WebSocket 中转), `relay_config.json5` (中转配置)
+- **配置系统**：`config_example.py`, `config_loader.py`, `web_config.json5`
+- **路由扩展**：`routes_management_ws.py` (WebSocket 管理), `routes_rpc.py` (RPC 转发), `routes_test.py` (测试接口)
+- **前端工具**：`kernel-client.js` (Kernel 客户端), `kernel-client-example.js`, `registry-tests.js`, `token-manager.js`, `test_registry.html`
+- **文档**：`WEBSOCKET_STATUS.md` (WebSocket 状态说明)
+
+**`scripts/`** (1 个文件)
+- `plan_manager.py` — 计划管理工具
+
+### 删除内容
+
+- **`routes_modules.py`** — 被 `routes_management_ws.py` 替代（HTTP → WebSocket）
+
+### 核心功能
+
+**Kite CLI 模块管理**
+```bash
+# 安装模块
+kite install <source>
+
+# 卸载模块
+kite uninstall <name>
+
+# 更新模块
+kite update <name>
+
+# 列出已安装模块
+kite list
+
+# 搜索可用模块
+kite search <keyword>
+
+# 查看模块信息
+kite info <name>
+
+# 查看操作日志
+kite log
+
+# 回滚最后一次操作
+kite rollback
+
+# 清理临时文件
+kite clean
+
+# 检查下载工具状态
+kite doctor
+```
+
+**Web 配对机制**
+- 生成 6 位配对码（临时，不持久化）
+- 前端输入配对码获取 frontend_token（30 天有效期）
+- 支持 admin/guest 角色权限控制
+- 配对记录持久化到 `pairing_codes.jsonl`
+
+**Kernel 中转服务**
+- 前端通过 WebSocket 连接 Web 模块
+- Web 模块为每个前端创建到 Kernel 的连接
+- 双向转发 JSON-RPC 消息
+- RPC 权限白名单控制（admin 全权限，guest 受限）
+- 前端模块生命周期管理（注册、重连、优雅退出）
+
+---
+
+## 架构演进
+
+| 版本 | 核心模块 | CLI 工具 | Web 功能 | 包文件数 |
+|------|---------|---------|---------|---------|
+| v1.2.0 | 3 (event_hub, registry, launcher) | 无 | 基础 API | 97 |
+| v1.3.1 | 2 (kernel, launcher) | 无 | 模块管理 API | 87 |
+| v1.3.2 | 2 (kernel, launcher) | 无 | 断线重连防抖 | 88 |
+| v1.4.0 | 2 (kernel, launcher) | kite_cli | 配对 + 中转 | 134 |
+
+---
+
+## 设计原则
+
+- ✅ **零共享代码依赖** — `relay.py` 和 `pairing.py` 可独立拷贝使用
+- ✅ **跨语言兼容** — WebSocket JSON-RPC 2.0 标准协议
+- ✅ **安全性** — 配对码 + frontend_token 双重验证，RPC 权限白名单
+
+---
+
+## 包信息
+
+- **文件数**：134（+46 vs v1.3.2）
+- **打包大小**：311.5 kB（+103.5 kB）
+- **解压大小**：1.4 MB
+
+---
+
+## 兼容性说明
+
+本次发布为 minor 版本，向后兼容。新增功能不影响现有模块运行。
+
+- ✅ CLI 接口保持兼容（`kite` 命令）
+- ✅ Kernel WebSocket 协议保持兼容
+- ✅ 现有模块无需修改即可运行
 # v1.3.2
 
 **发布日期**：2026-03-04
@@ -292,3 +527,70 @@
 ## 变更摘要
 
 重大功能更新：新增三个扩展类型目录（agents、channels、services），引入统一日志工具 `kite_log.py`，新增 backup、model_service、web 三个服务模块。核心模块（launcher、registry、event_hub）进行了多项优化和增强，包括进程管理改进、事件路由优化、模块生命周期管理完善。打包文件数从 36 个增至 72 个，框架扩展性和功能完整度显著提升。
+# v1.0.8
+
+**发布日期**：2026-03-01
+**上一版本**：v1.0.7
+**版本级别**：patch
+
+## 变更文件
+
+### 修改
+- `package.json` — `files` 字段新增 `!` 否定模式排除规则
+
+## 变更摘要
+
+修复 npm 打包时包含了不必要文件的问题。在 `package.json` 的 `files` 字段中添加排除规则（`!**/__pycache__`、`!**/*.pyc`、`!**/data`、`!**/bench_results`、`!core/event_hub_bench`），确保发布包不包含 Python 缓存、运行时数据和基准测试文件。包大小从 177.6 kB 降至 53.4 kB。
+# v1.0.7
+
+**发布日期**：2026-03-01
+**上一版本**：无（首次发布）
+**版本级别**：patch
+
+## 变更文件
+
+初始发布，包含所有文件：
+
+### 根文件
+- `cli.js`
+- `main.py`
+- `__main__.py`
+- `__init__.py`
+- `package.json`
+
+### core/
+- `core/__init__.py`
+- `core/launcher/__init__.py`
+- `core/launcher/entry.py`
+- `core/launcher/process_manager.py`
+- `core/launcher/module_scanner.py`
+- `core/launcher/module.md`
+- `core/registry/__init__.py`
+- `core/registry/entry.py`
+- `core/registry/server.py`
+- `core/registry/store.py`
+- `core/registry/module.md`
+- `core/event_hub/__init__.py`
+- `core/event_hub/entry.py`
+- `core/event_hub/hub.py`
+- `core/event_hub/router.py`
+- `core/event_hub/dedup.py`
+- `core/event_hub/server.py`
+- `core/event_hub/bench.py`
+- `core/event_hub/bench_extreme.py`
+- `core/event_hub/bench_perf.py`
+- `core/event_hub/module.md`
+- `core/event_hub/BENCHMARK.md`
+
+### extensions/
+- `extensions/__init__.py`
+- `extensions/services/__init__.py`
+- `extensions/services/watchdog/__init__.py`
+- `extensions/services/watchdog/entry.py`
+- `extensions/services/watchdog/server.py`
+- `extensions/services/watchdog/monitor.py`
+- `extensions/services/watchdog/module.md`
+
+## 变更摘要
+
+Kite 框架首次发布到 npm。包含核心启动器（launcher）、模块注册中心（registry）、事件中心（event_hub）三个核心模块，以及 watchdog 服务扩展。提供 Node.js CLI 入口和 Python 主入口，支持 Windows、Linux、macOS 三平台。

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);
@@ -67,6 +68,82 @@ for (let i = 0; i < args.length; i++) {
 
 const versionDir = path.join(kiteHome, 'versions', useVersion);
 
+// Check if first arg is a CLI command or help/version flag
+const cliCommands = ['install', 'uninstall', 'update', 'list', 'search', 'info', 'log', 'rollback', 'clean', 'doctor', 'history'];
+const helpFlags = ['-h', '-H', '--help', 'help'];
+const versionFlags = ['-v', '-V', '--version', 'version'];
+
+// Handle no arguments - show brief help
+if (args.length === 0) {
+  // Detect language from environment
+  const lang = (process.env.LANG || '').toLowerCase();
+  const isEnglish = lang.startsWith('en');
+
+  if (isEnglish) {
+    console.log('Kite CLI — Modular AI Framework');
+    console.log('');
+    console.log('Usage:');
+    console.log('  kite start              Start Kite framework');
+    console.log('  kite list               List installed modules');
+    console.log('  kite install <module>   Install a module');
+    console.log('  kite -h, --help         Show full help');
+    console.log('  kite -v, --version      Show version');
+    console.log('');
+    console.log('Run "kite -h" to see all available commands');
+  } else {
+    console.log('Kite CLI — 模块化 AI 框架');
+    console.log('');
+    console.log('用法:');
+    console.log('  kite start              启动 Kite 框架');
+    console.log('  kite list               列出已安装的模块');
+    console.log('  kite install <module>   安装模块');
+    console.log('  kite -h, --help         显示完整帮助信息');
+    console.log('  kite -v, --version      显示版本号');
+    console.log('');
+    console.log('运行 "kite -h" 查看所有可用命令');
+  }
+  process.exit(0);
+}
+
+// Handle 'start' command - launch Kite framework
+if (args[0] === 'start') {
+  // Remove 'start' from args and continue to framework launch
+  pythonArgs.splice(pythonArgs.indexOf('start'), 1);
+  // Continue to framework launch below
+} else if (args.length > 0 && (cliCommands.includes(args[0]) || helpFlags.includes(args[0]) || versionFlags.includes(args[0]))) {
+  // Determine working directory for kite_cli
+  let cliWorkDir = versionDir;
+
+  // If running from development directory (has kite_cli/), use current directory
+  if (fs.existsSync(path.join(packageDir, 'kite_cli', '__init__.py'))) {
+    cliWorkDir = packageDir;
+  } else if (!fs.existsSync(path.join(versionDir, 'main.py'))) {
+    // Version not installed yet
+    console.log('[kite] CLI 命令需要先安装 Kite 框架');
+    console.log('[kite] 正在安装...');
+    // Will be installed below
+  }
+
+  // Only execute if we have a valid working directory
+  if (fs.existsSync(path.join(cliWorkDir, 'kite_cli', '__init__.py'))) {
+    // 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, {
+      cwd: cliWorkDir,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        KITE_PROJECT: cliWorkDir,
+        KITE_MODULES: modulesDir,
+        KITE_DATA: dataDir
+      }
+    });
+    result.on('exit', code => process.exit(code ?? 0));
+    return;
+  }
+}
+
 // ── Install: copy framework to ~/.kite/versions/{ver}/ if needed ──
 
 function copyDirSync(src, dest) {
@@ -133,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}`);
@@ -152,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));