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

package/skill/SKILL.md

@@ -51,7 +51,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 10. When authorization UI is required, call `auth.login()` from a trusted user action. Missing gesture returns `USER_GESTURE_REQUIRED`; cancelling, rejecting, or closing returns `AUTHORIZATION_CANCELLED` and does not confirm or change authorization. An already-authorized `auth.login()` request may return a new code silently.
 11. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
 12. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the mini-program share link. `share.showShareMenu()` always uses the platform `common_share` landing page and does not accept a custom `url`. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
-13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Mobile, Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
+13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Android/iOS `1.3.396+` additionally require the Host to advertise the corresponding Native operations through `system.describe`; missing handlers, negotiation timeout, or partial operation sets fail closed per capability. Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
 14. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
 15. Use `companion.prepare()` and `companion.launch()` only from separate trusted user actions. Launch does not prepare implicitly. Treat stdio as raw `Uint8Array` with at-least-once output delivery, and implement business framing and sequence de-duplication explicitly.
 16. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.

package/skill/references/api-root.md

@@ -27,7 +27,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.1-alpha.11`
+- Version at generation time: `0.8.1-alpha.13`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -457,13 +457,14 @@ try {
 | Host             | `files.sandbox` | 外部 picker | `network.download()` |
 | ---------------- | --------------- | ----------- | -------------------- |
 | 新 PC            | 支持            | 支持        | 支持                 |
-| Mobile           | 不支持          | 不支持      | 不支持               |
+| Mobile           | 支持            | 支持        | 支持                 |
 | Web              | 不支持          | 不支持      | 不支持               |
 | Browser Dev Host | 不支持          | 不支持      | 不支持               |
 
 当前 Runtime 认识但 Host 未实现时返回 `METHOD_FORBIDDEN`；旧 Runtime 收到新 method 时返回
-`METHOD_NOT_FOUND`。新 PC V1 注入真实文件与流式下载 primitive；其他当前 Host 未实现时仍不
-提供 throwing stub、Blob 或内存假下载。
+`METHOD_NOT_FOUND`。新 PC 注入真实文件与流式下载 primitive；Android/iOS `1.3.396+` 还需在
+启动时通过 `system.describe` 宣告对应 Native operations。缺失 handler、协商超时或 operation
+不完整时对应能力保持关闭，且不提供 throwing stub、Blob 或内存假下载。
 
 ### 路径与创建
 
@@ -643,7 +644,7 @@ try {
 - `USER_GESTURE_REQUIRED` 表示潜在授权 UI 缺少可信用户手势，应让用户点击按钮后重试。
 - `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
 - `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
-- `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Mobile、Web 和 Browser Dev Host 都会得到该错误。
+- `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Web、Browser Dev Host 和未实现该能力的旧版 Host 会得到该错误；Android/iOS `1.3.396+` 需先经 `system.describe` 协商到对应 operation 集。
 - `ENVIRONMENT_NOT_READY` 表示在 SDK 完成握手前调用了 `environment.getInfoSync()`；一般改用会自动等待的 `environment.getInfo()`。
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
@@ -926,6 +927,7 @@ Fake 不选择、不下载、不解压、不启动本机程序，也不经过操
 - `COMPANION_DESCRIPTOR_UNAVAILABLE`：授权或描述符暂时不可用，可在有界重试策略下重试。
 - `COMPANION_ELEVATION_DENIED`：为未来管理员权限启动保留的兼容错误码；V1 构建不接受 `elevation: 'required'`。
 - `METHOD_FORBIDDEN` / `COMPANION_UNSUPPORTED`：当前 Host 或平台未实现，不要循环重试或用任意执行替代。
+- `COMPANION_PREVIEW_UNSUPPORTED`：当前 PC Host 不支持审核前预览 Companion，需要升级客户端后重试。
 
 完整类型与方法见 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/)。
 

package/skill/references/examples.md

@@ -193,8 +193,8 @@ export default defineConfig({
 - Do not call unsupported storage delete/clear/info operations.
 - Do not pass raw internal share/network protocol fields from mini-program code.
 - Do not send `multipart/form-data` (or handcrafted multipart bodies) through `network.request`; use form-urlencoded string body or a dedicated upload capability.
-- Do not pass string paths, browser File System Access handles, Blob targets, Range/resume fields, or upload bodies to `network.download`; use SDK-created File/Directory handles on new PC.
-- Do not treat Mobile, Web, Browser Dev Host, or legacy PC as evidence for files/download support. Only new PC currently implements the retained contract; other Hosts return `METHOD_FORBIDDEN` and provide no memory fallback.
+- Do not pass string paths, browser File System Access handles, Blob targets, Range/resume fields, or upload bodies to `network.download`; use SDK-created File/Directory handles on new PC, or on Android/iOS `1.3.396+` after the Native contract is negotiated.
+- Do not treat Web, Browser Dev Host, or legacy PC as evidence for files/download support. New PC implements the retained contract; Android/iOS `1.3.396+` additionally require matching Native operations from `system.describe`. Missing handlers, negotiation timeout, and partial operation sets fail closed per capability; other Hosts return `METHOD_FORBIDDEN` and provide no memory fallback.
 - Do not pass executable paths, dynamic args, cwd, environment variables, shell commands, URLs, hashes, or native process identifiers to `companion`. Only the reviewed Manifest may define launch inputs.
 - Treat `companion.prepare()` and `companion.launch()` as separate trusted-user-gesture and Host-authorization operations. Launch never prepares implicitly.
 - Companion stdio is raw `Uint8Array` with at-least-once output delivery. Business protocols own framing, sequence de-duplication, replay, and reconnection.

package/skill/references/recipes.md

@@ -138,13 +138,14 @@ try {
 | Host             | `files.sandbox` | 外部 picker | `network.download()` |
 | ---------------- | --------------- | ----------- | -------------------- |
 | 新 PC            | 支持            | 支持        | 支持                 |
-| Mobile           | 不支持          | 不支持      | 不支持               |
+| Mobile           | 支持            | 支持        | 支持                 |
 | Web              | 不支持          | 不支持      | 不支持               |
 | Browser Dev Host | 不支持          | 不支持      | 不支持               |
 
 当前 Runtime 认识但 Host 未实现时返回 `METHOD_FORBIDDEN`；旧 Runtime 收到新 method 时返回
-`METHOD_NOT_FOUND`。新 PC V1 注入真实文件与流式下载 primitive；其他当前 Host 未实现时仍不
-提供 throwing stub、Blob 或内存假下载。
+`METHOD_NOT_FOUND`。新 PC 注入真实文件与流式下载 primitive；Android/iOS `1.3.396+` 还需在
+启动时通过 `system.describe` 宣告对应 Native operations。缺失 handler、协商超时或 operation
+不完整时对应能力保持关闭，且不提供 throwing stub、Blob 或内存假下载。
 
 ### 路径与创建
 
@@ -416,7 +417,7 @@ try {
 - `USER_GESTURE_REQUIRED` 表示潜在授权 UI 缺少可信用户手势，应让用户点击按钮后重试。
 - `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
 - `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
-- `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Mobile、Web 和 Browser Dev Host 都会得到该错误。
+- `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Web、Browser Dev Host 和未实现该能力的旧版 Host 会得到该错误；Android/iOS `1.3.396+` 需先经 `system.describe` 协商到对应 operation 集。
 - `ENVIRONMENT_NOT_READY` 表示在 SDK 完成握手前调用了 `environment.getInfoSync()`；一般改用会自动等待的 `environment.getInfo()`。
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
@@ -619,6 +620,7 @@ Fake 不选择、不下载、不解压、不启动本机程序，也不经过操
 - `COMPANION_DESCRIPTOR_UNAVAILABLE`：授权或描述符暂时不可用，可在有界重试策略下重试。
 - `COMPANION_ELEVATION_DENIED`：为未来管理员权限启动保留的兼容错误码；V1 构建不接受 `elevation: 'required'`。
 - `METHOD_FORBIDDEN` / `COMPANION_UNSUPPORTED`：当前 Host 或平台未实现，不要循环重试或用任意执行替代。
+- `COMPANION_PREVIEW_UNSUPPORTED`：当前 PC Host 不支持审核前预览 Companion，需要升级客户端后重试。
 
 完整类型与方法见 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/)。
 

package/skill/references/safety-boundaries.md

@@ -22,8 +22,8 @@
 - 公开 `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。多选和小黑盒域名流式下载暂不支持；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`。
 - `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.1-alpha.11+skill.ee9c3d1cb222",
