@heybox/hb-sdk 0.8.1-alpha.14 → 0.8.1-alpha.16

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-mfGqyKpq.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-C1GHFN_L.js">
+    <script type="module" crossorigin src="/assets/index-BqskekK_.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-CvKi6AqK.js">
     <link rel="stylesheet" crossorigin href="/assets/index-DXd5IZBz.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -835,7 +835,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.14';
+    : '0.8.1-alpha.16';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/index.esm.js

@@ -831,7 +831,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.14';
+    : '0.8.1-alpha.16';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/miniapp-publish.cjs.js

@@ -2785,9 +2785,123 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+function parseMiniappBindAppIds(value, options = {}) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error(`${sourceLabel} 必须是字符串数组`);
+    if (value.length > MINIAPP_BIND_APP_IDS_MAX_COUNT) {
+        throw new Error(`${sourceLabel} 最多包含 ${MINIAPP_BIND_APP_IDS_MAX_COUNT} 个游戏 appid`);
+    }
+    const seen = new Set();
+    const appIds = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !/^[1-9]\d*$/.test(item)) {
+            throw new Error(`${sourceLabel} 包含非法游戏 appid：${String(item)}`);
+        }
+        const numeric = Number(item);
+        if (!Number.isSafeInteger(numeric) || numeric > 2_147_483_647) {
+            throw new Error(`${sourceLabel} 包含超出正 int32 范围的游戏 appid：${item}`);
+        }
+        if (seen.has(item))
+            throw new Error(`${sourceLabel} 包含重复游戏 appid：${item}`);
+        seen.add(item);
+        appIds.push(item);
+    }
+    appIds.sort((left, right) => Number(left) - Number(right));
+    return Object.freeze(appIds);
+}
+
+const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
+/** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
+const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = '0.9.0';
+/**
+ * 历史移动端兼容平台集合。
+ *
+ * @remarks
+ * 仅在 `sdkVersion` 缺失或 SemVer precedence 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`，
+ * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
+ */
+const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
 }
