@heybox/hb-sdk 0.9.1-alpha.11 → 0.9.1-alpha.13

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.1-alpha.13
+
+### 问题修复
+
+- 真机调试根据确认后的网络权限使用对应身份流程，授权状态读取失败时明确提示重试。
+- 本地权限刷新遇到临时故障或限流后自动重试，重新打开调试会话时刷新过期权限缓存。
+
+## 0.9.1-alpha.12 - 2026-10-16
+
+### 行为调整
+
+- 新宿主仅对正式 SDK `0.9.1` 及以上启用默认截图水印；较旧版本（含 `0.9.1-alpha.*`）或缺少版本记录的兼容模式静默保留无水印截图。
+- SDK 每次调用 `share.screenshot()` 时输出行为变更提醒，说明水印版本门槛、底部至少预留 57 个逻辑像素及明暗配色；日志输出失败不影响截图。
+
+### 文档与工具
+
+- Agent Skill 强制检查截图升级影响，提醒同步核对页面布局、版本兼容和主题选择。
+
 ## 0.9.1-alpha.11 - 2026-10-16
 
 ### 新增能力

package/README.md

@@ -332,7 +332,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `network`    | 发起经过平台授权的网络请求及受控文件传输  |
 | `companion`  | 准备、启动并控制当前版本审核过的桌面辅助应用    |
 
