@cloudbase/cli 2.8.0-beta.4 → 2.8.0-beta.5

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

@@ -0,0 +1,57 @@
+# 技术方案设计
+
+## 架构概述
+
+本方案通过在 CLI 中暴露一个全局的 `cloudbase-mcp` bin 命令，直接调用内置的 `@cloudbase/cloudbase-mcp` 包，并修改模板下载逻辑，使所有 MCP 配置都指向这个全局命令，从而避免用户需要额外安装 MCP 包。
+
+## 技术栈
+
+- Node.js CLI 工具
+- `@cloudbase/cloudbase-mcp` 内置依赖
+- 文件系统操作 (fs-extra)
+- 模板下载和解压
+
+## 技术选型
+
+### 1. Bin 文件创建
+- 在 `bin/` 目录下创建 `cloudbase-mcp.js` 文件
+- 在 `package.json` 的 `bin` 字段中注册 `cloudbase-mcp` 命令
+- 直接调用内置的 `@cloudbase/cloudbase-mcp` 包
+
+### 2. 模板配置生成
+- 修改 `router.ts` 中的模板下载逻辑
+- 根据 IDE 类型生成对应的 MCP 配置文件
+- 所有配置都指向 `cloudbase-mcp` 命令
+
+### 3. IDE 配置映射和格式支持
+- 参考 CloudBase-AI-ToolKit 的 IDE 到文件映射关系
+- 支持 Cursor、VSCode、Claude Code、OpenAI Codex、OpenCode、Aider 等多种 IDE
+- 支持 JSON 和 TOML 两种配置文件格式
+- 实现 TOML 解析和修改功能
+
+## 数据库/接口设计
+
+无需数据库设计，主要涉及文件系统操作和命令行接口。
+
+## 测试策略
+
+1. **单元测试**：测试 bin 文件是否正确调用内置包
+2. **集成测试**：测试模板下载和配置生成功能
+3. **端到端测试**：测试完整的 MCP 配置流程
+
+## 安全性
+
+- 确保 bin 文件有正确的执行权限
+- 验证模板下载源的安全性
+- 防止路径遍历攻击
+
+## 实施计划
+
+```mermaid
+graph TD
+    A[创建 cloudbase-mcp.js bin 文件] --> B[在 package.json 中注册命令]
+    B --> C[修改 router.ts 模板下载逻辑]
+    C --> D[实现 IDE 配置映射]
+    D --> E[测试验证]
+    E --> F[文档更新]
+``` 

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

