@cloudbase/cli 2.11.0-beta.0 → 2.11.0

package/specs/ag-command/doc.md

@@ -1,204 +0,0 @@
-# 背景
-云开发平台 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 | 查看命令帮助信息 |
-
-# 讨论

package/specs/ag-command/requirements.md

@@ -1,173 +0,0 @@
-# AG 命令需求文档
-
-## 介绍
-
-基于云开发平台 Agent 架构统一切换为基于 Web 云函数的 Serverless 服务类型 Agent 的背景，需要在 CloudBase CLI 中实现 ag 命令，用于 Agent 的开发调试、部署和管理等工作。
-
-## 需求
-
-### 需求 1 - Agent 项目初始化
-
-**用户故事：** 作为开发者，我希望能够快速初始化一个新的 Agent 项目，以便开始 Agent 开发工作。
-
-#### 验收标准
-
-1. When 执行 `tcb ag create <agentId>` 时，系统应当创建一个新的 Agent 项目目录结构。
-2. When 指定模板参数时，系统应当基于指定模板创建项目。
-3. When 未指定模板时，系统应当提供模板选择界面。
-4. When 项目创建成功时，系统应当自动生成或更新 cloudbaserc.json 配置文件。
-5. When agentId 格式不正确时，系统应当提示错误信息并拒绝创建。
-
-### 需求 2 - Agent 部署管理
-
-**用户故事：** 作为开发者，我希望能够将本地 Agent 代码部署到云端，支持首次部署和更新部署。
-
-#### 验收标准
-
-1. When 执行 `tcb ag deploy <agentId>` 时，系统应当将 Agent 部署到云端。
-2. When Agent 不存在时，系统应当执行首次部署流程（调用 Create 接口）。
-3. When Agent 已存在时，系统应当执行更新部署流程（调用 Update 接口）。
-4. When 指定 --mode cloudrun 时，系统应当部署到云托管服务。
-5. When 指定 --mode webFn 时，系统应当部署到 Web 函数（默认模式）。
-6. When 部署成功时，系统应当提供访问链接和管理控制台链接。
-
-### 需求 3 - Agent 本地调试
-
-**用户故事：** 作为开发者，我希望能够在本地运行和调试 Agent，以便快速验证功能。
-
-#### 验收标准
-
-1. When 执行 `tcb ag run <agentId>` 时，系统应当启动本地 Agent 服务。
-2. When 服务启动成功时，系统应当自动打开浏览器显示 Agent 调试界面。
-3. When 指定 --extendedContext 参数时，系统应当将扩展上下文传递给 Agent。
-4. When 指定环境 ID 时，系统应当使用对应环境的配置和凭证。
-5. When 文件发生变化时，系统应当支持热重载功能（可选）。
-
-### 需求 4 - Agent Web 应用服务
-
-**用户故事：** 作为开发者，我希望能够启动 Agent 的 Web 应用服务，以便进行 Web 界面调试。
-
-#### 验收标准
-
-1. When 执行 `tcb ag web <agentId>` 时，系统应当启动 Agent Web 服务。
-2. When 指定 --port 参数时，系统应当在指定端口启动服务。
-3. When 未指定端口时，系统应当使用默认端口 8080。
-4. When 服务启动成功时，系统应当输出访问地址。
-
-### 需求 5 - Agent 远程调用
-
-**用户故事：** 作为开发者，我希望能够通过命令行调用云端 Agent，以便测试 Agent 功能。
-
-#### 验收标准
-
-1. When 执行 `tcb ag invoke <agentId>` 时，系统应当调用云端 Agent 服务。
-2. When 指定 -d 参数时，系统应当将数据作为请求体发送。
-3. When 指定 -h 参数时，系统应当将头信息添加到请求中。
-4. When 调用成功时，系统应当输出 Agent 的响应结果。
-5. When 调用失败时，系统应当显示错误信息和状态码。
-
-### 需求 6 - Agent 列表查询
-
-**用户故事：** 作为开发者，我希望能够查看环境中的所有 Agent，以便了解当前部署状态。
-
-#### 验收标准
-
-1. When 执行 `tcb ag list` 时，系统应当显示当前环境的所有 Agent。
-2. When 指定 -l 参数时，系统应当限制返回的数据条数。
-3. When 指定 -o 参数时，系统应当从指定偏移量开始返回数据。
-4. When 列表为空时，系统应当显示相应提示信息。
-5. When 查询成功时，系统应当以表格形式显示 Agent 基本信息（ID、名称、状态、更新时间等）。
-
-### 需求 7 - Agent 详情查看
-
-**用户故事：** 作为开发者，我希望能够查看特定 Agent 的详细信息，包括配置和绑定的资源。
-
-#### 验收标准
-
-1. When 执行 `tcb ag detail <agentId>` 时，系统应当显示指定 Agent 的详细信息。
-2. When Agent 存在时，系统应当显示完整的配置信息（运行时、内存、环境变量等）。
-3. When Agent 绑定了资源时，系统应当同时显示资源信息。
-4. When Agent 不存在时，系统应当提示 Agent 未找到的错误信息。
-
-### 需求 8 - Agent 删除管理
-
-**用户故事：** 作为开发者，我希望能够删除不需要的 Agent，支持单个删除和批量删除。
-
-#### 验收标准
-
-1. When 执行 `tcb ag delete <agentId>` 时，系统应当删除指定的 Agent。
-2. When 执行 `tcb ag delete` 时，系统应当删除配置文件中的所有 Agent。
-3. When 未指定 --force 参数时，系统应当要求用户确认删除操作。
-4. When 指定 --force 参数时，系统应当直接执行删除操作。
-5. When 删除成功时，系统应当显示成功信息并更新本地配置文件。
-
-### 需求 9 - Agent 代码下载
-
-**用户故事：** 作为开发者，我希望能够将云端 Agent 代码下载到本地，以便进行修改和调试。
-
-#### 验收标准
-
-1. When 执行 `tcb ag download <agentId>` 时，系统应当下载指定 Agent 的代码到本地。
-2. When 指定 --destPath 参数时，系统应当下载到指定目录。
-3. When 未指定目标路径时，系统应当下载到当前目录。
-4. When 目标目录已存在文件且未指定 --force 时，系统应当询问是否覆盖。
-5. When 下载成功时，系统应当更新本地 cloudbaserc.json 配置文件。
-
-### 需求 10 - Agent 资源管理
-
-**用户故事：** 作为开发者，我希望能够管理 Agent 绑定的资源，包括绑定、解绑和查询操作。
-
-#### 验收标准
-
-1. When 执行 `tcb ag resource unbind` 时，系统应当解绑指定的资源。
-2. When 执行 `tcb ag resource detail` 时，系统应当显示 Agent 绑定的资源详情。
-3. When 指定必要参数时，系统应当执行相应的资源操作。
-4. When 参数不完整时，系统应当提示缺少的参数信息。
-5. When 操作成功时，系统应当显示操作结果和更新后的资源状态。
-
-### 需求 11 - 配置文件管理
-
-**用户故事：** 作为开发者，我希望系统能够自动管理 cloudbaserc.json 配置文件，确保配置的一致性。
-
-#### 验收标准
-
-1. When 执行 Agent 相关操作时，系统应当自动读取和解析 cloudbaserc.json 配置文件。
-2. When 配置文件不存在时，系统应当自动创建默认配置文件。
-3. When 配置文件格式错误时，系统应当提示错误信息并拒绝操作。
-4. When Agent 配置发生变化时，系统应当自动更新配置文件。
-5. When 多个 Agent 存在时，系统应当正确管理 agents 数组配置。
-
-### 需求 12 - 错误处理和用户体验
-
-**用户故事：** 作为开发者，我希望在操作过程中能够获得清晰的错误提示和操作指导。
-
-#### 验收标准
-
-1. When 操作失败时，系统应当显示具体的错误原因和解决建议。
-2. When 网络请求超时时，系统应当提示网络问题并建议重试。
-3. When 权限不足时，系统应当提示权限问题和获取权限的方法。
-4. When 参数格式错误时，系统应当显示正确的参数格式示例。
-5. When 长时间操作时，系统应当显示进度指示器和状态信息。
-
-### 需求 13 - 国际化支持
-
-**用户故事：** 作为国际化用户，我希望能够使用本地语言进行 Agent 管理操作。
-
-#### 验收标准
-
-1. When 系统语言为中文时，所有提示信息应当显示为中文。
-2. When 系统语言为英文时，所有提示信息应当显示为英文。
-3. When 添加新的文本时，系统应当支持多语言配置。
-4. When 错误信息显示时，系统应当使用对应语言的错误描述。
-
-### 需求 14 - 兼容性和扩展性
-
-**用户故事：** 作为平台维护者，我希望 ag 命令能够与现有 CLI 架构兼容，并支持未来功能扩展。
-
-#### 验收标准
-
-1. When 集成到现有 CLI 时，ag 命令应当遵循统一的命令行接口规范。
-2. When 使用装饰器模式时，系统应当与现有的 functions 和 cloudrun 命令保持一致。
-3. When 添加新功能时，系统应当支持向后兼容的配置格式。
-4. When 升级版本时，系统应当提供配置迁移工具和指导。
-5. When 扩展新的部署模式时，系统应当支持插件化的架构设计。