+function validateMiniappPlatforms(platforms, sourceLabel = 'platforms') {
+    if (!Array.isArray(platforms) || platforms.length === 0) {
+        throw new Error(`${sourceLabel} 必须是非空平台数组`);
+    }
+    const allowedPlatforms = new Set(MINIAPP_PLATFORM_VALUES);
+    const seen = new Set();
+    for (const platform of platforms) {
+        if (typeof platform !== 'string' || !allowedPlatforms.has(platform)) {
+            throw new Error(`${sourceLabel} 包含不支持的平台：${String(platform)}`);
+        }
+        if (seen.has(platform)) {
+            throw new Error(`${sourceLabel} 包含重复平台：${platform}`);
+        }
+        seen.add(platform);
+    }
+    return Object.freeze(MINIAPP_PLATFORM_VALUES.filter((platform) => seen.has(platform)));
+}
+const NO_MINIAPP_PLATFORMS = Object.freeze([]);
+/**
+ * 解析 Manifest 平台声明，是 `0.9.0` 硬切规则的唯一实现。
+ *
+ * @remarks
+ * 规则与后端领域层保持一致：
+ * - 无 `platforms` 字段：`sdkVersion` 缺失或 SemVer precedence 低于
+ *   `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION` 时按历史移动端兼容；达到或高于硬切点即非法。
+ * - 有 `platforms` 字段：复用 `validateMiniappPlatforms` 校验并规范化顺序；任何非法值
+ *   （空数组、非数组、未知值、重复值）都不回退到历史兼容，即使 `sdkVersion < 0.9.0`。
+ * - 任何非法的 `sdkVersion` 都会抛出，不做字符串比较。
+ * @param sdkVersion - 产物 hb-sdk 版本；历史产物可能缺失。
+ * @param manifest - 待解析的 Manifest（不可信输入）。
+ * @returns 冻结的平台解析结果。
+ * @throws Manifest 不是对象、`sdkVersion` 不是合法 SemVer、达到硬切点仍缺失 `platforms`，
+ *   或 `platforms` 声明非法时抛出。
+ */
+function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
+    if (!isRecord$1(manifest)) {
+        throw new Error('manifest 必须是 JSON 对象');
+    }
+    // 与后端 ResolvePlatforms 对齐：空串/纯空白按“缺失 SDK 版本”处理（历史产物），不报错。
+    const trimmedSdkVersion = typeof sdkVersion === 'string' ? sdkVersion.trim() : undefined;
+    const normalizedSdkVersion = trimmedSdkVersion ? validateSdkVersion(trimmedSdkVersion) : undefined;
+    if (Object.prototype.hasOwnProperty.call(manifest, 'platforms')) {
+        const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+        return Object.freeze({
+            declared: platforms,
+            effective: platforms,
+            platformsDeclared: true,
+            policy: 'explicit',
+        });
+    }
+    if (normalizedSdkVersion === undefined || semverExports.lt(normalizedSdkVersion, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION)) {
+        return Object.freeze({
+            declared: NO_MINIAPP_PLATFORMS,
+            effective: MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES,
+            platformsDeclared: false,
+            policy: 'legacy_mobile_default',
+        });
+    }
+    throw new Error(`manifest.platforms 缺失：hb-sdk ${MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION} 起必须显式声明非空 platforms（当前 ${normalizedSdkVersion}）`);
+}
+function validateSdkVersion(version, sourceLabel = 'sdkVersion') {
+    if (typeof version !== 'string' || version.trim() === '') {
+        throw new Error(`${sourceLabel} 必须是合法 SemVer：${String(version)}`);
+    }
+    const normalized = version.trim();
+    const parsed = semverExports.parse(normalized);
+    if (!parsed || parsed.version !== normalized || parsed.build.length > 0) {
+        throw new Error(`${sourceLabel} 必须是合法 SemVer：${normalized}`);
+    }
+    return normalized;
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function getMiniappManifestVersionError(version) {
     if (typeof version !== 'string' || version.trim() === '') {
         return `必须是合法 SemVer：${String(version)}`;
@@ -3202,6 +3316,8 @@ exports.LIST_USER_MINIPROGRAM_API_PATH = LIST_USER_MINIPROGRAM_API_PATH;
 exports.LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH;
 exports.LIST_USER_MINIPROGRAM_VERSION_API_PATH = LIST_USER_MINIPROGRAM_VERSION_API_PATH;
 exports.MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES = MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES;
+exports.MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES;
+exports.MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION;
 exports.MINIAPP_UPLOAD_BATCH_SIZE = MINIAPP_UPLOAD_BATCH_SIZE;
 exports.MINIAPP_UPLOAD_SCOPE = MINIAPP_UPLOAD_SCOPE;
 exports.MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES = MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES;
@@ -3222,8 +3338,10 @@ exports.getMiniProgramUploadAlias = getMiniProgramUploadAlias;
 exports.getMiniappUploadKey = getMiniappUploadKey;
 exports.isValidVersion = isValidMiniappManifestVersion;
 exports.normalizeRelativePath = normalizeRelativePath;
+exports.parseMiniappBindAppIds = parseMiniappBindAppIds;
 exports.prepareMiniappArtifactFiles = prepareMiniappArtifactFiles;
 exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
+exports.resolveMiniappManifestPlatforms = resolveMiniappManifestPlatforms;
 exports.resolveMiniappUploadSessionFiles = resolveMiniappUploadSessionFiles;
 exports.shouldUploadDistFile = shouldUploadDistFile;
 exports.validateMiniappCompanionFileReceipts = validateMiniappCompanionFileReceipts;

package/dist/miniapp-publish.esm.js

@@ -2783,9 +2783,123 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+function parseMiniappBindAppIds(value, options = {}) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error(`${sourceLabel} 必须是字符串数组`);
+    if (value.length > MINIAPP_BIND_APP_IDS_MAX_COUNT) {
+        throw new Error(`${sourceLabel} 最多包含 ${MINIAPP_BIND_APP_IDS_MAX_COUNT} 个游戏 appid`);
+    }
+    const seen = new Set();
+    const appIds = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !/^[1-9]\d*$/.test(item)) {
+            throw new Error(`${sourceLabel} 包含非法游戏 appid：${String(item)}`);
+        }
+        const numeric = Number(item);
+        if (!Number.isSafeInteger(numeric) || numeric > 2_147_483_647) {
+            throw new Error(`${sourceLabel} 包含超出正 int32 范围的游戏 appid：${item}`);
+        }
+        if (seen.has(item))
+            throw new Error(`${sourceLabel} 包含重复游戏 appid：${item}`);
+        seen.add(item);
+        appIds.push(item);
+    }
+    appIds.sort((left, right) => Number(left) - Number(right));
+    return Object.freeze(appIds);
+}
+
+const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
+/** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
+const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = '0.9.0';
+/**
+ * 历史移动端兼容平台集合。
+ *
+ * @remarks
+ * 仅在 `sdkVersion` 缺失或 SemVer precedence 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`，
+ * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
+ */
+const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
 }
