@cloudbase/manager-node 5.7.1-beta.1 → 5.8.0-beta.0

package/types/deploy/GatewayDeployer.d.ts

@@ -0,0 +1,194 @@
+import { Environment } from '../environment';
+import { HTTPServiceRouteParam } from '../env/type';
+/** 网关路由配置（cloudbaserc.json gateway.routes[]） */
+export interface IGatewayRoute {
+    /** 绑定的自定义域名。配置时自动绑定（需 certId）；不填则使用环境 HTTP 访问服务的默认域名（如 {envId}-{uin}.{region}.app.tcloudbase.com） */
+    domain?: string;
+    /** SSL 证书 ID（绑定自定义域名时需要，可先通过 SSL 控制台/API 获取） */
+    certId?: string;
+    /** 域名接入方式（默认 DIRECT 直接接入）：DIRECT/CDN（接入云开发 CDN）/CUSTOM（自定义接入，需 customCname）/EO（接入云开发 EdgeOne） */
+    accessType?: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO';
+    /** 自定义接入时配置的 CNAME 记录（accessType=CUSTOM 时必填） */
+    customCname?: string;
+    /** 域名协议（默认 HTTP_AND_HTTPS）：HTTP/HTTPS/HTTP_AND_HTTPS/HTTP_TO_HTTPS/HTTPS_TO_HTTP */
+    protocol?: 'HTTP' | 'HTTPS' | 'HTTP_AND_HTTPS' | 'HTTP_TO_HTTPS' | 'HTTPS_TO_HTTP';
+    /** 域名启用状态（默认 true） */
+    enable?: boolean;
+    /** 路径，如 /api 或 /web */
+    path: string;
+    /** 目标：function:<name> 或 hosting:<name> */
+    target: string;
+    /** 是否开启路径透传（默认 false） */
+    enablePathTransmission?: boolean;
+    /** 是否开启身份认证（默认 false） */
+    enableAuth?: boolean;
+    /** 路径重写配置（prefix/staticStorePrefix 只能填一个）。hosting 路由未配置时自动生成 { Prefix: deployPath }；显式配置时透传且不校验 hosting 名称（可引用已部署实例） */
+    pathRewrite?: {
+        prefix?: string;
+        staticStorePrefix?: string;
+    };
+    /** QPS 限频策略 */
+    qpsPolicy?: {
+        /** QPS 限额总量（每秒请求次数），100-100000 */
+        qpsTotal?: number;
+        /** 客户端限频配置 */
+        qpsPerClient?: {
+            limitBy?: 'UserID' | 'ClientIP';
+            limitValue?: number;
+        };
+    };
+}
+/** 网关部署结果 */
+export interface IGatewayDeployResult {
+    domain: string;
+    routes: Array<{
+        path: string;
+        target: string;
+        url: string;
+    }>;
+}
+/**
+ * 网关声明式部署器
+ * 支持 function:<name>（SCF 云函数）与 hosting:<name>（STATIC_STORE 静态托管）两种目标
+ */
+export declare class GatewayDeployer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * 部署网关路由
+     *
+     * 域名规则：
+     * - 未配置 domain → 使用环境 HTTP 访问服务的**默认域名**（Domains 中 IsDefault=true，如 {envId}-{uin}.{region}.app.tcloudbase.com），直接创建路由
+     * - 配置了 domain（自定义域名）→ **先自动绑定自定义域名**（bindCustomDomain，需 certId），再创建路由
+     * 不同域名的路由分组创建。
+     */
+    deploy(options: {
+        routes: IGatewayRoute[];
+        envId: string;
+        /** hosting 配置列表（用于为 hosting:<name> 路由生成 PathRewrite.Prefix 部署路径） */
+        hostings?: Array<{
+            name?: string;
+            deployPath?: string;
+        }>;
+    }): Promise<IGatewayDeployResult>;
+    /**
+     * 解析路由配置：校验 target 格式并映射为 HTTPServiceRouteParam
+     *
+     * 对齐 tcb routes add 的底层校验（src/commands/routes/add.ts）：
+     * - path 必须以 / 开头，每段只含字母/数字/./_/-，50 字符内，不支持通配符 *
+     * - 静态托管（STATIC_STORE）上游名固定为 staticstore，且只支持一级路径
+     */
+    parseRoute(route: IGatewayRoute): HTTPServiceRouteParam;
+    /**
+     * 计算网关路由部署计划（dry-run）：每个路由 create/update/skip + 变更字段明细
+     *
+     * 判定逻辑与 deploy() 完全一致：云端不存在的 path → create；
+     * 已存在但显式配置不一致 → update（带 changes）；一致 → skip。
+     */
+    planRoutes(options: {
+        routes: IGatewayRoute[];
+        envId: string;
+        hostings?: Array<{
+            name?: string;
+            deployPath?: string;
+        }>;
+    }): Promise<Array<{
+        path: string;
+        target: string;
+        status: 'create' | 'update' | 'skip';
+        changes?: Array<{
+            field: string;
+            from?: string;
+            to?: string;
+        }>;
+    }>>;
+    /**
+     * 查询指定域名下已存在的路由（幂等收敛用），返回 Map<path, 云端路由详情>
+     *
+     * 匹配策略（优先级从高到低）：
+     * 1. 用 Filters 精确查询目标域名：DescribeHTTPServiceRoute 不带 Filters 时返回的 Domains
+     *    列表可能不完整（如 lowcode 环境 TotalCount=67 但 Domains 只返回部分，HTTPSERVICE 的
+     *    .app.tcloudbase.com 域名缺失），导致云端已有路由查不到被误判为 create
+     * 2. 降级：不带 Filters 全量查询，按域名归一化匹配（去协议/尾斜杠/转小写）
+     *    若目标域名找不到则返回空（保留 domain 维度，避免把其他域名同 path 误判为已存在）
+     */
+    private getExistingRoutes;
+    /**
+     * 域名归一化：去协议、去尾斜杠、转小写（用于幂等收敛的域名匹配）
+     */
+    private normalizeDomain;
+    /**
+     * 判断错误是否属于「路由已存在/已占用」类（幂等降级专用）
+     *
+     * 只匹配明确的重复/占用语义（code 含 AlreadyExists/Duplicate/ResourceInUse/Conflict，
+     * 或 message 含 already exists），并显式排除否定语义（not exists/not found 等），
+     * 避免把「环境/资源不存在」等真实失败误判为「已存在」而被静默跳过
+     */
+    private isAlreadyExistsError;
+    /**
+     * 判断期望路由与云端已存在路由是否一致
+     *
+     * 只比较**用户显式声明的字段**（enableAuth/enablePathTransmission 显式配置才比较；
+     * QPSPolicy/PathRewrite 本地有值才比较），避免覆盖控制台单独配置的字段。
+     */
+    private routesEqual;
+    /**
+     * 构建 modifyHttpServiceRoute 的路由参数：只包含基础字段 + 用户显式声明的配置字段
+     */
+    private buildModifyParam;
+    private deepEqual;
+    /**
+     * 自动绑定自定义域名（幂等，支持证书更新）
+     *
+     * certId 解析优先级：
+     * 1. 显式配置的 certId 优先（未配置时按域名自动匹配已签发证书）
+     * 2. 域名已绑定 + 未显式 certId 或与云端一致 → 跳过绑定（幂等）
+     * 3. 域名已绑定 + 显式 certId 与云端不一致 → 重新绑定（更新证书）
+     * 4. 未绑定且无法确定 certId → 明确报错并给出操作指引
+     */
+    private ensureDomainBound;
+    /**
+     * 查询当前环境已绑定的自定义域名列表（含证书 ID，用于幂等跳过与证书更新判断）
+     */
+    private getBoundDomains;
+    /**
+     * 按域名自动匹配 SSL 证书 ID（腾讯云 ssl.DescribeCertificates）
+     *
+     * 匹配规则（按返回顺序取第一个）：
+     * - 证书状态为已签发（Status === 1）
+     * - 证书主域名（Domain）或关联域名（SubjectAltName）包含目标域名
+     * - 证书未过期（CertEndTime 晚于当前时间）
+     * 查询失败或无匹配返回 null（由调用方给出明确报错）
+     */
+    private resolveCertIdByDomain;
+    /**
+     * 解析路由（含异步函数类型判断 + hosting 路径重写）
+     *
+     * - function 目标：查询函数详情，HTTP 类型函数 → WEB_SCF（Web 云函数），普通函数 → SCF。
+     *   与 tcb fn deploy 部署 HTTP 函数后控制台创建路由的行为一致（控制台请求中 UpstreamResourceType=WEB_SCF）。
+     * - hosting 目标：自动生成 PathRewrite.Prefix = 对应 hosting 配置的 deployPath（控制台行为：静态托管路由必带
+     *   PathRewrite.Prefix，将 /路由 前缀重写到静态托管的实际部署路径，否则请求会打到存储根路径导致 404）。
+     */
+    private parseRouteWithType;
+    /**
+     * 映射用户 pathRewrite（camelCase）为 API 格式 HTTPServicePathRewrite（PascalCase）
+     */
+    private mapPathRewrite;
+    /**
+     * 生成路由变更字段明细（与 routesEqual 的判定字段一致）
+     */
+    private routeChanges;
+    /**
+     * 解析环境 HTTP 访问服务的默认域名
+     *
+     * 域名优先级：
+     * 1. Domains 列表中 DomainType=HTTPSERVICE 且 IsDefault=true 的域名（HTTP 网关默认域名）
+     *    —— 注意：AI_AGENT/CBR 等类型的域名（如 agt-xxx.agent.tcloudbase.com）也可能 IsDefault=true，
+     *       但它们不是 HTTP 网关默认域名，必须结合 DomainType 过滤
+     * 2. 通过 DescribeEnvInfo 构造的默认域名 `{envId}-{uin}.{region}.app.tcloudbase.com`（兜底，覆盖 Domains 列表为空的场景——实测部分环境下 Domains 列表为空但默认域名仍存在）
+     * 3. 首个 DomainType=HTTPSERVICE 的域名
+     * 4. OriginDomain —— 回源域名（供自定义 CDN/WAF 回源使用，非对外访问地址），仅作最后兜底
+     * 查询失败或域名缺失时**明确报错**，不使用猜测的兜底域名（避免 INVALID_HOST）。
+     */
+    private resolveDomain;
+}