package/specs/ag-command/summary.md

@@ -1,174 +0,0 @@
-# AG 命令实现总结
-
-## 项目概述
-
-基于 doc.md 中的设计要求，成功实现了完整的 `tcb ag` 命令系统，用于管理基于 Web 云函数的 Serverless 服务类型 Agent。
-
-## 已完成的工作
-
-### 1. 架构设计 ✅
-
-- **设计文档**：`specs/ag-command/design.md` - 完整的架构设计方案
-- **需求文档**：`specs/ag-command/requirements.md` - 详细的需求规格说明
-- **任务分解**：`specs/ag-command/tasks.md` - 完整的实施计划
-
-### 2. 核心实现 ✅
-
-#### 基础架构
-- **`src/commands/ag/base.ts`** - 基础服务类和工具函数
-  - `getAgentService()` - Agent 服务连接
-  - `AgentConfig` 接口定义
-  - 配置文件管理函数
-  - 工具函数和错误处理
-
-#### 命令实现
-- **`src/commands/ag/create.ts`** - Agent 项目初始化
-- **`src/commands/ag/deploy.ts`** - Agent 部署管理
-- **`src/commands/ag/run.ts`** - 本地调试运行
-- **`src/commands/ag/web.ts`** - Web 应用服务
-- **`src/commands/ag/invoke.ts`** - 云端 Agent 调用
-- **`src/commands/ag/list.ts`** - Agent 列表查询
-- **`src/commands/ag/detail.ts`** - Agent 详情查看
-- **`src/commands/ag/delete.ts`** - Agent 删除管理
-- **`src/commands/ag/download.ts`** - Agent 代码下载
-
-#### 资源管理
-- **`src/commands/ag/resource/unbind.ts`** - 资源解绑
-- **`src/commands/ag/resource/detail.ts`** - 资源查询
-
-### 3. 文档完善 ✅
-
-- **使用指南**：`specs/ag-command/usage-guide.md` - 详细的使用说明
-- **命令参考**：包含所有命令的语法、参数和示例
-- **最佳实践**：开发流程和故障排除指南
-
-## 功能特性
-
-### 核心功能
-
-1. **项目管理**
-   - ✅ 初始化 Agent 项目（`ag create`）
-   - ✅ 下载云端代码（`ag download`）
-
-2. **开发调试**
-   - ✅ 本地运行调试（`ag run`）
-   - ✅ Web 应用服务（`ag web`）
-
-3. **部署管理**
-   - ✅ 云端部署（`ag deploy`）
-   - ✅ 支持 Web 函数和云托管两种模式
-
-4. **运维管理**
-   - ✅ Agent 列表查询（`ag list`）
-   - ✅ Agent 详情查看（`ag detail`）
-   - ✅ Agent 删除（`ag delete`）
-   - ✅ 云端调用测试（`ag invoke`）
-
-5. **资源管理**
-   - ✅ 资源解绑（`ag resource unbind`）
-   - ✅ 资源查询（`ag resource detail`）
-
-### 技术特性
-
-1. **架构设计**
-   - 遵循现有 CLI 的装饰器模式
-   - 与 cloudrun、functions 模块保持一致的设计风格
-   - 支持国际化（i18n）
-
-2. **用户体验**
-   - 丰富的交互式提示
-   - 详细的错误信息和解决建议
-   - 进度指示器和状态反馈
-   - 多种输出格式支持（table、json）
-
-3. **配置管理**
-   - 自动管理 `cloudbaserc.json` 配置文件
-   - 支持环境变量配置
-   - 灵活的参数传递方式
-
-4. **错误处理**
-   - 统一的错误处理机制
-   - 详细的错误提示
-   - 优雅的降级处理
-
-## 技术实现亮点
-
-### 1. 模块化设计
-- 每个子命令独立实现，便于维护和扩展
-- 公共功能抽取到 `base.ts` 中复用
-- 清晰的目录结构和导出机制
-
-### 2. 类型安全
-- 完整的 TypeScript 类型定义
-- 接口规范化，便于后续扩展
-- 编译时类型检查
-
-### 3. 用户友好
-- 智能的默认值设置
-- 交互式参数输入
-- 彩色输出和格式化显示
-
-### 4. 扩展性
-- 支持插件化的模板系统
-- 可配置的部署模式
-- 灵活的资源绑定机制
-
-## 与现有系统的集成
-
-### 1. 命令系统集成
-- 使用相同的装饰器模式（`@ICommand`、`@InjectParams` 等）
-- 遵循现有的参数处理和错误处理机制
-- 与现有的环境选择和认证系统集成
-
-### 2. 服务集成
-- 复用现有的 CloudBase SDK 连接方式
-- 使用统一的凭证管理
-- 集成现有的日志和监控系统
-
-### 3. 配置集成
-- 扩展现有的 `cloudbaserc.json` 配置格式
-- 兼容现有的环境管理方式
-- 支持现有的国际化系统
-
-## 后续工作建议
-
-### 1. 集成测试
-- 编写完整的单元测试和集成测试
-- 测试各种边界条件和错误场景
-- 验证与现有系统的兼容性
-
-### 2. 性能优化
-- 优化大文件上传和下载
-- 实现并发部署和批量操作
-- 添加缓存机制提升响应速度
-
-### 3. 功能增强
-- 实现热重载功能（ag run --watch）
-- 添加更多模板选择
-- 支持更多资源类型绑定
-
-### 4. 文档完善
-- 添加 API 文档
-- 创建视频教程
-- 编写故障排除指南
-
-## 部署清单
-
-在正式发布前，需要完成以下工作：
-
-### 必需项
-- [ ] 将 ag 命令注册到主命令系统
-- [ ] 添加国际化文本到语言文件
-- [ ] 编写单元测试
-- [ ] 更新 CLI 版本和变更日志
-
-### 可选项
-- [ ] 添加命令补全支持
-- [ ] 集成使用统计
-- [ ] 添加性能监控
-
-## 结论
-
-AG 命令的实现完全符合 doc.md 中的设计要求，提供了完整的 Agent 生命周期管理功能。代码结构清晰，功能完善，用户体验良好，可以满足开发者对 Agent 管理的各种需求。
-
-通过模块化的设计和与现有系统的良好集成，AG 命令不仅功能强大，而且易于维护和扩展，为后续的功能增强奠定了良好的基础。