@cloudbase/cli 2.8.0-beta.7 → 2.8.0

package/README.md

@@ -5,7 +5,7 @@ CloudBase CLI 是一个开源的命令行界面交互工具，用于帮助用户
 ## 主要功能
 
 - **云开发资源管理**：快速部署项目，管理云函数、数据库、存储等资源
-- **AI 开发助手**：集成多种 AI 工具（Claude、Qwen、Codex、aider 等），提升开发效率
+- **AI 开发助手**：集成多种 AI 工具（Claude、Qwen、Codex、Aider 等），提升开发效率
 - **MCP 协议支持**：内置 `cloudbase-mcp` 命令，支持 Model Context Protocol，无需额外安装
 - **模板下载**：提供多种项目模板，自动配置 IDE 和 MCP 环境
 

package/lib/commands/functions/deploy.js

@@ -35,6 +35,7 @@ const gateway_1 = require("../../gateway");
 const utils_1 = require("../../utils");
 const constant_1 = require("../../constant");
 const decorators_1 = require("../../decorators");
+const function_2 = require("../../function");
 const regionIdMap = {
     'ap-guangzhou': 1,
     'ap-shanghai': 4,
@@ -207,19 +208,31 @@ let FunctionDeploy = class FunctionDeploy extends common_1.Command {
                     message: `存在同名云函数：[${func.name}]，是否覆盖原函数代码与配置`,
                     default: false
                 });
+                const { triggers } = func;
                 if (force) {
-                    loading.start('云函数部署中...');
+                    loading.start('云函数更新部署中...');
                     try {
-                        yield (0, function_1.createFunction)({
+                        yield (0, function_2.updateFunctionCode)({
                             func,
                             envId,
                             codeSecret,
-                            accessPath,
-                            force: true,
-                            functionPath,
                             functionRootPath
                         });
-                        loading.succeed(`[${func.name}] 云函数部署成功！`);
+                        const code_text = '代码';
+                        yield this.waitForFunctionReady(envId, func.name, loading, code_text);
+                        yield (0, function_2.updateFunctionConfig)({
+                            envId,
+                            functionName: func.name,
+                            config: func
+                        });
+                        const config_text = '配置';
+                        yield this.waitForFunctionReady(envId, func.name, loading, config_text);
+                        yield (0, function_2.createFunctionTriggers)({
+                            envId,
+                            functionName: func.name,
+                            triggers
+                        });
+                        loading.succeed(`[${func.name}] 云函数更新成功！`);
                         yield this.printSuccessTips(envId);
                     }
                     catch (e) {
@@ -232,6 +245,36 @@ let FunctionDeploy = class FunctionDeploy extends common_1.Command {
             throw e;
         });
     }
+    waitForFunctionReady(envId, functionName, loading, text, timeoutMinutes = 5) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const scfService = yield (0, function_2.getFunctionService)(envId);
+            const timeoutMs = timeoutMinutes * 60 * 1000;
+            return new Promise((resolve, reject) => {
+                let intervalId = null;
+                const timeoutId = setTimeout(() => {
+                    clearInterval(intervalId);
+                    reject(new error_1.CloudBaseError(`[${functionName}] 等待函数更新超时，已等待 ${timeoutMinutes} 分钟`));
+                }, timeoutMs);
+                intervalId = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        const functionInfo = yield scfService.getFunctionDetail(functionName);
+                        if ((functionInfo === null || functionInfo === void 0 ? void 0 : functionInfo.Status) === 'Active') {
+                            clearTimeout(timeoutId);
+                            clearInterval(intervalId);
+                            loading.succeed(`[${functionName}] 云函数${text}已更新！`);
+                            resolve();
+                        }
+                        else {
+                            loading.text = `正在更新[${functionName}] 云函数${text}... 当前状态: ${(functionInfo === null || functionInfo === void 0 ? void 0 : functionInfo.Status) || '未知'}`;
+                        }
+                    }
+                    catch (error) {
+                        loading.text = `获取[${functionName}] 云函数状态失败，重试中...`;
+                    }
+                }), 2000);
+            });
+        });
+    }
     printSuccessTips(envId, log) {
         return __awaiter(this, void 0, void 0, function* () {
             let url = `https://console.cloud.tencent.com/tcb/scf?envId=${envId}`;

package/lib/function/layer/attach.js

@@ -54,11 +54,15 @@ function unAttachLayer(options) {
             throw new error_1.CloudBaseError('层不存在');
         }
         Layers.splice(index, 1);
-        return scfService.request('UpdateFunctionConfiguration', {
-            Layers,
+        const apiParams = {
             Namespace: envId,
-            FunctionName: functionName
-        });
+            FunctionName: functionName,
+            Layers: Layers.length > 0 ? Layers : [{
+                    LayerName: '',
+                    LayerVersion: 0
+                }]
+        };
+        return scfService.request('UpdateFunctionConfiguration', apiParams);
     });
 }
 exports.unAttachLayer = unAttachLayer;

