@heybox/hb-sdk 0.7.5-alpha.0 → 0.8.0-alpha

package/dist/index.esm.js

@@ -292,9 +292,9 @@ class HbMiniProgramSDKError extends Error {
 /**
  * 创建 SDK 标准错误。
  *
- * @param code 稳定错误码。
- * @param message 面向开发者的错误说明。
- * @param data 可选调试数据。
+ * @param code - 稳定错误码。
+ * @param message - 面向开发者的错误说明。
+ * @param data - 可选调试数据。
  * @returns 标准化 `HbMiniProgramSDKError` 实例。
  *
  * @remarks
@@ -314,7 +314,7 @@ function createSDKError(code, message, data) {
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
  * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
  *
- * @typeParam T 标准化响应数据的类型。
+ * @typeParam T - 标准化响应数据的类型。
  */
 class HbMiniProgramNetworkError extends Error {
     /** HTTP 状态码。 */
@@ -328,7 +328,7 @@ class HbMiniProgramNetworkError extends Error {
     /** 完整标准化响应。 */
     response;
     /**
-     * @param response 已完成请求的标准化网络响应。
+     * @param response - 已完成请求的标准化网络响应。
      */
     constructor(response) {
         const method = (response.config.method || 'GET').toUpperCase();
@@ -668,7 +668,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.5-alpha.0';
+    : '0.8.0-alpha';
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -1048,10 +1048,10 @@ function createCloudModule(requester) {
 /**
  * 复制当前小程序的通用分享链接。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 分享扩展数据；不传时复制默认首页链接。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 分享扩展数据；不传时复制默认首页链接。
  * @returns 已写入系统剪贴板的完整分享链接。
- * @throws {HbMiniProgramSDKError} 当参数、bridge、父容器或剪贴板能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当参数、bridge、父容器或剪贴板能力调用失败时抛出。
  */
 function copyLink(requester, options) {
     return requester.request(SHARE_COPY_LINK_METHOD, options);
@@ -2251,10 +2251,10 @@ function decodeBase64Url(value) {
 /**
  * 截图并唤起分享。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 截图区域、延迟与保存相册等配置。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 截图区域、延迟与保存相册等配置。
  * @returns 由宿主客户端协议决定的结果。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function screenshot(requester, options) {
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
@@ -2263,10 +2263,10 @@ function screenshot(requester, options) {
 /**
  * 展示基础分享面板。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 基础分享参数。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 基础分享参数。
  * @returns 由宿主客户端协议决定的结果。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function showShareMenu(requester, options) {
     return requester.request(SHARE_SHOW_SHARE_MENU_METHOD, options);
@@ -2275,25 +2275,25 @@ function showShareMenu(requester, options) {
 /**
  * 创建分享模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的分享模块对象。
  */
 function createShareModule(requester, launchHref) {
     return {
-        copyLink: options => copyLink(requester, options),
+        copyLink: (options) => copyLink(requester, options),
         getExtra: () => readMiniProgramShareExtra(launchHref),
-        showShareMenu: options => showShareMenu(requester, options),
-        screenshot: options => screenshot(requester, options),
+        showShareMenu: (options) => showShareMenu(requester, options),
+        screenshot: (options) => screenshot(requester, options),
     };
 }
 
 /**
  * 获取小程序隔离 storage。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 读取的 storage key。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 读取的 storage key。
  * @returns 对应 key 的标准化读取结果。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function getStorage(requester, options) {
     return requester.request(STORAGE_GET_STORAGE_METHOD, options);
@@ -2301,10 +2301,10 @@ function getStorage(requester, options) {
 /**
  * 写入小程序隔离 storage。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 要写入的 storage key 与数据。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 要写入的 storage key 与数据。
  * @returns 当写入完成后 resolve。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function setStorage(requester, options) {
     return requester.request(STORAGE_SET_STORAGE_METHOD, options);
@@ -2312,13 +2312,13 @@ function setStorage(requester, options) {
 /**
  * 创建 storage 模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的 storage 模块对象。
  */
 function createStorageModule(requester) {
     return {
-        getStorage: options => getStorage(requester, options),
-        setStorage: options => setStorage(requester, options),
+        getStorage: (options) => getStorage(requester, options),
+        setStorage: (options) => setStorage(requester, options),
     };
 }
 
@@ -2393,13 +2393,13 @@ function formatNetworkRequestFailureMessage(detail) {
     return `${detail.kind} ${detail.method} ${detail.url}${statusPart}${codePart}`;
 }
 
-const DEFAULT_VALIDATE_STATUS = status => status >= 200 && status < 300;
+const DEFAULT_VALIDATE_STATUS = (status) => status >= 200 && status < 300;
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
 }
 function clonePublicValue(value) {
     if (Array.isArray(value)) {
-        return value.map(item => clonePublicValue(item));
+        return value.map((item) => clonePublicValue(item));
     }
     if (isPlainObject(value)) {
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clonePublicValue(item)]));
@@ -2453,11 +2453,11 @@ function toNetworkResponse(payload, config) {
 /**
  * 发起网络请求并返回标准化响应。
  *
- * @param requester 底层 bridge 请求能力。
- * @param config 面向业务层的网络请求配置。
+ * @param requester - 底层 bridge 请求能力。
+ * @param config - 面向业务层的网络请求配置。
  * @returns 标准化网络响应。HTTP 2xx 默认返回 resolve。
- * @throws {HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
- * @throws {HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
  *
  * @remarks
  * `validateStatus` 仅在 SDK 侧执行，不会跨 bridge 传输函数值。
@@ -2475,7 +2475,7 @@ async function request(requester, config) {
     const validateStatus = config.validateStatus || DEFAULT_VALIDATE_STATUS;
     try {
         assertSupportedPublicNetworkRequest(config);
-        const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
+        const responsePayload = (await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config)));
         const response = toNetworkResponse(responsePayload, config);
         if (!validateStatus(response.status)) {
             const error = new HbMiniProgramNetworkError(response);
@@ -2527,21 +2527,21 @@ function assertSupportedPublicNetworkRequest(config) {
 /**
  * 创建 network 模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的网络模块对象。
  */
 function createNetworkModule(requester) {
     return {
-        request: config => request(requester, config),
+        request: (config) => request(requester, config),
     };
 }
 
 /**
  * 获取当前小程序窗口信息。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 当前小程序可用窗口信息。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function getWindowInfo(requester) {
     return requester.request(VIEWPORT_GET_WINDOW_INFO_METHOD);
@@ -2549,10 +2549,10 @@ function getWindowInfo(requester) {
 /**
  * 设置导航栏关闭按钮与状态栏图标/文字的前景样式。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 导航栏样式配置。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 导航栏样式配置。
  * @returns 宿主接受设置后 resolve。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function setNavigationBarStyle(requester, options) {
     return requester.request(VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, options);
@@ -2560,13 +2560,13 @@ function setNavigationBarStyle(requester, options) {
 /**
  * 创建 Viewport 模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的 Viewport 模块对象。
  */
 function createViewportModule(requester) {
     return {
         getWindowInfo: () => getWindowInfo(requester),
-        setNavigationBarStyle: options => setNavigationBarStyle(requester, options),
+        setNavigationBarStyle: (options) => setNavigationBarStyle(requester, options),
     };
 }
 
@@ -2579,7 +2579,7 @@ function createViewportModule(requester) {
  * `app_user_id`，并隐式授予 `identity` 与 `profile` 后返回昵称与头像，不展示授权 UI。未登录时返回
  * `{ isHeyboxAppLoggedIn: false, authorization: null, userInfo: null }`。
  *
- * @throws {HbMiniProgramSDKError} 当 SDK 调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 SDK 调用失败时抛出。
  */
 function getInfo(requester) {
     return requester.request(USER_GET_INFO_METHOD);
@@ -2592,8 +2592,8 @@ function revokeAuthorization(requester) {
 /**
  * 获取当前用户 Steam 游戏库。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 查询与分页参数。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 查询与分页参数。
  * @returns 当前用户 Steam 游戏库；未登录或未绑定 Steam 时返回状态对象。
  */
 function getSteamGameList(requester, options) {
@@ -2623,8 +2623,8 @@ function hideLoading(requester) {
 /** 创建 UI 模块。 */
 function createUiModule(requester) {
     return {
-        showToast: options => showToast(requester, options),
-        showLoading: options => showLoading(requester, options),
+        showToast: (options) => showToast(requester, options),
+        showLoading: (options) => showLoading(requester, options),
         hideLoading: () => hideLoading(requester),
     };
 }
@@ -2640,8 +2640,8 @@ function setClipboard(requester, options) {
 /** 创建设备能力模块。 */
 function createDeviceModule(requester) {
     return {
-        vibrate: options => vibrate(requester, options),
-        setClipboard: options => setClipboard(requester, options),
+        vibrate: (options) => vibrate(requester, options),
+        setClipboard: (options) => setClipboard(requester, options),
     };
 }
 
@@ -2752,7 +2752,7 @@ function createNavigationModule(requester) {
     return {
         close: () => close(requester),
         reload: () => reload(requester),
-        openAppPage: options => openAppPage(requester, options),
+        openAppPage: (options) => openAppPage(requester, options),
     };
 }
 
@@ -2815,8 +2815,8 @@ class MiniProgramSDK {
     /**
      * 注册小程序生命周期或业务事件。
      *
-     * @param eventName 要监听的事件名。
-     * @param handler 事件处理函数。
+     * @param eventName - 要监听的事件名。
+     * @param handler - 事件处理函数。
      * @returns 事件解绑函数。
      */
     on(eventName, handler) {
@@ -2825,8 +2825,8 @@ class MiniProgramSDK {
     /**
      * 移除小程序生命周期或业务事件。
      *
-     * @param eventName 要移除的事件名。
-     * @param handler 对应的事件处理函数。
+     * @param eventName - 要移除的事件名。
+     * @param handler - 对应的事件处理函数。
      */
     off(eventName, handler) {
         this.client.off(eventName, handler);
@@ -2845,7 +2845,7 @@ class MiniProgramSDK {
 /**
  * 创建独立 SDK 实例。
  *
- * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @param options - SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
  * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
  *
  * @remarks
@@ -2871,20 +2871,59 @@ function getDefaultSDK() {
     }
     return defaultSDK;
 }
-/** 获取默认 SDK 实例的当前握手状态。 */
+/**
+ * 获取默认 SDK 实例的当前握手状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 function getHandshakeState() {
     return getDefaultSDK().getHandshakeState();
 }
-/** 订阅默认 SDK 实例的握手状态，并立即接收当前状态。 */
+/**
+ * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 function onHandshakeStateChange(handler) {
     return getDefaultSDK().onHandshakeStateChange(handler);
 }
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName 要监听的事件名。
- * @param handler 事件处理函数。
+ * @param eventName - 要监听的事件名。
+ * @param handler - 事件处理函数。
  * @returns 事件解绑函数。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 function on(eventName, handler) {
     return getDefaultSDK().on(eventName, handler);
@@ -2892,9 +2931,20 @@ function on(eventName, handler) {
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName 要移除的事件名。
- * @param handler 对应的事件处理函数。
+ * @param eventName - 要移除的事件名。
+ * @param handler - 对应的事件处理函数。
  * @returns 无返回值。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 function off(eventName, handler) {
     getDefaultSDK().off(eventName, handler);

package/dist/miniapp-publish.cjs.js

@@ -2937,7 +2937,7 @@ function shouldUploadDistFile(relativePath) {
 /**
  * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
  *
- * @param files 待处理的构建产物文件。
+ * @param files - 待处理的构建产物文件。
  * @returns 保留输入附加字段的有序文件列表。
  * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
  */
@@ -2946,7 +2946,7 @@ function prepareMiniappArtifactFiles(files) {
         throw new Error('构建产物文件数量超出签名协议上限');
     }
     const usedPaths = new Set();
-    const prepared = files.map(file => {
+    const prepared = files.map((file) => {
         const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
         if (usedPaths.has(relativePath)) {
             throw new Error(`构建产物包含重复文件路径：${relativePath}`);
@@ -2960,15 +2960,15 @@ function prepareMiniappArtifactFiles(files) {
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files 待上传的构建产物文件。
- * @param options 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件。
+ * @param options - 小程序和长度限制配置。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
  */
 function validateMiniappUploadPathLengths(files, options) {
     const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
     const prefix = `/u/${getMiniProgramUploadAlias(options.miniProgramId)}/${'x'.repeat(MINIAPP_UPLOAD_SESSION_REF_LENGTH)}/`;
     const prefixLength = textEncoder.encode(prefix).length;
-    const tooLongFile = files.find(file => {
+    const tooLongFile = files.find((file) => {
         const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
         return prefixLength + textEncoder.encode(relativePath).length > maxLength;
     });
@@ -2977,7 +2977,7 @@ function validateMiniappUploadPathLengths(files, options) {
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount 参与签名的文件数量。
+ * @param fileCount - 参与签名的文件数量。
  * @returns 包含协议标识和文件数量的字节数组。
  * @throws 文件数量超出协议范围时抛出错误。
  */
@@ -2990,7 +2990,7 @@ function createMiniappArtifactSignatureHeader(fileCount) {
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file 已规范化或待校验的构建产物文件。
+ * @param file - 已规范化或待校验的构建产物文件。
  * @returns 包含路径长度、路径和文件大小的字节数组。
  * @throws 文件路径或大小非法时抛出错误。
  */
@@ -3003,9 +3003,9 @@ function createMiniappArtifactFileHeader(file) {
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles 本地构建产物文件。
- * @param serverFiles 服务端签发的文件映射。
- * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @param localFiles - 本地构建产物文件。
+ * @param serverFiles - 服务端签发的文件映射。
+ * @param uploadedKeys - 服务端已确认上传成功的 key。
  * @returns 完整映射、待上传文件和已确认 key。
  * @throws 服务端映射与本地产物不一致时抛出错误。
  */
@@ -3037,7 +3037,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         serverSizes.set(relativePath, size);
         knownKeys.add(key);
     }
-    const files = preparedFiles.map(file => {
+    const files = preparedFiles.map((file) => {
         const key = mappings.get(file.relativePath);
         if (!key) {
             throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
@@ -3057,7 +3057,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
     }
     return {
         files,
-        missingFiles: files.filter(file => !completed.has(file.key)),
+        missingFiles: files.filter((file) => !completed.has(file.key)),
         uploadedKeys: [...completed],
     };
 }
@@ -3075,7 +3075,7 @@ function normalizeMiniappArtifactRelativePath(relativePath) {
     if (containsControlCharacter(value) || UNPAIRED_SURROGATE_PATTERN.test(value)) {
         throw new Error(`构建产物路径包含非法字符：${value}`);
     }
-    if (value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+    if (value.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
         throw new Error(`构建产物路径包含非法目录段：${value}`);
     }
     if (value.includes(',')) {

package/dist/miniapp-publish.esm.js

@@ -2935,7 +2935,7 @@ function shouldUploadDistFile(relativePath) {
 /**
  * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
  *
- * @param files 待处理的构建产物文件。
+ * @param files - 待处理的构建产物文件。
  * @returns 保留输入附加字段的有序文件列表。
  * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
  */
@@ -2944,7 +2944,7 @@ function prepareMiniappArtifactFiles(files) {
         throw new Error('构建产物文件数量超出签名协议上限');
     }
     const usedPaths = new Set();
-    const prepared = files.map(file => {
+    const prepared = files.map((file) => {
         const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
         if (usedPaths.has(relativePath)) {
             throw new Error(`构建产物包含重复文件路径：${relativePath}`);
@@ -2958,15 +2958,15 @@ function prepareMiniappArtifactFiles(files) {
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files 待上传的构建产物文件。
- * @param options 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件。
+ * @param options - 小程序和长度限制配置。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
  */
 function validateMiniappUploadPathLengths(files, options) {
     const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
     const prefix = `/u/${getMiniProgramUploadAlias(options.miniProgramId)}/${'x'.repeat(MINIAPP_UPLOAD_SESSION_REF_LENGTH)}/`;
     const prefixLength = textEncoder.encode(prefix).length;
-    const tooLongFile = files.find(file => {
+    const tooLongFile = files.find((file) => {
         const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
         return prefixLength + textEncoder.encode(relativePath).length > maxLength;
     });
@@ -2975,7 +2975,7 @@ function validateMiniappUploadPathLengths(files, options) {
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount 参与签名的文件数量。
+ * @param fileCount - 参与签名的文件数量。
  * @returns 包含协议标识和文件数量的字节数组。
  * @throws 文件数量超出协议范围时抛出错误。
  */
@@ -2988,7 +2988,7 @@ function createMiniappArtifactSignatureHeader(fileCount) {
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file 已规范化或待校验的构建产物文件。
+ * @param file - 已规范化或待校验的构建产物文件。
  * @returns 包含路径长度、路径和文件大小的字节数组。
  * @throws 文件路径或大小非法时抛出错误。
  */
@@ -3001,9 +3001,9 @@ function createMiniappArtifactFileHeader(file) {
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles 本地构建产物文件。
- * @param serverFiles 服务端签发的文件映射。
- * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @param localFiles - 本地构建产物文件。
+ * @param serverFiles - 服务端签发的文件映射。
+ * @param uploadedKeys - 服务端已确认上传成功的 key。
  * @returns 完整映射、待上传文件和已确认 key。
  * @throws 服务端映射与本地产物不一致时抛出错误。
  */
@@ -3035,7 +3035,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         serverSizes.set(relativePath, size);
         knownKeys.add(key);
     }
-    const files = preparedFiles.map(file => {
+    const files = preparedFiles.map((file) => {
         const key = mappings.get(file.relativePath);
         if (!key) {
             throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
@@ -3055,7 +3055,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
     }
     return {
         files,
-        missingFiles: files.filter(file => !completed.has(file.key)),
+        missingFiles: files.filter((file) => !completed.has(file.key)),
         uploadedKeys: [...completed],
     };
 }
@@ -3073,7 +3073,7 @@ function normalizeMiniappArtifactRelativePath(relativePath) {
     if (containsControlCharacter(value) || UNPAIRED_SURROGATE_PATTERN.test(value)) {
         throw new Error(`构建产物路径包含非法字符：${value}`);
     }
-    if (value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+    if (value.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
         throw new Error(`构建产物路径包含非法目录段：${value}`);
     }
     if (value.includes(',')) {

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -1,5 +1,7 @@
 # <%= projectName %>
 
+`vite.config.ts` 中的 `miniappManifest({ platforms })` 声明本项目承诺适配的平台。模板预填的 `android`、`ios`、`ohos` 只是初始配置；发布前请按实际目标调整，并在每个声明的平台完成真机验收。
+
 这是通过 `hb-sdk create` 生成的小黑盒工坊小程序模板。项目使用 Vue 3、Vite、TypeScript 和 `@heybox/hb-sdk`。
 
 ## 使用命令

package/dist/templates/vue3-vite-ts/vite.config.ts

@@ -4,5 +4,5 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [vue(), miniappManifest()],
+  plugins: [vue(), miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
 });