+function validateMiniappPlatforms(platforms, sourceLabel = 'platforms') {
+    if (!Array.isArray(platforms) || platforms.length === 0) {
+        throw new Error(`${sourceLabel} 必须是非空平台数组`);
+    }
+    const allowedPlatforms = new Set(MINIAPP_PLATFORM_VALUES);
+    const seen = new Set();
+    for (const platform of platforms) {
+        if (typeof platform !== 'string' || !allowedPlatforms.has(platform)) {
+            throw new Error(`${sourceLabel} 包含不支持的平台：${String(platform)}`);
+        }
+        if (seen.has(platform)) {
+            throw new Error(`${sourceLabel} 包含重复平台：${platform}`);
+        }
+        seen.add(platform);
+    }
+    return Object.freeze(MINIAPP_PLATFORM_VALUES.filter((platform) => seen.has(platform)));
+}
+const NO_MINIAPP_PLATFORMS = Object.freeze([]);
+/**
+ * 解析 Manifest 平台声明，是 `0.9.0` 硬切规则的唯一实现。
+ *
+ * @remarks
+ * 规则与后端领域层保持一致：
+ * - 无 `platforms` 字段：`sdkVersion` 缺失或 SemVer precedence 低于
+ *   `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION` 时按历史移动端兼容；达到或高于硬切点即非法。
+ * - 有 `platforms` 字段：复用 `validateMiniappPlatforms` 校验并规范化顺序；任何非法值
+ *   （空数组、非数组、未知值、重复值）都不回退到历史兼容，即使 `sdkVersion < 0.9.0`。
+ * - 任何非法的 `sdkVersion` 都会抛出，不做字符串比较。
+ * @param sdkVersion - 产物 hb-sdk 版本；历史产物可能缺失。
+ * @param manifest - 待解析的 Manifest（不可信输入）。
+ * @returns 冻结的平台解析结果。
+ * @throws Manifest 不是对象、`sdkVersion` 不是合法 SemVer、达到硬切点仍缺失 `platforms`，
+ *   或 `platforms` 声明非法时抛出。
+ */
+function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
+    if (!isRecord$1(manifest)) {
+        throw new Error('manifest 必须是 JSON 对象');
+    }
+    // 与后端 ResolvePlatforms 对齐：空串/纯空白按“缺失 SDK 版本”处理（历史产物），不报错。
+    const trimmedSdkVersion = typeof sdkVersion === 'string' ? sdkVersion.trim() : undefined;
+    const normalizedSdkVersion = trimmedSdkVersion ? validateSdkVersion(trimmedSdkVersion) : undefined;
+    if (Object.prototype.hasOwnProperty.call(manifest, 'platforms')) {
+        const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+        return Object.freeze({
+            declared: platforms,
+            effective: platforms,
+            platformsDeclared: true,
+            policy: 'explicit',
+        });
+    }
+    if (normalizedSdkVersion === undefined || semverExports.lt(normalizedSdkVersion, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION)) {
+        return Object.freeze({
+            declared: NO_MINIAPP_PLATFORMS,
+            effective: MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES,
+            platformsDeclared: false,
+            policy: 'legacy_mobile_default',
+        });
+    }
+    throw new Error(`manifest.platforms 缺失：hb-sdk ${MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION} 起必须显式声明非空 platforms（当前 ${normalizedSdkVersion}）`);
+}
+function validateSdkVersion(version, sourceLabel = 'sdkVersion') {
+    if (typeof version !== 'string' || version.trim() === '') {
+        throw new Error(`${sourceLabel} 必须是合法 SemVer：${String(version)}`);
+    }
+    const normalized = version.trim();
+    const parsed = semverExports.parse(normalized);
+    if (!parsed || parsed.version !== normalized || parsed.build.length > 0) {
+        throw new Error(`${sourceLabel} 必须是合法 SemVer：${normalized}`);
+    }
+    return normalized;
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function getMiniappManifestVersionError(version) {
     if (typeof version !== 'string' || version.trim() === '') {
         return `必须是合法 SemVer：${String(version)}`;
@@ -3187,4 +3301,4 @@ function compareBytes(left, right) {
     return left.length - right.length;
 }
 
-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_VERSION_API_PATH, MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES, 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, 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, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, prepareMiniappArtifactFiles, relativePathContainsNodeModulesSegment, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappCompanionFileReceipts, validateMiniappUploadPathLengths, validateMiniappUploadSizeBudgets, 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_VERSION_API_PATH, MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES, 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, 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, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, parseMiniappBindAppIds, prepareMiniappArtifactFiles, relativePathContainsNodeModulesSegment, resolveMiniappManifestPlatforms, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappCompanionFileReceipts, validateMiniappUploadPathLengths, validateMiniappUploadSizeBudgets, validateUploadPaths, validateUploadTotalSize };

package/dist/vite.cjs.js

@@ -11,7 +11,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.14';
+    : '0.8.1-alpha.16';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3116,6 +3116,35 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+function parseMiniappBindAppIds(value, options = {}) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error(`${sourceLabel} 必须是字符串数组`);
+    if (value.length > MINIAPP_BIND_APP_IDS_MAX_COUNT) {
+        throw new Error(`${sourceLabel} 最多包含 ${MINIAPP_BIND_APP_IDS_MAX_COUNT} 个游戏 appid`);
+    }
+    const seen = new Set();
+    const appIds = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !/^[1-9]\d*$/.test(item)) {
+            throw new Error(`${sourceLabel} 包含非法游戏 appid：${String(item)}`);
+        }
+        const numeric = Number(item);
+        if (!Number.isSafeInteger(numeric) || numeric > 2_147_483_647) {
+            throw new Error(`${sourceLabel} 包含超出正 int32 范围的游戏 appid：${item}`);
+        }
+        if (seen.has(item))
+            throw new Error(`${sourceLabel} 包含重复游戏 appid：${item}`);
+        seen.add(item);
+        appIds.push(item);
+    }
+    appIds.sort((left, right) => Number(left) - Number(right));
+    return Object.freeze(appIds);
+}
+
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
@@ -3351,6 +3380,7 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
     const window = validateMiniappWindow(manifest.window, 'manifest.window');
