@heybox/hb-sdk 0.7.5-alpha.0 → 0.8.0-alpha.2

package/skill/references/recipes.md

@@ -37,7 +37,7 @@ import hbSDK, { type MiniProgramSDKHandshakeState } from '@heybox/hb-sdk'
 import { computed, onUnmounted, ref } from 'vue'
 
 const handshakeState = ref<MiniProgramSDKHandshakeState>(hbSDK.getHandshakeState())
-const stopHandshakeState = hbSDK.onHandshakeStateChange((state) => {
+const stopHandshakeState = hbSDK.onHandshakeStateChange(state => {
   handshakeState.value = state
 })
 const sdkReady = computed(() => handshakeState.value.status === 'ready')
@@ -93,6 +93,102 @@ async function loginFromUserAction() {
 
 返回值与边界以[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
 
+## 文件与下载
+
+`files.sandbox` 是当前小程序隔离的逻辑根。`file()` / `directory()` 只创建 lazy proxy，不执行
+I/O；第一次真实 I/O 仍由 Runtime 和 Host 校验当前 session、授权、mode、kind 和路径。
+
+```ts
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+
+const exportDirectory = hbSDK.files.sandbox.directory('exports')
+await exportDirectory.create({ recursive: true })
+
+const controller = new AbortController()
+
+try {
+  const file = await hbSDK.network.download({
+    url: 'https://cdn.example.com/report.json',
+    to: exportDirectory,
+    suggestedName: 'report.json',
+    overwrite: true,
+    maxBytes: 8 * 1024 * 1024,
+    signal: controller.signal,
+    onProgress({ loaded, total, lengthComputable }) {
+      console.log(lengthComputable ? `${loaded}/${total}` : loaded)
+    },
+  })
+
+  console.log(await file.readText())
+} catch (error) {
+  if (error instanceof HbMiniProgramSDKError && error.code === 'METHOD_FORBIDDEN') {
+    // 当前 Host 不支持 V1 文件能力。
+    return
+  }
+  throw error
+}
+```
+
+当前平台状态如下：
+
+| Host             | `files.sandbox` | 外部 picker | `network.download()` |
+| ---------------- | --------------- | ----------- | -------------------- |
+| 旧版 PC          | 不支持          | 不支持      | 不支持               |
+| Mobile           | 不支持          | 不支持      | 不支持               |
+| Web              | 不支持          | 不支持      | 不支持               |
+| Browser Dev Host | 不支持          | 不支持      | 不支持               |
+
+当前 Runtime 认识但 Host 未实现时返回 `METHOD_FORBIDDEN`；旧 Runtime 收到新 method 时返回
+`METHOD_NOT_FOUND`。此前曾实现面向旧版小黑盒 PC 的 Host 适配；由于新版 PC 即将启用，该适配
+不再发布。文件/下载 API、协议和 Runtime 体系保持不变，后续直接按照新版 PC Host 架构接入。
+当前任何 Host 都不提供 Blob 或内存假下载。
+
+### 路径与创建
+
+- 逻辑相对路径统一使用 `/`。拒绝空字符串、绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符、NUL 和控制字符。
+- `create()` 的 `recursive` 与 `exclusive` 默认均为 `false`。默认行为是不截断内容的 ensure-exists；`exclusive: true` 在同名实体已存在时失败。
+- `writeText()` / `writeBytes()` 可以在父目录存在时隐式创建目标，但不会自动创建父目录。
+- `exists()` 在祖先/目标缺失或 kind mismatch 时返回 `false`；授权撤销、quota 与 I/O 错误仍抛出。
+- `file.remove()` 与 `directory.remove()` 只删除 sandbox 对象；外部 picker/saveFile 授权调用删除时抛出 `FILE_ACCESS_DENIED`。
+- 非空目录默认不能删除并抛出 `DIRECTORY_NOT_EMPTY`；确认删除整个目录树后显式调用 `directory.remove({ recursive: true })`。
+- `directory.list()` 默认最多返回 1000 项，显式 `limit` 也不能超过 1000；超限抛出 `DIRECTORY_LIST_LIMIT_EXCEEDED`。
+- Host 文件错误只暴露稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
+- `FileStat.size` 是字节数；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
+
+### 外部授权与保存
+
+`pickFiles()`、`pickDirectory()` 和 `saveFile()` 必须直接从按钮点击等可信用户操作调用。picker
+取消会抛 `FILE_PICKER_CANCELLED`，不会返回空数组或 `undefined`。
+
+```ts
+async function saveFromUserAction(text: string) {
+  const file = await hbSDK.files.saveFile({ suggestedName: 'report.json' })
+  await file.writeText(text)
+}
+```
+
+`saveFile()` 打开系统保存对话框并返回精确 File 授权，不会同时创建或保留 Directory
+授权。V1 不接受 `accept`；扩展名过滤只属于 `pickFiles({ accept: ['.json'] })`。外部授权仅在当前
+Runtime session 有效。
+
+`pickFiles()` / `pickDirectory()` 默认返回 `mode: 'read'` 的授权；只有显式传入
+`multiple: true` 时，`pickFiles()` 才允许 Host 返回多个文件。需要修改文件、在所选目录中创建
+文件，或把外部授权用作下载目标时，必须在 picker options 中显式请求 `mode: 'readwrite'`。
+
+单个 Runtime session 最多保留 1024 个 picker/saveFile direct handle；整批选择超过剩余额度时抛出 `FILE_QUOTA_EXCEEDED`，不会保留部分授权。Sandbox 派生项与目录枚举结果使用逻辑引用，不持续占用该额度。
+
+### 下载边界
+
+- 下载固定使用 GET，不接受 method、body、上传或 Range 字段。
+- File target 必须已存在且为 `readwrite`，成功后返回同一个 File proxy；Directory target 必须存在且为 `readwrite`，成功后返回新的子 File proxy。
+- Directory 默认不覆盖同名文件；只有显式 `overwrite: true` 才允许原子替换。
+- Directory target 的子文件名按安全的 `Content-Disposition filename*` / `filename`、`suggestedName`、URL basename、`download.bin` 依次选择。
+- `timeout` 是网络空闲超时，不是整个下载总时长。取消或失败不会改动原目标。
+- `AbortSignal` 只发出取消意图并等待 Host 终态；如果 Host 已先完成原子提交，Promise 仍以成功结果 resolve，否则抛出 `DOWNLOAD_CANCELLED`。
+- 公开 request 与 download 都不跟随重定向；3xx 或 partial representation 会失败。
+- 进度从 `loaded: 0` 开始并单调不减；原子提交后、Promise resolve 前会再发送一次 final progress，因此空文件或 Host 已报告最终值时允许相邻值相同。只有无歧义、identity-encoded 的 `Content-Length` 才使 `lengthComputable=true`；压缩、chunked 或重复长度都视为未知 total，可信长度必须在提交前与实际字节数一致。
+- `onProgress` 在本地同步执行；回调异常不会中断下载。成功时最后一次回调发生在文件提交后、Promise resolve 前。
+
 ## 默认单例
 
 大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
@@ -316,6 +412,10 @@ try {
 - `USER_GESTURE_REQUIRED` 表示潜在授权 UI 缺少可信用户手势，应让用户点击按钮后重试。
 - `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
 - `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
+- `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Mobile、Web 和 Browser Dev Host 都会得到该错误。
+- `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
+- `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
+- `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
 - 超时或运行环境不可用时，允许用户重试或退出当前流程。
 - 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -364,6 +464,10 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 
 授权码在取得后立即交给开发者服务端交换，不要写入页面状态、DOM、日志或持久化存储。UI 只处理服务端会话是否建立成功。
 
+文件与下载仍使用 `HbMiniProgramSDKError`，不会新增第三种错误类。业务根据 `error.code` 处理
+picker 取消、授权撤销、文件缺失、quota、下载状态或取消，不依赖 `message` 文案，也不要记录
+真实路径、内部 handle 或响应凭据头。
+
 ## Login gate recipe
 
 

package/skill/references/safety-boundaries.md

@@ -21,10 +21,21 @@
 - `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- 公开 `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`，文件上传请走专用上传能力。
+- 当前 Host（包括旧版 PC、Mobile、Web 与 Browser Dev Host）均未开放 `files` / `network.download()`；新版 PC 将按同一公开合同重新接入，期间不提供内存或 Blob 假实现。
+- picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`。
+- `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
+- `file()` / `directory()` 只接受以 `/` 分隔的规范相对路径；拒绝绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符和控制字符。
+- `create()` 的 `recursive` / `exclusive` 默认都是 `false`；`exists()` 仅把缺失祖先、缺失目标或 kind mismatch 归一为 `false`，不会吞授权和 I/O 错误。
+- `remove()` 只允许删除 sandbox 对象；外部 picker/saveFile 授权返回 `FILE_ACCESS_DENIED`。非空目录默认返回 `DIRECTORY_NOT_EMPTY`，需显式调用 `remove({ recursive: true })`。
+- `directory.list()` 默认最多返回 1000 项，`limit` 也不能超过 1000；超限返回 `DIRECTORY_LIST_LIMIT_EXCEEDED`。
+- 单个 Runtime session 最多保留 1024 个 picker/saveFile direct handle；整批授权超限时返回 `FILE_QUOTA_EXCEEDED`，不会保留部分结果。
+- Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
+- `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
 - 仅当远端已启用 `network.request` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
-- 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
+- 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
 ## Agent rules
 

package/skill/scripts/sync-references.mjs

@@ -78,6 +78,8 @@ function rewriteBundledProtocolIndexLinks(markdown) {
   return markdown
     .replaceAll('(./root/)', '(api-root.md)')
     .replaceAll('(./protocol/)', '(#public-protocol-entrypoint)')
+    .replaceAll('(./compatibility)', '(https://docs.xiaoheihe.cn/hb_sdk/reference/compatibility)')
+    .replaceAll('](/reference/', '](https://docs.xiaoheihe.cn/hb_sdk/reference/')
     .replaceAll('(./miniapp-publish/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/)')
     .replaceAll('(./vite/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/)')
     .replaceAll('(./runtime/)', '(https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/)')
@@ -381,7 +383,7 @@ files.set(
     ['Update reminders', 'update-reminders'],
   ])}## When to use the CLI
 
-Use the bundled \`hb-sdk\` CLI to create a workshop mini-program, open the local debugging page, test in the Heybox Mac or mobile App, or manage and publish a remote mini-program.
+Use the bundled \`hb-sdk\` CLI to create a workshop mini-program, open the local Browser debugging workbench, test in the Heybox mobile App, or manage and publish a remote mini-program.
 
 \`hb-sdk login\` is for development and publishing commands only. It does not authorize mini-program users and does not change \`auth.login()\`, \`user.getInfo()\`, or \`network.request()\` inside a mini-program.
 
@@ -406,7 +408,9 @@ Agent rules:
 
 ${cliDevSection}
 
-Use \`hb-sdk dev\` to open the local debugging page after CLI login and project binding are complete. Missing login, binding, or remote Dev Context stops before Vite and the debugging services start. The "Mobile App" QR code opens it in the phone App after a LAN interface is selected. The phone and computer must be on the same LAN.
+Use \`hb-sdk dev\` to open the local Vue 3 debugging workbench. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need them fail explicitly. The upper-right QR popover is the only Mobile entry and requires selecting a LAN interface the phone can reach.
+
+The workbench offers iPhone 16 Pro Max (\`440 x 956\`) and Pixel 9 Pro (\`410 x 914\`) presets. Switching presets preserves the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Do not suggest a debugging-page permission editor; it does not exist, and the validated remote permission snapshot remains canonical.
 
 Browser Mock uses the Node \`hb-sdk login\` session to send Host \`heybox-session\` requests. Mini-program code must still call \`auth.login()\`; the debug page only shows an authorization dialog. Never copy pkey, cookies, tokens, or credential-bearing URLs into page JavaScript or logs. Phone debugging continues to use the App login, not the CLI session.
 
@@ -692,6 +696,34 @@ try {
 }`,
 )}
 
+### Sandbox download contract (Host pending)
+
+${fenced(
+  'ts',
+  `import { files, network, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+
+export async function downloadReport() {
+  const directory = files.sandbox.directory('exports');
+  await directory.create({ recursive: true });
+
+  try {
+    return await network.download({
+      url: 'https://cdn.example.com/report.json',
+      to: directory,
+      suggestedName: 'report.json',
+      onProgress: ({ loaded, total, lengthComputable }) => {
+        console.log(lengthComputable ? [loaded, total].join('/') : loaded);
+      },
+    });
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'METHOD_FORBIDDEN') {
+      return undefined;
+    }
+    throw error;
+  }
+}`,
+)}
+
 ### Host/runtime protocol import
 
 ${fenced(
@@ -735,7 +767,7 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest()],
+  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
 });`,
 )}
 
@@ -749,6 +781,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 after a supporting Host is available.
+- Do not treat any current Host, including legacy PC or Browser Dev Host, as evidence for files/download support. They return \`METHOD_FORBIDDEN\` and provide no memory fallback; the new PC Host will integrate the retained contract separately.
 - Do not treat \`hb-sdk login\` as iframe SDK authentication state.
 - Do not create a second mock runtime package when \`hb-sdk dev\` is the supported local mock workflow.
 - Do not import \`@heybox/hb-sdk/vite\` from iframe business code or fetch a deployed \`manifest.json\` directly.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.7.5-alpha.0+skill.00f042a71c63",
+  "skillVersion": "0.8.0-alpha.2+skill.417e5072238c",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.7.5-alpha.0",
-    "compatibility": "0.7.5-alpha.0"
+    "version": "0.8.0-alpha.2",
+    "compatibility": "0.8.0-alpha.2"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-00f042a71c637f5aad3141a72a647fc136c74eec7339e4801634c761ea2b7ce5"
+  "integrity": "sha256-417e5072238c0b2a53836824d60639046935ad28ca337a63d82016421c97127b"
 }

package/types/core/client.d.ts

@@ -25,8 +25,18 @@ export interface MiniProgramRequester {
     /** 向父容器调用指定开放能力。 */
     request<Method extends MiniProgramBridgeMethod>(method: Method, ...args: MiniProgramRequesterArgs<Method>): Promise<MiniProgramCapabilityResult<Method>>;
 }
+/** 长操作使用的本地 observer 与取消配置，不进入 bridge payload。 */
+export interface MiniProgramOperationOptions<TProgress = unknown> {
+    signal?: AbortSignal;
+    onProgress?: (progress: TProgress) => void;
+    createAbortError?: () => unknown;
+}
+/** 支持 request-scoped progress/cancel 的 bridge requester。 */
+export interface MiniProgramOperationRequester extends MiniProgramRequester {
+    requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
+}
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
-export declare class MiniProgramBridgeClient implements MiniProgramRequester {
+export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester {
     private readonly timeout;
     private readonly selfWindow?;
     private readonly targetWindow;
@@ -64,6 +74,9 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
     /** 调用父容器开放能力。 */
     request<Method extends MiniProgramBridgeMethod>(method: Method, ...args: MiniProgramRequesterArgs<Method>): Promise<MiniProgramCapabilityResult<Method>>;
+    /** 发起不使用固定总时长 timer 的长操作。 */
+    requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
+    private performRequest;
     /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
     destroy(): void;
     private ensureStarted;
@@ -73,6 +86,9 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private postCSPViolation;
     private handleEvent;
     private handleResponse;
+    private handleOperationProgress;
+    private sendCancel;
+    private cleanupPending;
     private postMessage;
     private resolveHandshakeOnce;
     private failHandshake;

package/types/core/errors.d.ts

@@ -18,9 +18,9 @@ export declare class HbMiniProgramSDKError extends Error {
 /**
  * 创建 SDK 标准错误。
  *
- * @param code 稳定错误码。
- * @param message 面向开发者的错误说明。
- * @param data 可选调试数据。
+ * @param code - 稳定错误码。
+ * @param message - 面向开发者的错误说明。
+ * @param data - 可选调试数据。
  * @returns 标准化 `HbMiniProgramSDKError` 实例。
  *
  * @remarks
@@ -34,7 +34,7 @@ export declare function createSDKError(code: string, message: string, data?: unk
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
  * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
  *
- * @typeParam T 标准化响应数据的类型。
+ * @typeParam T - 标准化响应数据的类型。
  */
 export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
     /** HTTP 状态码。 */
@@ -48,7 +48,7 @@ export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
     /** 完整标准化响应。 */
     response: MiniProgramNetworkResponse<T>;
     /**
-     * @param response 已完成请求的标准化网络响应。
+     * @param response - 已完成请求的标准化网络响应。
      */
     constructor(response: MiniProgramNetworkResponse<T>);
 }

package/types/core/sdk.d.ts

@@ -4,6 +4,7 @@ import { type MiniProgramCloudModule } from '../modules/cloud';
 import { type MiniProgramShareModule } from '../modules/share';
 import { type MiniProgramStorageModule } from '../modules/storage';
 import { type MiniProgramNetworkModule } from '../modules/network';
+import { type FilesModule } from '../modules/files';
 import { type MiniProgramViewportModule } from '../modules/viewport';
 import { type MiniProgramUserModule } from '../modules/user';
 import { type MiniProgramUiModule } from '../modules/ui';
@@ -37,6 +38,8 @@ export declare class MiniProgramSDK {
     readonly storage: MiniProgramStorageModule;
     /** 网络请求相关开放能力。 */
     readonly network: MiniProgramNetworkModule;
+    /** 受控文件与目录能力。 */
+    readonly files: FilesModule;
     /** UI 交互相关开放能力。 */
     readonly ui: MiniProgramUiModule;
     /** 设备相关开放能力。 */
@@ -53,16 +56,16 @@ export declare class MiniProgramSDK {
     /**
      * 注册小程序生命周期或业务事件。
      *
-     * @param eventName 要监听的事件名。
-     * @param handler 事件处理函数。
+     * @param eventName - 要监听的事件名。
+     * @param handler - 事件处理函数。
      * @returns 事件解绑函数。
      */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /**
      * 移除小程序生命周期或业务事件。
      *
-     * @param eventName 要移除的事件名。
-     * @param handler 对应的事件处理函数。
+     * @param eventName - 要移除的事件名。
+     * @param handler - 对应的事件处理函数。
      */
     off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
     /**
@@ -77,7 +80,7 @@ export declare class MiniProgramSDK {
 /**
  * 创建独立 SDK 实例。
  *
- * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @param options - SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
  * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
  *
  * @remarks

package/types/core/singleton.d.ts

@@ -3,6 +3,7 @@ import type { MiniProgramCloudModule } from '../modules/cloud';
 import type { MiniProgramShareModule } from '../modules/share';
 import type { MiniProgramStorageModule } from '../modules/storage';
 import type { MiniProgramNetworkModule } from '../modules/network';
+import type { FilesModule } from '../modules/files';
 import type { MiniProgramViewportModule } from '../modules/viewport';
 import type { MiniProgramUserModule } from '../modules/user';
 import type { MiniProgramUiModule } from '../modules/ui';
@@ -10,24 +11,74 @@ import type { MiniProgramDeviceModule } from '../modules/device';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-/** 获取默认 SDK 实例的当前握手状态。 */
+/**
+ * 获取默认 SDK 实例的当前握手状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 export declare function getHandshakeState(): MiniProgramSDKHandshakeState;
-/** 订阅默认 SDK 实例的握手状态，并立即接收当前状态。 */
+/**
+ * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName 要监听的事件名。
- * @param handler 事件处理函数。
+ * @param eventName - 要监听的事件名。
+ * @param handler - 事件处理函数。
  * @returns 事件解绑函数。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 export declare function on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName 要移除的事件名。
- * @param handler 对应的事件处理函数。
+ * @param eventName - 要移除的事件名。
+ * @param handler - 对应的事件处理函数。
  * @returns 无返回值。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 export declare function off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
 /** 默认 SDK 实例的授权模块。 */
@@ -42,6 +93,8 @@ export declare const viewport: MiniProgramViewportModule;
 export declare const storage: MiniProgramStorageModule;
 /** 默认 SDK 实例的 network 模块。 */
 export declare const network: MiniProgramNetworkModule;
+/** 默认 SDK 实例的 files 模块。 */
+export declare const files: FilesModule;
 /** 默认 SDK 实例的 UI 模块。 */
 export declare const ui: MiniProgramUiModule;
 /** 默认 SDK 实例的 device 模块。 */

package/types/index.d.ts

@@ -1,5 +1,5 @@
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud, } from './core/singleton';
+export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, navigation, cloud, } from './core/singleton';
 export type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './core/handshake-state';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
 export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
@@ -10,7 +10,8 @@ export type { UserInfoAuthorizationScope } from './modules/user';
 export type { CopyLinkPayload, CopyLinkResult, MiniProgramCopyLinkOptions, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult, } from './modules/share';
 export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramViewportModule, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
 export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload } from './modules/storage';
-export type { MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
+export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
+export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './modules/files';
 export type { HideLoadingPayload, HideLoadingResult, MiniProgramToastStatus, MiniProgramUiModule, ShowLoadingPayload, ShowLoadingResult, ShowToastPayload, ShowToastResult, } from './modules/ui';
 export type { MiniProgramDeviceModule, MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult, } from './modules/device';
 export type { ClosePayload, CloseResult, MiniProgramAppPageTarget, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationModule, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenGameDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenPostDetailAppPageOptions, OpenUserDetailAppPagePayload, OpenUserDetailAppPageOptions, ReloadPayload, ReloadResult, } from './modules/navigation';
@@ -25,6 +26,7 @@ declare const hbSDK: {
     share: import(".").MiniProgramShareModule;
     viewport: import(".").MiniProgramViewportModule;
     storage: import(".").MiniProgramStorageModule;
+    files: import(".").FilesModule;
     network: import(".").MiniProgramNetworkModule;
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;

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

@@ -1,8 +1,11 @@
 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];
 export interface MiniappManifest {
     [key: string]: unknown;
     sdkVersion: string;
     version: string;
+    platforms: readonly MiniappPlatform[];
 }
 export interface ParseMiniappManifestResult {
     manifest: MiniappManifest;
@@ -16,5 +19,7 @@ export declare function parseMiniappManifestJson(raw: string, sourceLabel?: stri
 export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
     version: string;
     sdkVersion: string;
+    platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
 };
+export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
 export declare function validateSdkVersion(version: unknown, sourceLabel?: string): string;

package/types/miniapp-publish/index.d.ts

@@ -71,7 +71,7 @@ export interface MiniappUploadSessionFile {
 /**
  * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
  *
- * @param files 待处理的构建产物文件。
+ * @param files - 待处理的构建产物文件。
  * @returns 保留输入附加字段的有序文件列表。
  * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
  */
@@ -81,8 +81,8 @@ export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFil
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files 待上传的构建产物文件。
- * @param options 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件。
+ * @param options - 小程序和长度限制配置。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
  */
 export declare function validateMiniappUploadPathLengths(files: readonly Pick<MiniappArtifactFile, 'relativePath'>[], options: {
@@ -92,7 +92,7 @@ export declare function validateMiniappUploadPathLengths(files: readonly Pick<Mi
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount 参与签名的文件数量。
+ * @param fileCount - 参与签名的文件数量。
  * @returns 包含协议标识和文件数量的字节数组。
  * @throws 文件数量超出协议范围时抛出错误。
  */
@@ -100,7 +100,7 @@ export declare function createMiniappArtifactSignatureHeader(fileCount: number):
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file 已规范化或待校验的构建产物文件。
+ * @param file - 已规范化或待校验的构建产物文件。
  * @returns 包含路径长度、路径和文件大小的字节数组。
  * @throws 文件路径或大小非法时抛出错误。
  */
@@ -108,9 +108,9 @@ export declare function createMiniappArtifactFileHeader(file: MiniappArtifactFil
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles 本地构建产物文件。
- * @param serverFiles 服务端签发的文件映射。
- * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @param localFiles - 本地构建产物文件。
+ * @param serverFiles - 服务端签发的文件映射。
+ * @param uploadedKeys - 服务端已确认上传成功的 key。
  * @returns 完整映射、待上传文件和已确认 key。
  * @throws 服务端映射与本地产物不一致时抛出错误。
  */

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

@@ -16,7 +16,21 @@ export interface LoginResult {
 export type { MiniProgramAuthMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的授权模块。 */
 export interface MiniProgramAuthModule {
-    /** 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。 */
+    /**
+     * 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。
+     *
+     * @since 0.2.0-alpha.0
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     login(options?: LoginOptions): Promise<LoginResult>;
 }
 /** 获取短期授权码。 */