@agentunion/kite 1.5.0 → 1.6.1

package/docs/CI/344/270/216AI/350/207/252/345/212/250/345/214/226/346/265/213/350/257/225/346/226/271/346/241/210.md

@@ -0,0 +1,75 @@
+# CI 与 AI 自动化测试方案
+
+> 状态：待实施（基础框架建设完成后再启动）
+
+## 一、CI（持续集成）
+
+### 工具选型
+
+| 工具 | 适合场景 | 成本 |
+|------|---------|------|
+| **GitHub Actions** | 代码在 GitHub 上 | 免费额度够用 |
+| **GitLab CI** | 代码在 GitLab 上 | 自带 |
+| **Jenkins** | 自建服务器、需要复杂流水线 | 免费但要自己维护 |
+
+### CI 流水线阶段
+
+```
+代码 push / PR
+  ↓
+Stage 1: 环境准备
+  - 安装 Python 依赖（requirements.txt）
+  - 安装 Node 依赖（package.json）
+  ↓
+Stage 2: 静态检查
+  - 代码风格（ruff / flake8）
+  - 类型检查（mypy，可选）
+  - 安全扫描（bandit，可选）
+  ↓
+Stage 3: 单元测试
+  - pytest 跑各模块的独立测试
+  - 不需要启动整个系统
+  ↓
+Stage 4: 集成测试
+  - 启动 Kite → 跑已有的前端测试
+  - 验证模块注册、RPC、事件等
+  ↓
+Stage 5: 报告
+  - 测试通过/失败 → GitHub PR 上显示状态
+  - 可选：覆盖率报告
+```
+
+### 当前项目差距
+
+- 已有：前端测试框架（Evol 控制台的模块测试 + 集成测试），但只能手动触发
+- 缺少：pytest 单元测试框架、CI 配置文件、代码检查工具、前端测试命令行触发方式
+
+## 二、AI 自动化测试
+
+### 三个层次
+
+#### 层次 1：AI 生成测试（最容易落地）
+
+- 用 LLM 批量生成单元测试
+- 做法：写脚本把模块代码喂给 LLM，生成 pytest 测试文件
+- 适合：工具函数、配置解析、数据处理等纯逻辑代码
+- 价值：快速补齐测试覆盖率
+
+#### 层次 2：AI 分析测试结果（中等难度）
+
+- CI 跑完测试后，把失败日志喂给 LLM 分析
+- 做法：GitHub Actions 步骤里加一步，调用 Claude API 分析失败原因，自动评论到 PR
+- 价值：减少人工排查时间
+
+#### 层次 3：AI 自动探索测试（较复杂）
+
+- AI 根据 API 文档和代码自主设计测试场景
+- 做法：Agent 模式——让 AI 读代码 → 设计测试用例 → 执行 → 判断结果 → 发现 bug
+- 价值：发现人想不到的边界情况
+
+## 三、建议落地路径
+
+1. **搭 CI 基础** — GitHub Actions + ruff 代码检查 + pytest 跑现有测试
+2. **补单元测试** — AI 批量生成关键模块测试（RPC 路由、配置加载、事件匹配、Token 认证）
+3. **集成测试自动化** — 前端测试改造为命令行触发（headless），CI 自动跑
+4. **AI 分析能力** — CI 失败时调 Claude API 分析日志，结果评论到 PR

package/docs/CLI/345/274/200/345/217/221/350/256/241/345/210/222.md

