@h-ai/deploy 1.0.0-beta.5 → 1.0.0-beta.6

package/dist/index.d.ts

@@ -375,100 +375,6 @@ type DeployConfig = z.infer<typeof DeployConfigSchema>;
  */
 type DeployConfigInput = z.input<typeof DeployConfigSchema>;
 
-/** 部署环境的加载和持久化；公开环境文件不保存真实凭据。 */
-
-/**
- * 部署环境快照；例如 prod 的 targetValues 只来自 `.env.prod`，不包含基础/私有覆盖。
- * @example
- * ```ts
- * import type { DeploymentEnvironment } from '@h-ai/deploy'
- * const environment: DeploymentEnvironment = { environment: 'prod', envDir: '/workspace/shop', values: { HAI_DB_TYPE: 'postgresql' }, targetValues: { HAI_DB_TYPE: 'postgresql' } }
- * // values 可能还含私有凭据，不能整体写入日志。
- * ```
- */
-interface DeploymentEnvironment {
-    /** 文件模式（dev/test/prod 或其他合法模式名）。 */
-    environment: string;
-    /** 环境文件的绝对目录。 */
-    envDir: string;
-    /** 合并后的部署变量，可能含私有值，不得直接记录日志。 */
-    values: Record<string, string>;
-    /** 仅目标环境文件显式声明的变量，用于判断能否“保持不变”。 */
-    targetValues: Record<string, string>;
-}
-/**
- * 按来源归并环境变量；HAI 高层父配置清除旧叶，同层按父→叶处理。
- * @param layers - 从低到高优先级的环境来源。
- * @param prefix - 可选变量前缀，仅归并该模块。
- * @returns 归并后的字面量环境变量，可能包含秘密。
- * @example 模块内部上下文
- * ```ts
- * const env = mergeEnvironmentLayers([{ HAI_CACHE_TYPE: 'memory' }, { HAI_CACHE: '{"type":"redis"}' }])
- * ```
- */
-declare function mergeEnvironmentLayers(layers: Array<Record<string, string | undefined>>, prefix?: string): Record<string, string>;
-/**
- * 按部署环境解析配置；未选择的可选 Provisioner 缺少凭据时保留空值，选择完成后由 Schema 校验。
- * hai.json 只读取对应的根分区；运行时模块继续读取 YAML。不修改 core 缓存或进程变量。
- * @param name - 模块配置名，例如 deploy/db/iam
- * @param path - hai.json 或运行时 YAML 文件的绝对路径
- * @param values - 已加载的目标环境变量
- * @returns 配置对象；解析错误已脱敏
- * @example
- * ```ts
- * import { loadDeploymentConfig, loadDeploymentEnvironment } from '@h-ai/deploy'
- * const environment = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
- * if (!environment.success) throw new Error(environment.error.message)
- * const config = loadDeploymentConfig('deploy', `${process.cwd()}/hai.json`, environment.data.values)
- * if (!config.success) throw new Error(config.error.message)
- * // 返回对象仍需经 DeployConfigSchema 或 deploy.init 验证。
- * ```
- */
-declare function loadDeploymentConfig(name: string, path: string, values: Record<string, string | undefined>): HaiResult<Record<string, unknown>>;
-/**
- * 加载部署环境；指定环境文件缺失时返回错误并要求用户创建。
- * 部署目标按进程 > 模式私有 > 模式公共 > 旧全局私有 > 基础归并。
- * 其它模块保留进程 > 模式私有 > 旧全局私有 > 模式公共 > 基础；targetValues 仅记录模式公共项。
- * @param options - 模式、环境目录与是否强制存在目标文件
- * @param options.environment - dev/test/prod 或自定义模式
- * @param options.envDir - 环境文件所在目录
- * @param options.requireFile - 默认 true；扫描无显式环境时可只读取已有基础文件
- * @returns 环境快照，可能包含私有值，不得直接输出
- * @example
- * ```ts
- * import { loadDeploymentEnvironment } from '@h-ai/deploy'
- * const loaded = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
- * if (!loaded.success) throw new Error(loaded.error.message)
- * const explicitlyConfigured = loaded.data.targetValues.HAI_DB_TYPE
- * ```
- */
-declare function loadDeploymentEnvironment(options: {
-    environment: string;
-    envDir: string;
-    requireFile?: boolean;
-}): HaiResult<DeploymentEnvironment>;
-/**
- * 保存部署变量：公共值写目标环境文件，凭据写 `.env.<environment>.local`；旧共享私有文件不删除。
- * 返回实际写入的变量名，调用者只展示名称或脱敏值。
- * @param environment - 已加载的目标环境快照
- * @param values - 需要更新的变量；未提供的项保持原状
- * @param options - private 为 true 时所有值只保存在本机；适用于 SSH 地址、端口及密钥路径
- * @param options.private - 是否将全部值保存到选中模式的私有文件
- * @returns 已保存的变量名或脱敏错误
- * @example
- * ```ts
- * import { loadDeploymentEnvironment, saveDeploymentEnvironment } from '@h-ai/deploy'
- * const loaded = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
- * if (!loaded.success) throw new Error(loaded.error.message)
- * const saved = saveDeploymentEnvironment(loaded.data, { HAI_DB_HOST: 'db' })
- * if (!saved.success) throw new Error(saved.error.message)
- * // 密钥应以 { private: true } 写入被忽略的 .env.prod.local，不能放公共环境文件。
- * ```
- */
-declare function saveDeploymentEnvironment(environment: DeploymentEnvironment, values: Record<string, string>, options?: {
-    private?: boolean;
-}): HaiResult<string[]>;
-
 /**
  *
  * @example
@@ -722,6 +628,10 @@ interface DeployCommandState {
  * ```
  */
 interface DeployAppOptions {
+    /** 本地打包所需镜像的下载源；Compose 与部署身份保留原始镜像引用。 */
+    imageSource?: ImageSourceConfig;
+    /** 本次拉取子进程的代理；远程 Podman/Docker daemon 的代理需在引擎侧设置。 */
+    proxy?: DownloadProxyConfig;
     /** 接收实际执行阶段，用于终端进度显示；不包含凭据或配置原文。 */
     onProgress?: (stage: 'packaging' | 'preflight' | 'images' | 'dependencies' | 'start' | 'https' | 'health' | 'complete') => void;
     /** 只更新指定的 Compose 服务；省略时完整制品部署全部，部分制品只部署其镜像。 */
@@ -743,6 +653,31 @@ interface DeployAppOptions {
     /** 交付包命名路径；默认在 .hai/deploy/<环境>/bundle-<项目>-<部署ID>-<版本>/ 中输出同名 tar 和脚本，自定义 release.tar 输出 release-<版本>/release-<版本>.tar；已有目录拒绝覆盖。 */
     output?: string;
 }
+/**
+ * 镜像下载源；自定义映射可带命名空间路径，不含认证信息。
+ * @example
+ * ```ts
+ * import type { ImageSourceConfig } from '@h-ai/deploy'
+ * const source: ImageSourceConfig = { type: 'custom', registries: { 'docker.io': 'mirror.example.com/docker.io', 'ghcr.io': 'mirror.example.com/ghcr.io' } }
+ * ```
+ */
+interface ImageSourceConfig {
+    type: 'official' | 'cn' | 'custom';
+    registries?: Record<string, string>;
+}
+/**
+ * 下载代理；自定义地址仅接受无认证的 HTTP(S)，认证代理从进程环境继承。
+ * @example
+ * ```ts
+ * import type { DownloadProxyConfig } from '@h-ai/deploy'
+ * const proxy: DownloadProxyConfig = { mode: 'custom', url: 'http://127.0.0.1:10808', bypass: 'localhost,127.0.0.1' }
+ * ```
+ */
+interface DownloadProxyConfig {
+    mode: 'inherit' | 'system' | 'custom' | 'none';
+    url?: string;
+    bypass?: string;
+}
 /**
  * Deploy 凭证文件操作。
  *
@@ -929,6 +864,131 @@ interface DeployFunctions {
     deployApp: (appDir: string, options?: DeployAppOptions) => Promise<HaiResult<DeployResult>>;
 }
 
+/** 构建与交付共用的下载源解析；不修改系统或容器引擎配置。 */
+
+/**
+ * 将镜像引用映射到所选下载源，保留命名空间、版本与摘要。
+ * @param reference - Docker/OCI 镜像引用。
+ * @param source - 官方、大陆或按原仓库配置的自定义源。
+ * @returns 下载引用；官方源保留输入引用。
+ * @throws Error - 源、仓库映射或镜像引用不合法。
+ * @example
+ * ```ts
+ * import { resolveImageReference } from '@h-ai/deploy'
+ * const image = resolveImageReference('node:24.22.1-bookworm-slim', { type: 'cn' })
+ * // docker.1ms.run/library/node:24.22.1-bookworm-slim
+ * ```
+ */
+declare function resolveImageReference(reference: string, source?: ImageSourceConfig): string;
+/**
+ * 解析本次下载使用的代理环境，不写配置、不重启引擎。
+ * @param config - 继承进程、读取系统、自定义或禁用代理。
+ * @returns 显式覆盖大小写代理变量的环境；远程引擎仍需自身配置代理。
+ * @throws Error - 配置非法、系统仅提供 PAC 或平台不支持读取系统代理。
+ * @example
+ * ```ts
+ * import { resolveDownloadProxy } from '@h-ai/deploy'
+ * const environment = resolveDownloadProxy({ mode: 'custom', url: 'http://127.0.0.1:10808' })
+ * // environment.HTTPS_PROXY 供本次子进程使用，不写进运行镜像。
+ * ```
+ */
+declare function resolveDownloadProxy(config?: DownloadProxyConfig): Record<string, string>;
+
+/** 部署环境的加载和持久化；公开环境文件不保存真实凭据。 */
+
+/**
+ * 部署环境快照；例如 prod 的 targetValues 只来自 `.env.prod`，不包含基础/私有覆盖。
+ * @example
+ * ```ts
+ * import type { DeploymentEnvironment } from '@h-ai/deploy'
+ * const environment: DeploymentEnvironment = { environment: 'prod', envDir: '/workspace/shop', values: { HAI_DB_TYPE: 'postgresql' }, targetValues: { HAI_DB_TYPE: 'postgresql' } }
+ * // values 可能还含私有凭据，不能整体写入日志。
+ * ```
+ */
+interface DeploymentEnvironment {
+    /** 文件模式（dev/test/prod 或其他合法模式名）。 */
+    environment: string;
+    /** 环境文件的绝对目录。 */
+    envDir: string;
+    /** 合并后的部署变量，可能含私有值，不得直接记录日志。 */
+    values: Record<string, string>;
+    /** 仅目标环境文件显式声明的变量，用于判断能否“保持不变”。 */
+    targetValues: Record<string, string>;
+}
+/**
+ * 按来源归并环境变量；HAI 高层父配置清除旧叶，同层按父→叶处理。
+ * @param layers - 从低到高优先级的环境来源。
+ * @param prefix - 可选变量前缀，仅归并该模块。
+ * @returns 归并后的字面量环境变量，可能包含秘密。
+ * @example 模块内部上下文
+ * ```ts
+ * const env = mergeEnvironmentLayers([{ HAI_CACHE_TYPE: 'memory' }, { HAI_CACHE: '{"type":"redis"}' }])
+ * ```
+ */
+declare function mergeEnvironmentLayers(layers: Array<Record<string, string | undefined>>, prefix?: string): Record<string, string>;
+/**
+ * 按部署环境解析配置；未选择的可选 Provisioner 缺少凭据时保留空值，选择完成后由 Schema 校验。
+ * hai.json 只读取对应的根分区；运行时模块继续读取 YAML。不修改 core 缓存或进程变量。
+ * @param name - 模块配置名，例如 deploy/db/iam
+ * @param path - hai.json 或运行时 YAML 文件的绝对路径
+ * @param values - 已加载的目标环境变量
+ * @returns 配置对象；解析错误已脱敏
+ * @example
+ * ```ts
+ * import { loadDeploymentConfig, loadDeploymentEnvironment } from '@h-ai/deploy'
+ * const environment = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
+ * if (!environment.success) throw new Error(environment.error.message)
+ * const config = loadDeploymentConfig('deploy', `${process.cwd()}/hai.json`, environment.data.values)
+ * if (!config.success) throw new Error(config.error.message)
+ * // 返回对象仍需经 DeployConfigSchema 或 deploy.init 验证。
+ * ```
+ */
+declare function loadDeploymentConfig(name: string, path: string, values: Record<string, string | undefined>): HaiResult<Record<string, unknown>>;
+/**
+ * 加载部署环境；指定环境文件缺失时返回错误并要求用户创建。
+ * 统一按进程 > 模式私有 > 全局私有 > 模式公共 > 基础归并；targetValues 仅记录模式公共项。
+ * @param options - 模式、环境目录与是否强制存在目标文件
+ * @param options.environment - dev/test/prod 或自定义模式
+ * @param options.envDir - 环境文件所在目录
+ * @param options.requireFile - 默认 true；扫描无显式环境时可只读取已有基础文件
+ * @returns 环境快照，可能包含私有值，不得直接输出
+ * @example
+ * ```ts
+ * import { loadDeploymentEnvironment } from '@h-ai/deploy'
+ * const loaded = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
+ * if (!loaded.success) throw new Error(loaded.error.message)
+ * const explicitlyConfigured = loaded.data.targetValues.HAI_DB_TYPE
+ * ```
+ */
+declare function loadDeploymentEnvironment(options: {
+    environment: string;
+    envDir: string;
+    requireFile?: boolean;
+}): HaiResult<DeploymentEnvironment>;
+/**
+ * 保存部署变量：公共值写目标环境文件，凭据写 `.env.<environment>.local`；旧共享私有文件不删除。
+ * 返回实际写入的变量名，调用者只展示名称或脱敏值。
+ * @param environment - 已加载的目标环境快照
+ * @param values - 需要更新的变量；未提供的项保持原状
+ * @param options - private 为 true 时所有值只保存在本机；适用于 SSH 地址、端口及密钥路径
+ * @param options.private - 是否将全部值保存到选中模式的私有文件
+ * @param options.replace - 本次完整替换的配置前缀，只清理该模式中对应项。
+ * @returns 已保存的变量名或脱敏错误
+ * @example
+ * ```ts
+ * import { loadDeploymentEnvironment, saveDeploymentEnvironment } from '@h-ai/deploy'
+ * const loaded = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
+ * if (!loaded.success) throw new Error(loaded.error.message)
+ * const saved = saveDeploymentEnvironment(loaded.data, { HAI_DB_HOST: 'db' })
+ * if (!saved.success) throw new Error(saved.error.message)
+ * // 密钥应以 { private: true } 写入被忽略的 .env.prod.local，不能放公共环境文件。
+ * ```
+ */
+declare function saveDeploymentEnvironment(environment: DeploymentEnvironment, values: Record<string, unknown>, options?: {
+    private?: boolean;
+    replace?: readonly string[];
+}): HaiResult<string[]>;
+
 /**
  * @h-ai/deploy — 部署辅助函数
  *
@@ -1002,7 +1062,7 @@ declare const deploy: DeployFunctions;
  * const message = deployM('deploy_sshRequired')
  * ```
  */
-declare const deployM: (key: "deploy_notInitialized" | "deploy_initFailed" | "deploy_unsupportedProviderType" | "deploy_unsupportedProvisionerType" | "deploy_configTokenRequired" | "deploy_authRequired" | "deploy_authFailed" | "deploy_projectCreateFailed" | "deploy_uploadFailed" | "deploy_deployFailed" | "deploy_provisionFailed" | "deploy_adapterMissing" | "deploy_scanFailed" | "deploy_envVarFailed" | "deploy_credentialError" | "deploy_credentialInvalidKey" | "deploy_credentialSaved" | "deploy_credentialLoaded" | "deploy_configError" | "deploy_credentialMissing" | "deploy_apiError" | "deploy_fileUploadFailed" | "deploy_provisionNoResult" | "deploy_recoveryFailure" | "deploy_recoverySuggestion" | "deploy_commandTimeout" | "deploy_commandFailed" | "deploy_remoteConnectFailed" | "deploy_remoteRuntimeMissing" | "deploy_imageTransferFailed" | "deploy_healthCheckFailed" | "deploy_invalidEnvironment" | "deploy_environmentMissing" | "deploy_environmentReadFailed" | "deploy_environmentWriteFailed" | "deploy_multipleApplications" | "deploy_purposeSqlite" | "deploy_purposeDatabase" | "deploy_purposeMemory" | "deploy_purposeLocal" | "deploy_purposeCache" | "deploy_purposeStorage" | "deploy_purposeVector" | "deploy_purposeDisabled" | "deploy_purposeLdap" | "deploy_purposeConsole" | "deploy_purposeEmail" | "deploy_purposeSms" | "deploy_webProxyInvalid" | "deploy_webBaseConflict" | "deploy_storageProxyInvalid" | "deploy_storagePublicEndpointInvalid" | "deploy_storageBackendRequired" | "deploy_artifactInvalid" | "deploy_sshRequired" | "deploy_sshPasswordInvalid" | "deploy_sshAskpassFailed" | "deploy_sshAskpassCleanupFailed" | "deploy_targetAuth" | "deploy_targetPasswordEnv" | "deploy_bundleInstructions" | "deploy_bundleMetadata" | "deploy_targetHost" | "deploy_targetPort" | "deploy_targetUsername" | "deploy_targetIdentityFile" | "deploy_targetKnownHostsFile" | "deploy_targetStrictHostKeyChecking" | "deploy_targetConnectTimeoutSeconds" | "deploy_targetDirectory" | "deploy_targetBundle" | "deploy_bundleOnlyContainer" | "deploy_selectedContainerOnly" | "deploy_selectionInvalid" | "deploy_imageVersionRequired" | "deploy_bundleRuntimeRequired" | "deploy_bundleFailed" | "deploy_configFileInvalid" | "deploy_configFileUnreadable" | "deploy_bundleNameInvalid" | "deploy_localStopped" | "deploy_localUnknown" | "deploy_localNotStarted" | "deploy_commandOutputFailed" | "deploy_commandInputFailed" | "deploy_commandTreeActive" | "deploy_commandExecutionFailed" | "deploy_remoteUnknown" | "deploy_remoteFinished" | "deploy_bundleDirectoryExists" | "deploy_bundleFull" | "deploy_bundlePartial" | "deploy_bundleSelection" | "deploy_transportBodyLimitInvalid" | "deploy_transportKeyRingInvalid" | "deploy_uploadPasswordPrompt" | "deploy_uploadPasswordUnavailable" | "deploy_uploadPasswordCancelled" | "deploy_uploadPasswordInvalid" | "deploy_managedSecretsInvalid" | "deploy_secretImportFailed" | "deploy_projectNameRequired" | "deploy_projectNameOverrideRemoved" | "deploy_requestAccessInvalid" | "deploy_httpsPortsInvalid" | "deploy_httpsCertificateInvalid" | "deploy_bundleRuntime" | "deploy_bundleHttpOnly" | "deploy_bundleHttps" | "deploy_bundleAcme" | "deploy_bundleAccounts" | "deploy_bundleDirectories", options?: _h_ai_core.MessageOptions) => string;
+declare const deployM: (key: "deploy_notInitialized" | "deploy_initFailed" | "deploy_unsupportedProviderType" | "deploy_unsupportedProvisionerType" | "deploy_configTokenRequired" | "deploy_authRequired" | "deploy_authFailed" | "deploy_projectCreateFailed" | "deploy_uploadFailed" | "deploy_deployFailed" | "deploy_provisionFailed" | "deploy_adapterMissing" | "deploy_scanFailed" | "deploy_envVarFailed" | "deploy_credentialError" | "deploy_credentialInvalidKey" | "deploy_credentialSaved" | "deploy_credentialLoaded" | "deploy_configError" | "deploy_credentialMissing" | "deploy_apiError" | "deploy_fileUploadFailed" | "deploy_provisionNoResult" | "deploy_recoveryFailure" | "deploy_recoverySuggestion" | "deploy_commandTimeout" | "deploy_commandFailed" | "deploy_remoteConnectFailed" | "deploy_remoteRuntimeMissing" | "deploy_imageTransferFailed" | "deploy_healthCheckFailed" | "deploy_invalidEnvironment" | "deploy_environmentMissing" | "deploy_environmentReadFailed" | "deploy_environmentWriteFailed" | "deploy_multipleApplications" | "deploy_purposeSqlite" | "deploy_purposeDatabase" | "deploy_purposeMemory" | "deploy_purposeLocal" | "deploy_purposeCache" | "deploy_purposeStorage" | "deploy_purposeVector" | "deploy_purposeDisabled" | "deploy_purposeLdap" | "deploy_purposeConsole" | "deploy_purposeEmail" | "deploy_purposeSms" | "deploy_webProxyInvalid" | "deploy_webBaseConflict" | "deploy_storageProxyInvalid" | "deploy_storagePublicEndpointInvalid" | "deploy_storageBackendRequired" | "deploy_artifactInvalid" | "deploy_sshRequired" | "deploy_sshPasswordInvalid" | "deploy_sshAskpassFailed" | "deploy_sshAskpassCleanupFailed" | "deploy_targetAuth" | "deploy_targetPasswordEnv" | "deploy_bundleInstructions" | "deploy_bundleMetadata" | "deploy_targetHost" | "deploy_targetPort" | "deploy_targetUsername" | "deploy_targetIdentityFile" | "deploy_targetKnownHostsFile" | "deploy_targetStrictHostKeyChecking" | "deploy_targetConnectTimeoutSeconds" | "deploy_targetDirectory" | "deploy_targetBundle" | "deploy_bundleOnlyContainer" | "deploy_selectedContainerOnly" | "deploy_selectionInvalid" | "deploy_imageVersionRequired" | "deploy_bundleRuntimeRequired" | "deploy_bundleFailed" | "deploy_configFileInvalid" | "deploy_configFileUnreadable" | "deploy_bundleNameInvalid" | "deploy_localStopped" | "deploy_localUnknown" | "deploy_localNotStarted" | "deploy_commandOutputFailed" | "deploy_commandInputFailed" | "deploy_commandTreeActive" | "deploy_commandExecutionFailed" | "deploy_remoteUnknown" | "deploy_remoteFinished" | "deploy_bundleDirectoryExists" | "deploy_bundleFull" | "deploy_bundlePartial" | "deploy_bundleSelection" | "deploy_transportBodyLimitInvalid" | "deploy_transportKeyRingInvalid" | "deploy_uploadPasswordPrompt" | "deploy_uploadPasswordUnavailable" | "deploy_uploadPasswordCancelled" | "deploy_uploadPasswordInvalid" | "deploy_managedSecretsInvalid" | "deploy_secretImportFailed" | "deploy_projectNameRequired" | "deploy_projectNameOverrideRemoved" | "deploy_requestAccessInvalid" | "deploy_httpsPortsInvalid" | "deploy_httpsCertificateInvalid" | "deploy_bundleRuntime" | "deploy_bundleHttpOnly" | "deploy_bundleHttps" | "deploy_bundleAcme" | "deploy_bundleAccounts" | "deploy_bundleDirectories" | "deploy_downloadInvalid" | "deploy_imageSourceMissing" | "deploy_proxySystemUnsupported" | "deploy_middlewareFieldInvalid" | "deploy_s3Engine", options?: _h_ai_core.MessageOptions) => string;
 
 /**
  * 部署中间件的后端与连接字段目录，供扫描、CLI 和容器规划共同使用。
@@ -1027,6 +1087,8 @@ interface MiddlewareField {
     required?: boolean;
     /** 密码输入与私有环境文件写入标记。 */
     secret?: boolean;
+    /** 自建服务会定稿此字段，默认模式允许尚未生成。 */
+    managed?: boolean;
     /** 交互校验类型；端口范围为 1–65535。 */
     kind?: 'port' | 'boolean' | 'number' | 'url';
     /** 数值下限；未声明时为 0。 */
@@ -1051,6 +1113,26 @@ interface MiddlewareBackend {
     purpose: Parameters<typeof deployM>[0];
     /** 云自动开通器；缺失表示不能自动开通该云服务。 */
     provisioner?: 'neon' | 'upstash' | 'cloudflare-r2' | 'resend' | 'aliyun';
+    /** 云凭据字段，由所属开通器 Schema 派生。 */
+    cloudFields?: string[];
+    /** 是否支持容器自动创建；省略为支持。 */
+    containerSupported?: boolean;
+    /** 自建容器的可选实现，配置位置属于 deploy.container。 */
+    containerOptions?: Array<{
+        /** deploy.container 中的字段。 */
+        field: string;
+        /** 对应细项环境变量。 */
+        variable: string;
+        /** 输入提示的消息键。 */
+        purpose: Parameters<typeof deployM>[0];
+        /** 未配置时的选择。 */
+        defaultValue: string;
+        /** 可选实现。 */
+        choices: Array<{
+            label: string; /** 配置值。 */
+            value: string;
+        }>;
+    }>;
     /** 自定义连接需要逐项输入的字段。 */
     fields: MiddlewareField[];
 }
@@ -1078,7 +1160,87 @@ declare const DEPLOY_MIDDLEWARE: Record<ServiceType, MiddlewareBackend[]>;
  * }
  * ```
  */
-declare function describeMiddlewareBackend(backend: MiddlewareBackend): string;
+declare function describeMiddlewareBackend(backend: Pick<MiddlewareBackend, 'purpose'>): string;
+
+/** 中间件表单值与模块配置之间的部署适配；CLI 仅收集输入，不解释模块字段。 */
+
+/**
+ * 判断目标模式是否显式配置了所选连接，凭据可来自更高优先级的私有来源。
+ * @param requirement - 扫描得到的连接需求。
+ * @param backend - 选择的后端及连接字段目录。
+ * @param environment - 合并值与目标文件的原始值。
+ * @returns 目标文件声明后端和必要连接字段时为 true。
+ * @example
+ * ```ts
+ * import { canKeepMiddleware, DEPLOY_MIDDLEWARE } from '@h-ai/deploy'
+ * const keep = canKeepMiddleware({ service: 'cache', backend: 'memory', source: 'cache', configName: 'cache', configPath: [], envPrefix: 'HAI_CACHE', config: {} }, DEPLOY_MIDDLEWARE.cache[0]!, { environment: 'test', envDir: '.', values: {}, targetValues: { HAI_CACHE_TYPE: 'memory' } })
+ * ```
+ */
+declare function canKeepMiddleware(requirement: MiddlewareRequirement, backend: MiddlewareBackend, environment: DeploymentEnvironment): boolean;
+/**
+ * 校验部署连接字段，TLS 复用数据库模块的公开 Schema。
+ * @param options - 原始值、字段定义及实际后端。
+ * @param options.value - 字面输入值。
+ * @param options.field - 已声明的连接字段。
+ * @param options.backend - 实际后端名称。
+ * @returns 输入有效时为 true，不包含输入值或凭据。
+ * @example
+ * ```ts
+ * import { validateMiddlewareField } from '@h-ai/deploy'
+ * const valid = validateMiddlewareField({ value: '5432', field: { name: 'port', kind: 'port' }, backend: 'postgresql' })
+ * ```
+ */
+declare function validateMiddlewareField(options: {
+    value: string;
+    field: MiddlewareField;
+    backend: string;
+}): boolean;
+/**
+ * 将已校验表单值还原为连接字段类型，不进行 dotenv 序列化。
+ * @param options - 输入值、字段和后端。
+ * @param options.value - 字面输入值。
+ * @param options.field - 已声明的连接字段。
+ * @param options.backend - 实际后端名称。
+ * @param options.managed - 默认开通时允许托管秘密尚未生成。
+ * @returns 类型化值或配置错误；空值表示移除该可选字段。
+ * @example
+ * ```ts
+ * import { parseMiddlewareField } from '@h-ai/deploy'
+ * const parsed = parseMiddlewareField({ value: 'false', field: { name: 'secure', kind: 'boolean' }, backend: 'smtp' })
+ * if (!parsed.success) throw new Error(parsed.error.message)
+ * ```
+ */
+declare function parseMiddlewareField(options: {
+    value: string;
+    field: MiddlewareField;
+    backend: string;
+    managed?: boolean;
+}): HaiResult<unknown>;
+/**
+ * 保存选择后的完整连接，声明配置节点并清理该模式中被替换的旧连接字段。
+ * @param environment - 目标环境快照，不修改进程环境。
+ * @param options - 应用目录、扫描需求、后端、可选连接和其他生成项。
+ * @param options.appDir - 应用配置文件所在根目录。
+ * @param options.requirement - 扫描的中间件配置路径。
+ * @param options.backend - 选定的后端。
+ * @param options.configuration - 本次完整连接；云开通前可不提供。
+ * @param options.updates - 同次选择需要保存的其他配置。
+ * @returns 实际写入的变量名；错误不包含配置值。
+ * @example
+ * ```ts
+ * import { loadDeploymentEnvironment, saveMiddlewareEnvironment } from '@h-ai/deploy'
+ * const loaded = loadDeploymentEnvironment({ environment: 'test', envDir: process.cwd() })
+ * if (!loaded.success) throw new Error(loaded.error.message)
+ * const saved = saveMiddlewareEnvironment(loaded.data, { appDir: process.cwd(), requirement: { service: 'cache', backend: 'memory', source: 'cache', configName: 'cache', configPath: [], envPrefix: 'HAI_CACHE', config: {} }, backend: 'memory', configuration: { type: 'memory' } })
+ * ```
+ */
+declare function saveMiddlewareEnvironment(environment: DeploymentEnvironment, options: {
+    appDir: string;
+    requirement: MiddlewareRequirement;
+    backend: string;
+    configuration?: Record<string, unknown>;
+    updates?: Record<string, unknown>;
+}): HaiResult<string[]>;
 
 /**
  * 查看与执行入口相同的扫描、环境、项目身份和制品校验结果。远端 current 只报告为待执行时核验。
@@ -1223,4 +1385,4 @@ declare function importDeploymentSecrets(options: {
     changed: boolean;
 }>>;
 
-export { DEPLOY_MIDDLEWARE, type DeployAppOptions, type DeployCommandState, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, type DeployScanOptions, type DeploymentArtifact, DeploymentArtifactSchema, type DeploymentEnvironment, type DockerSshProviderConfig, HaiDeployError, type MiddlewareBackend, type MiddlewareField, type MiddlewareMode, type MiddlewareRequirement, type PortExposeConfig, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, type SshConfig, artifactChecksum, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, readDeploymentArtifact, saveDeploymentEnvironment };
+export { DEPLOY_MIDDLEWARE, type DeployAppOptions, type DeployCommandState, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, type DeployScanOptions, type DeploymentArtifact, DeploymentArtifactSchema, type DeploymentEnvironment, type DockerSshProviderConfig, type DownloadProxyConfig, HaiDeployError, type ImageSourceConfig, type MiddlewareBackend, type MiddlewareField, type MiddlewareMode, type MiddlewareRequirement, type PortExposeConfig, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, type SshConfig, artifactChecksum, canKeepMiddleware, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, parseMiddlewareField, readDeploymentArtifact, resolveDownloadProxy, resolveImageReference, saveDeploymentEnvironment, saveMiddlewareEnvironment, validateMiddlewareField };