@cloudbase/cli 2.11.6 → 2.11.7

package/specs/ai-cli-bootstrap/design.md

@@ -0,0 +1,185 @@
+# 技术方案设计
+
+## 整体架构
+
+### 核心组件
+- **AICommandRouter**: 命令路由与执行引擎
+- **AIConfigManager**: 配置管理与持久化
+- **AISetupWizard**: 交互式配置向导
+- **TemplateManager**: 模板下载与完整性校验
+
+### 技术栈
+- **语言**: TypeScript
+- **CLI框架**: 基于现有 CloudBase CLI 架构
+- **配置管理**: JSON + 环境变量
+- **模板系统**: 远程下载 + 本地解压
+- **终端美化**: figlet + gradient-string + chalk
+
+## 命令设计
+
+### 主命令结构
+```bash
+tcb ai [options] -- [agent-args]
+```
+
+### 核心选项
+- `-a, --agent <name>`: 指定 AI 工具 (claude/codex/gemini)
+- `-e, --envId <id>`: 云开发环境 ID
+- `--setup`: 启动配置向导
+- `--config`: 显示当前配置
+- `--reset`: 重置配置
+
+### 参数透传机制
+- 使用 `--` 分隔符实现参数透传
+- 支持所有 agent CLI 原生参数
+- 自动注入环境变量和配置
+
+## 多 Agent 配置
+
+### 配置结构
+```json
+{
+  "defaultAgent": "claude",
+  "agents": {
+    "claude": {
+      "command": "claude",
+      "apiKey": "sk-xxx",
+      "baseUrl": "https://api.anthropic.com",
+      "model": "claude-3.5-sonnet"
+    }
+  }
+}
+```
+
+### 协议适配
+- **Anthropic协议**: 直接透传 (claude, kimi, k2)
+- **OpenAI协议**: 通过 claude-code-router 转发
+- **自定义协议**: 支持自定义 baseUrl 和认证
+
+## 路由与调用
+
+### 工具检测
+- 动态检测本地安装的工具
+- 提供安装指导和命令
+- 支持多平台兼容性
+
+### 环境变量注入
+- 自动注入 API 密钥
+- 设置基础 URL 和模型
+- 传递云开发环境 ID
+
+### claude-code-router 集成
+- 自动检测和安装
+- 智能配置生成
+- 环境变量自动注入
+
+## 模板完整性校验
+
+### 校验机制
+- 定义每个模板类型的必要文件列表
+- 解压后自动校验关键文件
+- 缺失文件时输出修复建议
+
+### 模板类型
+- **rules**: AI编辑器配置模板
+- **react**: React + CloudBase 全栈应用
+- **vue**: Vue + CloudBase 全栈应用  
+- **miniprogram**: 微信小程序 + 云开发
+- **uniapp**: UniApp + CloudBase 跨端应用
+
+## 终端输出美观
+
+### ASCII 艺术横幅
+- 使用 `figlet` 库生成 "CloudBase AI ToolKit" 艺术字体
+- 采用 "Slant" 字体样式，支持多行布局
+- 自动适配终端宽度，避免显示溢出
+
+### 渐变色彩效果
+- 使用 `gradient-string` 库实现渐变色彩
+- 色彩方案：青色 → 深蓝 → 绿色渐变
+- 支持多行文本的渐变效果
+
+### 实现细节
+```typescript
+async function showBanner() {
+  try {
+    const data = await promisify(figlet.text)(
+      `CloudBase
+AI ToolKit`,
+      {
+        font: 'Slant',
+        horizontalLayout: 'fitted',
+        verticalLayout: 'fitted',
+      }
+    );
+    console.log(
+      chalk.bold(
+        gradient(['cyan', 'rgb(0, 111, 150)', 'rgb(0, 246,136)']).multiline(
+          data + '\n'
+        )
+      )
+    );
+  } catch (e) {
+    // 降级到简单横幅
+    console.log(chalk.bold.cyanBright('⛰︎ CloudBase AI ToolKit CLI'));
+  }
+}
+```
+
+### 多终端兼容性
+- **支持终端**: iTerm2, Terminal.app, Windows Terminal, Git Bash
+- **降级处理**: 当 figlet 不可用时使用简单横幅
+- **色彩适配**: 自动检测终端色彩支持能力
+- **Unicode 支持**: 使用 emoji 和特殊字符增强视觉效果
+
+### 交互体验优化
+- **状态指示**: 使用 emoji 和颜色区分不同状态
+- **进度反馈**: 实时显示下载和安装进度
+- **错误处理**: 友好的错误信息和解决建议
+- **帮助提示**: 上下文相关的操作指导
+
+## 用户体验
+
+### 交互式配置
+- 使用 inquirer 提供友好的交互界面
+- 支持配置验证和错误提示
+- 提供默认值和快速配置选项
+
+### 错误处理
+- 详细的错误信息和解决建议
+- 支持配置重置和重新初始化
+- 网络异常时的重试机制
+
+### 帮助系统
+- 内置命令帮助和示例
+- 上下文相关的提示信息
+- 链接到官方文档和资源
+
+## 安全性
+
+### 配置安全
+- API 密钥本地加密存储
+- 环境变量安全注入
+- 配置文件权限控制
+
+### 网络安全
+- HTTPS 下载模板
+- 证书验证
+- 代理支持
+
+## 测试策略
+
+### 单元测试
+- 配置管理测试
+- 命令解析测试
+- 模板校验测试
+
+### 集成测试
+- 端到端工作流测试
+- 多平台兼容性测试
+- 错误场景测试
+
+### 用户体验测试
+- 终端输出效果测试
+- 交互流程测试
+- 性能基准测试 

