@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/dist/miniapp-publish.esm.js

@@ -2783,7 +2783,58 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+/** 单个小程序版本最多声明的关联游戏数量。 */
 const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+/**
+ * 校验并规范化小程序关联的游戏 App ID。
+ *
+ * @param value - 不可信声明。`undefined` 和 `[]` 均返回空绑定；其他值必须是最多 20 项的
+ * 字符串数组，不接受 `null`、单个字符串、number 数组或类数组对象。
+ * @param options - 可选诊断来源；`sourceLabel` 默认 `package.json#heybox.bindAppIds`，并原样
+ * 作为所有错误消息的前缀。
+ * @returns 新建、按 appid 数值升序排列且经 `Object.freeze` 冻结的 `readonly string[]`。
+ * 输入数组及其顺序不会被修改；空输入也返回新的冻结空数组。
+ * @throws `Error` `${sourceLabel} 必须是字符串数组`：`value` 不是数组。
+ * @throws `Error` `${sourceLabel} 最多包含 20 个游戏 appid`：输入数组超过 20 项；数量检查
+ * 先于逐项格式检查。
+ * @throws `Error` `${sourceLabel} 包含非法游戏 appid：<value>`：任一项不是 string，或不匹配
+ * `/^[1-9]\d*$/`。因此空串、首尾空白、`0`、前导零、正负号、小数、指数和非十进制字符
+ * 都不会被自动修正。
+ * @throws `Error` `${sourceLabel} 包含超出正 int32 范围的游戏 appid：<value>`：十进制值
+ * 大于 `2147483647` 或不能成为安全整数。
+ * @throws `Error` `${sourceLabel} 包含重复游戏 appid：<value>`：规范字符串在同一数组重复。
+ *
+ * @remarks
+ * 合法范围是闭区间 `1..2147483647`，每项在输出中仍保持十进制 string。排序按数值而不是
+ * 字典序执行，所以 `['3513350', '730', '10']` 输出为 `['10', '730', '3513350']`。
+ * 函数先复制后排序并冻结结果，不排序或冻结调用方传入的数组。
+ *
+ * 这是同步、纯离线的格式规范化函数，不访问网络，也不确认 appid 是否真实存在、可绑定或
+ * 属于当前开发者。`miniappManifest()` 用它校验 `package.json#heybox.bindAppIds` 并把非空结果
+ * 写入 Manifest；远端 deploy 预检和提审才校验游戏可用性。缺失和空数组在普通构建中都表示
+ * 无绑定，函数本身不处理 `remote deploy --from-version` 的历史快照继承语义。
+ *
+ * `bindAppIds` 是版本发布元数据，不是 Runtime 权限，也不会因调用
+ * [navigation.openAppPage](/reference/sdk/navigation/openAppPage) 而变化。后者的 `appId` 是一次
+ * 页面导航参数，允许 string 或 number、只要求字符串化后非空，不适用本函数的数组、int32、
+ * 前导零、去重、20 项或排序规则。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniappBindAppIds } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const declared = ['3513350', '730', '10']
+ * const appIds = parseMiniappBindAppIds(declared)
+ *
+ * console.log(appIds) // ['10', '730', '3513350']
+ * console.log(declared) // ['3513350', '730', '10']，输入顺序不变
+ * console.log(Object.isFrozen(appIds)) // true
+ * ```
+ *
+ * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ * @see [CLI 与远端发布](/guide/cli#生产构建)
+ */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
     if (value === undefined)
@@ -2812,6 +2863,11 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/**
+ * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
+ *
+ * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
+ */
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 /** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
 const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = '0.9.0';
@@ -2823,6 +2879,49 @@ const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = '0.9.0';
  * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
  */
 const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
+/**
+ * 判断小程序版本是否符合公开 Manifest 版本规则。
+ *
+ * @param version - 待判断的 `package.json.version` / Manifest 版本字符串；首尾空白会先被
+ * 移除，但函数不会把规范化后的字符串返回给调用方。
+ * @returns trim 后满足小程序严格版本规则时返回 `true`，否则返回 `false`。对类型声明允许的
+ * 字符串输入，该函数只返回布尔值，不抛出校验错误。
+ *
+ * @remarks
+ * 接受形式为 canonical SemVer `MAJOR.MINOR.PATCH[-PRERELEASE]`。trim 后的输入必须与
+ * `semver` 严格解析得到的 `version` 完全相同，因此不完整版本（如 `1.2`）、`v` / `=`
+ * 前缀、范围表达式、额外段，以及 major/minor/patch 或纯数字 prerelease 标识中的前导零
+ * 都返回 `false`。只有首尾空白会被忽略，内部空白不会被修复。
+ *
+ * 合法 prerelease（如 `1.2.3-alpha.1`、`0.0.1-rc.0`）可以使用。build metadata 即使符合
+ * 标准 SemVer（如 `1.2.3+build.1`）也被小程序发布合同显式禁止。模板占位 core
+ * `0.0.0` 同样禁止，包括 `0.0.0-alpha` 等 prerelease；至少应提升 patch/minor/major
+ * 之一，例如 `0.0.1-alpha.1`。
+ *
+ * 这是无 I/O、无状态修改的 predicate，适合表单即时判断。实际 Vite / `hb-sdk build`
+ * 流程会调用同规则的 package version validator：成功时返回 trim 后版本并写入 Manifest，
+ * 失败时抛出带 `package.json.version` 来源的错误；调用本函数为 `true` 不能跳过正式构建。
+ *
+ * {@link resolveMiniappManifestPlatforms} 处理的是 Manifest `sdkVersion` 对平台声明策略的
+ * SemVer precedence，不是当前小程序的发布 `version`。不要用本函数替代平台解析，也不要
+ * 把项目 version 当作 sdkVersion 传入。
+ *
+ * @example
+ * ```ts
+ * import { isValidVersion } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * isValidVersion(' 1.2.3 ') // true
+ * isValidVersion('1.2.3-alpha.1') // true
+ * isValidVersion('0.0.1-alpha.1') // true
+ * isValidVersion('1.2') // false
+ * isValidVersion('v1.2.3') // false
+ * isValidVersion('1.2.3+build.1') // false
+ * isValidVersion('0.0.0-alpha') // false
+ * ```
+ *
+ * @see {@link resolveMiniappManifestPlatforms}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
+ */
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
 }
