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

package/dist/protocol.esm.js

@@ -10,6 +10,22 @@ const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle
 const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
 const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
 const NETWORK_REQUEST_METHOD = 'network.request';
+const NETWORK_DOWNLOAD_METHOD = 'network.download';
+const FILES_PICK_FILES_METHOD = 'files.pickFiles';
+const FILES_PICK_DIRECTORY_METHOD = 'files.pickDirectory';
+const FILES_SAVE_FILE_METHOD = 'files.saveFile';
+const FILE_CREATE_METHOD = 'file.create';
+const FILE_REMOVE_METHOD = 'file.remove';
+const FILE_EXISTS_METHOD = 'file.exists';
+const FILE_READ_TEXT_METHOD = 'file.readText';
+const FILE_WRITE_TEXT_METHOD = 'file.writeText';
+const FILE_READ_BYTES_METHOD = 'file.readBytes';
+const FILE_WRITE_BYTES_METHOD = 'file.writeBytes';
+const FILE_STAT_METHOD = 'file.stat';
+const DIRECTORY_CREATE_METHOD = 'directory.create';
+const DIRECTORY_REMOVE_METHOD = 'directory.remove';
+const DIRECTORY_EXISTS_METHOD = 'directory.exists';
+const DIRECTORY_LIST_METHOD = 'directory.list';
 const UI_SHOW_TOAST_METHOD = 'ui.showToast';
 const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
 const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
@@ -60,6 +76,46 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     { method: STORAGE_GET_STORAGE_METHOD, module: 'storage', capability: STORAGE_GET_STORAGE_METHOD, permission: 'storage.read', risk: 'low' },
     { method: STORAGE_SET_STORAGE_METHOD, module: 'storage', capability: STORAGE_SET_STORAGE_METHOD, permission: 'storage.write', risk: 'medium' },
     { method: NETWORK_REQUEST_METHOD, module: 'network', capability: NETWORK_REQUEST_METHOD, permission: 'network.request', risk: 'high' },
