@heybox/hb-sdk 0.8.1-alpha.10 → 0.8.1-alpha.12

package/dist/protocol.cjs.js

@@ -331,32 +331,32 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
 ];
 
 function isMiniProgramBridgeMessage(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
-    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString$1(value.nonce)) {
         return false;
     }
     if (value.type === 'handshake') {
-        return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+        return isNonEmptyString$1(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
     }
     if (value.type === 'request') {
-        return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+        return isNonEmptyString$1(value.id) && isNonEmptyString$1(value.method) && value.error === undefined;
     }
     if (value.type === 'response') {
-        return (isNonEmptyString(value.id) &&
-            (value.method === undefined || isNonEmptyString(value.method)) &&
+        return (isNonEmptyString$1(value.id) &&
+            (value.method === undefined || isNonEmptyString$1(value.method)) &&
             (value.error === undefined || isBridgeError(value.error)));
     }
     if (value.type === 'event') {
-        if (!isNonEmptyString(value.method) || value.error !== undefined)
+        if (!isNonEmptyString$1(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString$1(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
-        return value.id === undefined || isNonEmptyString(value.id);
+        return value.id === undefined || isNonEmptyString$1(value.id);
     }
     if (value.type === 'cancel') {
-        return (value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
+        return (value.version === 2 && isNonEmptyString$1(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
     }
     return false;
 }
@@ -369,40 +369,40 @@ function isMiniProgramRelativePath(value) {
     return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
 }
 function isMiniProgramPathRootRef(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.kind === 'sandbox')
         return hasOnlyKeys(value, ['kind']);
-    return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+    return value.kind === 'directory' && isNonEmptyString$1(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
 }
 function isMiniProgramFileRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'file')
+    if (!isRecord$2(value) || value.kind !== 'file')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramDirectoryRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'directory')
+    if (!isRecord$2(value) || value.kind !== 'directory')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramFileRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
 }
 function isMiniProgramDirectoryDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'directory' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramDirectoryRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
@@ -414,7 +414,7 @@ function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
 function isMiniProgramFileStat(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
         isNonNegativeSafeInteger(value.size) &&
         (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
@@ -422,7 +422,7 @@ function isMiniProgramFileStat(value) {
         hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
 }
 function isMiniProgramDownloadProgressPayload(value) {
-    if (!isRecord$1(value) ||
+    if (!isRecord$2(value) ||
         !isNonNegativeSafeInteger(value.loaded) ||
         typeof value.lengthComputable !== 'boolean' ||
         !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
@@ -433,7 +433,7 @@ function isMiniProgramDownloadProgressPayload(value) {
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 function isMiniProgramCompanionPrepareProgress(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.phase === 'downloading') {
         return (isNonNegativeSafeInteger(value.loaded) &&
@@ -451,10 +451,10 @@ function isMiniProgramOperationProgressPayload(value) {
     return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
 }
 function isSDKHandshakePayload(value) {
-    return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+    return isRecord$2(value) && isNonEmptyString$1(value.href) && typeof value.userAgent === 'string' && isNonEmptyString$1(value.sdkVersion);
 }
 function isBridgeError(value) {
-    return isRecord$1(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+    return isRecord$2(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
 }
 function isFileMode(value) {
     return value === 'read' || value === 'readwrite';
@@ -465,14 +465,14 @@ function isNonNegativeSafeInteger(value) {
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
-function isNonEmptyString(value) {
+function isNonEmptyString$1(value) {
     return typeof value === 'string' && value.length > 0;
 }
 function hasOnlyKeys(value, allowedKeys) {
     const allowed = new Set(allowedKeys);
     return Object.keys(value).every((key) => allowed.has(key));
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 

package/dist/protocol.esm.js

@@ -329,32 +329,32 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
 ];
 
 function isMiniProgramBridgeMessage(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
-    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString$1(value.nonce)) {
         return false;
     }
     if (value.type === 'handshake') {
-        return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+        return isNonEmptyString$1(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
     }
     if (value.type === 'request') {
-        return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+        return isNonEmptyString$1(value.id) && isNonEmptyString$1(value.method) && value.error === undefined;
     }
     if (value.type === 'response') {
-        return (isNonEmptyString(value.id) &&
-            (value.method === undefined || isNonEmptyString(value.method)) &&
+        return (isNonEmptyString$1(value.id) &&
+            (value.method === undefined || isNonEmptyString$1(value.method)) &&
             (value.error === undefined || isBridgeError(value.error)));
     }
     if (value.type === 'event') {
-        if (!isNonEmptyString(value.method) || value.error !== undefined)
+        if (!isNonEmptyString$1(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString$1(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
-        return value.id === undefined || isNonEmptyString(value.id);
+        return value.id === undefined || isNonEmptyString$1(value.id);
     }
     if (value.type === 'cancel') {
-        return (value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
+        return (value.version === 2 && isNonEmptyString$1(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
     }
     return false;
 }
@@ -367,40 +367,40 @@ function isMiniProgramRelativePath(value) {
     return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
 }
 function isMiniProgramPathRootRef(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.kind === 'sandbox')
         return hasOnlyKeys(value, ['kind']);
-    return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+    return value.kind === 'directory' && isNonEmptyString$1(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
 }
 function isMiniProgramFileRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'file')
+    if (!isRecord$2(value) || value.kind !== 'file')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramDirectoryRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'directory')
+    if (!isRecord$2(value) || value.kind !== 'directory')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramFileRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
 }
 function isMiniProgramDirectoryDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'directory' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramDirectoryRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
@@ -412,7 +412,7 @@ function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
 function isMiniProgramFileStat(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
         isNonNegativeSafeInteger(value.size) &&
         (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
@@ -420,7 +420,7 @@ function isMiniProgramFileStat(value) {
         hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
 }
 function isMiniProgramDownloadProgressPayload(value) {
-    if (!isRecord$1(value) ||
+    if (!isRecord$2(value) ||
         !isNonNegativeSafeInteger(value.loaded) ||
         typeof value.lengthComputable !== 'boolean' ||
         !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
@@ -431,7 +431,7 @@ function isMiniProgramDownloadProgressPayload(value) {
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 function isMiniProgramCompanionPrepareProgress(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.phase === 'downloading') {
         return (isNonNegativeSafeInteger(value.loaded) &&
@@ -449,10 +449,10 @@ function isMiniProgramOperationProgressPayload(value) {
     return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
 }
 function isSDKHandshakePayload(value) {
-    return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+    return isRecord$2(value) && isNonEmptyString$1(value.href) && typeof value.userAgent === 'string' && isNonEmptyString$1(value.sdkVersion);
 }
 function isBridgeError(value) {
-    return isRecord$1(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+    return isRecord$2(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
 }
 function isFileMode(value) {
     return value === 'read' || value === 'readwrite';
@@ -463,14 +463,14 @@ function isNonNegativeSafeInteger(value) {
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
-function isNonEmptyString(value) {
+function isNonEmptyString$1(value) {
     return typeof value === 'string' && value.length > 0;
 }
 function hasOnlyKeys(value, allowedKeys) {
     const allowed = new Set(allowedKeys);
     return Object.keys(value).every((key) => allowed.has(key));
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 

package/dist/vite.cjs.js

@@ -11,7 +11,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.10';
+    : '0.8.1-alpha.12';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/dist/vite.esm.js

@@ -8,7 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.10';
+    : '0.8.1-alpha.12';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.1-alpha.10",
+  "version": "0.8.1-alpha.12",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.1-alpha.10"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.12"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -113,13 +113,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-api": "~1.28.3",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.12",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.10",
-    "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0"
+    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/runtime": "~0.2.0",
+    "@heybox/hb-api": "~1.28.3",
+    "@heybox-domain/heybox-theme": "~0.1.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

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.10`
+- Version at generation time: `0.8.1-alpha.12`
 - 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` 表示网络空闲超时，失败不会改动原目标。

package/skill/references/cli.md

@@ -115,7 +115,7 @@ CLI 会启动页面服务并自动打开 Vue 3 本地调试台。左侧集中放
 
 `hb-sdk dev` 从项目 `package.json` 读取开发者声明，并在远端权限快照可用时读取平台批准结果。只有当前版本声明且平台已批准 `network` 时才跳过平台 CSP；`useOfficialDomain` 不参与该判定。调试台不提供权限或平台批准修改入口；快照缺失或无效时保留平台 CSP。
 
-调试台右上角的桌面图标与手机二维码按钮使用相同样式。点击桌面图标后选择小黑盒正式版或 Debug 版，选择后立即请求客户端打开当前本地小程序，不需要再点一次确认；上次选择的客户端会在本地记忆。桌面调试只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择；手机二维码仍维护独立的局域网选择。项目未绑定或本地调试启动票不可用时，菜单会显示不可用原因。
+调试台右上角的桌面图标与手机二维码按钮使用相同样式。桌面图标只在该项目于 `package.json#heybox.platforms` 声明了桌面平台（`windows`、`macos` 或 `linux`）时展示，未声明桌面平台的项目不显示该入口。点击桌面图标后选择小黑盒正式版或 Debug 版，选择后立即请求客户端打开当前本地小程序，不需要再点一次确认；上次选择的客户端会在本地记忆。桌面调试只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择；手机二维码仍维护独立的局域网选择。项目未绑定或本地调试启动票不可用时，入口保持展示但两个客户端选项置灰不可用。
 
 桌面打开使用 `ai-desktop://v1/extensions/ai-desktop.heybox-user-miniprogram/open`，Debug 客户端使用 `ai-desktop-debug://`。URI 只包含 `mini_program_id` 与 `mini_url`，不包含启动票、权限快照或客户端执行参数；detail 仍从 `mini_url` 同源的 `/__hb_sdk__/launch.json` 读取最新启动事实并由后端验证。浏览器无法取得外部协议的可靠完成回执，所以界面只显示“已请求打开”，不会声明成功，也不会自动 fallback 到另一个客户端。
 

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` 表示网络空闲超时，失败不会改动原目标。

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.10+skill.79d09c3b6cad",
+  "skillVersion": "0.8.1-alpha.12+skill.0ec2760a9aa0",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.10",
-    "compatibility": "0.8.1-alpha.10"
+    "version": "0.8.1-alpha.12",
+    "compatibility": "0.8.1-alpha.12"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.10",
+    "version": "0.8.1-alpha.12",
     "path": "skill"
   },
-  "integrity": "sha256-79d09c3b6cad5fe22962d813b7513e2ef23eda8f6ff5fb9ddc8d6778eb73a81f"
+  "integrity": "sha256-0ec2760a9aa09dc2c2d97237da7d3647bee16dc1c4e69df3216c0be22f9de1d7"
 }

package/types/miniapp-manifest/schema.d.ts

@@ -3,6 +3,15 @@ import type { MiniappCompanionManifestDeclarations } from './companion-types';
 export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
 export declare const MINIAPP_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos", "linux"];
 export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
+/**
+ * 桌面平台子集：从唯一平台词表 `MINIAPP_PLATFORM_VALUES` 派生，`satisfies` 阻止它漂移出词表。
+ * 小程序声明其中任一平台，即视为该项目承诺适配 PC / 桌面端；调试台据此取舍桌面调试入口。
+ *
+ * 注意：子集只表达「声明为桌面」，不保证已有可用的客户端基线——例如 `linux` 目前既没有 `@hbPlatform` 声明，
+ * 也没有 Companion target，仅声明 `linux` 的项目会展示入口但未必能真正打开。
+ */
+export declare const MINIAPP_DESKTOP_PLATFORM_VALUES: readonly ["windows", "macos", "linux"];
+export declare function hasMiniappDesktopPlatform(platforms: readonly MiniappPlatform[] | undefined): boolean;
 export interface MiniappManifest {
     [key: string]: unknown;
     sdkVersion: string;

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