@heybox/hb-sdk 0.8.3-alpha.5 → 0.8.3-alpha.6

package/dist/devtools/browser-dev-host/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-8N4og21f.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-BbRQb08Y.js">
+    <script type="module" crossorigin src="/assets/index-Dui3LdcO.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-38leCDIj.js">
     <link rel="stylesheet" crossorigin href="/assets/index-BrXEMo2-.css">
   </head>
   <body>

package/dist/index.cjs.js

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

package/dist/index.esm.js

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

package/dist/miniapp-publish.cjs.js

@@ -3142,13 +3142,27 @@ const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', '
 /** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
 const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = '0.9.0';
 /**
- * 历史移动端兼容平台集合。
+ * 历史兜底平台集合。
  *
  * @remarks
  * 仅在 `sdkVersion` 缺失或 SemVer precedence 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`，
  * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
+ *
+ * 不含 `linux`：客户端暂无 linux 基线，后端 `x_os_type` 也不映射该平台，声明了也进不了运行门禁。
+ */
+const MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES = [
+    'android',
+    'ios',
+    'ohos',
+    'windows',
+    'macos',
+];
+/**
+ * 历史兜底平台集合的旧名称。
+ *
+ * @deprecated Since 0.8.3. 请改用 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}，本别名取值与之一致，仅为不破坏既有 import 保留。
  */
-const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
+const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES;
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
 const MINIAPP_WINDOW_NUMBER_FIELDS = ['defaultWidth', 'defaultHeight', 'minWidth', 'minHeight'];
@@ -3314,7 +3328,7 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
  * @param manifest - 待解析的不可信 Manifest。必须是非 `null`、非数组的对象；函数只读取其
  * 自有 `platforms` 字段，其他字段不参与平台解析。
  * @returns 冻结的 {@link MiniappPlatformResolution}。显式声明返回规范排序后的 declared /
- * effective；历史兼容返回空 declared 与 Android/iOS/OHOS effective。
+ * effective；历史兼容返回空 declared 与历史兜底平台集合 effective。
  * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
  * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
  * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
@@ -3362,11 +3376,11 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
  * // }
  *
  * const legacy = resolveMiniappManifestPlatforms('0.9.0-alpha.1', {})
- * console.log(legacy.effective) // ['android', 'ios', 'ohos']
+ * console.log(legacy.effective) // ['android', 'ios', 'ohos', 'windows', 'macos']
  * ```
  *
  * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
- * @see {@link MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES}
+ * @see {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
  */
@@ -3389,7 +3403,7 @@ function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
     if (normalizedSdkVersion === undefined || semverExports.lt(normalizedSdkVersion, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION)) {
         return Object.freeze({
             declared: NO_MINIAPP_PLATFORMS,
-            effective: MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES,
+            effective: MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES,
             platformsDeclared: false,
             policy: 'legacy_mobile_default',
         });
@@ -12613,6 +12627,7 @@ exports.LIST_USER_MINIPROGRAM_API_PATH = LIST_USER_MINIPROGRAM_API_PATH;
 exports.LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH;
 exports.LIST_USER_MINIPROGRAM_VERSION_API_PATH = LIST_USER_MINIPROGRAM_VERSION_API_PATH;
 exports.MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES = MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES;
+exports.MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES = MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES;
 exports.MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES;
 exports.MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION;
 exports.MINIAPP_UPLOAD_BATCH_SIZE = MINIAPP_UPLOAD_BATCH_SIZE;

package/dist/miniapp-publish.esm.js

@@ -3140,13 +3140,27 @@ const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', '
 /** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
 const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = '0.9.0';
 /**
- * 历史移动端兼容平台集合。
+ * 历史兜底平台集合。
  *
  * @remarks
  * 仅在 `sdkVersion` 缺失或 SemVer precedence 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`，
  * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
+ *
+ * 不含 `linux`：客户端暂无 linux 基线，后端 `x_os_type` 也不映射该平台，声明了也进不了运行门禁。
+ */
+const MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES = [
+    'android',
+    'ios',
+    'ohos',
+    'windows',
+    'macos',
+];
+/**
+ * 历史兜底平台集合的旧名称。
+ *
+ * @deprecated Since 0.8.3. 请改用 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}，本别名取值与之一致，仅为不破坏既有 import 保留。
  */
