@agentunion/kite 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -1,4 +1,223 @@
-# v1.3.0
+# 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
+**上一版本**：v1.3.1
+**版本级别**：patch
+
+---
+
+## 核心变更
+
+本次发布主要包含功能增强和稳定性改进。新增 Web 模块管理 API，支持通过 HTTP 接口扫描、查看和编辑模块元数据与配置。Kernel 模块增加断线重连防抖机制（5 秒窗口），避免短暂网络波动导致的模块状态误判。多个扩展模块和前端界面进行了优化更新。
+
+---
+
+## 变更统计
+
+| 类型 | 数量 | 说明 |
+|------|------|------|
+| 新增 | 1 | `routes_modules.py` (249 行) |
+| 修改 | 18 | kernel、launcher、扩展模块、web 前端 |
+
+---
+
+## 关键变更
+
+### 新增功能
+
+**`extensions/services/web/routes/routes_modules.py`** (249 行)
+- 模块管理 API：扫描项目中的所有模块
+- 元数据查看与编辑（`module.md` 前置元数据）
+- 配置查看与编辑（`config.yaml`）
+- 只读字段保护（`name`, `type`, `runtime`, `entry`）
+
+### 核心改进
+
+**`kernel/server.py`** — 断线重连防抖
+```diff
++ # Debounce timers for disconnected modules (module_id -> asyncio.Task)
++ self._debounce_tasks: dict[str, asyncio.Task] = {}
++ # Cancel debounce timer if module is reconnecting within 5s window
++ old_debounce = server._debounce_tasks.pop(module_id, None)
++ if old_debounce:
++     old_debounce.cancel()
+```
+- 5 秒防抖窗口，避免短暂断线误判
+- Launcher 离线 35 秒后触发全局重启
+
+**`kernel/registry_store.py`** — 连接状态管理
+- 新增 `set_connected()` / `set_disconnected()` 方法
+- 模块注册表支持实时连接状态跟踪
+
+**`launcher/entry.py`** — 进程管理优化
+- 改进模块启动和停止逻辑
+- 优化日志输出和错误处理
+
+### 前端更新
+
+**Web UI** (`static/index.html`, `static/js/app.js`, `static/css/style.css`)
+- 界面样式优化
+- 交互逻辑改进
+- 新增模块管理相关 UI 组件
+
+### 扩展模块适配
+
+更新以下模块以适配 Kernel 连接状态管理：
+- `extensions/agents/assistant/server.py`
+- `extensions/channels/acp_channel/server.py`
+- `extensions/services/backup/entry.py`
+- `extensions/services/model_service/entry.py`
+- `extensions/services/watchdog/entry.py`
+- `extensions/services/watchdog/monitor.py`
+
+---
+
+## 包信息
+
+- **文件数**：88（与 v1.3.1 相同）
+- **打包大小**：~208 kB
+
+---
+
+## 稳定性改进
+
+- ✅ **断线重连防抖** — 避免短暂网络波动导致模块误判为离线
+- ✅ **连接状态跟踪** — Registry 实时记录模块连接状态
+- ✅ **Launcher 保护** — 35 秒容错窗口，避免误触发全局重启
+# v1.3.1
 
 **发布日期**：2026-03-04
 **上一版本**：v1.2.0
@@ -206,3 +425,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

@@ -67,6 +67,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'))) {
+    // Delegate to kite_cli
+    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) {

package/extensions/agents/assistant/entry.py

@@ -19,7 +19,113 @@ from datetime import datetime, timezone
 
 
 # ── Module configuration ──
-MODULE_NAME = "assistant"
+
+def _load_module_config() -> dict:
+    """Load module configuration from module.md frontmatter.
+
+    Returns:
+        Dict with keys: name, preferred_port, advertise_ip
+
+    Raises:
+        SystemExit: If module.md is invalid or name is non-compliant
+    """
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+
+    # Calculate relative path for error messages
+    project_root = os.environ.get("KITE_PROJECT", "")
+    if project_root and _this_dir.startswith(project_root):
+        rel_path = os.path.relpath(_this_dir, project_root)
+    else:
+        rel_path = _this_dir
+
+    # Default values (will be overridden if valid config exists)
+    result = {
+        "name": "",
+        "preferred_port": 0,
+        "advertise_ip": "0.0.0.0"
+    }
+
+    # Check if module.md exists
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+        print(f"  Path: {rel_path}/module.md")
+        print(f"  Reason: File not found")
+        sys.exit(1)
+
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+
+        # Extract YAML frontmatter (between --- markers)
+        import re
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing YAML frontmatter")
+            sys.exit(1)
+
+        # Parse YAML frontmatter
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
+            sys.exit(1)
+        except Exception as e:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: YAML parse error: {e}")
+            sys.exit(1)
+
+        # Validate 'name' field (required)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing 'name' field")
+            sys.exit(1)
+
+        raw_name = str(fm["name"]).strip()
+
+        if not raw_name:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Empty module name")
+            sys.exit(1)
+
+        # Validate name characters
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+
+        if sanitized != raw_name:
+            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
+            sys.exit(1)
+
+        result["name"] = sanitized
+
+        # Extract optional fields
+        if "preferred_port" in fm:
+            try:
+                result["preferred_port"] = int(fm["preferred_port"])
+            except (ValueError, TypeError):
+                pass
+
+        if "advertise_ip" in fm:
+            result["advertise_ip"] = str(fm["advertise_ip"])
+
+    except SystemExit:
+        raise  # Re-raise exit to prevent catching by outer except
+    except Exception as e:
+        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
+        sys.exit(1)
+
+    return result
+
+_module_config = _load_module_config()
+MODULE_NAME = _module_config["name"]
 
 
 class _SafeWriter:
@@ -324,6 +430,10 @@ def main():
         _print_crash_summary(type(e), e.__traceback__)
         sys.exit(1)
 
+    # Check if server requested exit with non-zero code
+    if server._exit_code != 0:
+        sys.exit(server._exit_code)
+
 
 if __name__ == "__main__":
     main()