@@ -2847,18 +2946,67 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
 /**
  * 解析 Manifest 平台声明，是 `0.9.0` 硬切规则的唯一实现。
  *
+ * @param sdkVersion - 产物写入 Manifest 的 hb-sdk 版本，不是小程序自身的发布 version。
+ * `undefined`、空字符串和纯空白按历史“缺失 sdkVersion”处理；其他字符串会先 trim，再按
+ * canonical strict SemVer 校验并参与 precedence 比较。
+ * @param manifest - 待解析的不可信 Manifest。必须是非 `null`、非数组的对象；函数只读取其
+ * 自有 `platforms` 字段，其他字段不参与平台解析。
+ * @returns 冻结的 {@link MiniappPlatformResolution}。显式声明返回规范排序后的 declared /
+ * effective；历史兼容返回空 declared 与 Android/iOS/OHOS effective。
+ * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
+ * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
+ * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
+ *
  * @remarks
- * 规则与后端领域层保持一致：
- * - 无 `platforms` 字段：`sdkVersion` 缺失或 SemVer precedence 低于
- *   `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION` 时按历史移动端兼容；达到或高于硬切点即非法。
- * - 有 `platforms` 字段：复用 `validateMiniappPlatforms` 校验并规范化顺序；任何非法值
- *   （空数组、非数组、未知值、重复值）都不回退到历史兼容，即使 `sdkVersion < 0.9.0`。
- * - 任何非法的 `sdkVersion` 都会抛出，不做字符串比较。
- * @param sdkVersion - 产物 hb-sdk 版本；历史产物可能缺失。
- * @param manifest - 待解析的 Manifest（不可信输入）。
- * @returns 冻结的平台解析结果。
- * @throws Manifest 不是对象、`sdkVersion` 不是合法 SemVer、达到硬切点仍缺失 `platforms`，
- *   或 `platforms` 声明非法时抛出。
+ * 解析顺序与后端领域层保持一致：先校验 Manifest 对象，再处理 sdkVersion；只要非空
+ * sdkVersion 非法，即使存在合法 platforms 也会抛出，不会忽略版本。版本比较使用 SemVer
+ * precedence，不做字符串比较：`0.9.0-alpha.1 < 0.9.0`，而 `0.10.0 > 0.9.0`。
+ *
+ * Manifest 拥有 `platforms` 字段时总是走 `explicit`：字段必须是非空数组，每项必须属于
+ * `MINIAPP_PLATFORM_VALUES` 且不能重复；结果按固定平台词表排序，而不是保留输入顺序。
+ * 该规则与 sdkVersion 是否缺失、低于或达到硬切点无关。显式声明一旦非法绝不回退到
+ * legacy 默认值。
+ *
+ * Manifest 完全没有 `platforms` 字段时才判断硬切：sdkVersion 缺失/空白，或 precedence
+ * 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`（`0.9.0`）时返回
+ * `legacy_mobile_default`；`0.9.0` 稳定版及更高版本直接抛错。`0.9.0-*` prerelease 仍低于
+ * 稳定硬切点，因此可解析历史缺失声明。
+ *
+ * 返回对象被 `Object.freeze()`；显式声明数组和 legacy 的空 declared 数组也被冻结。所有
+ * 数组均以 readonly 合同暴露，调用方应直接消费 `effective`，不得再比较版本或补默认值。
+ *
+ * 当前 Vite 构建入口
+ * {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
+ * 会从 `package.json#heybox.platforms` 读取并写入显式声明；legacy 分支只用于解析缺少字段
+ * 的历史产物，不是新项目省略 platforms 的许可。
+ *
+ * {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
+ * 判断的是小程序发布 `version`，并额外拒绝模板值 `0.0.0`；本函数的 sdkVersion 是 hb-sdk
+ * 版本，`0.0.0` 本身是可比较的 strict SemVer 并低于硬切点。两类版本不能互换校验。
+ *
+ * @example
+ * ```ts
+ * import { resolveMiniappManifestPlatforms } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const explicit = resolveMiniappManifestPlatforms('0.9.0', {
+ *   platforms: ['linux', 'android', 'macos'],
+ * })
+ * console.log(explicit)
+ * // {
+ * //   declared: ['android', 'macos', 'linux'],
+ * //   effective: ['android', 'macos', 'linux'],
+ * //   platformsDeclared: true,
+ * //   policy: 'explicit'
+ * // }
+ *
+ * const legacy = resolveMiniappManifestPlatforms('0.9.0-alpha.1', {})
+ * console.log(legacy.effective) // ['android', 'ios', 'ohos']
+ * ```
+ *
+ * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
+ * @see {@link MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
  */
 function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
     if (!isRecord$1(manifest)) {
@@ -2921,33 +3069,59 @@ function getMiniappManifestVersionError(version) {
     return undefined;
 }
 
+/** CDN 上传接口使用的小程序产物业务 scope。 */
 const MINIAPP_UPLOAD_SCOPE = 'activity';
+/** 完整 CDN 上传 key 的默认长度上限；旧固定版本流程按字符计数，上传会话流程按 UTF-8 bytes 计数。 */
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+/** 单次向 CDN 申请上传信息时包含的最大文件数；当前合同固定为 `50`。 */
 const MINIAPP_UPLOAD_BATCH_SIZE = 50;
+/** Web 构建产物的默认总大小上限，单位为 bytes；当前为 100 MiB。 */
 const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES = 100 * 1024 * 1024;
-/** 与 Activity 上传后端合同一致的 Companion 归档总大小上限。 */
+/** Companion 归档的临时总大小上限，单位为 bytes；当前为 500 MiB。 */
 const MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES = 500 * 1024 * 1024;
+/** 查询当前开发者账号是否具备小程序访问资格的开放平台 API 路径。 */
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
+/** 查询当前开发者可管理主体列表的开放平台 API 路径。 */
 const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
+/** 切换当前开发者主体的开放平台 API 路径。 */
 const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
+/** 查询当前主体下小程序列表的开放平台 API 路径。 */
 const LIST_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/list';
+/** 创建小程序的开放平台 API 路径。 */
 const CREATE_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/create';
+/** 查询单个小程序详情的开放平台 API 路径。 */
 const DETAIL_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/detail';
+/** 创建本地开发启动凭据的开放平台 API 路径。 */
 const CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH = '/mall/developer/user_miniprogram/local_dev_launch_token';
+/** 查询小程序预览白名单的开放平台 API 路径。 */
 const USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = '/mall/developer/user_miniprogram/preview_allowlist';
+/** 更新小程序预览白名单的开放平台 API 路径。 */
 const UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = '/mall/developer/user_miniprogram/preview_allowlist/update';
+/** 创建小程序云排行榜的开放平台 API 路径。 */
 const CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/create';
+/** 查询单个小程序云排行榜详情的开放平台 API 路径。 */
 const DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/detail';
+/** 查询小程序云排行榜列表的开放平台 API 路径。 */
 const LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/list';
+/** 删除小程序云排行榜的开放平台 API 路径。 */
 const DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/delete';
+/** 在上传或复用版本前执行发布预检的开放平台 API 路径。 */
 const PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/precheck';
+/** 将小程序版本提交审核的开放平台 API 路径。 */
 const SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = '/mall/developer/user_miniprogram/version/submit_audit';
+/** 查询小程序版本预览信息的开放平台 API 路径。 */
 const USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = '/mall/developer/user_miniprogram/version/preview_info';
+/** 撤回待审核小程序版本的开放平台 API 路径。 */
 const WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/withdraw';
+/** 发布审核通过的小程序版本的开放平台 API 路径。 */
 const RELEASE_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/release';
+/** 下架当前线上小程序的开放平台 API 路径。 */
 const TAKE_DOWN_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/take_down';
+/** 重新开放已下架小程序的开放平台 API 路径。 */
 const REOPEN_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/reopen';
+/** 更新小程序广场展示状态的开放平台 API 路径。 */
 const UPDATE_SQUARE_DISPLAY_API_PATH = '/mall/developer/user_miniprogram/square_display/update';
+/** 查询小程序历史版本列表的开放平台 API 路径。 */
 const LIST_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/list';
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
@@ -2955,17 +3129,114 @@ const MINIAPP_UPLOAD_SESSION_REF_LENGTH = 10;
 const MINIAPP_ARTIFACT_SIGNATURE_MAGIC = 'heybox-user-miniprogram-artifact\0v1\0';
 const UNPAIRED_SURROGATE_PATTERN = /[\ud800-\udbff](?![\udc00-\udfff])|(^|[^\ud800-\udbff])[\udc00-\udfff]/;
 const textEncoder = new TextEncoder();
+/**
+ * 将扫描到的相对路径转换为统一的 `/` 分隔形式。
+ *
+ * @param relativePath - 待整理的构建产物路径。TypeScript 入口声明为字符串；JavaScript 运行时会
+ * 先计算 `relativePath || ''`，再通过 `String(...)` 强制转换。
+ * @returns 仅统一分隔符形态的新字符串：所有 `\\` 转为 `/`，所有前导 `/` 被删除，其余连续
+ * `/` 合并为一个。空字符串以及运行时传入的 `undefined`、`null`、`false`、`0`、`NaN` 等
+ * falsy 值返回 `''`；truthy 非字符串按标准 `String(value)` 结果继续整理。
+ *
+ * @remarks
+ * 这是面向 build/deploy 文件扫描结果的**格式 helper**，不是路径安全校验或 canonical path
+ * parser。它不会 trim、URL decode、Unicode normalize、解析盘符，也不会拒绝或消解 `.` / `..`
+ * segment、控制字符、Windows drive prefix 或尾随 `/`。例如 `/etc/passwd` 会变成
+ * `etc/passwd`，`C:\\temp\\app.js` 会变成 `C:/temp/app.js`，`assets/../secret/` 仍保留点段
+ * 和尾随 slash；调用方不能根据返回值推断原输入是安全相对路径。
+ *
+ * SDK 的 build/deploy 流程会把扫描路径先用本函数统一分隔符，再分别使用
+ * {@link relativePathContainsNodeModulesSegment} 排除完整 `node_modules` 目录段、用
+ * {@link shouldUploadDistFile} 过滤根 `manifest.json` / `.DS_Store` / source map。`hb-sdk build`
+ * 随后校验大小预算；`hb-sdk remote deploy` 还会在签名和上传前通过
+ * `validateUploadPaths()`、`prepareMiniappArtifactFiles()` 或
+ * `validateMiniappUploadPathLengths()` 执行真正的空路径、点段、控制字符、重复和长度校验。
+ * 这些步骤不能由本函数单独替代；`shouldUploadDistFile()` 也不会自行检查 `node_modules`。
+ *
+ * 不要把本函数与 `@heybox/hb-sdk/protocol` 的 `isMiniProgramRelativePath()` 混用：协议 guard
+ * 不做转换，只接受已经规范的非空字符串，并拒绝前导/尾随 `/`、反斜杠、空 segment、`.`、
+ * `..` 与控制字符；本函数则会改写部分非法形态并保留其余不安全内容。
+ *
+ * @example
+ * ```ts
+ * import { normalizeRelativePath } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * normalizeRelativePath('///dist\\assets//app.js'); // 'dist/assets/app.js'
+ * normalizeRelativePath('assets/../secret///'); // 'assets/../secret/'，仍需安全校验
+ * normalizeRelativePath(123 as unknown as string); // '123'，JavaScript 运行时强制转换
+ * normalizeRelativePath(0 as unknown as string); // ''，falsy 值先回退为空串
+ * ```
+ *
+ * @see {@link relativePathContainsNodeModulesSegment}
+ * @see {@link shouldUploadDistFile}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/protocol/functions/isMiniProgramRelativePath | isMiniProgramRelativePath}
+ */
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
         .replace(/^\/+/, '')
         .replace(/\/+/g, '/');
 }
