@cloudbase/cli 2.10.0-beta.0 → 2.11.0-beta.0

package/specs/ag-command/design.md

@@ -0,0 +1,421 @@
+# AG 命令设计方案
+
+## 1. 整体架构
+
+基于 doc.md 的设计要求，ag 命令将作为 CloudBase CLI 的一个子模块，用于管理新版 Agent（基于 Web 云函数的 Serverless 服务类型 Agent）。
+
+### 1.1 命令结构
+
+```
+tcb ag <subcommand> [agentId] [options]
+```
+
+### 1.2 子命令列表
+
+| 子命令 | 功能 | 参数 |
+|--------|------|------|
+| `create` | 初始化 Agent 项目 | `agentId` |
+| `deploy` | 部署 Agent | `agentId` |
+| `run` | 本地运行 Agent | `agentId` |
+| `web` | 本地运行 Agent Web 应用 | `agentId` |
+| `invoke` | 请求云端 Agent | `agentId` |
+| `list` | 查询 Agent 列表 | - |
+| `detail` | 查看 Agent 详情 | `agentId` |
+| `delete` | 删除 Agent | `[agentId]` |
+| `download` | 下载 Agent 代码 | `agentId` |
+| `resource` | 资源管理 | - |
+
+## 2. 配置文件设计
+
+### 2.1 cloudbaserc.json 扩展
+
+```json
+{
+  "envId": "dev-xxxx",
+  "agents": [
+    {
+      "id": "ag-xxx",
+      "name": "app",
+      "timeout": 5,
+      "environment": {
+        "key": "value"
+      },
+      "runtime": "Nodejs18.15",
+      "memorySize": 10,
+      "description": "",
+      "sessionConfig": {
+        "enable": true
+      },
+      "resources": [
+        {
+          "ResourceId": "",
+          "ResourceType": "",
+          "ResourceConfig": {
+            "Type": "",
+            "ApiKey": ""
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 2.2 TypeScript 类型定义
+
+```typescript
+interface AgentConfig {
+  id: string;
+  name: string;
+  timeout?: number;
+  environment?: Record<string, string>;
+  runtime?: string;
+  memorySize?: number;
+  description?: string;
+  sessionConfig?: {
+    enable: boolean;
+  };
+  resources?: Array<{
+    ResourceId: string;
+    ResourceType: string;
+    ResourceConfig: {
+      Type: string;
+      ApiKey: string;
+    };
+  }>;
+}
+
+interface CloudbaseConfig {
+  envId: string;
+  agents?: AgentConfig[];
+}
+```
+
+## 3. 命令实现设计
+
+### 3.1 基础服务类
+
+参考 cloudrun 模块的 `getCloudrunService` 实现，创建 `getAgentService`：
+
+```typescript
+export async function getAgentService(envId: string) {
+    const region = await getRegion()
+    const { secretId, secretKey, token } = await checkAndGetCredential(true)
+
+    const app = new CloudBase({
+        region,
+        token,
+        envId,
+        secretId,
+        secretKey,
+        proxy: getProxy()
+    })
+    return app.agent
+}
+```
+
+### 3.2 命令类设计
+
+每个子命令对应一个 Command 类，使用装饰器模式：
+
+```typescript
+@ICommand()
+export class AgentCreateCommand extends Command {
+    get options() {
+        return {
+            cmd: 'ag',
+            childCmd: 'create <agentId>',
+            options: [
+                {
+                    flags: '-e, --envId <envId>',
+                    desc: t('环境 ID')
+                },
+                {
+                    flags: '--template <template>',
+                    desc: t('模板名称')
+                },
+                {
+                    flags: '--targetPath <targetPath>',
+                    desc: t('项目初始化目标路径')
+                }
+            ],
+            requiredEnvId: false,
+            autoRunLogin: true,
+            desc: t('初始化 Agent 项目')
+        }
+    }
+
+    @InjectParams()
+    async execute(
+        @CmdContext() ctx: any,
+        @EnvId() envId: string,
+        @Log() log: Logger,
+        @ArgsParams() params: string[],
+        @ArgsOptions() options: {
+            template?: string;
+            targetPath?: string;
+        }
+    ) {
+        // 实现逻辑
+    }
+}
+```
+
+## 4. 详细功能设计
+
+### 4.1 ag create - 初始化 Agent 项目
+
+**功能**：创建新的 Agent 项目结构
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+- `--template`：模板名称（可选）
+- `--targetPath`：目标路径（可选，默认当前目录）
+
+**实现逻辑**：
+1. 验证 agentId 格式
+2. 选择或指定模板
+3. 下载模板到指定目录
+4. 更新 cloudbaserc.json 配置
+5. 初始化项目依赖
+
+### 4.2 ag deploy - 部署 Agent
+
+**功能**：部署 Agent 到云端
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+- `--mode`：部署模式（webFn | cloudrun，默认 webFn）
+- `--force`：强制部署（可选）
+
+**实现逻辑**：
+1. 读取配置文件
+2. 检查 Agent 是否存在（首次部署 vs 更新部署）
+3. 打包代码
+4. 调用相应的部署接口
+5. 更新配置信息
+
+### 4.3 ag run - 本地运行 Agent
+
+**功能**：本地调试运行 Agent
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+- `--extendedContext`：扩展上下文（可选）
+- `--port`：端口号（可选，默认 3000）
+
+**实现逻辑**：
+1. 读取 Agent 配置
+2. 设置本地环境变量
+3. 启动本地服务
+4. 打开调试界面
+
+### 4.4 ag web - 本地运行 Agent Web 应用
+
+**功能**：启动 Agent Web 服务
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+- `--port`：端口号（可选，默认 8080）
+
+**实现逻辑**：
+1. 读取 Agent 配置
+2. 启动 Web 服务器
+3. 提供访问地址
+
+### 4.5 ag invoke - 请求云端 Agent
+
+**功能**：调用云端 Agent 服务
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+- `-d, --data`：请求数据 JSON
+- `-h, --headers`：请求头 JSON
+
+**实现逻辑**：
+1. 构建请求参数
+2. 发送 HTTP 请求到 Agent 服务
+3. 输出响应结果
+
+### 4.6 ag list - 查询 Agent 列表
+
+**功能**：列出环境中的所有 Agent
+
+**参数**：
+- `-l, --limit`：数据长度（可选）
+- `-o, --offset`：偏移量（可选）
+
+**实现逻辑**：
+1. 调用列表接口
+2. 格式化输出表格
+3. 显示 Agent 基本信息
+
+### 4.7 ag detail - 查看 Agent 详情
+
+**功能**：查看指定 Agent 的详细信息
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+
+**实现逻辑**：
+1. 调用详情接口
+2. 查询绑定的资源信息
+3. 格式化输出详细信息
+
+### 4.8 ag delete - 删除 Agent
+
+**功能**：删除指定的 Agent 或所有 Agent
+
+**参数**：
+- `[agentId]`：Agent 标识符（可选，不指定则删除所有）
+- `--force`：强制删除（可选）
+
+**实现逻辑**：
+1. 确认删除操作
+2. 调用删除接口
+3. 更新本地配置文件
+
+### 4.9 ag download - 下载 Agent 代码
+
+**功能**：下载云端 Agent 代码到本地
+
+**参数**：
+- `agentId`：Agent 标识符（必需）
+- `--destPath`：目标目录（可选）
+- `--force`：强制覆盖（可选）
+
+**实现逻辑**：
+1. 选择目标目录
+2. 检查覆盖确认
+3. 下载代码文件
+4. 更新本地配置
+
+### 4.10 ag resource - 资源管理
+
+**子命令**：
+- `ag resource bind`：绑定资源
+- `ag resource unbind`：解绑资源
+- `ag resource detail`：查询绑定资源
+
+**实现逻辑**：
+1. 根据子命令调用相应接口
+2. 处理资源绑定关系
+3. 更新配置信息
+
+## 5. 错误处理设计
+
+### 5.1 通用错误处理
+
+```typescript
+export class AgentError extends CloudBaseError {
+    constructor(message: string, code?: string) {
+        super(message, code)
+        this.name = 'AgentError'
+    }
+}
+```
+
+### 5.2 错误类型
+
+- 配置文件错误
+- Agent 不存在错误
+- 部署失败错误
+- 网络请求错误
+- 权限不足错误
+
+## 6. 工具函数设计
+
+### 6.1 配置文件操作
+
+```typescript
+// 读取 Agent 配置
+export async function getAgentConfig(agentId: string): Promise<AgentConfig>
+
+// 更新 Agent 配置
+export async function updateAgentConfig(agentId: string, config: Partial<AgentConfig>): Promise<void>
+
+// 验证 Agent ID 格式
+export function validateAgentId(agentId: string): boolean
+```
+
+### 6.2 交互式输入
+
+```typescript
+// 选择 Agent
+export async function selectAgent(agents: AgentConfig[]): Promise<string>
+
+// 输入 Agent 名称
+export async function inputAgentName(defaultName?: string): Promise<string>
+
+// 确认操作
+export async function confirmOperation(message: string): Promise<boolean>
+```
+
+## 7. 测试策略
+
+### 7.1 单元测试
+
+- 配置文件操作测试
+- 工具函数测试
+- 错误处理测试
+
+### 7.2 集成测试
+
+- 命令执行流程测试
+- API 接口调用测试
+- 文件操作测试
+
+### 7.3 端到端测试
+
+- 完整的 Agent 生命周期测试
+- 多环境部署测试
+- 错误场景测试
+
+## 8. 国际化支持
+
+所有用户可见的文本都需要支持国际化，使用 `t()` 函数包装：
+
+```typescript
+desc: t('初始化 Agent 项目')
+message: t('请输入 Agent 名称')
+```
+
+## 9. 日志和监控
+
+### 9.1 操作日志
+
+- 记录关键操作步骤
+- 记录错误信息和堆栈
+- 记录性能指标
+
+### 9.2 用户反馈
+
+- 操作进度提示
+- 成功/失败状态反馈
+- 帮助信息和建议
+
+## 10. 兼容性考虑
+
+### 10.1 向后兼容
+
+- 支持旧版配置文件格式
+- 提供迁移工具和指导
+
+### 10.2 平台兼容
+
+- 支持 Windows、macOS、Linux
+- 支持不同 Node.js 版本
+
+## 11. 安全性设计
+
+### 11.1 凭证管理
+
+- 安全存储访问凭证
+- 支持临时凭证
+- 避免凭证泄露
+
+### 11.2 代码保护
+
+- 支持代码加密
+- 安全的代码传输
+- 访问权限控制

package/specs/ag-command/doc.md

@@ -0,0 +1,204 @@
+# 背景
+云开发平台 Agent 架构后续统一切换为基于 Web 云函数的 Serverless 服务类型 Agent，且Agent 实现统一基于 AG-Kit 框架完成，CLI 需针对新版 Agent 完成 开发调试，部署，管理等工作
+
+# 设计
+
+## Agent 配置文件 cloudbaserc.json
+
+``` json
+{
+  // 关联环境 ID
+  "envId": "dev-xxxx",
+  // agent 项目的上级目录
+  "agentRoot": "./",
+  // agent 配置
+  "agents": [
+    {
+       // agent id，也是 agent 代码目录名称
+      "id": "ag-xxx",
+      // agent 名称
+      "name": "app", 
+      // 超时时间，单位：秒 S
+      "timeout": 5,
+      // 环境变量
+      "environment": {
+        "key": "value"
+      },
+      "runtime": "Nodejs18.15",
+      "memorySize": 10,
+      "description": "", 
+      "sessionConfig": {
+	  	"enable": true // 是否开启会话配置
+	  },
+      "resources": [ // 要绑定的资源
+		{
+			     "ResourceId": "", // 资源id
+			     "RecourceType": "", // 资源种类
+			     "RecourceConfig": {
+					 "Type": "", // 资源的子类型
+				 	 "ApiKey": "" // 密钥 
+				 }
+		}
+	  ]
+    }
+  ]
+}
+```
+
+
+## 本地运行 Agent
+
+``` 
+tcb ag run agId [options]
+```
+
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| -e <envId> | 可选，环境 ID |
+| --extendedContext <extendedContext> | 可选，示例：--extendedContext '{"a":1,"b":2}' |
+| -h | 查看命令帮助信息 |
+
+示例
+
+``` 
+tcb ag run ag-xxx
+```
+
+本地运行后可类似 函数式 Agent 启动后打开浏览器渲染 Agent-UI 组件进行调试对话
+
+## 本地运行 Agent Web 应用
+
+``` 
+tcb ag web agId [options] 
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| --port |  Web 服务端口号  |
+
+示例
+
+``` 
+tcb ag web ag-xxx --port 8080 
+```
+
+## 请求云端 Agent 
+HTTP API 形式
+
+```
+curl -L 'https://${ag-xxxxaaaaaa-xxx}.ag.tcloudbase.com?webfn=true' \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
+  -d '{}'
+```
+
+命令形式
+``` 
+tcb ag invoke agId [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| -d | 触发调用的 data JSON 串,如 '{"prompt": "Hello world!"}'   |
+| -h | 触发调用的header JSON 串, 如 '{"Authorization": "Bearer <ACCESS_TOKEN>"}'   |
+
+## 部署 Agent 
+
+内部实现区分首次部署及后续更新部署，命令不做区分
+``` 
+tcb ag deploy agId [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| --mode | webFn：默认值，部署到 Web 函数，cloudrun：部署到托管  |
+- 部署函数
+部署 Agent 会参照 Agent JSON 配置文件
+实现：先检查当前是否存在该 agId 对应的agent，不存在则为首次部署，调用 Create 接口，存在则为更新部署，调用 Update 接口，更新配置信息仍读 Agent 配置文件
+~~首次部署时 CLI 处理给角色授权~~
+
+- 部署托管
+  参照原云托管部署流程
+
+## 查询 Agent 列表
+``` 
+tcb ag list [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| -l | 数据长度  |
+| -o | 偏移量 |
+| -h | 查看命令帮助信息 |
+
+示例
+``` 
+tcb ag list -l 10 -o 10
+```
+## 查看 Agent 详情
+
+``` 
+tcb ag detail ag-xxx
+```
+这里查询会同时查绑定的 resource 信息
+
+## 删除 Agent 
+
+删除指定的 Agent 
+``` 
+tcb ag delete ag-xxx
+```
+删除配置文件中所有 Agent
+``` 
+tcb ag delete
+```
+
+## 初始化 Agent 项目
+
+用户准备项目目录，进入目录后执行该命令生成 Agent 初始项目
+``` 
+tcb ag create agId [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| --template <template> | agent 项目模板   |
+| -h | 查看命令帮助信息 |
+
+``` 
+tcb ag create ag-xxx chat-bot
+```
+实现上可通过下载 Agent 模板项目或者 调用  @ag-kit/cli 命令 <code>ag-kit init</code> 完成初始化
+
+## 下载 Agent 代码
+
+将指定的Agent 项目代码下载到本地指定目录
+``` 
+tcb ag download ag-xxx [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| --destPath | 目标目录   |
+| -h | 查看命令帮助信息 |
+
+## 解绑资源
+``` 
+tcb ag resource unbind [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| --envId | 环境ID   |
+| --agId | 要解绑的 agent 标识   |
+| --resourceId | 资源ID   |
+| --recourceType | 资源类型   |
+| -h | 查看命令帮助信息 |
+
+## 查询绑定资源
+``` 
+tcb ag resource detail [options]
+```
+| 命令行参数 | 含义 |
+| ------ | ------ |
+| --envId | 环境ID   |
+| --agId |  agent 标识   |
+| --resourceId | 资源ID   |
+| --recourceType | 资源类型   |
+| -h | 查看命令帮助信息 |
+
+# 讨论