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

package/types/miniapp-publish/index.d.ts

@@ -1,94 +1,425 @@
+/** CDN 上传接口使用的小程序产物业务 scope。 */
 export declare const MINIAPP_UPLOAD_SCOPE = "activity";
+/** 完整 CDN 上传 key 的默认长度上限；旧固定版本流程按字符计数，上传会话流程按 UTF-8 bytes 计数。 */
 export declare const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+/** 单次向 CDN 申请上传信息时包含的最大文件数；当前合同固定为 `50`。 */
 export declare const MINIAPP_UPLOAD_BATCH_SIZE = 50;
+/** Web 构建产物的默认总大小上限，单位为 bytes；当前为 100 MiB。 */
 export declare const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES: number;
-/** 与 Activity 上传后端合同一致的 Companion 归档总大小上限。 */
+/** Companion 归档的临时总大小上限，单位为 bytes；当前为 500 MiB。 */
 export declare const MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES: number;
+/** 查询当前开发者账号是否具备小程序访问资格的开放平台 API 路径。 */
 export declare const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = "/mall/developer/user_miniprogram/access_status";
+/** 查询当前开发者可管理主体列表的开放平台 API 路径。 */
 export declare const DEVELOPER_ENTITY_LIST_API_PATH = "/mall/developer/entity/list";
+/** 切换当前开发者主体的开放平台 API 路径。 */
 export declare const DEVELOPER_ENTITY_SWITCH_API_PATH = "/mall/developer/entity/switch";
+/** 查询当前主体下小程序列表的开放平台 API 路径。 */
 export declare const LIST_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/list";
+/** 创建小程序的开放平台 API 路径。 */
 export declare const CREATE_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/create";
+/** 查询单个小程序详情的开放平台 API 路径。 */
 export declare const DETAIL_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/detail";
+/** 创建本地开发启动凭据的开放平台 API 路径。 */
 export declare const CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH = "/mall/developer/user_miniprogram/local_dev_launch_token";
+/** 查询小程序预览白名单的开放平台 API 路径。 */
 export declare const USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist";
+/** 更新小程序预览白名单的开放平台 API 路径。 */
 export declare const UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist/update";
+/** 创建小程序云排行榜的开放平台 API 路径。 */
 export declare const CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/create";
+/** 查询单个小程序云排行榜详情的开放平台 API 路径。 */
 export declare const DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/detail";
+/** 查询小程序云排行榜列表的开放平台 API 路径。 */
 export declare const LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/list";
+/** 删除小程序云排行榜的开放平台 API 路径。 */
 export declare const DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/delete";
+/** 在上传或复用版本前执行发布预检的开放平台 API 路径。 */
 export declare const PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/precheck";
+/** 将小程序版本提交审核的开放平台 API 路径。 */
 export declare const SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = "/mall/developer/user_miniprogram/version/submit_audit";
+/** 查询小程序版本预览信息的开放平台 API 路径。 */
 export declare const USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = "/mall/developer/user_miniprogram/version/preview_info";
+/** 撤回待审核小程序版本的开放平台 API 路径。 */
 export declare const WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/withdraw";
+/** 发布审核通过的小程序版本的开放平台 API 路径。 */
 export declare const RELEASE_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/release";
+/** 下架当前线上小程序的开放平台 API 路径。 */
 export declare const TAKE_DOWN_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/take_down";
+/** 重新开放已下架小程序的开放平台 API 路径。 */
 export declare const REOPEN_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/reopen";
+/** 更新小程序广场展示状态的开放平台 API 路径。 */
 export declare const UPDATE_SQUARE_DISPLAY_API_PATH = "/mall/developer/user_miniprogram/square_display/update";
+/** 查询小程序历史版本列表的开放平台 API 路径。 */
 export declare const LIST_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/list";
 export { isValidMiniappManifestVersion as isValidVersion } from '../miniapp-manifest/schema';
 export { MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, resolveMiniappManifestPlatforms, type MiniappPlatformPolicy, type MiniappPlatformResolution, } from '../miniapp-manifest/schema';
 export { parseMiniappBindAppIds, type ParseMiniappBindAppIdsOptions } from '../miniapp-manifest/bindings';