+/**
+ * 判断路径中是否包含大小写不敏感的完整 `node_modules` 目录段。
+ *
+ * @param relativePath - 待检查的构建产物路径。函数先通过 {@link normalizeRelativePath} 把
+ * 反斜杠改为 `/`、删除前导 `/` 并合并连续 `/`，再按 `/` 分段。
+ * @returns 至少一个非空段大小写不敏感地等于完整 `node_modules` 时返回 `true`；空路径、
+ * 空段及 `node_modules.txt`、`node_modules-old`、`@node_modules` 等相似名称返回 `false`。
+ *
+ * @remarks
+ * 比较使用每个非空 segment 的 `toLowerCase() === 'node_modules'`，因此根目录或任意深度的
+ * `node_modules`、`NODE_MODULES`、`Node_Modules` 都会命中。前导和重复 slash 会先被
+ * `normalizeRelativePath` 整理；尾随 slash 产生的空段会被忽略。
+ *
+ * 这是同步、无副作用的**单一 predicate**，只回答“规范化后的文本是否包含该完整段”。它
+ * 不 trim segment、不进行 URL/percent decode、Unicode normalize 或文件系统解析。例如
+ * `node_modules%2Fpkg/index.js`、`%6eode_modules/pkg.js` 和 `node_modules.txt` 都不会命中；调用方
+ * 不应传 URL，也不能把未命中解释为路径安全。
+ *
+ * 本函数不会拒绝或消解 `.` / `..`、绝对路径、Windows drive prefix、控制字符、空路径、
+ * symlink、重复路径或超长路径。`assets/../node_modules/pkg.js` 仍会命中，因为点段保持原样；
+ * 不含 `node_modules` 的危险路径则仍可能返回 `false`。签名或上传前必须继续执行对应的上传
+ * 路径规范、唯一性和长度校验。
+ *
+ * SDK build/deploy 会在文件扫描后用本函数拒绝整个 `node_modules` 树，再用
+ * {@link shouldUploadDistFile} 排除根 `manifest.json`、`.DS_Store` 和 source map。build 随后
+ * 校验大小预算；deploy 还会执行上传路径安全、唯一性、长度与签名校验。这些步骤互不替代：`shouldUploadDistFile()` 本身不检查
+ * `node_modules`，本函数也不决定普通文件是否应该上传。
+ *
+ * @example
+ * ```ts
+ * import { relativePathContainsNodeModulesSegment } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * relativePathContainsNodeModulesSegment('dist\\NODE_MODULES/pkg/index.js'); // true
+ * relativePathContainsNodeModulesSegment('dist//vendor///node_modules/'); // true
+ * relativePathContainsNodeModulesSegment('dist/node_modules.txt'); // false
+ * relativePathContainsNodeModulesSegment('dist/node_modules%2Fpkg.js'); // false，不做 URL decode
+ * relativePathContainsNodeModulesSegment('assets/../secret.js'); // false，但这不代表路径安全
+ * ```
+ *
+ * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
+ * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
+ * @see [miniapp-publish](/reference/miniapp-publish/)
+ */
 function relativePathContainsNodeModulesSegment(relativePath) {
     return normalizeRelativePath(relativePath)
         .split('/')
         .some((segment) => segment.length > 0 && segment.toLowerCase() === 'node_modules');
 }