+  "skillVersion": "0.8.1-alpha.13+skill.3784ce3da843",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.11",
-    "compatibility": "0.8.1-alpha.11"
+    "version": "0.8.1-alpha.13",
+    "compatibility": "0.8.1-alpha.13"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.11",
+    "version": "0.8.1-alpha.13",
     "path": "skill"
   },
-  "integrity": "sha256-ee9c3d1cb2220befd45d58f637c9a11caa7c520cdcc31ead6a48b074831fb6cb"
+  "integrity": "sha256-3784ce3da8431dd675160a5c2a66e19d08f5210d3765a2cddcadee6e3dfa2a38"
 }

package/types/modules/files/types.d.ts

@@ -35,8 +35,8 @@ export interface PathRoot {
      * @hbPlatform ohos
      * @hbPlatform windows
      * @hbPlatform macos
-     * @hbClient android none
-     * @hbClient ios none
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
      * @hbClient ohos none
      * @hbClient windows none
      * @hbClient macos none
@@ -53,8 +53,8 @@ export interface PathRoot {
      * @hbPlatform ohos
      * @hbPlatform windows
      * @hbPlatform macos
-     * @hbClient android none
-     * @hbClient ios none
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
      * @hbClient ohos none
      * @hbClient windows none
      * @hbClient macos none
@@ -107,14 +107,15 @@ export interface FilesModule {
      *
      * @param options - 访问模式、扩展名筛选与多选设置。
      * @returns 用户选择的文件代理。
+     * @remarks Android `1.3.396` 的精确 SAF 文件仅支持只读选择；请求 `readwrite` 会返回 `FILE_ACCESS_DENIED`。
      * @since 0.8.0-alpha.2
      * @hbPlatform android
      * @hbPlatform ios
      * @hbPlatform ohos
      * @hbPlatform windows
      * @hbPlatform macos
-     * @hbClient android none
-     * @hbClient ios none
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
      * @hbClient ohos none
      * @hbClient windows none
      * @hbClient macos none
@@ -131,8 +132,8 @@ export interface FilesModule {
      * @hbPlatform ohos
      * @hbPlatform windows
      * @hbPlatform macos
-     * @hbClient android none
-     * @hbClient ios none
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
      * @hbClient ohos none
      * @hbClient windows none
      * @hbClient macos none
@@ -144,13 +145,11 @@ export interface FilesModule {
      * @param options - 建议文件名。
      * @returns 具备读写权限的目标文件代理。
      * @since 0.8.0-alpha.2
-     * @hbPlatform android
      * @hbPlatform ios
      * @hbPlatform ohos
      * @hbPlatform windows
      * @hbPlatform macos
-     * @hbClient android none
-     * @hbClient ios none
+     * @hbClient ios numeric-dot \>= 1.3.396
      * @hbClient ohos none
      * @hbClient windows none
      * @hbClient macos none

package/types/modules/network/index.d.ts

@@ -135,8 +135,8 @@ export interface MiniProgramNetworkModule {
      * @hbPlatform ohos
      * @hbPlatform windows
      * @hbPlatform macos
-     * @hbClient android none
-     * @hbClient ios none
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
      * @hbClient ohos none
      * @hbClient windows none
      * @hbClient macos none