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

package/CHANGELOG.md

@@ -4,6 +4,49 @@
 
 待发布：本地调试支持尚未获平台批准的普通网络与桌面辅助应用，并持续提示这些能力发布后仍不可用。浏览器 Mock 可在未登录、未绑定或远端暂不可用时启动；真实设备仍需有效调试会话，并在每次启动时确认临时权限。官方域名不在临时权限范围内。部署与发布前会提示声明中尚未获线上批准的权限。
 
+## 0.8.3-alpha.9
+
+### 问题修复
+
+- 修复 `hb-sdk dev` 在 VS Code 等进程占用默认 loopback 端口时可能卡在入口探测的问题；端口冲突时会自动切换并提示，页面探测也会在超时后继续启动。
+
+## 0.8.3-alpha.8
+
+> 摘要：修复开发调试时设备日志上传被平台 CSP 阻断并持续循环告警的问题。
+> 影响级别：常规
+> 开发者动作：无需修改业务代码；重新运行 `hb-sdk dev` 即可恢复调试台日志聚合。
+> 兼容范围：只调整本地开发期的日志上传放行地址与失败重试节奏；正式构建的 CSP 与线上权限模型保持不变。
+
+### 问题修复
+
+- 修复 `hb-sdk dev` 在未开通网络权限时设备日志上传被平台 CSP 阻断，导致调试台持续出现 `CSP_VIOLATION` 告警且日志无法聚合的问题；日志上传失败改为最高 30 秒指数退避，成功后恢复 1 秒心跳。
+
+## 0.8.3-alpha.7
+
+### 新增能力
+
+- `navigation.openAppPage()` 新增 `mini_program` 目标，可按小程序 ID 打开公开发布的小程序，并携带由目标通过 `share.getExtra()` 读取的可选 `extra` 启动数据；不开放版本、URL、scheme 或窗口配置。
+
+### 问题修复
+
+- 发送分享或跨小程序启动数据时会拒绝目标解码器不支持的 `__proto__` 字段，避免调用成功后目标读取到 `undefined`。
+- 修复 `hb-sdk dev` 在项目命中旧 Vite 插件产物时可能让页面 SDK 版本与调试启动记录不一致的问题，避免 Browser Dev Host 报 `SDK_VERSION_MISMATCH`。
+- 修复移动端跨小程序跳转复用当前 Host 地址的问题；测试环境使用 `web.debugmode.cn`，生产环境使用 `www.xiaoheihe.cn`。
+
+## 0.8.3-alpha.6
+
+### 新增能力
+
+- 新增 [`MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES`](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/constants/MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES.html)：历史产物缺少 `platforms` 声明时的兜底平台集合，由 `android` / `ios` / `ohos` 扩为 `android` / `ios` / `ohos` / `windows` / `macos`。原 `MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES` 更名为此常量并保留为已弃用别名，取值一致。
+- `hb-sdk create` 生成的 `package.json#heybox.platforms` 默认声明同步扩为 `android`、`ios`、`ohos`、`windows`、`macos`。
+
+### 行为调整
+
+- `hb-sdk dev` 与 `hb-sdk build` 在 `platforms` 仍是旧模板移动端默认 `android` / `ios` / `ohos` 时输出一条非阻断提示，提醒按实际适配补充桌面平台声明；不影响构建结果，只做移动端的项目可忽略。普通 `vite build` 走同一插件钩子，也会输出该提示。
+- 历史产物缺少 `platforms` 且 SDK 版本低于 `0.9.0` 时按新的兜底集合解析，桌面端不再被默认排除。`0.9.0` 硬切点、未声明即失败以及显式声明非法的报错行为均保持不变；`linux` 不在兜底集合内，客户端暂无对应基线。
+- Host/Runtime 侧同步：`MINI_PROGRAM_LEGACY_DEFAULT_PLATFORMS` 取代 `MINI_PROGRAM_LEGACY_MOBILE_PLATFORMS`（旧名保留为已弃用别名），历史缺声明兜底与显式门禁统一为五平台（不含 `linux`），`MINI_PROGRAM_PLATFORM_POLICY_VERSION` 升为 2；无法判定平台集合的兼容窗口仍按 fail open 放行整个平台词表。
+- 详情接口的 `platform_policy` 字面量仍为 `legacy_mobile_default`，后台存储与协议无需迁移；已发布版本继续使用已固化的平台快照。
+
 ## 0.8.3-alpha.5 - 2026-09-23
 
 > 摘要：修复浏览器调试台顶部偏移与手机真机不一致的问题。

