@cloudbase/manager-node 4.11.0-alpha.1 → 4.11.0-alpha.11

package/types/agent/index.d.ts

@@ -1,17 +1,127 @@
 import { Environment } from '../environment';
-import { ICreateFunctionAgentParams } from './type';
+import { ICreateFunctionAgentParams, ICreateAgentParams, ICreateTcbrAgentByImageParams, ICreateTcbrAgentByPackageParams, ICreateTcbrAgentByCodeParams, IDescribeAgentListParams, IDescribeAgentListResponse, IDescribeAgentResponse, IDeleteAgentParams, IDescribeCloudBaseBuildServiceParams, IDescribeCloudBaseBuildServiceResponse, ICreateAgentResponse, IDeleteAgentResponse, ICommonResponse, IUpdateAgentParams, IUpdateScfAgentParams, IUpdateScfAgentResponse, IUpdateTcbrAgentParams, IGetAgentLogsParams } from './type';
 /**
  * Agent 管理类
+ * 支持三种部署方式：
+ * - SCF 云函数：轻量级、按需计费
+ * - TCBR 云托管-镜像：容器化部署
+ * - TCBR 云托管-代码包：源码部署
  */
 export declare class AgentService {
     private environment;
     private tcbService;
     constructor(environment: Environment);
     /**
-     * 创建函数型 Agent
-     * @param {string} [cwd=process.cwd()] 工作目录
-     * @param {ICreateFunctionAgentParams} agentInfo Agent 信息
-     * @returns {Promise<{ BotId: string; RequestId: string }>} Agent 创建结果
+     * 创建 Agent
+     * 支持两种方式：
+     * 1. 传入 cwd 代码目录，自动打包上传
+     * 2. 传入 ZipFile / CosBucketRegion + TempCosObjectName，直接上传
+     * @param params 创建参数
+     * @returns Agent 创建结果
+     */
+    createAgent(params: ICreateAgentParams): Promise<ICreateAgentResponse>;
+    /**
+     * 查询 Agent 列表
+     * @param params 查询参数
+     * @returns Agent 列表
+     */
+    describeAgentList(params?: IDescribeAgentListParams): Promise<IDescribeAgentListResponse>;
+    /**
+     * 查询单个 Agent 详情（包含可用状态）
+     * @param agentId Agent ID
+     * @returns Agent 详情，IsReady 表示是否可用
+     * @example
+     * ```typescript
+     * const result = await agentService.describeAgent('agent-xxx')
+     * if (result.IsReady) {
+     *     console.log('Agent 已就绪，可以调用')
+     * } else {
+     *     console.log('Agent 不可用:', result.NotReadyReason)
+     * }
+     * ```
+     */
+    describeAgent(agentId: string): Promise<IDescribeAgentResponse>;
+    /**
+     * 删除 Agent
+     * 先删除 Agent 记录，再尝试删除底层的云函数或云托管服务
+     * @param params 删除参数
+     * @returns 操作结果，包含 Agent 和底层资源的删除状态
+     */
+    deleteAgent(params: IDeleteAgentParams): Promise<IDeleteAgentResponse>;
+    /**
+     * 更新 Agent（自动判断类型）
+     * 先查询 Agent 类型，然后调用对应的更新方法
+     * @param params 更新参数
+     * @returns 操作结果
+     */
+    updateAgent(params: IUpdateAgentParams): Promise<IUpdateScfAgentResponse>;
+    /**
+     * 更新 SCF Agent（云函数）
+     * 支持两种方式：本地代码目录、ZIP 文件
+     * @param params 更新参数
+     * @returns 更新结果，包含耗时信息
+     */
+    updateScfAgent(params: IUpdateScfAgentParams): Promise<IUpdateScfAgentResponse>;
+    /**
+     * 获取 Agent 调用日志（自动判断类型）
+     * @param params 查询参数
+     * @returns 日志结果，根据 Agent 类型返回不同结构：
+     *   - SCF: IFunctionLogDetailRes[]
+     *   - TCBR: ISearchClsLogResponse
+     * @example
+     * ```typescript
+     * const logs = await agentService.getAgentLogs({
+     *     AgentId: 'agent-xxx',
+     *     limit: 20,
+     *     startTime: '2025-01-01 00:00:00',
+     *     endTime: '2025-01-01 23:59:59'
+     * })
+     * ```
+     */
+    getAgentLogs(params: IGetAgentLogsParams): Promise<any>;
+    /**
+     * 通过镜像创建 TCBR Agent
+     * @internal 暂不对外暴露，后续版本开放
+     * @param params 创建参数
+     * @returns Agent 创建结果
+     */
+    createTcbrAgentByImage(params: ICreateTcbrAgentByImageParams): Promise<ICreateAgentResponse>;
+    /**
+     * 获取代码包上传信息
+     * @internal 暂不对外暴露，后续版本开放
+     * @param params 查询参数
+     * @returns 上传信息
+     */
+    describeCloudBaseBuildService(params: IDescribeCloudBaseBuildServiceParams): Promise<IDescribeCloudBaseBuildServiceResponse>;
+    /**
+     * 通过代码包信息创建 TCBR Agent（已上传代码包）
+     * @internal 暂不对外暴露，后续版本开放
+     * @param params 创建参数
+     * @returns Agent 创建结果
+     */
+    createTcbrAgentByPackage(params: ICreateTcbrAgentByPackageParams): Promise<ICreateAgentResponse>;
+    /**
+     * 通过本地代码创建 TCBR Agent（自动打包上传）
+     * @internal 暂不对外暴露，后续版本开放
+     * @param cwd 代码目录，默认当前工作目录
+     * @param params 创建参数
+     * @returns Agent 创建结果
+     */
+    createTcbrAgentByCode(cwd: string, params: ICreateTcbrAgentByCodeParams): Promise<ICreateAgentResponse>;
+    /**
+     * 更新 TCBR Agent（云托管）
+     * 支持两种方式：本地代码目录、镜像
+     * @internal 暂不对外暴露，后续版本开放
+     * @param params 更新参数
+     * @returns 操作结果
+     */
+    updateTcbrAgent(params: IUpdateTcbrAgentParams): Promise<ICommonResponse>;
+    /**
+     * @deprecated 请使用 createTcbrAgentByCode
+     * 创建函数型 Agent（旧版）
+     * @param cwd 工作目录
+     * @param agentInfo Agent 信息
+     * @returns Agent 创建结果
      */
     createFunctionAgent(cwd: string, agentInfo: ICreateFunctionAgentParams): Promise<{
         BotId: string;

package/types/agent/type.d.ts

@@ -1,3 +1,392 @@
+/**
+ * Agent 类型
+ */
+export type AgentType = 'scf' | 'tcbr';
+/**
+ * 运行时版本
+ */
+export type RuntimeVersion = 'Nodejs20.19' | 'Nodejs18.15' | 'Nodejs16.13' | 'Nodejs14.18' | 'Python3.10' | 'Python3.9' | 'Python3.7' | 'Php8.0' | 'Php7.4' | 'Go1' | 'Java11' | 'Java8';
+/**
+ * 会话来源
+ */
+export type SessionSource = 'HEADER' | 'COOKIE' | 'QUERY_STRING';
+/**
+ * 会话配置
+ */
+export interface ISessionConfig {
+    /** 会话来源，默认 'HEADER' */
+    SessionSource?: SessionSource;
+    /** 会话名称，5-40字符，字母开头 */
+    SessionName?: string;
+    /** 单实例并发会话数，1-100，默认 1 */
+    MaximumConcurrencySessionPerInstance?: number;
+    /** 会话最长生命周期（秒），1-604800，默认 21600 */
+    MaximumTTLInSeconds?: number;
+    /** 会话最长空闲时间（秒），不超过 TTL，默认 1800 */
+    MaximumIdleTimeInSeconds?: number;
+    /** 单实例最大并发数，1-100，默认 50 */
+    MaxConcurrency?: number;
+}
+/**
+ * 创建 Agent 的参数
+ * 支持两种方式：
+ * 1. 传入 cwd 代码目录，自动打包上传
+ * 2. 传入 ZipFile / CosBucketRegion + TempCosObjectName，直接上传
+ */
+export interface ICreateAgentParams {
+    /** Agent 名称 */
+    Name: string;
+    /** Agent ID，不传则自动生成 */
+    AgentId?: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** 运行时版本 */
+    Runtime: RuntimeVersion;
+    /** 超时时间（秒），1-900，默认 3 */
+    Timeout?: number;
+    /** 函数运行时内存大小（MB），可选 64、128-3072（128为阶梯），默认 128 */
+    MemorySize?: number;
+    /** 是否自动安装依赖，默认 false */
+    InstallDependency?: boolean;
+    /** 会话配置 */
+    SessionConfig?: ISessionConfig;
+    /** 代码目录路径 */
+    cwd?: string;
+    /** 忽略的文件模式 */
+    ignore?: string | string[];
+    /** 部署方式：zip（直接上传）或 cos（COS 上传，大文件推荐） */
+    deployMode?: 'zip' | 'cos';
+    /** Base64 编码的 ZIP 文件内容 */
+    ZipFile?: string;
+    /** COS Bucket 区域 */
+    CosBucketRegion?: string;
+    /** COS 临时对象名称 */
+    TempCosObjectName?: string;
+}
+/**
+ * 仓库信息
+ */
+export interface IRepoInfo {
+    /** Git 仓库地址或模板下载地址 */
+    Repo: string;
+    /** 来源标识，如 'template' */
+    Source: string;
+}
+/**
+ * 通过镜像创建 TCBR Agent 的参数
+ */
+export interface ICreateTcbrAgentByImageParams {
+    /** Agent 名称 */
+    Name: string;
+    /** Agent ID */
+    AgentId: string;
+    /** 模板标识符 */
+    Template: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** Docker 镜像 URL */
+    ImageUrl: string;
+    /** 仓库信息 */
+    RepoInfo: IRepoInfo;
+    /** 头像 URL */
+    Avatar?: string;
+    /** 简介 */
+    Introduction?: string;
+}
+/**
+ * 通过代码包创建 TCBR Agent 的参数
+ */
+export interface ICreateTcbrAgentByPackageParams {
+    /** Agent 名称 */
+    Name: string;
+    /** Agent ID */
+    AgentId: string;
+    /** 模板标识符 */
+    Template: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** 代码包名称（上传后获取） */
+    PackageName: string;
+    /** 代码包版本（上传后获取） */
+    PackageVersion: string;
+    /** 来源标识，如 'aiAgentWithConfigYaml' */
+    Source?: string;
+    /** 头像 URL */
+    Avatar?: string;
+    /** 简介 */
+    Introduction?: string;
+}
+/**
+ * 通过本地代码创建 TCBR Agent 的参数（自动上传）
+ */
+export interface ICreateTcbrAgentByCodeParams {
+    /** Agent 名称 */
+    Name: string;
+    /** Agent ID */
+    AgentId: string;
+    /** 模板标识符 */
+    Template: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** 来源标识 */
+    Source?: string;
+    /** 头像 URL */
+    Avatar?: string;
+    /** 简介 */
+    Introduction?: string;
+}
+/**
+ * 查询 Agent 列表的参数
+ */
+export interface IDescribeAgentListParams {
+    /** 每页数量，默认 20 */
+    PageSize?: number;
+    /** 页码，默认 1 */
+    PageNumber?: number;
+    /** 指定 Agent ID（查询单个） */
+    AgentId?: string;
+}
+/**
+ * Agent 信息
+ */
+export interface IAgentInfo {
+    /** Agent ID */
+    AgentId: string;
+    /** Agent 名称 */
+    Name: string;
+    /** Agent 类型 */
+    AgentType: AgentType;
+    /** 简介 */
+    Introduction?: string;
+    /** 头像 */
+    Avatar?: string;
+    /** 背景图 */
+    Background?: string;
+    /** 标签 */
+    Tags?: string[];
+    /** 创建时间 */
+    CreateTime?: string;
+    /** 更新时间 */
+    UpdateTime?: string;
+    /** 状态 */
+    Status?: string;
+    /** 服务 ID */
+    ServiceId?: string;
+}
+/**
+ * Agent 列表响应
+ */
+export interface IDescribeAgentListResponse {
+    /** Agent 列表 */
+    AgentList: IAgentInfo[];
+    /** 总数 */
+    Total: number;
+    /** 请求 ID */
+    RequestId: string;
+}
+/**
+ * Agent 详情响应（包含底层资源状态）
+ */
+export interface IDescribeAgentResponse {
+    /** Agent 基本信息 */
+    AgentInfo: IAgentInfo | null;
+    /** Agent 是否已部署完成且可用 */
+    IsReady: boolean;
+    /** 不可用时的原因说明 */
+    NotReadyReason?: string;
+    /** 请求 ID */
+    RequestId: string;
+}
+/**
+ * 删除 Agent 的参数
+ */
+export interface IDeleteAgentParams {
+    /** Agent ID */
+    AgentId: string;
+}
+/**
+ * 更新 Agent 的参数（通用）
+ * 会自动判断 Agent 类型并调用对应的更新方法
+ */
+export interface IUpdateAgentParams {
+    /** Agent ID（必填） */
+    AgentId: string;
+    /** 代码目录路径（可选，不传则不更新代码） */
+    cwd?: string;
+    /** Base64 编码的 ZIP 文件内容（与 cwd 二选一，仅 SCF 类型） */
+    ZipFile?: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** 运行时版本 */
+    Runtime?: RuntimeVersion;
+    /** 超时时间（秒），1-900 */
+    Timeout?: number;
+    /** 函数运行时内存大小（MB），可选 64、128-3072（128为阶梯） */
+    MemorySize?: number;
+    /** 是否自动安装依赖 */
+    InstallDependency?: boolean;
+    /** 忽略的文件模式（仅 cwd 方式有效，SCF 类型） */
+    Ignore?: string | string[];
+}
+/**
+ * 更新 SCF Agent 的参数
+ */
+export interface IUpdateScfAgentParams {
+    /** Agent ID */
+    AgentId: string;
+    /** 代码目录路径（与 ZipFile 二选一） */
+    cwd?: string;
+    /** Base64 编码的 ZIP 文件内容（与 cwd 二选一） */
+    ZipFile?: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** 运行时版本 */
+    Runtime?: RuntimeVersion;
+    /** 函数超时时间（秒），1-900 */
+    Timeout?: number;
+    /** 函数运行时内存大小（MB），可选 64、128-3072（128为阶梯） */
+    MemorySize?: number;
+    /** 是否自动安装依赖 */
+    InstallDependency?: boolean;
+    /** 忽略的文件模式（仅 cwd 方式有效） */
+    Ignore?: string | string[];
+}
+/**
+ * 更新 SCF Agent 的返回结果
+ */
+export interface IUpdateScfAgentResponse {
+    /** 请求 ID */
+    RequestId: string;
+    /** 总耗时（毫秒） */
+    elapsedTime: number;
+    /** 结果消息 */
+    message: string;
+    /** 详细步骤信息 */
+    details: string[];
+}
+/**
+ * 更新 TCBR Agent 的参数
+ */
+export interface IUpdateTcbrAgentParams {
+    /** Agent ID */
+    AgentId: string;
+    /** 代码目录路径（与 ImageUrl 二选一） */
+    cwd?: string;
+    /** Docker 镜像 URL */
+    ImageUrl?: string;
+    /** 环境变量 */
+    envVariables?: Record<string, string>;
+    /** 是否安装依赖，默认 true（仅代码包部署时有效） */
+    InstallDependency?: boolean;
+    /** CPU 规格（核），如 0.25、0.5、1、2 */
+    Cpu?: number;
+    /** 内存规格（GB），如 0.5、1、2、4 */
+    Mem?: number;
+    /** 最小副本数 */
+    MinNum?: number;
+    /** 最大副本数 */
+    MaxNum?: number;
+    /** 服务端口 */
+    Port?: number;
+    /** 延迟检测时间（秒） */
+    InitialDelaySeconds?: number;
+    /** 日志采集路径，如 "stdout" */
+    CustomLogs?: string;
+}
+/**
+ * 获取上传信息的参数
+ */
+export interface IDescribeCloudBaseBuildServiceParams {
+    /** 服务名（即 AgentId） */
+    ServiceName: string;
+    /** build 类型 */
+    CIBusiness?: 'cloudbaserun' | 'framework-ci';
+    /** 服务版本 */
+    ServiceVersion?: string;
+    /** 文件后缀 */
+    Suffix?: string;
+}
+/**
+ * 上传信息响应
+ */
+export interface IDescribeCloudBaseBuildServiceResponse {
+    /** 上传 URL */
+    UploadUrl: string;
+    /** 上传请求头 */
+    UploadHeaders: Array<{
+        Key: string;
+        Value: string;
+    }>;
+    /** 包名 */
+    PackageName: string;
+    /** 包版本 */
+    PackageVersion: string;
+    /** 下载链接 */
+    DownloadUrl?: string;
+    /** 下载链接是否过期 */
+    OutDate?: boolean;
+    /** 请求 ID */
+    RequestId: string;
+}
+/**
+ * 创建 Agent 响应
+ */
+export interface ICreateAgentResponse {
+    /** Agent ID */
+    AgentId: string;
+    /** 请求 ID */
+    RequestId: string;
+}
+/**
+ * 通用操作响应
+ */
+export interface ICommonResponse {
+    /** 请求 ID */
+    RequestId: string;
+}
+/**
+ * 删除 Agent 响应
+ */
+export interface IDeleteAgentResponse {
+    /** 请求 ID */
+    RequestId: string;
+    /** Agent 记录是否删除成功 */
+    AgentDeleted: boolean;
+    /** 底层资源删除结果，无底层资源时为 undefined */
+    ResourceResult?: {
+        /** 资源类型 */
+        Type: 'scf' | 'tcbr';
+        /** 资源名称 */
+        Name: string;
+        /** 是否删除成功 */
+        Deleted: boolean;
+        /** 删除失败时的错误信息 */
+        Error?: string;
+        /** 删除失败时的清理提示 */
+        CleanupHint?: string;
+    };
+}
+/**
+ * 获取 Agent 日志的参数
+ */
+export interface IGetAgentLogsParams {
+    /** Agent ID */
+    AgentId: string;
+    /** 偏移量，默认 0 */
+    offset?: number;
+    /** 返回数量，默认 10 */
+    limit?: number;
+    /** 开始时间，如 "2024-01-01 00:00:00" */
+    startTime?: string;
+    /** 结束时间，如 "2024-01-01 23:59:59" */
+    endTime?: string;
+    /** 按 RequestId 筛选（仅 SCF Agent） */
+    requestId?: string;
+}
+/**
+ * @deprecated 请使用 ICreateTcbrAgentByCodeParams
+ * 创建函数型 Agent 的参数（旧版）
+ */
 export interface ICreateFunctionAgentParams {
     /**
      * 智能体名称

package/types/cloudApp/index.d.ts

@@ -0,0 +1,73 @@
+import { Environment } from '../environment';
+import { ICreateCloudAppParams, ICreateCloudAppResult, IDescribeCloudAppListParams, IDescribeCloudAppListResult, IDescribeCloudAppInfoParams, IDescribeCloudAppInfoResult, IDeleteCloudAppParams, IDeleteCloudAppResult, IDescribeCloudAppVersionParams, IDescribeCloudAppVersionResult, IDescribeCloudAppVersionListParams, IDescribeCloudAppVersionListResult, IDeleteCloudAppVersionParams, IDeleteCloudAppVersionResult, IDescribeCloudAppCosInfoParams, IDescribeCloudAppCosInfoResult, IUploadCloudAppCodeParams, IUploadCloudAppCodeResult } from './types';
+export * from './types';
+/**
+ * CloudApp 统一部署服务
+ * 提供 Web 应用的创建、查询、删除、版本管理等功能
+ */
+export declare class CloudAppService {
+    private tcbService;
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * 创建/更新 CloudApp 应用
+     * @param params 创建参数
+     */
+    createApp(params: ICreateCloudAppParams): Promise<ICreateCloudAppResult>;
+    /**
+     * 获取 CloudApp 应用列表
+     * @param params 查询参数
+     */
+    describeAppList(params: IDescribeCloudAppListParams): Promise<IDescribeCloudAppListResult>;
+    /**
+     * 获取 CloudApp 应用详情
+     * @param params 查询参数
+     */
+    describeAppInfo(params: IDescribeCloudAppInfoParams): Promise<IDescribeCloudAppInfoResult>;
+    /**
+     * 删除 CloudApp 应用
+     * @param params 删除参数
+     */
+    deleteApp(params: IDeleteCloudAppParams): Promise<IDeleteCloudAppResult>;
+    /**
+     * 获取 CloudApp 版本详情
+     * 不指定 versionName 或 buildId 时返回最新版本
+     * @param params 查询参数
+     */
+    describeAppVersion(params: IDescribeCloudAppVersionParams): Promise<IDescribeCloudAppVersionResult>;
+    /**
+     * 获取 CloudApp 版本列表
+     * @param params 查询参数
+     */
+    describeAppVersionList(params: IDescribeCloudAppVersionListParams): Promise<IDescribeCloudAppVersionListResult>;
+    /**
+     * 删除 CloudApp 版本
+     * @param params 删除参数
+     */
+    deleteAppVersion(params: IDeleteCloudAppVersionParams): Promise<IDeleteCloudAppVersionResult>;
+    /**
+     * 获取 CloudApp COS 上传信息（预签名 URL）
+     * @param params 查询参数
+     */
+    describeCosInfo(params: IDescribeCloudAppCosInfoParams): Promise<IDescribeCloudAppCosInfoResult>;
+    /**
+     * 上传本地代码到 COS
+     * 自动打包 ZIP 并上传到预签名 URL
+     *
+     * 注意：此方法不依赖应用是否已创建，可在创建应用前调用
+     * 返回的 cosTimestamp 用于 createApp 时传入 staticConfig.cosTimestamp
+     *
+     * @param params 上传参数
+     */
+    uploadCode(params: IUploadCloudAppCodeParams): Promise<IUploadCloudAppCodeResult>;
+    /**
+     * 获取环境信息
+     */
+    private getEnvInfo;
+    /**
+     * 校验必填参数
+     * @param params 参数对象
+     * @param fields 必填字段列表
+     */
+    private validateRequiredParams;
+}