@@ -0,0 +1,43 @@
+# 需求文档
+
+## 介绍
+
+当前下载的模板中的 MCP 配置使用 `npx npm-global-exec@latest @cloudbase/cloudbase-mcp@latest` 命令，这会导致用户需要安装 MCP，降低了成功率。CLI 已经内置了 `@cloudbase/cloudbase-mcp@latest` 依赖，需要在 CLI 中直接暴露一个额外的 bin 文件指向到这个依赖，然后修改下载模板的 MCP 配置都指向这个全局命令。
+
+## 需求
+
+### 需求 1 - 创建全局 MCP bin 命令
+
+**用户故事：** 作为开发者，我希望 CLI 提供一个全局的 MCP 命令，这样我就不需要额外安装 MCP 包，提高配置成功率。
+
+#### 验收标准
+
+1. When CLI 安装后，the 系统 shall 提供一个全局的 `cloudbase-mcp` 命令
+2. When 执行 `cloudbase-mcp` 命令时，the 系统 shall 直接调用内置的 `@cloudbase/cloudbase-mcp` 包
+3. When 验证 MCP 配置时，the 配置文件中的命令 shall 指向 `cloudbase-mcp` 而不是 `npx npm-global-exec@latest @cloudbase/cloudbase-mcp@latest`
+
+### 需求 2 - 自动修改模板 MCP 配置
+
+**用户故事：** 作为开发者，我希望下载模板后系统自动修改 MCP 配置，将 npx 命令替换为 CLI 提供的全局命令，避免额外的依赖安装。
+
+#### 验收标准
+
+1. When 下载模板完成后，the 系统 shall 自动检测并修改所有 MCP 配置文件
+2. When 发现 `.cursor/mcp.json` 等配置文件时，the 系统 shall 将 `npx npm-global-exec@latest @cloudbase/cloudbase-mcp@latest` 替换为 `cloudbase-mcp`
+3. When 修改完成后，the 系统 shall 验证配置文件的正确性
+4. When 用户使用模板时，the MCP 功能 shall 无需额外安装即可正常工作
+
+### 需求 3 - 支持多种 IDE 配置和格式
+
+**用户故事：** 作为开发者，我希望模板支持多种 IDE 的 MCP 配置，包括不同格式（JSON、TOML）和各种工具。
+
+#### 验收标准
+
+1. When 下载模板时，the 系统 shall 根据 IDE 类型生成对应的配置文件
+2. When 配置 Cursor 时，the 系统 shall 生成 `.cursor/mcp.json` 和 `.cursor/rules/cloudbase-rules.mdc`
+3. When 配置 VSCode 时，the 系统 shall 生成 `.vscode/mcp.json` 和 `.vscode/settings.json`
+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` 文件
+8. When 处理 TOML 格式时，the 系统 shall 正确解析和修改配置 

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

@@ -0,0 +1,54 @@
+# 实施计划
+
+- [x] 1. 创建 cloudbase-mcp bin 文件
+  - 在 `bin/` 目录下创建 `cloudbase-mcp.js` 文件
+  - 实现直接调用内置 `@cloudbase/cloudbase-mcp` 包的逻辑
+  - 确保文件有正确的执行权限
+  - _需求: 需求 1
+
+- [x] 2. 在 package.json 中注册新命令
+  - 在 `bin` 字段中添加 `cloudbase-mcp` 命令映射
+  - 确保命令指向正确的 bin 文件
+  - _需求: 需求 1
+
+- [x] 3. 实现 IDE 配置映射常量
+  - 在 `router.ts` 中添加 IDE 到文件的映射关系常量
+  - 参考 CloudBase-AI-ToolKit 的映射配置
+  - 支持 Cursor、VSCode、Claude Code 等多种 IDE
+  - _需求: 需求 3
+
+- [x] 3.1. 扩展支持更多 IDE 和格式
+  - 添加 OpenAI Codex (.codex/config.toml) 支持
+  - 添加 OpenCode (.opencode.json) 支持
+  - 添加 Aider (mcp.json) 支持
+  - 实现 TOML 格式解析和修改功能
+  - _需求: 需求 3
+
+- [x] 4. 修改模板下载后的处理逻辑
+  - 在 `downloadAndExtractTemplate` 方法中添加 MCP 配置修改逻辑
+  - 实现自动检测 MCP 配置文件的功能
+  - 实现将 npx 命令替换为 cloudbase-mcp 命令的功能
+  - _需求: 需求 2
+
+- [x] 5. 实现 MCP 配置文件修改函数
+  - 创建 `modifyMCPConfigs` 函数
+  - 遍历所有 IDE 配置文件并修改命令
+  - 验证修改后的配置文件正确性
+  - _需求: 需求 2
+
+- [x] 6. 添加配置验证功能
+  - 实现验证 MCP 配置文件格式的功能
+  - 确保修改后的配置仍然有效
+  - 添加错误处理和回滚机制
+  - _需求: 需求 2
+
+- [x] 7. 测试验证
+  - 测试 cloudbase-mcp 命令是否正常工作
+  - 测试模板下载和配置修改功能
+  - 测试不同 IDE 配置文件的生成
+  - _需求: 需求 1, 需求 2, 需求 3
+
+- [x] 8. 文档更新
+  - 更新 README.md 说明新的 cloudbase-mcp 命令
+  - 更新模板下载相关的文档
+  - _需求: 需求 1, 需求 2 

package/types/commands/ai/index.d.ts

@@ -0,0 +1,23 @@
+import { Command } from '../common';
+import { ICommandContext } from '../../types';
+import { Logger } from '../../utils/log';
+export declare class AICommand extends Command {
+    get options(): {
+        cmd: string;
+        options: {
+            flags: string;
+            desc: string;
+        }[];
+        desc: string;
+        requiredEnvId: boolean;
+        withoutAuth: boolean;
+        allowUnknownOption: boolean;
+    };
+    execute(options: any, ctx: ICommandContext, log: Logger): Promise<void | {
+        defaultAgent: string;
+    }>;
+    private resetConfig;
+    private showConfig;
+    private parseArgs;
+    private getSubCommand;
+}

package/types/commands/index.d.ts

@@ -16,3 +16,4 @@ export * from './fun';
 export * from './runf';
 export * from './cloudfunction';
 export * from './cloudrun';
+export * from './ai';

package/types/commands/utils.d.ts

@@ -15,6 +15,12 @@ export declare function fetchAccessToken(params: {
     secretKey: string;
     token?: string;
 }): Promise<any>;
+export declare function rawFetchAccessToken(params: {
+    envId: string;
+    secretId: string;
+    secretKey: string;
+    token?: string;
+}): Promise<any>;
 export declare function upsertCloudbaserc(projectPath: string, inputData: {
     envId?: string;
     [key: string]: any;

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

@@ -0,0 +1,2 @@
+import { Logger } from '../log';
+export declare function showBanner(log: Logger): Promise<void>;

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

@@ -0,0 +1,79 @@
+import { ConfigParser } from '@cloudbase/toolbox';
+import { CLAUDE, QWEN, CODEX, AIDER } from './const';
+import z from 'zod/v3';
+export declare const CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND";
+export declare function isValidAgent(agent: unknown): agent is keyof AIConfig['agents'];
+export interface AIConfig {
+    defaultAgent: string;
+    agents: {
+        claude?: z.infer<(typeof CLAUDE)['configSchema']>;
+        qwen?: z.infer<(typeof QWEN)['configSchema']>;
+        codex?: z.infer<(typeof CODEX)['configSchema']>;
+        aider?: z.infer<(typeof AIDER)['configSchema']>;
+    };
+}
+export interface AgentConfig {
+    enabled: boolean;
+    command: string;
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    maxTokens?: number;
+}
+export declare const TOOLKIT_CONFIGS: {
+    [x: string]: {
+        mcp: string;
+        rules: string;
+        config?: undefined;
+    } | {
+        config: string;
+        rules: string;
+        mcp?: undefined;
+    } | {
+        config: string;
+        mcp?: undefined;
+        rules?: undefined;
+    };
+};
+export declare function createConfigParser(): ConfigParser;
+export declare class AIConfigManager {
+    private envLocalManager;
+    loadConfig(): Promise<AIConfig>;
+    isConfigured(): Promise<boolean>;
+    getAgentConfig(agent: string): Promise<AgentConfig | null>;
+    resetConfig(): Promise<void>;
+    checkToolkitConfig(agent: string): Promise<{
+        hasConfig: boolean;
+        hasMcp: boolean;
+        hasRules: boolean;
+        missingFiles: string[];
+    }>;
+    updateEnvId(envId: string): Promise<void>;
+    updateDefaultAgent(agent: string): Promise<void>;
+    updateClaudeConfig(type: 'custom' | 'cloudbase', config: {
+        baseUrl?: string;
+        apiKey?: string;
+        provider?: string;
+        model?: string;
+        transformer?: string;
+    }): Promise<void>;
+    updateQwenConfig(type: 'custom' | 'cloudbase', config: {
+        baseUrl?: string;
+        apiKey?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<void>;
+    updateCodexConfig(type: 'custom' | 'cloudbase', config: {
+        baseUrl?: string;
+        apiKey?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<void>;
+    updateAiderConfig(type: 'custom' | 'cloudbase', config: {
+        apiKey?: string;
+        baseUrl?: string;
+        model?: string;
+        provider?: string;
+    }): Promise<void>;
+    private updateConfig;
+}