@heybox/hb-sdk 0.9.3-alpha.4 → 0.9.3-alpha.6

package/dist/devtools/browser-dev-host/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-D2OzmHdY.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-E0Vk3jdW.js">
+    <script type="module" crossorigin src="/assets/index-Br7UpHGt.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-CFl6m8k-.js">
     <link rel="stylesheet" crossorigin href="/assets/index-7Cq8iNcD.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -7299,7 +7299,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.4';
+    : '0.9.3-alpha.6';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/index.esm.js

@@ -7295,7 +7295,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.4';
+    : '0.9.3-alpha.6';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/vite.cjs.js

@@ -10304,7 +10304,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.4';
+    : '0.9.3-alpha.6';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/dist/vite.esm.js

@@ -10301,7 +10301,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.4';
+    : '0.9.3-alpha.6';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/docs/runtime-host-migration.md

@@ -113,7 +113,7 @@ Node 负责 CLI-owned stable context endpoint、短跳转 registry 和 Launch Re
 
 ## Breaking 行为
 
-- `network.request` 继续拒绝平台保留 endpoint，并校验 Header；Host、分帧、逐跳及平台认证头不能由页面设置。`withCredentials` 仅在旧 wire 边界忽略。Mobile 完整官方请求只在 `system.describe.features.officialRequestV1 === true` 时启用：`sendRequestV2` 携带显式扩展标记与已编码正文，复用原有签名栈，透传安全应用 Header、JSON/表单和 HTTP 状态，禁止重定向及覆盖 Cookie。Native WebView 绑定与 Flutter Dart 绑定各自声明自身执行器的能力，不能直接继承底层库声明。旧 Host 保持 GET/表单 POST 兼容，不支持的形态提前拒绝；第三方仍走 RAW。Private credential realm 继续显式映射，凭据不进入 iframe。发布顺序允许 transport/客户端先行，缺少任一能力的旧 Host 保持兼容；宿主 H5 启用扩展前必须确保配套 transport 已发布。
+- `network.request` 继续拒绝平台保留 endpoint，并校验 Header；Host、分帧、逐跳及平台认证头不能由页面设置。`withCredentials` 仅在旧 wire 边界忽略。Mobile 官方域名的无自定义应用 Header GET 与可兼容表单 POST 使用既有 Native 签名通道，JSON、自定义应用 Header 及其它方法沿用 RAW。RAW 不补齐 Native 默认公参与签名；第一方主体、官方域名权限和 Cookie 会话均不能绕过此限制。当前没有同时组合这两种能力的扩展标记或调用方开关，需要时应由服务端提供兼容鉴权。第三方仍走 RAW 且不自动带平台凭据。Private credential realm 继续显式映射，凭据不进入 iframe。
 - UI、device、navigation、storage、`user.revokeAuthorization` 等 void method 统一 resolve `undefined`，不再透传 Host sentinel；排行榜删除保持 `{ deleted: boolean }`。
 - iframe DOM/network helper、旧平台 facade 和独立 mock runtime 不再提供兼容入口。按本页新 Host Port 图迁移，不要在应用层重新实现 bridge。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.3-alpha.4",
+  "version": "0.9.3-alpha.6",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -76,7 +76,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.3-alpha.4"
+    "@heybox/hb-sdk-protocol": "0.9.3-alpha.6"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -128,13 +128,13 @@
     "vitest": "^3.2.4",
     "@ai-desktop/view-contract": "file:../hb-sdk-protocol/vendor/view-contract-2.2.2-6ac49bbf6410.tgz",
     "rollup-plugin-dts": "6.4.0",
+    "@heybox/hb-sdk-runtime": "~0.9.3-alpha.6",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-api": "~1.28.16",
-    "@heybox/hb-sdk-runtime": "~0.9.3-alpha.4",
-    "@heybox/runtime-policy": "~0.2.1",
     "@heybox/runtime": "~0.2.1",
-    "@heybox/runtime-transport-fetch": "~0.2.1",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0"
+    "@heybox/runtime-policy": "~0.2.1",
+    "@heybox/hb-api": "~1.28.17",
+    "@heybox/runtime-transport-fetch": "~0.2.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/SKILL.md

@@ -17,6 +17,12 @@ Before implementing screenshot flows or upgrading the SDK, use the canonical doc
 
 Before upgrading, verify both the page layout and the captured image. Do not only update the dependency or invocation without explaining screenshot behavior changes. Read exact version cutoffs, dimensions, parameters, and Host support from the canonical documentation fetched for this task; never substitute an older installed Skill snapshot.
 
