@agentunion/kite 1.4.0 → 1.6.0

package/docs//346/265/213/350/257/225/344/270/255/345/277/203/346/267/273/345/212/240/346/250/241/345/235/227/346/265/213/350/257/225/346/214/207/345/215/227.md

@@ -0,0 +1,147 @@
+# 测试中心添加新模块测试指南
+
+## 概述
+
+本文档说明如何在 kite_console 测试中心添加新模块的单元测试和集成测试。
+
+## 步骤
+
+### 1. 创建模块测试文件
+
+**位置**：`extensions/services/kite_console/static/js/tests/modules/{模块名}.js`
+
+**模板**：
+```javascript
+/**
+ * {模块名} 模块测试
+ */
+
+async function test{模块名首字母大写}Module() {
+  const runner = window.testRunner;
+  const client = runner.kernelClient;
+
+  runner.log('【{模块名} 模块测试】', 'section');
+
+  // 1. 模块存在性检查
+  await runner.runTest('{模块名} 模块存在性检查', async () => {
+    const result = await client.call('launcher.list_modules', {});
+    const module = result.modules.find(m => m.name === '{模块名}');
+    if (!module) throw new Error('{模块名} 模块未找到');
+  });
+
+  // 2. RPC 方法注册验证
+  runner.log('', 'info');
+  runner.log('RPC 方法注册验证', 'subsection');
+
+  const rpcMethods = ['health', 'status', /* 其他方法 */];
+  for (const method of rpcMethods) {
+    await runner.runTest(`{模块名}.${method} 注册检查`, async () => {
+      const result = await client.call('registry.lookup', {
+        field: `tools.rpc.module.${method}`,
+        module: '{模块名}'
+      });
+      if (!result.results || result.results.length === 0) throw new Error('未找到注册');
+    });
+  }
+
+  // 3. 事件注册验证
+  runner.log('', 'info');
+  runner.log('事件注册验证', 'subsection');
+
+  // 4. RPC 功能测试
+  runner.log('', 'info');
+  runner.log('RPC 功能测试', 'subsection');
+
+  runner.log('');
+}
+
+window.test{模块名首字母大写}Module = test{模块名首字母大写}Module;
+```
+
+### 2. 创建集成测试文件
+
+**位置**：`extensions/services/kite_console/static/js/tests/integration/{模块名}.js`
+
+**模板**：
+```javascript
+/**
+ * {模块名} 集成测试
+ */
+
+async function test{模块名首字母大写}Integration() {
+  const runner = window.testRunner;
+  const client = runner.kernelClient;
+
+  runner.log('【{模块名} 集成测试】', 'section');
+
+  // 测试完整流程
+  await runner.runTest('{模块名} 完整流程', async () => {
+    // 测试逻辑
+  });
+
+  runner.log('');
+}
+
+window.test{模块名首字母大写}Integration = test{模块名首字母大写}Integration;
+```
+
+### 3. 注册到测试中心
+
+**文件**：`extensions/services/kite_console/static/js/tests/index.js`
+
+**修改 MODULE_TESTS**：
+```javascript
+const MODULE_TESTS = {
+  // ... 其他模块
+  {模块名}: 'test{模块名首字母大写}Module'
+};
+```
+
+**修改 INTEGRATION_TESTS**：
+```javascript
+const INTEGRATION_TESTS = {
+  // ... 其他测试
+  '{模块名}': 'test{模块名首字母大写}Integration'
+};
+```
+
+## 示例：Redis 模块
+
+### 文件结构
+```
+tests/
+├── modules/
+│   └── redis.js          # Redis 模块测试
+├── integration/
+│   └── redis.js          # Redis 集成测试
+└── index.js              # 注册入口
+```
+
+### 注册代码
+```javascript
+// index.js
+const MODULE_TESTS = {
+  // ...
+  redis: 'testRedisModule'
+};
+
+const INTEGRATION_TESTS = {
+  // ...
+  'redis': 'testRedisIntegration'
+};
+```
+
+## 测试运行
+
+1. 启动 Kite：`python main.py`
+2. 访问 kite_console 前端
+3. 进入"模块管理" → "测试中心"
+4. 选择对应测试运行
+
+## 注意事项
+
+- 测试函数必须是 async 函数
+- 使用 `runner.runTest()` 包装每个测试用例
+- 测试失败时抛出 Error
+- 使用 `runner.log()` 输出日志
+- 测试完成后自动上传日志到后端

package/docs//347/211/210/346/234/254/351/224/201/345/256/232/347/216/257/345/242/203/347/256/241/347/220/206/346/226/271/346/241/210.md

