@heybox/hb-sdk 0.9.2-alpha.8 → 0.9.2

package/dist/devtools/browser-dev-host/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-D7F2y1lF.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-lmlBUG16.js">
+    <script type="module" crossorigin src="/assets/index-p1R5T0MK.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-DcTaMyDt.js">
     <link rel="stylesheet" crossorigin href="/assets/index-7Cq8iNcD.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -544,6 +544,7 @@ const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
  * @see [MINI_PROGRAM_BRIDGE_NONCE_PARAM](/reference/symbols/protocol/constants/MINI_PROGRAM_BRIDGE_NONCE_PARAM) iframe URL 中的 nonce 参数名。
  * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) 公开 method 与权限 requirement 目录。
  * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) Runtime 权限快照解析器。
+ * @since 0.3.1
  */
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$3(value))
@@ -628,6 +629,7 @@ function isMiniProgramBridgeMessage(value) {
  * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) 提供 `file()` / `directory()` 的 SDK 路径入口。
  * @see [FileSystem](/reference/symbols/root/interfaces/FileSystem) `files.sandbox` 逻辑路径能力。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 已授权目录下的相对路径能力。
+ * @since 0.8.0
  */
 function isMiniProgramRelativePath(value) {
     if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
@@ -694,6 +696,7 @@ function isMiniProgramRelativePath(value) {
  * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) SDK 公开的逻辑路径 root 能力。
  * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) 提供 `files.sandbox` 与目录 picker 的入口。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 可作为 derived path root 的目录代理。
