@agentunion/kite 1.5.0 → 1.6.0

package/docs//347/216/257/345/242/203/347/256/241/347/220/206/345/256/214/346/225/264/346/226/271/346/241/210.md

@@ -0,0 +1,334 @@
+# Kite 环境管理完整方案
+
+## 概述
+
+Kite 采用**两层环境管理**机制：
+1. **npm 层**：确保 Python 可用
+2. **Python 层**：准备虚拟环境和依赖库，使用状态记录优化启动速度
+
+## 架构设计
+
+### 目录结构
+
+```
+~/.kite/                          ← KITE_DATA
+├── python/                       ← Python 安装目录（如果系统没有）
+│   └── python.exe
+├── venv/                         ← 虚拟环境
+│   ├── Scripts/ (Windows)
+│   ├── Lib/site-packages/
+│   └── pyvenv.cfg
+├── env_status.json               ← 环境状态记录（关键优化）
+├── versions/                     ← 框架代码
+└── workspace/                    ← 运行时数据
+
+node_modules/@agentunion/kite/    ← npm 包
+├── cli.js
+├── main.py
+├── scripts/
+│   └── setup-python-env.js       ← npm postinstall
+└── core/
+    └── env_checker.py            ← Python 环境检查器
+```
+
+### 状态记录文件
+
+**路径**：`~/.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",
+    "system_python": "C:/Python311/python.exe"
+  },
+  "venv": {
+    "path": "C:/Users/xxx/.kite/venv",
+    "exists": true,
+    "valid": true
+  },
+  "dependencies": {
+    "installed": true,
+    "requirements_hash": "abc123..."
+  },
+  "error": null
+}
+```
+
+**失败时的错误结构**：
+```json
+{
+  "status": "failed",
+  "error": {
+    "type": "missing_python" | "wrong_version" | "missing_dependencies" | "venv_failed",
+    "message": "具体错误信息",
+    "details": {...}
+  }
+}
+```
+
+## 执行流程
+
+### 1. npm install（一次性）
+
+```
+npm install -g @agentunion/kite
+    ↓
+postinstall 钩子执行
+    ↓
+scripts/setup-python-env.js
+    ↓
+检测系统 Python 3.8+
+    ├─ 有 → 完成
+    └─ 没有 → 下载 Python embeddable（仅 Windows）
+```
+
+**职责**：只确保 Python 可用，不创建虚拟环境，不安装依赖
+
+### 2. kite start（每次启动）
+
+```
+用户执行: kite start
+    ↓
+cli.js (Node.js 层)
+    ├─ 检查框架代码是否安装
+    └─ 调用: python main.py
+         ↓
+main.py (Python 层)
+    ├─ 调用 env_checker.check_environment()
+    ├─ 读取 ~/.kite/env_status.json
+    ├─ status === "success"?
+    │   ├─ YES → 跳过检查（快速启动）
+    │   └─ NO  → 运行完整诊断
+    │        ↓
+    │   完整诊断流程：
+    │   1. 检查 Python 版本
+    │   2. 检查虚拟环境（不存在则创建）
+    │   3. 检查依赖库（缺失则安装）
+    │        ↓
+    │   更新 env_status.json
+    │   ├─ 成功 → status = "success"
+    │   └─ 失败 → status = "failed" + 错误信息
+    └─ 启动 Launcher
+```
+
+## 触发完整检查的条件
+
+1. **首次运行**：`env_status.json` 不存在
+2. **上次失败**：`status === "failed"`
+3. **依赖更新**：`requirements.txt` 的 hash 变化
+4. **环境损坏**：虚拟环境目录被删除
+5. **手动触发**：`kite doctor` 或 `python core/env_checker.py`
+
+## 关键优化
+
+### 快速启动机制
+
+**正常情况**（环境已就绪）：
+```
+kite start
+    ↓
+读取 env_status.json
+    ↓
+status === "success" → 直接启动（< 1 秒）
+```
+
+**首次启动或环境变更**：
+```
+kite start
+    ↓
+完整诊断（创建 venv + 安装依赖）
+    ↓
+更新 env_status.json
+    ↓
+启动（首次约 1-3 分钟）
+```
+
+### Hash 机制
+
+使用 SHA256 计算 `requirements.txt` 的 hash：
+- 依赖未变化 → 跳过检查
+- 依赖有更新 → 自动重新安装
+
+## 实现文件
+
+### 1. scripts/setup-python-env.js（npm 层）
+
+**职责**：
+- 检测系统 Python 3.8+
+- 如果没有，下载 Python embeddable（仅 Windows）
+
+**不做**：
+- ❌ 不创建虚拟环境
+- ❌ 不安装依赖
+
+### 2. core/env_checker.py（Python 层）
+
+**核心函数**：
+
+```python
+def check_environment() -> bool:
+    """检查环境是否就绪"""
+    # 1. 加载状态
+    status = load_status()
+
+    # 2. 判断是否需要完整检查
+    need_check, reason = should_run_full_check(status)
+
+    if not need_check:
+        return True  # 快速启动
+
+    # 3. 运行完整检查
+    success, error_data = run_full_check()
+
+    # 4. 保存状态
+    save_status(status_data)
+
+    return success
+```
+
+**完整检查流程**：
+
+```python
+def run_full_check() -> Tuple[bool, Dict]:
+    """运行完整的环境检查"""
+    # 1. 检查 Python 版本
+    py_ok, py_version = check_python_version()
+
+    # 2. 检查虚拟环境（不存在则创建）
+    venv_ok, venv_msg = check_venv_exists()
+    if not venv_ok:
+        create_venv()
+
+    # 3. 检查依赖（缺失则安装）
+    deps_ok, deps_msg = check_dependencies_installed()
+    if not deps_ok:
+        install_dependencies()
+
+    return success, error_data
+```
+
+### 3. main.py（入口）
+
+```python
+from core.env_checker import check_environment
+
+if not check_environment():
+    print("环境检查失败")
+    sys.exit(1)
+
+# 启动 Launcher
+from launcher.entry import start_launcher
+start_launcher()
+```
+
+### 4. cli.js（npm 入口）
+
+```javascript
+// 使用系统 Python（env_checker 会处理 venv）
+const python = process.platform === 'win32' ? 'python' : 'python3';
+const child = spawn(python, [path.join(versionDir, 'main.py')], {...});
+```
+
+## 用户体验
+
+### 首次安装
+
+```bash
+npm install -g @agentunion/kite
+```
+
+**输出**：
+```
+[Kite Setup] 检查 Python 环境...
+[Kite Setup] 检测到系统 Python: Python 3.11.5
+[Kite Setup] Python 环境检查完成
+[Kite Setup] 虚拟环境和依赖将在首次运行 kite 时自动准备
+```
+
+### 首次启动
+
+```bash
+kite start
+```
+
+**输出**：
+```
+[环境检查] 需要完整检查（首次运行）
+[环境检查] 开始完整诊断...
+[环境检查] ✓ Python 版本: 3.11.5
+[环境检查] ✗ 虚拟环境: 虚拟环境目录不存在
+[环境检查] 正在创建虚拟环境: C:\Users\xxx\.kite\venv
+[环境检查] 虚拟环境创建成功
+[环境检查] ✓ 虚拟环境: 虚拟环境正常
+[环境检查] ✗ 依赖库: pip 不存在
+[环境检查] 正在安装依赖: requirements.txt
+... (安装进度)
+[环境检查] 依赖安装完成
+[环境检查] ✓ 依赖库: 依赖正常
+[环境检查] 完整诊断通过
+[环境检查] 环境就绪
+... (Kite 启动)
+```
+
+### 后续启动（快速）
+
+```bash
+kite start
+```
+
+**输出**：
+```
+[环境检查] 跳过检查（环境正常）
+... (Kite 启动)
+```
+
+## 故障排查
+
+### 手动运行环境检查
+
+```bash
+python core/env_checker.py
+```
+
+### 查看状态文件
+
+```bash
+cat ~/.kite/env_status.json
+```
+
+### 强制重新检查
+
+```bash
+rm ~/.kite/env_status.json
+kite start
+```
+
+### 清理环境重新开始
+
+```bash
+rm -rf ~/.kite/venv
+rm ~/.kite/env_status.json
+kite start
+```
+
+## 优势总结
+
+1. **用户无感知**：自动处理所有环境准备
+2. **快速启动**：环境就绪后跳过检查（< 1 秒）
+3. **智能检测**：只在必要时运行完整诊断
+4. **结构化错误**：失败时提供清晰的错误信息
+5. **自动修复**：检测到问题自动尝试修复
+6. **跨平台兼容**：Windows/Linux/macOS 完全兼容
+
+## 未来改进
+
+1. **并行安装**：虚拟环境创建和依赖安装并行
+2. **增量更新**：只安装变更的依赖
+3. **离线模式**：支持离线安装包
+4. **健康检查**：定期检查环境健康度
+5. **自动清理**：清理过期的虚拟环境