package/types/deploy/StateStore.d.ts

@@ -0,0 +1,170 @@
+/** hosting 文件指纹（hash + size；size 用于懒加载 diff 预判，避免为未变文件重复读内容） */
+export interface IHostingFileFingerprint {
+    hash: string;
+    size: number;
+}
+/** 快照中指纹值：兼容旧格式（纯 string = 仅 hash，size 未知） */
+export type HostingFileValue = string | IHostingFileFingerprint;
+/** hosting 状态快照条目（产物指纹，不存文件内容） */
+export interface IHostingStateEntry {
+    name: string;
+    deployPath?: string;
+    /** 相对路径 → 文件指纹（兼容旧格式：纯字符串 = 仅 hash，size 未知） */
+    files: Record<string, HostingFileValue>;
+}
+/** hosting 文件级 diff 结果（懒加载：size 预判 + 按需 hash） */
+export interface IHostingFileDiff {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    totalChanged: number;
+    /** 本地与快照完全一致（可跳过部署） */
+    unchanged: boolean;
+    /** true = 文件数超过指纹上限，diff 被放弃，需降级为全量部署 */
+    overLimit?: boolean;
+}
+/** hosting 指纹扫描选项 */
+export interface IHostingScanOptions {
+    /** 指纹文件数上限：超过则抛 HostingFilesOverLimitError（默认 50000；0 = 不限） */
+    maxFiles?: number;
+    /** hash 截断长度（hex 位数，默认 16；64 = 完整 sha256） */
+    hashLength?: number;
+}
+/** diffHostingFiles 选项（继承扫描选项，追加忽略规则） */
+export interface IHostingDiffOptions extends IHostingScanOptions {
+    /** 自定义忽略规则（追加到默认 node_modules / .DS_Store 之后） */
+    ignore?: string[];
+}
+/** hosting 指纹文件数超过上限时抛出（触发降级为全量部署） */
+export declare class HostingFilesOverLimitError extends Error {
+    fileCount: number;
+    limit: number;
+    constructor(fileCount: number, limit: number);
+}
+/** 默认指纹文件数上限（防快照膨胀与 I/O 失控） */
+export declare const DEFAULT_MAX_HOSTING_FILES = 50000;
+/** 默认 hash 截断长度（16 位 hex = 64bit，碰撞概率可忽略；快照体积减半） */
+export declare const DEFAULT_HASH_LENGTH = 16;
+/** app 状态快照条目（仅 diff 相关字段，不写 envVariables 等敏感信息） */
+export interface IAppStateEntry {
+    serviceName?: string;
+    installCommand?: string;
+    buildCommand?: string;
+    outputDir?: string;
+    deployPath?: string;
+}
+/** 部署状态快照（.cloudbase/state.json） */
+export interface IDeployState {
+    version: number;
+    updatedAt: string;
+    gitCommit?: string;
+    resources: {
+        hosting?: IHostingStateEntry[];
+        gateway?: unknown;
+        app?: IAppStateEntry;
+    };
+}
+interface IStateStoreOptions {
+    /** 项目根目录（默认 process.cwd()） */
+    cwd?: string;
+    /** 环境名（--env production 等）：按环境分文件 state.{env}.json */
+    env?: string;
+    /** 自定义 state 路径（优先于 cwd+env 推导） */
+    stateFile?: string;
+}
+/**
+ * 部署状态快照（StateStore）
+ *
+ * 职责：读写 `.cloudbase/state.json`（默认），为 dry-run 的 hosting/app diff 提供本地基准，
+ * 避免每次 diff 都拉取云端。
+ *
+ * 指纹算法：hosting = 产物目录逐文件内容 sha256（相对路径为 key）。
+ * 只存 hash 不存内容，体积 = O(文件数)；app 快照不写入 envVariables（敏感过滤）。
+ */
+export declare class StateStore {
+    private cwd;
+    private env?;
+    private stateFile?;
+    constructor(options?: IStateStoreOptions);
+    /**
+     * 计算 state 文件路径：
+     * - 自定义 stateFile 优先
+     * - 否则 {cwd}/.cloudbase/state.json（无 env）或 state.{env}.json（多环境隔离）
+     */
+    getFilePath(): string;
+    /**
+     * 读取状态快照；文件不存在或 JSON 损坏返回 null（缺失降级，由调用方走云端兜底）
+     */
+    read(): IDeployState | null;
+    /**
+     * 写入状态快照（自动补 version/updatedAt/gitCommit，自动创建 .cloudbase 目录）
+     */
+    write(state: {
+        resources: IDeployState['resources'];
+        gitCommit?: string;
+    }): void;
+    /**
+     * 计算产物目录逐文件 sha256 指纹（仅 hash，兼容旧调用）
+     *
+     * @param projectPath 产物目录（hosting 的 outputDir / root）
+     * @param ignore 自定义忽略规则（追加到默认 node_modules / .DS_Store 之后）
+     * @param options 扫描选项（maxFiles / hashLength）
+     * @returns 相对路径（/ 分隔）→ 文件内容 sha256（默认截断 16 位）
+     */
+    computeHostingFiles(projectPath: string, ignore?: string[], options?: IHostingScanOptions): Promise<Record<string, string>>;
+    /**
+     * 计算产物目录逐文件指纹（hash + size）
+     *
+     * - 强制忽略 node_modules / .DS_Store（与传入 ignore 合并，不可关闭）
+     * - hash 默认截断为 16 位 hex（hashLength 可调，64 = 完整 sha256）
+     * - 文件数超过 maxFiles 抛 HostingFilesOverLimitError（防快照膨胀与 I/O 失控）
+     *
+     * @param projectPath 产物目录（hosting 的 outputDir / root）
+     * @param ignore 自定义忽略规则
+     * @param options 扫描选项（maxFiles / hashLength）
+     * @returns 相对路径（/ 分隔）→ { hash, size }
+     */
+    computeHostingFingerprints(projectPath: string, ignore?: string[], options?: IHostingScanOptions): Promise<Record<string, IHostingFileFingerprint>>;
+    /**
+     * 计算产物目录与快照的变更集（懒加载）
+     *
+     * 优化：先 stat 拿 size，size 与快照不同的文件直接判定变更（不读文件内容），
+     * 只有 size 相同（或旧快照 size 未知）的文件才读内容 hash 对比，
+     * 避免为未变文件做无谓的 I/O 与 hash。
+     * 文件数超过 maxFiles 时放弃 diff，返回 overLimit=true（调用方应降级为全量部署）。
+     *
+     * @param projectPath 产物目录（hosting 的 outputDir / root）
+     * @param previous 上次快照指纹（undefined = 首次部署，全部视为新增）
+     * @param options 选项（ignore / maxFiles / hashLength）
+     */
+    diffHostingFiles(projectPath: string, previous: Record<string, HostingFileValue> | undefined, options?: IHostingDiffOptions): Promise<IHostingFileDiff>;
+    /**
+     * 提取 app 配置快照（仅 diff 白名单字段）
+     * envVariables / ignore 等非 diff 字段与敏感信息不进入快照
+     */
+    buildAppConfig(config: {
+        serviceName?: string;
+        installCommand?: string;
+        buildCommand?: string;
+        outputDir?: string;
+        deployPath?: string;
+        [key: string]: unknown;
+    }): IAppStateEntry | undefined;
+    private hashFile;
+    /** 合并默认忽略规则（node_modules / .DS_Store 不可被调用方关闭） */
+    private mergeIgnore;
+    /** 归一化快照指纹值：旧格式（纯 string = 仅 hash，size 未知用 -1 表示） */
+    private normalizeFileValue;
+    /**
+     * 是否命中忽略规则：
+     * - 目录模式（结尾 /）：匹配该目录及其下所有
+     * - glob（含 **）：转换为正则匹配相对路径
+     * - 其余：精确/前缀匹配
+     */
+    private isIgnored;
+    private matchPattern;
+    private escapeRegExp;
+    /** 解析当前 git commit（非 git 仓库或失败返回 undefined，不阻断） */
+    private resolveGitCommit;
+}
+export {};