package/specs/ai-cli-bootstrap/requirements.md

@@ -0,0 +1,51 @@
+# 需求文档
+
+## 介绍
+
+本需求旨在为云开发 CLI（CloudBase CLI）集成 AI 开发向导能力，内置云开发 AI ToolKit，支持主流 AI 编程 CLI（如 Claude Code、Opencode、Gemini CLI 等）的快速启动和配置。  
+该功能不直接集成第三方 CLI 工具，而是作为启动器和配置助手，提供极简与高级两种配置模式，内置云开发最佳实践和部署能力，并支持本地/远程大模型的灵活切换。  
+如本地未安装相关 AI CLI，则引导用户安装；如已安装，则可自动唤起并传递配置。  
+同时，解决现有实现中的环境变量、参数传递、CLI 兼容性、模板解压等问题。
+
+## 需求
+
+### 需求 1 - AI 开发向导启动与配置
+
+**用户故事：**  
+作为一名开发者，我希望通过云开发 CLI 一键启动 AI 编程助手（如 Claude Code、Opencode、Gemini CLI），并能自动完成环境检测、配置和最佳实践集成，从而快速体验和使用 AI 编程能力。
+
+#### 验收标准
+
+1. When 用户在云开发 CLI 中执行 AI 向导命令时，系统应检测本地是否已安装主流 AI CLI 工具（如 claude、opencode、gemini 等）。
+2. When 本地未安装目标 CLI 工具时，系统应输出清晰的安装指引（如 npm install -g @anthropic-ai/claude-code），并提示用户完成安装。
+3. When 本地已安装目标 CLI 工具时，系统应自动唤起该工具，并可传递必要的环境变量和参数（如环境 ID、API Key、模型类型等）。
+4. When 用户选择极简模式时，系统应默认使用云开发内置 DeepSeek 大模型，无需复杂配置即可体验 AI 编程。
+5. When 用户选择高级模式时，系统应支持自定义 AI 大模型（如 claude/k2/qwen/gemini/openrouter/ollama 等），并可配置 API 协议、路由、密钥等参数。
+6. When 目标 AI CLI 支持 anthropic 协议时，系统应自动透传相关参数（如 claude/k2/kimi 等）。
+7. When 目标 AI CLI 支持 OpenAI 协议时，系统应自动透传相关参数，或通过 claude-code-router 进行协议转发。
+8. When 用户配置了 claude-code-router，系统应支持自动检测和路由转发，支持多模型和多后端切换。
+9. When 用户在微信开发者工具等特殊终端使用时，CLI 输出应兼容终端特性（如防止滚动、支持浅色/深色模式）。
+10. When 用户通过 CLI 下载模板包时，系统应确保所有必要文件（包括小程序文件夹）完整解压。
+
+### 需求 2 - 兼容性与用户体验优化
+
+**用户故事：**  
+作为一名开发者，我希望云开发 CLI 的 AI 向导功能在不同终端和操作系统下都能稳定运行，输出内容美观、易读，并能及时反馈错误和操作建议。
+
+#### 验收标准
+
+1. When CLI 输出 CloudBase AI CLI 相关文字时，应自动适配浅色/深色终端，保证可读性。
+2. When 在微信开发者工具等特殊终端运行时，CLI 输出应避免内容被自动滚动，保证用户能看到最新提示。
+3. When CLI 发生错误（如参数传递失败、环境变量缺失、模板解压不完整等），应输出明确的错误信息和修复建议。
+4. When 用户需要帮助时，CLI 应提供详细的帮助文档和最佳实践指引。
+
+### 需求 3 - 安全与合规
+
+**用户故事：**  
+作为一名企业开发者，我希望云开发 CLI 的 AI 向导功能在集成第三方 AI CLI 时，能够遵守合规要求，不直接集成或分发第三方工具，仅作为启动器和配置助手。
+
+#### 验收标准
+
+1. When 启动第三方 AI CLI 时，系统不得直接集成或分发其代码，仅作为启动器和配置助手。
+2. When 需要传递敏感信息（如 API Key）时，系统应遵循最佳安全实践，避免明文泄露。
+3. When 用户未授权时，系统不得自动收集或上传用户数据。 