+/**
+ * 将扫描到的相对路径转换为统一的 `/` 分隔形式。
+ *
+ * @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}
+ */
 export declare function normalizeRelativePath(relativePath: string): string;
+/**
+ * 判断路径中是否包含大小写不敏感的完整 `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/)
+ */
 export declare function relativePathContainsNodeModulesSegment(relativePath: string): boolean;
+/**
+ * 为小程序 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
+ * ```
+ */
 export declare function getMiniProgramUploadAlias(miniProgramId: string): string;
+/** 生成旧版固定版本上传 key 所需的输入。 */
 export interface MiniappUploadKeyInput {
+    /** 小程序 ID；函数会将其转换为稳定上传别名。 */
     miniProgramId: string;
+    /** 要写入上传 key 的版本字符串；调用方应先完成版本合法性校验。 */
     version: string;
+    /** 构建产物相对路径；生成 key 前会整理路径分隔符。 */
     relativePath: string;
 }
+/**
+ * 生成旧版固定版本 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
+ * ```
+ */
 export declare function getMiniappUploadKey(input: MiniappUploadKeyInput): string;
+/** 参与旧版上传路径校验的构建产物条目。 */
 export interface UploadPathItem {
+    /** 构建产物相对路径。 */
     relativePath: string;
 }
+/** 旧版固定版本上传路径的校验选项。 */
 export interface ValidateUploadPathsOptions {
+    /** 小程序 ID，用于计算上传 key 中的稳定别名。 */
     miniProgramId: string;
+    /** 要写入上传 key 的版本字符串。 */
     version: string;
+    /** 完整上传 key 的最大字符数，默认 {@link ACTIVITY_UPLOAD_KEY_MAX_LENGTH}。 */
     maxLength?: number;
 }
+/**
+ * 校验旧版固定版本上传路径的格式、唯一性和完整 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);
+ * ```
+ */
 export declare function validateUploadPaths(items: UploadPathItem[], options: ValidateUploadPathsOptions): string | undefined;
+/**
+ * 参与上传总大小计算的构建产物条目。
+ *
+ * @remarks
+ * {@link validateUploadTotalSize} 只读取 `size`，不会读取或校验 `relativePath`。同一类型也供
+ * `validateMiniappUploadSizeBudgets()` 使用，后者才根据规范化路径区分 Web 与 Companion 预算。
+ */
 export interface UploadSizeItem {
+    /**
+     * 构建产物相对路径。直接调用 {@link validateUploadTotalSize} 时该字段不参与计算；预算包装
+     * 函数会把规范化后以 `companions/` 开头的路径归入 Companion 组。
+     */
     relativePath: string;
+    /**
+     * 调用方提供的文件大小，单位为 bytes。函数内部执行 `Number(size)`，仅有限且大于 `0` 的
+     * 数值加入总和；`NaN`、正负 `Infinity`、负数和 `0` 均按 `0` 处理，不会单独报错。
+     */
     size: number;
 }
+/** {@link validateUploadTotalSize} 的总量上限选项。 */
 export interface ValidateUploadTotalSizeOptions {
+    /**
+     * 总大小上限，单位为 bytes；省略时使用 `MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES`，当前为
+     * `104857600` bytes（100 MiB）。总和恰好等于上限仍合法，只有严格大于才算超限。
+     *
+     * @remarks
+     * 本函数不校验自定义上限。调用方应传有限且大于等于 `0` 的 number；`NaN`、负数或
+     * `Infinity` 会直接参与 JavaScript 的 `>` 比较，不应作为受支持配置使用。
+     */
     limitBytes?: number;
 }
+/**
+ * 校验一组构建产物的总大小是否超过给定上限。
+ *
+ * @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/)
+ */
 export declare function validateUploadTotalSize(items: UploadSizeItem[], options?: ValidateUploadTotalSizeOptions): "构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy" | 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);