+    { method: NETWORK_DOWNLOAD_METHOD, module: 'network', capability: NETWORK_DOWNLOAD_METHOD, permission: 'network.request', risk: 'high' },
+    { method: FILES_PICK_FILES_METHOD, module: 'files', capability: FILES_PICK_FILES_METHOD, permission: 'files.external', risk: 'high' },
+    {
+        method: FILES_PICK_DIRECTORY_METHOD,
+        module: 'files',
+        capability: FILES_PICK_DIRECTORY_METHOD,
+        permission: 'files.external',
+        risk: 'high',
+    },
+    { method: FILES_SAVE_FILE_METHOD, module: 'files', capability: FILES_SAVE_FILE_METHOD, permission: 'files.external', risk: 'high' },
+    { method: FILE_CREATE_METHOD, module: 'file', capability: FILE_CREATE_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_REMOVE_METHOD, module: 'file', capability: FILE_REMOVE_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_EXISTS_METHOD, module: 'file', capability: FILE_EXISTS_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_READ_TEXT_METHOD, module: 'file', capability: FILE_READ_TEXT_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_WRITE_TEXT_METHOD, module: 'file', capability: FILE_WRITE_TEXT_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_READ_BYTES_METHOD, module: 'file', capability: FILE_READ_BYTES_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_WRITE_BYTES_METHOD, module: 'file', capability: FILE_WRITE_BYTES_METHOD, permission: 'files.access', risk: 'high' },
+    { method: FILE_STAT_METHOD, module: 'file', capability: FILE_STAT_METHOD, permission: 'files.access', risk: 'high' },
+    {
+        method: DIRECTORY_CREATE_METHOD,
+        module: 'directory',
+        capability: DIRECTORY_CREATE_METHOD,
+        permission: 'files.access',
+        risk: 'high',
+    },
+    {
+        method: DIRECTORY_REMOVE_METHOD,
+        module: 'directory',
+        capability: DIRECTORY_REMOVE_METHOD,
+        permission: 'files.access',
+        risk: 'high',
+    },
+    {
+        method: DIRECTORY_EXISTS_METHOD,
+        module: 'directory',
+        capability: DIRECTORY_EXISTS_METHOD,
+        permission: 'files.access',
+        risk: 'high',
+    },
+    { method: DIRECTORY_LIST_METHOD, module: 'directory', capability: DIRECTORY_LIST_METHOD, permission: 'files.access', risk: 'high' },
     { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, permission: 'ui.toast', risk: 'low' },
     { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
     { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
@@ -124,15 +180,134 @@ 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 (!value || typeof value !== 'object')
+    if (!isRecord$1(value))
+        return false;
+    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
         return false;
-    const message = value;
-    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
-        (message.version === 1 || message.version === 2) &&
-        typeof message.nonce === 'string' &&
-        typeof message.type === 'string');
+    }
+    if (value.type === 'handshake') {
+        return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+    }
+    if (value.type === 'request') {
+        return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+    }
+    if (value.type === 'response') {
+        return (isNonEmptyString(value.id) &&
+            (value.method === undefined || isNonEmptyString(value.method)) &&
+            (value.error === undefined || isBridgeError(value.error)));
+    }
+    if (value.type === 'event') {
+        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.id === undefined || isNonEmptyString(value.id);
+    }
+    if (value.type === 'cancel') {
+        return (value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
+    }
+    return false;
+}
+function isMiniProgramRelativePath(value) {
+    if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
+        return false;
+    }
+    if (/[\\\u0000-\u001f\u007f]/.test(value))
+        return false;
+    return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
+}
+function isMiniProgramPathRootRef(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.kind === 'sandbox')
+        return hasOnlyKeys(value, ['kind']);
+    return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+}
+function isMiniProgramFileRef(value) {
+    if (!isRecord$1(value) || value.kind !== 'file')
+        return false;
+    if (isNonEmptyString(value.handleId)) {
+        return hasOnlyKeys(value, ['kind', 'handleId']);
+    }
+    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+}
+function isMiniProgramDirectoryRef(value) {
+    if (!isRecord$1(value) || value.kind !== 'directory')
+        return false;
+    if (isNonEmptyString(value.handleId)) {
+        return hasOnlyKeys(value, ['kind', 'handleId']);
+    }
+    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+}
+function isMiniProgramFileDescriptor(value) {
+    return (isRecord$1(value) &&
+        value.kind === 'file' &&
+        isNonEmptyString(value.name) &&
+        isFileMode(value.mode) &&
+        isMiniProgramFileRef(value.ref) &&
+        hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
+}
+function isMiniProgramDirectoryDescriptor(value) {
+    return (isRecord$1(value) &&
+        value.kind === 'directory' &&
+        isNonEmptyString(value.name) &&
+        isFileMode(value.mode) &&
+        isMiniProgramDirectoryRef(value.ref) &&
+        hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
+}
+function isMiniProgramFileSystemEntityDescriptor(value) {
+    return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
+}
+function isMiniProgramByteArray(value) {
+    return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
+}
+function isMiniProgramFileStat(value) {
+    return (isRecord$1(value) &&
+        value.kind === 'file' &&
+        isNonNegativeSafeInteger(value.size) &&
+        (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
+        (value.createdAt === undefined || isNonNegativeFiniteNumber(value.createdAt)) &&
+        hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
+}
+function isMiniProgramDownloadProgressPayload(value) {
+    if (!isRecord$1(value) ||
+        !isNonNegativeSafeInteger(value.loaded) ||
+        typeof value.lengthComputable !== 'boolean' ||
+        !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
+        return false;
+    }
+    if (!value.lengthComputable)
+        return value.total === undefined;
+    return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
+}
+function isSDKHandshakePayload(value) {
+    return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+}
+function isBridgeError(value) {
+    return isRecord$1(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+}
+function isFileMode(value) {
+    return value === 'read' || value === 'readwrite';
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonNegativeFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function hasOnlyKeys(value, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 /** 当前用户信息与登录能力支持的完整 scope 目录。 */
@@ -177,4 +352,4 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, parseMiniProgramRuntimePermissions };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };

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

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

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

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

package/dist/vite.cjs.js

@@ -8,7 +8,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.5-alpha.0';
+    : '0.8.0-alpha.2';
 
 var re = {exports: {}};
 
@@ -2795,6 +2795,7 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
 }
@@ -2806,7 +2807,25 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
     return String(version).trim();
 }
 function renderMiniappManifest(manifest) {
-    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion }, null, 2)}\n`;
+    const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion, platforms }, null, 2)}\n`;
+}
+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)));
 }
 function getMiniappManifestVersionError(version) {
     if (typeof version !== 'string' || version.trim() === '') {
@@ -11629,7 +11648,8 @@ function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
 
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
-function miniappManifest() {
+function miniappManifest(options) {
+    const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
     let root = process.cwd();
     let outDir = 'dist';
@@ -11649,6 +11669,12 @@ function miniappManifest() {
             };
         },
         configResolved(resolved) {
+            if (resolved.plugins) {
+                const manifestPluginCount = resolved.plugins.filter((plugin) => plugin.name === 'heybox-miniapp-manifest').length;
+                if (manifestPluginCount !== 1) {
+                    throw new Error(`Vite 配置必须且只能包含一个 miniappManifest() 插件，当前数量：${manifestPluginCount}`);
+                }
+            }
             root = resolved.root;
             outDir = resolved.build.outDir;
             command = resolved.command;
@@ -11688,7 +11714,7 @@ function miniappManifest() {
             node_fs.writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(node_fs.readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             const manifestPath = path.join(outputRoot, 'manifest.json');
             node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-            node_fs.writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));
+            node_fs.writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
         },
     };
 }
@@ -11734,4 +11760,5 @@ function resolveHmrWebSocketUrl(resolved) {
     return `${protocol}://${host}${port ? `:${port}` : ''}`;
 }
 
+exports.MINIAPP_PLATFORM_VALUES = MINIAPP_PLATFORM_VALUES;
 exports.miniappManifest = miniappManifest;

package/dist/vite.esm.js

@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.5-alpha.0';
+    : '0.8.0-alpha.2';
 
 var re = {exports: {}};
 
@@ -2792,6 +2792,7 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
 }