package/lib/utils/ai/banner.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.showBanner = void 0;
 const chalk_1 = __importDefault(require("chalk"));
+const output_1 = require("../output");
 function showBanner(log) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
@@ -74,6 +75,8 @@ AI ToolKit`, {
                 log.log('    🎯 无需运维，极速上线你的创意 💫');
             }
             log.log('');
+            log.log(`beta 能力，如遇问题可创建 issue： ${(0, output_1.genClickableLink)('https://cnb.cool/tencent/cloud/cloudbase/community/-/issues')}`);
+            log.log('');
         }
         catch (e) {
             log.log(chalk_1.default.bold.cyanBright('⛰︎'), chalk_1.default.bold.hex('#FFFFFF')(' CloudBase AI ToolKit CLI'));

package/lib/utils/ai/const.js

@@ -3,13 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDefaultModelByBaseUrl = exports.BASE_URL_MODEL_MAPPING = exports.getAgentConfigValidator = exports.getDefaultConfig = exports.CLOUDBASE_PROVIDERS = exports.AGENTS = exports.NONE = exports.AIDER = exports.CODEX = exports.QWEN = exports.CLAUDE = exports.DEFAULT_CONFIG = exports.CLOUDBASE_MCP_CONFIG_PATH = exports.CLAUDE_CODE_ROUTER_CONFIG_PATH = exports.ENV_LOCAL_PATH = exports.CONFIG_PATH = void 0;
+exports.getDefaultModelByBaseUrl = exports.BASE_URL_MODEL_MAPPING = exports.getAgentConfigValidator = exports.getDefaultConfig = exports.CLOUDBASE_PROVIDERS = exports.AGENTS = exports.NONE = exports.AIDER = exports.CODEX = exports.QWEN = exports.CLAUDE = exports.DEFAULT_CONFIG = exports.CLOUDBASE_MCP_CONFIG_PATH = exports.CLAUDE_CODE_ROUTER_LOG_PATH = exports.CLAUDE_CODE_ROUTER_CONFIG_PATH = exports.ENV_LOCAL_PATH = exports.CONFIG_PATH = void 0;
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const v3_1 = __importDefault(require("zod/v3"));
 exports.CONFIG_PATH = path_1.default.join(process.cwd(), 'cloudbaserc.json');
 exports.ENV_LOCAL_PATH = path_1.default.join(process.cwd(), '.env.local');
 exports.CLAUDE_CODE_ROUTER_CONFIG_PATH = path_1.default.join(os_1.default.homedir(), '.claude-code-router', 'config.json');
+exports.CLAUDE_CODE_ROUTER_LOG_PATH = path_1.default.join(os_1.default.homedir(), '.claude-code-router', 'claude-code-router.log');
 exports.CLOUDBASE_MCP_CONFIG_PATH = path_1.default.join(os_1.default.homedir(), '.cloudbase-env-id');
 exports.DEFAULT_CONFIG = `{
   "envId": "{{env.ENV_ID}}"
@@ -105,18 +106,18 @@ exports.NONE = {
 };
 exports.AGENTS = [exports.CLAUDE, exports.QWEN, exports.CODEX, exports.AIDER, exports.NONE];
 exports.CLOUDBASE_PROVIDERS = [
+    {
+        name: 'Kimi',
+        value: 'kimi-exp',
+        models: ['kimi-k2-instruct-local'],
+        transformer: undefined
+    },
     {
         name: 'DeepSeek',
         value: 'deepseek',
         models: ['deepseek-v3'],
         transformer: 'deepseek'
     },
-    {
-        name: 'Kimi',
-        value: 'kimi',
-        models: ['Kimi-K2-Instruct-Online-128K'],
-        transformer: undefined
-    },
     {
         name: '自定义',
         value: 'custom',

package/lib/utils/ai/router.js

@@ -359,38 +359,6 @@ class AICommandRouter {
             yield this.modifyMCPConfigs(extractDir, log);
         });
     }
-    validateTemplateIntegrity(templateType, extractDir, log) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const fs = yield Promise.resolve().then(() => __importStar(require('fs-extra')));
-            const path = yield Promise.resolve().then(() => __importStar(require('path')));
-            const requiredFiles = {
-                rules: ['.mcp.json', 'CLAUDE.md'],
-                react: ['package.json', 'src/', 'public/', 'cloudbaserc.json'],
-                vue: ['package.json', 'src/', 'public/', 'cloudbaserc.json'],
-                miniprogram: ['app.js', 'app.json', 'pages/', 'cloudbaserc.json'],
-                uniapp: ['pages.json', 'manifest.json', 'pages/', 'cloudbaserc.json']
-            };
-            const files = requiredFiles[templateType] || [];
-            const missingFiles = [];
-            for (const file of files) {
-                const filePath = path.join(extractDir, file);
-                if (!(yield fs.pathExists(filePath))) {
-                    missingFiles.push(file);
-                }
-            }
-            if (missingFiles.length > 0) {
-                log.warn(`⚠️  模板解压不完整，缺失文件: ${missingFiles.join(', ')}`);
-                log.info('💡 建议重新下载模板或检查网络连接');
-                if (templateType === 'miniprogram' && missingFiles.some((f) => f.includes('pages/'))) {
-                    log.warn('⚠️  小程序 pages 文件夹缺失，可能影响项目正常运行');
-                    log.info('💡 请重新运行 tcb ai 并选择下载 miniprogram 模板');
-                }
-            }
-            else {
-                log.info('✅ 模板完整性校验通过，所有必要文件已解压');
-            }
-        });
-    }
     getInstallCommand(agent) {
         switch (agent) {
             case 'claude':
@@ -454,6 +422,9 @@ class AICommandRouter {
                             log.info('💡 可能是参数错误或配置问题');
                             log.info('🔧 请检查 API 密钥、模型名称等配置是否正确');
                         }
+                        if (command === 'ccr') {
+                            log.info(`🔧 请前往 ${const_1.CLAUDE_CODE_ROUTER_LOG_PATH} 查看日志`);
+                        }
                         reject(new Error(errorMsg));
                     }
                 });
