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

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';
 
 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';
 
 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",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -57,7 +57,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"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -100,11 +100,11 @@
     "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.22",
+    "@heybox/hb-api": "~1.25.23",
+    "@heybox/hb-sdk-runtime": "~0.8.0-alpha",
     "@heybox/runtime": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0",
-    "@heybox/hb-sdk-runtime": "~0.7.5-alpha.0",
-    "@heybox/runtime-policy": "~0.2.0"
+    "@heybox/runtime-policy": "~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.5-alpha.0`
+- 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.5-alpha.0+skill.00f042a71c63",
+  "skillVersion": "0.8.0-alpha+skill.e73cb0ba5184",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.7.5-alpha.0",
-    "compatibility": "0.7.5-alpha.0"
+    "version": "0.8.0-alpha",
+    "compatibility": "0.8.0-alpha"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-00f042a71c637f5aad3141a72a647fc136c74eec7339e4801634c761ea2b7ce5"
+  "integrity": "sha256-e73cb0ba518459e1b262d09fb0ead87a7163c8e5358430184a9dd4f085049357"
 }

package/types/core/errors.d.ts

@@ -18,9 +18,9 @@ export declare class HbMiniProgramSDKError extends Error {
 /**
  * 创建 SDK 标准错误。
  *
- * @param code 稳定错误码。
- * @param message 面向开发者的错误说明。
- * @param data 可选调试数据。
+ * @param code - 稳定错误码。
+ * @param message - 面向开发者的错误说明。
+ * @param data - 可选调试数据。
  * @returns 标准化 `HbMiniProgramSDKError` 实例。
  *
  * @remarks
@@ -34,7 +34,7 @@ export declare function createSDKError(code: string, message: string, data?: unk
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
  * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
  *
- * @typeParam T 标准化响应数据的类型。
+ * @typeParam T - 标准化响应数据的类型。
  */
 export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
     /** HTTP 状态码。 */
@@ -48,7 +48,7 @@ export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
     /** 完整标准化响应。 */
     response: MiniProgramNetworkResponse<T>;
     /**
-     * @param response 已完成请求的标准化网络响应。
+     * @param response - 已完成请求的标准化网络响应。
      */
     constructor(response: MiniProgramNetworkResponse<T>);
 }

package/types/core/sdk.d.ts

@@ -53,16 +53,16 @@ export declare class MiniProgramSDK {
     /**
      * 注册小程序生命周期或业务事件。
      *
-     * @param eventName 要监听的事件名。
-     * @param handler 事件处理函数。
+     * @param eventName - 要监听的事件名。
+     * @param handler - 事件处理函数。
      * @returns 事件解绑函数。
      */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /**
      * 移除小程序生命周期或业务事件。
      *
-     * @param eventName 要移除的事件名。
-     * @param handler 对应的事件处理函数。
+     * @param eventName - 要移除的事件名。
+     * @param handler - 对应的事件处理函数。
      */
     off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
     /**
@@ -77,7 +77,7 @@ export declare class MiniProgramSDK {
 /**
  * 创建独立 SDK 实例。
  *
- * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @param options - SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
  * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
  *
  * @remarks

package/types/core/singleton.d.ts

@@ -10,24 +10,74 @@ import type { MiniProgramDeviceModule } from '../modules/device';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-/** 获取默认 SDK 实例的当前握手状态。 */
+/**
+ * 获取默认 SDK 实例的当前握手状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 export declare function getHandshakeState(): MiniProgramSDKHandshakeState;
-/** 订阅默认 SDK 实例的握手状态，并立即接收当前状态。 */
+/**
+ * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName 要监听的事件名。
- * @param handler 事件处理函数。
+ * @param eventName - 要监听的事件名。
+ * @param handler - 事件处理函数。
  * @returns 事件解绑函数。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 export declare function on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName 要移除的事件名。
- * @param handler 对应的事件处理函数。
+ * @param eventName - 要移除的事件名。
+ * @param handler - 对应的事件处理函数。
  * @returns 无返回值。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 export declare function off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
 /** 默认 SDK 实例的授权模块。 */

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

@@ -1,8 +1,11 @@
 export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
+export declare const MINIAPP_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos", "linux"];
+export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
 export interface MiniappManifest {
     [key: string]: unknown;
     sdkVersion: string;
     version: string;
+    platforms: readonly MiniappPlatform[];
 }
 export interface ParseMiniappManifestResult {
     manifest: MiniappManifest;
@@ -16,5 +19,7 @@ export declare function parseMiniappManifestJson(raw: string, sourceLabel?: stri
 export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
     version: string;
     sdkVersion: string;
+    platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
 };
+export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
 export declare function validateSdkVersion(version: unknown, sourceLabel?: string): string;

package/types/miniapp-publish/index.d.ts

@@ -71,7 +71,7 @@ export interface MiniappUploadSessionFile {
 /**
  * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
  *
- * @param files 待处理的构建产物文件。
+ * @param files - 待处理的构建产物文件。
  * @returns 保留输入附加字段的有序文件列表。
  * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
  */
@@ -81,8 +81,8 @@ export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFil
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files 待上传的构建产物文件。
- * @param options 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件。
+ * @param options - 小程序和长度限制配置。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
  */
 export declare function validateMiniappUploadPathLengths(files: readonly Pick<MiniappArtifactFile, 'relativePath'>[], options: {
@@ -92,7 +92,7 @@ export declare function validateMiniappUploadPathLengths(files: readonly Pick<Mi
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount 参与签名的文件数量。
+ * @param fileCount - 参与签名的文件数量。
  * @returns 包含协议标识和文件数量的字节数组。
  * @throws 文件数量超出协议范围时抛出错误。
  */
@@ -100,7 +100,7 @@ export declare function createMiniappArtifactSignatureHeader(fileCount: number):
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file 已规范化或待校验的构建产物文件。
+ * @param file - 已规范化或待校验的构建产物文件。
  * @returns 包含路径长度、路径和文件大小的字节数组。
  * @throws 文件路径或大小非法时抛出错误。
  */
@@ -108,9 +108,9 @@ export declare function createMiniappArtifactFileHeader(file: MiniappArtifactFil
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles 本地构建产物文件。
- * @param serverFiles 服务端签发的文件映射。
- * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @param localFiles - 本地构建产物文件。
+ * @param serverFiles - 服务端签发的文件映射。
+ * @param uploadedKeys - 服务端已确认上传成功的 key。
  * @returns 完整映射、待上传文件和已确认 key。
  * @throws 服务端映射与本地产物不一致时抛出错误。
  */

package/types/modules/auth/index.d.ts

@@ -16,7 +16,21 @@ export interface LoginResult {
 export type { MiniProgramAuthMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的授权模块。 */
 export interface MiniProgramAuthModule {
-    /** 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。 */
+    /**
+     * 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。
+     *
+     * @since 0.2.0-alpha.0
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     login(options?: LoginOptions): Promise<LoginResult>;
 }
 /** 获取短期授权码。 */