@cloudbase/cli 2.11.0-beta.0 → 2.11.0

package/specs/ag-command/tasks.md

@@ -1,197 +0,0 @@
-# AG 命令实施计划
-
-## 阶段一：基础架构搭建
-
-- [ ] 1. 创建 ag 命令基础结构
-  - 在 `src/commands/` 下创建 `ag/` 目录
-  - 创建 `ag/index.ts` 作为命令入口
-  - 创建 `ag/base.ts` 定义基础服务和工具函数
-  - _需求: 需求 11, 需求 14_
-
-- [ ] 2. 定义 TypeScript 类型和接口
-  - 创建 `AgentConfig` 接口定义
-  - 创建 `AgentError` 错误类
-  - 定义命令参数和选项的类型
-  - _需求: 需求 11, 需求 12_
-
-- [ ] 3. 实现配置文件管理工具
-  - 实现 `getAgentConfig()` 函数
-  - 实现 `updateAgentConfig()` 函数
-  - 实现 `validateAgentId()` 函数
-  - 实现 cloudbaserc.json 的读写操作
-  - _需求: 需求 11_
-
-- [ ] 4. 创建 Agent 服务连接
-  - 实现 `getAgentService()` 函数（参考 cloudrun 模块）
-  - 配置认证和区域信息
-  - 实现错误处理和重试机制
-  - _需求: 需求 12_
-
-## 阶段二：核心命令实现
-
-- [ ] 5. 实现 ag create 命令
-  - 创建 `ag/create.ts` 文件
-  - 实现 `AgentCreateCommand` 类
-  - 支持模板选择和项目初始化
-  - 集成 @ag-kit/cli 或模板下载功能
-  - _需求: 需求 1_
-
-- [ ] 6. 实现 ag deploy 命令
-  - 创建 `ag/deploy.ts` 文件
-  - 实现 `AgentDeployCommand` 类
-  - 支持首次部署和更新部署逻辑
-  - 支持 webFn 和 cloudrun 两种部署模式
-  - _需求: 需求 2_
-
-- [ ] 7. 实现 ag run 命令
-  - 创建 `ag/run.ts` 文件
-  - 实现 `AgentRunCommand` 类
-  - 集成本地调试服务启动
-  - 实现浏览器自动打开功能
-  - _需求: 需求 3_
-
-- [ ] 8. 实现 ag web 命令
-  - 创建 `ag/web.ts` 文件
-  - 实现 `AgentWebCommand` 类
-  - 启动 Web 应用服务
-  - 配置端口和访问地址
-  - _需求: 需求 4_
-
-## 阶段三：管理命令实现
-
-- [ ] 9. 实现 ag invoke 命令
-  - 创建 `ag/invoke.ts` 文件
-  - 实现 `AgentInvokeCommand` 类
-  - 支持 HTTP API 调用
-  - 处理请求数据和头信息
-  - _需求: 需求 5_
-
-- [ ] 10. 实现 ag list 命令
-  - 创建 `ag/list.ts` 文件
-  - 实现 `AgentListCommand` 类
-  - 实现分页查询功能
-  - 格式化表格输出
-  - _需求: 需求 6_
-
-- [ ] 11. 实现 ag detail 命令
-  - 创建 `ag/detail.ts` 文件
-  - 实现 `AgentDetailCommand` 类
-  - 查询 Agent 详细信息
-  - 显示绑定的资源信息
-  - _需求: 需求 7_
-
-- [ ] 12. 实现 ag delete 命令
-  - 创建 `ag/delete.ts` 文件
-  - 实现 `AgentDeleteCommand` 类
-  - 支持单个和批量删除
-  - 实现确认机制
-  - _需求: 需求 8_
-
-## 阶段四：扩展功能实现
-
-- [ ] 13. 实现 ag download 命令
-  - 创建 `ag/download.ts` 文件
-  - 实现 `AgentDownloadCommand` 类
-  - 支持代码下载和覆盖确认
-  - 更新本地配置文件
-  - _需求: 需求 9_
-
-- [ ] 14. 实现 ag resource 命令组
-  - 创建 `ag/resource/` 目录
-  - 实现 `resource/unbind.ts` - 解绑资源
-  - 实现 `resource/detail.ts` - 查询资源
-  - 创建 `resource/index.ts` 统一导出
-  - _需求: 需求 10_
-
-- [ ] 15. 实现交互式工具函数
-  - 创建 `ag/utils.ts` 文件
-  - 实现 `selectAgent()` 函数
-  - 实现 `inputAgentName()` 函数
-  - 实现 `confirmOperation()` 函数
-  - _需求: 需求 12_
-
-## 阶段五：国际化和优化
-
-- [ ] 16. 添加国际化支持
-  - 在 `locales/langs/` 中添加 ag 命令相关文本
-  - 使用 `t()` 函数包装所有用户可见文本
-  - 更新中英文语言文件
-  - _需求: 需求 13_
-
-- [ ] 17. 完善错误处理
-  - 实现统一的错误处理机制
-  - 添加详细的错误提示和解决建议
-  - 实现操作进度指示器
-  - _需求: 需求 12_
-
-- [ ] 18. 集成到主命令系统
-  - 在 `src/commands/index.ts` 中导出 ag 命令
-  - 更新命令注册逻辑
-  - 确保与现有命令的兼容性
-  - _需求: 需求 14_
-
-## 阶段六：测试和文档
-
-- [ ] 19. 编写单元测试
-  - 创建 `test/ag/` 测试目录
-  - 编写配置文件操作测试
-  - 编写工具函数测试
-  - 编写错误处理测试
-  - _需求: 所有需求_
-
-- [ ] 20. 编写集成测试
-  - 测试命令执行流程
-  - 测试 API 接口调用
-  - 测试文件操作
-  - _需求: 所有需求_
-
-- [ ] 21. 完善文档和示例
-  - 更新 README.md 文档
-  - 创建使用示例和最佳实践
-  - 编写故障排除指南
-  - _需求: 需求 12, 需求 13_
-
-## 阶段七：发布和维护
-
-- [ ] 22. 版本发布准备
-  - 更新版本号和变更日志
-  - 进行最终测试和验证
-  - 准备发布说明
-  - _需求: 需求 14_
-
-- [ ] 23. 监控和反馈收集
-  - 设置使用情况监控
-  - 收集用户反馈
-  - 制定后续优化计划
-  - _需求: 需求 12_
-
-## 依赖关系
-
-- 阶段一是所有后续阶段的基础
-- 阶段二的命令实现相互独立，可以并行开发
-- 阶段三依赖阶段二的基础架构
-- 阶段四可以与阶段三并行进行
-- 阶段五需要在功能完成后进行
-- 阶段六贯穿整个开发过程
-- 阶段七在所有功能完成后进行
-
-## 里程碑
-
-1. **M1 - 基础架构完成**：完成阶段一，建立基本的项目结构和工具函数
-2. **M2 - 核心功能完成**：完成阶段二，实现主要的 Agent 管理功能
-3. **M3 - 管理功能完成**：完成阶段三，实现所有管理和查询功能
-4. **M4 - 功能完整**：完成阶段四，实现所有扩展功能
-5. **M5 - 产品就绪**：完成阶段五和六，准备发布
-6. **M6 - 正式发布**：完成阶段七，正式发布并开始维护
-
-## 预估工期
-
-- 阶段一：3-5 天
-- 阶段二：8-10 天
-- 阶段三：6-8 天
-- 阶段四：4-6 天
-- 阶段五：3-4 天
-- 阶段六：5-7 天（与开发并行）
-- 阶段七：2-3 天
-
-**总计：约 4-6 周**

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

@@ -1,420 +0,0 @@
-# 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)