+ * ```
+ */
 export declare function validateMiniappUploadSizeBudgets(items: UploadSizeItem[], options?: {
     webLimitBytes?: number;
     companionLimitBytes?: number;
 }): "构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy" | "Companion 归档总大小超过 500MiB 上限，请缩减归档后重新 deploy" | 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/)
+ */
 export declare function shouldUploadDistFile(relativePath: string): boolean;
-/** 参与整包签名和上传会话映射的构建产物文件。 */
+/**
+ * 参与整包签名和上传会话映射的构建产物文件。
+ *
+ * 路径必须是规范相对路径，大小必须是大于或等于 `0` 的 safe integer。
+ */
 export interface MiniappArtifactFile {
-    /** 使用 `/` 分隔的构建产物相对路径。 */
+    /** 使用 `/` 分隔的构建产物相对路径；不能包含绝对路径、点目录段、控制字符、逗号或通配符。 */
     relativePath: string;
-    /** 文件字节数。 */
+    /** 文件大小，单位为 bytes；必须是大于或等于 `0` 的 safe integer。 */
     size: number;
 }
-/** 上传会话 v1 使用的逐文件完整性凭据。 */
+/** 上传会话 v1 使用的逐文件完整性凭据，由本地文件内容计算。 */
 export interface MiniappArtifactFileReceipt extends MiniappArtifactFile {
-    /** 文件内容 SHA-256，小写十六进制。 */
+    /** 文件内容 SHA-256，使用 64 位小写十六进制字符串。 */
     sha256: string;
 }
-/** 服务端上传会话返回的文件映射。 */
+/** 服务端上传会话返回的单个文件映射。 */
 export interface MiniappUploadSessionFile {
-    /** 与创建会话时提交值一致的相对路径。 */
+    /** 与创建会话时提交值一致的规范相对路径。 */
     relative_path: string;
-    /** 服务端签发的完整上传 key。 */
+    /** 服务端签发的非空完整 CDN 上传 key；同一会话内必须唯一。 */
     key: string;
-    /** 服务端记录的文件字节数。 */
+    /** 服务端记录的文件大小，单位为 bytes；必须是大于或等于 `0` 的 safe integer。 */
     size: number;
-    /** 服务端固化的文件内容 SHA-256。 */
+    /** 服务端固化的文件内容 SHA-256，使用 64 位小写十六进制字符串。 */
     sha256: string;
 }
 /**
- * 校验构建产物路径和大小，并按路径 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']
+ * ```
  */
 export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFile>(files: readonly T[]): (T & {
     relativePath: string;
@@ -96,9 +427,19 @@ export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFil
 /**
  * 按服务端 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);
+ * ```
  */
 export declare function validateMiniappUploadPathLengths(files: readonly Pick<MiniappArtifactFile, 'relativePath'>[], options: {
     miniProgramId: string;
@@ -107,27 +448,56 @@ export declare function validateMiniappUploadPathLengths(files: readonly Pick<Mi
 /**
  * 创建 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 和内容。
+ * ```
  */
 export declare function createMiniappArtifactSignatureHeader(fileCount: number): Uint8Array<ArrayBuffer>;
 /**
  * 创建单个文件的 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,
+ * });
+ * ```
  */
 export declare function createMiniappArtifactFileHeader(file: MiniappArtifactFile): Uint8Array<ArrayBuffer>;
 /**
  * 校验服务端 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
+ * ```
  */
 export declare function resolveMiniappUploadSessionFiles<T extends MiniappArtifactFile>(localFiles: readonly T[], serverFiles: readonly MiniappUploadSessionFile[], uploadedKeys: readonly string[]): {
     files: {
@@ -144,5 +514,31 @@ export declare function resolveMiniappUploadSessionFiles<T extends MiniappArtifa
     }[];
     uploadedKeys: string[];
 };
-/** 校验 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);
+ * ```
+ */
 export declare function validateMiniappCompanionFileReceipts(companions: unknown, files: readonly MiniappArtifactFileReceipt[]): void;