package/types/deploy/StaticDeployer.d.ts

@@ -0,0 +1,97 @@
+import { Environment } from '../environment';
+/** app 声明式配置（cloudbaserc.json app 对象） */
+export interface IAppDeployConfig {
+    serviceName?: string;
+    root?: string;
+    framework?: string;
+    installCommand?: string;
+    buildCommand?: string;
+    outputDir?: string;
+    deployPath?: string;
+    ignore?: string[];
+    envVariables?: Record<string, string | number | boolean>;
+}
+/** hosting 声明式配置（cloudbaserc.json hosting[]） */
+export interface IHostingDeployConfig {
+    name?: string;
+    root?: string;
+    /** 框架类型：显式指定或未配置时读 root/package.json 自动检测；static/custom 表示纯静态（不构建） */
+    framework?: string;
+    /** 安装命令，默认 npm install；空字符串跳过安装 */
+    installCommand?: string;
+    /** 构建命令：非空则本地构建后上传；空字符串/未配置且无法检测 → 纯静态直接上传 outputDir */
+    buildCommand?: string;
+    /** 构建产物目录：有构建时默认 dist，纯静态时默认 root */
+    outputDir?: string;
+    /** 云端部署路径（决定访问 URL 与网关 PathRewrite.Prefix） */
+    deployPath?: string;
+    ignore?: string[];
+    /** 构建时环境变量（注入本地构建进程，非敏感） */
+    envVariables?: Record<string, string | number | boolean>;
+}
+export interface IStaticDeployResult {
+    name: string;
+    url?: string;
+    /** 是否写入了版本记录（app 写、hosting 不写） */
+    wroteRecord: boolean;
+}
+/**
+ * app/hosting 声明式部署器
+ *
+ * app：framework=static → 直传产物 + SkipBuild 写记录（对齐 tcb app deploy 纯静态分支）；
+ *      其余 framework → 云端构建（上传源码 → 云端构建 → 写版本记录），与现有 tcb app deploy 一致
+ * hosting：固定静态流程（buildCommand 非空则本地构建后直传），不写版本记录（现有 tcb hosting deploy 行为）
+ */
+export declare class StaticDeployer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * app 部署（与现有 tcb app deploy 一致）
+     *
+     * framework=static：直传产物（hosting uploadFiles）+ createApp(SkipBuild) 后台写部署记录，跳过云端构建。
+     * 其余 framework：上传源码 ZIP → createApp 云端构建 → 写版本记录。
+     */
+    deployApp(options: {
+        config: IAppDeployConfig;
+        cwd?: string;
+    }): Promise<IStaticDeployResult>;
+    /**
+     * hosting 部署（固定静态流程，不写版本记录）
+     *
+     * 支持本地构建（对齐 Netlify）：buildCommand 非空时自动执行 install + build 后上传产物；
+     * 纯静态（buildCommand 空/未配置且无法检测框架）时直接上传 outputDir（默认 root，保持现状）。
+     * 访问地址 = https://{CdnDomain}{deployPath}（与 tcb hosting deploy 一致）
+     */
+    deployHosting(options: {
+        config: IHostingDeployConfig;
+        cwd?: string;
+    }): Promise<IStaticDeployResult>;
+    /**
+     * app 纯静态直传（对齐 tcb app deploy 的 deployStaticApp 分支）
+     *
+     * 1. hosting uploadFiles 直传产物（文件级上传，立即可访问，无需打 ZIP）
+     * 2. 后台异步 createApp(SkipBuild) 写部署记录（失败不影响文件访问）
+     * 3. 跳过云端构建轮询，返回访问地址
+     */
+    private deployAppStatic;
+    /**
+     * app 云端构建：上传源码 ZIP → createApp 云端构建 → 写版本记录
+     */
+    private deployAppCloud;
+    /**
+     * 解析 hosting 访问地址：https://{CdnDomain}{deployPath}
+     */
+    private resolveHostingUrl;
+    /**
+     * 本地构建（install + build）
+     *
+     * - installCommand：默认 npm install，显式空字符串跳过安装
+     * - buildCommand：由调用方保证非空（hosting 经 resolveBuildCommand 判定；app local 由 if 判定）
+     * - envVariables：注入构建进程环境变量（值统一转字符串）
+     */
+    private runLocalBuild;
+    /**
+     * 解析 app 访问地址（describeAppInfo.Domain + appPath）
+     */
+    private resolveAppUrl;
+}