+## 展示 API 迁移：升级前必查
+
+实现 `viewport.setDisplay` 调用流程或升级 SDK 前，先通过 canonical 文档索引读取该方法的 Reference 与迁移预告。主动向开发者说明已公布的返回值迁移安排，包括目标版本、是否已生效，以及需要准备的兼容和错误处理。
+
+核对项目已安装的 SDK 与公告中的版本门槛。当前和计划契约均以本次读取的 canonical 文档为准，不提前套用未来契约，不把不支持结果当作设置成功，也不依赖旧 Skill 快照。建议升级前验证支持和不支持两种 Host。
+
 ## Canonical Documentation
 
 The only maintained hb-sdk guidance source is:

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.3-alpha.4+skill.4d7b063940c3",
+  "skillVersion": "0.9.3-alpha.6+skill.d0d502673711",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.3-alpha.4",
-    "compatibility": "0.9.3-alpha.4"
+    "version": "0.9.3-alpha.6",
+    "compatibility": "0.9.3-alpha.6"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.3-alpha.4",
+    "version": "0.9.3-alpha.6",
     "path": "skill"
   },
-  "integrity": "sha256-4d7b063940c341502cf34c481b656be96ac27f1a252055b2b1af445c6392264c"
+  "integrity": "sha256-d0d502673711f5d077ee62e657749125788e396d5203894b7077dfe866fd2990"
 }

package/types/index.d.ts