+    const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
@@ -3358,6 +3388,7 @@ function renderMiniappManifest(manifest) {
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
         ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
         ...(window === undefined ? {} : { window }),
+        ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -3519,6 +3550,11 @@ function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
         sdkVersion,
     });
 }
+function readMiniappBindAppIdsFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return parseMiniappBindAppIds(heybox?.bindAppIds);
+}
 function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
@@ -13302,6 +13338,7 @@ function miniappManifest() {
             const windowDeclaration = readMiniappWindowFromPackageJson(root);
             const companionConfig = readMiniappCompanionsFromPackageJson(root);
             const companionDeclarations = includeCompanions ? companionConfig.declarations : undefined;
+            const bindAppIds = readMiniappBindAppIdsFromPackageJson(root);
             if (!parsedPermissions.declared)
                 this.warn(getMissingPermissionsWarning());
             if (companionDeclarations && !parsedPermissions.permissions?.companion) {
@@ -13330,6 +13367,7 @@ function miniappManifest() {
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
                 ...(companions === undefined ? {} : { companions }),
                 ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
+                ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
             }));
         },
     };

package/dist/vite.esm.js

@@ -8,7 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.14';
+    : '0.8.1-alpha.16';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3113,6 +3113,35 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+function parseMiniappBindAppIds(value, options = {}) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error(`${sourceLabel} 必须是字符串数组`);
+    if (value.length > MINIAPP_BIND_APP_IDS_MAX_COUNT) {
+        throw new Error(`${sourceLabel} 最多包含 ${MINIAPP_BIND_APP_IDS_MAX_COUNT} 个游戏 appid`);
+    }
+    const seen = new Set();
+    const appIds = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !/^[1-9]\d*$/.test(item)) {
+            throw new Error(`${sourceLabel} 包含非法游戏 appid：${String(item)}`);
+        }
+        const numeric = Number(item);
+        if (!Number.isSafeInteger(numeric) || numeric > 2_147_483_647) {
+            throw new Error(`${sourceLabel} 包含超出正 int32 范围的游戏 appid：${item}`);
+        }
+        if (seen.has(item))
+            throw new Error(`${sourceLabel} 包含重复游戏 appid：${item}`);
+        seen.add(item);
+        appIds.push(item);
+    }
+    appIds.sort((left, right) => Number(left) - Number(right));
+    return Object.freeze(appIds);
+}
+
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
@@ -3348,6 +3377,7 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
     const window = validateMiniappWindow(manifest.window, 'manifest.window');
+    const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
@@ -3355,6 +3385,7 @@ function renderMiniappManifest(manifest) {
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
         ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
         ...(window === undefined ? {} : { window }),
+        ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -3516,6 +3547,11 @@ function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
         sdkVersion,
     });
 }
+function readMiniappBindAppIdsFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return parseMiniappBindAppIds(heybox?.bindAppIds);
+}
 function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
@@ -13299,6 +13335,7 @@ function miniappManifest() {
             const windowDeclaration = readMiniappWindowFromPackageJson(root);
             const companionConfig = readMiniappCompanionsFromPackageJson(root);
             const companionDeclarations = includeCompanions ? companionConfig.declarations : undefined;
+            const bindAppIds = readMiniappBindAppIdsFromPackageJson(root);
             if (!parsedPermissions.declared)
                 this.warn(getMissingPermissionsWarning());
             if (companionDeclarations && !parsedPermissions.permissions?.companion) {
@@ -13327,6 +13364,7 @@ function miniappManifest() {
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
                 ...(companions === undefined ? {} : { companions }),
                 ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
+                ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
             }));
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.1-alpha.14",
+  "version": "0.8.1-alpha.16",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.1-alpha.14"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.16"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -113,9 +113,9 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.14",
+    "@heybox-domain/heybox-theme": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.16",
     "@heybox/hb-api": "~1.28.3",
     "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",

package/skill/SKILL.md