package/types/deploy/domain.d.ts

@@ -0,0 +1,17 @@
+import { Environment } from '../environment';
+/**
+ * 构造环境 HTTP 访问服务默认域名 `${envId}-${AppId}.${region}.${ACCESS_DOMAIN_SUFFIX}`
+ *
+ * 关键：用 `UserInfo.AppId`（腾讯云 appid）而非 `UserInfo.Uin`（账号 uin）。
+ * 控制台默认域名格式是 `${envId}-${AppId}.${region}.${ACCESS_DOMAIN_SUFFIX}`
+ * （如 `xxx-1326375956.ap-shanghai.app.tcloudbase.com`），与 cookie 中的 `appid` 字段对应。
+ * AppId/Region 缺失或查询失败时返回 undefined
+ */
+export declare function resolveAccessServiceDomain(environment: Environment, envId: string): Promise<string | undefined>;
+/**
+ * 构造网关基础地址 `https://{envId}.api.tcloudbasegateway.com`
+ *
+ * 对齐 CLI 的 `EDomain.Gateway`：`isInternalEndpoint` 决定是否国际站域名
+ * （`api.intl.tcloudbasegateway.com`）。
+ */
+export declare function getGatewayBaseUrl(environment: Environment, envId: string): string;

package/types/deploy/framework.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 框架 → 默认构建命令映射（hosting 本地构建 / app 云端构建复用）
+ */
+export declare const FRAMEWORK_BUILD_COMMANDS: Record<string, string>;
+/**
+ * 框架 → 默认构建产物目录映射（与 FRAMEWORK_BUILD_COMMANDS 一一对应）
+ *
+ * 注意不能全部默认 dist：
+ * - CRA（react-scripts build）实际输出 build/
+ * - next/nuxt 输出 .next/.nuxt
+ * - vite/vue 输出 dist
+ * - angular 默认 outputPath 为 dist/<项目名>，产物在子目录而非 dist/ 根目录（见 resolveAngularOutputDir），
+ *   此处 'dist' 仅作 angular.json 推导失败时的回退值
+ * 构建场景 outputDir 未显式配置时必须按此映射取产物目录，否则上传路径与构建产物不一致导致部署失败
+ * （或上传到陈旧的 dist 目录）。
+ */
+export declare const FRAMEWORK_OUTPUT_DIRS: Record<string, string>;
+export interface IFrameworkConfig {
+    framework?: string;
+    buildCommand?: string;
+}
+/** hosting 构建产物目录解析配置 */
+export interface IHostingOutputConfig extends IFrameworkConfig {
+    outputDir?: string;
+}
+/** 读取 package.json 的函数签名（测试可注入 mock，Node 20+ 下 fs 属性为只读 getter 不便 spy） */
+export type ReadPkgFile = (filePath: string, encoding: 'utf8') => string;
+/**
+ * 探测项目根目录下的框架类型（读 package.json 依赖）
+ * 读取失败或无匹配返回 null（按纯静态处理）
+ */
+export declare function detectFramework(root: string, readPkgFile?: ReadPkgFile): string | null;
+/**
+ * 解析构建命令，优先级：
+ * 1. 显式配置 buildCommand（含空字符串，'' = 不构建）
+ * 2. 显式配置 framework → 映射推导（static/custom → null 不构建）
+ * 3. 未配置 framework → 读 package.json 自动探测框架并推导
+ * 均无法确定 → null（纯静态直接上传）
+ */
+export declare function resolveBuildCommand(config: IFrameworkConfig, root: string, readPkgFile?: ReadPkgFile): string | null;
+/**
+ * 解析默认产物目录（有构建场景），优先级：
+ * 1. 显式配置 outputDir → 直接返回（调用方负责 path.resolve）
+ * 2. 显式 framework → FRAMEWORK_OUTPUT_DIRS 映射（react → build，vite/vue → dist，next → .next；
+ *    angular 默认 outputPath 为 dist/<项目名>，从 angular.json 推导真实产物目录）
+ * 3. package.json 自动探测框架 → 映射推导
+ * 均无法确定（纯静态）→ null，由调用方回退到 root
+ *
+ * 与 resolveBuildCommand 共用同一份「框架探测/推导」逻辑，保证「构建产物目录」与「构建命令」来自同一次探测，
+ * 避免 CRA 场景探测到 react-scripts build（产物在 build/）却默认上传 dist 导致路径不存在。
+ */
+export declare function resolveOutputDir(config: IHostingOutputConfig, root: string, readPkgFile?: ReadPkgFile): string | null;
+/**
+ * 统一解析 hosting 上传目录（绝对路径），与 StaticDeployer.deployHosting 保持严格一致。
+ *
+ * 规则：
+ * 1) 有构建命令时：
+ *    - 显式 buildCommand（自定义构建）：outputDir 未配置回退 root/dist
+ *    - 推导 buildCommand（framework / package.json）：按 resolveOutputDir 框架映射，未命中回退 dist
+ * 2) 无构建命令时：
+ *    - outputDir 未配置回退 root（纯静态直传）
+ */
+export declare function resolveHostingOutputDir(config: IHostingOutputConfig, root: string, readPkgFile?: ReadPkgFile): string;

