@heybox/hb-sdk 0.8.0-alpha.3 → 0.8.0-alpha.9

package/README.md

@@ -13,7 +13,7 @@ SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部
 ### 创建新项目
 
 ```bash
-npx @heybox/hb-sdk@latest create my-miniapp
+npx @heybox/hb-sdk@alpha create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
@@ -21,6 +21,8 @@ npm run dev
 
 脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试台的二维码入口使用手机小黑盒 APP 验收。
 
+当前 `0.8` 模板位于 alpha 发布线；稳定版本发布后，创建命令会恢复使用 `@latest`。
+
 ### 接入已有项目
 
 ```bash
@@ -212,7 +214,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 
 ## 分享扩展数据
 
-默认分享和复制链接可以携带小程序自行定义的页面状态：
+`share.showShareMenu()` 的落地页固定为当前小程序的 `common_share`，不接受自定义 `url`。分享和复制链接可以携带小程序自行定义的页面状态：
 
 ```ts
 await hbSDK.share.showShareMenu({
@@ -270,6 +272,8 @@ hb-sdk remote deploy --release-note "本次更新说明"
 | `hb-sdk build`         | 执行生产构建与产物校验，不包含类型检查 |
 | `hb-sdk remote deploy` | 构建、上传并提交当前版本审核           |
 
+`hb-sdk create` 默认生成可直接删除的 Vanilla JavaScript + Vite HelloWorld，只保留 SDK Toast 示例、三端 Manifest 和开发/构建/部署命令，不绑定业务框架或项目内测试工具。
+
 `hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示调用日志、当前小程序作用域内的 Storage 快照和问题，右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
 
 浏览器调试入口不要求 CLI 登录或项目绑定；需要账号或远端配置的能力会按当前可用上下文返回结果或明确失败。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。

package/dist/cli-chunks/{build-qWzAbpS7.cjs → build-DkokKVNy.cjs}