@@ -0,0 +1,595 @@
+# Kite CLI 开发计划
+
+## 当前状态
+
+**版本**: v1.0.0
+**最后更新**: 2026-03-09
+
+### 已完成功能 ✓
+
+**核心命令 (20个)**
+- [x] `install` - 安装模块 (支持 PyPI/npm/Git/local，支持版本号 @version，读取配置)
+- [x] `uninstall` - 卸载模块
+- [x] `update` - 更新模块 (支持 --to 指定版本，支持 --all 批量更新)
+- [x] `list` - 列出已安装模块 (分类显示，支持 --outdated/--disabled/--enabled)
+- [x] `search` - 搜索可用模块
+- [x] `info` - 显示模块详细信息
+- [x] `log` - 查看操作日志
+- [x] `history` - 查看最近安装的模块
+- [x] `rollback` - 回滚最后一次操作
+- [x] `clean` - 清理临时文件和缓存
+- [x] `doctor` - 检查下载工具状态
+- [x] `outdated` - 列出可更新的模块
+- [x] `enable` - 启用模块
+- [x] `disable` - 禁用模块
+- [x] `export` - 导出已安装模块列表 (支持 text/json 格式)
+- [x] `import` - 从文件批量安装模块
+- [x] `config` - 配置管理 (list/get/set/unset/reset)
+- [x] `prepare` - 打包前准备（扫描依赖，生成锁定文件）
+- [x] `env-check` - 环境检查（虚拟环境和依赖库）
+- [x] `venv-setup` - 创建虚拟环境
+- [x] `deps-install` - 安装依赖库
+
+**核心功能**
+- [x] 跨平台下载 (PyPI/npm/Git/local)
+- [x] 多位置安装 (dev/local/global)
+- [x] 依赖管理 (Python/npm/Git/Kite模块)
+- [x] 工具自动安装 (Python/pip/Node.js/npm/Git)
+- [x] 操作日志记录
+- [x] 国际化支持 (中英文)
+- [x] 错误处理和详细提示
+- [x] 保留名称保护
+- [x] 版本号解析和匹配 (semver: =, ^, ~, >, <, >=, <=, latest, 范围)
+
+---
+
+## Phase 1: 核心功能完善 (优先级: 高)
+
+### 1.1 版本管理增强
+
+**状态**: ✅ 已完成
+**预计工作量**: 2-3 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 支持版本号指定
+  - `kite install pkg@1.2.0` - 安装指定版本 ✓
+  - `kite install pkg@latest` - 安装最新版本 ✓
+  - `kite install pkg@^1.0.0` - 安装兼容版本 ✓
+- [x] 更新到指定版本
+  - `kite update pkg --to 2.0.0` - 更新到指定版本 ✓
+- [x] 显示可更新版本
+  - `kite list --outdated` - 列出可更新的模块 ✓
+  - `kite outdated` - 新命令,专门列出过期模块 ✓
+
+**技术要点**:
+- 解析版本号语法 (支持 @, ^, ~, >, <, >=, <=)
+- 调用平台 API 获取版本列表
+- 版本比较算法 (semver)
+- 更新 checker.py 支持版本查询
+- 更新 downloader.py 支持版本下载
+
+**测试用例**:
+```bash
+kite install requests@2.28.0
+kite install express@^4.0.0
+kite list --outdated
+kite outdated
+kite update requests --to 2.31.0
+```
+
+---
+
+### 1.2 模块启用/禁用
+
+**状态**: ✅ 已完成
+**预计工作量**: 1-2 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 启用模块
+  - `kite enable <name>` - 修改 module.md 的 state: enabled ✓
+- [x] 禁用模块
+  - `kite disable <name>` - 修改 module.md 的 state: disabled ✓
+- [x] 列出禁用模块
+  - `kite list --disabled` - 只显示禁用的模块 ✓
+  - `kite list --enabled` - 只显示启用的模块 ✓
+
+**技术要点**:
+- 读取并修改 module.md 的 YAML frontmatter
+- 保持文件格式和注释不变
+- 支持批量启用/禁用
+- 添加到操作日志
+
+**测试用例**:
+```bash
+kite disable watchdog
+kite list --disabled
+kite enable watchdog
+kite list --enabled
+```
+
+---
+
+### 1.3 批量操作
+
+**状态**: ✅ 已完成
+**预计工作量**: 2-3 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 批量更新
+  - `kite update --all` - 更新所有模块 ✓
+  - `kite update --all --dry-run` - 预览更新（暂未实现）
+- [x] 批量安装
+  - `kite install pkg1 pkg2 pkg3` - 一次安装多个（暂未实现）
+  - `kite install -r requirements.txt` - 从文件安装（通过 import 实现）✓
+- [x] 导出/导入
+  - `kite export > modules.txt` - 导出模块列表 ✓
+  - `kite export --format json > modules.json` - JSON 格式 ✓
+  - `kite import modules.txt` - 批量安装 ✓
+
+**技术要点**:
+- 并行安装优化
+- 失败处理策略 (继续/中断)
+- 导出格式设计 (包含版本、来源、位置)
+- 进度显示
+
+**测试用例**:
+```bash
+kite update --all
+kite install pkg1 pkg2 pkg3
+kite export > my-modules.txt
+kite import my-modules.txt
+```
+
+---
+
+### 1.4 配置管理
+
+**状态**: ✅ 已完成
+**预计工作量**: 2 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 配置命令
+  - `kite config list` - 列出所有配置 ✓
+  - `kite config get <key>` - 获取配置值 ✓
+  - `kite config set <key> <value>` - 设置配置 ✓
+  - `kite config unset <key>` - 删除配置 ✓
+  - `kite config reset` - 重置为默认值 ✓
+- [x] 支持的配置项
+  - `default_location` - 默认安装位置 (dev/local/global) ✓
+  - `pypi_mirror` - PyPI 镜像源 ✓
+  - `npm_registry` - npm 镜像源 ✓
+  - `auto_update_check` - 自动检查更新 ✓
+  - `confirm_install` - 安装前确认 (默认 true) ✓
+  - `confirm_uninstall` - 卸载前确认 ✓
+  - `confirm_update` - 更新前确认 ✓
+
+**技术要点**:
+- 配置文件路径: `~/.kite/data/cli_config.json`
+- 配置验证 (类型、取值范围)
+- 环境变量覆盖机制
+- 配置迁移
+
+**测试用例**:
+```bash
+kite config list
+kite config set default_location global
+kite config set pypi_mirror https://pypi.tuna.tsinghua.edu.cn/simple
+kite config get default_location
+kite config unset pypi_mirror
+```
+
+---
+
+## Phase 2: 用户体验优化 (优先级: 中)
+
+### 2.1 进度显示
+
+**状态**: ✅ 已完成
+**预计工作量**: 2-3 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 下载进度条
+  - 使用 tqdm 实现进度条 ✓
+  - 支持非 TTY 环境自动禁用 ✓
+  - 创建 ProgressBar 类 ✓
+  - 创建 DownloadProgress 类 ✓
+- [x] 依赖安装进度
+  - 批量操作进度条 ✓
+  - 显示当前操作的模块名 ✓
+- [x] 多步骤操作进度
+  - 创建 StepProgress 类 ✓
+  - 显示当前步骤和总步骤数 ✓
+  - 集成到 install 命令 ✓
+  - 集成到 update --all 命令 ✓
+  - 集成到 import 命令 ✓
+
+**技术要点**:
+- 使用 tqdm 库实现进度条
+- 实时更新进度（不换行）
+- 处理终端宽度变化
+- 支持非 TTY 环境（CI/CD）自动降级
+- ANSI 颜色支持
+
+**测试用例**:
+```bash
+kite install large-package  # 观察多步骤进度
+kite update --all           # 观察批量更新进度
+kite import modules.txt     # 观察批量安装进度
+```
+
+---
+
+### 2.2 交互优化
+
+**状态**: ✅ 已完成
+**预计工作量**: 2 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 彩色输出
+  - 成功消息 = 绿色 ✓
+  - 错误消息 = 红色 ✓
+  - 警告消息 = 黄色 ✓
+  - 信息消息 = 蓝色 ✓
+  - 创建 colors 工具模块 ✓
+  - 自动检测终端颜色支持 ✓
+  - 集成到 outdated 和 config 命令 ✓
+- [x] 表格化显示
+  - `kite list` 使用表格格式 ✓
+  - `kite search` 显示表格结果 ✓
+  - 创建 table 工具模块 ✓
+  - 支持 ANSI 颜色的列宽计算 ✓
+  - 集成到 list 和 search 命令 ✓
+- [ ] 更好的来源选择
+  - 显示模块描述
+  - 显示星标数/下载量
+  - 显示最后更新时间
+
+**技术要点**:
+- 使用 colorama 或 ANSI 转义码
+- 使用 tabulate 或自实现表格
+- 检测终端是否支持颜色
+- 支持 --no-color 选项
+
+**测试用例**:
+```bash
+kite list  # 观察表格输出
+kite search requests  # 观察彩色输出
+```
+
+---
+
+### 2.3 帮助完善
+
+**状态**: 待开始
+**预计工作量**: 1 天
+**负责人**: 待分配
+
+**功能需求**:
+- [ ] 补充命令详细用法
+  - `log` 命令的所有选项
+  - `rollback` 命令的限制说明
+  - `clean` 命令的清理范围
+  - `doctor` 命令的修复建议
+- [ ] 添加更多示例
+  - 常见使用场景
+  - 组合命令示例
+- [ ] 常见问题解答
+  - 安装失败怎么办
+  - 如何切换镜像源
+  - 如何卸载所有模块
+
+**技术要点**:
+- 更新 HELP_TEXT
+- 添加 --examples 选项
+- 添加 FAQ 文档
+
+---
+
+### 2.4 别名支持
+
+**状态**: ✅ 已完成
+**预计工作量**: 0.5 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 命令别名
+  - `kite i` = `kite install` ✓
+  - `kite add` = `kite install` ✓
+  - `kite rm` = `kite uninstall` ✓
+  - `kite remove` = `kite uninstall` ✓
+  - `kite up` = `kite update` ✓
+  - `kite upgrade` = `kite update` ✓
+  - `kite ls` = `kite list` ✓
+  - `kite show` = `kite list` ✓
+
+**技术要点**:
+- 在 main.py 中添加别名映射
+- 更新帮助文档显示别名
+
+**测试用例**:
+```bash
+kite i requests
+kite ls
+kite rm requests
+```
+
+---
+
+## Phase 3: 高级功能 (优先级: 中)
+
+### 3.1 依赖分析
+
+**状态**: ✅ 已完成
+**预计工作量**: 3 天
+**负责人**: 待分配
+
+**功能需求**:
+- [x] 依赖树显示
+  - `kite deps <name>` - 显示依赖树 ✓
+  - `kite deps <name> --depth 2` - 限制深度 ✓
+  - 创建 DependencyGraph 类 ✓
+  - 树形输出格式 ✓
+- [x] 反向依赖
+  - `kite why <name>` - 显示为什么安装了这个模块 ✓
+  - 显示依赖路径 ✓
+- [x] 依赖检查
+  - `kite check` - 检查依赖完整性 ✓
+  - 检测缺失依赖 ✓
+  - 检测循环依赖 ✓
+  - 统计信息显示 ✓
+
+**技术要点**:
+- 递归解析 module.md 的 dependencies
+- 构建依赖图（正向和反向）
+- 检测循环依赖（DFS + 递归栈）
+- 树形输出格式（带缩进和前缀）
+- 彩色高亮显示
+
+**测试用例**:
+```bash
+kite deps watchdog
+kite why some-package
+kite check
+```
+
+---
+
+### 3.2 模块开发辅助
+
+**状态**: 待开始
+**预计工作量**: 3-4 天
+**负责人**: 待分配
+
+**功能需求**:
+- [ ] 创建模块模板
+  - `kite init` - 交互式创建模块
+  - `kite init --name mymod --type service` - 指定参数
+- [ ] 验证模块
+  - `kite validate` - 验证当前目录的 module.md
+  - `kite validate <path>` - 验证指定路径
+- [ ] 打包模块
+  - `kite pack` - 打包为 .tar.gz
+  - `kite pack --output dist/` - 指定输出目录
+- [ ] 发布模块
+  - `kite publish` - 发布到配置的仓库
+  - `kite publish --registry <url>` - 指定仓库
+
+**技术要点**:
+- 模块模板设计
+- module.md schema 验证
+- 打包格式规范
+- 发布协议设计
+
+---
+
+### 3.3 缓存管理
+
+**状态**: 待开始
+**预计工作量**: 1-2 天
+**负责人**: 待分配
+
+**功能需求**:
+- [ ] 缓存命令
+  - `kite cache list` - 列出缓存内容
+  - `kite cache clean` - 清理所有缓存
+  - `kite cache clean --older-than 7d` - 清理旧缓存
+  - `kite cache path` - 显示缓存路径
+  - `kite cache size` - 显示缓存大小
+
+**技术要点**:
+- 缓存目录: `~/.kite/data/cli_cache/`
+- 缓存内容: 下载的包、API 响应
+- 缓存过期策略
+- 缓存大小限制
+
+---
+
+## Phase 4: 安全性增强 (优先级: 低)
+
+### 4.1 模块验证
+
+**状态**: 待开始
+**预计工作量**: 4-5 天
+**负责人**: 待分配
+
+**功能需求**:
+- [ ] 签名验证
+  - 验证模块签名
+  - 支持 GPG 签名
+- [ ] 哈希校验
+  - 下载后校验 SHA256
+  - 防止中间人攻击
+- [ ] 恶意代码扫描
+  - 基础规则扫描
+  - 检测可疑代码模式
+
+---
+
+### 4.2 权限管理
+
+**状态**: 待开始
+**预计工作量**: 2 天
+**负责人**: 待分配
+
+**功能需求**:
+- [ ] 权限检查
+  - 检查安装目录写权限
+  - 提示需要 sudo
+- [ ] 沙箱模式
+  - 隔离模块执行环境
+  - 限制文件系统访问
+
+---
+
+## Phase 5: 代码重构 (优先级: 低)
+
+### 5.1 消除重复代码
+
+**状态**: 待开始
+**预计工作量**: 2 天
+**负责人**: 待分配
+
+**任务**:
+- [ ] 提取 `find_module_locations()` 到 utils
+- [ ] 统一错误处理机制
+- [ ] 统一日志输出格式
+- [ ] 消除硬编码字符串
+
+---
+
+### 5.2 测试覆盖
+
+**状态**: 待开始
+**预计工作量**: 5-7 天
+**负责人**: 待分配
+
+**任务**:
+- [ ] 单元测试 (pytest)
+- [ ] 集成测试
+- [ ] 跨平台测试 (Windows/Linux/macOS)
+- [ ] CI/CD 集成
+
+---
+
+### 5.3 性能优化
+
+**状态**: 待开始
+**预计工作量**: 3 天
+**负责人**: 待分配
+
+**任务**:
+- [ ] 并行下载优化
+- [ ] 缓存优化
+- [ ] 启动速度优化
+- [ ] 内存占用优化
+
+---
+
+## 实施时间表
+
+**第一周**: Phase 1.1 + 1.2 (版本管理 + 启用/禁用)
+**第二周**: Phase 1.3 + 1.4 (批量操作 + 配置管理)
+**第三周**: Phase 2.1 + 2.2 (进度显示 + 交互优化)
+**第四周**: Phase 3.1 (依赖分析)
+**后续**: Phase 3.2, 3.3, 4, 5 (按需实施)
+
+---
+
+## 变更日志
+
+### 2026-03-10
+- ✅ 完成 Phase 1.4 配置管理
+  - 实现 `kite config` 命令（list/get/set/unset/reset）
+  - 创建 ConfigManager 配置管理器
+  - 配置文件：`~/.kite/data/cli_config.json`
+  - 支持 7 个配置项（default_location, pypi_mirror, npm_registry 等）
+  - install 命令集成配置读取（默认位置、镜像源）
+  - downloader 支持 PyPI 和 npm 镜像源配置
+  - 配置验证和类型检查
+  - 表格化显示配置（标记已修改项）
+- 🎉 **Phase 1 核心功能完善 - 全部完成！**
+  - 1.1 版本管理增强 ✅
+  - 1.2 模块启用/禁用 ✅
+  - 1.3 批量操作 ✅
+  - 1.4 配置管理 ✅
+- ✅ 完成 Phase 2.4 别名支持
+  - 实现 8 个命令别名（i/add/rm/remove/up/upgrade/ls/show）
+  - 在 argparse 解析前处理别名
+  - 更新帮助文档显示别名
+- ✅ 完成 Phase 2.2 交互优化
+  - 创建 colors 工具模块
+  - 支持 ANSI 颜色代码（成功/错误/警告/信息等）
+  - 自动检测终端颜色支持（Windows/Unix）
+  - 集成到 outdated 命令（高亮模块名、版本号）
+  - 集成到 config 命令（高亮已修改配置）
+  - 创建 table 工具模块
+  - 实现表格格式化（支持对齐、最小列宽、ANSI 颜色宽度计算）
+  - 集成到 list 命令（表格显示模块列表）
+  - 集成到 search 命令（表格显示搜索结果）
+- ✅ 完成 Phase 2.1 进度显示
+  - 创建 progress 工具模块
+  - 实现 ProgressBar 类（基于 tqdm，支持简单降级）
+  - 实现 DownloadProgress 类（下载进度显示）
+  - 实现 StepProgress 类（多步骤进度显示）
+  - 集成到 install 命令（7 步安装流程）
+  - 集成到 update --all 命令（批量更新进度条）
+  - 集成到 import 命令（批量安装进度条）
+  - 支持非 TTY 环境自动禁用
+  - 彩色进度显示（成功/失败状态）
+- 🎉 **Phase 2 用户体验优化 - 基本完成！**
+  - 2.1 进度显示 ✅
+  - 2.2 交互优化 ✅
+  - 2.4 别名支持 ✅
+  - 2.3 帮助完善 ⏳（待实施）
+- ✅ 完成 Phase 3.1 依赖分析
+  - 创建 dependency_graph 工具模块
+  - 实现 DependencyGraph 类（依赖图构建和分析）
+  - 实现 `kite deps` 命令（显示依赖树）
+  - 实现 `kite why` 命令（显示反向依赖和依赖路径）
+  - 实现 `kite check` 命令（检查依赖完整性）
+  - 支持缺失依赖检测
+  - 支持循环依赖检测
+  - 树形输出格式（带彩色高亮）
+  - 统计信息显示
+
+### 2026-03-09
+- ✅ 完成 Phase 1.1 版本管理增强
+  - 实现 `kite outdated` 命令
+  - 为 `kite list` 添加 `--outdated` 选项
+  - 支持按位置筛选可更新模块
+  - 表格化显示可更新模块信息
+- ✅ 完成 Phase 1.2 模块启用/禁用
+  - 实现 `kite enable <name>` 命令
+  - 实现 `kite disable <name>` 命令
+  - 为 `kite list` 添加 `--disabled` 和 `--enabled` 选项
+  - 支持读取和修改 module.md 的 state 字段
+  - 添加操作日志记录
+  - 在列表中显示模块状态（✓ 启用 / ○ 禁用）
+- ✅ 完成 Phase 1.3 批量操作
+  - 实现 `kite update --all` 批量更新所有模块
+  - 实现 `kite export` 导出模块列表（支持 text/json 格式）
+  - 实现 `kite import` 从文件批量安装模块
+  - 支持从 stdin 读取（`kite import -`）
+  - 显示批量操作进度和统计信息
+- 更新开发计划文档
+  - 更新已完成功能列表（19 个命令）
+  - 标记 Phase 1.1、1.2、1.3 完成状态
+  - Phase 1 核心功能完善全部完成！
+  - 准备开始实施 Phase 2（用户体验优化）
+
+### 2026-03-07
+- ✓ 实现 `kite update --to <version>` 功能
+  - 支持 PyPI 和 npm 平台的版本指定
+  - Git 源显示警告提示
+  - 更新帮助文档和确认提示
+
+### 2026-03-06
+- 创建开发计划文档
+- 定义 Phase 1-5 的详细任务
+- 设定优先级和时间表