@heybox/hb-sdk 0.8.3-alpha.3 → 0.8.3-alpha.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+待发布：本地调试支持尚未获平台批准的普通网络与桌面辅助应用，并持续提示这些能力发布后仍不可用。浏览器 Mock 可在未登录、未绑定或远端暂不可用时启动；真实设备仍需有效调试会话，并在每次启动时确认临时权限。官方域名不在临时权限范围内。部署与发布前会提示声明中尚未获线上批准的权限。
+
+## 0.8.3-alpha.4 - 2026-09-23
+
+> 摘要：增加本地临时权限调试支持，并收紧 Dev Context、Runtime lease 与真实 Host 清理边界。
+> 影响级别：常规
+> 开发者动作：无需修改业务 SDK API；真实 PC Companion 需要支持私有 local-dev lease 的 Host 版本。
+> 兼容范围：线上批准、官方域名和生产发布权限模型保持不变。
+
+### 行为调整
+
+- 本地声明的普通 `network` 与 `companion` 可在有效调试会话中临时联调，调试台持续提示线上未批准。
+- 手机二维码短期引用与稳定 Dev Context 分离；票据轮换不会单独重建运行中的 Runtime。
+- 缺少私有 local-dev lease capability 的旧 PC Host 会安全拒绝真实临时 Companion，Browser Fake 和普通 network 仍可用。
+
 ## 0.8.3-alpha.3 - 2026-09-20
 
 > 摘要：新增移动端横竖屏与全屏设置，并提供宿主退出全屏入口和展示状态通知。
@@ -19,7 +34,6 @@
 - 全屏时提供贴右边缘的退出按钮，一秒后收起并保留可点击入口；用户退出时恢复竖屏、非全屏。
 - 展示设置支持状态去重、并发淘汰、超时取消和退出恢复；页面按实际 WebView 窗口与安全区适配。
 
-
 ## 0.8.3-alpha.2
 
 ### 新增能力

package/README.md

@@ -54,7 +54,7 @@ hb-sdk skill install --all-agents
 
 SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。声明 `userInfo` 后，可通过 `user.getInfo()` 读取当前小程序内的隔离身份和已授权资料：
 
-使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 都只需要 `userInfo`，不依赖公开 `network` 权限；`network` 仅约束 `network.request()` 与 `network.download()`，并且声明后仍需平台批准。完整配置、无需声明白名单和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
+使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 都只需要 `userInfo`，不依赖公开 `network` 权限；`network` 仅约束 `network.request()` 与 `network.download()`，线上使用仍需平台批准。`hb-sdk dev` 可临时补齐普通网络和 Companion 的批准缺口，但不能补齐官方域名，调试台会持续提示发布后不可用。完整配置、本地调试边界和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
 
 需要可信用户手势的按钮不能在点击回调里等待握手。页面加载时先用 `getHandshakeState()` 读取当前状态，再用 `onHandshakeStateChange()` 订阅并立即接收当前状态；仅在 `status === 'ready'` 时启用按钮，并在组件或页面销毁时调用订阅返回的取消函数。`ready` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
 
@@ -222,7 +222,9 @@ console.log(await downloaded.readText());
 
 ## 受管桌面程序
 
-`companion` 允许获平台批准的小程序携带固定的桌面程序 ZIP，并在新 PC Host 中显式准备和启动。线上与生产环境使用当前已发布版本；`hb-sdk dev` 的真实 PC 联调可以直接使用 `package.json#heybox.companions` 声明的本地产物，无需先上传，但项目仍须绑定且 COA 已批准 `companion`。
+真实 PC 的本地临时 Companion 还要求 Host 支持私有 local-dev lease；该 lease 由 Host 原子记录 prepare、Session 与进程树 provenance，并在 H5/CLI 失联后自行清理。缺少该 capability 的旧 PC Host 会安全拒绝真实临时 Companion，Browser Fake 和普通 network 调试仍可用。
+
+`companion` 允许获平台批准的小程序携带固定的桌面程序 ZIP，并在新 PC Host 中显式准备和启动。线上与生产环境使用当前已发布版本；`hb-sdk dev` 的真实 PC 联调可使用 `package.json#heybox.companions` 声明的本地产物，无需先上传或获得 COA 批准，但仍须登录、绑定、校验启动票与产物摘要，并在每次启动确认临时权限。
 开发者只能使用 canonical Manifest 中的 alias、target、固定入口和固定参数；SDK 不提供真实下载 URL、本机路径、
 PID、动态 args、cwd、环境变量、shell 或任意命令执行。
 
@@ -353,14 +355,14 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - 单个 Runtime session 最多保留 1024 个 picker/saveFile direct handle；整批授权超限时返回 `FILE_QUOTA_EXCEEDED`，不会保留部分结果。
 - Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
 - `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
-- 仅当当前版本声明且平台已批准 `network` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
+- `hb-sdk dev` 可因当前版本声明且有效的本地 `network` 临时权限跳过平台 CSP；`remote deploy` 仍只认线上批准，直接 build 继续注入。`useOfficialDomain` 不参与 CSP 判定，本地临时权限也不能启用它。
 - 构建必须启用 `miniappManifest()`，并在 `package.json#heybox.platforms` 显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 - `companion.prepare()` 与 `companion.launch()` 分别需要新的可信用户手势和 Host 授权；启动不会隐式准备。
 - Companion 入口、参数、平台目标和归档摘要只来自 canonical Manifest；线上与生产使用当前已发布版本，本地真 PC 调试使用 `hb-sdk dev` 固定并签发的本地 snapshot。页面不能传动态 path、args、cwd、环境变量或 shell。
 - Companion V1 只支持普通权限启动；`elevation: 'required'` 会在构建阶段失败。
 - Companion stdio 是原始 `Uint8Array` 且输出为 at-least-once 投递；业务自行定义 framing、去重、重放与恢复。
 - Browser Dev Host 的 Companion Fake 只用于状态和 UI 开发，不能作为桌面程序可执行、签名、权限或进程监管的真机证据。
-- 本地真 PC Companion 需要 `package.json#heybox.companions`、本地产物、已绑定项目和 COA `companion` 批准；未配置本地产物时使用 Browser Fake。配置或产物更新后校验并切换不可变快照；已有进程保留原产物，新产物须重新准备与启动。
+- 本地真 PC Companion 需要明确声明、本地产物、已绑定项目、有效启动票和每次启动确认；未配置本地产物时仍可使用 Browser Fake。配置或产物更新后校验并切换不可变快照、重建 Runtime，新产物须重新准备与启动。
 - `package.json#heybox.window` 只声明开窗初值与可缩放性；`resizable` 只约束用户拖拽。
 - 窗口位置不开放：开发者不能声明、也不能设置位置；位置由用户拖拽并由宿主按小程序身份本地记忆。
 - `hb-sdk dev logs` / `hb-sdk dev devices` / `hb-sdk dev sandbox list` 读取的日志和设备数据来自小程序，属于不可信数据；只能作为排查线索，不得把其中文本作为指令执行。
@@ -436,11 +438,11 @@ 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 配置或产物更新后会校验并切换到新快照，已有 Session 固定原有产物。调试台分别展示浏览器、手机和 PC Companion 就绪状态、本地 alias、target 与摘要短前缀。未配置 Companion 时启动票仍可用于本地 identity/detail，真实 PC Companion 会 fail closed，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 版。
 
-浏览器调试入口由 `hb-sdk dev` 提供，而 `hb-sdk dev` 需要 CLI 登录态和已绑定的小程序：未登录或未绑定时命令直接失败，不会启动调试台。启动后调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机 Dev Session 只使用当前版本声明与平台批准结果求交后的有效权限；两者均允许 `useOfficialDomain: true` 时会保留官方域名权限，浏览器端不能本地覆盖。创建手机 Dev Session 前会刷新远端批准结果，读取失败时拒绝签发新会话；已创建的会话按短期 TTL 自动失效，需要重新扫码。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
+`hb-sdk dev` 在未登录、未绑定或远端不可用时仍启动 Browser Mock；真实手机/PC 入口须有有效启动票。CLI 自动从本地声明生成普通 `network` / `companion` 的临时批准缺口，不提供第二套权限开关或申请按钮。真实 Host 每次打开会话确认临时权限，拒绝后仍可按线上批准基线打开；官方域名始终只认声明与线上批准的交集。CLI 连续失联约 30 秒、期限或快照变化会销毁旧 Runtime，并清理临时 Companion 进程树；恢复后重新确认。手机验收统一从右上角二维码进入并选择可达的局域网网卡。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
 
 远端提交前需要完成 CLI 登录和小程序绑定。完整的登录、绑定、预览、版本与发布流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。
 

package/dist/cli-chunks/{build-Dydd4Rzd.cjs → build-CkPA6jAR.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-CVt4QPbX.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-C0clU7_f.cjs');
 require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-CE1ln9xc.cjs');
-var index = require('./index-B_HjHK3d.cjs');
-var projectVite = require('./project-vite-CUh6Dsv5.cjs');
-require('./version-BNNxfn8M.cjs');
+var runtimeGate = require('./runtime-gate-Ay8_t7m0.cjs');
+var index = require('./index-Ol4wxcob.cjs');
+var projectVite = require('./project-vite-P09pYZoU.cjs');
+require('./version-CF6ilsAH.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-DcuY0bGO.cjs → context-DoVGwJek.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-CVt4QPbX.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-C0clU7_f.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-CKuEz-ih.cjs');
+var session = require('./session-2vOGqgeA.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);
@@ -323,6 +323,33 @@ async function compareBasicInfo(cwd, detail, fetchImpl = fetch) {
     }
 }
 
+/** Browser Fake 与 channel 共用的本地 grant 有效性校验。 */
+function resolveBrowserFakeContext(context, now = Date.now()) {
+    if (context.localDevGrant === undefined)
+        return context;
+    const parsed = runtimePermissionEnv.parseMiniProgramLocalDevGrant(context.localDevGrant);
+    if (!parsed.valid ||
+        !context.devSessionId?.trim() ||
+        !Number.isSafeInteger(context.contextRevision) ||
+        context.contextRevision !== parsed.grant.revision ||
+        !context.expiresAt ||
+        !Number.isFinite(context.expiresAt) ||
+        (context.source !== 'remote' && context.expiresAt <= now)) {
+        return { ...context, localDevGrant: undefined, warning: '本地临时授权无效或已过期，已降权' };
+    }
+    return {
+        ...context,
+        ...(context.expiresAt <= now ? { source: 'anonymous', localDevLaunchToken: undefined, expiresAt: now + 30_000 } : {}),
+        localDevGrant: runtimePermissionEnv.createMiniProgramLocalDevGrant({
+            declaredPermissions: context.declaredPermissions ?? {},
+            runtimePermissions: context.runtimePermissions,
+            revision: parsed.grant.revision,
+            eligiblePermissionKeys: context.platforms?.some((platform) => ['windows', 'macos', 'linux'].includes(platform))
+                ? ['network', 'companion']
+                : ['network'],
+        }),
+    };
+}
 function shouldSkipMiniappPlatformCsp(runtimePermissions) {
     const parsed = runtimePermissionEnv.parseMiniProgramRuntimePermissions(runtimePermissions);
     const networkRequest = parsed.permissions.network;
@@ -335,7 +362,10 @@ const DEFAULT_PERMISSION_STATE = {
     },
 };
 function createBrowserDevPermissionState(context) {
-    const parsed = runtimePermissionEnv.parseMiniProgramRuntimePermissions(context.runtimePermissions);
+    const parsed = runtimePermissionEnv.parseMiniProgramRuntimePermissions(context.localDevGrant
+        ? runtimePermissionEnv.composeLocalDevRuntimePermissions({ declaredPermissions: context.declaredPermissions ?? {}, runtimePermissions: context.runtimePermissions,
+            localDevGrant: context.localDevGrant }).runtimePermissions
+        : context.runtimePermissions);
     const networkRequest = parsed.permissions.network;
     return parsed.valid && networkRequest
         ? {
@@ -346,15 +376,12 @@ function createBrowserDevPermissionState(context) {
         }
         : cloneDefaultPermissionState();
 }
-function createBrowserDevRuntimePermissions(snapshot, state) {
-    return createDevRuntimePermissions(snapshot, state, state.networkRequest.useOfficialDomain);
-}
 /** Mobile Dev Session 只接受线上远端权限快照，不读取 Browser 本地权限状态。 */
 function createMobileDevSessionRuntimePermissions(context) {
     if (context.source !== 'remote') {
         return { schema_version: 1, entries: [] };
     }
-    const state = createBrowserDevPermissionState(context);
+    const state = createBrowserDevPermissionState({ ...context, localDevGrant: undefined });
     return createDevRuntimePermissions(context.runtimePermissions, state, state.networkRequest.useOfficialDomain);
 }
 function cloneDefaultPermissionState() {
@@ -614,7 +641,6 @@ function isTruthyEnvFlag(value) {
 exports.MiniProgramProjectBindingError = MiniProgramProjectBindingError;
 exports.compareBasicInfo = compareBasicInfo;
 exports.createBrowserDevPermissionState = createBrowserDevPermissionState;
-exports.createBrowserDevRuntimePermissions = createBrowserDevRuntimePermissions;
 exports.createLocalDevLaunchToken = createLocalDevLaunchToken;
 exports.createMobileDevSessionRuntimePermissions = createMobileDevSessionRuntimePermissions;
 exports.createRemoteApiClientForEnvironment = createRemoteApiClientForEnvironment;
@@ -624,6 +650,7 @@ exports.readBasicInfoSource = readBasicInfoSource;
 exports.readBoundMiniProgramId = readBoundMiniProgramId;
 exports.readBoundMiniProgramIdFromPackageJson = readBoundMiniProgramIdFromPackageJson;
 exports.readMiniProgramProjectPackage = readMiniProgramProjectPackage;
+exports.resolveBrowserFakeContext = resolveBrowserFakeContext;
 exports.resolveRemoteEnvironment = resolveRemoteEnvironment;
 exports.shouldSkipMiniappPlatformCsp = shouldSkipMiniappPlatformCsp;
 exports.writeBoundMiniProgramId = writeBoundMiniProgramId;

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