+/**
+ * 为小程序 ID 计算稳定、紧凑的上传路径别名。
+ *
+ * @param miniProgramId - 小程序 ID。
+ * @returns 基于 32-bit FNV-1a 结果生成的 base36 字符串。
+ * @remarks 该别名只用于缩短上传 key，不是加密摘要，也不能用于鉴权或隐藏小程序身份。
+ * @example
+ * ```ts
+ * const alias = getMiniProgramUploadAlias('mp_example');
+ * console.log(/^[a-z0-9]+$/.test(alias)); // true
+ * ```
+ */
 function getMiniProgramUploadAlias(miniProgramId) {
     let hash = FNV_OFFSET;
     const input = String(miniProgramId || '');
@@ -2975,11 +3246,44 @@ function getMiniProgramUploadAlias(miniProgramId) {
     }
     return hash.toString(36);
 }
+/**
+ * 生成旧版固定版本 CDN 上传 key。
+ *
+ * @param input - 小程序 ID、版本和构建产物相对路径。
+ * @returns `/u/{alias}/{version}/{relativePath}` 形式的上传 key。
+ * @remarks 此函数不会校验版本、路径安全性或 key 长度；批量上传前应调用 {@link validateUploadPaths}。
+ * @example
+ * ```ts
+ * getMiniappUploadKey({
+ *   miniProgramId: 'mp_example',
+ *   version: '1.2.3',
+ *   relativePath: 'assets\\app.js',
+ * }); // /u/<alias>/1.2.3/assets/app.js
+ * ```
+ */
 function getMiniappUploadKey(input) {
     const alias = getMiniProgramUploadAlias(input.miniProgramId);
     const normalized = normalizeRelativePath(input.relativePath);
     return `/u/${alias}/${input.version}/${normalized}`;
 }
