@heybox/hb-sdk 0.8.0-alpha → 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,8 +21,19 @@
 - `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({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 

package/skill/scripts/sync-references.mjs

@@ -383,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.
 
@@ -408,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.
 
@@ -694,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(
@@ -751,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.8.0-alpha+skill.e73cb0ba5184",
+  "skillVersion": "0.8.0-alpha.2+skill.417e5072238c",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0-alpha",
-    "compatibility": "0.8.0-alpha"
+    "version": "0.8.0-alpha.2",
+    "compatibility": "0.8.0-alpha.2"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-e73cb0ba518459e1b262d09fb0ead87a7163c8e5358430184a9dd4f085049357"
+  "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/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;
     /** 设备相关开放能力。 */

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';
@@ -92,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/modules/files/index.d.ts

@@ -0,0 +1,5 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { FilesModule } from './types';
+export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './types';
+/** 创建当前 SDK session 的 files 模块。 */
+export declare function createFilesModule(requester: MiniProgramRequester): FilesModule;

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

@@ -0,0 +1,35 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramDirectoryDescriptor, MiniProgramDirectoryRef, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileRef, MiniProgramFileSystemEntityDescriptor } from '@heybox/hb-sdk-protocol';
+import type { DirectoryHandle, FileHandle, FileSystem, FileSystemEntity } from './types';
+interface FileHandleState {
+    ref: MiniProgramFileRef;
+    mode: MiniProgramFileMode;
+}
+interface DirectoryHandleState {
+    ref: MiniProgramDirectoryRef;
+    mode: MiniProgramFileMode;
+}
+/** 校验并返回平台无关的 `/` 分隔逻辑相对路径。 */
+export declare function normalizeRelativePath(value: unknown): string;
+export declare class MiniProgramFileHandleRegistry {
+    private readonly requester;
+    private readonly fileStates;
+    private readonly directoryStates;
+    private readonly pathRootStates;
+    private sandboxRoot?;
+    constructor(requester: MiniProgramRequester);
+    getSandbox(): FileSystem;
+    createFile(descriptor: MiniProgramFileDescriptor): FileHandle;
+    createDirectFile(descriptor: MiniProgramFileDescriptor): FileHandle;
+    createDirectory(descriptor: MiniProgramDirectoryDescriptor): DirectoryHandle;
+    createDirectDirectory(descriptor: MiniProgramDirectoryDescriptor): DirectoryHandle;
+    createEntity(descriptor: MiniProgramFileSystemEntityDescriptor): FileSystemEntity;
+    requireFile(handle: unknown): FileHandleState;
+    requireDirectory(handle: unknown): DirectoryHandleState;
+    private definePathRootMethods;
+    private assertFileDescriptor;
+    private assertDirectoryDescriptor;
+}
+export declare function getFileHandleRegistry(requester: MiniProgramRequester): MiniProgramFileHandleRegistry;
+export declare function isMiniProgramFileSystemValue(value: unknown): value is FileSystem | FileSystemEntity;
+export {};

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

@@ -0,0 +1,159 @@
+/** File/Directory 访问模式。 */
+export type FileMode = 'read' | 'readwrite';
+export interface PickFilesOptions {
+    mode?: FileMode;
+    accept?: string[];
+    multiple?: boolean;
+}
+export interface PickDirectoryOptions {
+    mode?: FileMode;
+}
+export interface SaveFileOptions {
+    suggestedName: string;
+}
+export interface CreateOptions {
+    recursive?: boolean;
+    exclusive?: boolean;
+}
+export interface RemoveOptions {
+    /** 是否递归删除目录内容，默认 `false`。 */
+    recursive?: boolean;
+}
+export interface ListOptions {
+    limit?: number;
+}
+/** 可同步派生 lazy File/Directory proxy 的逻辑根。 */
+export interface PathRoot {
+    /**
+     * 按规范相对路径派生文件代理。
+     *
+     * @param relativePath - 使用 `/` 分隔的规范相对路径。
+     * @returns 延迟访问对应文件的代理。
+     * @since 0.8.0-alpha.2
+     * @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
+     */
+    file(relativePath: string): FileHandle;
+    /**
+     * 按规范相对路径派生目录代理。
+     *
+     * @param relativePath - 使用 `/` 分隔的规范相对路径。
+     * @returns 延迟访问对应目录的代理。
+     * @since 0.8.0-alpha.2
+     * @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
+     */
+    directory(relativePath: string): DirectoryHandle;
+}
+/** Mini-program 私有 sandbox 的逻辑根。 */
+export interface FileSystem extends PathRoot {
+}
+/** 当前 SDK session 中的文件代理。 */
+export interface FileHandle {
+    readonly kind: 'file';
+    readonly name: string;
+    readonly mode: FileMode;
+    create(options?: CreateOptions): Promise<FileHandle>;
+    /** 删除 sandbox 文件；外部授权文件不允许删除。 */
+    remove(): Promise<void>;
+    exists(): Promise<boolean>;
+    readText(): Promise<string>;
+    writeText(content: string): Promise<void>;
+    readBytes(): Promise<Uint8Array>;
+    writeBytes(content: Uint8Array): Promise<void>;
+    stat(): Promise<FileStat>;
+}
+/** 当前 SDK session 中的目录代理。 */
+export interface DirectoryHandle extends PathRoot {
+    readonly kind: 'directory';
+    readonly name: string;
+    readonly mode: FileMode;
+    create(options?: CreateOptions): Promise<DirectoryHandle>;
+    /** 删除 sandbox 目录；非空目录需要显式设置 `recursive`，外部授权目录不允许删除。 */
+    remove(options?: RemoveOptions): Promise<void>;
+    exists(): Promise<boolean>;
+    list(options?: ListOptions): Promise<FileSystemEntity[]>;
+}
+export type FileSystemEntity = FileHandle | DirectoryHandle;
+export interface FileStat {
+    kind: 'file';
+    size: number;
+    /** Unix epoch milliseconds。 */
+    modifiedAt?: number;
+    /** Unix epoch milliseconds。 */
+    createdAt?: number;
+}
+/** Mini-program 对外文件能力。 */
+export interface FilesModule {
+    readonly sandbox: FileSystem;
+    /**
+     * 让用户选择一个或多个文件并返回当前 session 的授权代理。
+     *
+     * @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 ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    pickFiles(options?: PickFilesOptions): Promise<FileHandle[]>;
+    /**
+     * 让用户选择目录并返回当前 session 的授权代理。
+     *
+     * @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 ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    pickDirectory(options?: PickDirectoryOptions): Promise<DirectoryHandle>;
+    /**
+     * 让用户选择一个精确的文件保存目标。
+     *
+     * @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 ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    saveFile(options: SaveFileOptions): Promise<FileHandle>;
+}

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

@@ -1,5 +1,6 @@
-import type { MiniProgramRequester } from '../../core/client';
-export { NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
+import type { MiniProgramOperationRequester, MiniProgramRequester } from '../../core/client';
+import type { DirectoryHandle, FileHandle } from '../files';
+export { NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
 export { createNetworkRequestFailureLog, formatNetworkRequestFailureMessage, logNetworkRequestFailure, previewNetworkData, sanitizeNetworkHeaders, sanitizeNetworkRequestUrl, } from './observability';
 export { describeHostNetworkFailure, isMultipartContentType, isUnsupportedMultipartNetworkRequest, looksLikeMultipartBody, NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE, readNetworkContentType, } from './request-shape';
 /** `network.request` 请求头。 */
@@ -42,6 +43,32 @@ export interface MiniProgramNetworkRequestConfig {
     /** SDK 侧状态校验；不会跨 bridge 传输函数值。 */
     validateStatus?: MiniProgramNetworkValidateStatus;
 }
+/** 流式下载的 request-scoped 进度。 */
+export interface DownloadProgress {
+    loaded: number;
+    total?: number;
+    lengthComputable: boolean;
+}
+export interface DownloadBaseOptions {
+    url: string;
+    params?: MiniProgramNetworkParams;
+    headers?: MiniProgramNetworkHeaders;
+    timeout?: number;
+    withCredentials?: boolean;
+    maxBytes?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: DownloadProgress) => void;
+}
+/** File target 原子替换，Directory target 创建或替换子文件。 */
+export type DownloadOptions = DownloadBaseOptions & ({
+    to: FileHandle;
+    suggestedName?: never;
+    overwrite?: never;
+} | {
+    to: DirectoryHandle;
+    suggestedName?: string;
+    overwrite?: boolean;
+});
 /**
  * bridge / runtime 可消费的网络请求 payload。
  *
@@ -100,6 +127,24 @@ export interface MiniProgramNetworkModule {
      * @hbClient macos none
      */
     request<T = unknown>(config: MiniProgramNetworkRequestConfig): Promise<MiniProgramNetworkResponse<T>>;
+    /**
+     * 将 GET 响应流式写入受控 File/Directory target。
+     *
+     * @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 ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    download(options: DownloadOptions): Promise<FileHandle>;
 }
 /**
  * 发起网络请求并返回标准化响应。
@@ -123,10 +168,12 @@ export interface MiniProgramNetworkModule {
  * ```
  */
 export declare function request<T = unknown>(requester: MiniProgramRequester, config: MiniProgramNetworkRequestConfig): Promise<MiniProgramNetworkResponse<T>>;