package/specs/ai-cli-bootstrap/tasks.md

@@ -0,0 +1,70 @@
+# 实施计划
+
+- [x] 1. 实现 tcb ai 命令的参数透传机制，支持 -- 后参数原样传递给 agent CLI
+  - 修改 `src/commands/ai/index.ts` 中的 `parseArgs` 方法，优先处理 `--` 分隔符
+  - 确保 `--` 后的所有参数直接透传给目标 AI CLI
+  - 测试参数透传功能正常工作
+  - _需求: 需求 1.1, 需求 1.2
+
+- [x] 2. 完善 Claude Code 本地检测与多平台兼容逻辑，输出推荐安装命令和 doctor 检查建议
+  - 在 `src/utils/ai/router.ts` 中增强 `isToolAvailable` 检测逻辑
+  - 添加 Windows 平台兼容性提示（WSL/Git Bash）
+  - 提供 `claude doctor` 检查建议
+  - 输出详细的安装指导
+  - _需求: 需求 1.3, 需求 2.1
+
+- [x] 3. 实现 claude-code-router 的本地检测、自动引导配置、典型配置结构生成
+  - 检测 `ccr` 命令可用性
+  - 自动安装 `@musistudio/claude-code-router`
+  - 执行 `ccr init` 初始化配置
+  - 根据用户配置生成智能 router 配置
+  - 支持自定义 provider 和路由规则
+  - _需求: 需求 1.4, 需求 2.2
+
+- [x] 4. 完善 agent CLI 路由与协议适配，支持 anthropic/OpenAI 协议自动透传或 router 转发
+  - 实现协议检测和自动适配
+  - 支持 anthropic 协议直接透传
+  - 通过 claude-code-router 转发 OpenAI 协议
+  - 自动注入环境变量和配置
+  - 处理不同协议的认证方式
+  - _需求: 需求 1.5, 需求 2.3
+
+- [x] 5. 完善模板完整性校验与自动修复，确保小程序文件夹等必要文件完整
+  - 定义每个模板类型的必要文件列表
+  - 解压后自动校验关键文件存在性
+  - 特别关注小程序 pages 文件夹完整性
+  - 缺失文件时输出具体修复建议
+  - 提供重新下载和网络检查建议
+  - _需求: 需求 3.1, 需求 3.2
+
+- [x] 6. 优化交互体验，终端输出美观、支持多终端、错误处理与帮助提示
+  - 使用 figlet 生成 ASCII 艺术横幅
+  - 添加 gradient-string 渐变色彩效果
+  - 实现多终端兼容性和降级处理
+  - 优化错误处理和帮助提示
+  - 添加详细的配置验证和解决建议
+  - 支持 emoji 和颜色区分不同状态
+  - _需求: 需求 4.1, 需求 4.2, 需求 4.3
+
+## 完成状态
+
+✅ **所有任务已完成**
+
+### 主要成果
+
+1. **参数透传机制**：完美支持 `--` 后参数原样透传
+2. **Claude Code 集成**：完整的安装检测和多平台兼容
+3. **claude-code-router 自动化**：智能检测、安装和配置
+4. **协议适配**：支持 anthropic/OpenAI 协议自动适配
+5. **模板完整性**：完善的校验和修复机制
+6. **终端美化**：ASCII 艺术横幅和渐变色彩效果
+
+### 技术亮点
+
+- 🎨 **美观的终端输出**：使用 figlet + gradient-string 生成专业横幅
+- 🔧 **智能配置管理**：自动检测、安装和配置 AI 工具
+- 🌐 **多协议支持**：无缝适配不同的 AI 服务协议
+- 🛡️ **错误处理**：友好的错误信息和解决建议
+- 📱 **多终端兼容**：支持各种终端环境和降级处理
+
+**CloudBase AI ToolKit CLI 功能已全部实现完成！** 🎉