+ * @since 0.8.0
  */
 function isMiniProgramPathRootRef(value) {
     if (!isRecord$3(value))
@@ -760,6 +763,7 @@ function isMiniProgramPathRootRef(value) {
  * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 包含名称和 mode 的文件 descriptor guard。
  * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 可用 `'.'` 指向 root 自身的目录引用 guard。
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 使用文件引用的公开 I/O 代理。
+ * @since 0.8.0
  */
 function isMiniProgramFileRef(value) {
     if (!isRecord$3(value) || value.kind !== 'file')
@@ -827,6 +831,7 @@ function isMiniProgramFileRef(value) {
  * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 包含名称和 mode 的目录 descriptor guard。
  * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 不接受 root 自身 `'.'` 的文件引用 guard。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 使用目录引用的公开路径操作代理。
+ * @since 0.8.0
  */
 function isMiniProgramDirectoryRef(value) {
     if (!isRecord$3(value) || value.kind !== 'directory')
@@ -887,6 +892,7 @@ function isMiniProgramDirectoryRef(value) {
  * @see [CompanionStdio](/reference/symbols/root/interfaces/CompanionStdio) Companion 原始字节 stdin/stdout/stderr。
  * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 文件 descriptor guard。
  * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 目录 descriptor guard。
+ * @since 0.8.0
  */
 function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
@@ -946,6 +952,7 @@ function isMiniProgramByteArray(value) {
  * @see [FileStatResult](/reference/symbols/protocol/types/FileStatResult) `file.stat` 的 wire 返回类型。
  * @see [FileStat](/reference/symbols/root/interfaces/FileStat) SDK 向业务返回的元数据快照。
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 提供 `stat()` 的当前 session 文件代理。
+ * @since 0.8.0
  */
 function isMiniProgramFileStat(value) {
     return (isRecord$3(value) &&
@@ -1006,6 +1013,7 @@ function isMiniProgramFileStat(value) {
  * @see [DownloadProgress](/reference/symbols/root/interfaces/DownloadProgress) `onProgress` 接收的公开 SDK 进度类型。
  * @see [network.download](/reference/sdk/network/download) 产生并消费该进度的下载能力。
  * @see [isMiniProgramBridgeMessage](/reference/symbols/protocol/functions/isMiniProgramBridgeMessage) operation progress envelope 的最低校验。
+ * @since 0.8.0
  */
 function isMiniProgramDownloadProgressPayload(value) {
     if (!isRecord$3(value) ||
@@ -7291,7 +7299,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.2-alpha.8';
+    : '0.9.2';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -11595,7 +11603,7 @@ function getDefaultSDK() {
  * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的生命周期边沿事件。
  * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` 后同步读取环境快照。
  *
- * @since 0.7.0-alpha.9
+ * @since 0.7.0
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos
@@ -11690,7 +11698,7 @@ function getHandshakeState() {
  * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` handler 中同步读取环境。
  * @see [事件与生命周期](/guide/lifecycle) 握手与普通生命周期事件的使用建议。
  *
- * @since 0.7.0-alpha.9
+ * @since 0.7.0
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos
@@ -11785,7 +11793,7 @@ function onHandshakeStateChange(handler) {
  * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
  * @see [事件与生命周期](/guide/lifecycle) 生命周期时机与清理建议。
  *
- * @since 0.2.0-alpha.0
+ * @since 0.3.1
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos
@@ -11854,7 +11862,7 @@ function on(eventName, handler) {
  * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
  * @see [事件与生命周期](/guide/lifecycle) 生命周期事件列表与清理建议。
  *
- * @since 0.2.0-alpha.0
+ * @since 0.3.1
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos

package/dist/index.esm.js

@@ -540,6 +540,7 @@ const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
  * @see [MINI_PROGRAM_BRIDGE_NONCE_PARAM](/reference/symbols/protocol/constants/MINI_PROGRAM_BRIDGE_NONCE_PARAM) iframe URL 中的 nonce 参数名。
  * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) 公开 method 与权限 requirement 目录。
  * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) Runtime 权限快照解析器。
+ * @since 0.3.1
  */
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$3(value))
@@ -624,6 +625,7 @@ function isMiniProgramBridgeMessage(value) {
  * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) 提供 `file()` / `directory()` 的 SDK 路径入口。
  * @see [FileSystem](/reference/symbols/root/interfaces/FileSystem) `files.sandbox` 逻辑路径能力。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 已授权目录下的相对路径能力。
+ * @since 0.8.0
  */
 function isMiniProgramRelativePath(value) {
     if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
@@ -690,6 +692,7 @@ function isMiniProgramRelativePath(value) {
  * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) SDK 公开的逻辑路径 root 能力。
  * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) 提供 `files.sandbox` 与目录 picker 的入口。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 可作为 derived path root 的目录代理。
+ * @since 0.8.0
  */
 function isMiniProgramPathRootRef(value) {
     if (!isRecord$3(value))
@@ -756,6 +759,7 @@ function isMiniProgramPathRootRef(value) {
  * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 包含名称和 mode 的文件 descriptor guard。
  * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 可用 `'.'` 指向 root 自身的目录引用 guard。
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 使用文件引用的公开 I/O 代理。
+ * @since 0.8.0
  */
 function isMiniProgramFileRef(value) {
     if (!isRecord$3(value) || value.kind !== 'file')
@@ -823,6 +827,7 @@ function isMiniProgramFileRef(value) {
  * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 包含名称和 mode 的目录 descriptor guard。
  * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 不接受 root 自身 `'.'` 的文件引用 guard。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 使用目录引用的公开路径操作代理。
+ * @since 0.8.0
  */
 function isMiniProgramDirectoryRef(value) {
     if (!isRecord$3(value) || value.kind !== 'directory')
@@ -883,6 +888,7 @@ function isMiniProgramDirectoryRef(value) {
  * @see [CompanionStdio](/reference/symbols/root/interfaces/CompanionStdio) Companion 原始字节 stdin/stdout/stderr。
  * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 文件 descriptor guard。
  * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 目录 descriptor guard。
+ * @since 0.8.0
  */
 function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
@@ -942,6 +948,7 @@ function isMiniProgramByteArray(value) {
  * @see [FileStatResult](/reference/symbols/protocol/types/FileStatResult) `file.stat` 的 wire 返回类型。
  * @see [FileStat](/reference/symbols/root/interfaces/FileStat) SDK 向业务返回的元数据快照。
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 提供 `stat()` 的当前 session 文件代理。
+ * @since 0.8.0
  */
 function isMiniProgramFileStat(value) {
     return (isRecord$3(value) &&
@@ -1002,6 +1009,7 @@ function isMiniProgramFileStat(value) {
  * @see [DownloadProgress](/reference/symbols/root/interfaces/DownloadProgress) `onProgress` 接收的公开 SDK 进度类型。
  * @see [network.download](/reference/sdk/network/download) 产生并消费该进度的下载能力。
  * @see [isMiniProgramBridgeMessage](/reference/symbols/protocol/functions/isMiniProgramBridgeMessage) operation progress envelope 的最低校验。
+ * @since 0.8.0
  */
 function isMiniProgramDownloadProgressPayload(value) {
     if (!isRecord$3(value) ||
@@ -7287,7 +7295,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.2-alpha.8';
+    : '0.9.2';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -11591,7 +11599,7 @@ function getDefaultSDK() {
  * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的生命周期边沿事件。
  * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` 后同步读取环境快照。
  *
- * @since 0.7.0-alpha.9
+ * @since 0.7.0
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos
@@ -11686,7 +11694,7 @@ function getHandshakeState() {
  * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` handler 中同步读取环境。
  * @see [事件与生命周期](/guide/lifecycle) 握手与普通生命周期事件的使用建议。
  *
- * @since 0.7.0-alpha.9
+ * @since 0.7.0
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos
@@ -11781,7 +11789,7 @@ function onHandshakeStateChange(handler) {
  * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
  * @see [事件与生命周期](/guide/lifecycle) 生命周期时机与清理建议。
  *
- * @since 0.2.0-alpha.0
+ * @since 0.3.1
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos
@@ -11850,7 +11858,7 @@ function on(eventName, handler) {
  * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
  * @see [事件与生命周期](/guide/lifecycle) 生命周期事件列表与清理建议。
  *
- * @since 0.2.0-alpha.0
+ * @since 0.3.1
  * @hbPlatform android
  * @hbPlatform ios
  * @hbPlatform ohos

package/dist/miniapp-publish.cjs.js

@@ -6595,6 +6595,7 @@ function validateWorkspaceCardReceiptV2(raw, controller) {
  * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
  * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
  * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ * @since 0.8.3
  */
 function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category') {
     if (value === undefined)
@@ -9398,6 +9399,7 @@ const BASIC_INFO_MAX_PIXELS = 40_000_000;
  * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
  * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
  * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ * @since 0.8.2
  */
 function normalizeBasicInfoName(raw) {
     if (typeof raw !== 'string')
@@ -9429,6 +9431,7 @@ function validateBasicInfoPath(raw) {
  * @remarks
  * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
  * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ * @since 0.8.2
  */
 function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
     sdkVersion = sdkVersion.trim();
@@ -9501,6 +9504,7 @@ const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
  * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
  * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
  * @see [CLI 与远端发布](/guide/cli#生产构建)
+ * @since 0.8.1
  */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
@@ -9689,6 +9693,7 @@ const MINIAPP_WINDOW_ALLOWED_FIELDS = [...MINIAPP_WINDOW_NUMBER_FIELDS, 'resizab
  *
  * @see {@link resolveMiniappManifestPlatforms}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
+ * @since 0.3.1
  */
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
@@ -9709,6 +9714,7 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
  * @remarks
  * 不修改输入对象，不执行文件 I/O；不会验证图片/归档是否存在、内容摘要是否匹配，也不查询远端发布资格。
  * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
+ * @since 0.8.2
  */
 function validateMiniappManifestForDeploy(manifest) {
     const version = validateMiniappManifestVersion(manifest.version, 'manifest.version');
@@ -9882,6 +9888,7 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
  * @see {@link MINIAPP_LEGACY_DEFAULT_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}
+ * @since 0.8.1
  */
 function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
     if (!isRecord$1(manifest)) {
@@ -10079,6 +10086,7 @@ const BASIC_INFO_PLACEHOLDER_SHA256 = 'd14e54b30f5e6d1bcbf51267bc82b06a0af7c333f
  *   }
  * }
  * ```
+ * @since 0.8.2
  */
 async function previewMiniappBasicInfo(manifest, files) {
     const profile = parseMiniappBasicInfo(manifest, String(manifest.sdkVersion ?? ''));
@@ -18381,6 +18389,7 @@ const RUNTIME_GATE_BOOTSTRAP_MARKER = 'data-heybox-runtime-gate-bootstrap';
  * @param html - 待检查的完整 HTML 文本，使用 HTML parser 解析。
  * @returns Gate、隐藏样式及 bootstrap 标记均出现时返回 `true`，否则返回 `false`。
  * @remarks 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
+ * @since 0.8.2
  */
 function hasMiniappRuntimeGate(html) {
     const document = parse(html);
@@ -18513,6 +18522,7 @@ const textEncoder = new TextEncoder();
  * @see {@link relativePathContainsNodeModulesSegment}
  * @see {@link shouldUploadDistFile}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/protocol/functions/isMiniProgramRelativePath | isMiniProgramRelativePath}
+ * @since 0.3.1
  */
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
@@ -18543,6 +18553,7 @@ function normalizeRelativePath(relativePath) {
  * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
  * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
  * @see [miniapp-publish](/reference/miniapp-publish/)
+ * @since 0.3.1
  */
 function relativePathContainsNodeModulesSegment(relativePath) {
     return normalizeRelativePath(relativePath)
@@ -18570,85 +18581,6 @@ 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();
-    for (const item of items) {
-        const relativePath = String(item.relativePath ?? '');
-        const normalizedRelativePath = normalizeRelativePath(relativePath);
-        const invalidReason = getInvalidUploadPathReason(normalizedRelativePath);
-        if (invalidReason) {
-            return `构建产物文件路径不合法（${invalidReason}）：${JSON.stringify(relativePath)}`;
-        }
-        const key = getMiniappUploadKey({
-            miniProgramId: options.miniProgramId,
-            version: options.version,
-            relativePath: normalizedRelativePath,
-        });
-        if (uploadKeys.has(key)) {
-            return `构建产物文件路径重复，无法上传到同一位置：${JSON.stringify(relativePath)}`;
-        }
-        uploadKeys.add(key);
-        if (key.length > limit) {
-            return `文件路径过长，请缩短构建产物文件名或目录层级：${relativePath}`;
-        }
-    }
-    return undefined;
-}
-function getInvalidUploadPathReason(relativePath) {
-    const segments = relativePath.replace(/\\/g, '/').split('/');
-    if (segments.some((segment) => !segment)) {
-        return '包含空路径段';
-    }
-    if (segments.some((segment) => segment === '.')) {
-        return '包含当前目录';
-    }
-    if (segments.some((segment) => segment === '..')) {
-        return '包含上级目录';
-    }
-    if (/[\u0000-\u001F\u007F]/.test(relativePath)) {
-        return '包含控制字符';
-    }
-    return undefined;
-}
 /**
  * 校验一组构建产物的总大小是否超过给定上限。
  *
@@ -18705,6 +18637,7 @@ function getInvalidUploadPathReason(relativePath) {
  * @see {@link ValidateUploadTotalSizeOptions}
  * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
  * @see [miniapp-publish](/reference/miniapp-publish/)
+ * @since 0.4.7
  */
 function validateUploadTotalSize(items, options = {}) {
     const limit = options.limitBytes ?? MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES;
@@ -18797,6 +18730,7 @@ function validateMiniappUploadSizeBudgets(items, options = {}) {
  * @see [relativePathContainsNodeModulesSegment](/reference/symbols/miniapp-publish/functions/relativePathContainsNodeModulesSegment)
  * @see [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize)
  * @see [miniapp-publish](/reference/miniapp-publish/)
+ * @since 0.3.1
  */
 function shouldUploadDistFile(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
@@ -19220,7 +19154,6 @@ exports.createMiniappArtifactFileHeader = createMiniappArtifactFileHeader;
 exports.createMiniappArtifactSignatureHeader = createMiniappArtifactSignatureHeader;
 exports.getMiniProgramUploadAlias = getMiniProgramUploadAlias;
 exports.getMiniappMetadataWarnings = getMiniappMetadataWarnings;
-exports.getMiniappUploadKey = getMiniappUploadKey;
 exports.hasMiniappRuntimeGate = hasMiniappRuntimeGate;
 exports.isValidVersion = isValidMiniappManifestVersion;
 exports.normalizeBasicInfoName = normalizeBasicInfoName;
@@ -19239,5 +19172,4 @@ exports.validateMiniappManifestForDeploy = validateMiniappManifestForDeploy;
 exports.validateMiniappUploadPathLengths = validateMiniappUploadPathLengths;
 exports.validateMiniappUploadSizeBudgets = validateMiniappUploadSizeBudgets;
 exports.validateMiniappWorkspaceCardFileReceipts = validateMiniappWorkspaceCardFileReceipts;
-exports.validateUploadPaths = validateUploadPaths;
 exports.validateUploadTotalSize = validateUploadTotalSize;

package/dist/miniapp-publish.esm.js

@@ -6593,6 +6593,7 @@ function validateWorkspaceCardReceiptV2(raw, controller) {
  * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
  * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
  * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ * @since 0.8.3
  */
 function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category') {
     if (value === undefined)
@@ -9396,6 +9397,7 @@ const BASIC_INFO_MAX_PIXELS = 40_000_000;
  * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
  * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
  * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ * @since 0.8.2
  */
 function normalizeBasicInfoName(raw) {
     if (typeof raw !== 'string')
@@ -9427,6 +9429,7 @@ function validateBasicInfoPath(raw) {
  * @remarks
  * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
  * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ * @since 0.8.2
  */
 function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
     sdkVersion = sdkVersion.trim();
@@ -9499,6 +9502,7 @@ const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
  * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
  * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
  * @see [CLI 与远端发布](/guide/cli#生产构建)
+ * @since 0.8.1
  */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
@@ -9687,6 +9691,7 @@ const MINIAPP_WINDOW_ALLOWED_FIELDS = [...MINIAPP_WINDOW_NUMBER_FIELDS, 'resizab
  *
  * @see {@link resolveMiniappManifestPlatforms}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
+ * @since 0.3.1
  */
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
@@ -9707,6 +9712,7 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
  * @remarks
  * 不修改输入对象，不执行文件 I/O；不会验证图片/归档是否存在、内容摘要是否匹配，也不查询远端发布资格。
  * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
+ * @since 0.8.2
  */
 function validateMiniappManifestForDeploy(manifest) {
     const version = validateMiniappManifestVersion(manifest.version, 'manifest.version');
@@ -9880,6 +9886,7 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
  * @see {@link MINIAPP_LEGACY_DEFAULT_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}
+ * @since 0.8.1
  */
 function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
     if (!isRecord$1(manifest)) {
@@ -10077,6 +10084,7 @@ const BASIC_INFO_PLACEHOLDER_SHA256 = 'd14e54b30f5e6d1bcbf51267bc82b06a0af7c333f
  *   }
  * }
  * ```
+ * @since 0.8.2
  */
 async function previewMiniappBasicInfo(manifest, files) {
     const profile = parseMiniappBasicInfo(manifest, String(manifest.sdkVersion ?? ''));
@@ -18379,6 +18387,7 @@ const RUNTIME_GATE_BOOTSTRAP_MARKER = 'data-heybox-runtime-gate-bootstrap';
  * @param html - 待检查的完整 HTML 文本，使用 HTML parser 解析。
  * @returns Gate、隐藏样式及 bootstrap 标记均出现时返回 `true`，否则返回 `false`。
  * @remarks 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
+ * @since 0.8.2
  */
 function hasMiniappRuntimeGate(html) {
     const document = parse(html);
@@ -18511,6 +18520,7 @@ const textEncoder = new TextEncoder();
  * @see {@link relativePathContainsNodeModulesSegment}
  * @see {@link shouldUploadDistFile}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/protocol/functions/isMiniProgramRelativePath | isMiniProgramRelativePath}
+ * @since 0.3.1
  */
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
@@ -18541,6 +18551,7 @@ function normalizeRelativePath(relativePath) {
  * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
  * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
  * @see [miniapp-publish](/reference/miniapp-publish/)
+ * @since 0.3.1
  */
 function relativePathContainsNodeModulesSegment(relativePath) {
     return normalizeRelativePath(relativePath)
@@ -18568,85 +18579,6 @@ 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();
-    for (const item of items) {
-        const relativePath = String(item.relativePath ?? '');
-        const normalizedRelativePath = normalizeRelativePath(relativePath);
-        const invalidReason = getInvalidUploadPathReason(normalizedRelativePath);
-        if (invalidReason) {
-            return `构建产物文件路径不合法（${invalidReason}）：${JSON.stringify(relativePath)}`;
-        }
-        const key = getMiniappUploadKey({
-            miniProgramId: options.miniProgramId,
-            version: options.version,
-            relativePath: normalizedRelativePath,
-        });
-        if (uploadKeys.has(key)) {
-            return `构建产物文件路径重复，无法上传到同一位置：${JSON.stringify(relativePath)}`;
-        }
-        uploadKeys.add(key);
-        if (key.length > limit) {
-            return `文件路径过长，请缩短构建产物文件名或目录层级：${relativePath}`;
-        }
-    }
-    return undefined;
-}
-function getInvalidUploadPathReason(relativePath) {
-    const segments = relativePath.replace(/\\/g, '/').split('/');
-    if (segments.some((segment) => !segment)) {
-        return '包含空路径段';
-    }
-    if (segments.some((segment) => segment === '.')) {
-        return '包含当前目录';
-    }
-    if (segments.some((segment) => segment === '..')) {
-        return '包含上级目录';
-    }
-    if (/[\u0000-\u001F\u007F]/.test(relativePath)) {
-        return '包含控制字符';
-    }
-    return undefined;
-}
 /**
  * 校验一组构建产物的总大小是否超过给定上限。
  *
@@ -18703,6 +18635,7 @@ function getInvalidUploadPathReason(relativePath) {
  * @see {@link ValidateUploadTotalSizeOptions}
  * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
  * @see [miniapp-publish](/reference/miniapp-publish/)
+ * @since 0.4.7
  */
 function validateUploadTotalSize(items, options = {}) {
     const limit = options.limitBytes ?? MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES;
@@ -18795,6 +18728,7 @@ function validateMiniappUploadSizeBudgets(items, options = {}) {
  * @see [relativePathContainsNodeModulesSegment](/reference/symbols/miniapp-publish/functions/relativePathContainsNodeModulesSegment)
  * @see [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize)
  * @see [miniapp-publish](/reference/miniapp-publish/)
+ * @since 0.3.1
  */
 function shouldUploadDistFile(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
@@ -19182,4 +19116,4 @@ const LIST_USER_MINIPROGRAM_PERMISSION_APPLICATION_API_PATH = '/mall/developer/u
 /** 提交不绑定版本的平台权限申请。 */
 const SUBMIT_USER_MINIPROGRAM_PERMISSION_APPLICATION_API_PATH = '/mall/developer/user_miniprogram/runtime_permission/application_submit';
 
-export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_PERMISSION_APPLICATION_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES, MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES, MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, SUBMIT_USER_MINIPROGRAM_PERMISSION_APPLICATION_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, createMiniappArtifactFileHeader, createMiniappArtifactSignatureHeader, getMiniProgramUploadAlias, getMiniappMetadataWarnings, getMiniappUploadKey, hasMiniappRuntimeGate, isValidMiniappManifestVersion as isValidVersion, normalizeBasicInfoName, normalizeRelativePath, parseMiniappBasicInfo, parseMiniappBindAppIds, parseMiniappCategory, prepareMiniappArtifactFiles, previewMiniappBasicInfo, relativePathContainsNodeModulesSegment, resolveMiniappManifestPlatforms, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappCompanionFileReceipts, validateMiniappManifestForDeploy, validateMiniappUploadPathLengths, validateMiniappUploadSizeBudgets, validateMiniappWorkspaceCardFileReceipts, validateUploadPaths, validateUploadTotalSize };
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_PERMISSION_APPLICATION_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES, MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES, MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, SUBMIT_USER_MINIPROGRAM_PERMISSION_APPLICATION_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, createMiniappArtifactFileHeader, createMiniappArtifactSignatureHeader, getMiniProgramUploadAlias, getMiniappMetadataWarnings, hasMiniappRuntimeGate, isValidMiniappManifestVersion as isValidVersion, normalizeBasicInfoName, normalizeRelativePath, parseMiniappBasicInfo, parseMiniappBindAppIds, parseMiniappCategory, prepareMiniappArtifactFiles, previewMiniappBasicInfo, relativePathContainsNodeModulesSegment, resolveMiniappManifestPlatforms, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappCompanionFileReceipts, validateMiniappManifestForDeploy, validateMiniappUploadPathLengths, validateMiniappUploadSizeBudgets, validateMiniappWorkspaceCardFileReceipts, validateUploadTotalSize };