@anov/cic-standard-sdk 0.0.20 → 0.0.21

package/dist/types/manifest/runtime.manifest.d.ts

@@ -0,0 +1,549 @@
+/**
+ * @file runtime.manifest.ts
+ * @description Runtime 供给表（RuntimeManifest）+ 合并结果（ResolvedManifest）+ 报告（ResolutionReport）类型定义
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  职责定位                                                            │
+ * │  本文件是"宿主侧视角"的完整声明，描述运行时环境能提供什么、            │
+ * │  以何种物理形态提供、以及供需匹配后的最终结果。                        │
+ * │                                                                     │
+ * │  依赖关系：                                                          │
+ * │    从 cic.manifest 导入基础枚举与原始类型（单一来源，避免重复定义）    │
+ * │    CICManifest 的类型在 ResolvedManifest 中被引用                   │
+ * └─────────────────────────────────────────────────────────────────────┘
+ *
+ * 导出内容分三组：
+ *   1. 供给表：GlobalBinding / EsmBinding / ProvideEntry / RuntimeManifest
+ *   2. 合并结果：ResolvedManifest / ResolutionReport / ResolutionEntry
+ *   3. 工具类型：LoaderOptions / window 全局扩展
+ */
+import type { CICManifest, EngineMode, EnginePlatform, EngineRuntime, EnvRecord, ImportMap, SemverRange, SemverString, Specifier, UrlPath, WindowPath } from './cic.manifest';
+/**
+ * GlobalBinding 的文件格式声明（描述文件的物理格式）
+ *
+ *   'umd'        —— UMD bundle，可直接用 <script src> 加载，
+ *                   执行后自动挂载到 window（或 CommonJS exports）
+ *   'iife'       —— IIFE bundle，立即执行函数，行为同 umd
+ *   'esm-global' —— ESM 语法的文件，但副作用是挂 window（特殊场景）
+ *                   不能用 <script src>（浏览器拒绝非模块上下文加载 ESM）
+ *                   Loader 自动升级为 blob-script 加载方式
+ *
+ * format → 默认 loadMode 推导规则（resolveLoadMode 函数）：
+ *   'umd' / 'iife'  → 'script'      → <script src>
+ *   'esm-global'    → 'blob-script' → fetch → Blob URL → <script type="module">
+ *
+ * ⚠️ EsmBinding.format 固定为 'esm'，不在此类型中。
+ * ⚠️ 推荐总是显式声明 format，避免 Loader 从文件名猜测（guessFormat 可能误判）。
+ */
+export type GlobalBindingFormat = 'umd' | 'iife' | 'esm-global';
+/**
+ * 加载模式（单依赖级别），可覆盖 format 字段推导的默认值
+ *
+ *   'script'      —— <script src>
+ *                   适用：umd / iife 格式，同步执行，挂 window
+ *   'blob-script' —— fetch 源码 → Blob URL → <script type="module">
+ *                   适用：esm-global 格式，或 shimB 阶段（importMap 未就绪时加载 ESM）
+ *                   ⚠️ 需要 CSP 允许 blob: 来源（script-src 'self' blob:）
+ *                   ⚠️ shimB 阶段此模式失败 → 直接报错，无 import() 回退
+ *   'import'      —— 动态 import(url)，可获取模块导出对象
+ *                   适用：shimA 阶段（globalTask，importMap 已就绪后执行）
+ *                   shimA 阶段 blob-script 失败时可自动回退到 import()
+ *
+ * 优先级：loadMode 显式声明 > format 默认推导 > guessFormat 文件名猜测
+ */
+export type LoadMode = 'script' | 'blob-script' | 'import';
+/**
+ * 全局依赖绑定：依赖以脚本形式加载，执行后挂载到 window
+ *
+ * 使用场景：
+ *   - 宿主平台通过 CDN / 本地 vendor chunk 提供的 UMD 库
+ *   - 需要向 window 挂全局变量供旧版代码（非 ESM）访问
+ *   - 供 shimB 生成 data: URL shim（将 window.X 重新导出为 ESM）
+ *
+ * 典型配置示例（Vue global 形态）：
+ *   {
+ *     window: 'Vue',                              // 挂到 window.Vue
+ *     src: '/anov-dev-runtime/deps/vue.global.js', // 开发模式路径
+ *     prodSrc: null,                               // 生产由宿主注入，Loader 不加载
+ *     format: 'umd',
+ *     loadMode: 'script'
+ *   }
+ */
+export interface GlobalBinding {
+    /**
+     * 挂载到 window 上的属性路径，支持链式（如 'MyLib.Core'）。
+     * Loader 用 getWindowPath(path) 读写，无需 eval。
+     *
+     * shimB 生成时使用此字段：
+     *   const __m = window['Vue']  ← 来自 binding.window
+     */
+    window: WindowPath;
+    /**
+     * 开发模式（mode === 'development'）下的脚本路径。
+     * 通常是本地 devServer 或相对路径。
+     */
+    src: UrlPath;
+    /**
+     * 生产模式（mode !== 'development'）下的脚本路径。
+     *   UrlPath —— 使用此路径加载
+     *   null    —— 生产由宿主环境注入，Loader 不发起加载，
+     *              但会调用 getWindowPath(window) 做存在性校验
+     *   undefined（未填） —— 回退使用 src 字段
+     *
+     * 最佳实践：生产环境由 Nginx/CDN 统一注入时设为 null，
+     *           避免 Loader 重复加载已存在于页面的库。
+     */
+    prodSrc?: UrlPath | null;
+    /**
+     * 文件格式声明。强烈建议显式填写，避免 guessFormat 误判。
+     * 格式 → 默认 loadMode 见 GlobalBindingFormat 注释。
+     */
+    format?: GlobalBindingFormat;
+    /**
+     * 覆盖 format 推导的加载方式（单依赖级别）。
+     * 仅在 format 推导结果不符合预期时填写。
+     *
+     * 常见需求：某个文件扩展名看似 ESM，但实际是副作用挂全局
+     *   format: 'esm-global', loadMode: 'blob-script'  // 通常 format 已蕴含此推导
+     */
+    loadMode?: LoadMode;
+}
+/**
+ * ESM 依赖绑定：依赖注册到 importMap，通过 import specifier 消费
+ *
+ * 使用场景：
+ *   - 现代 ESM 项目，应用代码通过 import { ref } from 'vue' 消费
+ *   - 供 shimA 生成（import() 后挂到 window）
+ *
+ * 典型配置示例（Vue ESM 形态）：
+ *   {
+ *     specifier: 'vue',
+ *     src: '/anov-dev-runtime/deps/vue.esm-browser.js',
+ *     prodSrc: '/anov-prod-runtime/deps/vue.esm-browser.js',
+ *     format: 'esm',
+ *     loadMode: 'import'
+ *   }
+ */
+export interface EsmBinding {
+    /**
+     * 注册到 importMap.imports 的 key（import specifier）。
+     * resolveManifest 会将此 specifier 映射到对应的 URL：
+     *   importMap.imports[specifier] = pickUrl(mode, binding)
+     */
+    specifier: Specifier;
+    /** 开发模式下的 ESM 文件路径 */
+    src: UrlPath;
+    /**
+     * 生产模式下的路径。
+     *   null      —— 生产由宿主 importMap 提供，resolveManifest 不写入 imports
+     *   undefined —— 回退使用 src
+     */
+    prodSrc?: UrlPath | null;
+    /**
+     * 固定为 'esm'，不可变更。
+     * readonly 确保类型安全，防止运行时修改。
+     */
+    readonly format: 'esm';
+    /**
+     * 覆盖默认加载方式（通常不需要填写，保留给特殊场景）。
+     *   shimA 阶段：'import' 是默认且推荐的值
+     *   特殊场景：某些 ESM 文件有副作用但不导出，用 'blob-script' 加载
+     */
+    loadMode?: LoadMode;
+}
+/**
+ * 单依赖的供给形态组合
+ *
+ * 两种都有（最优）：Loader 直连满足所有 consume 需求，无 shim 开销
+ * 只有 global：
+ *   - consume='global' → direct-global（loadScript）
+ *   - consume='esm'    → shimB（loadScript + buildShimB 生成 data: URL）
+ * 只有 esm：
+ *   - consume='esm'    → direct-esm（importMap 直连）
+ *   - consume='global' → shimA（import() 后 setWindowProp）
+ *
+ * ⚠️ 至少声明一种，否则 resolveManifest 抛出错误。
+ */
+export interface ProvideBindings {
+    global?: GlobalBinding;
+    esm?: EsmBinding;
+}
+/**
+ * 依赖的导出接口声明（仅 shimB 场景需要）
+ *
+ * shimB 生成的 data: URL shim 代码结构：
+ *   const __m = window['Vue']         ← 从 window 读取全局对象
+ *   export default __m                ← 当 default=true 时生成
+ *   export const { ref, reactive } = __m  ← 来自 named 列表
+ *
+ * 若不填此字段（exports=undefined 或 named=[]）：
+ *   - shim 只有 default export
+ *   - import { ref } from 'vue' → ref 为 undefined（静默失败！）
+ *   - Loader 会发出 warning，但不中止流程
+ *
+ * 建议：对所有可能走 shimB 的依赖（只有 global binding），
+ *       务必声明完整的 exports.named 列表。
+ */
+export interface ExportsDeclaration {
+    /**
+     * 具名导出列表，用于生成：
+     *   export const { ref, reactive, computed, ... } = __m
+     *
+     * 应包含应用代码实际用到的所有具名导出，
+     * 不需要覆盖全部导出，只覆盖用到的即可（减少 shim 体积）。
+     */
+    named: string[];
+    /**
+     * 是否有 default export，用于生成：
+     *   export default __m
+     *
+     * 注意：pinia 没有 default export（default=false），
+     *       若设为 true 会导致 import Pinia from 'pinia' 异常。
+     */
+    default: boolean;
+}
+/**
+ * 单依赖的完整供给描述（RuntimeManifest.provides 的值类型）
+ *
+ * 设计意图：
+ *   供给表只声明"我有什么"，不关心消费方"要什么"。
+ *   Loader 在 resolveManifest 时将供给 × 需求做笛卡尔积匹配。
+ */
+export interface ProvideEntry {
+    /**
+     * 实际提供的版本号（semver string，具体值，非范围）。
+     * resolveManifest 用 checkVersion(provided.version, ext.version) 校验。
+     *
+     * 示例：'3.4.21'（正确）
+     *       '^3.0.0'（错误，此处不接受范围）
+     */
+    version: SemverString;
+    /**
+     * 导出接口声明（shimB 场景必填）。
+     *
+     * 若该依赖只有 global binding，且有 esm 消费需求，
+     * 必须填写此字段，否则生成的 shim 缺少具名导出。
+     *
+     * 若两种 binding 都有（direct 路径），此字段可不填。
+     */
+    exports?: ExportsDeclaration;
+    /**
+     * 供给形态，至少声明一种。
+     * 两种都有是"理想态"，性能最优，无 shim 开销。
+     * 只有一种时，Loader 自动生成对应 shim（shimA 或 shimB）。
+     */
+    bindings: ProvideBindings;
+}
+/**
+ * Runtime 供给清单（宿主侧，由平台运维/构建工具维护）
+ *
+ * 字段分组：
+ *   version    —— manifest 格式版本，用于 Loader 兼容判断
+ *   engine     —— 宿主运行时能力描述（平台/框架/版本/模式）
+ *   provides   —— 依赖供给表（核心：宿主能提供什么）
+ *   importMap  —— 基础路径前缀映射（cdn/ 等）
+ *   env        —— 默认环境变量（可被 cic.env 覆盖）
+ *   preload    —— 运行时核心 chunk 预加载列表
+ *   entry      —— 默认应用入口模块路径
+ *   extensions —— 业务扩展字段
+ *
+ * 生命周期：
+ *   由 manifest-loader 在页面启动时 fetch，
+ *   与 cic.manifest 一起传入 resolveManifest()，
+ *   结果写入 window.__MANIFEST__。
+ */
+export interface RuntimeManifest {
+    /**
+     * manifest 格式版本（semver），供 Loader 做格式兼容判断。
+     * 当前稳定版本：'2.0.0'
+     */
+    version: SemverString;
+    /**
+     * 宿主运行时能力描述
+     */
+    engine: {
+        platform: EnginePlatform;
+        runtime: EngineRuntime;
+        /**
+         * 宿主提供的框架实际版本（semver string）。
+         * resolveManifest 用此版本与 cic.modules.requires[].version 校验。
+         * 强烈建议填写，未填则所有版本校验结果为 'unknown'。
+         */
+        version: SemverString;
+        /**
+         * 运行模式，决定 Loader 选 binding.src 还是 binding.prodSrc。
+         *   development → 使用 src（本地/devServer 路径）
+         *   production  → 使用 prodSrc（CDN / 部署路径）
+         *   staging     → 使用 prodSrc，但可开启额外日志
+         *
+         * ⚠️ 可选（?），但不填时 Loader 默认按 'development' 处理（使用 src），
+         *    生产部署时务必设置为 'production'，否则会加载开发服务器路径。
+         */
+        mode?: EngineMode;
+        /**
+         * 开发服务器基础 URL（仅 development 模式有效）。
+         * 用于将相对路径转换为绝对 URL（适配 devServer proxy）。
+         * 区别于 CICManifest.modules.baseURL（应用模块路径前缀）。
+         *
+         * 示例：'http://localhost:5173'
+         */
+        devServerURL?: string;
+    };
+    /**
+     * 依赖供给表（宿主能提供的所有依赖）
+     * key：依赖 id，通常与 npm 包名一致（如 'vue' '@anov/charts'）
+     * value：依赖的版本 + 导出声明 + 供给形态
+     *
+     * resolveManifest 遍历 cic.modules.requires，对每条 external：
+     *   1. 查找 provides[external.id]
+     *   2. 若不存在 → host-injected 检查
+     *   3. 若存在 → 版本校验 → 供需匹配 → 决策 strategy
+     */
+    provides: Record<string, ProvideEntry>;
+    /**
+     * 基础 importMap（路径前缀 / 全局别名映射）。
+     * 不直接承载具体依赖的 specifier 映射（由供需匹配动态生成）。
+     *
+     * 典型用途：
+     *   { 'cdn/': '/anov-prod/mgt/ui/' }  → 路径前缀映射
+     *   { '@/': '/src/' }                 → 开发别名（通常由 cic.modules.alias 处理）
+     *
+     * 合并优先级（最低）：此字段被供需生成映射和 cic 显式映射覆盖。
+     */
+    importMap?: ImportMap;
+    /**
+     * 默认环境变量（可被 CICManifest.env 覆盖同名字段）。
+     * 合并结果写入 window.__ENV__ 和 ResolvedManifest.env。
+     *
+     * 示例：{ NODE_ENV: 'development', APP_NAME: 'CIC Runtime', ENABLE_DEVTOOLS: true }
+     */
+    env?: EnvRecord;
+    /**
+     * importMap 注入后需要预加载的模块路径列表（运行时核心 chunk）。
+     *
+     * ⚠️ 重要：不能写在 HTML 的 <link rel="modulepreload"> 里！
+     *    原因：HTML 解析阶段触发 modulepreload 时 importMap 尚未注入，
+     *          module graph 解析 specifier 失败。
+     *    正确做法：由 manifest-loader 在 injectImportMap() 之后动态插入。
+     *
+     * 与 cic.modules.preload 合并去重后，统一由 Loader 的
+     * injectModulePreloads() 插入 <link rel="modulepreload">。
+     */
+    preload?: UrlPath[];
+    /**
+     * 默认应用入口模块路径，可被 CICManifest.entry（如果存在）覆盖。
+     *
+     * 入口加载失败语义：
+     *   - 触发 CustomEvent('manifest:error')
+     *   - 中止流程，不重试，不走 fallback
+     *   - 两者均未填 → resolveManifest 后 Loader 抛出错误
+     */
+    entry?: UrlPath;
+    /** 预留扩展，Loader 不处理，原样透传到 ResolvedManifest.runtime.extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * 供需匹配决策结果枚举
+ *
+ * 每条 CICRequires 经过 resolveManifest 后得到唯一一个 strategy：
+ *
+ *   direct-esm     供给有 esm binding，消费需求含 'esm'
+ *                  → importMap.imports[specifier] = esm.src
+ *
+ *   direct-global  供给有 global binding，消费需求含 'global'
+ *                  → Loader 调用 loadByFormat(global.src) 挂 window
+ *
+ *   shimA          供给只有 esm binding，消费需求含 'global'
+ *                  → importMap 注入后，import(esm.src) 结果挂到 window.X
+ *                  → CSP 失败时自动回退 import()（importMap 已就绪）
+ *
+ *   shimB          供给只有 global binding，消费需求含 'esm'
+ *                  → 先加载 global script，再生成 data: URL ESM shim
+ *                  → shimB 必须在 importMap 注入前完成（data: URL 在此阶段确定）
+ *                  → CSP 失败直接报错（无回退路径）
+ *
+ *   host-injected  runtime.provides 无记录，但 window.X 存在性校验通过
+ *                  → 假定宿主通过其他方式（HTML script / 框架注入）提供
+ *                  → 记录 warning，不生成任何 importMap 条目
+ *
+ *   skipped        required=false 且失败（版本不满足/加载失败/宿主未注入）
+ *                  → 跳过此依赖，记录 warning，继续执行
+ */
+export type ResolutionStrategy = 'direct-esm' | 'direct-global' | 'shimA' | 'shimB' | 'host-injected' | 'skipped';
+/**
+ * 版本校验三态结果
+ *
+ *   'yes'     provides[id].version 满足 external.version 范围
+ *   'no'      不满足；required=true 时中止，required=false 时 skipped
+ *   'unknown' version 字段缺失，或 semver 解析失败，无法判断
+ *             → host-injected 场景下固定为 'unknown'（无供给版本可比较）
+ */
+export type VersionSatisfied = 'yes' | 'no' | 'unknown';
+/**
+ * 单依赖的供需匹配结果记录
+ *
+ * 用途：
+ *   - 开发调试：在 window.__MANIFEST__.report.entries 中查看每个依赖的决策过程
+ *   - 性能监控：统计 shim 路径数量（shim 比 direct 有额外开销）
+ *   - 版本告警：过滤 versionSatisfied='no' 的条目上报监控
+ */
+export interface ResolutionEntry {
+    /** 依赖 id，对应 CICRequires.id 和 RuntimeManifest.provides 的 key */
+    id: string;
+    /**
+     * 供需匹配决策结果。
+     * 决定 Loader 实际执行的加载/shim 路径，详见 ResolutionStrategy 注释。
+     */
+    strategy: ResolutionStrategy;
+    /** 供给方实际版本（来自 provides[id].version），host-injected/skipped 时为 undefined */
+    providedVersion?: SemverString;
+    /** 需求方版本范围（来自 CICRequires.version），未声明时为 undefined */
+    requiredVersion?: SemverRange;
+    /** 版本校验三态结果，详见 VersionSatisfied 注释 */
+    versionSatisfied: VersionSatisfied;
+    /**
+     * ESM 场景：最终注册到 importMap.imports 的 specifier。
+     * strategy 为 direct-esm / shimB / shimA 时填充。
+     */
+    finalSpecifier?: Specifier;
+    /**
+     * global 场景：最终挂载到 window 的属性路径。
+     * strategy 为 direct-global / shimA / host-injected 时填充。
+     */
+    finalWindowKey?: WindowPath;
+    /**
+     * 最终解析到的 URL（物理路径或 data: URL）。
+     *   direct-esm    → esm.src 或 esm.prodSrc
+     *   direct-global → global.src 或 global.prodSrc
+     *   shimB         → data:text/javascript,... （生成的 shim）
+     *   shimA         → esm.src（import() 的目标）
+     */
+    finalUrl?: string;
+    /**
+     * 本条目产生的所有警告信息列表。
+     * 常见警告：
+     *   - "版本不满足但 required=false，已跳过"
+     *   - "exports.named 未声明，shimB 只有 default export"
+     *   - "runtime 无供给记录，按 host-injected 处理"
+     */
+    warnings: string[];
+}
+/**
+ * 本次 resolveManifest 过程的汇总报告
+ *
+ * 始终生成，写入 ResolvedManifest.report 和 window.__MANIFEST__.report。
+ * 调用方可通过 await window.__manifestReady 获取完整报告。
+ */
+export interface ResolutionReport {
+    /** ISO 8601 时间戳，如 "2026-03-23T08:00:00.000Z" */
+    timestamp: string;
+    /**
+     * 本次运行的引擎模式（来自 RuntimeManifest.engine.mode）。
+     * 用于区分开发/生产环境下的报告差异。
+     */
+    mode: EngineMode;
+    /** 所有 CICRequires 条目的匹配结果列表（顺序与 cic.modules.requires 一致） */
+    entries: ResolutionEntry[];
+    /**
+     * 最终注入到页面的 importMap.imports 条目数量。
+     * 包含：runtime 基础映射 + 供需生成映射 + alias 展开 + cic 显式映射
+     */
+    importMapSize: number;
+    /**
+     * 最终注入的 modulepreload 数量（runtime.preload + cic.modules.preload 去重后）。
+     * 用于监控预加载策略的覆盖范围。
+     */
+    preloadCount: number;
+}
+/**
+ * resolveManifest() 的输出，Loader 将其写入 window.__MANIFEST__
+ *
+ * importMap 合并优先级（低 → 高）：
+ *   runtime.importMap.imports（基础前缀）
+ *     < 供需匹配生成（direct-esm URL + shimB data: URL）
+ *     < alias 展开（cic.modules.alias → imports）
+ *     < cic.modules.importMap.imports（应用显式，最高优先级）
+ *
+ * scopes 深度合并（mergeScopes 函数，非 spread 整体覆盖）：
+ *   同 scope key 下的 imports 按 key 级覆盖
+ *
+ * env 合并：{ ...runtime.env, ...cic.env }（cic 覆盖 runtime 同名字段）
+ */
+export interface ResolvedManifest {
+    /** 原始供给表（未修改，原样保留供调试用） */
+    runtime: RuntimeManifest;
+    /** 原始需求表（未修改，原样保留供调试用） */
+    cic: CICManifest;
+    /**
+     * 三方合并后的完整 importMap（含 scopes）。
+     * Loader 将此结构注入为 <script type="importmap">。
+     */
+    importMap: ImportMap;
+    /**
+     * 合并后的环境变量。
+     * 同步写入 window.__ENV__，可直接通过 window.__ENV__.API_BASE_URL 访问。
+     */
+    env: EnvRecord;
+    /**
+     * 供需匹配过程报告，始终生成。
+     * 用于调试、监控和验收。
+     * 访问方式：window.__MANIFEST__.report 或 const { report } = await window.__manifestReady
+     */
+    report: ResolutionReport;
+}
+/**
+ * manifest-loader 初始化选项（传入 createManifestLoader）
+ *
+ * 所有字段均可选，提供合理默认值，零配置开箱即用。
+ */
+export interface LoaderOptions {
+    /** runtime.manifest.json 的 URL，默认 './runtime.manifest.json' */
+    runtimeUrl?: string;
+    /** cic.manifest.json 的 URL，默认 './cic.manifest.json' */
+    cicUrl?: string;
+    /**
+     * 单个任务网络加载的最大重试次数，默认 1（允许一次重试）。
+     * 重试粒度：单个 script / import() 加载（非整个 Adapter 生命周期阶段）。
+     * 0 表示不重试，直接报错。
+     *
+     * ⚠️ entry 加载失败不受此选项影响，直接触发 manifest:error，不重试。
+     */
+    maxRetries?: number;
+}
+/**
+ * RuntimeManifest 完整配置示例
+ *
+ * 场景说明：
+ *   - vue 同时提供 esm + global（两种都有，理想态，无 shim 开销）
+ *   - @anov/charts 只有 esm（新内部库，只支持 ESM）
+ *   - echarts 只有 global（老版本，只有 UMD，通过 CDN 加载）
+ *     → 若应用 consume='esm'，Loader 自动走 shimB 路径
+ */
+export declare const RuntimeManifestExample: RuntimeManifest;
+declare global {
+    interface Window {
+        /**
+         * Loader 完成后可 await 的 Promise，resolve 值为 ResolvedManifest。
+         *
+         * 使用方式：
+         *   const manifest = await window.__manifestReady
+         *   // 此时 importMap 已注入，所有 external 依赖已就绪
+         *
+         * 注意：在 src/main.js 中无需 await，因为 main.js 本身由
+         *       manifest-loader 在 Promise resolve 后 import()，
+         *       执行到 main.js 时 __MANIFEST__ 已经可以同步访问。
+         */
+        __manifestReady: Promise<ResolvedManifest>;
+        /**
+         * Loader 完成后写入的完整解析结果（同步可访问）。
+         * 在 manifest:ready 事件触发后即可使用。
+         */
+        __MANIFEST__: ResolvedManifest;
+        /**
+         * 合并后的环境变量（等同于 __MANIFEST__.env）。
+         * 独立提取为顶层字段，方便业务代码直接访问：
+         *   const { API_BASE_URL } = window.__ENV__
+         */
+        __ENV__: EnvRecord;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anov/cic-standard-sdk",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "CIC Standard SDK with TypeScript support",
   "main": "dist/cic-sdk.cjs.js",
   "module": "dist/cic-sdk.es.js",