-`share.screenshot()` 会在截图区域底部添加当前小程序名称的品牌搜索胶囊及灰色「小黑盒工坊小程序」。请在目标区域底部预留至少 57 个逻辑像素的空白背景，避免遮挡重要内容，并保证背景与水印有足够对比度。`watermarkTheme: 'light'` 适合浅色背景（黑色水印），`'dark'` 适合深色背景（白色水印，默认）；不自动跟随系统主题。水印仅在 SDK 截图期间展示，不增加图片尺寸；系统按键截图暂不支持。截图等待不受 SDK 普通请求超时限制；排队和延迟期间会响应会话终止，Mobile Host 从投递原生截图起最多等待 15 秒成图回调。详见 [截图分享布局要求](https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share#截图分享)。
+`share.screenshot()` 每次调用都会在 SDK 侧输出行为变更 warning，提醒升级后的布局与配色要求；日志失败不阻断调用。截图从正式 SDK `0.9.1` 起默认添加水印。新 Runtime 对低于 `0.9.1` 的 SDK（包含 `0.9.1-alpha.*`）或缺少 SDK 版本记录的兼容模式静默保持无水印截图；升级前需同步调整布局。启用水印时，会在截图区域底部添加当前小程序名称的品牌搜索胶囊及灰色「小黑盒工坊小程序」。请在目标区域底部预留至少 57 个逻辑像素的空白背景，避免遮挡重要内容，并保证背景与水印有足够对比度。`watermarkTheme: 'light'` 适合浅色背景（黑色水印），`'dark'` 适合深色背景（白色水印，默认）；不自动跟随系统主题。水印仅在 SDK 截图期间展示，不增加图片尺寸；系统按键截图暂不支持。截图等待不受 SDK 普通请求超时限制；排队和延迟期间会响应会话终止，Mobile Host 从投递原生截图起最多等待 15 秒成图回调。详见 [截图分享布局要求](https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share#截图分享)。
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
@@ -483,7 +483,9 @@ CLI 会复用已验证产物、跳过该 ZIP 的网络上传；Web 文件及发
 
 右上角的桌面图标与二维码按钮使用相同样式。桌面图标只在该项目于 `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` 在未登录、未绑定或远端不可用时仍启动 Browser Mock；真实手机/PC 入口须有有效启动票。CLI 自动从本地声明生成普通 `network` / `companion` 的临时批准缺口，不提供第二套权限开关。调试台顶部的“查看全部权限申请”在新标签页打开当前小程序的权限列表；尚未获批的 Network、Companion 单项提供“去申请”，直接打开对应申请表单。未获取到小程序 ID 时先选择小程序，再进入对应权限；已获批或审核中的权限不重复打开申请表单。真实 Host 每次打开会话确认临时权限，拒绝后仍可按线上批准基线打开；官方域名始终只认声明与线上批准的交集。真机 Dev Session 的公开 `network.request()` 通过开发机的 HTTP 代理转发，因此 HTTPS `localhost` 指向开发机；代理不管理独立租约，不判断黑盒域名或改写应用层凭据。正式版本和 Runtime 私有请求仍走 Host 网络。CLI 连续失联约 30 秒、期限或快照变化会销毁旧 Runtime，并清理临时 Companion 进程树；恢复后重新确认。手机验收统一从右上角二维码进入并选择可达的局域网网卡。完整操作见 [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` 的临时批准缺口，不提供第二套权限开关。调试台顶部的“查看全部权限申请”在新标签页打开当前小程序的权限列表；尚未获批的 Network、Companion 单项提供“去申请”，直接打开对应申请表单。未获取到小程序 ID 时先选择小程序，再进入对应权限；已获批或审核中的权限不重复打开申请表单。真实 Host 每次打开会话确认临时权限，拒绝后仍可按线上批准基线打开；官方域名始终只认声明与线上批准的交集。真机 Dev Session 的公开 `network.request()` 通过开发机的 HTTP 代理转发，因此 HTTPS `localhost` 指向开发机；代理不管理独立租约，不判断黑盒域名或改写应用层凭据。正式版本和 Runtime 私有请求仍走 Host 网络。CLI 连续失联约 30 秒、期限或快照变化会销毁旧 Runtime，并清理临时 Companion 进程树；恢复后重新确认。手机验收统一从右上角二维码进入并选择可达的局域网网卡。开发描述、运行快照与续票边界见[开发会话](./docs/development-session.md)。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
+
+开发上下文按需读取并默认缓存 30 秒；重新打开真机会话时，过期缓存会刷新。权限刷新遇到临时故障或限流会按退避自动重试，恢复前暂停签发新启动票。真机按确认后的有效网络权限选择身份模式；身份上下文读取失败会提示重试，不会静默切换旧身份模式。
 
 远端提交前需要完成 CLI 登录和小程序绑定。完整的登录、绑定、预览、版本与发布流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。
 

package/dist/cli-chunks/{build-CSTdWNu1.cjs → build-BbHZwXU-.cjs}

@@ -1,14 +1,14 @@
 'use strict';
 
-var runtimeGate = require('./runtime-gate-Bh1vm1an.cjs');
+var runtimeGate = require('./runtime-gate-DZsAmCYW.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-DuRchECp.cjs');
-var index = require('./index-CQtu_5c7.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CmEUEBaN.cjs');
+var index = require('./index-D9EWV1_s.cjs');
 require('node:crypto');
 require('node:zlib');
-var projectVite = require('./project-vite-DqbyiCMm.cjs');
+var projectVite = require('./project-vite-ESL8lQxi.cjs');
 require('node:module');
 require('node:url');
 require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
@@ -16,7 +16,7 @@ require('fs');
 require('path');
 require('os');
 require('inspector');
-require('./version-BaMa3UQg.cjs');
+require('./version-BQjpkyst.cjs');
 require('node:async_hooks');
 require('readline');
 require('tty');

package/dist/cli-chunks/{context-Bej2XR0w.cjs → context-DO5i8KuO.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-DuRchECp.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CmEUEBaN.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var index = require('./index-CQtu_5c7.cjs');
+var index = require('./index-D9EWV1_s.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);
@@ -376,13 +376,17 @@ function createBrowserDevPermissionState(context) {
         }
         : cloneDefaultPermissionState();
 }
-/** Mobile Dev Session 只接受线上远端权限快照，不读取 Browser 本地权限状态。 */
+/** Mobile Dev Session 使用本地声明与平台基线，不读取 Browser 模拟权限状态。 */
 function createMobileDevSessionRuntimePermissions(context) {
     if (context.source !== 'remote') {
         return { schema_version: 1, entries: [] };
     }
-    const state = createBrowserDevPermissionState({ ...context, localDevGrant: undefined });
-    return createDevRuntimePermissions(context.runtimePermissions, state, state.networkRequest.useOfficialDomain);
+    // 历史内部调用没有本地声明，沿用旧快照适配；新 CLI 始终显式提供声明（可为空）。
+    if (context.declaredPermissions === undefined) {
+        const state = createBrowserDevPermissionState(context);
+        return createDevRuntimePermissions(context.runtimePermissions, state, state.networkRequest.useOfficialDomain);
+    }
+    return runtimePermissionEnv.composeLocalDevRuntimePermissions({ declaredPermissions: context.declaredPermissions, runtimePermissions: context.runtimePermissions }).runtimePermissions;
 }
 function cloneDefaultPermissionState() {
     return {
@@ -623,6 +627,7 @@ async function createLocalDevLaunchToken(options, runtime = {}) {
     const api = await resolveRemoteApiClient(options, runtime);
     return api.createLocalDevLaunchToken({
         mini_program_id: miniProgramId,
+        ...(options.developmentSnapshot ? { development_snapshot: options.developmentSnapshot } : {}),
         ...(options.companionManifestSha256
             ? { companion_manifest_sha256: options.companionManifestSha256 }
             : {}),

package/dist/cli-chunks/{create-Cz5tqvMR.cjs → create--IVuD5k_.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-CQtu_5c7.cjs');
+var index = require('./index-D9EWV1_s.cjs');
 require('node:module');
 require('readline');
 require('os');