package/README.md

@@ -99,12 +99,12 @@ async function revokeAuthorizationFromUserAction() {
 
 `user.revokeAuthorization()` 位于无需声明白名单，不接收小程序 ID、黑盒用户 ID 或手势参数。调用必须来自可信用户操作，否则返回 `USER_GESTURE_REQUIRED`。撤销成功后，后续身份或授权读取会重新进入授权流程；SDK 不会替业务清理已经持久化的数据。
 
-已有 Vite 项目先在 `package.json#heybox.platforms` 声明实际承诺适配的平台：
+已有 Vite 项目先在 `package.json#heybox.platforms` 声明实际承诺适配的平台（下面是官方模板的起始默认，未适配的平台应删除）：
 
 ```json
 {
   "heybox": {
-    "platforms": ["android", "ios", "ohos"]
+    "platforms": ["android", "ios", "ohos", "windows", "macos"]
   }
 }
 ```
@@ -319,8 +319,8 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `share`      | 打开分享、复制链接或截图分享流程                |
 | `ui`         | 展示 Toast 和 Loading                           |
 | `device`     | 调用振动和剪贴板能力                            |
-| `navigation` | 关闭、刷新页面或打开小黑盒页面                  |
-| `viewport`   | 读取窗口信息、设置方向/胶囊及导航栏样式                    |
+| `navigation` | 关闭、刷新页面，或打开小黑盒页面和公开小程序    |
+| `viewport`   | 读取窗口信息、设置方向/胶囊及导航栏样式         |
 | `storage`    | 读写当前小程序的隔离存储                        |
 | `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
 | `cloud`      | 使用小程序云端排行榜                            |
@@ -345,7 +345,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
 - 新 PC 开放持久 sandbox、单文件/目录 picker、精确 File 保存与公网 `network.download()`；Android/iOS `1.3.396+` 通过独立 Native host contract 提供 Files/Download，并用 `system.describe` 的实际 operation 集逐项启用，缺失 handler、握手超时或 operation 不完整时对应能力 fail closed。`pickFiles()` 默认单文件；显式传入 `multiple: true` 时允许 Host 返回多个文件，实际返回数量由宿主 picker 决定。小黑盒域名流式下载暂不支持；Web 与 Browser Dev Host 仍未开放这些 primitive。
 - `withCredentials` 不再是支持的配置字段，也不会进入新 SDK、协议或 Host contract；旧 SDK 构建产物的 wire 字段仅由 Runtime 兼容忽略。Mobile 对官方 HTTPS 默认端口目标自动启用 Native Cookie，第三方关闭；应用可显式提供 `Cookie`、`Authorization` 等请求头。`Origin`、`Referer`、`User-Agent` 由 Host 接管；`Host`、分帧及逐跳请求头由传输层管理，不能由小程序设置。Web Host 使用浏览器 Fetch，无法发送显式 `Cookie` 等浏览器禁止的头，会返回 `REQUEST_UNSUPPORTED`；需要第三方 Cookie 会话时请在支持原始请求头的 Mobile/PC Host 验收。已启用的 Mobile 下载走无凭据 Native transfer；需要鉴权的下载请使用服务端签发的限时 URL。
-- 新 PC 不支持振动、分享菜单和截图分享；`navigation.openAppPage` 仅支持 `game_detail`，用户/帖子详情会明确失败。调用平台相关能力时应处理 `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。
+- 新 PC 不支持振动、分享菜单和截图分享；`navigation.openAppPage` 支持 `game_detail` 与 `mini_program`，用户/帖子详情会明确失败。调用平台相关能力时应处理 `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。
 - picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`；Mobile 上 Android 不提供 `saveFile()`，`pickFiles()` 选中的 Android 精确 SAF 文件仅支持只读（对这类目标请求 `mode: 'readwrite'` 返回 `FILE_ACCESS_DENIED`）。可用性由 Host 通过 `system.describe` 宣告的 operation 集协商，Runtime/H5 不按操作系统分支判定能力。
 - `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
 - `file()` / `directory()` 只接受以 `/` 分隔的规范相对路径；拒绝绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符和控制字符。
@@ -356,7 +356,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
 - `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
 - `hb-sdk dev` 可因当前版本声明且有效的本地 `network` 临时权限跳过平台 CSP；`remote deploy` 仍只认线上批准，直接 build 继续注入。`useOfficialDomain` 不参与 CSP 判定，本地临时权限也不能启用它。
-- 构建必须启用 `miniappManifest()`，并在 `package.json#heybox.platforms` 显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
+- 构建必须启用 `miniappManifest()`，并在 `package.json#heybox.platforms` 显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos', 'windows', 'macos']` 只是初始配置，不代表已经完成真机验收；声明仍是旧模板移动端默认 `['android', 'ios', 'ohos']` 时，`hb-sdk dev` 与 `hb-sdk build` 只会输出一条非阻断提示。
 - `companion.prepare()` 与 `companion.launch()` 分别需要新的可信用户手势和 Host 授权；启动不会隐式准备。
 - Companion 入口、参数、平台目标和归档摘要只来自 canonical Manifest；线上与生产使用当前已发布版本，本地真 PC 调试使用 `hb-sdk dev` 固定并签发的本地 snapshot。页面不能传动态 path、args、cwd、环境变量或 shell。
 - Companion V1 只支持普通权限启动；`elevation: 'required'` 会在构建阶段失败。
@@ -371,6 +371,26 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 `@heybox/hb-sdk-runtime` 与 `@heybox/hb-sdk-protocol` 按同一 release family 锁步升级，部署 detail
 前必须保证三个 package 均可解析同一版本。
 
+## 跨小程序跳转
+
+`navigation.openAppPage()` 的 `mini_program` 目标会让 Host 打开另一个公开发布的小程序：
+
+```ts
+await hbSDK.navigation.openAppPage({
+  target: 'mini_program',
+  miniProgramId: '2e2b8e19-8d73-45f8-8785-b87fd5535510',
+  extra: { page: 'ranking', itemId: 123 },
+});
+```
+
+目标小程序在新的启动上下文中读取：
+
+```ts
+const launchData = hbSDK.share.getExtra();
+```
+
+该目标无需权限声明或可信用户手势，只接受目标 `miniProgramId` 和可选 `extra`；不能指定版本、URL、scheme 或窗口样式。生产 Host 只解析当前用户可访问的公开发布版本，预览与本地开发目标仅由 Dev Host 提供。`extra` 不会继承源小程序当前的启动数据，省略时目标读取到 `undefined`，显式传 `null` 时读取到 `null`。调用成功只表示 Host 已接受开窗请求，不等待目标加载或 SDK 握手。
+
 ## 分享扩展数据
 
 `share.showShareMenu()` 的落地页固定为当前小程序的 `common_share`，不接受自定义 `url`。分享和复制链接可以携带小程序自行定义的页面状态：

package/dist/cli-chunks/{build-8dIKgG1v.cjs → build-Dd5EmgU1.cjs}

@@ -3,13 +3,13 @@
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-DNXaBBHz.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D7X7T6VT.cjs');
 require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-hlz0xgg8.cjs');
-var index = require('./index-B6lVqj5W.cjs');
-var projectVite = require('./project-vite-C-YGhyHJ.cjs');
-require('./version-MrIy1W5p.cjs');
+var runtimeGate = require('./runtime-gate-OEku3HCR.cjs');
+var index = require('./index-D4KcCSeD.cjs');
+var projectVite = require('./project-vite-BWhbvrXL.cjs');
+require('./version-CHBZvmBz.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-DSNBFwsG.cjs → context-Cm0U_oeb.cjs}

@@ -3,10 +3,10 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-DNXaBBHz.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D7X7T6VT.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-u4BpZqwE.cjs');
+var session = require('./session-BC8gfXbM.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

package/dist/cli-chunks/{create-DmNfBoq7.cjs → create-Bj08BLVt.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 require('node:module');
 require('os');
 require('node:crypto');

package/dist/cli-chunks/{dev-C15G1TxE.cjs → dev-BQtFwaZ6.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var context = require('./context-DSNBFwsG.cjs');
+var context = require('./context-Cm0U_oeb.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-DNXaBBHz.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D7X7T6VT.cjs');
 var os = require('node:os');
 var path = require('node:path');
 var net = require('node:net');
@@ -12,13 +12,13 @@ var node_http = require('node:http');
 var node_module = require('node:module');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-u4BpZqwE.cjs');
+var session = require('./session-BC8gfXbM.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-C-YGhyHJ.cjs');
-var version = require('./version-MrIy1W5p.cjs');
+var projectVite = require('./project-vite-BWhbvrXL.cjs');
+var version = require('./version-CHBZvmBz.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1731,6 +1731,22 @@ async function selectAvailablePort(options) {
 function createPortCandidates(startPort, count) {
     return Array.from({ length: count }, (_, index) => startPort + index);
 }
+async function isTcpPortListening(port, host, timeoutMs = 250) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        let settled = false;
+        const finish = (listening) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(listening);
+        };
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(timeoutMs, () => finish(true));
+    });
+}
 
 const DEFAULT_TTL_MS = 300_000;
 const DEFAULT_CAPACITY = 64;
@@ -1970,8 +1986,8 @@ const DEFAULT_CHANNEL_TRANSPORT = {
 };
 const IPV4_LOOPBACK_ADDRESSES = new net.BlockList();
 IPV4_LOOPBACK_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
-const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-C15G1TxE.cjs', document.baseURI).href)))('ws');
-const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-C15G1TxE.cjs', document.baseURI).href)))('parse5');
+const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-BQtFwaZ6.cjs', document.baseURI).href)))('ws');
+const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-BQtFwaZ6.cjs', document.baseURI).href)))('parse5');
 const BROWSER_DEV_HOST_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'devtools/browser-dev-host'),
     path.resolve(__dirname, '../devtools/browser-dev-host'),
@@ -11070,7 +11086,7 @@ function assertNodeRuntimeCapabilities(ctx, settings) {
 function createNodeRealtimeDriverRegistry() {
     const registry = createRuntimeRealtimeDriverRegistry();
     registry.registerLazy('node-websocket', async () => {
-        const mod = await Promise.resolve().then(function () { return require('./index.esm-DG1EUOV-.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-Dog1YTU_.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -15175,6 +15191,9 @@ function writeLaunchResponse(response, status, body) {
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_BROWSER_DEV_HOST_PORT = 5174;
 const DEFAULT_DEV_CONTEXT_TIMEOUT_MS = 3000;
+const DEFAULT_APP_URL_PROBE_TIMEOUT_MS = 3000;
+const MAX_DEV_PORT_ATTEMPTS = 20;
+const HB_SDK_BUILD_VERSION_DEFINE = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 const DEV_LISTEN_HOST = '0.0.0.0';
 const LOCAL_DEV_URL_HOST = '127.0.0.1';
 // 与 Heybox H5 Vite 插件共享，让 hb-sdk 统一管理启动输出。
@@ -15192,12 +15211,14 @@ async function runDevCommand(options, runtime = {}) {
     const openUrl = runtime.openExternalUrl ?? browser.openExternalUrl;
     const networkInterfaceSnapshot = (runtime.networkInterfaces ?? os.networkInterfaces)();
     const getPortImpl = runtime.getPort ?? getPorts;
-    const appPort = await selectAvailablePort({
+    const requestedAppPort = options.port ?? DEFAULT_APP_PORT;
+    const appPort = await selectAvailableVitePort({
         getPort: getPortImpl,
-        host: DEV_LISTEN_HOST,
-        label: 'Vite 开发服务器',
-        startPort: options.port ?? DEFAULT_APP_PORT,
+        isPortListening: runtime.isTcpPortListening ?? isTcpPortListening,
+        startPort: requestedAppPort,
     });
+    if (appPort !== requestedAppPort)
+        logger.warn(`端口 ${requestedAppPort} 已被占用，已自动切换到 ${appPort}`);
     const resolvedOptions = {
         ...options,
         hmrHost: createLanInterfaceCandidates(networkInterfaceSnapshot)[0]?.address,
@@ -15302,7 +15323,7 @@ async function runDevCommand(options, runtime = {}) {
         void runtimePermissionEnv.withMiniappPlatformCspEnv(next, () => withCompanionArtifactAccessTokenEnv(companionArtifactAccessToken, () => withMiniProgramManifestAccessTokenEnv(miniProgramManifestAccessToken, () => appServer.restart(), runtime.env), runtime.env), runtime.env)
             .catch(() => logger.warn('开发服务器权限配置刷新失败，请重新运行 hb-sdk dev'));
     };
-    const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
+    const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl, runtime.appUrlProbeTimeoutMs ?? DEFAULT_APP_URL_PROBE_TIMEOUT_MS), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
         appUrl,
         devContextPath,
@@ -15576,6 +15597,21 @@ function createMiniProgramDevLaunchVitePlugin(getSnapshot, handleSession) {
         },
     };
 }
+/** 保证调试页与 CLI 启动记录使用同一 SDK 版本，避免项目命中旧 Vite 插件产物。 */
+function createMiniProgramDevSdkVersionVitePlugin() {
+    return {
+        name: 'heybox-mini-program-dev-sdk-version',
+        enforce: 'post',
+        config(config) {
+            return {
+                define: {
+                    ...config.define,
+                    [HB_SDK_BUILD_VERSION_DEFINE]: JSON.stringify(version.HB_SDK_VERSION),
+                },
+            };
+        },
+    };
+}
 function createViteServerOptions(projectRoot, options, launchPlugin) {
     const configFile = resolveProjectViteConfig(projectRoot);
     const server = {
@@ -15593,13 +15629,13 @@ function createViteServerOptions(projectRoot, options, launchPlugin) {
         return {
             configFile,
             logLevel: VITE_LOG_LEVEL,
-            plugins: [launchPlugin],
+            plugins: [launchPlugin, createMiniProgramDevSdkVersionVitePlugin()],
             server,
         };
     }
     return {
         logLevel: VITE_LOG_LEVEL,
-        plugins: [launchPlugin],
+        plugins: [launchPlugin, createMiniProgramDevSdkVersionVitePlugin()],
         root: projectRoot,
         server,
     };
@@ -15608,10 +15644,27 @@ function resolveProjectViteConfig(projectRoot) {
     const candidates = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'];
     return candidates.map((file) => path.join(projectRoot, file)).find((file) => fs.existsSync(file));
 }
-async function resolveViteAppUrl(server, options, fetchImpl) {
+async function selectAvailableVitePort(options) {
+    const lastCandidate = options.startPort + MAX_DEV_PORT_ATTEMPTS - 1;
+    let nextCandidate = options.startPort;
+    while (nextCandidate <= lastCandidate) {
+        const port = await selectAvailablePort({
+            getPort: options.getPort,
+            host: DEV_LISTEN_HOST,
+            label: 'Vite 开发服务器',
+            maxAttempts: lastCandidate - nextCandidate + 1,
+            startPort: nextCandidate,
+        });
+        if (!(await options.isPortListening(port, LOCAL_DEV_URL_HOST)))
+            return port;
+        nextCandidate = port + 1;
+    }
+    throw new Error(`无法找到可用端口（Vite 开发服务器），起始端口：${options.startPort}`);
+}
+async function resolveViteAppUrl(server, options, fetchImpl, timeoutMs) {
     const candidates = createViteAppUrlCandidates(server, options);
     for (const candidate of candidates) {
-        if (await canReachDocumentUrl(candidate, fetchImpl)) {
+        if (await canReachDocumentUrl(candidate, fetchImpl, timeoutMs)) {
             return candidate;
         }
     }
@@ -15654,11 +15707,12 @@ function createH5EntryUrl(origin, base) {
     const pathname = `${ensureTrailingSlash(base)}src/index.html`;
     return new URL(pathname, `${origin}/`).toString();
 }
-async function canReachDocumentUrl(url, fetchImpl) {
+async function canReachDocumentUrl(url, fetchImpl, timeoutMs) {
     try {
         const headResponse = await fetchImpl(url, {
             method: 'HEAD',
             redirect: 'follow',
+            signal: AbortSignal.timeout(timeoutMs),
         });
         if (headResponse.ok) {
             return true;
@@ -15669,6 +15723,7 @@ async function canReachDocumentUrl(url, fetchImpl) {
         const getResponse = await fetchImpl(url, {
             method: 'GET',
             redirect: 'follow',
+            signal: AbortSignal.timeout(timeoutMs),
         });
         return getResponse.ok;
     }

package/dist/cli-chunks/{doctor-r6m7pK1R.cjs → doctor-C3LLR1Hq.cjs}

@@ -3,7 +3,7 @@
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{index-CsQ1g-cL.cjs → index-B2kcpr9q.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-B6lVqj5W.cjs');
+var index$2 = require('./index-D4KcCSeD.cjs');
 var require$$0$3 = require('fs');
 var require$$0$2 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$5 = require('assert');
 var require$$0$4 = require('events');
 var require$$1$1 = require('util');
-var runtimePermissionEnv = require('./runtime-permission-env-DNXaBBHz.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D7X7T6VT.cjs');
 var require$$0$7 = require('net');
 var require$$0$6 = require('url');
 var require$$2$1 = require('http');

package/dist/cli-chunks/{index-B6lVqj5W.cjs → index-D4KcCSeD.cjs}

@@ -235,19 +235,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B6lVqj5W.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-D4KcCSeD.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B6lVqj5W.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-D4KcCSeD.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B6lVqj5W.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-D4KcCSeD.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B6lVqj5W.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-D4KcCSeD.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B6lVqj5W.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-D4KcCSeD.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13467,7 +13467,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.8.3-alpha.5';
+const BUILT_CLI_VERSION = '0.8.3-alpha.9';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13826,39 +13826,39 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DOUitUrc.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-C7Q6SStX.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DOUitUrc.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-C7Q6SStX.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DOUitUrc.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-C7Q6SStX.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-8dIKgG1v.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-Dd5EmgU1.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-DmNfBoq7.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-Bj08BLVt.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-C15G1TxE.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-BQtFwaZ6.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-r6m7pK1R.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-C3LLR1Hq.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunSkillInstallCommand = async (...args) => {
-    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-DAOCq0eg.cjs'); });
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-BXzVRK6G.cjs'); });
     return runSkillInstallCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-i3QX7A-u.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DrflbJjL.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index.esm-DG1EUOV-.cjs → index.esm-Dog1YTU_.cjs}

@@ -11,8 +11,8 @@ var require$$0$4 = require('url');
 var require$$0 = require('zlib');
 var require$$0$1 = require('buffer');
 var require$$1 = require('util');
-var index = require('./index-B6lVqj5W.cjs');
-var dev = require('./dev-C15G1TxE.cjs');
+var index = require('./index-D4KcCSeD.cjs');
+var dev = require('./dev-BQtFwaZ6.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');
@@ -23,12 +23,12 @@ require('node:crypto');
 require('readline');
 require('tty');
 require('assert');
-require('./context-DSNBFwsG.cjs');
-require('./runtime-permission-env-DNXaBBHz.cjs');
-require('./version-MrIy1W5p.cjs');
+require('./context-Cm0U_oeb.cjs');
+require('./runtime-permission-env-D7X7T6VT.cjs');
+require('./version-CHBZvmBz.cjs');
 require('node:async_hooks');
 require('sharp');
-require('./session-u4BpZqwE.cjs');
+require('./session-BC8gfXbM.cjs');
 require('fs');
 require('constants');
 require('node:os');
@@ -42,7 +42,7 @@ require('node:buffer');
 require('node:url');
 require('node:util');
 require('node:child_process');
-require('./project-vite-C-YGhyHJ.cjs');
+require('./project-vite-BWhbvrXL.cjs');
 require('node:zlib');
 
 var bufferUtil = {exports: {}};

package/dist/cli-chunks/{login-DOUitUrc.cjs → login-C7Q6SStX.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-u4BpZqwE.cjs');
+var session = require('./session-BC8gfXbM.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-C-YGhyHJ.cjs → project-vite-BWhbvrXL.cjs}

@@ -5,7 +5,7 @@ var fs$1 = require('node:fs/promises');
 var node_module = require('node:module');
 var path = require('node:path');
 var node_url = require('node:url');
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);

package/dist/cli-chunks/{remote-i3QX7A-u.cjs → remote-DrflbJjL.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-DNXaBBHz.cjs');
-var context = require('./context-DSNBFwsG.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D7X7T6VT.cjs');
+var context = require('./context-Cm0U_oeb.cjs');
 var promises = require('node:readline/promises');
-var index = require('./index-B6lVqj5W.cjs');
-var session = require('./session-u4BpZqwE.cjs');
+var index = require('./index-D4KcCSeD.cjs');
+var session = require('./session-BC8gfXbM.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
 var node_crypto = require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-hlz0xgg8.cjs');
-require('./version-MrIy1W5p.cjs');
+var runtimeGate = require('./runtime-gate-OEku3HCR.cjs');
+require('./version-CHBZvmBz.cjs');
 require('node:async_hooks');
 require('sharp');
 require('node:module');
@@ -274,7 +274,7 @@ function createDefaultCosClient(uploadToken, COS) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-CsQ1g-cL.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-B2kcpr9q.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{runtime-gate-hlz0xgg8.cjs → runtime-gate-OEku3HCR.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-DNXaBBHz.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D7X7T6VT.cjs');
 
 // Shorthands
 /**

package/dist/cli-chunks/{runtime-permission-env-DNXaBBHz.cjs → runtime-permission-env-D7X7T6VT.cjs}

@@ -2,7 +2,7 @@
 
 var fs = require('node:fs');
 var path = require('node:path');
-var version = require('./version-MrIy1W5p.cjs');
+var version = require('./version-CHBZvmBz.cjs');
 require('node:crypto');
 var node_async_hooks = require('node:async_hooks');
 

package/dist/cli-chunks/{session-u4BpZqwE.cjs → session-BC8gfXbM.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli-chunks/{skill-DAOCq0eg.cjs → skill-BXzVRK6G.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var version = require('./version-MrIy1W5p.cjs');
+var version = require('./version-CHBZvmBz.cjs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
 var childProcess = require('node:child_process');
-var index = require('./index-B6lVqj5W.cjs');
+var index = require('./index-D4KcCSeD.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{version-MrIy1W5p.cjs → version-CHBZvmBz.cjs}

@@ -3,6 +3,6 @@
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.5';
+    : '0.8.3-alpha.9';
 
 exports.HB_SDK_VERSION = HB_SDK_VERSION;