@heybox/hb-sdk 0.9.2-alpha.7 → 0.9.2-alpha.9

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);
@@ -18408,6 +18417,27 @@ function walk(node, visit) {
         walk(node.content, visit);
 }
 
+/** 根据当前项目声明或实际版本 Manifest 检查资料完整性，不联网、不修改输入。 */
+function getMiniappMetadataWarnings(metadata) {
+    const warnings = [];
+    if (metadata.desc === undefined || (typeof metadata.desc === 'string' && !metadata.desc.trim())) {
+        warnings.push({
+            code: 'MINIAPP_DESC_MISSING',
+            field: 'desc',
+            message: '尚未填写小程序简介。建议在 package.json#heybox.desc 中说明主要功能和适用场景，修改后重新构建。',
+        });
+    }
+    if (metadata.category === 'tool' &&
+        (metadata.bindAppIds === undefined || (Array.isArray(metadata.bindAppIds) && metadata.bindAppIds.length === 0))) {
+        warnings.push({
+            code: 'MINIAPP_TOOL_GAME_BINDING_MISSING',
+            field: 'bindAppIds',
+            message: '当前小程序为工具类，尚未关联游戏。如服务于特定 PC 游戏，可通过 hb-sdk remote games search "游戏名" 查询 appid 并填写 package.json#heybox.bindAppIds，修改后重新构建；通用工具可保持为空。',
+        });
+    }
+    return warnings;
+}
+
 /** CDN 上传接口使用的小程序产物业务 scope。 */
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 /** 完整 CDN 上传 key 的默认长度上限；旧固定版本流程按字符计数，上传会话流程按 UTF-8 bytes 计数。 */
@@ -18490,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 || '')
@@ -18520,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)
@@ -18547,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;
-}
 /**
  * 校验一组构建产物的总大小是否超过给定上限。
  *
@@ -18682,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;
@@ -18774,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);
@@ -19161,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, 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 };

package/dist/protocol.cjs.js

@@ -504,6 +504,7 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
  * @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))
@@ -588,6 +589,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('/')) {
@@ -654,6 +656,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))
@@ -720,6 +723,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')
@@ -787,6 +791,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')
@@ -861,6 +866,7 @@ function isMiniProgramDirectoryRef(value) {
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 校验后由 SDK 建立的文件代理。
  * @see [PickFilesResult](/reference/symbols/protocol/types/PickFilesResult) picker 的 direct-ref 文件结果。
  * @see [SaveFileResult](/reference/symbols/protocol/types/SaveFileResult) save picker 的 direct-ref 文件结果。
+ * @since 0.8.0
  */
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$3(value) &&
@@ -931,6 +937,7 @@ function isMiniProgramFileDescriptor(value) {
  * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) `files` 公开能力入口。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 校验后由 SDK 建立的目录代理。
  * @see [PickDirectoryResult](/reference/symbols/protocol/types/PickDirectoryResult) picker 的 direct-ref 返回契约。