@@ -2803,7 +2804,25 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
     return String(version).trim();
 }
 function renderMiniappManifest(manifest) {
-    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion }, null, 2)}\n`;
+    const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion, platforms }, null, 2)}\n`;
+}
+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)));
 }
 function getMiniappManifestVersionError(version) {
     if (typeof version !== 'string' || version.trim() === '') {
@@ -11626,7 +11645,8 @@ function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
 
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
-function miniappManifest() {
+function miniappManifest(options) {
+    const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
     let root = process.cwd();
     let outDir = 'dist';
@@ -11646,6 +11666,12 @@ function miniappManifest() {
             };
         },
         configResolved(resolved) {
+            if (resolved.plugins) {
+                const manifestPluginCount = resolved.plugins.filter((plugin) => plugin.name === 'heybox-miniapp-manifest').length;
+                if (manifestPluginCount !== 1) {
+                    throw new Error(`Vite 配置必须且只能包含一个 miniappManifest() 插件，当前数量：${manifestPluginCount}`);
+                }
+            }
             root = resolved.root;
             outDir = resolved.build.outDir;
             command = resolved.command;
@@ -11685,7 +11711,7 @@ function miniappManifest() {
             writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             const manifestPath = path.join(outputRoot, 'manifest.json');
             mkdirSync(path.dirname(manifestPath), { recursive: true });
-            writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));
+            writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
         },
     };
 }
@@ -11731,4 +11757,4 @@ function resolveHmrWebSocketUrl(resolved) {
     return `${protocol}://${host}${port ? `:${port}` : ''}`;
 }
 