-const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
+const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES = MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES;
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
 const MINIAPP_WINDOW_NUMBER_FIELDS = ['defaultWidth', 'defaultHeight', 'minWidth', 'minHeight'];
@@ -3312,7 +3326,7 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
  * @param manifest - 待解析的不可信 Manifest。必须是非 `null`、非数组的对象；函数只读取其
  * 自有 `platforms` 字段，其他字段不参与平台解析。
  * @returns 冻结的 {@link MiniappPlatformResolution}。显式声明返回规范排序后的 declared /
- * effective；历史兼容返回空 declared 与 Android/iOS/OHOS effective。
+ * effective；历史兼容返回空 declared 与历史兜底平台集合 effective。
  * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
  * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
  * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
@@ -3360,11 +3374,11 @@ const NO_MINIAPP_PLATFORMS = Object.freeze([]);
  * // }
  *
  * const legacy = resolveMiniappManifestPlatforms('0.9.0-alpha.1', {})
- * console.log(legacy.effective) // ['android', 'ios', 'ohos']
+ * console.log(legacy.effective) // ['android', 'ios', 'ohos', 'windows', 'macos']
  * ```
  *
  * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
- * @see {@link MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES}
+ * @see {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
  */
@@ -3387,7 +3401,7 @@ function resolveMiniappManifestPlatforms(sdkVersion, manifest) {
     if (normalizedSdkVersion === undefined || semverExports.lt(normalizedSdkVersion, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION)) {
         return Object.freeze({
             declared: NO_MINIAPP_PLATFORMS,
-            effective: MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES,
+            effective: MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES,
             platformsDeclared: false,
             policy: 'legacy_mobile_default',
         });
@@ -12598,4 +12612,4 @@ function compareBytes(left, right) {
     return left.length - right.length;
 }
 
-export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES, MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, createMiniappArtifactFileHeader, createMiniappArtifactSignatureHeader, getMiniProgramUploadAlias, getMiniappUploadKey, hasMiniappRuntimeGate, isValidMiniappManifestVersion as isValidVersion, normalizeBasicInfoName, normalizeRelativePath, parseMiniappBasicInfo, parseMiniappBindAppIds, parseMiniappCategory, prepareMiniappArtifactFiles, previewMiniappBasicInfo, relativePathContainsNodeModulesSegment, resolveMiniappManifestPlatforms, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappCompanionFileReceipts, validateMiniappManifestForDeploy, validateMiniappUploadPathLengths, validateMiniappUploadSizeBudgets, validateUploadPaths, validateUploadTotalSize };
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES, MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES, MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, createMiniappArtifactFileHeader, createMiniappArtifactSignatureHeader, getMiniProgramUploadAlias, getMiniappUploadKey, hasMiniappRuntimeGate, isValidMiniappManifestVersion as isValidVersion, normalizeBasicInfoName, normalizeRelativePath, parseMiniappBasicInfo, parseMiniappBindAppIds, parseMiniappCategory, prepareMiniappArtifactFiles, previewMiniappBasicInfo, relativePathContainsNodeModulesSegment, resolveMiniappManifestPlatforms, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappCompanionFileReceipts, validateMiniappManifestForDeploy, validateMiniappUploadPathLengths, validateMiniappUploadSizeBudgets, validateUploadPaths, validateUploadTotalSize };

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

@@ -14,6 +14,6 @@ npm run deploy -- --release-note "更新说明"
 
 `package.json#heybox.category` 初始声明为 `other`（其他）。发布前请按实际用途选择 `tool`（工具）、`game`（游戏）或 `other`（其他）；该字段为必填，修改后需重新构建。
 
