@cloudbase/cli 2.7.7 → 2.8.0-beta.0

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/tcb-ai-config-env-local/design.md

@@ -0,0 +1,125 @@
+# 技术方案设计
+
+## 整体架构
+
+### 核心变更
+- **文件路径**：从 `.env` 改为 `.env.local`
+- **更新策略**：从全覆盖改为按需更新
+- **配置管理**：支持 AI 配置项的精确管理
+
+### 技术栈
+- **语言**：TypeScript
+- **文件操作**：fs-extra
+- **配置解析**：自定义 env 文件解析器
+- **错误处理**：CloudBaseError 统一错误处理
+
+## 核心组件设计
+
+### 1. EnvLocalManager 类
+负责 `.env.local` 文件的读取、解析、更新和写入操作。
+
+```typescript
+export class EnvLocalManager {
+  private envLocalPath: string
+  
+  // 解析 .env.local 文件内容
+  parseEnvFile(content: string): Map<string, EnvLine>
+  
+  // 更新 AI 相关配置
+  updateAIConfig(aiConfig: AIEnvConfig): Promise<void>
+  
+  // 移除 AI 相关配置
+  removeAIConfig(agentName?: string): Promise<void>
+  
+  // 按需写入文件
+  writeEnvFile(envMap: Map<string, EnvLine>): Promise<void>
+}
+```
+
+### 2. 环境变量数据结构
+```typescript
+interface EnvLine {
+  key: string
+  value: string
+  comment?: string
+  isAIConfig: boolean
+  originalLine: string
+}
+
+interface AIEnvConfig {
+  defaultAgent: string
+  agents: {
+    [agentName: string]: {
+      apiKey?: string
+      authToken?: string
+      baseUrl?: string
+      model?: string
+    }
+  }
+}
+```
+
+## 文件处理策略
+
+### 解析策略
+1. **行级解析**：逐行解析，保留注释和空行
+2. **AI 配置识别**：通过 `AI_` 前缀识别 AI 相关配置
+3. **格式保持**：保持原有文件的格式和注释结构
+
+### 更新策略
+1. **精确匹配**：只更新 AI 相关的环境变量
+2. **保留格式**：维持注释、空行和非 AI 配置的原有位置
+3. **智能合并**：新增配置追加到 AI 配置区域
+
+## 配置项映射
+
+### AI 配置变量命名规范
+```
+AI_DEFAULT_AGENT=claude
+AI_CLAUDE_AUTH_TOKEN=sk-ant-xxx
+AI_CLAUDE_BASE_URL=https://api.anthropic.com
+AI_QWEN_API_KEY=sk-xxx
+AI_QWEN_BASE_URL=https://api.openai.com
+AI_QWEN_MODEL=qwen-plus
+```
+
+### 配置区域管理
+- **区域标识**：使用注释标记 AI 配置区域
+- **区域更新**：只在 AI 配置区域内进行修改
+- **区域隔离**：确保不影响其他配置区域
+
+## 错误处理策略
+
+### 文件操作错误
+- 权限不足：提供明确的权限解决方案
+- 文件锁定：重试机制和友好提示
+- 磁盘空间：检查可用空间并提示
+
+### 配置格式错误
+- 解析失败：备份原文件并提供修复建议
+- 无效配置：标记问题行并提供正确格式示例
+- 冲突配置：智能合并或提示用户选择
+
+## 测试策略
+
+### 单元测试
+- EnvLocalManager 各方法的功能测试
+- 边界条件和异常情况测试
+- 文件格式兼容性测试
+
+### 集成测试
+- AISetupWizard 与 EnvLocalManager 集成
+- 多种配置场景的端到端测试
+- 文件操作的并发安全性测试
+
+## 安全性考虑
+
+### 敏感信息保护
+- API 密钥的安全存储
+- 文件权限控制（600）
+- 临时文件的安全清理
+
+### 原子操作
+- 写入操作的原子性保证
+- 失败时的回滚机制
+- 并发写入的锁定机制 

package/specs/tcb-ai-config-env-local/requirements.md

