@heybox/hb-sdk 0.8.1-alpha.9 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,98 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。内部集成、实现策略和审查证据不在此维护。
 
+## 0.8.1 - 2026-09-18
+
+> 摘要：新增受管桌面程序、窗口尺寸与游戏绑定声明，开放移动端受控文件与流式下载，新增多设备开发日志与平台解析合同，并收敛网络凭据与调试权限边界。
+> 影响级别：必须操作
+> 开发者动作：升级 `@heybox/hb-sdk` 至 `0.8.1`；将平台声明迁移到 `package.json#heybox.platforms` 并使用无参 `miniappManifest()`；移除 `withCredentials`；按需补充 `package.json#heybox.window`、`package.json#heybox.companions`、`package.json#heybox.bindAppIds`。
+> 兼容范围：业务 API 保持兼容；`network.request()` 仍受支持，但其 `withCredentials` 配置已被移除（传入会被忽略且不报错）；本次唯一会阻断构建的变更是[平台声明迁移](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)——未声明平台的版本 `hb-sdk build` 与 `hb-sdk remote deploy` 会失败，且从 `0.9.0` 起缺失声明不再按移动端兜底。
+
+### 必须操作
+
+- 平台声明迁移到 [package.json#heybox.platforms](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，Vite 配置中使用无参 `miniappManifest()`；旧版带 `companions` 参数的写法已移除，桌面程序改由 [package.json#heybox.companions](https://docs.xiaoheihe.cn/hb_sdk/guide/companion) 声明。
+- `network.request` 不再支持 `withCredentials`：传入会被忽略且不报错，请从代码中移除；请求凭据由客户端按目标域名决定，应用可显式提供 `Cookie` 或 `Authorization`。
+
+### 新增能力
+
+- 窗口尺寸声明 [package.json#heybox.window](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size)：`defaultWidth`、`defaultHeight`、`minWidth`、`minHeight`、`resizable`，构建时写入 Manifest；窗口位置不对开发者开放。
+- 游戏绑定 [package.json#heybox.bindAppIds](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)：每个版本最多声明 20 个游戏 appid，部署前校验游戏可用，`hb-sdk remote info` 只读展示本地与线上绑定差异。
+- 受管桌面程序 [`companion`](https://docs.xiaoheihe.cn/hb_sdk/guide/companion)：显式准备、启动和控制随审核版本发布的桌面辅助程序，支持会话输出、退出通知与只读附件。
+- 移动端（Android/iOS `1.3.396+`）开放[受控文件空间与流式下载](https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox)：单文件或目录选择，以及带进度、可取消的公网流式下载。
+- 环境信息 `environment.getInfo()` 与 `environment.getInfoSync()`。
+- 手机真机调试会话[权限](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)按项目声明与平台批准结果逐项求交；创建会话前会刷新远端批准结果。
+- `hb-sdk dev` 调试台可在运营审核完成前预览候选版本的[桌面程序](https://docs.xiaoheihe.cn/hb_sdk/guide/companion)产物，也可在审核通过后调试正式产物；未发布的预览产物以独立来源标识区分。
+- [平台解析合同](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/resolveMiniappManifestPlatforms.html)：`@heybox/hb-sdk/miniapp-publish` 新增 `resolveMiniappManifestPlatforms()`，按项目声明的平台与 hb-sdk `0.9.0` 硬切口径解析支持平台；未声明且低于 `0.9.0` 时按 Android/iOS/OHOS 兼容，`0.9.0` 起未声明直接失败，声明非法（空数组、未知值、重复值、类型错误）抛错。调用方应复用它，不要自行比较版本或补默认值。
+- `hb-sdk dev` 新增[多设备日志](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)能力：`hb-sdk dev logs` 查询设备日志并支持 `--follow` 输出 NDJSON，`hb-sdk dev devices` 列出已连接设备，`hb-sdk dev sandbox list` 查看小程序沙箱目录。
+
+### 行为调整
+
+- `network.request()` 仍受支持，但不再支持 `withCredentials` 配置（传入会被忽略且不报错）；`Origin`、`Referer`、`User-Agent` 由客户端统一接管，路由与逐跳请求头不能由小程序设置。
+- [浏览器调试台](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)按当前 SDK 版本校验握手，使用旧版本 SDK 的页面会被拒绝启动。
+- 调试台[桌面端入口](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)只在项目声明了桌面平台时展示；手机扫码调试不受影响。
+- 受管桌面程序的[归档总大小上限](https://docs.xiaoheihe.cn/hb_sdk/guide/companion)为 500 MiB，超限时构建与部署直接失败。
+- [`hb-sdk doctor`](https://docs.xiaoheihe.cn/hb_sdk/guide/cli) 现在校验随包 [Agent Skill](https://docs.xiaoheihe.cn/hb_sdk/guide/agent-skill) 的内容完整性，并同时探测项目级与全局 `.agents/skills`；Skill 缺失、版本不匹配或内容被手工修改时返回非零退出码。
+- Host/Runtime 集成：PC [页面通道合同](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size)升级到 `1.7.0`（`1.6.0 → 1.7.0` 增量），新增窗口通道的 getGeometry 请求与 geometryChanged 上报；只有用户拖拽来源才允许写入本地窗口记忆，detail 页面与工坊插件须成对发布与回滚。
+
+### 问题修复
+
+- 修复调试台页脚版本号显示、`hb-sdk remote info` 权限快照误判，以及旧版桌面宿主能力判定等问题。
+
+### 文档与工具
+
+- 补充窗口尺寸、游戏绑定、受管桌面程序、移动端文件与下载的使用说明和能力边界；调试台按平台展示浏览器、手机与桌面程序的就绪状态。
+
+## 0.8.1-alpha.17
+
+- 修正文档与随包 Agent Skill 中过时或自相矛盾的内容：`miniappManifest()` 调用示例、桌面程序归档 500 MiB 上限、移动端文件与下载的支持范围、多选语义与 `files.saveFile()` 的平台差异、`bindAppIds` 的取值边界，以及手机调试会话的权限批准语义。
+- 兼容性记录补齐受管桌面程序（`companion`）的公开接口；此后新增根级公开接口若未登记，校验会直接失败。
+- `hb-sdk doctor` 现在校验随包 Agent Skill 的内容完整性，并覆盖 `.agents/skills` 安装路径；Skill 缺失、版本不匹配或内容被修改时返回非零退出码。
+
+## 0.8.1-alpha.16
+
+- 新增 `resolveMiniappManifestPlatforms(sdkVersion, manifest)`：按 `manifest.platforms` 与 hb-sdk `0.9.0` 硬切口径解析小程序支持的平台；缺少声明且低于 `0.9.0`（含缺失 sdkVersion）时按 Android / iOS / OHOS 移动端兼容，显式声明非法（空数组、未知值、重复值、类型错误）时直接抛错。
+- 该能力从 `@heybox/hb-sdk/miniapp-publish` 导出，开放平台网页与其它调用方复用它做上传前校验，不再各自实现硬切比较或缺省逻辑。
+
+## 0.8.1-alpha.15
+
+- 支持在 `package.json#heybox.bindAppIds` 中声明当前版本关联的小黑盒 PC 游戏 appid；构建产物写入规范化后的 Manifest 顶层 `bindAppIds`，最多 20 项。
+- `hb-sdk build` 保持离线校验；`hb-sdk remote deploy` 会在上传前校验游戏是否存在且可用，并在正式提审时由服务端再次校验。缺失或空数组表示清空绑定，`--from-version` 继承源版本快照。
+- `hb-sdk remote info` 只读展示本地、线上、新增和移除绑定；绑定不是 Runtime 权限，修改仍只能更新项目配置并重新发布版本。
+
+## 0.8.1-alpha.14
+
+- 新增 `package.json#heybox.window` 开发者声明：`defaultWidth` / `defaultHeight` / `minWidth` / `minHeight` / `resizable`，构建时写入 `dist/manifest.json`，所有平台都会写入，由各宿主自行消费。
+- 声明严格校验：空对象、未知字段、`width` / `height` 写法、非正整数、超过 `16384`、`min` 未与对应默认值配对或 `min > default` 全部构建期失败；`x` / `y` 显式报错，**位置不开放**。
+- `resizable` 只约束用户手动拖拽；用户拖拽位置不受该字段限制，窗口位置始终不对开发者开放。
+- `hb-sdk build` 与 `hb-sdk remote deploy` 校验 `dist/manifest.json.window` 与 `package.json#heybox.window` 一致，不一致时要求重新构建。
+- Host/Runtime 集成维护者：页面通道合同升级到 `1.6.0`，新增 `window.getGeometry` 请求与 `window.geometryChanged` 上报，只有用户拖拽来源才允许写入本地记忆。detail 页面与工坊插件须成对发布和回滚。
+
+## 0.8.1-alpha.13
+
+- 审核前预览现在可以准备和启动当前候选版本声明的 Companion；旧版 PC Host 会返回 `COMPANION_PREVIEW_UNSUPPORTED`，需升级客户端后重试。
+- `CompanionInfo.source` 新增 `preview`，用于在可信授权界面区分尚未发布的预览产物。
+
+## 0.8.1-alpha.12
+
+- 摘要：Android/iOS 移动端在 Native Host contract 下新增受控文件与流式下载能力，并修复 Files/Download 的释放、配额与访问边界。
+- 影响级别：常规
+- 开发者动作：将 SDK family 升级到 `0.8.1-alpha.12`；Android/iOS 客户端需升级到 `1.3.396`，能力按 `system.describe` 协商结果逐项启用。
+- 兼容范围：官方 `network.request` 继续由 Host 按目标域名决定凭据；下载与第三方 Native 请求不携带产品凭据，`withCredentials` 仍不被支持。
+- 新增能力
+  - Android/iOS 支持 `files.sandbox.file()`、`files.sandbox.directory()`、`files.pickFiles()` 与 `files.pickDirectory()`；`files.saveFile()` 仅 iOS 开放，Android 精确 SAF 文件保持只读。
+  - Mobile 支持带进度和取消的 `network.download()`，由 Native 网络直接写入文件目标。
+- 问题修复
+  - 新增 Native Host contract、payload 与 `system.describe` 协商；缺失 handler、握手超时或 operation 不完整时逐项 fail closed。
+  - 修复沙箱根路径、下载配额、写入释放、重定向与内网地址限制、取消终态等边界问题。
+
+## 0.8.1-alpha.11
+
+- `hb-sdk dev` 调试台右上角的桌面端入口只在项目声明了桌面平台时展示；`package.json#heybox.platforms` 未包含 `windows`、`macos` 或 `linux` 的小程序不再显示该入口，手机扫码调试不受影响。
+
+## 0.8.1-alpha.10
+
+- `hb-sdk remote deploy` 现在将 Companion 归档总大小限制为 500 MiB；超限项目需先缩减桌面辅助应用产物再重新部署。
+
 ## 0.8.1-alpha.9
 
 - `hb-sdk dev` 浏览器调试台（Browser Dev Host）现在按当前 SDK 实际版本校验握手；开发者需升级 `@heybox/hb-sdk` 到 0.8.1-alpha.9 或更高版本后再进行本地调试，旧版本 SDK 页面会被拒绝启动。
@@ -14,7 +106,7 @@
 
 ## 0.8.1-alpha.7
 
-- `network.request` 已标记为废弃，但仍可调用，目前没有替代接口。请移除 `withCredentials`；旧版 SDK 的 wire 字段由 Runtime 兼容忽略。Mobile 对官方 HTTPS 默认端口目标自动携带 Native Cookie，第三方不自动携带。需要第三方会话时可显式提供应用 `Cookie` 或 `Authorization`；Web Host 受浏览器 Fetch 限制，不支持显式 `Cookie`。`Origin`、`Referer`、`User-Agent` 由 Host 管理，路由/分帧/逐跳请求头不能由小程序设置。
+- `network.request` 仍受支持，目前没有替代接口；`withCredentials` 配置已移除，传入会被忽略；旧版 SDK 的 wire 字段由 Runtime 兼容忽略。Mobile 对官方 HTTPS 默认端口目标自动携带 Native Cookie，第三方不自动携带。需要第三方会话时可显式提供应用 `Cookie` 或 `Authorization`；Web Host 受浏览器 Fetch 限制，不支持显式 `Cookie`。`Origin`、`Referer`、`User-Agent` 由 Host 管理，路由/分帧/逐跳请求头不能由小程序设置。
 
 ## 0.8.1-alpha.6
 

package/README.md

@@ -106,6 +106,19 @@ async function revokeAuthorizationFromUserAction() {
 }
 ```
 
+需要让已发布版本出现在新 PC 的游戏工作区时，在同一个 `heybox` 对象中按需声明精确的小黑盒 PC 游戏 appid：
+
+```json
+{
+  "heybox": {
+    "platforms": ["windows", "macos"],
+    "bindAppIds": ["730", "3513350"]
+  }
+}
+```
+
+`bindAppIds` 只接受规范十进制字符串（形如 `/^[1-9]\d*$/`，拒绝前导零、空串与非数字），每项必须是正 int32（最大 `2147483647`），数组内不允许重复，最多 20 项，并按数值升序写入 Manifest。它不是权限，构建不联网；游戏真实性在远端预检和提审时校验。字段缺失或 `[]` 都表示清空绑定，`remote deploy --from-version` 则继承源版本快照。PC 展示仍受 `platforms` 过滤。
+
 再启用构建插件：
 
 ```ts
@@ -138,6 +151,29 @@ console.log(info.sdk.version);
 
 环境信息无需权限，只用于界面适配、兼容降级、埋点和诊断，不能作为鉴权、权限控制或风控依据。完整字段和 Browser Mock 行为见[环境信息](https://docs.xiaoheihe.cn/hb_sdk/guide/environment)。
 
+## 窗口尺寸
+
+新 PC 工坊小程序支持在 `package.json#heybox.window` 声明开窗默认尺寸与可缩放性：
+
+```json
+{
+  "heybox": {
+    "platforms": ["android", "ios", "ohos", "windows", "macos"],
+    "window": {
+      "defaultWidth": 480,
+      "defaultHeight": 900,
+      "minWidth": 360,
+      "minHeight": 600,
+      "resizable": true
+    }
+  }
+}
+```
+
+`window` 整体可选，字段为 `defaultWidth` / `defaultHeight` / `minWidth` / `minHeight` / `resizable`；`{}`、未知字段、`width` / `height` 写法、非正整数、超过 `16384`、`min` 未与对应默认值配对或 `min > default` 都会在构建期明确失败。`minWidth` / `minHeight` 必须与 `defaultWidth` / `defaultHeight` 同时声明。
+
+`resizable` 只约束**用户手动拖拽**；**位置不开放**：开发者不能声明或设置窗口位置，位置由用户拖拽产生并由宿主按小程序身份本地记忆。完整语义见[窗口尺寸与可缩放性](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size)。
+
 ## 文件与下载
 
 `files` 提供当前小程序私有 sandbox 和由用户选择授予的外部 File/Directory；
@@ -166,8 +202,10 @@ const downloaded = await hbSDK.network.download({
 console.log(await downloaded.readText());
 ```
 
-新 PC 已开放 `files` sandbox、单文件/目录 picker 与公网 `network.download()`；其它 Host 尚未开放
-对应 primitive 时返回 `METHOD_FORBIDDEN`，旧 Runtime 不认识新 method 时返回 `METHOD_NOT_FOUND`。
+新 PC 已开放 `files` sandbox、单文件/目录 picker 与公网 `network.download()`；Android/iOS `1.3.396+`
+通过独立 Native host contract 提供同样的 Files/Download primitive，并按 `system.describe` 的实际 operation
+集逐项启用。Web 与 Browser Dev Host 等尚未开放对应 primitive 的 Host 返回 `METHOD_FORBIDDEN`，旧 Runtime
+不认识新 method 时返回 `METHOD_NOT_FOUND`。
 新 PC 的下载字节留在插件 Node 并直接原子落盘，不提供 Blob 或内存假实现。
 
 外部 picker 必须从可信用户操作触发。`files.saveFile({ suggestedName })` 返回精确 File 授权，
@@ -205,6 +243,8 @@ at-least-once 语义投递，业务协议必须能按 sequence 去重并处理
 
 V1 仅支持普通权限启动；Manifest 的 `elevation` 只能省略或设为 `none`，`required` 会在构建时明确失败。
 管理员权限启动不属于当前版本交付范围。
+`dist/companions/` 下全部归档的**总大小**上限为 500 MiB（`500 × 1024 × 1024` bytes），针对归档总量而非单个文件；
+超限时 `hb-sdk build` 与 `hb-sdk remote deploy` 都会失败并要求先缩减归档。
 `displayName` 最多 120 个 Unicode code point；args 最多 64 项，单项最多 1024 UTF-8 bytes、总计最多
 16384 UTF-8 bytes，并拒绝 NUL、CR 和 LF。
 
@@ -258,14 +298,14 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - `auth.login()`、`user.getInfo()` 和 `user.getSteamGameList()` 的可用性不由 `network` 决定；它们分别要求 `userInfo` 或 `steamLibrary`，并继续遵循各自的用户授权和数据规则。
 - `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
-- 现有业务网络请求仍使用 `network.request()`；该 API 已标记废弃，但目前没有替代调用入口，不要依赖浏览器原生网络出口。
+- 现有业务网络请求仍使用 `network.request()`；该 API 仍受支持，但目前没有替代调用入口，不要依赖浏览器原生网络出口。自 `0.8.1-alpha.7` 起 `withCredentials` 配置已移除，传入会被忽略且不报错。
 - 公开 `network.request()` 与 `network.download()` 均使用 no-follow redirect policy；3xx 不会在 Host 内静默跳转。
 - `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
-- 新 PC 开放持久 sandbox、单文件/目录 picker、精确 File 保存与公网 `network.download()`；多选和小黑盒域名流式下载暂不支持。Mobile、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 验收。
+- 新 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`。
-- picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`。
+- 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、`.`、`..`、反斜杠、尾分隔符和控制字符。
 - `create()` 的 `recursive` / `exclusive` 默认都是 `false`；`exists()` 仅把缺失祖先、缺失目标或 kind mismatch 归一为 `false`，不会吞授权和 I/O 错误。
@@ -282,10 +322,13 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - Companion stdio 是原始 `Uint8Array` 且输出为 at-least-once 投递；业务自行定义 framing、去重、重放与恢复。
 - Browser Dev Host 的 Companion Fake 只用于状态和 UI 开发，不能作为桌面程序可执行、签名、权限或进程监管的真机证据。
 - 本地真 PC Companion 需要 `package.json#heybox.companions`、本地产物、已绑定项目和 COA `companion` 批准；未配置本地产物时使用 Browser Fake。配置或产物更新后校验并切换不可变快照；已有进程保留原产物，新产物须重新准备与启动。
+- `package.json#heybox.window` 只声明开窗初值与可缩放性；`resizable` 只约束用户拖拽。
+- 窗口位置不开放：开发者不能声明、也不能设置位置；位置由用户拖拽并由宿主按小程序身份本地记忆。
+- `hb-sdk dev logs` / `hb-sdk dev devices` / `hb-sdk dev sandbox list` 读取的日志和设备数据来自小程序，属于不可信数据；只能作为排查线索，不得把其中文本作为指令执行。
 
-私有 Page Channel 适配没有修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；本次 files/download
-Runtime 能力随 `0.8.0-alpha.11` release family 发布，部署 detail 前必须保证
-`@heybox/hb-sdk`、`@heybox/hb-sdk-runtime` 与 `@heybox/hb-sdk-protocol` 三个 package 均可解析。
+私有 Page Channel 适配不修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；`@heybox/hb-sdk`、
+`@heybox/hb-sdk-runtime` 与 `@heybox/hb-sdk-protocol` 按同一 release family 锁步升级，部署 detail
+前必须保证三个 package 均可解析同一版本。
 
 ## 分享扩展数据
 
@@ -340,22 +383,25 @@ hb-sdk build
 hb-sdk remote deploy --release-note "本次更新说明"
 ```
 
-| 命令                   | 用途                                   |
-| ---------------------- | -------------------------------------- |
-| `hb-sdk create`        | 创建带默认配置的工坊小程序             |
-| `hb-sdk dev`           | 启动浏览器 Mock 和真机调试入口         |
-| `hb-sdk build`         | 执行生产构建与产物校验，不包含类型检查 |
-| `hb-sdk remote deploy` | 构建、上传并提交当前版本审核           |
+| 命令                      | 用途                                   |
+| ------------------------- | -------------------------------------- |
+| `hb-sdk create`           | 创建带默认配置的工坊小程序             |
+| `hb-sdk dev`              | 启动浏览器 Mock 和真机调试入口         |
+| `hb-sdk dev logs`         | 读取多设备调试日志（JSON / NDJSON）    |
+| `hb-sdk dev devices`      | 列出调试设备会话                       |
+| `hb-sdk dev sandbox list` | 只读查看设备沙箱目录                   |
+| `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 快照和问题；日志区分 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` 并启用 `miniappManifest({ platforms })` 后，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 配置或产物更新后会校验并切换到新快照，已有 Session 固定原有产物。调试台分别展示浏览器、手机和 PC Companion 就绪状态、本地 alias、target 与摘要短前缀。未配置 Companion 时启动票仍可用于本地 identity/detail，真实 PC Companion 会 fail closed，Browser Fake 可继续用于未上传状态联调。
 
-右上角的桌面图标与二维码按钮使用相同样式。点击桌面图标后选择小黑盒正式版或 Debug 版，选择会立即请求客户端打开当前本地页面并在本地记忆，不需要二次确认。桌面端只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择或手工 URL；手机二维码继续独立选择局域网地址。入口仅在项目已绑定且本地调试启动票有效时可用，统一 URI 只携带 `mini_program_id` 和 `mini_url`，启动票继续由 detail 从同源 `launch.json` 发现并交给后端验证。浏览器无法确认客户端是否真正打开，因此调试台只记录“已请求打开”，不会自动切换正式版或 Debug 版。
+右上角的桌面图标与二维码按钮使用相同样式。桌面图标只在该项目于 `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 版。
 
-浏览器调试入口不要求 CLI 登录或项目绑定；需要账号或远端配置的能力会按当前可用上下文返回结果或明确失败。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机 Dev Session 只使用当前版本声明与平台批准结果求交后的有效权限；两者均允许 `useOfficialDomain: true` 时会保留官方域名权限，浏览器端不能本地覆盖。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
+浏览器调试入口由 `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) 维护。
 
 远端提交前需要完成 CLI 登录和小程序绑定。完整的登录、绑定、预览、版本与发布流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。
 

package/dist/cli-chunks/{build-D8eh0bxZ.cjs → build-DPe1Ycjd.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-g_2W-HqP.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-C2S34ldj.cjs');
 require('node:crypto');
 require('node:zlib');
 var runtimeGate = require('./runtime-gate-BWb8QIcX.cjs');
-var index = require('./index-B2eLzOSD.cjs');
-var projectVite = require('./project-vite-C-r7_UvY.cjs');
-require('./version-Dox07wdq.cjs');
+var index = require('./index-CKIyipP9.cjs');
+var projectVite = require('./project-vite-Bd0WzAqQ.cjs');
+require('./version-0qwlEyZC.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');
@@ -23,6 +23,9 @@ require('buffer');
 require('util');
 require('node:url');
 
+function areStringArraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 async function runBuildCommand(_options = {}, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
@@ -31,6 +34,8 @@ async function runBuildCommand(_options = {}, runtime = {}) {
     const mode = env.HB_SDK_ENV?.trim() || undefined;
     const skipPlatformCsp = runtimePermissionEnv.shouldSkipMiniappPlatformCspFromEnv(env);
     const declaredPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
+    const declaredWindow = runtimePermissionEnv.readMiniappWindowFromPackageJson(projectRoot);
+    const declaredBindAppIds = runtimePermissionEnv.readMiniappBindAppIdsFromPackageJson(projectRoot);
     runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
     await fs.rm(distDir, { force: true, recursive: true });
     try {
@@ -49,7 +54,7 @@ async function runBuildCommand(_options = {}, runtime = {}) {
                     write: true,
                 },
             }), { successText: 'Vite 构建完成' });
-            const result = await validateBuildOutput(projectRoot, logger, declaredPlatforms);
+            const result = await validateBuildOutput(projectRoot, logger, declaredPlatforms, declaredWindow, declaredBindAppIds);
             logger.success(`构建完成: dist/ | manifest version ${result.version} | sdkVersion ${result.sdkVersion} | 待上传文件 ${result.fileCount} 个 | ${formatSize(result.totalBytes)}`);
             return result;
         }, env);
@@ -78,7 +83,7 @@ function createFixedBuildOutputPlugin(projectRoot) {
         },
     };
 }
-async function validateBuildOutput(projectRoot, logger, declaredPlatforms) {
+async function validateBuildOutput(projectRoot, logger, declaredPlatforms, declaredWindow, declaredBindAppIds) {
     const distDir = path.join(projectRoot, 'dist');
     const entryHtmlPath = path.join(distDir, 'index.html');
     const manifestPath = path.join(distDir, 'manifest.json');
@@ -96,10 +101,18 @@ async function validateBuildOutput(projectRoot, logger, declaredPlatforms) {
     if (hadBom) {
         logger.warn('dist/manifest.json 包含 BOM，已自动剥离');
     }
-    const { platforms, sdkVersion, version, permissions } = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
+    const validated = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
+    const { platforms, sdkVersion, version, permissions, window } = validated;
+    const bindAppIds = validated.bindAppIds ?? [];
     if (!runtimePermissionEnv.areMiniappPlatformsEqual(platforms, declaredPlatforms)) {
         throw new Error('dist/manifest.json.platforms 与 package.json#heybox.platforms 不一致，请重新 build');
     }
+    if (!runtimePermissionEnv.areMiniappWindowsEqual(window, declaredWindow)) {
+        throw new Error('dist/manifest.json.window 与 package.json#heybox.window 不一致，请重新 build');
+    }
+    if (!areStringArraysEqual(bindAppIds, declaredBindAppIds)) {
+        throw new Error('dist/manifest.json.bindAppIds 与 package.json#heybox.bindAppIds 不一致，请重新 build');
+    }
     const allFiles = await walkDistFiles(distDir);
     const uploadFiles = allFiles.filter((file) => runtimePermissionEnv.shouldUploadDistFile(file.relativePath));
     const sizeError = runtimePermissionEnv.validateMiniappUploadSizeBudgets(uploadFiles);
@@ -108,6 +121,7 @@ async function validateBuildOutput(projectRoot, logger, declaredPlatforms) {
     }
     return {
         distDir,
+        bindAppIds,
         fileCount: uploadFiles.length,
         sdkVersion,
         platforms,

package/dist/cli-chunks/{context-JfGWhXSD.cjs → context-BSUhAv3Z.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-g_2W-HqP.cjs');
-var session = require('./session-CaNwlovY.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-C2S34ldj.cjs');
+var session = require('./session-zXVkHuhY.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');

package/dist/cli-chunks/{create-BiqK-4fa.cjs → create-CaiKrGnb.cjs}

@@ -5,9 +5,10 @@ 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-B2eLzOSD.cjs');
+var index = require('./index-CKIyipP9.cjs');
 require('node:module');
 require('os');
+require('node:crypto');
 require('readline');
 require('tty');
 require('assert');

package/dist/cli-chunks/{dev-u27Q6a-K.cjs → dev-BG1o8Q-0.cjs}

@@ -8,17 +8,17 @@ var net = require('node:net');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
 var node_module = require('node:module');
-var context = require('./context-JfGWhXSD.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-g_2W-HqP.cjs');
+var context = require('./context-BSUhAv3Z.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-C2S34ldj.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-B2eLzOSD.cjs');
+var index = require('./index-CKIyipP9.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CaNwlovY.cjs');
+var session = require('./session-zXVkHuhY.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-C-r7_UvY.cjs');
-var version = require('./version-Dox07wdq.cjs');
+var projectVite = require('./project-vite-Bd0WzAqQ.cjs');
+var version = require('./version-0qwlEyZC.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1950,8 +1950,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-u27Q6a-K.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-u27Q6a-K.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-BG1o8Q-0.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-BG1o8Q-0.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'),
@@ -1982,8 +1982,10 @@ async function startBrowserDevHostServer(options) {
         lanAddresses: options.lanAddresses ?? [],
         loginAvailable: options.loginService !== undefined,
         miniProgram: options.miniProgram,
+        miniProgramSupportsDesktop: options.miniProgramSupportsDesktop,
         mobileLaunchRedirect: initialMobileLaunchRedirect,
         nativeAppLaunchUnavailableReason: options.nativeAppLaunchUnavailableReason,
+        miniProgramManifestAccessToken: options.miniProgramManifestAccessToken,
         runtimePermissions: options.runtimePermissions,
         devReadiness: options.devReadiness,
     };
@@ -2070,6 +2072,8 @@ async function startBrowserDevHostServer(options) {
             }
             if (next.miniProgram !== undefined)
                 bootstrap.miniProgram = next.miniProgram;
+            if (next.miniProgramSupportsDesktop !== undefined)
+                bootstrap.miniProgramSupportsDesktop = next.miniProgramSupportsDesktop;
             bootstrapJson = serializeBrowserDevHostBootstrap(bootstrap);
         },
         networkUrls: createBrowserDevHostNetworkUrls({
@@ -11045,7 +11049,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-CCDqeyc7.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-BPlpP-O0.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -13928,9 +13932,10 @@ function readHeyboxWebV4BrowserFingerprint() {
     if (typeof document === 'undefined' || typeof navigator === 'undefined') {
         return '';
     }
+    let webgl = null;
     try {
         const canvas = document.createElement('canvas');
-        const webgl = canvas.getContext('webgl');
+        webgl = canvas.getContext('webgl');
         const debugInfo = webgl?.getExtension('WEBGL_debug_renderer_info');
         let renderer = debugInfo ? String(webgl?.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) ?? '') : '';
         if (!renderer) {
@@ -13949,6 +13954,15 @@ function readHeyboxWebV4BrowserFingerprint() {
     catch {
         return `${navigator.userAgent ?? ''}${navigator.platform ?? ''}${navigator.language ?? ''}`;
     }
+    finally {
+        // 签名请求会反复读取种子，及时释放临时上下文，避免耗尽浏览器的 WebGL 配额。
+        try {
+            webgl?.getExtension('WEBGL_lose_context')?.loseContext();
+        }
+        catch {
+            // 浏览器可能已丢失上下文；清理失败不改变本次签名种子或原降级语义。
+        }
+    }
 }
 /**
  * 根据 pathname、时间和 nonce 计算 Web V4 hkey。
@@ -15133,6 +15147,8 @@ const VITE_LOG_LEVEL = 'warn';
 const COMPANION_DEV_MANIFEST_PATH = '/__hb_sdk__/companion/manifest.json';
 const COMPANION_DEV_MANIFEST_MAX_BYTES = 1024 * 1024;
 const COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+// 本地 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';
 async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
@@ -15156,8 +15172,9 @@ async function runDevCommand(options, runtime = {}) {
     };
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
     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');
-    runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
+    const miniProgramPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     const { context: devLaunchContext, miniProgram } = await loadDevLaunchContext({
         env: runtime.env,
         fetchImpl,
@@ -15217,7 +15234,7 @@ async function runDevCommand(options, runtime = {}) {
         return true;
     });
     const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
-    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withCompanionArtifactAccessTokenEnv(companionArtifactAccessToken, () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions, launchPlugin)), runtime.env), runtime.env), runtime.env), '已创建 Vite 开发服务器');
+    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withCompanionArtifactAccessTokenEnv(companionArtifactAccessToken, () => withMiniProgramManifestAccessTokenEnv(miniProgramManifestAccessToken, () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions, launchPlugin)), runtime.env), runtime.env), runtime.env), runtime.env), '已创建 Vite 开发服务器');
     await runDevStartupTask(logger, '正在启动 Vite 开发服务器', () => appServer.listen(appPort), 'Vite 开发服务器已启动');
     const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
@@ -15241,9 +15258,12 @@ async function runDevCommand(options, runtime = {}) {
             getPort: getPortImpl,
             defaultLanAddressId: lanAddresses[0]?.id,
             lanAddresses,
+            miniProgramManifestAccessToken,
             lookupHostname: runtime.lookupHostname,
             loginService: runtime.loginService,
             miniProgram,
+            // 只在项目声明了桌面平台时向调试台暴露「在桌面端打开」入口。
+            miniProgramSupportsDesktop: runtimePermissionEnv.hasMiniappDesktopPlatform(miniProgramPlatforms),
             cliAuth: runtime.cliAuth ?? createBrowserDevHostCliAuth({ env: runtime.env, fetchImpl }),
             onMobileDevSessionCreated: ({ devContextUrl, miniUrlOrigin }) => {
                 mobileDevContextUrlsByOrigin.set(miniUrlOrigin, devContextUrl);
@@ -15588,6 +15608,19 @@ async function withCompanionArtifactAccessTokenEnv(token, action, env = process.
             env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV] = previous;
     }
 }
+async function withMiniProgramManifestAccessTokenEnv(token, action, env = process.env) {
+    const previous = env[MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV];
+    env[MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV] = token;
+    try {
+        return await action();
+    }
+    finally {
+        if (previous === undefined)
+            delete env[MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV];
+        else
+            env[MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV] = previous;
+    }
+}
 function installShutdownHandlers(closers, processLike) {
     const shutdown = async () => {
         await closeAll(closers);