@@ -0,0 +1,331 @@
+# Kite 版本锁定环境管理方案
+
+## 概述
+
+Kite 采用**版本锁定**机制，确保生产环境与开发环境完全一致：
+1. **Python 版本锁定**：`python_version.json` 记录开发环境的 Python 版本
+2. **依赖版本锁定**：`dependencies_lock.json` 记录所有依赖的精确版本
+
+## 核心文件
+
+### 1. python_version.json
+
+记录开发环境的 Python 版本：
+
+```json
+{
+  "version": "3.11.5",
+  "note": "此文件在开发环境打包时生成，记录开发环境的 Python 版本。生产环境必须使用相同版本。"
+}
+```
+
+### 2. dependencies_lock.json
+
+记录所有模块的依赖及精确版本：
+
+```json
+{
+  "scan_time": "2026-03-08T10:00:00Z",
+  "python_version": "3.11.5",
+  "dependencies": {
+    "fastapi": {
+      "version": "0.115.2",
+      "used_by": ["kernel", "web"]
+    },
+    "websockets": {
+      "version": "13.1",
+      "used_by": ["kernel", "launcher"]
+    },
+    "json5": {
+      "version": "0.9.25",
+      "used_by": ["web"]
+    }
+  }
+}
+```
+
+## 开发环境工作流
+
+### 1. 扫描依赖（打包前）
+
+```bash
+kite prepare
+```
+
+或者：
+
+```bash
+python -m kite_cli prepare
+```
+
+**功能**：
+- 扫描所有模块的 Python 文件
+- 提取 import 语句
+- 过滤标准库和项目内部模块
+- 获取每个第三方包的版本
+- 生成 `dependencies_lock.json`
+- 同步更新 `python_version.json`
+
+**输出示例**：
+```
+============================================================
+  Kite 打包准备
+============================================================
+
+[扫描] core...
+  发现 5 个第三方依赖
+[扫描] kernel...
+  发现 8 个第三方依赖
+[依赖] fastapi==0.115.2 (used by: kernel, web)
+[依赖] websockets==13.1 (used by: kernel, launcher)
+[完成] 依赖锁定文件已生成: dependencies_lock.json
+[统计] 共 18 个第三方依赖
+[完成] Python 版本文件已更新: python_version.json
+[版本] Python 3.11.5
+
+✓ 打包准备完成
+
+生成的文件:
+  - dependencies_lock.json
+  - python_version.json
+
+下一步:
+  1. 检查生成的文件
+  2. 提交到 git: git add dependencies_lock.json python_version.json
+  3. 发布: npm publish
+```
+
+### 2. 打包发布
+
+```bash
+npm publish
+```
+
+**打包内容**：
+- `python_version.json` — Python 版本锁定
+- `dependencies_lock.json` — 依赖版本锁定
+- 所有源代码
+
+## 生产环境工作流
+
+### 1. npm install（一次性）
+
+```
+npm install -g @agentunion/kite
+    ↓
+postinstall 钩子执行
+    ↓
+scripts/setup-python-env.js
+    ↓
+1. 读取 python_version.json
+2. 检测系统是否有该精确版本的 Python
+3. 如果没有 → 下载安装该版本（仅 Windows）
+```
+
+**精确版本匹配**：
+- 开发环境：Python 3.11.5
+- 生产环境：必须 Python 3.11.5（不接受 3.11.6 或 3.11.4）
+
+### 2. kite start（每次启动）
+
+```
+kite start
+    ↓
+main.py
+    ↓
+env_checker.check_environment()
+    ↓
+读取 ~/.kite/env_status.json
+    ↓
+status === "success"?
+    ├─ YES → 跳过检查（快速启动）
+    └─ NO  → 完整诊断
+         ↓
+    1. 检查 Python 版本（精确匹配）
+    2. 检查虚拟环境
+    3. 检查依赖（精确版本）
+         ↓
+    更新 env_status.json
+```
+
+## 依赖检查逻辑
+
+### 精确版本检查
+
+```python
+def check_dependencies_installed():
+    lock_data = load_dependencies_lock()
+    dependencies = lock_data["dependencies"]
+
+    for package_name, package_info in dependencies.items():
+        required_version = package_info["version"]
+        installed_version = get_installed_version(package_name)
+
+        # 精确匹配
+        if installed_version != required_version:
+            version_mismatch.append({
+                "package": package_name,
+                "required": required_version,
+                "installed": installed_version
+            })
+```
+
+### 检查结果
+
+**成功**：
+```
+[环境检查] ✓ Python 版本: 3.11.5
+[环境检查] ✓ 虚拟环境: 虚拟环境正常
+[环境检查] ✓ 依赖库: 依赖正常
+```
+
+**失败（版本不匹配）**：
+```
+[环境检查] ✓ Python 版本: 3.11.5
+[环境检查] ✓ 虚拟环境: 虚拟环境正常
+[环境检查] ✗ 依赖库: 2 个版本不匹配
+  版本不匹配: 2 个
+[环境检查] 正在安装 18 个依赖...
+... (安装进度)
+[环境检查] 依赖安装完成
+[环境检查] ✓ 依赖库: 依赖正常
+```
+
+## 状态记录文件
+
+**路径**：`~/.kite/env_status.json`
+
+**格式**：
+```json
+{
+  "version": "1.0",
+  "last_check": "2026-03-08T10:30:00Z",
+  "status": "success",
+  "python": {
+    "path": "C:/Users/xxx/.kite/venv/Scripts/python.exe",
+    "version": "3.11.5",
+    "required_version": "3.11.5",
+    "system_python": "C:/Python311/python.exe"
+  },
+  "venv": {
+    "path": "C:/Users/xxx/.kite/venv",
+    "exists": true,
+    "valid": true
+  },
+  "dependencies": {
+    "installed": true,
+    "lock_hash": "abc123..."
+  },
+  "error": null
+}
+```
+
+## 触发完整检查的条件
+
+1. **首次运行**：`env_status.json` 不存在
+2. **上次失败**：`status === "failed"`
+3. **依赖更新**：`dependencies_lock.json` 的 hash 变化
+4. **环境损坏**：虚拟环境目录被删除
+
+## 优势
+
+### 1. 版本一致性
+
+- 开发环境：Python 3.11.5 + fastapi 0.115.2
+- 生产环境：Python 3.11.5 + fastapi 0.115.2
+- **完全一致，避免版本差异导致的问题**
+
+### 2. 精确依赖管理
+
+- 不使用 `>=` 或 `~` 等模糊版本
+- 每个依赖都是精确版本：`fastapi==0.115.2`
+- 避免依赖升级导致的兼容性问题
+
+### 3. 可追溯性
+
+- `dependencies_lock.json` 记录每个依赖的使用者
+- 方便排查依赖冲突
+- 清晰的依赖关系图
+
+### 4. 快速启动
+
+- 环境就绪后跳过检查（< 1 秒）
+- 只在必要时运行完整诊断
+
+## 开发流程
+
+### 完整的打包发布流程
+
+```bash
+# 1. 开发完成后，扫描依赖
+kite prepare
+
+# 2. 检查生成的文件
+cat dependencies_lock.json
+cat python_version.json
+
+# 3. 提交到 git
+git add dependencies_lock.json python_version.json
+git commit -m "chore: update dependencies lock"
+
+# 4. 发布到 npm
+npm publish
+```
+
+### 添加新依赖
+
+1. 在开发环境安装：`pip install new-package`
+2. 重新扫描依赖：`kite prepare`
+3. 提交更新：`git add dependencies_lock.json`
+4. 发布新版本：`npm publish`
+
+### 升级 Python 版本
+
+1. 升级开发环境 Python
+2. 重新扫描依赖：`kite prepare`
+3. 测试所有功能
+4. 提交更新：`git add python_version.json dependencies_lock.json`
+5. 发布新版本：`npm publish`
+
+## 故障排查
+
+### 问题：Python 版本不匹配
+
+**错误**：
+```
+[环境检查] ✗ Python 版本不匹配: 3.11.6（需要 3.11.5）
+```
+
+**解决**：
+- Windows：自动下载安装 Python 3.11.5
+- Linux/macOS：手动安装 Python 3.11.5
+
+### 问题：依赖版本不匹配
+
+**错误**：
+```
+[环境检查] ✗ 依赖库: 2 个版本不匹配
+```
+
+**解决**：
+- 自动重新安装正确版本
+- 如果失败，手动运行：`python core/env_checker.py`
+
+### 问题：扫描依赖失败
+
+**错误**：
+```
+[警告] 解析文件失败: xxx.py - SyntaxError
+```
+
+**解决**：
+- 检查 Python 文件语法
+- 或在 `scan_dependencies.py` 中跳过该文件
+
+## 未来改进
+
+1. **依赖树分析**：可视化依赖关系
+2. **安全扫描**：检查依赖的安全漏洞
+3. **增量更新**：只更新变化的依赖
+4. **离线包**：提供包含所有依赖的离线安装包
+5. **多版本支持**：支持多个 Python 版本并存