@@ -0,0 +1,39 @@
+# 需求文档
+
+## 介绍
+
+当前 tcb ai 配置保存功能存在问题：配置保存到 `.env` 文件中，且采用全覆盖方式更新，会丢失用户其他环境变量。需要改进为保存到 `.env.local` 文件，并支持按需更新，只更新 AI 相关的配置项，保留其他现有配置。
+
+## 需求
+
+### 需求 1 - 配置文件路径变更
+
+**用户故事：** 作为开发者，我希望 tcb ai 的配置能够保存到 `.env.local` 文件中，这样可以与项目的其他环境变量分离，避免配置冲突。
+
+#### 验收标准
+
+1. When 运行 `tcb ai --setup` 时，系统应当将 AI 配置保存到 `.env.local` 文件而不是 `.env` 文件。
+2. When `.env.local` 文件不存在时，系统应当创建新的 `.env.local` 文件。
+3. When `.env.local` 文件已存在时，系统应当保留现有内容并追加或更新 AI 配置部分。
+
+### 需求 2 - 按需更新机制
+
+**用户故事：** 作为开发者，我希望更新 AI 配置时不会覆盖我的其他环境变量，系统只更新 AI 相关的配置项。
+
+#### 验收标准
+
+1. When 更新 AI 配置时，系统应当只修改以 `AI_` 开头的环境变量。
+2. When `.env.local` 文件中存在非 AI 相关的环境变量时，系统应当保留这些变量不变。
+3. When AI 配置项已存在时，系统应当更新对应的值。
+4. When AI 配置项不存在时，系统应当添加新的配置项。
+
+### 需求 3 - 配置项管理
+
+**用户故事：** 作为开发者，我希望系统能够智能管理 AI 配置项，包括添加、更新和删除过期的配置。
+
+#### 验收标准
+
+1. When 切换默认 AI 工具时，系统应当更新 `AI_DEFAULT_AGENT` 变量。
+2. When 配置新的 AI 工具时，系统应当添加对应的 API_KEY/AUTH_TOKEN、BASE_URL、MODEL 等配置。
+3. When 移除 AI 工具配置时，系统应当能够清理对应的环境变量。
+4. When 配置文件格式错误时，系统应当提供友好的错误提示和修复建议。

package/specs/tcb-ai-config-env-local/tasks.md

@@ -0,0 +1,48 @@
+# 实施计划
+
+- [x] 1. 创建 EnvLocalManager 核心类
+  - 创建 `src/utils/ai/envLocalManager.ts` 文件
+  - 实现环境变量解析和数据结构定义
+  - 实现文件读取和解析方法
+  - _需求: 需求1, 需求2_
+
+- [x] 2. 实现 AI 配置更新逻辑
+  - 实现 `updateAIConfig` 方法，支持按需更新
+  - 实现配置项的添加、修改和删除
+  - 确保只更新 AI 相关的环境变量
+  - _需求: 需求2, 需求3_
+
+- [x] 3. 实现文件写入和格式保持
+  - 实现 `writeEnvFile` 方法，保持原有格式
+  - 确保注释、空行和非AI配置的保留
+  - 实现原子写入操作，确保数据安全性
+  - _需求: 需求2_
+
+- [x] 4. 修改 AISetupWizard 使用新的管理器
+  - 更新 `src/utils/ai/setup.ts` 中的文件路径为 `.env.local`
+  - 替换现有的文件更新逻辑为 EnvLocalManager
+  - 移除简单的覆盖和追加方法
+  - _需求: 需求1, 需求2_
+
+- [x] 5. 更新 .gitignore 配置提醒
+  - 修改 gitignore 提醒逻辑，建议添加 `.env.local`
+  - 保持对 `.env` 的兼容提醒
+  - _需求: 需求1_
+
+- [x] 6. 错误处理和用户体验优化
+  - 实现友好的错误提示和修复建议
+  - 添加文件操作的重试机制
+  - 实现配置验证和格式检查
+  - _需求: 需求3_
+
+- [x] 7. 单元测试和集成测试
+  - 为 EnvLocalManager 编写完整的单元测试
+  - 编写 AISetupWizard 的集成测试
+  - 测试各种边界条件和异常情况
+  - _需求: 所有需求_
+  - **状态：已取消（按用户要求不需要测试）**
+
+- [x] 8. 更新 TOOLKIT_CONFIGS 配置
+  - 检查并更新相关配置引用
+  - 确保整个系统的一致性
+  - _需求: 需求1_ 

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/cloudrun/base.d.ts

@@ -1,6 +1,7 @@
 import { Logger } from '../../decorators';
 import { Command } from '../common';
 export declare function getCloudrunService(envId: string): Promise<import("@cloudbase/manager-node/types/cloudrun").CloudRunService>;
+export declare function getAgentService(envId: string): Promise<import("@cloudbase/manager-node/types/agent").AgentService>;
 export declare class CloudRunInitCommand extends Command {
     get options(): {
         cmd: string;
@@ -136,6 +137,7 @@ export declare class CloudRunDeployCommand extends Command {
         source?: string;
         force?: boolean;
         port?: number;
+        createAgent?: boolean;
     }): Promise<void>;
 }
 export declare class CloudRunRunCommand extends Command {

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>;