package/types/deploy/function/artifact.d.ts

@@ -0,0 +1,40 @@
+import { ICloudFunction } from '../../interfaces';
+import { ICodeArtifact, IFunctionArtifact, IImageArtifact, INormalizedDeployConfig, INormalizedHttpCloudConfig, INormalizedHttpImageConfig, INormalizedHttpLocalConfig } from '../types';
+/**
+ * 部署物构造与 SCF 参数映射
+ *
+ * 四种构建策略最终都产出统一的部署物，之后走同一条 SCF 创建或更新流程
+ */
+/** 由本地代码来源构造代码类部署物 */
+export declare function createCodeArtifact(config: INormalizedDeployConfig): ICodeArtifact;
+/** 由已有镜像配置构造镜像类部署物 */
+export declare function createImageArtifactFromConfig(config: INormalizedHttpImageConfig): IImageArtifact;
+/**
+ * 由本地构建结果构造镜像类部署物
+ *
+ * local 策略（个人版先行）产出：镜像已由 local-builder 构建并推送，
+ * 此处仅承载最终 imageUri/digest 与容器启动配置，之后复用镜像部署链。
+ */
+export declare function createImageArtifactFromBuild(config: INormalizedHttpLocalConfig, build: {
+    imageUri: string;
+    imageDigest?: string;
+}): IImageArtifact;
+/**
+ * 由云端构建结果构造镜像类部署物
+ *
+ * cloud 策略（CloudApp custom）产出：镜像已在构建容器内 docker build + push到 TCR，
+ * 此处仅承载最终 imageUri/digest 与构建元信息（buildId/logsUrl），之后复用镜像部署链。
+ * effectiveStrategy 标记为 cloud，便于结果层如实回传实际生效的策略。
+ */
+export declare function createImageArtifactFromCloudBuild(config: INormalizedHttpCloudConfig, build: {
+    imageUri: string;
+    imageDigest?: string;
+    buildId?: string;
+    logsUrl?: string;
+}): IImageArtifact;
+/**
+ * 将部署配置与部署物映射为 FunctionService 所需的云函数配置
+ *
+ * 只映射与 SCF 相关的字段，public、gatewayPath 等访问配置由后处理阶段负责
+ */
+export declare function toCloudFunction(config: INormalizedDeployConfig, artifact: IFunctionArtifact): ICloudFunction;