-`package.json#heybox.platforms` 默认声明 `android`、`ios`、`ohos`。发布前请在每个声明的平台完成真机验收；需要支持桌面平台时，由项目自行加入并验收。
+`package.json#heybox.platforms` 默认声明全平台 `android`、`ios`、`ohos`、`windows`、`macos`，请按项目实际完成适配并验收的平台保留，未适配的平台务必删除。`linux` 目前没有客户端基线与 API 兼容声明，暂不建议声明。
 
 更多内容见 [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

@@ -9,7 +9,7 @@
     "category": "other",
     "icon": "assets/heybox-placeholder.png",
     "coverImages": ["assets/heybox-placeholder.png"],
-    "platforms": ["android", "ios", "ohos"],
+    "platforms": ["android", "ios", "ohos", "windows", "macos"],
     "permissions": {}
   },
   "scripts": {

package/dist/vite.cjs.js

@@ -2948,7 +2948,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.5';
+    : '0.8.3-alpha.6';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3601,6 +3601,34 @@ const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', '
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
 const MINIAPP_WINDOW_NUMBER_FIELDS = ['defaultWidth', 'defaultHeight', 'minWidth', 'minHeight'];
 const MINIAPP_WINDOW_ALLOWED_FIELDS = [...MINIAPP_WINDOW_NUMBER_FIELDS, 'resizable'];
+/**
+ * 旧版模板的移动端默认声明。
+ *
+ * @remarks
+ * 这不是平台词表的子集定义，也不参与平台解析；它只用于识别「从旧模板创建后从未调整过
+ * `platforms`」的项目，以便在其构建/调试时给出非阻断提醒。刻意只做移动端的项目只要不恰好
+ * 等于这组声明就不会被提醒。
+ */
+const MINIAPP_LEGACY_MOBILE_TEMPLATE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
+/**
+ * 判断平台声明是否仍是旧版模板的移动端默认值。
+ *
+ * @param platforms - 待判断的平台数组；不要求预先规范化顺序，重复项会被长度校验挡下。
+ * @returns 恰好包含 `android`、`ios`、`ohos` 三个平台时返回 `true`，其余组合返回 `false`。
+ */
+function isLegacyMobileTemplatePlatforms(platforms) {
+    return (platforms.length === MINIAPP_LEGACY_MOBILE_TEMPLATE_PLATFORM_VALUES.length &&
+        MINIAPP_LEGACY_MOBILE_TEMPLATE_PLATFORM_VALUES.every((platform) => platforms.includes(platform)));
+}
+/**
+ * 生成「平台声明仍是旧模板移动端默认」的非阻断提示。
+ *
+ * @param sourceLabel - 提示前缀，默认指向开发者声明路径。
+ * @returns 面向开发者的单行提示；调用方负责经 Vite 插件 `warn` 或等价日志通道输出，不得据此阻断构建。
+ */
+function getLegacyMobileTemplatePlatformsNotice(sourceLabel = 'package.json#heybox.platforms') {
+    return `${sourceLabel} 仍是旧模板的移动端默认声明（android / ios / ohos）。hb-sdk 现已支持桌面端 windows / macos，如项目已完成适配请补充声明；只做移动端可忽略本提示。`;
+}
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
 }
@@ -13313,7 +13341,9 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  *
  * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
  *   `0.0.0`；
- * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
+ *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
+ *   一条非阻断提示，不影响构建结果；
  * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
  *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
  * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
