@heybox/hb-sdk 0.9.5-alpha.1 → 0.9.5-alpha.3

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.5-alpha.3 - 2026-10-30
+
+### 新增能力
+
+- [hb-sdk dev](https://docs.xiaoheihe.cn/hb_sdk/guide/cli) 调试台新增“桌面”预览，按[窗口尺寸声明](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size.html)初始化窗口，支持拖拽缩放、最大化与还原、最小化后恢复同一实例，以及关闭后重新打开；系统信息跟随运行 CLI 的本机，`viewport.setDisplay()` 返回不支持。
+
+### 文档与工具
+
+- 桌面预览使用深色标题栏和胶囊窗口操作区，“更多”中支持复制链接与刷新；修复刷新按钮被工具栏挤压成椭圆的问题。
+
+## 0.9.5-alpha.2 - 2026-10-29
+
+### 文档与工具
+
+- [CLI 版本提醒](https://docs.xiaoheihe.cn/hb_sdk/guide/cli#%E7%89%88%E6%9C%AC%E6%8F%90%E9%86%92)支持在交互终端启动时展示已审核的重点更新；直接回车继续，同一版本按本地日期每天最多提醒一次，输入 `y` 并回车后不再展示该版本公告，后续 npm 升级提示仍保留，新版本公告仍可提醒；提醒独立分块，以「行为变更，请关注」为标题并用颜色强调确认选项；已安装更高版本时提示核对已升级版本的行为变更。
+- 重点提醒获取失败不影响命令执行，按 `Ctrl+C` 会取消本次命令；非交互环境、CI 和 JSON 输出不展示重点提醒。
+- SDK Skill 补充已审核更新通知的读取指引，开发和升级时结合项目版本及实际使用能力检查相关变更。
+- [更新提醒](https://docs.xiaoheihe.cn/hb_sdk/guide/update-notices)按稳定版展示人工编写的重大提示；没有重大更新时可保留空正文。
+
+
 ## 0.9.5-alpha.1 - 2026-10-29
 
 ### 文档与工具

package/README.md

@@ -505,7 +505,7 @@ CLI 会复用已验证产物、跳过该 ZIP 的网络上传；Web 文件及发
 
 `hb-sdk create` 默认生成可直接删除的 Vanilla JavaScript + Vite HelloWorld，只保留 SDK Toast 示例、三端 Manifest 和开发/构建/部署命令，不绑定业务框架或项目内测试工具。
 
-`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 和振动反馈都限制在预览框内。
+`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；切换手机与桌面会重新加载小程序并建立新实例。桌面模式按 `package.json#heybox.window` 初始化可缩放窗口，支持拖拽缩放、最大化/还原、最小化后恢复同一实例、关闭后重新打开新实例；系统信息与视口按运行 `hb-sdk dev` 的本机与窗口内容尺寸上报，`viewport.setDisplay()` 返回不支持，不模拟旋转或全屏。授权与操作弹窗、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/dist/cli-chunks/{artifact-CevKlc1g.cjs → artifact-qcqjww0s.cjs}

@@ -3,9 +3,9 @@
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-BF-Jw5-T.cjs');
-require('./version-CArGts-T.cjs');
-var index = require('./index-xZw-b2po.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-BfP6motG.cjs');
+require('./version-DyS8HIuU.cjs');
+var index = require('./index-C3p93h2e.cjs');
 var node_crypto = require('node:crypto');
 require('node:zlib');
 require('node:module');

package/dist/cli-chunks/{build-CF1-28D8.cjs → build-DCgpTg32.cjs}

@@ -2,14 +2,14 @@
 
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-BF-Jw5-T.cjs');
-var index = require('./index-xZw-b2po.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-BfP6motG.cjs');
+var index = require('./index-C3p93h2e.cjs');
 require('node:crypto');
 require('node:fs');
 require('node:zlib');
-var artifact = require('./artifact-CevKlc1g.cjs');
-var projectVite = require('./project-vite-CgMLPNS6.cjs');
-require('./version-CArGts-T.cjs');
+var artifact = require('./artifact-qcqjww0s.cjs');
+var projectVite = require('./project-vite-C48AvOrg.cjs');
+require('./version-DyS8HIuU.cjs');
 require('node:async_hooks');
 require('node:module');
 require('readline');
@@ -23,6 +23,8 @@ require('util');
 require('path');
 require('fs');
 require('constants');
+require('node:readline/promises');
+require('node:timers/promises');
 require('node:url');
 require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
 require('inspector');

package/dist/cli-chunks/{create-Q50un0Bg.cjs → create-B1R3GzUJ.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-xZw-b2po.cjs');
+var index = require('./index-C3p93h2e.cjs');
 require('node:module');
 require('readline');
 require('os');
@@ -18,6 +18,8 @@ require('util');
 require('node:crypto');
 require('constants');
 require('node:zlib');
+require('node:readline/promises');
+require('node:timers/promises');
 
 var ejs = {};
 

package/dist/cli-chunks/{dev-Bsa-tW7L.cjs → dev-BktX-Knf.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index = require('./index-xZw-b2po.cjs');
+var index = require('./index-C3p93h2e.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-BF-Jw5-T.cjs');
-var version = require('./version-CArGts-T.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-BfP6motG.cjs');
+var version = require('./version-DyS8HIuU.cjs');
 require('node:zlib');
-var devContext = require('./dev-context-D007Z2-c.cjs');
+var devContext = require('./dev-context-CE4HgJig.cjs');
 var os = require('node:os');
 var net = require('node:net');
 var promises = require('node:dns/promises');
@@ -18,7 +18,7 @@ var fs$1 = require('node:fs/promises');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-CgMLPNS6.cjs');
+var projectVite = require('./project-vite-C48AvOrg.cjs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const DEFAULT_DEV_CONTEXT_TIMEOUT_MS = 3000;
@@ -3056,8 +3056,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-Bsa-tW7L.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-Bsa-tW7L.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-BktX-Knf.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-BktX-Knf.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'),
@@ -3093,6 +3093,8 @@ async function startBrowserDevHostServer(options) {
         miniProgram: options.miniProgram,
         miniProgramSupportsDesktop: options.miniProgramSupportsDesktop,
         workspaceCardsEnabled: options.workspaceCardsEnabled === true,
+        windowForm: options.windowForm,
+        hostPlatform: options.hostPlatform,
         mobileLaunchRedirect: initialMobileLaunchRedirect,
         nativeAppLaunchUnavailableReason: options.nativeAppLaunchUnavailableReason,
         miniProgramManifestAccessToken: options.miniProgramManifestAccessToken,
@@ -12183,7 +12185,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-hwkHnZhi.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-BjwRn4Dl.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -16517,12 +16519,30 @@ const COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TO
 // 本地 PC 调试 manifest 的专用令牌：开窗时扩展还没拿到 LocalDevelopmentBinding，只能靠启动 URI 带来。
 const MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = 'HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN';
 const COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER = 'x-hb-sdk-companion-dev-token';
+/**
+ * 把 Node 的 `process.platform` 归一为桌面预览使用的系统名。
+ *
+ * 桌面模式下 SDK `environment.getInfo()` 返回的是**运行 CLI 的电脑**，而不是浏览器看到的系统；
+ * 未知平台回落到 `'unknown'`，不猜测成 Windows。
+ */
+function resolveHostPlatform(platform) {
+    if (platform === 'darwin')
+        return 'macos';
+    if (platform === 'win32')
+        return 'windows';
+    if (platform === 'linux')
+        return 'linux';
+    return 'unknown';
+}
 async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const fetchImpl = runtime.fetchImpl ?? fetch;
     const openUrl = runtime.openExternalUrl ?? browser.openExternalUrl;
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
     const workspaceCardsDeclared = runtimePermissionEnv.readMiniappWorkspaceCardsFromPackageJson(projectRoot).declaration !== undefined;
+    // 与 build 使用同一个声明校验入口：非法声明直接冒泡，避免调试台用错误尺寸静默预览。
+    const windowForm = runtimePermissionEnv.readMiniappWindowFromPackageJson(projectRoot);
+    const hostPlatform = runtime.hostPlatform ?? resolveHostPlatform(process.platform);
     const companionArtifactAccessToken = (runtime.randomBytes ?? node_crypto.randomBytes)(32).toString('base64url');
     const miniProgramManifestAccessToken = (runtime.randomBytes ?? node_crypto.randomBytes)(32).toString('base64url');
     const devSessionId = node_crypto.randomBytes(16).toString('hex');
@@ -16703,6 +16723,9 @@ async function runDevCommand(options, runtime = {}) {
             // 只在项目声明了桌面平台时向调试台暴露「在桌面端打开」入口。
             miniProgramSupportsDesktop: sessionView.miniProgramSupportsDesktop,
             workspaceCardsEnabled: workspaceCardsDeclared,
+            // 桌面预览按项目声明初始化窗口尺寸，并按运行 CLI 的真实系统生成环境信息。
+            windowForm,
+            hostPlatform,
             cliAuth: runtime.cliAuth ?? createBrowserDevHostCliAuth({ env: runtime.env, fetchImpl }),
             onMobileDevSessionCreated: ({ devContextUrl, miniUrlOrigin }) => {
                 mobileDevContextUrlsByOrigin.set(miniUrlOrigin, devContextUrl);
@@ -17078,6 +17101,7 @@ function isPrivateIPv4(address) {
 var dev = /*#__PURE__*/Object.freeze({
     __proto__: null,
     createMiniProgramDevLaunchVitePlugin: createMiniProgramDevLaunchVitePlugin,
+    resolveHostPlatform: resolveHostPlatform,
     runDevCommand: runDevCommand
 });
 

package/dist/cli-chunks/{dev-context-D007Z2-c.cjs → dev-context-CE4HgJig.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var index = require('./index-xZw-b2po.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-BF-Jw5-T.cjs');
+var index = require('./index-C3p93h2e.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-BfP6motG.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');

package/dist/cli-chunks/{doctor-CIWDaPfi.cjs → doctor-ahqYzMjt.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-xZw-b2po.cjs');
+var index = require('./index-C3p93h2e.cjs');
 require('node:module');
 require('readline');
 require('os');
@@ -19,6 +19,8 @@ require('fs');
 require('constants');
 require('node:fs');
 require('node:zlib');
+require('node:readline/promises');
+require('node:timers/promises');
 
 const CANDIDATES = [
     path.resolve(__dirname, '..', 'package.json'),

package/dist/cli-chunks/{games-CNjfXQjT.cjs → games-DeOUz5bI.cjs}

@@ -3,8 +3,7 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var index = require('./index-xZw-b2po.cjs');
-var deployLock = require('./deploy-lock-CpdL3s9E.cjs');
+var index = require('./index-C3p93h2e.cjs');
 require('node:module');
 require('readline');
 require('os');
@@ -19,6 +18,8 @@ require('fs');
 require('constants');
 require('node:fs');
 require('node:zlib');
+require('node:readline/promises');
+require('node:timers/promises');
 
 const WINDOW_MS = 30 * 60 * 1000;
 const MAX_REQUESTS = 50;
@@ -29,10 +30,10 @@ async function reserveGameSearchRequest(account, apiBaseUrl, options = {}) {
     const scope = node_crypto.createHash('sha256').update(`${apiBaseUrl}\0${account}`).digest('hex');
     let lock;
     try {
-        lock = await deployLock.acquireDeployLock({ apiBaseUrl, miniProgramId: `game-search:${scope}`, version: 'rate-limit-v1' }, { cacheRoot });
+        lock = await index.acquireDeployLock({ apiBaseUrl, miniProgramId: `game-search:${scope}`, version: 'rate-limit-v1' }, { cacheRoot });
     }
     catch (error) {
-        if (error instanceof Error && error.message === deployLock.DEPLOY_LOCKED_MESSAGE) {
+        if (error instanceof Error && error.message === index.DEPLOY_LOCKED_MESSAGE) {
             throw new Error('游戏搜索请求正在处理中，请稍后重试');
         }
         throw error;