@agentunion/kite 1.5.0 → 1.6.0

package/docs//345/256/211/350/243/205/350/204/232/346/234/254/345/274/200/345/217/221/346/226/207/346/241/243.md

@@ -0,0 +1,643 @@
+# Kite 安装脚本开发文档
+
+## 概述
+
+本文档记录 Kite 框架的自动化安装方案设计与实现。
+
+## 设计目标
+
+1. **一键安装** - 用户只需一条命令即可完成安装
+2. **跨平台支持** - Linux、macOS、Windows 全平台兼容
+3. **自动依赖管理** - 自动检测和安装 Python、Node.js 等依赖
+4. **虚拟环境隔离** - 使用 Python venv 避免污染系统环境
+5. **智能降级** - 多种安装方式，自动选择最佳方案
+
+## 系统要求
+
+### 必需依赖
+
+| 依赖 | 最低版本 | 用途 |
+|------|---------|------|
+| Python | 3.8+ | 核心运行时 |
+| Node.js | 16+ | CLI 工具 |
+
+### 可选依赖
+
+| 依赖 | 平台 | 用途 |
+|------|------|------|
+| Git | 全平台 | 下载和更新（推荐）|
+| D-Bus | Linux | 蓝牙支持 |
+| PulseAudio | Linux | 音频支持 |
+
+### Python 依赖包
+
+核心依赖（必需）：
+```
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+websockets>=13.0
+pyyaml>=6.0
+json5>=0.9.0
+aiofiles>=24.1.0
+httpx>=0.27.0
+```
+
+完整依赖（可选，见 requirements.txt）：
+```
+openai>=1.50.0
+anthropic>=0.39.0
+google-generativeai>=0.8.0
+edge-tts>=6.1.0
+webrtcvad>=2.0.10
+cryptography>=42.0.0
+python-multipart>=0.0.12
+mcp>=1.0.0
+dasbus>=1.7          # Linux only
+pasimple>=0.0.2      # Linux only
+```
+
+## 安装方式对比
+
+### 方案 A：curl | bash（推荐）
+
+**优点：**
+- 用户体验最好，一条命令完成
+- 可以处理复杂的安装逻辑
+- 易于更新和维护
+- 业界标准做法
+
+**缺点：**
+- 需要用户信任服务器
+- 需要 HTTPS 域名托管
+
+**使用场景：** 主要安装方式
+
+**示例：**
+```bash
+# Linux/macOS
+curl -fsSL https://kite.dev/install.sh | bash
+
+# Windows
+iwr -useb https://kite.dev/install.ps1 | iex
+```
+
+### 方案 B：包管理器
+
+**优点：**
+- 用户熟悉的安装方式
+- 自动处理依赖
+- 易于更新和卸载
+
+**缺点：**
+- 需要维护多个平台的包
+- 审核流程可能较慢
+
+**使用场景：** 备选安装方式
+
+**示例：**
+```bash
+# Homebrew (macOS/Linux)
+brew install kite
+
+# npm (跨平台)
+npm install -g @agentunion/kite
+
+# apt (Debian/Ubuntu)
+sudo apt install kite
+
+# winget (Windows)
+winget install agentcp.kite
+```
+
+### 方案 C：手动安装
+
+**优点：**
+- 完全可控
+- 适合离线环境
+
+**缺点：**
+- 步骤繁琐
+- 容易出错
+
+**使用场景：** 自动安装失败时的备选方案
+
+## 安装脚本架构
+
+### Unix/Linux/macOS (install.sh)
+
+```
+install.sh
+├── 检测平台 (detect_platform)
+├── 检查 Python (check_python)
+│   └── 安装 Python (install_python)
+├── 检查 Node.js (check_nodejs)
+│   └── 安装 Node.js (install_nodejs)
+├── 检查系统依赖 (check_system_deps)
+├── 下载 Kite (download_kite)
+│   ├── Git clone (优先)
+│   └── Tarball 下载 (降级)
+├── 创建虚拟环境 (setup_venv)
+├── 安装 Python 依赖 (install_python_deps)
+├── 安装 Node.js 依赖 (install_node_deps)
+├── 创建启动器 (create_launcher)
+├── 配置 PATH (configure_path)
+├── 初始化配置 (init_config)
+└── 验证安装 (verify_installation)
+```
+
+### Windows (install.ps1)
+
+```
+install.ps1
+├── 检测管理员权限 (Test-Administrator)
+├── 检查 Python (Test-Python)
+│   └── 安装 Python (Install-Python)
+│       ├── winget (优先)
+│       ├── Chocolatey (降级)
+│       └── 手动下载 (最后)
+├── 检查 Node.js (Test-NodeJS)
+│   └── 安装 Node.js (Install-NodeJS)
+├── 检查 Git (Test-Git)
+│   └── 安装 Git (Install-Git)
+├── 下载 Kite (Get-Kite)
+│   ├── Git clone (优先)
+│   └── ZIP 下载 (降级)
+├── 创建虚拟环境 (New-VirtualEnv)
+├── 安装 Python 依赖 (Install-PythonDeps)
+├── 安装 Node.js 依赖 (Install-NodeDeps)
+├── 创建启动器 (New-Launcher)
+│   ├── kite.bat (CMD)
+│   └── kite.ps1 (PowerShell)
+├── 配置 PATH (Set-EnvironmentPath)
+├── 初始化配置 (Initialize-Config)
+└── 验证安装 (Test-Installation)
+```
+
+## 安装目录结构
+
+### Linux/macOS
+
+```
+~/.kite/
+├── versions/              # 版本目录
+│   ├── 1.4.0/            # 当前版本
+│   │   ├── venv/         # Python 虚拟环境
+│   │   │   ├── bin/
+│   │   │   ├── lib/
+│   │   │   └── ...
+│   │   ├── launcher/     # Kite 核心模块
+│   │   ├── kernel/
+│   │   ├── extensions/
+│   │   ├── main.py
+│   │   ├── cli.js
+│   │   └── ...
+│   └── 1.3.0/            # 旧版本（可选）
+├── bin/                   # 可执行文件
+│   └── kite              # 启动脚本
+├── data/                  # 全局数据
+├── workspace/             # 工作空间
+│   └── <project>/        # 项目实例
+├── modules/               # 模块目录
+├── repo/                  # 仓库缓存
+├── config.yaml            # 全局配置
+└── current_version        # 当前版本标记
+```
+
+### Windows
+
+```
+C:\Users\<用户名>\.kite\
+├── versions\
+│   └── 1.4.0\
+│       ├── venv\
+│       │   ├── Scripts\
+│       │   ├── Lib\
+│       │   └── ...
+│       ├── launcher\
+│       ├── kernel\
+│       ├── extensions\
+│       ├── main.py
+│       ├── cli.js
+│       └── ...
+├── bin\
+│   ├── kite.bat          # CMD 启动脚本
+│   └── kite.ps1          # PowerShell 启动脚本
+├── data\
+├── workspace\
+├── modules\
+├── repo\
+├── config.yaml
+└── current_version
+```
+
+## 启动器设计
+
+### Unix/Linux/macOS (kite)
+
+```bash
+#!/usr/bin/env bash
+KITE_HOME="${KITE_HOME:-$HOME/.kite}"
+KITE_VERSION=$(cat "$KITE_HOME/current_version" 2>/dev/null || echo "latest")
+KITE_DIR="$KITE_HOME/versions/$KITE_VERSION"
+
+# 激活虚拟环境
+if [ -f "$KITE_DIR/venv/bin/activate" ]; then
+    source "$KITE_DIR/venv/bin/activate"
+fi
+
+# 运行 Kite
+if [ -f "$KITE_DIR/cli.js" ]; then
+    node "$KITE_DIR/cli.js" "$@"
+elif [ -f "$KITE_DIR/main.py" ]; then
+    python "$KITE_DIR/main.py" "$@"
+else
+    echo "Error: Kite not found at $KITE_DIR"
+    exit 1
+fi
+```
+
+### Windows (kite.bat)
+
+```batch
+@echo off
+setlocal
+
+set KITE_HOME=%USERPROFILE%\.kite
+if exist "%KITE_HOME%\current_version" (
+    set /p KITE_VERSION=<"%KITE_HOME%\current_version"
+) else (
+    set KITE_VERSION=latest
+)
+
+set KITE_DIR=%KITE_HOME%\versions\%KITE_VERSION%
+
+REM 激活虚拟环境
+if exist "%KITE_DIR%\venv\Scripts\activate.bat" (
+    call "%KITE_DIR%\venv\Scripts\activate.bat"
+)
+
+REM 运行 Kite
+if exist "%KITE_DIR%\cli.js" (
+    node "%KITE_DIR%\cli.js" %*
+) else if exist "%KITE_DIR%\main.py" (
+    python "%KITE_DIR%\main.py" %*
+) else (
+    echo Error: Kite not found at %KITE_DIR%
+    exit /b 1
+)
+```
+
+## 依赖安装策略
+
+### Python 安装
+
+**Linux:**
+1. apt-get (Debian/Ubuntu)
+2. yum (CentOS/RHEL)
+3. dnf (Fedora)
+4. pacman (Arch)
+
+**macOS:**
+1. Homebrew (推荐)
+2. 手动下载
+
+**Windows:**
+1. winget (Windows 10+)
+2. Chocolatey
+3. 手动下载安装器
+
+### Node.js 安装
+
+**Linux:**
+1. NodeSource 仓库 (推荐)
+2. 系统包管理器
+
+**macOS:**
+1. Homebrew
+
+**Windows:**
+1. winget
+2. Chocolatey
+3. 手动下载 MSI
+
+### Python 依赖安装
+
+```bash
+# 核心依赖（最小化安装）
+pip install fastapi uvicorn websockets pyyaml json5 aiofiles httpx
+
+# 完整依赖（从 requirements.txt）
+pip install -r requirements.txt
+
+# Linux 特定依赖
+pip install dasbus pasimple  # Linux only
+```
+
+## 虚拟环境管理
+
+### 创建虚拟环境
+
+```bash
+# Unix/Linux/macOS
+python3 -m venv ~/.kite/versions/1.4.0/venv
+
+# Windows
+python -m venv %USERPROFILE%\.kite\versions\1.4.0\venv
+```
+
+### 激活虚拟环境
+
+```bash
+# Unix/Linux/macOS
+source ~/.kite/versions/1.4.0/venv/bin/activate
+
+# Windows (CMD)
+%USERPROFILE%\.kite\versions\1.4.0\venv\Scripts\activate.bat
+
+# Windows (PowerShell)
+& $env:USERPROFILE\.kite\versions\1.4.0\venv\Scripts\Activate.ps1
+```
+
+### 优点
+
+1. **依赖隔离** - 不污染系统 Python 环境
+2. **版本管理** - 每个 Kite 版本独立的依赖
+3. **易于清理** - 删除目录即可完全卸载
+4. **跨平台一致** - 所有平台使用相同的机制
+
+## 环境变量配置
+
+### KITE_HOME
+
+**用途：** Kite 安装根目录
+
+**默认值：**
+- Linux/macOS: `~/.kite`
+- Windows: `%USERPROFILE%\.kite`
+
+**配置方法：**
+
+```bash
+# Linux/macOS (~/.bashrc 或 ~/.zshrc)
+export KITE_HOME="$HOME/.kite"
+export PATH="$KITE_HOME/bin:$PATH"
+
+# Windows (系统环境变量)
+KITE_HOME=C:\Users\<用户名>\.kite
+Path=%KITE_HOME%\bin;%Path%
+```
+
+### 其他环境变量
+
+```bash
+KITE_VERSION=1.4.0           # 当前使用的版本
+KITE_ENV=production          # 运行环境 (development/production)
+KITE_DATA=$KITE_HOME/data    # 数据目录
+KITE_WORKSPACE=$KITE_HOME/workspace  # 工作空间目录
+```
+
+## 版本管理
+
+### 多版本共存
+
+```
+~/.kite/versions/
+├── 1.4.0/    # 当前版本
+├── 1.3.0/    # 旧版本
+└── dev/      # 开发版本
+```
+
+### 切换版本
+
+```bash
+# 方法 1: 修改 current_version 文件
+echo "1.3.0" > ~/.kite/current_version
+
+# 方法 2: 使用 kite 命令
+kite use 1.3.0
+
+# 方法 3: 临时使用特定版本
+KITE_VERSION=1.3.0 kite start
+```
+
+## 更新机制
+
+### 自动更新
+
+```bash
+# 检查更新
+kite update --check
+
+# 更新到最新版本
+kite update
+
+# 更新到指定版本
+kite update --version 1.5.0
+```
+
+### 手动更新
+
+```bash
+# 重新运行安装脚本
+curl -fsSL https://kite.dev/install.sh | bash
+```
+
+## 卸载流程
+
+### 完全卸载
+
+```bash
+# Linux/macOS
+rm -rf ~/.kite
+# 从 ~/.bashrc 或 ~/.zshrc 中删除 KITE_HOME 相关行
+
+# Windows
+Remove-Item -Recurse -Force $env:USERPROFILE\.kite
+# 从系统环境变量中删除 PATH 条目
+```
+
+### 保留数据卸载
+
+```bash
+# 只删除程序文件，保留数据
+rm -rf ~/.kite/versions
+rm -rf ~/.kite/bin
+# 保留 ~/.kite/data 和 ~/.kite/workspace
+```
+
+## 常见问题处理
+
+### Python 版本过低
+
+**问题：** 系统 Python 版本低于 3.8
+
+**解决方案：**
+```bash
+# Linux
+sudo apt install python3.12
+
+# macOS
+brew install python@3.12
+
+# Windows
+winget install Python.Python.3.12
+```
+
+### 缺少 json5 模块
+
+**问题：** `ModuleNotFoundError: No module named 'json5'`
+
+**解决方案：**
+```bash
+# 激活虚拟环境
+source ~/.kite/versions/1.4.0/venv/bin/activate
+
+# 安装 json5
+pip install json5
+```
+
+### Windows 执行策略错误
+
+**问题：** PowerShell 脚本执行被阻止
+
+**解决方案：**
+```powershell
+# 临时允许（当前会话）
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+
+# 永久允许（当前用户）
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+### Linux 缺少系统依赖
+
+**问题：** 编译 Python 包时缺少头文件
+
+**解决方案：**
+```bash
+# Ubuntu/Debian
+sudo apt install build-essential libdbus-1-dev libpulse-dev portaudio19-dev
+
+# CentOS/RHEL
+sudo yum install gcc dbus-devel pulseaudio-libs-devel portaudio-devel
+
+# Arch
+sudo pacman -S base-devel dbus pulseaudio portaudio
+```
+
+## 测试清单
+
+### 平台测试
+
+- [ ] Ubuntu 20.04 LTS
+- [ ] Ubuntu 22.04 LTS
+- [ ] Debian 11
+- [ ] CentOS 8
+- [ ] Fedora 38
+- [ ] Arch Linux
+- [ ] macOS 12 (Monterey)
+- [ ] macOS 13 (Ventura)
+- [ ] macOS 14 (Sonoma)
+- [ ] Windows 10
+- [ ] Windows 11
+
+### 场景测试
+
+- [ ] 全新安装（无 Python/Node.js）
+- [ ] 已有 Python 3.8+
+- [ ] 已有 Node.js 16+
+- [ ] 已有旧版本 Kite
+- [ ] 离线环境（无 Git）
+- [ ] 虚拟机环境
+- [ ] Docker 容器
+- [ ] WSL (Windows Subsystem for Linux)
+
+### 功能测试
+
+- [ ] 依赖自动安装
+- [ ] 虚拟环境创建
+- [ ] PATH 配置
+- [ ] 启动器创建
+- [ ] 版本切换
+- [ ] 更新功能
+- [ ] 卸载清理
+
+## 部署清单
+
+### 准备工作
+
+1. [ ] 创建 GitHub 仓库
+2. [ ] 添加 install.sh 到仓库
+3. [ ] 添加 install.ps1 到仓库
+4. [ ] 创建 requirements.txt
+5. [ ] 更新 README.md
+6. [ ] 创建 INSTALL.md
+
+### 可选：自定义域名
+
+1. [ ] 购买域名（如 kite.dev）
+2. [ ] 配置 DNS
+3. [ ] 设置 HTTPS
+4. [ ] 托管安装脚本
+5. [ ] 配置 CDN（可选）
+
+### 发布
+
+1. [ ] 创建 GitHub Release
+2. [ ] 发布到 npm（可选）
+3. [ ] 提交到 Homebrew（可选）
+4. [ ] 提交到 winget（可选）
+5. [ ] 更新文档网站
+
+## 维护指南
+
+### 定期维护
+
+- **每月：** 更新依赖版本
+- **每季度：** 测试新平台版本
+- **每年：** 审查安装流程
+
+### 监控指标
+
+- 安装成功率
+- 平均安装时间
+- 常见错误类型
+- 平台分布
+
+### 用户反馈
+
+- GitHub Issues
+- 用户调查
+- 社区讨论
+
+## 参考资料
+
+### 类似项目
+
+- **Homebrew**: https://brew.sh
+- **Rust**: https://rustup.rs
+- **Node Version Manager**: https://github.com/nvm-sh/nvm
+- **pyenv**: https://github.com/pyenv/pyenv
+
+### 技术文档
+
+- Python venv: https://docs.python.org/3/library/venv.html
+- npm scripts: https://docs.npmjs.com/cli/v9/using-npm/scripts
+- PowerShell: https://docs.microsoft.com/powershell
+
+## 更新日志
+
+### 2026-03-07
+
+- 创建初始版本
+- 实现 Unix/Linux/macOS 安装脚本
+- 实现 Windows PowerShell 安装脚本
+- 添加虚拟环境支持
+- 添加自动依赖安装
+- 创建安装文档
+
+---
+
+**文档版本：** 1.0.0
+**最后更新：** 2026-03-07
+**维护者：** agentcp