@@ -1638,12 +1638,16 @@ interface MiniProgramNetworkRequestConfig {
      * `new URLSearchParams(values).toString()` 并设置
      * `application/x-www-form-urlencoded`。
      *
-     * 支持官方请求扩展的 Mobile Host 可在保留官方鉴权的同时发送应用 Header、JSON 与表单，
-     * 支持标准 HTTP 方法；GET/HEAD 不携带正文，Cookie 仍由宿主管理。Host 自动协商能力，
-     * 页面无需传入额外开关。旧 Mobile Host 仅支持无应用 Header/正文的 GET 和表单 POST；
-     * 标量表单对象及无重复字段的合法 UTF-8 表单字符串可兼容，form Content-Type 由 Host
-     * 消化为编码声明。旧 Host 无法表达的请求返回 `REQUEST_UNSUPPORTED`，不降为无签名请求。
-     * 该兼容限制不改变第三方 URL 的 Header 与 JSON 请求能力。
+     * **在移动端访问官方域名时，JSON 请求体或自定义请求头不会自动附加客户端签名。**
+     * 依赖客户端签名的接口应使用服务端支持的 GET 或兼容表单 POST，并避免自定义请求头；
+     * 标量表单对象及无重复字段的合法 UTF-8 表单字符串可兼容。仅设置表单 Content-Type
+     * 用于声明编码，不影响这类表单请求的兼容性。
+     *
+     * 当前 API 不支持在同一请求中同时使用 JSON/自定义请求头和自动附加的客户端签名，
+     * 也没有强制启用签名的配置项。接口同时要求两者时，应先与服务端约定兼容的请求格式
+     * 或鉴权方式，并在目标客户端验收。官方域名访问权限、Cookie 可用、SDK 版本或请求
+     * 成功均不能作为已签名的依据。历史客户端仍可能以 `REQUEST_UNSUPPORTED` 拒绝。
+     * GET/HEAD 不携带正文。此限制不影响第三方 URL 的自定义请求头与 JSON 请求能力。
      *
      * 不支持 `FormData`、`Blob`、File/Directory 代理、`ArrayBuffer`、TypedArray、`DataView`、
      * `SharedArrayBuffer` 或它们的嵌套值。`multipart/form-data` 与手写 multipart body 均不可用；
@@ -1654,6 +1658,9 @@ interface MiniProgramNetworkRequestConfig {
      * 请求头；规则见 {@link MiniProgramNetworkHeaders}。调用方显式提供的普通 `Cookie` /
      * `Authorization` 可作为应用 Header 交给 Host，但 SDK 不提供平台 Cookie/token，且不得在
      * 小程序中持有或发送平台凭据、服务端应用密钥等敏感信息。
+     * 在移动端访问官方域名时，自定义请求头不能与自动附加的客户端签名同时使用。
+     * 依赖客户端签名的接口应避免自定义请求头。仅声明表单 Content-Type 的兼容规则
+     * 见 {@link MiniProgramNetworkRequestConfig.data}。
      */
     headers?: MiniProgramNetworkHeaders;
     /**
@@ -1877,6 +1884,8 @@ interface MiniProgramNetworkModule {
     /**
      * 发起网络请求。
      *
+     * **注意：在移动端访问官方域名时，JSON 请求体或自定义请求头不会自动附加客户端签名。**
+     *
      * @typeParam T - 调用方期望的响应 data 类型；只影响 TypeScript，不做运行时 schema 校验。
      * @param config - URL、方法、查询、body、Header、Host timeout 与 SDK 状态校验配置，详见
      * {@link MiniProgramNetworkRequestConfig}。
@@ -1893,6 +1902,12 @@ interface MiniProgramNetworkModule {
      * 其他握手、bridge 或 Host 错误保留对应 SDK 错误码。
      *
      * @remarks
+     * 移动端访问官方域名时，当前 API 不支持同时使用 JSON/自定义请求头和自动附加的
+     * 客户端签名，也没有强制启用签名的配置项。依赖客户端签名的接口应使用服务端支持的
+     * GET 或兼容表单 POST，并避免自定义请求头。接口同时要求两者时，应先与服务端约定
+     * 兼容的请求格式或鉴权方式。访问权限已获批、Cookie 可用或请求成功均不代表已签名，
+     * 具体编码与兼容规则见 {@link MiniProgramNetworkRequestConfig.data}。
+     *
      * 该 API 需要在 `package.json#heybox.permissions` 声明并启用 `network`，且取得平台批准；
      * 不需要 `filesystem` 或可信用户手势。`useOfficialDomain` 只有开发者声明与平台批准都为
      * `true` 时生效，并且不会绕过 HTTPS、敏感路径、Header、body、timeout 或响应策略。
@@ -3670,6 +3685,13 @@ interface MiniProgramViewportModule {
     /**
      * 设置当前小程序的窗口方向和全屏状态。
      *
+     * SDK `1.0.0` 计划将本方法调整为 `Promise<void>`：设置完成时正常返回，不支持时抛出明确错误；
+     * 切换失败、超时或取消仍抛出对应错误。当前仍返回 `{ supported: boolean }`，现有行为保持不变。
+     *
+     * 请提前补齐 `try/catch`，过渡期保留 `supported: false` 判断，并先检查返回值是否存在再读取该字段；
+     * 避免直接解构返回值或将未来的空返回值当作失败。仅在确认设置成功后继续依赖该设置的操作。
+     * 不支持时的错误码与适配期限会在 `1.0.0` 正式发布前公告，并提供预发布版本验证。
+     *
      * @param options - 方向与全屏目标，至少提供一个字段；省略的字段保持当前目标值。
      * @returns Host 完成原生方向与胶囊设置、布局稳定后返回 `{ supported: true }`；能力缺失或
      * 请求不受支持时返回 `{ supported: false }`，调用方仍应按实际窗口与安全区布局。

package/types/protocol.d.ts

@@ -1638,12 +1638,16 @@ interface MiniProgramNetworkRequestConfig {
      * `new URLSearchParams(values).toString()` 并设置
      * `application/x-www-form-urlencoded`。
      *
-     * 支持官方请求扩展的 Mobile Host 可在保留官方鉴权的同时发送应用 Header、JSON 与表单，
-     * 支持标准 HTTP 方法；GET/HEAD 不携带正文，Cookie 仍由宿主管理。Host 自动协商能力，
-     * 页面无需传入额外开关。旧 Mobile Host 仅支持无应用 Header/正文的 GET 和表单 POST；
-     * 标量表单对象及无重复字段的合法 UTF-8 表单字符串可兼容，form Content-Type 由 Host
-     * 消化为编码声明。旧 Host 无法表达的请求返回 `REQUEST_UNSUPPORTED`，不降为无签名请求。
-     * 该兼容限制不改变第三方 URL 的 Header 与 JSON 请求能力。
+     * **在移动端访问官方域名时，JSON 请求体或自定义请求头不会自动附加客户端签名。**
+     * 依赖客户端签名的接口应使用服务端支持的 GET 或兼容表单 POST，并避免自定义请求头；
+     * 标量表单对象及无重复字段的合法 UTF-8 表单字符串可兼容。仅设置表单 Content-Type
+     * 用于声明编码，不影响这类表单请求的兼容性。
+     *
+     * 当前 API 不支持在同一请求中同时使用 JSON/自定义请求头和自动附加的客户端签名，
+     * 也没有强制启用签名的配置项。接口同时要求两者时，应先与服务端约定兼容的请求格式
+     * 或鉴权方式，并在目标客户端验收。官方域名访问权限、Cookie 可用、SDK 版本或请求
+     * 成功均不能作为已签名的依据。历史客户端仍可能以 `REQUEST_UNSUPPORTED` 拒绝。
+     * GET/HEAD 不携带正文。此限制不影响第三方 URL 的自定义请求头与 JSON 请求能力。
      *
      * 不支持 `FormData`、`Blob`、File/Directory 代理、`ArrayBuffer`、TypedArray、`DataView`、
      * `SharedArrayBuffer` 或它们的嵌套值。`multipart/form-data` 与手写 multipart body 均不可用；
@@ -1654,6 +1658,9 @@ interface MiniProgramNetworkRequestConfig {
      * 请求头；规则见 {@link MiniProgramNetworkHeaders}。调用方显式提供的普通 `Cookie` /
      * `Authorization` 可作为应用 Header 交给 Host，但 SDK 不提供平台 Cookie/token，且不得在
      * 小程序中持有或发送平台凭据、服务端应用密钥等敏感信息。
+     * 在移动端访问官方域名时，自定义请求头不能与自动附加的客户端签名同时使用。
+     * 依赖客户端签名的接口应避免自定义请求头。仅声明表单 Content-Type 的兼容规则
+     * 见 {@link MiniProgramNetworkRequestConfig.data}。
      */
     headers?: MiniProgramNetworkHeaders;
     /**