-export { miniappManifest };
+export { MINIAPP_PLATFORM_VALUES, miniappManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.7.5-alpha.0",
+  "version": "0.8.0-alpha.2",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -44,6 +44,7 @@
   "files": [
     "README.md",
     "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
     "bin",
     "dist",
     "skill",
@@ -57,7 +58,7 @@
     "parse5": "^7.3.0",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.7.5-alpha.0"
+    "@heybox/hb-sdk-protocol": "0.8.0-alpha.2"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -73,7 +74,8 @@
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@heybox/hb-types": "^1.0.1",
     "@playwright/test": "^1.55.1",
-    "@vitejs/plugin-vue2": "^2.3.3",
+    "@sneas/telephone": "1.1.2",
+    "@vitejs/plugin-vue": "^6.0.1",
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/ejs": "^3.1.5",
     "@types/fs-extra": "^11.0.4",
@@ -82,6 +84,7 @@
     "@types/semver": "^7.7.1",
     "@types/ws": "^8.5.13",
     "@vitest/coverage-v8": "^3.2.4",
+    "@vue/test-utils": "^2",
     "commander": "^12.1.0",
     "cos-nodejs-sdk-v5": "2.15.4",
     "ejs": "^3.1.10",
@@ -89,22 +92,29 @@
     "fs-extra": "^11.3.0",
     "get-port": "^7.1.0",
     "happy-dom": "^19.0.2",
+    "lucide-vue-next": "1.0.0",
     "open": "^10.2.0",
     "ora": "^5.4.1",
     "picocolors": "^1.1.1",
     "qrcode": "^1.5.4",
     "rimraf": "^5.0.5",
+    "reka-ui": "2.10.4",
     "rollup": "^4.52.4",
     "semver": "^7.8.0",
+    "sass-embedded": "1.97.3",
+    "splitpanes": "^4.1.0",
     "typescript": "^5.9.3",
-    "vue": "^2.7.16",
+    "vue": "^3.5.22",
+    "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.22",
-    "@heybox/runtime": "~0.2.0",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/runtime-policy": "~0.2.0",
+    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox/runtime-transport-fetch": "~0.2.0",
-    "@heybox/hb-sdk-runtime": "~0.7.5-alpha.0",
-    "@heybox/runtime-policy": "~0.2.0"
+    "@heybox/hb-api": "~1.25.23",
+    "@heybox/runtime": "~0.2.0",
+    "@heybox/hb-sdk-runtime": "~0.8.0-alpha.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -117,6 +127,10 @@
           "{projectRoot}/src/**/*",
           "{projectRoot}/devtools/browser-dev-host/**/*",
           "{projectRoot}/scripts/copy-browser-dev-host.cjs",
+          "{projectRoot}/scripts/check-browser-dev-host-assets.cjs",
+          "{projectRoot}/scripts/generate-browser-dev-host-notices.cjs",
+          "{projectRoot}/licenses/**/*",
+          "{projectRoot}/THIRD_PARTY_NOTICES.md",
           "{projectRoot}/rollup.config.ts",
           "{projectRoot}/tsconfig*.json",
           "{workspaceRoot}/packages/hb-sdk-runtime/src/**/*",
@@ -144,15 +158,17 @@
     "build:lib:bundle": "rollup -c rollup.config.ts  --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
     "build:cli": "pnpm run build:hb-sdk-protocol && pnpm run build:hb-api-contract && pnpm run build:cli:bundle",
     "build:cli:bundle": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}' && pnpm run build:browser-dev-host",
-    "build:browser-dev-host": "node scripts/copy-browser-dev-host.cjs",
+    "build:browser-dev-host": "vite build --config vite.browser-dev-host.config.ts && node scripts/check-browser-dev-host-assets.cjs && node scripts/generate-browser-dev-host-notices.cjs",
     "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",
     "check:boundary": "node scripts/check-boundary.cjs",
     "check:docs-sync": "pnpm -w exec hbexec hb-sdk check",
+    "check:compatibility-evidence": "node scripts/validate-compatibility-evidence.mjs",
+    "check:api-semver": "node ../../ops/jobs/hb-sdk-docs-contract/semantic-diff.cjs",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:types:characterization": "tsc -p tsconfig.characterization.json --noEmit --pretty false",
-    "test:types:browser-dev-host": "tsc -p tsconfig.browser-dev-host.json --noEmit --pretty false",
+    "test:types:browser-dev-host": "vue-tsc -p tsconfig.browser-dev-host.json --noEmit --pretty false",
     "test:types": "pnpm run test:types:characterization && pnpm run test:types:browser-dev-host",
     "test:e2e:browser-dev-host": "pnpm run build:browser-dev-host && NODE_OPTIONS='--conditions=heybox' vitest run --config vitest.browser-dev-host-e2e.config.ts",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",
@@ -160,7 +176,8 @@
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest",
     "changelog:draft": "node scripts/changelog-draft.cjs",
     "check:changelog": "node scripts/check-changelog.cjs",
-    "test:release": "node --test scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs",
+    "test:release": "node --test scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs",
+    "test:compatibility-evidence": "node --test scripts/validate-compatibility-evidence.test.mjs",
     "release:prepare": "node scripts/release-prepare.cjs",
     "release:tag": "node scripts/release-tag.cjs",
     "release:family:dry-run": "node ../../ops/jobs/publish-changed-packages/publish.cjs --dry-run",

package/skill/SKILL.md

@@ -51,17 +51,19 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 11. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
 12. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
 13. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the default mini-program share link. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
+14. Treat `files` and `network.download()` as a retained public contract that is not yet enabled by a current Host. The legacy PC adapter was dropped because the new PC will implement the Host ports directly. Until then, legacy PC, Mobile, Web, and Browser Dev Host return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Once a supporting Host is available, call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
+15. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
 
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a workshop mini-program.
-2. Use `hb-sdk dev` for Browser Mock, Mac App, or Mobile App debugging. It requires an active CLI login, a bound Mini-program, and an available remote Dev Context; it must stop before starting Vite or any debugging service when a prerequisite is missing. Mobile uses the `open_inapp` and `heybox://` `openWindow` wrapper with a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
-3. Treat debugging-page permission overrides as local development behavior; overrides do not change remote permissions. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
+2. Use `hb-sdk dev` for Browser Mock and Mobile App debugging. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need those inputs fail explicitly. Mobile uses the single QR entry with the `open_inapp` and `heybox://` `openWindow` wrapper around a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
+3. The debugging page does not edit permissions. Treat the validated remote permission snapshot as canonical Runtime input. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
 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. Keep `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the required Manifest or Runtime gate output is missing.
 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 development, publishing, and Browser Mock Host `heybox-session` requests. 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.
+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.
@@ -81,11 +83,12 @@ For workshop mini-program business code:
 1. Do not read or request tokens, cookies, phone numbers, or private credentials from the SDK.
 2. Do not expose raw share protocol fields, JS callbacks, activity reporting, custom buttons, direct post publishing, or upload-only flows. Public `share.*({ post })` options only preset an editable client post flow and never publish automatically.
 3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
-4. Use only the public `network.request` configuration.
+4. Use only the public `network.request` / `network.download` configurations.
 5. Do not use private package paths or client protocols.
 6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
+9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
 
 For CLI and local development:
 
@@ -93,8 +96,9 @@ For CLI and local development:
 2. Do not skip `auth.login()` in mini-program code. Browser Mock may reuse the Node `hb-sdk login` session for Host network requests, but the page must still call `auth.login()` and handle the authorization dialog. Never paste CLI credentials into page JavaScript.
 3. Use the built-in local debugging page instead of creating another browser Mock.
 4. Keep the Vite `miniappManifest()` plugin enabled.
-5. Treat permission changes made in the `hb-sdk dev` debugging page as local debugging overrides, not online configuration changes. Use the page's reset action to return to the remote baseline.
+5. Do not suggest changing or resetting permissions in the `hb-sdk dev` debugging page; that UI does not exist. Diagnose permission behavior from the remote snapshot and capability result.
 6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
+7. The Browser Dev Host offers iPhone 16 Pro Max (`440 x 956`) and Pixel 9 Pro (`410 x 914`) presets. Switching a preset must preserve the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Use the upper-right QR popover as the only Mobile QR entry.
 
 For host/runtime/protocol-maintenance code: