@heybox/hb-sdk 0.7.4 → 0.8.0-alpha

package/dist/miniapp-publish.cjs.js

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

package/dist/miniapp-publish.esm.js

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

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

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

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

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

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.4';
+    : '0.8.0-alpha';
 
 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.4';
+    : '0.8.0-alpha';
 
 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.4",
+  "version": "0.8.0-alpha",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -53,11 +53,11 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@msgpack/msgpack": "^3.1.3",
+    "@msgpack/msgpack": "2.8.0",
     "parse5": "^7.3.0",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.7.4"
+    "@heybox/hb-sdk-protocol": "0.8.0-alpha"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -100,11 +100,11 @@
     "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.20",
-    "@heybox/hb-sdk-runtime": "~0.7.4",
-    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/hb-api": "~1.25.23",
+    "@heybox/hb-sdk-runtime": "~0.8.0-alpha",
+    "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/runtime": "~0.2.0"
+    "@heybox/runtime-transport-fetch": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -149,6 +149,8 @@
     "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",
@@ -160,7 +162,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/references/api-protocol.md

@@ -202,6 +202,18 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
 | Root API | 2 | 4 | 51 | 57 | 1 |
-| Protocol API | 0 | 3 | 44 | 68 | 31 |
+| Protocol API | 0 | 3 | 34 | 62 | 30 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
-| Vite API | 0 | 1 | 0 | 0 | 0 |
+| Vite API | 0 | 1 | 5 | 1 | 1 |
+
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=2; fingerprint=d54639a086217e53edf8a85d2e11e0f0263aa0fd3dc88183fe2b3f3f07b4f4a1 -->
+
+## SDK API
+
+- [兼容性总览](https://docs.xiaoheihe.cn/hb_sdk/reference/compatibility)
+
+## 常用 API
+
+- [`user.getInfo`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/user/getInfo)
+- [`auth.login`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/auth/login)
+- [`cloud.leaderboard.submit`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/cloud/leaderboard/submit)

package/skill/references/api-root.md

@@ -24,7 +24,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.7.4`
+- Version at generation time: `0.8.0-alpha`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -210,12 +210,18 @@ Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { HB_SDK_VERSION } from '../core/version';
-import { renderMiniappManifest, validateMiniappPackageVersionForBuild } from '../miniapp-manifest/schema';
+import {
+  MINIAPP_PLATFORM_VALUES,
+  renderMiniappManifest,
+  validateMiniappPackageVersionForBuild,
+  validateMiniappPlatforms,
+  type MiniappPlatform,
+} from '../miniapp-manifest/schema';
 import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
 import { enforceMiniappHtmlPolicy } from './html-policy';
 import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
 
-type MiniappManifestPlugin = {
+export interface MiniappManifestPlugin {
   name: string;
   config: (config: MiniappManifestUserConfig) => MiniappManifestUserConfig | void;
   configResolved: (resolved: MiniappManifestResolvedConfig) => void;
@@ -223,18 +229,18 @@ type MiniappManifestPlugin = {
   buildEnd: (error?: Error) => void;
   transformIndexHtml: (html: string) => string;
   closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
-};
+}
 
-interface MiniappManifestUserConfig {
+export interface MiniappManifestUserConfig {
   base?: string;
   define?: Record<string, string>;
 }
 
-interface MiniappManifestPluginContext {
+export interface MiniappManifestPluginContext {
   warn: (message: string) => void;
 }
 
-interface MiniappManifestResolvedConfig {
+export interface MiniappManifestResolvedConfig {
   root: string;
   command: 'build' | 'serve';
   build: {
@@ -253,12 +259,21 @@ interface MiniappManifestResolvedConfig {
           protocol?: 'ws' | 'wss';
         };
   };
+  plugins?: readonly { name?: string }[];
+}
+
+export { MINIAPP_PLATFORM_VALUES };
+export type { MiniappPlatform };
+
+export interface MiniappManifestOptions {
+  platforms: readonly MiniappPlatform[];
 }
 
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 
-export function miniappManifest(): MiniappManifestPlugin {
+export function miniappManifest(options: MiniappManifestOptions): MiniappManifestPlugin {
+  const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
   const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
   let root = process.cwd();
   let outDir = 'dist';
@@ -279,6 +294,12 @@ export function miniappManifest(): MiniappManifestPlugin {
       };
     },
     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;
@@ -322,7 +343,7 @@ export function miniappManifest(): MiniappManifestPlugin {
 
       const manifestPath = path.join(outputRoot, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));
+      writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
     },
   };
 }
@@ -556,18 +577,18 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 
 SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握手状态，并通过 `on()` / `off()` 处理前后台、登录态等生命周期事件。
 
-| 模块         | 用途                                                         |
-| ------------ | ------------------------------------------------------------ |
-| `auth`       | 获取交给开发者服务端交换的短期授权码                         |
-| `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权                   |
-| `share`      | 打开分享、复制链接或截图分享流程                             |
-| `ui`         | 展示 Toast 和 Loading                                        |
-| `device`     | 调用振动和剪贴板能力                                         |
-| `navigation` | 关闭、刷新页面或打开小黑盒页面                               |
-| `viewport`   | 读取窗口信息和设置导航栏样式                                 |
-| `storage`    | 读写当前小程序的隔离存储                                     |
-| `cloud`      | 使用小程序云端排行榜                                         |
-| `network`    | 发起经过平台授权的网络请求                                   |
+| 模块         | 用途                                       |
+| ------------ | ------------------------------------------ |
+| `auth`       | 获取交给开发者服务端交换的短期授权码       |
+| `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权 |
+| `share`      | 打开分享、复制链接或截图分享流程           |
+| `ui`         | 展示 Toast 和 Loading                      |
+| `device`     | 调用振动和剪贴板能力                       |
+| `navigation` | 关闭、刷新页面或打开小黑盒页面             |
+| `viewport`   | 读取窗口信息和设置导航栏样式               |
+| `storage`    | 读写当前小程序的隔离存储                   |
+| `cloud`      | 使用小程序云端排行榜                       |
+| `network`    | 发起经过平台授权的网络请求                 |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 

package/skill/references/examples.md

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

package/skill/references/safety-boundaries.md

@@ -24,7 +24,7 @@
 - `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
 - 仅当远端已启用 `network.request` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
-- 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
+- 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
 ## Agent rules
 

package/skill/scripts/sync-references.mjs

@@ -78,6 +78,8 @@ function rewriteBundledProtocolIndexLinks(markdown) {
   return markdown
     .replaceAll('(./root/)', '(api-root.md)')
     .replaceAll('(./protocol/)', '(#public-protocol-entrypoint)')
+    .replaceAll('(./compatibility)', '(https://docs.xiaoheihe.cn/hb_sdk/reference/compatibility)')
+    .replaceAll('](/reference/', '](https://docs.xiaoheihe.cn/hb_sdk/reference/')
     .replaceAll('(./miniapp-publish/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/)')
     .replaceAll('(./vite/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/)')
     .replaceAll('(./runtime/)', '(https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/)')
@@ -735,7 +737,7 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest()],
+  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
 });`,
 )}
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.7.4+skill.f8dd939f4173",
+  "skillVersion": "0.8.0-alpha+skill.e73cb0ba5184",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.7.4",
-    "compatibility": "0.7.4"
+    "version": "0.8.0-alpha",
+    "compatibility": "0.8.0-alpha"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-f8dd939f4173d20846ae7d62fbf6bc44227f8d9e186fc6a50e818a971a39213b"
+  "integrity": "sha256-e73cb0ba518459e1b262d09fb0ead87a7163c8e5358430184a9dd4f085049357"
 }