@@ -597,7 +568,7 @@ class AICommandRouter {
                 while (current < max) {
                     current++;
                     if (current > max) {
-                        throw new Error('ccr 重启完成失败');
+                        throw new Error(`ccr 重启完成失败，可前往 ${const_1.CLAUDE_CODE_ROUTER_LOG_PATH} 查看日志`);
                     }
                     log.info(`${current}/${max}等待 ccr 重启完成...`);
                     const isRunning = yield this.isClaudeCodeRouterRunning();
@@ -708,7 +679,8 @@ class AICommandRouter {
                     config.Router === null) {
                     config.Router = {};
                 }
-                config.Router.default = 'cloudbase,deepseek-v3';
+                config.Router.default = `cloudbase,${model}`;
+                config.Log = true;
                 yield fs.writeJson(const_1.CLAUDE_CODE_ROUTER_CONFIG_PATH, config, { spaces: 2 });
                 log.debug('✅ claude-code-router 配置完成');
             }

package/lib/utils/ai/setup.js

@@ -124,7 +124,8 @@ class AISetupWizard {
                         {
                             type: 'confirm',
                             name: 'shouldUpdateEnvId',
-                            message: `当前使用的 envId 为 ${configEnvId}，是否需要更新？`
+                            message: `当前使用的 envId 为 ${configEnvId}，是否需要更新？`,
+                            default: false
                         }
                     ]);
                     if (shouldUpdateEnvId) {
@@ -493,7 +494,7 @@ class AISetupWizard {
                     name: 'selectedProvider',
                     message: '选择大模型供应商:',
                     choices: const_1.CLOUDBASE_PROVIDERS.map(p => ({ name: p.name, value: p.value })),
-                    default: 'deepseek'
+                    default: 'kimi-exp'
                 }
             ]);
             if (selectedProvider === 'custom') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudbase/cli",
-    "version": "2.8.0-beta.7",
+    "version": "2.8.0",
     "description": "cli tool for cloudbase",
     "main": "lib/index.js",
     "scripts": {
@@ -39,7 +39,7 @@
         "@cloudbase/iac-core": "0.0.3-alpha.11",
         "@cloudbase/lowcode-cli": "^0.22.2",
         "@cloudbase/manager-node": "4.3.3",
-        "@cloudbase/toolbox": "^0.7.5",
+        "@cloudbase/toolbox": "^0.7.7",
         "@dotenvx/dotenvx": "^1.48.3",
         "address": "^1.1.2",
         "camelcase-keys": "^7.0.2",

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

@@ -0,0 +1,196 @@
+# Qwen Code 使用指南
+
+## 简介
+
+Qwen Code 是一个基于 Qwen3-Coder 模型的命令行 AI 工作流工具，专门为代码理解和编辑优化。
+
+## 安装
+
+```bash
+npm install -g @qwen-code/qwen-code
+```
+
+## 配置
+
+### 环境变量
+
+在 `.env` 文件中配置以下环境变量：
+
+```bash
+# Qwen API 配置
+OPENAI_API_KEY=your_qwen_api_key_here
+OPENAI_BASE_URL=https://dashscope.aliyuncs.com
+OPENAI_MODEL=qwen-turbo
+```
+
+### 获取 API Key
+
+1. 访问 [阿里云 DashScope](https://dashscope.aliyun.com/)
+2. 注册并登录账户
+3. 创建 API Key
+4. 将 API Key 配置到环境变量中
+
+## 使用方法
+
+### 基本命令
+
+```bash
+# 启动 Qwen Code
+qwen
+
+# 指定项目目录
+cd your-project/
+qwen
+```
+
+### 常用任务
+
+#### 代码理解
+
+```
+> 描述这个系统的主要架构组件
+> 这个模块的数据流是如何工作的？
+> 有哪些安全机制？
+```
+
+#### 代码重构
+
+```
+> 重构这个函数以提高可读性和性能
+> 帮助我重构这个类以遵循更好的设计模式
+> 添加适当的错误处理和日志记录
+```
+
+#### 文档和测试
+
+```
+> 为这个函数生成全面的 JSDoc 注释
+> 为这个组件编写单元测试
+> 创建 API 文档
+```
+
+#### 工作流自动化
+
+```
+> 分析过去 7 天的 git 提交，按功能和团队成员分组
+> 将此目录中的所有图像转换为 PNG 格式
+```
+
+## 与 CloudBase 集成
+
+### 云开发项目
+
+Qwen Code 可以与 CloudBase 项目完美集成：
+
+```bash
+# 在 CloudBase 项目中使用
+cd my-cloudbase-project/
+qwen
+
+# 询问云开发相关问题
+> 如何优化这个云函数的性能？
+> 这个数据库集合的权限配置是否正确？
+> 如何添加新的云函数触发器？
+```
+
+### 最佳实践
+
+1. **项目结构分析**：让 Qwen Code 理解你的 CloudBase 项目结构
+2. **代码审查**：使用 AI 进行代码质量检查
+3. **文档生成**：自动生成 API 文档和部署说明
+4. **问题诊断**：快速定位和解决代码问题
+
+## 高级功能
+
+### 代码编辑
+
+Qwen Code 支持直接编辑代码文件：
+
+```
+> 优化这个云函数的错误处理
+> 添加 TypeScript 类型定义
+> 重构数据库查询以提高性能
+```
+
+### 工作流自动化
+
+```
+> 创建部署脚本
+> 生成测试用例
+> 设置 CI/CD 配置
+```
+
+## 故障排除
+
+### 常见问题
+
+1. **API Key 错误**
+   - 检查 API Key 是否正确
+   - 确认账户余额充足
+
+2. **模型不可用**
+   - 确认模型名称正确
+   - 检查 API 端点配置
+
+3. **权限问题**
+   - 确认 API Key 有足够权限
+   - 检查网络连接
+
+### 调试模式
+
+```bash
+# 启用详细日志
+DEBUG=* qwen
+```
+
+## 性能优化
+
+### 上下文管理
+
+- 使用 `.qwenignore` 文件排除不必要的文件
+- 合理设置上下文窗口大小
+- 定期清理缓存
+
+### 模型选择
+
+- `qwen-turbo`: 快速响应，适合简单任务
+- `qwen-plus`: 平衡性能和准确性
+- `qwen-max`: 最高准确性，适合复杂任务
+
+## 示例项目
+
+### 云函数优化
+
+```bash
+cd cloudfunctions/
+qwen
+
+> 分析这个云函数的性能瓶颈
+> 添加适当的日志记录
+> 优化数据库查询
+```
+
+### 前端应用
+
+```bash
+cd miniprogram/
+qwen
+
+> 检查小程序代码规范
+> 优化页面加载性能
+> 添加错误处理
+```
+
+## 相关资源
+
+- [Qwen Code GitHub](https://github.com/QwenLM/qwen-code)
+- [阿里云 DashScope](https://dashscope.aliyun.com/)
+- [CloudBase 文档](https://cloud.tencent.com/document/product/876)
+- [Qwen 模型介绍](https://qwen.readthedocs.io/)
+
+## 更新日志
+
+### v1.0.0
+- 初始版本发布
+- 支持基本的代码理解和编辑功能
+- 集成 CloudBase 项目支持 

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 功能已全部实现完成！** 🎉 

package/specs/ai-cli-bootstrap/technical-docs.md

@@ -0,0 +1,421 @@
+# AI 开发套件
+
+AI 开发套件是云开发为用户提供的 AI 辅助开发能力，用户可以通过云开发提供的 CLI 工具快速启动和配置主流 AI 编程工具，如 Claude Code、OpenAI Codex、Gemini CLI 等。AI 开发套件内置云开发全栈能力，支持生成、部署和托管全栈 Web 应用与小程序、数据库和后端服务。
+
+## 命令总览
+
+```bash
+tcb ai [options] -- [agent-args]
+```
+
+## 路径说明
+
+* `options` 为 AI 开发套件的配置选项，如 `-a claude`、`-e my-env` 等。
+* `agent-args` 为目标 AI CLI 工具的原生参数，通过 `--` 分隔符透传。
+
+⚠️ 注意事项
+
+* `--` 分隔符后的所有参数将原样传递给目标 AI CLI 工具，请确保参数格式正确。
+* 首次使用需要运行 `tcb ai --setup` 进行配置。
+* 确保已安装目标 AI CLI 工具，如 Claude Code、OpenAI CLI 等。
+
+## 快速开始
+
+### 1. 配置 AI 开发套件
+
+首次使用需要配置 AI 开发套件：
+
+```bash
+# 启动配置向导
+tcb ai --setup
+```
+
+配置向导将引导您：
+- 选择默认的 AI 工具（Claude Code、OpenAI Codex、Gemini CLI）
+- 配置 API 密钥和基础 URL
+- 设置云开发环境 ID
+- 选择模型和协议类型
+
+### 2. 启动 AI 工具
+
+配置完成后，可以直接启动 AI 工具：
+
+```bash
+# 使用默认配置启动 Claude Code
+tcb ai -a claude -- --continue
+
+# 指定环境 ID 启动
+tcb ai -a claude -e my-env -- --model=claude-3.5-sonnet
+
+# 查看帮助信息
+tcb ai -a claude -- --help
+```
+
+## 核心功能
+
+### 启动 AI 工具
+
+您可以使用下面的命令启动配置好的 AI 工具：
+
+```bash
+tcb ai -a <agent> [options] -- [agent-args]
+```
+
+**参数说明：**
+- `-a, --agent <name>`: 指定 AI 工具名称（claude/codex/gemini）
+- `-e, --envId <id>`: 指定云开发环境 ID
+- `--`: 参数分隔符，后面的参数将透传给 AI 工具
+
+**使用示例：**
+```bash
+# 启动 Claude Code 并继续上次会话
+tcb ai -a claude -- --continue
+
+# 启动 OpenAI Codex 并指定模型
+tcb ai -a codex -- --model=gpt-4
+
+# 启动 Gemini CLI 并设置最大 token
+tcb ai -a gemini -- --max-tokens=4096
+```
+
+### 配置管理
+
+#### 查看当前配置
+
+```bash
+tcb ai --config
+```
+
+显示当前配置信息，包括：
+- 默认 AI 工具
+- API 密钥状态
+- 环境 ID 配置
+- 模型和协议设置
+
+#### 重置配置
+
+```bash
+tcb ai --reset
+```
+
+清除所有配置信息，恢复到初始状态。
+
+#### 交互式配置
+
+```bash
+tcb ai --setup
+```
+
+启动交互式配置向导，引导您完成：
+- AI 工具选择和配置
+- API 密钥设置
+- 云开发环境绑定
+- 协议和模型选择
+
+## 支持的 AI 工具
+
+### Claude Code
+
+Claude Code 是 Anthropic 推出的 AI 编程助手，支持自然语言编程和代码生成。
+
+**安装命令：**
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+**配置要求：**
+- API 密钥：`ANTHROPIC_API_KEY`
+- 基础 URL：`https://api.anthropic.com`
+- 支持模型：claude-3.5-sonnet, claude-3-opus 等
+
+**使用示例：**
+```bash
+# 启动 Claude Code
+tcb ai -a claude -- --continue
+
+# 指定模型和参数
+tcb ai -a claude -- --model=claude-3.5-sonnet --max-tokens=4096
+```
+
+### OpenAI Codex
+
+OpenAI Codex 是 OpenAI 的代码生成 AI，基于 GPT 模型优化。
+
+**安装命令：**
+```bash
+npm install -g openai
+```
+
+**配置要求：**
+- API 密钥：`OPENAI_API_KEY`
+- 基础 URL：`https://api.openai.com`
+- 支持模型：gpt-4, gpt-3.5-turbo 等
+
+**使用示例：**
+```bash
+# 启动 OpenAI Codex
+tcb ai -a codex -- --model=gpt-4
+
+# 设置温度和最大 token
+tcb ai -a codex -- --temperature=0.7 --max-tokens=2048
+```
+
+### Gemini CLI
+
+Gemini CLI 是 Google 的 AI 编程工具，基于 Gemini 模型。
+
+**安装命令：**
+```bash
+npm install -g @google/generative-ai
+```
+
+**配置要求：**
+- API 密钥：`GOOGLE_API_KEY`
+- 基础 URL：`https://generativelanguage.googleapis.com`
+- 支持模型：gemini-2.0-flash, gemini-2.0-pro 等
+
+**使用示例：**
+```bash
+# 启动 Gemini CLI
+tcb ai -a gemini -- --model=gemini-2.0-pro
+
+# 设置安全过滤
+tcb ai -a gemini -- --safety-level=BLOCK_MEDIUM_AND_ABOVE
+```
+
+## 协议适配
+
+### Anthropic 协议
+
+支持 Anthropic 协议的 AI 工具可以直接透传：
+
+```bash
+# Claude Code（原生支持）
+tcb ai -a claude -- --continue
+
+# Kimi（支持 Anthropic 协议）
+tcb ai -a kimi -- --model=claude-3.5-sonnet
+
+# K2（支持 Anthropic 协议）
+tcb ai -a k2 -- --max-tokens=4096
+```
+
+### OpenAI 协议
+
+支持 OpenAI 协议的 AI 工具通过 claude-code-router 转发：
+
+```bash
+# 自动检测并安装 claude-code-router
+tcb ai -a openai -- --model=gpt-4
+
+# 自定义 OpenAI 兼容服务
+tcb ai -a custom -- --base-url=https://api.example.com
+```
+
+## 云开发集成
+
+### 环境变量注入
+
+AI 开发套件会自动注入云开发相关环境变量：
+
+```bash
+# 自动注入环境 ID
+tcb ai -a claude -e my-env -- --continue
+
+# 环境变量示例
+CLOUDBASE_ENV_ID=my-env
+CLOUDBASE_REGION=ap-shanghai
+```
+
+### 模板下载
+
+支持下载云开发项目模板：
+
+```bash
+# 下载 React + CloudBase 模板
+tcb ai --template react
+
+# 下载小程序模板
+tcb ai --template miniprogram
+
+# 下载 Vue + CloudBase 模板
+tcb ai --template vue
+```
+
+**支持的模板类型：**
+- `rules`: AI 编辑器配置模板
+- `react`: React + CloudBase 全栈应用
+- `vue`: Vue + CloudBase 全栈应用
+- `miniprogram`: 微信小程序 + 云开发
+- `uniapp`: UniApp + CloudBase 跨端应用
+
+### 自动部署
+
+AI 工具生成的代码可以直接部署到云开发：
+
+```bash
+# 生成并部署 React 应用
+tcb ai -a claude -e my-env -- --prompt="创建一个 React 购物车应用"
+
+# 部署到云函数
+tcb ai -a claude -e my-env -- --prompt="创建一个用户注册云函数"
+```
+
+## 高级配置
+
+### 自定义 Provider
+
+支持配置自定义 AI 服务提供商：
+
+```json
+{
+  "defaultAgent": "custom",
+  "agents": {
+    "custom": {
+      "command": "claude",
+      "apiKey": "sk-xxx",
+      "baseUrl": "https://api.custom-ai.com",
+      "model": "custom-model"
+    }
+  }
+}
+```
+
+### 多环境支持
+
+支持配置多个云开发环境：
+
+```bash
+# 开发环境
+tcb ai -a claude -e dev-env -- --continue
+
+# 生产环境
+tcb ai -a claude -e prod-env -- --continue
+```
+
+### 代理配置
+
+支持通过代理访问 AI 服务：
+
+```bash
+# 设置代理
+export HTTP_PROXY=http://127.0.0.1:7890
+export HTTPS_PROXY=http://127.0.0.1:7890
+
+# 启动 AI 工具
+tcb ai -a claude -- --continue
+```
+
+## 故障排除
+
+### 常见问题
+
+#### 1. AI 工具未安装
+
+**错误信息：** `⚠️ claude 工具未安装`
+
+**解决方案：**
+```bash
+# 安装 Claude Code
+npm install -g @anthropic-ai/claude-code
+
+# 检查安装
+claude doctor
+```
+
+#### 2. API 密钥无效
+
+**错误信息：** `❌ API 密钥无效`
+
+**解决方案：**
+```bash
+# 重新配置
+tcb ai --setup
+
+# 检查 API 密钥格式
+# Claude: sk-ant-api03-xxx
+# OpenAI: sk-xxx
+# Google: AIzaSyCxxx
+```
+
+#### 3. 网络连接问题
+
+**错误信息：** `❌ 网络连接失败`
+
+**解决方案：**
+```bash
+# 检查网络连接
+ping api.anthropic.com
+
+# 配置代理
+export HTTP_PROXY=http://127.0.0.1:7890
+
+# 使用国内镜像（如果支持）
+tcb ai -a claude -- --base-url=https://api.anthropic.cn
+```
+
+#### 4. 模板下载失败
+
+**错误信息：** `❌ 模板下载失败`
+
+**解决方案：**
+```bash
+# 检查网络连接
+curl -I https://static.cloudbase.net
+
+# 重新下载
+tcb ai --template react --force
+
+# 手动下载模板
+wget https://static.cloudbase.net/cloudbase-examples/web-cloudbase-react-template.zip
+```
+
+### 调试模式
+
+启用调试模式获取详细信息：
+
+```bash
+# 启用调试
+DEBUG=* tcb ai -a claude -- --continue
+
+# 查看详细日志
+tcb ai -a claude -- --verbose --continue
+```
+
+## 最佳实践
+
+### 1. 配置管理
+
+- 使用 `tcb ai --setup` 进行初始配置
+- 定期更新 API 密钥
+- 为不同项目使用不同的环境 ID
+
+### 2. 安全考虑
+
+- 不要在代码中硬编码 API 密钥
+- 使用环境变量存储敏感信息
+- 定期轮换 API 密钥
+
+### 3. 性能优化
+
+- 选择合适的模型和参数
+- 使用 `--continue` 保持会话连续性
+- 合理设置 `max-tokens` 参数
+
+### 4. 云开发集成
+
+- 充分利用云开发的全栈能力
+- 使用模板快速搭建项目
+- 结合云函数和数据库构建完整应用
+
+## 相关资源
+
+- [CloudBase CLI 官方文档](https://docs.cloudbase.net/cli-v1/)
+- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)
+- [OpenAI API 文档](https://platform.openai.com/docs)
+- [Google AI Studio](https://aistudio.google.com/)
+- [云开发社区](https://cloudbase.net/community)
+
+---
+
+上一页[云存储](./storage) 下一页[静态网站托管](./hosting) 

package/specs/mcp-global-bin/design.md

@@ -25,7 +25,7 @@
 
 ### 3. IDE 配置映射和格式支持
 - 参考 CloudBase-AI-ToolKit 的 IDE 到文件映射关系
-- 支持 Cursor、VSCode、Claude Code、OpenAI Codex、OpenCode、aider 等多种 IDE
+- 支持 Cursor、VSCode、Claude Code、OpenAI Codex、OpenCode、Aider 等多种 IDE
 - 支持 JSON 和 TOML 两种配置文件格式
 - 实现 TOML 解析和修改功能
 

package/specs/mcp-global-bin/requirements.md

@@ -39,5 +39,5 @@
 4. When 配置 Claude Code 时，the 系统 shall 生成 `CLAUDE.md` 和 `.mcp.json`
 5. When 配置 OpenAI Codex 时，the 系统 shall 处理 `.codex/config.toml` 文件
 6. When 配置 OpenCode 时，the 系统 shall 处理 `.opencode.json` 文件
-7. When 配置 aider 时，the 系统 shall 处理 `mcp.json` 文件
+7. When 配置 Aider 时，the 系统 shall 处理 `mcp.json` 文件
 8. When 处理 TOML 格式时，the 系统 shall 正确解析和修改配置 

package/specs/mcp-global-bin/tasks.md

@@ -20,7 +20,7 @@
 - [x] 3.1. 扩展支持更多 IDE 和格式
   - 添加 OpenAI Codex (.codex/config.toml) 支持
   - 添加 OpenCode (.opencode.json) 支持
-  - 添加 aider (mcp.json) 支持
+  - 添加 Aider (mcp.json) 支持
   - 实现 TOML 格式解析和修改功能
   - _需求: 需求 3
 

package/types/commands/functions/deploy.d.ts

@@ -16,6 +16,7 @@ export declare class FunctionDeploy extends Command {
     execute(ctx: any, params: any, log: Logger): Promise<void>;
     deployAllFunction(options: any): Promise<void>;
     handleDeployFail(e: CloudBaseError, options: ICreateFunctionOptions): Promise<void>;
+    waitForFunctionReady(envId: string, functionName: string, loading: any, text: string, timeoutMinutes?: number): Promise<void>;
     printSuccessTips(envId: string, log?: Logger): Promise<void>;
     genApiGateway(envId: string, name: string): Promise<void>;
 }

package/types/utils/ai/const.d.ts

@@ -2,6 +2,7 @@ import z from 'zod/v3';
 export declare const CONFIG_PATH: string;
 export declare const ENV_LOCAL_PATH: string;
 export declare const CLAUDE_CODE_ROUTER_CONFIG_PATH: string;
+export declare const CLAUDE_CODE_ROUTER_LOG_PATH: string;
 export declare const CLOUDBASE_MCP_CONFIG_PATH: string;
 export declare const DEFAULT_CONFIG = "{\n  \"envId\": \"{{env.ENV_ID}}\"\n}";
 export declare const CLAUDE: {
@@ -299,15 +300,15 @@ export declare const AGENTS: readonly [{
     value: string;
 }];
 export declare const CLOUDBASE_PROVIDERS: readonly [{
+    readonly name: "Kimi";
+    readonly value: "kimi-exp";
+    readonly models: readonly ["kimi-k2-instruct-local"];
+    readonly transformer: any;
+}, {
     readonly name: "DeepSeek";
     readonly value: "deepseek";
     readonly models: readonly ["deepseek-v3"];
     readonly transformer: "deepseek";
-}, {
-    readonly name: "Kimi";
-    readonly value: "kimi";
-    readonly models: readonly ["Kimi-K2-Instruct-Online-128K"];
-    readonly transformer: any;
 }, {
     readonly name: "自定义";
     readonly value: "custom";

package/types/utils/ai/router.d.ts

@@ -13,7 +13,6 @@ export declare class AICommandRouter {
     private promptForTemplateDownload;
     private downloadTemplate;
     private downloadAndExtractTemplate;
-    private validateTemplateIntegrity;
     private getInstallCommand;
     private shouldCheckOverwrite;
     private executeCommand;