@heybox/hb-sdk 0.8.0 → 0.8.1-alpha.10

package/dist/miniapp-publish.cjs.js

@@ -2813,6 +2813,8 @@ const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const MINIAPP_UPLOAD_BATCH_SIZE = 50;
 const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES = 100 * 1024 * 1024;
+/** 与 Activity 上传后端合同一致的 Companion 归档总大小上限。 */
+const MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES = 500 * 1024 * 1024;
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
 const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
 const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
@@ -2918,6 +2920,18 @@ function validateUploadTotalSize(items, options = {}) {
     }
     return undefined;
 }
+function validateMiniappUploadSizeBudgets(items, options = {}) {
+    const companionItems = items.filter((item) => normalizeRelativePath(item.relativePath).startsWith('companions/'));
+    const webItems = items.filter((item) => !normalizeRelativePath(item.relativePath).startsWith('companions/'));
+    const webError = validateUploadTotalSize(webItems, { limitBytes: options.webLimitBytes ?? MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES });
+    if (webError)
+        return webError;
+    const companionTotal = companionItems.reduce((sum, item) => sum + (Number.isFinite(item.size) && item.size > 0 ? item.size : 0), 0);
+    const companionLimit = options.companionLimitBytes ?? MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES;
+    if (companionTotal > companionLimit)
+        return 'Companion 归档总大小超过 500MiB 上限，请缩减归档后重新 deploy';
+    return undefined;
+}
 function shouldUploadDistFile(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
     if (!normalized) {
@@ -3016,6 +3030,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
     }
     const mappings = new Map();
     const serverSizes = new Map();
+    const serverHashes = new Map();
     const knownKeys = new Set();
     for (const serverFile of serverFiles) {
         const relativePath = normalizeMiniappArtifactRelativePath(serverFile.relative_path);
@@ -3033,8 +3048,13 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         if (!Number.isSafeInteger(size) || size < 0) {
             throw new Error(`上传会话返回文件大小异常：${relativePath}`);
         }
+        const sha256 = String(serverFile.sha256 || '');
+        if (!/^[a-f0-9]{64}$/.test(sha256)) {
+            throw new Error(`上传会话返回文件 SHA-256 异常：${relativePath}`);
+        }
         mappings.set(relativePath, key);
         serverSizes.set(relativePath, size);
+        serverHashes.set(relativePath, sha256);
         knownKeys.add(key);
     }
     const files = preparedFiles.map((file) => {
@@ -3045,6 +3065,9 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         if (serverSizes.get(file.relativePath) !== file.size) {
             throw new Error(`上传会话文件大小与本地构建不一致：${file.relativePath}`);
         }
+        if (!('sha256' in file) || serverHashes.get(file.relativePath) !== file.sha256) {
+            throw new Error(`上传会话文件 SHA-256 与本地构建不一致：${file.relativePath}`);
+        }
         return { file, key };
     });
     const completed = new Set();
@@ -3061,6 +3084,41 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         uploadedKeys: [...completed],
     };
 }
+/** 校验 Manifest 中所有 Companion 归档都精确属于当前上传 receipt。 */
+function validateMiniappCompanionFileReceipts(companions, files) {
+    const companionFiles = new Map(files.filter((file) => file.relativePath.startsWith('companions/')).map((file) => [file.relativePath, file]));
+    if (companions === undefined) {
+        if (companionFiles.size > 0)
+            throw new Error('dist 包含未被 manifest.companions 引用的 Companion 归档');
+        return;
+    }
+    if (!isRecord(companions))
+        throw new Error('manifest.companions 必须是对象');
+    const referenced = new Set();
+    for (const definition of Object.values(companions)) {
+        if (!isRecord(definition) || !isRecord(definition.targets))
+            throw new Error('manifest.companions targets 不合法');
+        for (const artifact of Object.values(definition.targets)) {
+            if (!isRecord(artifact) || typeof artifact.path !== 'string' || typeof artifact.size !== 'number' || typeof artifact.sha256 !== 'string') {
+                throw new Error('manifest.companions artifact 不合法');
+            }
+            const file = companionFiles.get(artifact.path);
+            if (!file)
+                throw new Error(`manifest.companions 引用的归档不在当前上传 receipt：${artifact.path}`);
+            if (file.size !== artifact.size)
+                throw new Error(`Companion 归档大小与 manifest 不一致：${artifact.path}`);
+            if (file.sha256 !== artifact.sha256)
+                throw new Error(`Companion 归档 SHA-256 与 manifest 不一致：${artifact.path}`);
+            referenced.add(artifact.path);
+        }
+    }
+    const extra = [...companionFiles.keys()].find((relativePath) => !referenced.has(relativePath));
+    if (extra)
+        throw new Error(`Companion 归档未被 manifest.companions 引用：${extra}`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function normalizeMiniappArtifactRelativePath(relativePath) {
     const value = String(relativePath || '');
     if (!value) {
@@ -3143,6 +3201,7 @@ exports.DEVELOPER_ENTITY_SWITCH_API_PATH = DEVELOPER_ENTITY_SWITCH_API_PATH;
 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_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;
@@ -3167,6 +3226,8 @@ exports.prepareMiniappArtifactFiles = prepareMiniappArtifactFiles;
 exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
 exports.resolveMiniappUploadSessionFiles = resolveMiniappUploadSessionFiles;
 exports.shouldUploadDistFile = shouldUploadDistFile;
+exports.validateMiniappCompanionFileReceipts = validateMiniappCompanionFileReceipts;
 exports.validateMiniappUploadPathLengths = validateMiniappUploadPathLengths;
+exports.validateMiniappUploadSizeBudgets = validateMiniappUploadSizeBudgets;
 exports.validateUploadPaths = validateUploadPaths;
 exports.validateUploadTotalSize = validateUploadTotalSize;

package/dist/miniapp-publish.esm.js

@@ -2811,6 +2811,8 @@ const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const MINIAPP_UPLOAD_BATCH_SIZE = 50;
 const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES = 100 * 1024 * 1024;
+/** 与 Activity 上传后端合同一致的 Companion 归档总大小上限。 */
+const MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES = 500 * 1024 * 1024;
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
 const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
 const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
@@ -2916,6 +2918,18 @@ function validateUploadTotalSize(items, options = {}) {
     }
     return undefined;
 }
+function validateMiniappUploadSizeBudgets(items, options = {}) {
+    const companionItems = items.filter((item) => normalizeRelativePath(item.relativePath).startsWith('companions/'));
+    const webItems = items.filter((item) => !normalizeRelativePath(item.relativePath).startsWith('companions/'));
+    const webError = validateUploadTotalSize(webItems, { limitBytes: options.webLimitBytes ?? MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES });
+    if (webError)
+        return webError;
+    const companionTotal = companionItems.reduce((sum, item) => sum + (Number.isFinite(item.size) && item.size > 0 ? item.size : 0), 0);
+    const companionLimit = options.companionLimitBytes ?? MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES;
+    if (companionTotal > companionLimit)
+        return 'Companion 归档总大小超过 500MiB 上限，请缩减归档后重新 deploy';
+    return undefined;
+}
 function shouldUploadDistFile(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
     if (!normalized) {
@@ -3014,6 +3028,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
     }
     const mappings = new Map();
     const serverSizes = new Map();
+    const serverHashes = new Map();
     const knownKeys = new Set();
     for (const serverFile of serverFiles) {
         const relativePath = normalizeMiniappArtifactRelativePath(serverFile.relative_path);
@@ -3031,8 +3046,13 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         if (!Number.isSafeInteger(size) || size < 0) {
             throw new Error(`上传会话返回文件大小异常：${relativePath}`);
         }
+        const sha256 = String(serverFile.sha256 || '');
+        if (!/^[a-f0-9]{64}$/.test(sha256)) {
+            throw new Error(`上传会话返回文件 SHA-256 异常：${relativePath}`);
+        }
         mappings.set(relativePath, key);
         serverSizes.set(relativePath, size);
+        serverHashes.set(relativePath, sha256);
         knownKeys.add(key);
     }
     const files = preparedFiles.map((file) => {
@@ -3043,6 +3063,9 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         if (serverSizes.get(file.relativePath) !== file.size) {
             throw new Error(`上传会话文件大小与本地构建不一致：${file.relativePath}`);
         }
+        if (!('sha256' in file) || serverHashes.get(file.relativePath) !== file.sha256) {
+            throw new Error(`上传会话文件 SHA-256 与本地构建不一致：${file.relativePath}`);
+        }
         return { file, key };
     });
     const completed = new Set();
@@ -3059,6 +3082,41 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         uploadedKeys: [...completed],
     };
 }
+/** 校验 Manifest 中所有 Companion 归档都精确属于当前上传 receipt。 */
+function validateMiniappCompanionFileReceipts(companions, files) {
+    const companionFiles = new Map(files.filter((file) => file.relativePath.startsWith('companions/')).map((file) => [file.relativePath, file]));
+    if (companions === undefined) {
+        if (companionFiles.size > 0)
+            throw new Error('dist 包含未被 manifest.companions 引用的 Companion 归档');
+        return;
+    }
+    if (!isRecord(companions))
+        throw new Error('manifest.companions 必须是对象');
+    const referenced = new Set();
+    for (const definition of Object.values(companions)) {
+        if (!isRecord(definition) || !isRecord(definition.targets))
+            throw new Error('manifest.companions targets 不合法');
+        for (const artifact of Object.values(definition.targets)) {
+            if (!isRecord(artifact) || typeof artifact.path !== 'string' || typeof artifact.size !== 'number' || typeof artifact.sha256 !== 'string') {
+                throw new Error('manifest.companions artifact 不合法');
+            }
+            const file = companionFiles.get(artifact.path);
+            if (!file)
+                throw new Error(`manifest.companions 引用的归档不在当前上传 receipt：${artifact.path}`);
+            if (file.size !== artifact.size)
+                throw new Error(`Companion 归档大小与 manifest 不一致：${artifact.path}`);
+            if (file.sha256 !== artifact.sha256)
+                throw new Error(`Companion 归档 SHA-256 与 manifest 不一致：${artifact.path}`);
+            referenced.add(artifact.path);
+        }
+    }
+    const extra = [...companionFiles.keys()].find((relativePath) => !referenced.has(relativePath));
+    if (extra)
+        throw new Error(`Companion 归档未被 manifest.companions 引用：${extra}`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function normalizeMiniappArtifactRelativePath(relativePath) {
     const value = String(relativePath || '');
     if (!value) {
@@ -3129,4 +3187,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_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, validateMiniappUploadPathLengths, 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_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 };

package/dist/protocol.cjs.js

@@ -1,5 +1,14 @@
 'use strict';
 
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
+const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
+const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
+
 const AUTH_LOGIN_METHOD = 'auth.login';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
@@ -41,6 +50,18 @@ const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList';
 const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry';
 const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry';
 const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo';
+const COMPANION_GET_INFO_METHOD = 'companion.getInfo';
+const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus';
+const COMPANION_PREPARE_METHOD = 'companion.prepare';
+const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation';
+const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession';
+const COMPANION_LAUNCH_METHOD = 'companion.launch';
+const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write';
+const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin';
+const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate';
+const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
+const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
+const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     {
         method: AUTH_LOGIN_METHOD,
@@ -287,17 +308,28 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['leaderboard'] },
         risk: 'low',
     },
+    ...[
+        COMPANION_GET_INFO_METHOD,
+        COMPANION_GET_PREPARATION_STATUS_METHOD,
+        COMPANION_PREPARE_METHOD,
+        COMPANION_CANCEL_PREPARATION_METHOD,
+        COMPANION_GET_ACTIVE_SESSION_METHOD,
+        COMPANION_LAUNCH_METHOD,
+        COMPANION_SESSION_WRITE_METHOD,
+        COMPANION_SESSION_CLOSE_STDIN_METHOD,
+        COMPANION_SESSION_TERMINATE_METHOD,
+        COMPANION_SESSION_ACK_OUTPUT_METHOD,
+        COMPANION_OPEN_ATTACHMENT_METHOD,
+        COMPANION_SHOW_NOTIFICATION_METHOD,
+    ].map((method) => ({
+        method,
+        module: 'companion',
+        capability: method,
+        requirement: { kind: 'all', permissions: ['companion'] },
+        risk: 'high',
+    })),
 ];
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
-const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
-const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
-const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
-const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
-
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$1(value))
         return false;
@@ -319,7 +351,7 @@ function isMiniProgramBridgeMessage(value) {
         if (!isNonEmptyString(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
         return value.id === undefined || isNonEmptyString(value.id);
     }
@@ -357,7 +389,7 @@ function isMiniProgramDirectoryRef(value) {
     if (isNonEmptyString(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
-    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+    return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$1(value) &&
@@ -400,6 +432,24 @@ function isMiniProgramDownloadProgressPayload(value) {
         return value.total === undefined;
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
+function isMiniProgramCompanionPrepareProgress(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.phase === 'downloading') {
+        return (isNonNegativeSafeInteger(value.loaded) &&
+            (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+            hasOnlyKeys(value, ['phase', 'loaded', 'total']));
+    }
+    if (value.phase !== 'verifying' && value.phase !== 'extracting')
+        return false;
+    return (isNonNegativeSafeInteger(value.processed) &&
+        isNonNegativeSafeInteger(value.total) &&
+        value.processed <= value.total &&
+        hasOnlyKeys(value, ['phase', 'processed', 'total']));
+}
+function isMiniProgramOperationProgressPayload(value) {
+    return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
 function isSDKHandshakePayload(value) {
     return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }
@@ -438,6 +488,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 new Set(MINI_PROGRAM_PERMISSION_KEYS);
 
@@ -465,8 +516,8 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         seenKeys.add(key);
         if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-            if (!isRecord(rawEntry.config))
-                return { valid: false, permissions: {} };
+            // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+            // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
             continue;
         }
         if (key === 'network') {

package/dist/protocol.esm.js

@@ -1,3 +1,12 @@
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
+const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
+const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
+
 const AUTH_LOGIN_METHOD = 'auth.login';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
@@ -39,6 +48,18 @@ const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList';
 const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry';
 const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry';
 const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo';
+const COMPANION_GET_INFO_METHOD = 'companion.getInfo';
+const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus';
+const COMPANION_PREPARE_METHOD = 'companion.prepare';
+const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation';
+const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession';
+const COMPANION_LAUNCH_METHOD = 'companion.launch';
+const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write';
+const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin';
+const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate';
+const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
+const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
+const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     {
         method: AUTH_LOGIN_METHOD,
@@ -285,17 +306,28 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['leaderboard'] },
         risk: 'low',
     },
+    ...[
+        COMPANION_GET_INFO_METHOD,
+        COMPANION_GET_PREPARATION_STATUS_METHOD,
+        COMPANION_PREPARE_METHOD,
+        COMPANION_CANCEL_PREPARATION_METHOD,
+        COMPANION_GET_ACTIVE_SESSION_METHOD,
+        COMPANION_LAUNCH_METHOD,
+        COMPANION_SESSION_WRITE_METHOD,
+        COMPANION_SESSION_CLOSE_STDIN_METHOD,
+        COMPANION_SESSION_TERMINATE_METHOD,
+        COMPANION_SESSION_ACK_OUTPUT_METHOD,
+        COMPANION_OPEN_ATTACHMENT_METHOD,
+        COMPANION_SHOW_NOTIFICATION_METHOD,
+    ].map((method) => ({
+        method,
+        module: 'companion',
+        capability: method,
+        requirement: { kind: 'all', permissions: ['companion'] },
+        risk: 'high',
+    })),
 ];
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
-const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
-const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
-const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
-const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
-
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$1(value))
         return false;
@@ -317,7 +349,7 @@ function isMiniProgramBridgeMessage(value) {
         if (!isNonEmptyString(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
         return value.id === undefined || isNonEmptyString(value.id);
     }
@@ -355,7 +387,7 @@ function isMiniProgramDirectoryRef(value) {
     if (isNonEmptyString(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
-    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+    return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$1(value) &&
@@ -398,6 +430,24 @@ function isMiniProgramDownloadProgressPayload(value) {
         return value.total === undefined;
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
+function isMiniProgramCompanionPrepareProgress(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.phase === 'downloading') {
+        return (isNonNegativeSafeInteger(value.loaded) &&
+            (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+            hasOnlyKeys(value, ['phase', 'loaded', 'total']));
+    }
+    if (value.phase !== 'verifying' && value.phase !== 'extracting')
+        return false;
+    return (isNonNegativeSafeInteger(value.processed) &&
+        isNonNegativeSafeInteger(value.total) &&
+        value.processed <= value.total &&
+        hasOnlyKeys(value, ['phase', 'processed', 'total']));
+}
+function isMiniProgramOperationProgressPayload(value) {
+    return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
 function isSDKHandshakePayload(value) {
     return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }
@@ -436,6 +486,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 new Set(MINI_PROGRAM_PERMISSION_KEYS);
 
@@ -463,8 +514,8 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         seenKeys.add(key);
         if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-            if (!isRecord(rawEntry.config))
-                return { valid: false, permissions: {} };
+            // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+            // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
             continue;
         }
         if (key === 'network') {

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

@@ -9,6 +9,6 @@ npm run build
 npm run deploy -- --release-note "更新说明"
 ```
 
-`vite.config.js` 默认声明 `android`、`ios`、`ohos`。发布前请在每个声明的平台完成真机验收；需要支持桌面平台时，由项目自行加入并验收。
+`package.json#heybox.platforms` 默认声明 `android`、`ios`、`ohos`。发布前请在每个声明的平台完成真机验收；需要支持桌面平台时，由项目自行加入并验收。
 
 更多内容见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli) 和 [SDK 文档](https://docs.xiaoheihe.cn/hb_sdk/)。

package/dist/templates/vanilla-vite-js/package.json.ejs

@@ -5,6 +5,7 @@
   "type": "module",
   "heybox": {
     "miniProgramId": "",
+    "platforms": ["android", "ios", "ohos"],
     "permissions": {}
   },
   "scripts": {

package/dist/templates/vanilla-vite-js/vite.config.js

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