+ * @since 0.8.0
  */
 function isMiniProgramDirectoryDescriptor(value) {
     return (isRecord$3(value) &&
@@ -996,6 +1003,7 @@ function isMiniProgramDirectoryDescriptor(value) {
  * @see [FileSystemEntity](/reference/symbols/root/types/FileSystemEntity) SDK 公开的 FileHandle/DirectoryHandle 联合。
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 文件 descriptor 对应的能力代理。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 目录 descriptor 对应的能力代理及 `list()` 入口。
+ * @since 0.8.0
  */
 function isMiniProgramFileSystemEntityDescriptor(value) {
     return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
@@ -1051,6 +1059,7 @@ function isMiniProgramFileSystemEntityDescriptor(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;
@@ -1110,6 +1119,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) &&
@@ -1170,6 +1180,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) ||
@@ -1296,6 +1307,7 @@ const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(MINI_PROGRAM_PERMISSION_KEYS);
  * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 完整 snapshot 的 trim、legacy 归一化与 config 校验。
  * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) method 到 permission requirement 的权威映射。
  * @see [权限声明](/guide/permissions) Manifest 声明、平台批准与 Runtime 状态的完整流程。
+ * @since 0.6.4
  */
 function isManagedMiniProgramRuntimePermissionKey(key) {
     return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
@@ -1371,6 +1383,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * @see {@link isManagedMiniProgramRuntimePermissionKey}
  * @see {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+ * @since 0.6.4
  */
 function parseMiniProgramRuntimePermissions(snapshot) {
     if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {

package/dist/protocol.esm.js

@@ -502,6 +502,7 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
  * @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))
@@ -586,6 +587,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('/')) {
@@ -652,6 +654,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))
@@ -718,6 +721,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')
@@ -785,6 +789,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')
@@ -859,6 +864,7 @@ function isMiniProgramDirectoryRef(value) {
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 校验后由 SDK 建立的文件代理。
  * @see [PickFilesResult](/reference/symbols/protocol/types/PickFilesResult) picker 的 direct-ref 文件结果。
  * @see [SaveFileResult](/reference/symbols/protocol/types/SaveFileResult) save picker 的 direct-ref 文件结果。
+ * @since 0.8.0
  */
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$3(value) &&
@@ -929,6 +935,7 @@ function isMiniProgramFileDescriptor(value) {
  * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) `files` 公开能力入口。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 校验后由 SDK 建立的目录代理。
  * @see [PickDirectoryResult](/reference/symbols/protocol/types/PickDirectoryResult) picker 的 direct-ref 返回契约。
+ * @since 0.8.0
  */
 function isMiniProgramDirectoryDescriptor(value) {
     return (isRecord$3(value) &&
@@ -994,6 +1001,7 @@ function isMiniProgramDirectoryDescriptor(value) {
  * @see [FileSystemEntity](/reference/symbols/root/types/FileSystemEntity) SDK 公开的 FileHandle/DirectoryHandle 联合。
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 文件 descriptor 对应的能力代理。
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 目录 descriptor 对应的能力代理及 `list()` 入口。
+ * @since 0.8.0
  */
 function isMiniProgramFileSystemEntityDescriptor(value) {
     return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
@@ -1049,6 +1057,7 @@ function isMiniProgramFileSystemEntityDescriptor(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;
@@ -1108,6 +1117,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) &&
@@ -1168,6 +1178,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) ||
@@ -1294,6 +1305,7 @@ const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(MINI_PROGRAM_PERMISSION_KEYS);
  * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 完整 snapshot 的 trim、legacy 归一化与 config 校验。
  * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) method 到 permission requirement 的权威映射。
  * @see [权限声明](/guide/permissions) Manifest 声明、平台批准与 Runtime 状态的完整流程。
+ * @since 0.6.4
  */
 function isManagedMiniProgramRuntimePermissionKey(key) {
     return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
@@ -1369,6 +1381,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * @see {@link isManagedMiniProgramRuntimePermissionKey}
  * @see {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+ * @since 0.6.4
  */
 function parseMiniProgramRuntimePermissions(snapshot) {
     if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {

package/dist/templates/vanilla-vite-js/README.md.ejs

@@ -14,6 +14,10 @@ npm run deploy -- --release-note "更新说明"
 
 `package.json#heybox.category` 初始声明为 `other`（其他）。发布前请按实际用途选择 `tool`（工具）、`game`（游戏）或 `other`（其他）；该字段为必填，修改后需重新构建。
 
+发布前请补充 `package.json#heybox.desc`，描述已实现的主要功能和适用场景。模板不预填简介，以免占位文案被当作真实介绍发布。
+
+如果小程序服务于特定 PC 游戏，可运行 `npm run hb-sdk -- remote games search "游戏名" --json` 查询平台游戏 appid，核对结果后填写 `package.json#heybox.bindAppIds`（字符串数组）。工具类应主动检查，通用工具可保持为空。关联游戏随版本审核，修改后需重新构建；能否绑定以部署预检为准。
+
 `package.json#heybox.platforms` 默认声明全平台 `android`、`ios`、`ohos`、`windows`、`macos`，请按项目实际完成适配并验收的平台保留，未适配的平台务必删除。`linux` 目前没有客户端基线与 API 兼容声明，暂不建议声明。
 
 更多内容见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli) 和 [SDK 文档](https://docs.xiaoheihe.cn/hb_sdk/)。

package/dist/vite.cjs.js

@@ -15,6 +15,27 @@ var node_zlib = require('node:zlib');
 var node_async_hooks = require('node:async_hooks');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/** 根据当前项目声明或实际版本 Manifest 检查资料完整性，不联网、不修改输入。 */
+function getMiniappMetadataWarnings(metadata) {
+    const warnings = [];
+    if (metadata.desc === undefined || (typeof metadata.desc === 'string' && !metadata.desc.trim())) {
+        warnings.push({
+            code: 'MINIAPP_DESC_MISSING',
+            field: 'desc',
+            message: '尚未填写小程序简介。建议在 package.json#heybox.desc 中说明主要功能和适用场景，修改后重新构建。',
+        });
+    }
+    if (metadata.category === 'tool' &&
+        (metadata.bindAppIds === undefined || (Array.isArray(metadata.bindAppIds) && metadata.bindAppIds.length === 0))) {
+        warnings.push({
+            code: 'MINIAPP_TOOL_GAME_BINDING_MISSING',
+            field: 'bindAppIds',
+            message: '当前小程序为工具类，尚未关联游戏。如服务于特定 PC 游戏，可通过 hb-sdk remote games search "游戏名" 查询 appid 并填写 package.json#heybox.bindAppIds，修改后重新构建；通用工具可保持为空。',
+        });
+    }
+    return warnings;
+}
+
 /**
  * 所有小程序 iframe bridge envelope 共用的固定 namespace。
  *
@@ -10120,6 +10141,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')
@@ -10151,6 +10173,7 @@ function validateBasicInfoPath(raw) {
  * @remarks
  * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
  * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ * @since 0.8.2
  */
 function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
     sdkVersion = sdkVersion.trim();
@@ -10281,7 +10304,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.2-alpha.7';
+    : '0.9.2-alpha.9';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -10654,6 +10677,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';
@@ -10690,6 +10714,7 @@ function parseMiniappBindAppIds(value, options = {}) {
  * @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)
@@ -20637,6 +20662,7 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  * @see [权限声明](/guide/permissions) `heybox.permissions` 严格 schema 与迁移规则。
  * @see [窗口尺寸与可缩放性](/guide/window-size) `heybox.window` 字段与 Host 消费语义。
  * @see [受管桌面程序](/guide/companion) Companion 声明、归档和本地联调边界。
+ * @since 0.3.1
  */
 function miniappManifest() {
     const includeCompanions = process.env.HB_SDK_SKIP_COMPANIONS !== '1';
@@ -20650,6 +20676,7 @@ function miniappManifest() {
     let hmrWebSocketUrl;
     let configuredDeviceLogUploadUrls = [];
     let devServer;
+    let metadataWarningsShown = false;
     /** 构建链路中更早的失败原因；closeBundle 不得再用产物校验覆盖它。 */
     let priorBuildError;
     return {
@@ -20685,7 +20712,7 @@ function miniappManifest() {
             devServer = server;
             // 开发期只对「仍是旧模板移动端默认」的声明做非阻断提示。声明缺失或非法一律交由
             // build / remote deploy 链路拒绝，因此这里只容忍读取阶段的异常，保持 hb-sdk dev
-            // 既有的启动语义；warn 调用留在 try 之外，避免把插件上下文错误一起吞掉。
+            // 既有的启动语义；日志调用使用服务配置中的 logger，兼容没有插件上下文的 Vite 版本。
             let legacyMobileTemplate = false;
             try {
                 legacyMobileTemplate = isLegacyMobileTemplatePlatforms(readMiniappPlatformsFromPackageJson(root));
@@ -20694,7 +20721,22 @@ function miniappManifest() {
                 /* package.json#heybox.platforms 缺失或非法时不提示。 */
             }
             if (legacyMobileTemplate)
-                this.warn(getLegacyMobileTemplatePlatformsNotice());
+                server.config.logger.warn(getLegacyMobileTemplatePlatformsNotice());
+            if (!metadataWarningsShown) {
+                // 开发期读取失败不改变启动行为；非法声明仍由构建与提审校验。
+                let warnings = [];
+                try {
+                    warnings = getMiniappMetadataWarnings({
+                        desc: readMiniappDescFromPackageJson(root),
+                        category: readMiniappCategoryFromPackageJson(root),
+                        bindAppIds: readMiniappBindAppIdsFromPackageJson(root),
+                    });
+                }
+                catch { /* 读取失败不推断为缺失。 */ }
+                for (const warning of warnings)
+                    server.config.logger.warn(`[${warning.code}] ${warning.message}`);
+                metadataWarningsShown = true;
+            }
             let unregisterLogs;
             const registerLogs = () => {
                 const address = server.httpServer?.address();
@@ -21068,6 +21110,12 @@ function miniappManifest() {
             if (workspaceCards && 'runtimeVersion' in workspaceCards && Buffer.byteLength(manifestText, 'utf8') > WORKSPACE_CARDS_V2_MANIFEST_MAX_BYTES)
                 throw new Error('小程序 Manifest 超过 256 KiB');
             node_fs.writeFileSync(manifestPath, manifestText);
+            // deploy 子进程将提示交给父进程按最终提交 Manifest 输出，避免重复并保留自定义构建兜底。
+            if (process.env.HB_SDK_DEFER_METADATA_WARNINGS !== '1') {
+                for (const warning of getMiniappMetadataWarnings({ desc, category, bindAppIds })) {
+                    this.warn(`[${warning.code}] ${warning.message}`);
+                }
+            }
         },
     };
 }