+/**
+ * 校验旧版固定版本上传路径的格式、唯一性和完整 key 长度。
+ *
+ * @param items - 待上传条目；按数组顺序检查。
+ * @param options - 小程序 ID、版本和可选的 key 长度上限。
+ * @returns 第一个校验错误的中文提示；全部合法时返回 `undefined`。
+ * @remarks
+ * 路径会先统一分隔符，因此 `assets\\app.js` 与 `assets/app.js` 视为重复。
+ * 长度按 JavaScript 字符串 `length` 计算；上传会话的 UTF-8 字节限制应使用 {@link validateMiniappUploadPathLengths}。
+ * @example
+ * ```ts
+ * const error = validateUploadPaths(
+ *   [{ relativePath: 'index.html' }, { relativePath: 'assets/app.js' }],
+ *   { miniProgramId: 'mp_example', version: '1.2.3' },
+ * );
+ * if (error) throw new Error(error);
+ * ```
+ */
 function validateUploadPaths(items, options) {
     const limit = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
     const uploadKeys = new Set();
@@ -3021,6 +3325,63 @@ function getInvalidUploadPathReason(relativePath) {
     }
     return undefined;
 }
+/**
+ * 校验一组构建产物的总大小是否超过给定上限。
+ *
+ * @param items - 要累计的条目。函数按数组顺序读取每项 `size`，经 `Number(...)` 转换后仅
+ * 累加有限且大于 `0` 的值；不修改、过滤或排序输入数组，也不读取 `relativePath`。
+ * @param options - 可选 byte 上限；默认 `104857600` bytes（100 MiB）。自定义上限不会改变
+ * 固定错误文案。
+ * @returns 总和严格大于上限时返回唯一固定字符串
+ * `构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy`；总和小于或等于
+ * 上限时返回 `undefined`。函数不会因超限抛异常，调用方决定是否把返回文本转成 `Error`。
+ *
+ * @remarks
+ * 计算等价于把每项规范成 `Number.isFinite(Number(size)) && Number(size) > 0 ? Number(size) : 0`
+ * 后求和，不取整、不去重，也不设置单文件上限。因此一个文件可以占满全部预算，多个同路径
+ * 条目会重复计数，正小数会按 JavaScript number 原值加入；总和恰等 `limitBytes` 时通过，
+ * 多 1 byte 才返回错误。
+ *
+ * 在声明的 TypeScript 输入契约内，该函数以返回值报告预算结果，不为非有限/非正 size 抛错。
+ * 固定错误文本不包含首个文件、实际总量或自定义上限，即使测试/集成传了其他 `limitBytes`，
+ * 文案仍写 `100MB` 和 `重新 deploy`。`hb-sdk build` 的调用方会把末尾提示改成 `重新 build`。
+ *
+ * 该函数只校验一个未分组列表的总量，不读取文件系统，不执行 stat，也不校验路径、安全性、
+ * 文件数量、重复项、单文件大小或内容。调用方应先用
+ * [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 选择真正
+ * 上传的文件，并完成 `node_modules`、路径规范/唯一性/长度等校验；被提前过滤的 Manifest、
+ * `.DS_Store` 和 source map 才不会计入总量。
+ *
+ * Web 与 Companion 需要独立预算时使用 `validateMiniappUploadSizeBudgets()`：它按
+ * `relativePath` 的 `companions/` 前缀分组，Web 组复用本函数的默认 100 MiB 规则，Companion
+ * 组使用独立 500 MiB 上限。直接调用本函数不会识别或分开这些路径。
+ *
+ * @example
+ * ```ts
+ * import { validateUploadTotalSize } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * const atLimit = validateUploadTotalSize(
+ *   [
+ *     { relativePath: 'assets/app.js', size: 1_024 },
+ *     { relativePath: 'assets/ignored-negative.js', size: -1 },
+ *     { relativePath: 'assets/ignored-nan.js', size: Number.NaN },
+ *   ],
+ *   { limitBytes: 1_024 },
+ * )
+ * console.log(atLimit) // undefined，恰等上限
+ *
+ * const overLimit = validateUploadTotalSize(
+ *   [{ relativePath: 'assets/app.js', size: 1_025 }],
+ *   { limitBytes: 1_024 },
+ * )
+ * if (overLimit) throw new Error(overLimit)
+ * ```
+ *
+ * @see {@link UploadSizeItem}
+ * @see {@link ValidateUploadTotalSizeOptions}
+ * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
+ * @see [miniapp-publish](/reference/miniapp-publish/)
+ */
 function validateUploadTotalSize(items, options = {}) {
     const limit = options.limitBytes ?? MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES;
     const total = items.reduce((sum, item) => {
@@ -3032,6 +3393,22 @@ function validateUploadTotalSize(items, options = {}) {
     }
     return undefined;
 }
+/**
+ * 分别校验 Web 构建产物与 Companion 归档的总大小预算。
+ *
+ * @param items - 全部待上传文件；规范化后以 `companions/` 开头的路径计入 Companion 预算，其余计入 Web 预算。
+ * @param options - 可选测试或集成覆盖项：`webLimitBytes` 为 Web 上限，`companionLimitBytes` 为 Companion 上限，单位均为 bytes。
+ * @returns Web 或 Companion 的第一个超限提示；两类总量均不超过各自上限时返回 `undefined`。
+ * @remarks Web 默认上限为 100 MiB，Companion 默认上限为 500 MiB；两类预算不会相互借用。
+ * @example
+ * ```ts
+ * const error = validateMiniappUploadSizeBudgets([
+ *   { relativePath: 'index.html', size: 1_024 },
+ *   { relativePath: 'companions/runner/windows-x64.zip', size: 8_192 },
+ * ]);
+ * if (error) throw new Error(error);
+ * ```
+ */
 function validateMiniappUploadSizeBudgets(items, options = {}) {
     const companionItems = items.filter((item) => normalizeRelativePath(item.relativePath).startsWith('companions/'));
     const webItems = items.filter((item) => !normalizeRelativePath(item.relativePath).startsWith('companions/'));
@@ -3044,6 +3421,59 @@ function validateMiniappUploadSizeBudgets(items, options = {}) {
         return 'Companion 归档总大小超过 500MiB 上限，请缩减归档后重新 deploy';
     return undefined;
 }
+/**
+ * 判断 `dist` 中的文件是否应作为版本产物上传。
+ *
+ * @param relativePath - `dist` 根目录下的文件路径。判断前先经 {@link normalizeRelativePath}
+ * 统一斜杠、删除前导 `/` 并合并连续 `/`；函数不读取文件系统或文件内容。
+ * @returns 以下规范化结果返回 `false`：空路径、精确等于根 `manifest.json`、精确 basename 为
+ * `.DS_Store` 的任意层级路径，以及以大小写不敏感 `.map` 结尾的路径。其他值返回 `true`。
+ *
+ * @remarks
+ * 过滤顺序以 `normalizeRelativePath(relativePath)` 的结果为准：
+ *
+ * - `''` 返回 `false`。
+ * - 只有精确根路径 `manifest.json` 返回 `false`；`/manifest.json` 规范化后也会命中。
+ *   `assets/manifest.json` 会保留，因为它不是根文件。匹配大小写敏感，所以
+ *   `Manifest.json` 不会作为生成 Manifest 被过滤。
+ * - 根或任意子目录中精确名为 `.DS_Store` 的最终 segment 返回 `false`，匹配大小写敏感；
+ *   `.ds_store`、`.DS_Store.bak` 会保留。
+ * - 整条规范化路径经 `toLowerCase()` 后以 `.map` 结尾即返回 `false`，因此 `.map`、
+ *   `app.js.map`、`app.js.MAP` 都会过滤，而 `app.js.map.txt` 会保留。
+ *
+ * 根 `manifest.json` 是发布流水线单独读取并上送后台的版本元数据，不作为 CDN 文件上传；
+ * 子目录同名文件仍被视为普通业务产物。该 predicate 只做上传集合选择，不验证输入确实是
+ * 文件，也不检查扩展名白名单、文件存在性或内容。
+ *
+ * `true` 不代表路径安全。本函数不会 URL decode，也不会拒绝 `node_modules`、symlink、绝对
+ * 路径、Windows drive prefix、`.` / `..`、空 segment、控制字符、重复路径或超长路径。
+ * build/deploy 必须另外使用 {@link relativePathContainsNodeModulesSegment} 拒绝依赖目录；deploy
+ * 还需在签名/上传前执行路径规范、唯一性和长度校验。
+ *
+ * build/deploy 会先扫描并完成上述独立边界，再以本函数过滤候选文件。build 对保留文件校验
+ * 上传大小预算；deploy 额外执行 artifact 排序/签名与路径长度校验。因此被过滤的根 Manifest、Finder
+ * 元数据和 source map 不计入上传文件数或大小；本函数自身不读取 `size`，也不能替代
+ * `validateUploadTotalSize()` / `validateMiniappUploadSizeBudgets()`。
+ *
+ * @example
+ * ```ts
+ * import { shouldUploadDistFile } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * shouldUploadDistFile('/manifest.json'); // false，规范化后是根 manifest.json
+ * shouldUploadDistFile('assets/manifest.json'); // true
+ * shouldUploadDistFile('assets/.DS_Store'); // false
+ * shouldUploadDistFile('assets/.ds_store'); // true，.DS_Store 区分大小写
+ * shouldUploadDistFile('assets/app.js.MAP'); // false，.map 后缀不区分大小写
+ * shouldUploadDistFile('assets/app.js.map.txt'); // true
+ * shouldUploadDistFile('node_modules/pkg/index.js'); // true，必须另做 node_modules 检查
+ * shouldUploadDistFile('assets/../secret.js'); // true，但这不代表路径安全
+ * ```
+ *
+ * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
+ * @see [relativePathContainsNodeModulesSegment](/reference/symbols/miniapp-publish/functions/relativePathContainsNodeModulesSegment)
+ * @see [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize)
+ * @see [miniapp-publish](/reference/miniapp-publish/)
+ */
 function shouldUploadDistFile(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
     if (!normalized) {
@@ -3061,11 +3491,22 @@ function shouldUploadDistFile(relativePath) {
     return true;
 }
 /**
- * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ * 校验构建产物路径和大小，并按路径的 UTF-8 字节序稳定排序。
  *
- * @param files - 待处理的构建产物文件。
- * @returns 保留输入附加字段的有序文件列表。
- * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ * @param files - 待处理的构建产物文件；允许携带 `absolutePath`、`sha256` 等附加字段。
+ * @returns 新建的有序文件列表；每个结果保留输入条目的附加字段，输入数组顺序不变。
+ * @throws `Error` 当文件数超过 uint32、路径为空或不规范、路径重复，或大小不是非负 safe integer 时抛出。
+ * @remarks 路径必须已经使用规范 `/` 分隔形式；此函数不会把反斜杠或点目录段自动改写为其他路径。
+ * @example
+ * ```ts
+ * const files = prepareMiniappArtifactFiles([
+ *   { relativePath: 'index.html', size: 15, absolutePath: '/tmp/dist/index.html' },
+ *   { relativePath: 'assets/app.js', size: 42, absolutePath: '/tmp/dist/assets/app.js' },
+ * ]);
+ *
+ * console.log(files.map((file) => file.relativePath));
+ * // ['assets/app.js', 'index.html']
+ * ```
  */
 function prepareMiniappArtifactFiles(files) {
     if (files.length > 0xffffffff) {
@@ -3086,9 +3527,19 @@ function prepareMiniappArtifactFiles(files) {
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files - 待上传的构建产物文件。
- * @param options - 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件；每个路径都必须是规范相对路径。
+ * @param options - `miniProgramId` 用于计算上传别名，`maxLength` 是完整 key 的最大 UTF-8 bytes，默认 {@link ACTIVITY_UPLOAD_KEY_MAX_LENGTH}。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ * @throws `Error` 当任一文件路径为空或不符合构建产物路径规则时抛出。
+ * @remarks 会话引用按固定 10 个 ASCII 字符估算，因此该校验不依赖真实 session ID。
+ * @example
+ * ```ts
+ * const error = validateMiniappUploadPathLengths(
+ *   [{ relativePath: 'assets/app.js' }],
+ *   { miniProgramId: 'mp_example' },
+ * );
+ * if (error) throw new Error(error);
+ * ```
  */
 function validateMiniappUploadPathLengths(files, options) {
     const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
@@ -3103,9 +3554,14 @@ function validateMiniappUploadPathLengths(files, options) {
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount - 参与签名的文件数量。
- * @returns 包含协议标识和文件数量的字节数组。
- * @throws 文件数量超出协议范围时抛出错误。
+ * @param fileCount - 参与签名的文件数量；必须是 `0` 到 `0xffffffff` 的整数。
+ * @returns 新的字节数组，依次包含固定协议标识和 big-endian uint32 文件数。
+ * @throws `Error` 当文件数不是整数、为负数或超出 uint32 范围时抛出。
+ * @example
+ * ```ts
+ * const header = createMiniappArtifactSignatureHeader(2);
+ * // 将 header 写入 SHA-256，再按排序结果依次写入文件 header 和内容。
+ * ```
  */
 function createMiniappArtifactSignatureHeader(fileCount) {
     if (!Number.isInteger(fileCount) || fileCount < 0 || fileCount > 0xffffffff) {
@@ -3116,9 +3572,16 @@ function createMiniappArtifactSignatureHeader(fileCount) {
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file - 已规范化或待校验的构建产物文件。
- * @returns 包含路径长度、路径和文件大小的字节数组。
- * @throws 文件路径或大小非法时抛出错误。
+ * @param file - 构建产物文件；路径必须规范，大小必须是非负 safe integer。
+ * @returns 新的字节数组，依次包含 big-endian uint32 路径字节数、UTF-8 路径和 big-endian uint64 文件大小。
+ * @throws `Error` 当路径为空或不规范，或大小不是非负 safe integer 时抛出。
+ * @example
+ * ```ts
+ * const header = createMiniappArtifactFileHeader({
+ *   relativePath: 'assets/app.js',
+ *   size: 42,
+ * });
+ * ```
  */
 function createMiniappArtifactFileHeader(file) {
     const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
@@ -3129,11 +3592,28 @@ function createMiniappArtifactFileHeader(file) {
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles - 本地构建产物文件。
- * @param serverFiles - 服务端签发的文件映射。
- * @param uploadedKeys - 服务端已确认上传成功的 key。
- * @returns 完整映射、待上传文件和已确认 key。
- * @throws 服务端映射与本地产物不一致时抛出错误。
+ * @param localFiles - 本地构建产物 receipt；除 `relativePath` 和 `size` 外，每项必须包含 64 位小写十六进制 `sha256`。
+ * @param serverFiles - 服务端签发的文件映射；数量、路径、大小和 SHA-256 必须与本地产物一一一致。
+ * @param uploadedKeys - 服务端已确认上传成功的 key；每个值都必须属于当前会话，重复值会被去重。
+ * @returns
+ * 包含三个字段的对象：`files` 是按路径 UTF-8 字节序排列的全部 `{ file, key }` 映射，
+ * `missingFiles` 是其中尚未确认上传的映射，`uploadedKeys` 是去重后的已上传 key。
+ * @throws `Error` 当本地产物不规范，服务端映射数量或字段无效、重复或不匹配，或已上传 key 不属于当前产物时抛出。
+ * @example
+ * ```ts
+ * const resolved = resolveMiniappUploadSessionFiles(
+ *   [{ relativePath: 'index.html', size: 15, sha256: 'a'.repeat(64) }],
+ *   [{
+ *     relative_path: 'index.html',
+ *     key: '/u/abc/sessionref/index.html',
+ *     size: 15,
+ *     sha256: 'a'.repeat(64),
+ *   }],
+ *   [],
+ * );
+ *
+ * console.log(resolved.missingFiles.length); // 1
+ * ```
  */
 function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys) {
     const preparedFiles = prepareMiniappArtifactFiles(localFiles);
@@ -3196,7 +3676,33 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         uploadedKeys: [...completed],
     };
 }
-/** 校验 Manifest 中所有 Companion 归档都精确属于当前上传 receipt。 */
+/**
+ * 校验 Manifest 中所有 Companion 归档都精确属于当前上传 receipt。
+ *
+ * @param companions - `manifest.companions` 原始值；没有 Companion 时传 `undefined`。
+ * @param files - 当前版本的逐文件上传 receipt；只有 `companions/` 前缀文件参与本校验。
+ * @returns 校验成功时不返回值。
+ * @throws `Error` 当必要的 `targets`/artifact 字段缺失，引用不存在的归档、大小或 SHA-256 不一致，
+ * 或 receipt 中存在未被 Manifest 引用的 Companion 归档时抛出。
+ * @remarks 本函数只交叉校验 Companion 声明与上传 receipt，不替代完整 Manifest schema 校验。
+ * 非 Companion Web 文件会被忽略；`companions` 省略时 receipt 中也不能存在 Companion 归档。
+ * @example
+ * ```ts
+ * const receipt = [{
+ *   relativePath: 'companions/runner/windows-x64.zip',
+ *   size: 42,
+ *   sha256: 'a'.repeat(64),
+ * }];
+ *
+ * validateMiniappCompanionFileReceipts({
+ *   runner: {
+ *     targets: {
+ *       'windows-x64': { path: receipt[0].relativePath, size: 42, sha256: receipt[0].sha256 },
+ *     },
+ *   },
+ * }, receipt);
+ * ```
+ */
 function validateMiniappCompanionFileReceipts(companions, files) {
     const companionFiles = new Map(files.filter((file) => file.relativePath.startsWith('companions/')).map((file) => [file.relativePath, file]));
     if (companions === undefined) {