+/** 发起不使用 bridge 固定总时长 timer 的流式下载。 */
+export declare function download(requester: MiniProgramOperationRequester, options: DownloadOptions): Promise<FileHandle>;
 /**
  * 创建 network 模块。
  *
  * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的网络模块对象。
  */
-export declare function createNetworkModule(requester: MiniProgramRequester): MiniProgramNetworkModule;
+export declare function createNetworkModule(requester: MiniProgramOperationRequester): MiniProgramNetworkModule;

package/types/protocol/capabilities.d.ts

@@ -1,2 +1,2 @@
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from '@heybox/hb-sdk-protocol';
-export type { MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from '@heybox/hb-sdk-protocol';
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from '@heybox/hb-sdk-protocol';
+export type { MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryMethod, MiniProgramFileMethod, MiniProgramFilesMethod, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from '@heybox/hb-sdk-protocol';

package/types/protocol/constants.d.ts

@@ -1 +1 @@
-export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, } from '@heybox/hb-sdk-protocol';
+export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, } from '@heybox/hb-sdk-protocol';

package/types/protocol/guards.d.ts

@@ -1 +1 @@
-export { isMiniProgramBridgeMessage } from '@heybox/hb-sdk-protocol';
+export { isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, } from '@heybox/hb-sdk-protocol';