@cloudbase/cli 2.10.0 → 2.11.0-beta.0

package/specs/ag-command/usage-guide.md

@@ -0,0 +1,420 @@
+# AG 命令使用指南
+
+## 概述
+
+`tcb ag` 命令用于管理基于 Web 云函数的 Serverless 服务类型 Agent。本指南将详细介绍如何使用各个子命令。
+
+## 快速开始
+
+### 1. 假设当前工作空间目录为 workspace，此处创建新的 Agent 项目
+
+```bash
+# 交互式创建 Agent 项目（推荐）
+tcb ag create my-agent
+
+# 指定参数创建
+tcb ag create my-agent --lang node --framework default --template react
+```
+
+### 2. 本地开发和调试
+
+```bash
+# 进入工作空间目录
+cd workspace
+
+# 本地运行 Agent 服务
+tcb ag run my-agent
+
+# 同时启动 Agent 服务和前端项目
+tcb ag run my-agent --web
+
+# 启动调试面板
+tcb ag run my-agent --open-debug-panel
+```
+
+### 3. 部署到云端
+
+```bash
+# 部署到 Web 函数（默认）
+tcb ag deploy my-agent
+
+# 部署到云托管
+tcb ag deploy my-agent --deployMode cloudrun
+```
+
+## 命令详解
+
+### ag create - 初始化 Agent 项目
+
+创建新的 Agent 项目结构，支持交互式选择和命令行参数。
+
+**语法：**
+```bash
+tcb ag create <agentName> [options]
+```
+
+**参数：**
+- `agentName`: Agent 名称，用作项目目录名
+
+**选项：**
+- `-e, --envId <envId>`: 环境 ID
+- `--template <template>`: 前端模板 (react)
+- `--framework <framework>`: 后端 Agent 框架 (default)
+- `--lang <lang>`: 后端开发语言 (node, python)
+- `--name <name>`: Agent 显示名称
+
+**交互式创建（推荐）：**
+```bash
+# 启动交互式向导，逐步选择配置
+tcb ag create my-agent
+```
+
+**命令行参数创建：**
+```bash
+# Node.js + 默认框架
+tcb ag create my-agent --lang node --framework default
+
+# Python + 默认框架 + React 前端
+tcb ag create my-agent --lang python --framework default --template react
+
+# 指定环境和名称
+tcb ag create my-agent -e dev-xxxx --name "智能聊天机器人"
+```
+
+**支持的技术栈：**
+
+**后端语言：**
+- `node`: JavaScript/TypeScript
+- `python`: Python
+
+**后端框架：**
+- `default`: 多框架集合模板
+
+**前端模板：**
+- `react`: React 现代化前端框架
+
+### ag deploy - 部署 Agent
+
+将 Agent 部署到云端。
+
+**语法：**
+```bash
+tcb ag deploy [agentName] [options]
+```
+
+**参数：**
+- `agentName`: Agent 名称（可选，如果不指定会提示选择）
+
+**选项：**
+- `-e, --envId <envId>`: 环境 ID
+- `--deployMode <deployMode>`: 部署模式（webFn: Web 函数，cloudrun: 云托管，默认: webFn）
+- `--force`: 强制部署，跳过确认提示
+- `--source <source>`: 指定要部署的代码目录路径
+
+**示例：**
+```bash
+# 基本部署
+tcb ag deploy my-agent
+
+# 部署到云托管
+tcb ag deploy my-agent --deployMode cloudrun
+
+# 强制部署
+tcb ag deploy my-agent --force
+
+# 指定源代码目录
+tcb ag deploy my-agent --source ./my-agent-code
+
+# 不指定 Agent 名称，交互式选择
+tcb ag deploy
+```
+
+### ag run - 本地运行 Agent
+
+在本地启动 Agent 调试服务，支持 Node.js 和 Python 项目。
+
+**语法：**
+```bash
+tcb ag run <agentName> [options]
+```
+
+**参数：**
+- `agentName`: Agent 名称
+
+**选项：**
+- `-e, --envId <envId>`: 环境 ID
+- `--extendedContext <extendedContext>`: 扩展上下文 JSON 字符串
+- `--port <port>`: 监听端口（默认: 3000）
+- `--dry-run`: 只验证代码，不启动服务
+- `--open-debug-panel`: 是否打开调试面板（默认: false）
+- `--entryPath <entryPath>`: 指定 Agent 服务启动的入口文件路径
+- `--web`: 同时启动前端项目（如果存在 client 目录）
+
+**基本使用：**
+```bash
+# 基本运行
+tcb ag run my-agent
+
+# 指定端口和环境
+tcb ag run my-agent -e dev-xxxx --port 9000
+
+# 指定入口文件
+tcb ag run my-agent --entryPath ./custom-server.js
+```
+
+**调试功能：**
+```bash
+# 启动调试面板
+tcb ag run my-agent --open-debug-panel
+
+# 同时启动前端项目
+tcb ag run my-agent --web
+
+# 组合使用：Agent + 前端 + 调试面板
+tcb ag run my-agent --web --open-debug-panel
+```
+
+**高级功能：**
+```bash
+# 传递扩展上下文
+tcb ag run my-agent --extendedContext '{"userId": "123", "debug": true}'
+
+# 代码验证模式（不启动服务）
+tcb ag run my-agent --dry-run
+```
+
+**支持的项目类型：**
+- **Node.js 项目**: 自动检测 package.json 和入口文件
+- **Python 项目**: 自动检测 requirements.txt 和 Python 入口文件
+- **前端项目**: 检测 client 目录下的前端项目（React、Vue 等）
+
+
+### ag list - 查看 Agent 列表
+
+列出环境中的所有 Agent。
+
+**语法：**
+```bash
+tcb ag list [options]
+```
+
+**选项：**
+- `-e, --envId <envId>`: 环境 ID
+- `-l, --limit <limit>`: 数据长度（默认: 20）
+- `-o, --offset <offset>`: 偏移量（默认: 0）
+- `--format <format>`: 输出格式（table | json，默认: table）
+
+**示例：**
+```bash
+# 基本列表
+tcb ag list
+
+# 分页查询
+tcb ag list -l 10 -o 20
+
+# JSON 格式输出
+tcb ag list --format json
+```
+
+### ag detail - 查看 Agent 详情
+
+查看指定 Agent 的详细信息。
+
+**语法：**
+```bash
+tcb ag detail <agentName> [options]
+```
+
+**参数：**
+- `agentName`: Agent 名称
+
+**选项：**
+- `-e, --envId <envId>`: 环境 ID
+- `--format <format>`: 输出格式（table | json，默认: table）
+
+**示例：**
+```bash
+# 查看详情
+tcb ag detail my-agent
+
+# JSON 格式输出
+tcb ag detail my-agent --format json
+```
+
+### ag delete - 删除 Agent
+
+删除指定的 Agent 或所有 Agent。
+
+**语法：**
+```bash
+tcb ag delete [agentName] [options]
+```
+
+**参数：**
+- `agentName`: Agent 名称（可选）
+
+**选项：**
+- `-e, --envId <envId>`: 环境 ID
+- `--agentId <agentId>`: Agent ID（用于指定特定的 Agent ID）
+- `--force`: 强制删除，不提示确认
+- `--all`: 删除配置文件中的所有 Agent
+
+**示例：**
+```bash
+# 删除指定 Agent
+tcb ag delete my-agent
+
+# 强制删除
+tcb ag delete my-agent --force
+
+# 删除所有 Agent
+tcb ag delete --all
+
+# 通过 Agent ID 删除
+tcb ag delete --agentId specific-agent-id
+```
+
+## 配置文件
+
+### cloudbaserc.json
+
+Agent 配置存储在项目根目录的 `cloudbaserc.json` 文件中。使用 `tcb ag create` 命令会自动创建或更新此配置文件。
+
+**配置文件结构：**
+```json
+{
+  "envId": "test-tooltip-7g3fqqhv48eec964",
+  "agentRoot": "./",
+  "agents": [
+    {
+      "id": "my-agent",
+      "name": "智能聊天机器人",
+      "timeout": 300,
+      "environment": {
+        "key": "value"
+      },
+      "runtime": "Nodejs20.19",
+      "memorySize": 2048,
+      "description": "",
+      "sessionConfig": {
+        "enable": true
+      },
+      "ignore": ["client/**", "client/node_modules/**"],
+      "resources": [],
+      "installDependency": true
+    }
+  ]
+}
+```
+
+**配置字段说明：**
+- `envId`: CloudBase 环境 ID
+- `agentRoot`: Agent 项目根目录
+- `agents`: Agent 配置数组
+  - `id`: Agent 唯一标识符
+  - `name`: Agent 显示名称
+  - `timeout`: 超时时间（秒）
+  - `environment`: 环境变量配置
+  - `runtime`: 运行时版本（Nodejs20.19 或 Python3.10）
+  - `memorySize`: 内存大小（MB）
+  - `sessionConfig`: 会话配置
+  - `ignore`: 部署时忽略的文件/目录
+  - `resources`: 绑定的资源列表
+  - `installDependency`: 是否自动安装依赖
+
+## 最佳实践
+
+### 1. 开发流程
+
+1. **创建项目**：使用 `tcb ag create` 初始化项目
+2. **本地开发**：使用 `tcb ag run` 进行本地调试
+3. **全栈开发**：使用 `tcb ag run --web` 同时启动前后端
+4. **调试测试**：使用 `tcb ag run --open-debug-panel` 打开调试面板
+5. **部署上线**：使用 `tcb ag deploy` 部署到云端
+
+### 2. 调试和开发技巧
+
+**使用调试面板：**
+- 启动调试面板：`tcb ag run my-agent --open-debug-panel`
+- 调试面板提供 HTTP 和 SSE 请求测试功能
+- 支持自定义请求头和请求体
+
+**前端开发：**
+- 使用 `--web` 参数同时启动前后端
+- 前端项目会自动配置 API 地址指向 Agent 服务
+- 支持 React、Vue 等主流前端框架
+
+**多语言支持：**
+- Node.js 项目：自动检测 package.json 和入口文件
+- Python 项目：自动检测 requirements.txt 和 Python 入口文件
+- 支持自定义入口文件：`--entryPath`
+
+## 故障排除
+
+### 常见问题
+
+1. **Agent 名称规范**
+   - Agent 名称用作项目目录名，建议使用小写字母和连字符
+   - 避免使用特殊字符和空格
+
+2. **环境 ID 不存在**
+   - 检查环境 ID 是否正确
+   - 确保有访问该环境的权限
+
+3. **部署失败**
+   - 检查代码结构是否完整
+   - 确保 package.json 或 requirements.txt 存在
+   - 检查入口文件是否正确
+
+4. **本地调试无法启动**
+   - 检查端口是否被占用
+   - 确保项目依赖已安装
+   - 检查 Python 环境（Python 项目）
+
+5. **前端项目无法启动**
+   - 确保 client 目录存在
+   - 检查前端项目的 package.json 和启动脚本
+   - 确保前端依赖已安装
+
+### 获取帮助
+
+```bash
+# 查看命令帮助
+tcb ag --help
+tcb ag create --help
+tcb ag run --help
+tcb ag deploy --help
+
+# 查看版本信息
+tcb --version
+```
+
+## 新功能亮点
+
+### 🚀 交互式项目创建
+- 支持交互式向导，逐步选择后端语言、框架和前端模板
+- 自动更新 `cloudbaserc.json` 配置文件
+- 支持 Node.js 和 Python 两种后端语言
+
+### 🔧 强大的本地调试
+- 内置调试面板，支持 HTTP 和 SSE 请求测试
+- 支持同时启动前后端项目（`--web` 参数）
+- 自动检测项目类型和入口文件
+- 支持自定义入口文件路径
+
+### 🌐 全栈开发支持
+- 前端项目自动配置 API 地址
+- 支持多种前端框架（React、Vue 等）
+- 自动安装前端依赖
+- 智能环境变量配置
+
+### 🐍 Python 项目支持
+- 完整的 Python 项目支持
+- 自动检测 Python 解释器和依赖
+- 支持 requirements.txt 自动安装
+
+## 更多资源
+
+- [CloudBase 官方文档](https://docs.cloudbase.net/)
+- [Agent 开发指南](https://docs.cloudbase.net/agent/)
+- [问题反馈](https://github.com/TencentCloudBase/cloudbase-cli/issues)

package/tsconfig.json

@@ -1,7 +1,7 @@
 {
     "compilerOptions": {
         "module": "commonjs",
-        "target": "es2015",
+        "target": "es2019",
         "moduleResolution": "node",
         "outDir": "lib",
         "removeComments": true,

package/types/commands/ag/base.d.ts

@@ -0,0 +1,44 @@
+import { IAgentResource } from '@cloudbase/manager-node/types/agent/type';
+import { CloudBaseError } from '../../error';
+export interface CloudbaseConfig {
+    envId: string;
+    agentRoot: string;
+    agents?: IAgentConfig[];
+    [key: string]: any;
+}
+export interface IAgentConfig {
+    id?: string;
+    name: string;
+    timeout: number;
+    environment: {
+        [key: string]: string;
+    };
+    runtime: string;
+    memorySize: number;
+    description: string;
+    sessionConfig: {
+        enable: boolean;
+    };
+    ignore: string[];
+    resources: IAgentResource[];
+    installDependency: boolean;
+}
+export declare class AgentError extends CloudBaseError {
+    constructor(message: string, code?: string);
+}
+export declare function getAgentService(envId: string): Promise<import("@cloudbase/manager-node/types/agent").AgentService>;
+export declare function getCloudbaseConfig(cwd?: string): Promise<CloudbaseConfig>;
+export declare function updateCloudbaseConfig(config: Partial<CloudbaseConfig>, cwd?: string): Promise<void>;
+export declare function getAgentConfig(agentName: string, cwd?: string): Promise<IAgentConfig>;
+export declare function updateAgentConfig(agentName: string, agentConfig: Partial<IAgentConfig>, cwd?: string): Promise<void>;
+export declare function removeAgentConfig(agentName: string, cwd?: string): Promise<void>;
+export declare function validateAgentId(agentId: string): boolean;
+export declare function selectAgent(agents: IAgentConfig[]): Promise<string>;
+export declare function inputAgentName(defaultName?: string): Promise<string>;
+export declare function confirmOperation(message: string, defaultValue?: boolean): Promise<boolean>;
+export declare function selectEnvironment(): Promise<string>;
+export declare function formatAgentStatus(status: string): string;
+export declare function formatFileSize(bytes: number): string;
+export declare function formatTime(timestamp: string | number): string;
+export declare function getAgentIdFromConfig(agentName: string, cwd?: string): Promise<string>;
+export declare function updateAgentIdInConfig(agentName: string, agentId: string, cwd?: string): Promise<void>;

package/types/commands/ag/create.d.ts

@@ -0,0 +1,25 @@
+import { Command } from '../common';
+import { Logger } from '../../decorators';
+export declare class AgentCreateCommand extends Command {
+    get options(): {
+        cmd: string;
+        childCmd: string;
+        options: {
+            flags: string;
+            desc: string;
+        }[];
+        requiredEnvId: boolean;
+        autoRunLogin: boolean;
+        desc: string;
+    };
+    execute(ctx: any, envId: string, log: Logger, params: string[], options: {
+        template?: string;
+        framework?: string;
+        lang?: string;
+    }): Promise<void>;
+    private addAgentToConfig;
+    private interactiveSelection;
+    private validateSelections;
+    private downloadBackendTemplate;
+    private downloadFrontendTemplate;
+}

package/types/commands/ag/delete.d.ts

@@ -0,0 +1,32 @@
+import { Command } from '../common';
+import { Logger } from '../../decorators';
+export declare class AgentDeleteCommand extends Command {
+    get options(): {
+        cmd: string;
+        childCmd: string;
+        options: ({
+            flags: string;
+            desc: string;
+            defaultValue?: undefined;
+        } | {
+            flags: string;
+            desc: string;
+            defaultValue: string;
+        } | {
+            flags: string;
+            desc: string;
+            defaultValue: boolean;
+        })[];
+        requiredEnvId: boolean;
+        autoRunLogin: boolean;
+        desc: string;
+    };
+    execute(ctx: any, envId: string, log: Logger, params: string[], options: {
+        force: boolean;
+        all: boolean;
+        agentId: string;
+    }): Promise<void>;
+    private selectEnv;
+    private deleteAgent;
+    private deleteAllAgents;
+}

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

@@ -0,0 +1,31 @@
+import { Command } from '../common';
+import { Logger } from '../../decorators';
+type DeployMode = 'webFn' | 'cloudrun';
+export declare class AgentDeployCommand extends Command {
+    get options(): {
+        cmd: string;
+        childCmd: string;
+        options: ({
+            flags: string;
+            desc: string;
+            defaultValue?: undefined;
+        } | {
+            flags: string;
+            desc: string;
+            defaultValue: boolean;
+        })[];
+        requiredEnvId: boolean;
+        autoRunLogin: boolean;
+        desc: string;
+    };
+    execute(ctx: any, envId: string, log: Logger, params: string[], options: {
+        deployMode?: DeployMode;
+        port?: number;
+        force: boolean;
+        source?: string;
+    }): Promise<void>;
+    private deployAgentInCloudrun;
+    private selectEnv;
+    private checkIfFirstDeploy;
+}
+export {};

package/types/commands/ag/detail.d.ts

@@ -0,0 +1,28 @@
+import { Command } from '../common';
+import { Logger } from '../../decorators';
+export declare class AgentDetailCommand extends Command {
+    get options(): {
+        cmd: string;
+        childCmd: string;
+        options: ({
+            flags: string;
+            desc: string;
+            choices?: undefined;
+            defaultValue?: undefined;
+        } | {
+            flags: string;
+            desc: string;
+            choices: string[];
+            defaultValue: string;
+        })[];
+        requiredEnvId: boolean;
+        autoRunLogin: boolean;
+        desc: string;
+    };
+    execute(ctx: any, envId: string, log: Logger, params: string[], options: {
+        format: 'table' | 'json';
+    }): Promise<void>;
+    private selectEnv;
+    private outputTable;
+    private outputJson;
+}

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

@@ -0,0 +1,6 @@
+export * from './create';
+export * from './deploy';
+export * from './run';
+export * from './list';
+export * from './detail';
+export * from './delete';

package/types/commands/ag/list.d.ts

@@ -0,0 +1,35 @@
+import { Command } from '../common';
+import { Logger } from '../../decorators';
+export declare class AgentListCommand extends Command {
+    get options(): {
+        cmd: string;
+        childCmd: string;
+        options: ({
+            flags: string;
+            desc: string;
+            defaultValue?: undefined;
+            choices?: undefined;
+        } | {
+            flags: string;
+            desc: string;
+            defaultValue: number;
+            choices?: undefined;
+        } | {
+            flags: string;
+            desc: string;
+            choices: string[];
+            defaultValue: string;
+        })[];
+        requiredEnvId: boolean;
+        autoRunLogin: boolean;
+        desc: string;
+    };
+    execute(ctx: any, envId: string, log: Logger, options: {
+        limit: number;
+        offset: number;
+        format: 'table' | 'json';
+    }): Promise<void>;
+    private selectEnv;
+    private outputTable;
+    private outputJson;
+}

package/types/commands/ag/run.d.ts

@@ -0,0 +1,52 @@
+import { Command } from '../common';
+import { Logger } from '../../decorators';
+export declare class AgentRunCommand extends Command {
+    get options(): {
+        cmd: string;
+        childCmd: string;
+        allowUnknownOption: boolean;
+        options: ({
+            flags: string;
+            desc: string;
+            defaultValue?: undefined;
+        } | {
+            flags: string;
+            desc: string;
+            defaultValue: number;
+        } | {
+            flags: string;
+            desc: string;
+            defaultValue: string;
+        })[];
+        requiredEnvId: boolean;
+        autoRunLogin: boolean;
+        desc: string;
+    };
+    execute(ctx: any, envId: string, log: Logger, params: string[], options: {
+        extendedContext?: string;
+        port: number;
+        dryRun: boolean;
+        openDebugPanel: string;
+        entryPath?: string;
+        web?: boolean;
+    }): Promise<void>;
+    private selectEnv;
+    private setupEnvironment;
+    private startNormal;
+    private startDebugPanelAfterAgentReady;
+    private startWebProjectAfterAgentReady;
+    private startWebProject;
+    private startDebugPanelServer;
+    private findAvailablePort;
+    private openDebugPanel;
+    private waitForService;
+    private startAgentService;
+    private detectLanguage;
+    private validateCustomEntryPath;
+    private getPythonEntryPath;
+    private getEntryPath;
+    private startWithPython;
+    private checkPythonAvailable;
+    private startWithNode;
+    private loadEnvFile;
+}

package/types/commands/cloudrun/base.d.ts

@@ -1,7 +1,17 @@
+import { CloudrunServerType } from '@cloudbase/manager-node/types/cloudrun/type';
 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 function cloudRunDeploy(deployOptions: {
+    envId: string;
+    serviceName: string;
+    targetDir: string;
+    serverType: CloudrunServerType;
+    port?: number;
+    installDependency?: string;
+    log: Logger;
+}): Promise<void>;
 export declare class CloudRunInitCommand extends Command {
     get options(): {
         cmd: string;