@@ -66,20 +66,21 @@ Apply these instructions when writing, reviewing, or debugging code that consume
    For real PC Companion debugging, configure local artifacts in `package.json#heybox.companions`, keep `miniappManifest()` enabled, bind the project, and ensure COA has approved `companion`. `hb-sdk dev` validates immutable snapshots without requiring an upload; config or artifact changes rotate the snapshot while existing Sessions retain their original artifact. Prepare and launch the new artifact explicitly. Check separate Browser, Mobile and PC Companion readiness in the debugging workbench. Without a local declaration, use Browser Fake only for state/UI integration.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
 5. Declare the actual supported platforms in `package.json#heybox.platforms` and keep the no-argument `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the declaration, Manifest, or Runtime gate output is missing or inconsistent.
-6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
-7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
-8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
-9. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
-10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
-11. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
-12. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
-13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the current version declares and the platform approves `network`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
-14. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
-15. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
-16. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
-17. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
-18. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
-19. Do not print or expose cookies, tokens, private headers, or other credentials.
+6. When a released version should be discoverable from specific PC game workspaces, declare canonical decimal string appids in `package.json#heybox.bindAppIds` (maximum 20). This is version metadata, not a Runtime permission. Missing or empty clears bindings; `--from-version` inherits the source artifact snapshot.
+7. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
+8. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
+9. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
+10. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
+11. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
+12. Use `hb-sdk remote info` to compare local/current/added/removed game bindings, and use `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management. These commands do not edit game bindings.
+13. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
+14. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the current version declares and the platform approves `network`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
+15. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
+16. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
+17. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
+18. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
+19. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
+20. Do not print or expose cookies, tokens, private headers, or other credentials.
 
 ## Step 6: Preserve capability boundaries
 

package/skill/references/api-protocol.md

@@ -301,10 +301,10 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 | --- | ---: | ---: | ---: | ---: | ---: |
 | Root API | 2 | 4 | 75 | 73 | 3 |
 | Protocol API | 0 | 13 | 58 | 90 | 47 |
-| Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
+| Miniapp Publish API | 0 | 7 | 4 | 1 | 2 |
 | Vite API | 0 | 1 | 5 | 1 | 3 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=7356ab1376630f8bed1028cf9fca72895fc3a1603b8742280c265c53fdeff423 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=67370783f01088c3ba37e6506e18d075924b7966e0b53aa3ce82b38bac1a33f3 -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -27,7 +27,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.1-alpha.14`
+- Version at generation time: `0.8.1-alpha.16`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -328,6 +328,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
+`hb-sdk remote info` 会只读展示 `package.json#heybox.bindAppIds`、当前线上绑定以及新增/移除差异。修改绑定必须更新项目配置并重新提交版本；CLI、Open 和 COA 都不提供第二个写入入口。普通 deploy 在上传文件前把实际构建 Manifest 交给服务端预检；`--from-version` 只使用源版本快照。
+
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
 推荐由项目的 `scripts.build` 保留类型检查：

package/skill/references/cli.md

@@ -172,6 +172,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
+`hb-sdk remote info` 会只读展示 `package.json#heybox.bindAppIds`、当前线上绑定以及新增/移除差异。修改绑定必须更新项目配置并重新提交版本；CLI、Open 和 COA 都不提供第二个写入入口。普通 deploy 在上传文件前把实际构建 Manifest 交给服务端预检；`--from-version` 只使用源版本快照。
+
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
 推荐由项目的 `scripts.build` 保留类型检查：

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.1-alpha.14+skill.63b05480eba4",
+  "skillVersion": "0.8.1-alpha.16+skill.40a9aaafe9bf",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.14",
-    "compatibility": "0.8.1-alpha.14"
+    "version": "0.8.1-alpha.16",
+    "compatibility": "0.8.1-alpha.16"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.14",
+    "version": "0.8.1-alpha.16",
     "path": "skill"
   },
-  "integrity": "sha256-63b05480eba4af0e9aeb126196230250ec8349fa1d84e84ebac8005fabe3a602"
+  "integrity": "sha256-40a9aaafe9bf39ee033c27c149c7bcfff2f5e7c9674796d1b1ac24f7df9ea81c"
 }

package/types/miniapp-manifest/bindings.d.ts

@@ -0,0 +1,5 @@
+export declare const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+export interface ParseMiniappBindAppIdsOptions {
+    sourceLabel?: string;
+}
+export declare function parseMiniappBindAppIds(value: unknown, options?: ParseMiniappBindAppIdsOptions): readonly string[];