@@ -13429,6 +13459,18 @@ function miniappManifest() {
             hmrWebSocketUrl = resolveHmrWebSocketUrl(resolved);
         },
         configureServer(server) {
+            // 开发期只对「仍是旧模板移动端默认」的声明做非阻断提示。声明缺失或非法一律交由
+            // build / remote deploy 链路拒绝，因此这里只容忍读取阶段的异常，保持 hb-sdk dev
+            // 既有的启动语义；warn 调用留在 try 之外，避免把插件上下文错误一起吞掉。
+            let legacyMobileTemplate = false;
+            try {
+                legacyMobileTemplate = isLegacyMobileTemplatePlatforms(readMiniappPlatformsFromPackageJson(root));
+            }
+            catch {
+                /* package.json#heybox.platforms 缺失或非法时不提示。 */
+            }
+            if (legacyMobileTemplate)
+                this.warn(getLegacyMobileTemplatePlatformsNotice());
             let unregisterLogs;
             const registerLogs = () => {
                 const address = server.httpServer?.address();
@@ -13683,6 +13725,8 @@ function miniappManifest() {
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
             const platforms = readMiniappPlatformsFromPackageJson(root);
+            if (isLegacyMobileTemplatePlatforms(platforms))
+                this.warn(getLegacyMobileTemplatePlatformsNotice());
             const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
             const windowDeclaration = readMiniappWindowFromPackageJson(root);
             const companionConfig = readMiniappCompanionsFromPackageJson(root);

package/dist/vite.esm.js

@@ -2945,7 +2945,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.5';
+    : '0.8.3-alpha.6';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3598,6 +3598,34 @@ const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', '
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
 const MINIAPP_WINDOW_NUMBER_FIELDS = ['defaultWidth', 'defaultHeight', 'minWidth', 'minHeight'];
 const MINIAPP_WINDOW_ALLOWED_FIELDS = [...MINIAPP_WINDOW_NUMBER_FIELDS, 'resizable'];
+/**
+ * 旧版模板的移动端默认声明。
+ *
+ * @remarks
+ * 这不是平台词表的子集定义，也不参与平台解析；它只用于识别「从旧模板创建后从未调整过
+ * `platforms`」的项目，以便在其构建/调试时给出非阻断提醒。刻意只做移动端的项目只要不恰好
+ * 等于这组声明就不会被提醒。
+ */
+const MINIAPP_LEGACY_MOBILE_TEMPLATE_PLATFORM_VALUES = ['android', 'ios', 'ohos'];
+/**
+ * 判断平台声明是否仍是旧版模板的移动端默认值。
+ *
+ * @param platforms - 待判断的平台数组；不要求预先规范化顺序，重复项会被长度校验挡下。
+ * @returns 恰好包含 `android`、`ios`、`ohos` 三个平台时返回 `true`，其余组合返回 `false`。
+ */
+function isLegacyMobileTemplatePlatforms(platforms) {
+    return (platforms.length === MINIAPP_LEGACY_MOBILE_TEMPLATE_PLATFORM_VALUES.length &&
+        MINIAPP_LEGACY_MOBILE_TEMPLATE_PLATFORM_VALUES.every((platform) => platforms.includes(platform)));
+}
+/**
+ * 生成「平台声明仍是旧模板移动端默认」的非阻断提示。
+ *
+ * @param sourceLabel - 提示前缀，默认指向开发者声明路径。
+ * @returns 面向开发者的单行提示；调用方负责经 Vite 插件 `warn` 或等价日志通道输出，不得据此阻断构建。
+ */
+function getLegacyMobileTemplatePlatformsNotice(sourceLabel = 'package.json#heybox.platforms') {
+    return `${sourceLabel} 仍是旧模板的移动端默认声明（android / ios / ohos）。hb-sdk 现已支持桌面端 windows / macos，如项目已完成适配请补充声明；只做移动端可忽略本提示。`;
+}
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
 }
@@ -13310,7 +13338,9 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  *
  * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
  *   `0.0.0`；
- * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
+ *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
+ *   一条非阻断提示，不影响构建结果；
  * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
  *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
  * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
@@ -13426,6 +13456,18 @@ function miniappManifest() {
             hmrWebSocketUrl = resolveHmrWebSocketUrl(resolved);
         },
         configureServer(server) {
+            // 开发期只对「仍是旧模板移动端默认」的声明做非阻断提示。声明缺失或非法一律交由
+            // build / remote deploy 链路拒绝，因此这里只容忍读取阶段的异常，保持 hb-sdk dev
+            // 既有的启动语义；warn 调用留在 try 之外，避免把插件上下文错误一起吞掉。
+            let legacyMobileTemplate = false;
+            try {
+                legacyMobileTemplate = isLegacyMobileTemplatePlatforms(readMiniappPlatformsFromPackageJson(root));
+            }
+            catch {
+                /* package.json#heybox.platforms 缺失或非法时不提示。 */
+            }
+            if (legacyMobileTemplate)
+                this.warn(getLegacyMobileTemplatePlatformsNotice());
             let unregisterLogs;
             const registerLogs = () => {
                 const address = server.httpServer?.address();
@@ -13680,6 +13722,8 @@ function miniappManifest() {
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
             const platforms = readMiniappPlatformsFromPackageJson(root);
+            if (isLegacyMobileTemplatePlatforms(platforms))
+                this.warn(getLegacyMobileTemplatePlatformsNotice());
             const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
             const windowDeclaration = readMiniappWindowFromPackageJson(root);
             const companionConfig = readMiniappCompanionsFromPackageJson(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.3-alpha.5",
+  "version": "0.8.3-alpha.6",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -65,7 +65,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.8.3-alpha.5"
+    "@heybox/hb-sdk-protocol": "0.8.3-alpha.6"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -116,13 +116,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox/hb-api": "~1.28.9",
-    "@heybox/runtime": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/hb-sdk-runtime": "~0.8.3-alpha.6",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/hb-sdk-runtime": "~0.8.3-alpha.5"
+    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/runtime": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.3-alpha.5+skill.aa24d6656331",
+  "skillVersion": "0.8.3-alpha.6+skill.aa24d6656331",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.3-alpha.5",
-    "compatibility": "0.8.3-alpha.5"
+    "version": "0.8.3-alpha.6",
+    "compatibility": "0.8.3-alpha.6"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.3-alpha.5",
+    "version": "0.8.3-alpha.6",
     "path": "skill"
   },
   "integrity": "sha256-aa24d6656331cbad8f6aae7735258a49d7f1a82f6e900415de53a1b93a30ddb8"

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

@@ -13,13 +13,21 @@ export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
 /** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
 export declare const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = "0.9.0";
 /**
- * 历史移动端兼容平台集合。
+ * 历史兜底平台集合。
  *
  * @remarks
  * 仅在 `sdkVersion` 缺失或 SemVer precedence 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`，
  * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
+ *
+ * 不含 `linux`：客户端暂无 linux 基线，后端 `x_os_type` 也不映射该平台，声明了也进不了运行门禁。
+ */
+export declare const MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos"];
+/**
+ * 历史兜底平台集合的旧名称。
+ *
+ * @deprecated Since 0.8.3. 请改用 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}，本别名取值与之一致，仅为不破坏既有 import 保留。
  */
-export declare const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES: readonly ["android", "ios", "ohos"];
+export declare const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos"];
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 export declare const MINIAPP_WINDOW_SIZE_MAX = 16384;
 /**
@@ -50,6 +58,20 @@ export interface MiniappWindowDeclaration {
  */
 export declare const MINIAPP_DESKTOP_PLATFORM_VALUES: readonly ["windows", "macos", "linux"];
 export declare function hasMiniappDesktopPlatform(platforms: readonly MiniappPlatform[] | undefined): boolean;
+/**
+ * 判断平台声明是否仍是旧版模板的移动端默认值。
+ *
+ * @param platforms - 待判断的平台数组；不要求预先规范化顺序，重复项会被长度校验挡下。
+ * @returns 恰好包含 `android`、`ios`、`ohos` 三个平台时返回 `true`，其余组合返回 `false`。
+ */
+export declare function isLegacyMobileTemplatePlatforms(platforms: readonly MiniappPlatform[]): boolean;
+/**
+ * 生成「平台声明仍是旧模板移动端默认」的非阻断提示。
+ *
+ * @param sourceLabel - 提示前缀，默认指向开发者声明路径。
+ * @returns 面向开发者的单行提示；调用方负责经 Vite 插件 `warn` 或等价日志通道输出，不得据此阻断构建。
+ */
+export declare function getLegacyMobileTemplatePlatformsNotice(sourceLabel?: string): string;
 export interface MiniappManifest {
     [key: string]: unknown;
     name?: string;
@@ -140,7 +162,10 @@ export declare function areMiniappPlatformsEqual(left: readonly MiniappPlatform[
  * - `explicit`：Manifest 自身拥有合法、非空的 `platforms` 字段；无论 sdkVersion 是否低于
  *   `0.9.0`，显式声明都优先且不会被兼容默认值覆盖。
  * - `legacy_mobile_default`：Manifest 完全没有 `platforms` 字段，且 sdkVersion 缺失/空白或
- *   SemVer precedence 低于 `0.9.0`；最终按 `android`、`ios`、`ohos` 历史集合兼容。
+ *   SemVer precedence 低于 `0.9.0`；最终按 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES} 兜底。
+ *
+ * 字面量 `legacy_mobile_default` 已作为详情接口 wire 值下发、并持久化进后端平台快照；
+ * 兜底集合虽已由移动端三件套扩为五平台，这里仍保持原字符串不变，避免存储与协议迁移。
  */
 export type MiniappPlatformPolicy = 'explicit' | 'legacy_mobile_default';
 /**
@@ -149,7 +174,7 @@ export type MiniappPlatformPolicy = 'explicit' | 'legacy_mobile_default';
  * @remarks
  * 返回对象通过 `Object.freeze()` 冻结，字段和数组在类型层也都是只读值。调用方应把其中
  * 的数组视为不可变集合，不要修改、重新排序或自行合并 fallback。`platformsDeclared` 与
- * `policy` 用于保留“显式三移动端”与“历史默认三移动端”的来源差异。
+ * `policy` 用于保留“显式声明”与“历史缺声明默认”的来源差异。
  */
 export interface MiniappPlatformResolution {
     /**
@@ -160,11 +185,11 @@ export interface MiniappPlatformResolution {
     readonly declared: readonly MiniappPlatform[];
     /**
      * 最终用于展示、校验和运行判断的平台集合。`explicit` 时与规范化后的 `declared` 相同；
-     * `legacy_mobile_default` 时固定为 `android`、`ios`、`ohos`。
+     * `legacy_mobile_default` 时固定为 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}。
      */
     readonly effective: readonly MiniappPlatform[];
     /**
-     * Manifest 是否拥有经过校验的显式 `platforms` 字段。显式声明三移动端时为 `true`，
+     * Manifest 是否拥有经过校验的显式 `platforms` 字段。显式声明时为 `true`，
      * 历史 fallback 得到相同 effective 集合时仍为 `false`。
      */
     readonly platformsDeclared: boolean;
@@ -180,7 +205,7 @@ export interface MiniappPlatformResolution {
  * @param manifest - 待解析的不可信 Manifest。必须是非 `null`、非数组的对象；函数只读取其
  * 自有 `platforms` 字段，其他字段不参与平台解析。
  * @returns 冻结的 {@link MiniappPlatformResolution}。显式声明返回规范排序后的 declared /
- * effective；历史兼容返回空 declared 与 Android/iOS/OHOS effective。
+ * effective；历史兼容返回空 declared 与历史兜底平台集合 effective。
  * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
  * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
  * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
@@ -228,11 +253,11 @@ export interface MiniappPlatformResolution {
  * // }
  *
  * const legacy = resolveMiniappManifestPlatforms('0.9.0-alpha.1', {})
- * console.log(legacy.effective) // ['android', 'ios', 'ohos']
+ * console.log(legacy.effective) // ['android', 'ios', 'ohos', 'windows', 'macos']
  * ```
  *
  * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
- * @see {@link MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES}
+ * @see {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
  */

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

@@ -54,7 +54,7 @@ export declare const UPDATE_SQUARE_DISPLAY_API_PATH = "/mall/developer/user_mini
 export declare const LIST_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/list";
 export { parseMiniappCategory, type MiniappCategory } from '../miniapp-manifest/category';
 export { isValidMiniappManifestVersion as isValidVersion } from '../miniapp-manifest/schema';
-export { MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, resolveMiniappManifestPlatforms, type MiniappPlatformPolicy, type MiniappPlatformResolution, } from '../miniapp-manifest/schema';
+export { MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES, MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES, MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION, resolveMiniappManifestPlatforms, type MiniappPlatformPolicy, type MiniappPlatformResolution, } from '../miniapp-manifest/schema';
 export { parseMiniappBindAppIds, type ParseMiniappBindAppIdsOptions } from '../miniapp-manifest/bindings';
 /**
  * 将扫描到的相对路径转换为统一的 `/` 分隔形式。

package/types/vite/index.d.ts

@@ -18,7 +18,7 @@ export interface MiniappManifestPlugin {
     /** 记录 Vite 根目录、输出目录、运行命令和开发期 HMR 地址。 */
     configResolved: (resolved: MiniappManifestResolvedConfig) => void;
     /** 为 `hb-sdk dev` 注册本机调试能力；生产构建不会创建开发服务。 */
-    configureServer: (server: MiniappManifestDevServer) => void;
+    configureServer: (this: MiniappManifestPluginContext, server: MiniappManifestDevServer) => void;
     /** 保留 Rollup/Vite 已报告的构建错误，避免产物校验用二次错误掩盖原始原因。 */
     buildEnd: (error?: Error) => void;
     /** 向入口 HTML 注入 Runtime Gate 和平台 CSP；serve 时还会加入受限的 HMR 与日志调试支持。 */
@@ -134,7 +134,9 @@ export declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MIN
  *
  * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
  *   `0.0.0`；
- * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
+ *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
+ *   一条非阻断提示，不影响构建结果；
  * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
  *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
  * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；