@agentunion/kite 1.5.0 → 1.6.1

package/docs//346/250/241/345/235/227/345/256/211/350/243/205/346/234/272/345/210/266/350/256/276/350/256/241.md

@@ -0,0 +1,500 @@
+# Kite 模块安装机制设计文档
+
+## 一、概述
+
+Kite 模块安装机制是一个**跨平台下载壳**，通过统一的 CLI 接口，调用各平台（PyPI、npm、Git）的原生命令下载模块，验证 `module.md` 后安装到指定位置。
+
+### 核心原则
+
+1. **零共享代码依赖** — CLI 工具独立实现，不依赖 Kite 运行时
+2. **平台原生命令** — 使用 `pip`、`npm`、`git` 等原生工具下载
+3. **先检查后下载** — 先查询各平台是否存在，再下载
+4. **module.md 验证** — 下载后验证模块名是否匹配
+5. **多位置支持** — 开发环境、本地实例、全局共享
+
+## 二、安装位置
+
+| 位置 | 路径 | 环境变量 | 用途 |
+|------|------|----------|------|
+| **开发环境** | `{KITE_PROJECT}/extensions/` | `KITE_PROJECT` | 模块开发、调试 |
+| **本地实例** | `{KITE_INSTANCE_DIR}/extensions/` | `KITE_INSTANCE_DIR` | 当前实例专用 |
+| **全局共享** | `{KITE_MODULES}` | `KITE_MODULES` | 所有实例共享（默认 `~/.kite/modules/`） |
+
+**Launcher 扫描配置**（需在 `launcher/module.md` 中添加）：
+
+```yaml
+discovery:
+  # 已有的扫描路径
+  test_modules:
+    type: scan_dir
+    path: test_modules
+    enabled: true
+
+  # 新增：全局共享模块
+  global_modules:
+    type: scan_dir
+    path: ${KITE_MODULES}
+    max_depth: 2
+    enabled: true
+```
+
+## 三、CLI 命令接口
+
+### 3.1 安装命令
+
+```bash
+kite install <source> [options]
+```
+
+**参数**：
+- `<source>` — 平台下载参数（模块名、Git URL、本地路径等）
+- `-l, --location <dev|local|global>` — 安装位置（默认：交互式询问）
+- `-f, --from <pypi|npm|git|local>` — 指定平台（默认：自动检测）
+- `-y, --yes` — 跳过确认
+- `--no-deps` — 不安装依赖
+
+**示例**：
+```bash
+kite install watchdog-plus                    # 自动搜索所有平台
+kite install watchdog-plus -l global          # 安装到全局
+kite install watchdog-plus -f pypi            # 只从 PyPI 搜索
+kite install https://github.com/user/mod.git  # 从 Git 安装
+kite install ./my-module -f local             # 从本地安装
+```
+
+### 3.2 其他命令
+
+| 命令 | 说明 |
+|------|------|
+| `kite uninstall <name> [-l <location>]` | 卸载模块 |
+| `kite update <name> [-l <location>]` | 更新模块（使用记录的来源） |
+| `kite list [--all] [-v]` | 列出已安装模块 |
+| `kite search <keyword> [-f <platform>]` | 搜索可用模块 |
+| `kite info <name>` | 显示模块详细信息 |
+
+## 四、安装流程
+
+### 4.1 完整流程图
+
+```
+用户执行: kite install watchdog-plus
+    ↓
+┌─────────────────────────────────────┐
+│ 1. 解析命令行参数                    │
+│    - source: watchdog-plus          │
+│    - location: 未指定（需询问）      │
+│    - from: 未指定（自动检测）        │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 2. 并行检查各平台是否存在            │
+│    - PyPI: pip index versions       │
+│    - npm: npm view                  │
+│    - Git: GitHub API 搜索           │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 3. 收集检查结果                      │
+│    - PyPI: 找到 v1.2.0              │
+│    - npm: 未找到                    │
+│    - Git: 找到 user/watchdog-plus   │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 4. 用户选择来源（如果有多个）        │
+│    [1] PyPI: watchdog-plus v1.2.0   │
+│    [2] Git: user/watchdog-plus      │
+│    ? 选择: 1                        │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 5. 下载到临时目录                    │
+│    pip download watchdog-plus       │
+│    --dest /tmp/kite-install-xyz     │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 6. 验证 module.md                   │
+│    - 检查文件是否存在                │
+│    - 解析 YAML frontmatter          │
+│    - 验证 name 字段是否匹配          │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 7. 检查模块冲突                      │
+│    - 目标位置是否已存在同名模块      │
+│    - 询问：覆盖/跳过/重命名          │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 8. 安装依赖                          │
+│    - Python: 创建 .venv + pip       │
+│    - npm: npm install               │
+│    - Kite 模块: 递归安装            │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 9. 用户选择安装位置（如果未指定）    │
+│    [1] 开发环境 (Kite/extensions/)  │
+│    [2] 本地实例 (~/.kite/workspace) │
+│    [3] 全局共享 (~/.kite/modules/)  │
+│    ? 选择: 3                        │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 10. 复制到目标位置                   │
+│     cp -r /tmp/kite-xyz/*           │
+│     ~/.kite/modules/watchdog-plus/  │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 11. 记录安装信息                     │
+│     写入 .kite_install.json         │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 12. 清理临时文件                     │
+│     rm -rf /tmp/kite-install-xyz    │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 13. 提示用户重启 Kite                │
+│     ✅ 安装完成，重启生效            │
+└─────────────────────────────────────┘
+```
+
+### 4.2 关键步骤说明
+
+#### 步骤 2：并行检查各平台
+
+**PyPI**：
+```bash
+pip index versions watchdog-plus 2>/dev/null
+# 或使用 API
+curl -s https://pypi.org/pypi/watchdog-plus/json
+```
+
+**npm**：
+```bash
+npm view watchdog-plus version 2>/dev/null
+# 或
+npm search watchdog-plus --json
+```
+
+**Git (GitHub)**：
+```bash
+# 搜索仓库
+curl -s "https://api.github.com/search/repositories?q=watchdog-plus+kite"
+# 或检查特定仓库
+git ls-remote https://github.com/user/watchdog-plus.git 2>/dev/null
+```
+
+#### 步骤 5：下载到临时目录
+
+**PyPI**：
+```bash
+pip download watchdog-plus --dest /tmp/kite-xyz --no-deps
+# 解压 .whl 或 .tar.gz
+```
+
+**npm**：
+```bash
+npm pack watchdog-plus --pack-destination /tmp/kite-xyz
+# 解压 .tgz
+tar -xzf /tmp/kite-xyz/watchdog-plus-1.2.0.tgz -C /tmp/kite-xyz
+```
+
+**Git**：
+```bash
+git clone https://github.com/user/watchdog-plus.git /tmp/kite-xyz/watchdog-plus
+```
+
+**本地**：
+```bash
+cp -r ./my-module /tmp/kite-xyz/my-module
+```
+
+#### 步骤 6：验证 module.md
+
+```python
+import yaml
+
+# 查找 module.md
+module_md = find_file(temp_dir, "module.md")
+if not module_md:
+    raise Error("未找到 module.md")
+
+# 解析 YAML frontmatter
+with open(module_md) as f:
+    content = f.read()
+    frontmatter = extract_yaml_frontmatter(content)
+
+# 验证 name 字段
+if frontmatter.get("name") != expected_name:
+    raise Error(f"模块名不匹配: 期望 {expected_name}, 实际 {frontmatter.get('name')}")
+```
+
+#### 步骤 8：安装依赖
+
+**Python 依赖**：
+```bash
+# 读取 module.md 中的 dependencies.python
+# 或读取 requirements.txt
+cd /tmp/kite-xyz/watchdog-plus
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+**npm 依赖**：
+```bash
+cd /tmp/kite-xyz/watchdog-plus
+npm install
+```
+
+**Kite 模块依赖**：
+```bash
+# 读取 module.md 中的 dependencies.kite
+# 递归调用 kite install
+kite install kernel -l global
+```
+
+#### 步骤 11：记录安装信息
+
+`.kite_install.json` 格式：
+```json
+{
+  "name": "watchdog-plus",
+  "version": "1.2.0",
+  "source": {
+    "type": "pypi",
+    "package": "watchdog-plus",
+    "version": "1.2.0"
+  },
+  "installed_at": "2026-03-06T15:30:00Z",
+  "installed_by": "kite-cli@1.0.0",
+  "location": "global",
+  "dependencies": {
+    "python": ["psutil==5.9.8", "watchdog==2.1.9"],
+    "npm": [],
+    "kite": []
+  }
+}
+```
+
+## 五、module.md 规范
+
+### 5.1 必需字段
+
+```yaml
+---
+name: watchdog-plus
+display_name: Watchdog Plus
+version: "1.2.0"
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+---
+```
+
+### 5.2 依赖声明（可选）
+
+```yaml
+---
+name: watchdog-plus
+# ... 其他字段 ...
+dependencies:
+  python:
+    - psutil>=5.9.0
+    - watchdog>=2.1.0
+  npm:
+    - ws@^8.0.0
+  kite:
+    - kernel>=1.0.0
+---
+```
+
+**依赖格式**：
+- `python` — 列表，每项是 pip 包规范（`package>=version`）
+- `npm` — 列表，每项是 npm 包规范（`package@version`）
+- `kite` — 列表，每项是 Kite 模块名（`module>=version`）
+
+## 六、目录结构
+
+### 6.1 Kite 项目结构
+
+```
+Kite/
+├── cli.js                      # CLI 入口（已有）
+├── kite_cli/                   # CLI 实现（新增）
+│   ├── __init__.py
+│   ├── main.py                 # Python CLI 入口
+│   ├── commands/               # 命令实现
+│   │   ├── __init__.py
+│   │   ├── install.py
+│   │   ├── uninstall.py
+│   │   ├── update.py
+│   │   ├── list.py
+│   │   └── search.py
+│   ├── core/                   # 核心功能
+│   │   ├── __init__.py
+│   │   ├── checker.py          # 平台检查
+│   │   ├── downloader.py       # 下载器
+│   │   ├── validator.py        # module.md 验证
+│   │   ├── installer.py        # 安装器
+│   │   └── dependency.py       # 依赖管理
+│   └── utils/                  # 工具函数
+│       ├── __init__.py
+│       ├── interactive.py      # 交互式问答
+│       ├── paths.py            # 路径处理
+│       └── logger.py           # 日志
+├── launcher/
+├── kernel/
+└── extensions/
+```
+
+### 6.2 用户目录结构
+
+```
+~/.kite/
+├── versions/                   # Kite 框架版本
+│   └── 1.3.2/
+├── modules/                    # 全局共享模块（KITE_MODULES）
+│   ├── watchdog-plus/
+│   │   ├── module.md
+│   │   ├── entry.py
+│   │   ├── .venv/              # Python 虚拟环境
+│   │   ├── node_modules/       # npm 依赖
+│   │   └── .kite_install.json  # 安装信息
+│   └── backup-service/
+├── workspace/                  # 实例工作区
+│   └── Kite/
+│       └── extensions/         # 本地实例模块
+├── data/                       # 运行时数据
+└── cache/                      # 下载缓存
+    └── downloads/
+```
+
+## 七、实现架构
+
+### 7.1 CLI 调用流程
+
+```
+用户: kite install watchdog-plus
+    ↓
+cli.js 解析参数
+    ↓
+识别到 install 子命令
+    ↓
+调用: python -m kite_cli install watchdog-plus
+    ↓
+kite_cli/main.py 路由到 commands/install.py
+    ↓
+install.py 调用 core/ 模块执行安装
+```
+
+### 7.2 核心模块职责
+
+**checker.py** — 平台检查
+- `check_pypi(name)` → 返回版本列表或 None
+- `check_npm(name)` → 返回版本列表或 None
+- `check_git(name)` → 返回仓库列表或 None
+- `check_all(name)` → 并行检查所有平台
+
+**downloader.py** — 下载器
+- `download_pypi(name, dest)` → 下载并解压
+- `download_npm(name, dest)` → 下载并解压
+- `download_git(url, dest)` → 克隆仓库
+- `download_local(path, dest)` → 复制目录
+
+**validator.py** — 验证器
+- `find_module_md(dir)` → 查找 module.md
+- `parse_module_md(path)` → 解析 YAML frontmatter
+- `validate_module(dir, expected_name)` → 验证模块
+
+**installer.py** — 安装器
+- `install_module(source, location, from_platform)` → 完整安装流程
+- `check_conflict(name, location)` → 检查冲突
+- `copy_to_location(src, dest)` → 复制模块
+- `record_install_info(module_dir, info)` → 记录安装信息
+
+**dependency.py** — 依赖管理
+- `install_python_deps(module_dir, packages)` → 安装 Python 依赖
+- `install_npm_deps(module_dir, packages)` → 安装 npm 依赖
+- `install_kite_deps(modules, location)` → 递归安装 Kite 模块
+
+### 7.3 交互式问答
+
+**interactive.py**：
+- `select_source(candidates)` → 用户选择来源
+- `select_location()` → 用户选择安装位置
+- `confirm_overwrite(name)` → 确认覆盖
+
+## 八、兼容性设计
+
+### 8.1 跨平台
+
+| 功能 | Windows | Linux | macOS |
+|------|---------|-------|-------|
+| 临时目录 | `%TEMP%\kite-install-*` | `/tmp/kite-install-*` | `/tmp/kite-install-*` |
+| Python 虚拟环境 | `.venv\Scripts\python.exe` | `.venv/bin/python` | `.venv/bin/python` |
+| 路径分隔符 | `pathlib.Path` 自动处理 | | |
+| 命令执行 | `subprocess.run()` 统一接口 | | |
+
+### 8.2 错误处理
+
+| 错误场景 | 处理策略 |
+|---------|---------|
+| 平台命令不存在（pip/npm/git） | 提示用户安装，跳过该平台 |
+| 下载失败 | 重试 3 次，失败后清理临时文件 |
+| module.md 不存在 | 报错，清理临时文件 |
+| 模块名不匹配 | 跳过该候选，尝试下一个平台 |
+| 依赖安装失败 | 询问用户：继续/回滚 |
+| 目标位置冲突 | 询问用户：覆盖/跳过/重命名 |
+
+## 九、安全机制
+
+1. **来源验证**
+   - Git 仓库必须 HTTPS（除非用户明确允许）
+   - PyPI/npm 使用官方源，不允许自定义源（除非配置）
+
+2. **代码审查**
+   - 安装前显示 `module.md` 内容
+   - 显示 `entry` 启动命令
+   - 询问用户确认（`-y` 跳过）
+
+3. **沙箱隔离**
+   - Python 依赖安装到模块内 `.venv`
+   - npm 依赖安装到模块内 `node_modules`
+   - 不污染全局环境
+
+4. **回滚机制**
+   - 安装失败时自动清理临时文件
+   - 覆盖安装前备份原模块到 `.kite_backup/`
+
+## 十、后续扩展
+
+### Phase 1（MVP）
+- ✅ 本地路径安装
+- ✅ PyPI/npm/Git 检查和下载
+- ✅ module.md 验证
+- ✅ 三种安装位置
+- ✅ 交互式问答
+
+### Phase 2
+- ⬜ 依赖安装（Python/npm/Kite）
+- ⬜ 卸载和更新命令
+- ⬜ 安装信息记录
+- ⬜ 冲突检测和处理
+
+### Phase 3
+- ⬜ Kite 官方仓库
+- ⬜ 版本锁定（kite.lock）
+- ⬜ 缓存机制
+- ⬜ 并行下载
+
+### Phase 4
+- ⬜ 模块签名验证
+- ⬜ 热更新（无需重启）
+- ⬜ 依赖树可视化
+- ⬜ Web UI 模块市场