@@ -5,8 +5,8 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 var runtimeGate = require('./runtime-gate-DFjw66kF.cjs');
-var index = require('./index-De687C6-.cjs');
-var projectVite = require('./project-vite-1rvkK-M8.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
+var projectVite = require('./project-vite-BIPrOtRO.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-CtS2Thp0.cjs → context-CKzZxKbF.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var session = require('./session-CzaM2Cq3.cjs');
+var session = require('./session-B6Mo9eYW.cjs');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');

package/dist/cli-chunks/{create-PV5ua977.cjs → create-BQy5Jdmu.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-De687C6-.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 require('node:module');
 require('os');
 require('readline');
@@ -1238,7 +1238,7 @@ function requireEjs () {
 
 var ejsExports = requireEjs();
 
-const TEMPLATE_NAME = 'vue3-vite-ts';
+const TEMPLATE_NAME = 'vanilla-vite-js';
 const TEMPLATE_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'templates', TEMPLATE_NAME),
     path.resolve(__dirname, '..', 'templates', TEMPLATE_NAME),

package/dist/cli-chunks/{dev-CwKbAm_H.cjs → dev-Dik2zr5R.cjs}

@@ -8,16 +8,16 @@ var node_crypto = require('node:crypto');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
 var node_module = require('node:module');
-var context = require('./context-CtS2Thp0.cjs');
+var context = require('./context-CKzZxKbF.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-De687C6-.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CzaM2Cq3.cjs');
+var session = require('./session-B6Mo9eYW.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-1rvkK-M8.cjs');
-var version = require('./version-Bz-AfXQU.cjs');
+var projectVite = require('./project-vite-BIPrOtRO.cjs');
+var version = require('./version-DDB_btOG.cjs');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1605,7 +1605,7 @@ async function selectAvailablePort(options) {
         port: createPortCandidates(options.startPort, maxAttempts),
     });
     if (port < options.startPort || port >= options.startPort + maxAttempts) {
-        throw new Error(`无法找到可用 ${options.label} 端口，起始端口: ${options.startPort}`);
+        throw new Error(`无法找到可用端口（${options.label}），起始端口：${options.startPort}`);
     }
     return port;
 }
@@ -1851,8 +1851,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-CwKbAm_H.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-CwKbAm_H.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-Dik2zr5R.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-Dik2zr5R.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'),
@@ -2968,7 +2968,7 @@ async function listenHttpServer(server, options, getPortImpl, listen) {
         const port = await selectAvailablePort({
             getPort: getPortImpl,
             host: DEV_PORT_PROBE_HOST,
-            label: 'browser dev host',
+            label: '浏览器调试页服务',
             maxAttempts: lastCandidate - nextCandidate + 1,
             startPort: nextCandidate,
         });
@@ -2987,7 +2987,7 @@ async function listenHttpServer(server, options, getPortImpl, listen) {
             nextCandidate = port + 1;
         }
     }
-    throw lastAddressInUseError ?? new Error(`无法找到可用 browser dev host 端口，起始端口: ${options.port}`);
+    throw lastAddressInUseError ?? new Error(`无法找到可用浏览器调试页服务端口，起始端口：${options.port}`);
 }
 const listenBrowserDevHostServer = (server, options) => new Promise((resolve, reject) => {
     const onError = (error) => {
@@ -10895,7 +10895,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-B-4yrLNm.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-BYifBABc.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -14960,7 +14960,7 @@ const DEFAULT_BROWSER_DEV_HOST_PORT = 5174;
 const DEFAULT_DEV_CONTEXT_TIMEOUT_MS = 3000;
 const DEV_LISTEN_HOST = '0.0.0.0';
 const LOCAL_DEV_URL_HOST = '127.0.0.1';
-// Shared with Heybox H5 Vite plugins so hb-sdk can own the launch output.
+// 与 Heybox H5 Vite 插件共享，让 hb-sdk 统一管理启动输出。
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
 async function runDevCommand(options, runtime = {}) {
@@ -14975,7 +14975,7 @@ async function runDevCommand(options, runtime = {}) {
     const appPort = await selectAvailablePort({
         getPort: getPortImpl,
         host: DEV_LISTEN_HOST,
-        label: 'Vite dev server',
+        label: 'Vite 开发服务器',
         startPort: options.port ?? DEFAULT_APP_PORT,
     });
     const resolvedOptions = {
@@ -14992,8 +14992,8 @@ async function runDevCommand(options, runtime = {}) {
         timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
     const launchRuntimePermissions = context.createBrowserDevRuntimePermissions(context.createBrowserDevPermissionState(devLaunchContext));
-    const vite = await logger.task('正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), { successText: '已加载项目 Vite' });
-    const appServer = await logger.task('正在创建 Vite dev server', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), { successText: '已创建 Vite dev server' });
+    const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
+    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), '已创建 Vite 开发服务器');
     const mobileDevContextUrlsByOrigin = new Map();
     let currentLocalDevLaunchToken = devLaunchContext.localDevLaunchToken;
     appServer.middlewares.use((request, response, next) => {
@@ -15007,12 +15007,8 @@ async function runDevCommand(options, runtime = {}) {
         if (!handled)
             next();
     });
-    await logger.task('正在启动 Vite dev server', () => appServer.listen(appPort), {
-        successText: 'Vite dev server 已启动',
-    });
-    const appUrl = await logger.task('正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), {
-        successText: '已确定小程序入口',
-    });
+    await runDevStartupTask(logger, '正在启动 Vite 开发服务器', () => appServer.listen(appPort), 'Vite 开发服务器已启动');
+    const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
         appUrl,
         devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
@@ -15027,7 +15023,7 @@ async function runDevCommand(options, runtime = {}) {
     const closers = [() => appServer.close()];
     let browserDevHost;
     try {
-        browserDevHost = await logger.task('正在启动 Browser Dev Host', () => startBrowserDevHostServer({
+        browserDevHost = await runDevStartupTask(logger, '正在启动浏览器调试页服务', () => startBrowserDevHostServer({
             appUrl,
             devContext: devLaunchContext,
             fetchImpl,
@@ -15048,7 +15044,7 @@ async function runDevCommand(options, runtime = {}) {
             root: runtime.browserDevHostRoot,
             rootCandidates: runtime.browserDevHostRootCandidates,
             runtimePermissions: devLaunchContext.runtimePermissions,
-        }), { successText: 'Browser Dev Host 已启动' });
+        }), '浏览器调试页服务已启动');
     }
     catch (error) {
         await closeAll(closers);
@@ -15079,23 +15075,29 @@ async function runDevCommand(options, runtime = {}) {
         });
         closers.push(tokenSession.close);
     }
-    logger.success('Browser Dev Host 已就绪');
-    logger.info(`Browser Dev Host: ${browserDevHost.url}`);
-    logger.info(`Mini program URL: ${appUrl}`);
-    logger.info('Mobile APP: scan the QR code in Browser Dev Host');
+    logger.success('本地调试已启动');
+    logger.info(`调试页：${browserDevHost.url}`);
+    logger.info(`小程序地址：${appUrl}`);
+    logger.info('手机调试：请在调试页扫码');
     if (options.open !== false) {
         logger.debug('正在打开浏览器调试页');
         void openUrl(browserDevHost.url);
     }
     installShutdownHandlers(closers, runtime.process ?? process);
 }
+function runDevStartupTask(logger, text, action, successText) {
+    if (!logger.verbose) {
+        return action();
+    }
+    return logger.task(text, () => action(), { successText });
+}
 async function loadDevLaunchContext(options) {
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId) {
         throw new Error('hb-sdk dev 需要绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。');
     }
     try {
-        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
+        const { detail, miniProgramId: verifiedMiniProgramId } = await runDevStartupTask(options.logger, '正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
             fetchImpl: options.fetchImpl,
             load: (fetchImpl) => context.getBoundMiniProgram({
                 cwd: options.projectRoot,
@@ -15103,7 +15105,7 @@ async function loadDevLaunchContext(options) {
                 fetchImpl,
             }),
             timeoutMs: options.timeoutMs,
-        }), { successText: '已读取远端小程序权限' });
+        }), '已读取远端小程序权限');
         return {
             context: {
                 source: 'remote',
@@ -15303,25 +15305,30 @@ async function closeAll(closers) {
 function startLocalDevLaunchTokenSession(options) {
     let closed = false;
     let expirationTimer;
+    let hasReportedTokenFailure = false;
     let refreshTimer;
     const refresh = async () => {
         try {
             const issued = await issueLocalDevLaunchToken(options);
             if (closed)
                 return;
-            if (!issued) {
-                schedule(options.timeoutMs);
-                return;
-            }
             options.onToken(issued.token);
             const ttl = Math.max(0, issued.expiresAt - Date.now());
             scheduleExpiration(ttl);
             schedule(Math.max(1_000, Math.floor(ttl * 0.8)));
+            if (hasReportedTokenFailure) {
+                hasReportedTokenFailure = false;
+                options.logger.success('手机扫码调试已恢复');
+            }
         }
         catch (error) {
             if (closed)
                 return;
-            options.logger.warn(`刷新本地调试启动票失败，将自动重试：${index.readRedactedErrorMessage(error)}`);
+            if (!hasReportedTokenFailure) {
+                options.logger.warn('手机扫码调试凭证获取失败，将自动重试');
+            }
+            hasReportedTokenFailure = true;
+            options.logger.debug(`手机扫码调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
             schedule(options.timeoutMs);
         }
     };
@@ -15352,31 +15359,25 @@ function startLocalDevLaunchTokenSession(options) {
     };
 }
 async function issueLocalDevLaunchToken(options) {
-    try {
-        const issued = await loadRemoteDevContextWithTimeout({
-            fetchImpl: options.fetchImpl,
-            timeoutMs: options.timeoutMs,
-            load: (fetchImpl) => context.createLocalDevLaunchToken({
-                cwd: options.projectRoot,
-                env: options.env,
-                fetchImpl,
-                miniProgramId: options.miniProgramId,
-            }),
-        });
-        const token = typeof issued.token === 'string' ? issued.token.trim() : '';
-        if (!token) {
-            throw new Error('响应缺少 token');
-        }
-        const expiresAt = normalizeExpiresAt(issued.expires_at);
-        if (!expiresAt || expiresAt <= Date.now()) {
-            throw new Error('响应缺少有效 expires_at');
-        }
-        return { expiresAt, token };
+    const issued = await loadRemoteDevContextWithTimeout({
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs,
+        load: (fetchImpl) => context.createLocalDevLaunchToken({
+            cwd: options.projectRoot,
+            env: options.env,
+            fetchImpl,
+            miniProgramId: options.miniProgramId,
+        }),
+    });
+    const token = typeof issued.token === 'string' ? issued.token.trim() : '';
+    if (!token) {
+        throw new Error('响应缺少 token');
     }
-    catch (error) {
-        options.logger.warn(`未能签发本地调试启动票，扫码后公开详情可能仍拿不到未发布小程序身份：${index.readRedactedErrorMessage(error)}`);
-        return undefined;
+    const expiresAt = normalizeExpiresAt(issued.expires_at);
+    if (!expiresAt || expiresAt <= Date.now()) {
+        throw new Error('响应缺少有效 expires_at');
     }
+    return { expiresAt, token };
 }
 function normalizeExpiresAt(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)

package/dist/cli-chunks/{doctor-tJUGOYrm.cjs → doctor-Byr4uwKG.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-De687C6-.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{index-De687C6-.cjs → index-BwGBr1ZA.cjs}

@@ -234,19 +234,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-De687C6-.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-BwGBr1ZA.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-De687C6-.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-BwGBr1ZA.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-De687C6-.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-BwGBr1ZA.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-De687C6-.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-BwGBr1ZA.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-De687C6-.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-BwGBr1ZA.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -12833,6 +12833,7 @@ const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 1500;
 const UPDATE_CHECK_CACHE_FILE = 'update-check.json';
 const NPM_REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(HB_SDK_PACKAGE_NAME)}`;
+const PUBLIC_CHANGELOG_URL = 'https://docs.xiaoheihe.cn/hb_sdk/changelog/';
 const paths = envPaths('hb-sdk', { suffix: '' });
 const PACKAGE_JSON_CANDIDATES$1 = [
     path.resolve(__dirname, '..', 'package.json'),
@@ -12887,14 +12888,23 @@ async function getUpdateReminder(options = {}) {
     return createUpdateReminder(currentVersion, latestVersion);
 }
 function formatUpdateReminder(reminder) {
-    return `发现新版 ${HB_SDK_PACKAGE_NAME}: ${reminder.currentVersion} -> ${reminder.latestVersion}。升级命令: npm i -D ${HB_SDK_PACKAGE_NAME}@latest`;
+    const latestVersion = parseSemver(reminder.latestVersion);
+    const anchor = latestVersion
+        ? `v${latestVersion.major}-${latestVersion.minor}-${latestVersion.patch}`
+        : `v${reminder.latestVersion.replaceAll('.', '-')}`;
+    const changelogUrl = `${PUBLIC_CHANGELOG_URL}#${anchor}`;
+    return `发现新版 ${HB_SDK_PACKAGE_NAME}: ${reminder.currentVersion} -> ${reminder.latestVersion}。升级命令: npm i -D ${HB_SDK_PACKAGE_NAME}@latest；更新内容: ${changelogUrl}`;
 }
 function isVersionGreater(version, baseline) {
     const compared = compareSemver(version, baseline);
     return compared !== null && compared > 0;
 }
 function createUpdateReminder(currentVersion, latestVersion) {
-    if (!latestVersion || !isVersionGreater(latestVersion, currentVersion)) {
+    const parsedLatestVersion = latestVersion ? parseSemver(latestVersion) : null;
+    if (!latestVersion ||
+        !parsedLatestVersion ||
+        parsedLatestVersion.prerelease.length > 0 ||
+        !isVersionGreater(latestVersion, currentVersion)) {
         return null;
     }
     return {
@@ -13343,7 +13353,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.8.0-alpha.3';
+const BUILT_CLI_VERSION = '0.8.0-alpha.9';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13429,10 +13439,11 @@ function createCliProgram(overrides = {}) {
     }, handlers.printUpdateReminder, resolveLogger));
     addVerboseOption(program
         .command('dev')
-        .description('启动当前小程序项目的 Vite dev server 和 Browser Dev Host')
-        .option('--port <port>', 'App dev server 端口', parsePositivePort)
-        .option('--browser-dev-host-port <port>', 'Browser Dev Host 端口', parsePositivePort)
-        .option('--no-open', '不自动打开浏览器调试页')).action(withUpdateReminder(async (options, command) => {
+        .description('启动当前小程序项目的 Vite 开发服务器和浏览器调试页服务')
+        .option('--port <port>', '小程序开发服务器端口', parsePositivePort)
+        .option('--browser-dev-host-port <port>', '浏览器调试页服务端口', parsePositivePort)
+        .option('--no-open', '不自动打开浏览器调试页')
+        .helpOption('-h, --help', '显示命令帮助')).action(withUpdateReminder(async (options, command) => {
         const logger = resolveLogger(command);
         await handlers.runDevCommand(options, { logger });
     }, handlers.printUpdateReminder, resolveLogger));
@@ -13690,39 +13701,39 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DolpqD8K.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Dr9lclu3.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DolpqD8K.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Dr9lclu3.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DolpqD8K.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Dr9lclu3.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-qWzAbpS7.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-DkokKVNy.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-PV5ua977.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BQy5Jdmu.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-CwKbAm_H.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-Dik2zr5R.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-tJUGOYrm.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-Byr4uwKG.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunSkillInstallCommand = async (...args) => {
-    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-CM40_9WH.cjs'); });
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-f90sxv28.cjs'); });
     return runSkillInstallCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-rIAQE_G2.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DXxyA14a.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index-DVuD75Hr.cjs → index-Cl0XaX8e.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index$2 = require('./index-De687C6-.cjs');
+var index$2 = require('./index-BwGBr1ZA.cjs');
 var require$$0$3 = require('fs');
 var require$$0$2 = require('crypto');
 var require$$1$2 = require('path');

package/dist/cli-chunks/{index.esm-B-4yrLNm.cjs → index.esm-BYifBABc.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-De687C6-.cjs');
-var dev = require('./dev-CwKbAm_H.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
+var dev = require('./dev-Dik2zr5R.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');
@@ -27,8 +27,8 @@ require('node:net');
 require('node:crypto');
 require('node:dns/promises');
 require('node:http');
-require('./context-CtS2Thp0.cjs');
-require('./session-CzaM2Cq3.cjs');
+require('./context-CKzZxKbF.cjs');
+require('./session-B6Mo9eYW.cjs');
 require('fs');
 require('constants');
 require('./runtime-permission-env-CjsCe5bp.cjs');
@@ -40,8 +40,8 @@ require('node:buffer');
 require('node:url');
 require('node:util');
 require('node:child_process');
-require('./project-vite-1rvkK-M8.cjs');
-require('./version-Bz-AfXQU.cjs');
+require('./project-vite-BIPrOtRO.cjs');
+require('./version-DDB_btOG.cjs');
 
 var bufferUtil = {exports: {}};
 

package/dist/cli-chunks/{login-DolpqD8K.cjs → login-Dr9lclu3.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-CzaM2Cq3.cjs');
+var session = require('./session-B6Mo9eYW.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-De687C6-.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-1rvkK-M8.cjs → project-vite-BIPrOtRO.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-De687C6-.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);

package/dist/cli-chunks/{remote-rIAQE_G2.cjs → remote-DXxyA14a.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var index = require('./index-De687C6-.cjs');
-var session = require('./session-CzaM2Cq3.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
+var session = require('./session-B6Mo9eYW.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
@@ -10,7 +10,7 @@ var path = require('node:path');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 var runtimeGate = require('./runtime-gate-DFjw66kF.cjs');
 var node_crypto = require('node:crypto');
-var context = require('./context-CtS2Thp0.cjs');
+var context = require('./context-CKzZxKbF.cjs');
 require('node:module');
 require('path');
 require('os');
@@ -271,7 +271,7 @@ function createDefaultCosClient(uploadToken, COS) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-DVuD75Hr.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-Cl0XaX8e.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{session-CzaM2Cq3.cjs → session-B6Mo9eYW.cjs}

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

package/dist/cli-chunks/{skill-CM40_9WH.cjs → skill-f90sxv28.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
 var path = require('node:path');
-var version = require('./version-Bz-AfXQU.cjs');
+var version = require('./version-DDB_btOG.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs/promises');
-var index = require('./index-De687C6-.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{version-Bz-AfXQU.cjs → version-DDB_btOG.cjs}

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

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-De687C6-.cjs');
+var index = require('./cli-chunks/index-BwGBr1ZA.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');