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

package/CHANGELOG.md

@@ -2,7 +2,66 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
-待发布：本地调试支持尚未获平台批准的普通网络与桌面辅助应用，并持续提示这些能力发布后仍不可用。浏览器 Mock 可在未登录、未绑定或远端暂不可用时启动；真实设备仍需有效调试会话，并在每次启动时确认临时权限。官方域名不在临时权限范围内。部署与发布前会提示声明中尚未获线上批准的权限。
+## 0.8.3 - 2026-09-24
+
+> 影响级别：必须操作
+> 开发者动作：升级至 `0.8.3`，声明 `package.json#heybox.category`，并按需复核 `package.json#heybox.platforms`。
+> 兼容范围：已发布版本不受影响；新能力按 Host 支持情况降级；缺少类别的历史构建需重新构建；平台声明的 `0.9.0` 切点不变。
+
+### 必须操作
+
+- 新上传版本必须声明 [`package.json#heybox.category`](https://docs.xiaoheihe.cn/hb_sdk/guide/project-configuration)（`tool`、`game` 或 `other`）；历史产物缺少类别时需重新构建。
+
+### 新增能力
+
+- `viewport.setDisplay()` 支持横竖屏与全屏设置；不支持的 Host 返回 `supported: false`。详见[展示状态与生命周期](https://docs.xiaoheihe.cn/hb_sdk/guide/lifecycle)。
+- `navigation.openAppPage()` 支持打开公开小程序，并由目标通过 `share.getExtra()` 读取启动数据。详见[跨小程序导航](https://docs.xiaoheihe.cn/hb_sdk/recipes/mini-program-navigation)。
+
+### 行为调整
+
+- [`hb-sdk dev` 临时权限](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions) 支持普通网络和 Companion 调试，不包含官方域名，也不会带到线上。
+- [新项目和历史缺声明产物](https://docs.xiaoheihe.cn/hb_sdk/guide/project-configuration) 默认覆盖 Android、iOS、OHOS、Windows 与 macOS；显式移动端声明只提示复核。
+- 浏览器调试台移除分端汇总状态，不可用原因改在对应入口展示。
+
+### 问题修复
+
+- 对齐浏览器预览与真机的导航栏前景色和顶部安全区。
+- 修复 `hb-sdk dev` 使用旧 Vite 产物时页面 SDK 版本不一致的问题。
+- 修复开发日志 CSP 循环告警。
+- 修复默认端口占用时 `hb-sdk dev` 卡在入口探测的问题。
+
+### 文档与工具
+
+- 补充[游戏详情页资源位申请指南](https://docs.xiaoheihe.cn/hb_sdk/guide/game-detail-resource-placement)。
+
+## 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
 

package/README.md

@@ -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、`.`、`..`、反斜杠、尾分隔符和控制字符。
@@ -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`。分享和复制链接可以携带小程序自行定义的页面状态：
@@ -438,7 +458,7 @@ hb-sdk remote deploy --release-note "本次更新说明"
 
 `hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示结构化日志、当前小程序作用域内的 Storage 快照和问题；日志区分 App、SDK、Network、Runtime、Host 来源，支持毫秒级时间、结果、耗时、重复计数、脱敏详情展开以及来源/级别筛选。右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
 
-配置 `package.json#heybox.companions`（平台写在 `package.json#heybox.platforms`）并启用无参 `miniappManifest()` 后，dev server 只向 loopback 提供 canonical Companion Manifest 和固定 ZIP 路由。CLI 在每次签发或刷新本地启动票前绑定 Manifest 摘要；普通 Web HMR 不改变 snapshot，权限声明、Companion 配置或产物变化会触发新快照与 Runtime 重建。调试台分别展示 Browser、手机和 PC 就绪状态，并保留本地临时权限与线上未批准警告。未配置 Companion 时真实 PC Companion 保持不可用，Browser Fake 可继续做状态联调。
+配置 `package.json#heybox.companions`（平台写在 `package.json#heybox.platforms`）并启用无参 `miniappManifest()` 后，dev server 只向 loopback 提供 canonical Companion Manifest 和固定 ZIP 路由。CLI 在每次签发或刷新本地启动票前绑定 Manifest 摘要；普通 Web HMR 不改变 snapshot，权限声明、Companion 配置或产物变化会触发新快照与 Runtime 重建。调试台不展示 Browser、手机和 PC 的汇总就绪状态；真实入口不可用时只在对应入口内说明原因，并继续保留本地临时权限与线上未批准警告。未配置 Companion 时真实 PC Companion 保持不可用，Browser Fake 可继续做状态联调。
 
 右上角的桌面图标与二维码按钮使用相同样式。桌面图标只在该项目于 `package.json#heybox.platforms` 声明了桌面平台（`windows`、`macos` 或 `linux`）时展示，未声明桌面平台的项目不显示该入口。点击桌面图标后选择小黑盒正式版或 Debug 版，选择会立即请求客户端打开当前本地页面并在本地记忆，不需要二次确认。桌面端只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择或手工 URL；手机二维码继续独立选择局域网地址。入口在项目已绑定且本地调试启动票有效时可用，统一 URI 只携带 `mini_program_id` 和 `mini_url`，启动票继续由 detail 从同源 `launch.json` 发现并交给后端验证。浏览器无法确认客户端是否真正打开，因此调试台只记录“已请求打开”，不会自动切换正式版或 Debug 版。
 

package/dist/cli-chunks/{build-BRLdyZ76.cjs → build-BMLuhvh9.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-Bjlpv6zh.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D2pJlHds.cjs');
 require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-DjTZ46xz.cjs');
-var index = require('./index-BVylxPGU.cjs');
-var projectVite = require('./project-vite-AGDPqVSX.cjs');
-require('./version-CNl684Yw.cjs');
+var runtimeGate = require('./runtime-gate-CDh8XjRx.cjs');
+var index = require('./index-BrJ7364Q.cjs');
+var projectVite = require('./project-vite-D9tmGT59.cjs');
+require('./version-BuPFCnrl.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-CbiL9O6w.cjs → context-BoNshqZO.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-Bjlpv6zh.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D2pJlHds.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-DnS1mH8i.cjs');
+var session = require('./session-BAw6iix6.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

package/dist/cli-chunks/{create-B7kL5QkJ.cjs → create-rUrkd162.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-BVylxPGU.cjs');
+var index = require('./index-BrJ7364Q.cjs');
 require('node:module');
 require('os');
 require('node:crypto');

package/dist/cli-chunks/{dev-DvH2_I1Y.cjs → dev-BRx7xYck.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var context = require('./context-CbiL9O6w.cjs');
+var context = require('./context-BoNshqZO.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-Bjlpv6zh.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D2pJlHds.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-BVylxPGU.cjs');
+var index = require('./index-BrJ7364Q.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-DnS1mH8i.cjs');
+var session = require('./session-BAw6iix6.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-AGDPqVSX.cjs');
-var version = require('./version-CNl684Yw.cjs');
+var projectVite = require('./project-vite-D9tmGT59.cjs');
+var version = require('./version-BuPFCnrl.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-DvH2_I1Y.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-DvH2_I1Y.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-BRx7xYck.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-BRx7xYck.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-Cwh5ei9-.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-CGFTxGm6.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-DMqILTR4.cjs → doctor-DOCFSRjQ.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-BVylxPGU.cjs');
+var index = require('./index-BrJ7364Q.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{index-BVylxPGU.cjs → index-BrJ7364Q.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-BVylxPGU.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-BrJ7364Q.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-BVylxPGU.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-BrJ7364Q.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-BVylxPGU.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-BrJ7364Q.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-BVylxPGU.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-BrJ7364Q.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-BVylxPGU.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-BrJ7364Q.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.6';
+const BUILT_CLI_VERSION = '0.8.3';
 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-BHAg3-HY.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DxtSW2QP.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-BHAg3-HY.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DxtSW2QP.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-BHAg3-HY.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DxtSW2QP.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-BRLdyZ76.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-BMLuhvh9.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-B7kL5QkJ.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-rUrkd162.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DvH2_I1Y.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-BRx7xYck.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DMqILTR4.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DOCFSRjQ.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunSkillInstallCommand = async (...args) => {
-    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-CUnigEtN.cjs'); });
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-Cu4QVawo.cjs'); });
     return runSkillInstallCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-jgmCl_OP.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DuiJdetu.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index-D8AT5s4x.cjs → index-CbmIweP8.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-BVylxPGU.cjs');
+var index$2 = require('./index-BrJ7364Q.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-Bjlpv6zh.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D2pJlHds.cjs');
 var require$$0$7 = require('net');
 var require$$0$6 = require('url');
 var require$$2$1 = require('http');

package/dist/cli-chunks/{index.esm-Cwh5ei9-.cjs → index.esm-CGFTxGm6.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-BVylxPGU.cjs');
-var dev = require('./dev-DvH2_I1Y.cjs');
+var index = require('./index-BrJ7364Q.cjs');
+var dev = require('./dev-BRx7xYck.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-CbiL9O6w.cjs');
-require('./runtime-permission-env-Bjlpv6zh.cjs');
-require('./version-CNl684Yw.cjs');
+require('./context-BoNshqZO.cjs');
+require('./runtime-permission-env-D2pJlHds.cjs');
+require('./version-BuPFCnrl.cjs');
 require('node:async_hooks');
 require('sharp');
-require('./session-DnS1mH8i.cjs');
+require('./session-BAw6iix6.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-AGDPqVSX.cjs');
+require('./project-vite-D9tmGT59.cjs');
 require('node:zlib');
 
 var bufferUtil = {exports: {}};

package/dist/cli-chunks/{login-BHAg3-HY.cjs → login-DxtSW2QP.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-DnS1mH8i.cjs');
+var session = require('./session-BAw6iix6.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-BVylxPGU.cjs');
+var index = require('./index-BrJ7364Q.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-AGDPqVSX.cjs → project-vite-D9tmGT59.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-BVylxPGU.cjs');
+var index = require('./index-BrJ7364Q.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);

package/dist/cli-chunks/{remote-jgmCl_OP.cjs → remote-DuiJdetu.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-Bjlpv6zh.cjs');
-var context = require('./context-CbiL9O6w.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D2pJlHds.cjs');
+var context = require('./context-BoNshqZO.cjs');
 var promises = require('node:readline/promises');
-var index = require('./index-BVylxPGU.cjs');
-var session = require('./session-DnS1mH8i.cjs');
+var index = require('./index-BrJ7364Q.cjs');
+var session = require('./session-BAw6iix6.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-DjTZ46xz.cjs');
-require('./version-CNl684Yw.cjs');
+var runtimeGate = require('./runtime-gate-CDh8XjRx.cjs');
+require('./version-BuPFCnrl.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-D8AT5s4x.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-CbmIweP8.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{runtime-gate-DjTZ46xz.cjs → runtime-gate-CDh8XjRx.cjs}

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

package/dist/cli-chunks/{runtime-permission-env-Bjlpv6zh.cjs → runtime-permission-env-D2pJlHds.cjs}

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

package/dist/cli-chunks/{session-DnS1mH8i.cjs → session-BAw6iix6.cjs}

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

package/dist/cli-chunks/{skill-CUnigEtN.cjs → skill-Cu4QVawo.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var version = require('./version-CNl684Yw.cjs');
+var version = require('./version-BuPFCnrl.cjs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
 var childProcess = require('node:child_process');
-var index = require('./index-BVylxPGU.cjs');
+var index = require('./index-BrJ7364Q.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{version-CNl684Yw.cjs → version-BuPFCnrl.cjs}

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