@heybox/hb-sdk 0.8.0-alpha → 0.8.0-alpha.10

package/skill/references/api-protocol.md

@@ -1,6 +1,6 @@
 # Protocol API reference
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 
@@ -26,16 +26,33 @@ export {
   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_BRIDGE_NONCE_PARAM,
   MINI_PROGRAM_MESSAGE_NAMESPACE,
   MINI_PROGRAM_MESSAGE_VERSION,
+  MINI_PROGRAM_OPERATION_PROGRESS_METHOD,
   MINI_PROGRAM_PROTOCOL_CAPABILITIES,
   NAVIGATION_CLOSE_METHOD,
   NAVIGATION_OPEN_APP_PAGE_METHOD,
   NAVIGATION_RELOAD_METHOD,
   NETWORK_REQUEST_METHOD,
+  NETWORK_DOWNLOAD_METHOD,
   SDK_HANDSHAKE_METHOD,
   SHARE_COPY_LINK_METHOD,
   SHARE_SCREENSHOT_METHOD,
@@ -52,7 +69,17 @@ export {
   VIEWPORT_GET_WINDOW_INFO_METHOD,
   VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
   isManagedMiniProgramRuntimePermissionKey,
+  isMiniProgramByteArray,
   isMiniProgramBridgeMessage,
+  isMiniProgramDirectoryDescriptor,
+  isMiniProgramDirectoryRef,
+  isMiniProgramDownloadProgressPayload,
+  isMiniProgramFileDescriptor,
+  isMiniProgramFileRef,
+  isMiniProgramFileStat,
+  isMiniProgramFileSystemEntityDescriptor,
+  isMiniProgramPathRootRef,
+  isMiniProgramRelativePath,
   parseMiniProgramRuntimePermissions,
 } from '@heybox/hb-sdk-protocol';
 
@@ -62,6 +89,14 @@ export type {
   CloseResult,
   CopyLinkPayload,
   CopyLinkResult,
+  DirectoryCreatePayload,
+  DirectoryCreateResult,
+  DirectoryExistsPayload,
+  DirectoryExistsResult,
+  DirectoryListPayload,
+  DirectoryListResult,
+  DirectoryRemovePayload,
+  DirectoryRemoveResult,
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
   GetCurrentUserLeaderboardEntryPayload,
@@ -78,8 +113,25 @@ export type {
   GetUserInfoResult,
   GetWindowInfoPayload,
   GetWindowInfoResult,
+  DownloadProgressPayload,
   HideLoadingPayload,
   HideLoadingResult,
+  FileCreatePayload,
+  FileCreateResult,
+  FileExistsPayload,
+  FileExistsResult,
+  FileReadBytesPayload,
+  FileReadBytesResult,
+  FileReadTextPayload,
+  FileReadTextResult,
+  FileRemovePayload,
+  FileRemoveResult,
+  FileStatPayload,
+  FileStatResult,
+  FileWriteBytesPayload,
+  FileWriteBytesResult,
+  FileWriteTextPayload,
+  FileWriteTextResult,
   LeaderboardEntry,
   LeaderboardOrder,
   LoginPayload,
@@ -87,8 +139,10 @@ export type {
   LoginScope,
   MiniProgramAuthMethod,
   MiniProgramBridgeError,
+  MiniProgramBridgeCancelMessage,
   MiniProgramBridgeMessage,
   MiniProgramBridgeMessageType,
+  MiniProgramBridgeProgressMessage,
   MiniProgramBridgeMethod,
   MiniProgramCapabilityDefinition,
   MiniProgramCapabilityModule,
@@ -99,8 +153,23 @@ export type {
   MiniProgramCapabilityRisk,
   MiniProgramCloudMethod,
   MiniProgramDeviceMethod,
+  MiniProgramDirectoryDescriptor,
+  MiniProgramDirectoryMethod,
+  MiniProgramDirectoryRef,
+  MiniProgramDirectDirectoryRef,
+  MiniProgramDirectFileRef,
   MiniProgramEventName,
   MiniProgramEventPayloadMap,
+  MiniProgramFileDescriptor,
+  MiniProgramFileMode,
+  MiniProgramFileMethod,
+  MiniProgramFileRef,
+  MiniProgramFilesMethod,
+  MiniProgramFileStat,
+  MiniProgramFileSystemEntityDescriptor,
+  MiniProgramFileSystemEntityRef,
+  MiniProgramPathRootRef,
+  MiniProgramSandboxRootRef,
   MiniProgramNavigationBarForegroundStyle,
   MiniProgramNavigationMethod,
   MiniProgramNetworkHeaders,
@@ -125,11 +194,17 @@ export type {
   MiniProgramWindowInfoResult,
   NetworkRequestPayload,
   NetworkResponsePayload,
+  NetworkDownloadPayload,
+  NetworkDownloadResult,
   OpenAppPagePayload,
   OpenAppPageResult,
   OpenGameDetailAppPagePayload,
   OpenPostDetailAppPagePayload,
   OpenUserDetailAppPagePayload,
+  PickDirectoryPayload,
+  PickDirectoryResult,
+  PickFilesPayload,
+  PickFilesResult,
   ParsedMiniProgramRuntimePermissions,
   ReloadPayload,
   ReloadResult,
@@ -137,6 +212,8 @@ export type {
   RevokeAuthorizationResult,
   ScreenshotPayload,
   ScreenshotResult,
+  SaveFilePayload,
+  SaveFileResult,
   SDKHandshakePayload,
   SetClipboardPayload,
   SetClipboardResult,
@@ -167,10 +244,29 @@ export type { LoginOptions } from './modules/auth';
 export type { GetSteamGameListOptions } from './modules/user';
 export type { MiniProgramEventHandler } from './protocol/types';
 export type {
+  DownloadBaseOptions,
+  DownloadOptions,
+  DownloadProgress,
   MiniProgramNetworkRequestConfig,
   MiniProgramNetworkResponse,
   MiniProgramNetworkValidateStatus,
 } from './modules/network';
+export type {
+  CreateOptions,
+  DirectoryHandle,
+  FileHandle,
+  FileMode,
+  FileStat,
+  FileSystem,
+  FileSystemEntity,
+  FilesModule,
+  ListOptions,
+  PathRoot,
+  PickDirectoryOptions,
+  PickFilesOptions,
+  RemoveOptions,
+  SaveFileOptions,
+} from './modules/files';
 export type { MiniProgramScreenshotOptions, MiniProgramShowShareMenuOptions } from './modules/share';
 export type { MiniProgramSetNavigationBarStyleOptions } from './modules/viewport';
 ```
@@ -188,25 +284,23 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 | [Protocol API](#public-protocol-entrypoint) | `@heybox/hb-sdk/protocol` 的协议常量、消息类型与 method 契约。 |
 | [Miniapp Publish API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/) | `@heybox/hb-sdk/miniapp-publish` 的构建产物发布前的公开校验工具。 |
 | [Vite API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/) | `@heybox/hb-sdk/vite` 的Vite 工坊小程序插件。 |
-| [Host Runtime 集成](https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/) | `@heybox/hb-sdk-runtime` 的 Host Port、Web Host 与 Runtime 集成入口；声明 Reference 在 Runtime package 内生成。 |
 
 ## 查询建议
 
 - 想查业务接入路径：先看 [Guide](recipes.md)。
 - 想查导出符号：从上方对应公开入口进入分类页。
-- 想接入详情页或 Browser Dev Host：先看 [Host Runtime 集成](https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/)，再查 Runtime package 的声明 Reference。
 - 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
 
 ## 统计
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 4 | 51 | 57 | 1 |
-| Protocol API | 0 | 3 | 34 | 62 | 30 |
+| Root API | 2 | 4 | 65 | 60 | 1 |
+| Protocol API | 0 | 13 | 56 | 90 | 47 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
 | Vite API | 0 | 1 | 5 | 1 | 1 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=2; fingerprint=d54639a086217e53edf8a85d2e11e0f0263aa0fd3dc88183fe2b3f3f07b4f4a1 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=3; fingerprint=95cbf9ad1d791cfa4133a35e9084252798450930135372e1467931e34226b8ea -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -1,6 +1,6 @@
 # Root API reference
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 
@@ -24,7 +24,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.0-alpha`
+- Version at generation time: `0.8.0-alpha.10`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -43,6 +43,7 @@ export {
   share,
   viewport,
   storage,
+  files,
   network,
   ui,
   device,
@@ -117,6 +118,9 @@ export type {
 } from './modules/viewport';
 export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload } from './modules/storage';
 export type {
+  DownloadBaseOptions,
+  DownloadOptions,
+  DownloadProgress,
   MiniProgramNetworkHeaders,
   MiniProgramNetworkModule,
   MiniProgramNetworkParams,
@@ -127,6 +131,22 @@ export type {
   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,
@@ -177,6 +197,7 @@ import {
   onHandshakeStateChange,
   share,
   storage,
+  files,
   ui,
   viewport,
   user,
@@ -192,6 +213,7 @@ const hbSDK = {
   share,
   viewport,
   storage,
+  files,
   network,
   ui,
   device,
@@ -218,6 +240,8 @@ import {
   type MiniappPlatform,
 } from '../miniapp-manifest/schema';
 import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
+import { readMiniappPermissionsFromPackageJson } from '../miniapp-manifest/node';
+import { getMissingPermissionsWarning } from '../miniapp-manifest/permissions';
 import { enforceMiniappHtmlPolicy } from './html-policy';
 import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
 
@@ -325,6 +349,8 @@ export function miniappManifest(options: MiniappManifestOptions): MiniappManifes
 
       const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
       const sdkVersion = resolveSdkVersion();
+      const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
+      if (!parsedPermissions.declared) this.warn(getMissingPermissionsWarning());
       const outputRoot = path.resolve(root, outDir);
       const htmlFiles = collectHtmlFiles(outputRoot);
       const unexpectedHtmlFiles = htmlFiles.filter((file) => path.relative(outputRoot, file) !== 'index.html');
@@ -343,7 +369,15 @@ export function miniappManifest(options: MiniappManifestOptions): MiniappManifes
 
       const manifestPath = path.join(outputRoot, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
+      writeFileSync(
+        manifestPath,
+        renderMiniappManifest({
+          version,
+          sdkVersion,
+          platforms,
+          ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
+        }),
+      );
     },
   };
 }
@@ -398,7 +432,7 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
 
-直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端权限；仅当 `network.request.status=enabled` 时向子构建传递已验证上下文并跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
+直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
 推荐由项目的 `scripts.build` 保留类型检查：
 
@@ -417,7 +451,9 @@ hb-sdk build [--env <name>] [--verbose]
 
 # 快速开始
 
-如果页面不需要小黑盒开放能力，可以不接入 SDK。SDK 导入时会自动启动握手，能力调用会自动等待；业务只需根据小程序是否开通网络权限选择身份流程。
+新项目可先运行 `hb-sdk create my-miniapp` 获得 Vanilla JavaScript + Vite HelloWorld；模板只演示 Toast，业务代码可以直接替换。
+
+如果页面不需要小黑盒开放能力，可以不接入 SDK。SDK 导入时会自动启动握手，能力调用会自动等待；使用受保护能力前需在 `package.json#heybox.permissions` 声明对应权限，详见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
 
 ## 交互控件与握手状态
 
@@ -428,7 +464,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')
@@ -438,9 +474,9 @@ onUnmounted(stopHandshakeState)
 
 把 `sdkReady` 用作按钮的 `disabled` 条件。订阅会立即回放当前状态，因此晚挂载组件也能得到 `ready` 或 `failed` 终态。`ready` 生命周期事件只在握手成功瞬间派发且不会重放，不能作为当前状态来源。
 
-## 未开通网络权限
+## 读取当前用户
 
-无网络小程序可以在本地能力中使用按小程序隔离的 `app_user_id` 和公开资料：
+声明 `userInfo` 后，可以读取按小程序隔离的 `app_user_id` 和已授权资料。该能力不依赖公开 `network` 权限：
 
 ```ts
 import hbSDK from '@heybox/hb-sdk'
@@ -453,9 +489,9 @@ async function getCurrentUser() {
 
 `user.getInfo()` 不展示授权弹窗，也不要求可信用户手势。未登录时返回未登录状态；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），静默返回 `userInfo.app_user_id`、`profile.nickname` 和 `profile.avatar`。这条路径不能获取授权码或调用 OpenAPI，也不能把身份或资料发送到外部服务。
 
-## 已开通网络权限
+## 获取服务端授权码
 
-有网络小程序通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作：
+声明 `userInfo` 后，可通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作。该调用内部使用 Host 受信请求，不依赖公开 `network` 权限；示例中的 `network.request()` 另需声明并获得 `network` 平台批准。
 
 SDK 会自动完成握手。登录按钮应按上面的持久握手状态启用；点击回调直接调用 `auth.login()`，不要先等待其他异步任务，以免首次操作丢失可信手势。
 
@@ -484,6 +520,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 起不再对业务代码提供独立实例工厂。
@@ -520,9 +652,15 @@ try {
 
 - 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
 - 权限失败时给出可理解的提示，不要将它当成未登录。
+- `PERMISSION_NOT_DECLARED` 表示当前版本没有在 `package.json#heybox.permissions` 声明所需权限，应修改项目配置并重新构建、提交版本。
+- `PERMISSION_DENIED` 表示权限已声明，但需要的平台批准缺失或批准配置不足。首期只有 `network` 需要平台批准。
 - `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` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -571,24 +709,29 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 
 授权码在取得后立即交给开发者服务端交换，不要写入页面状态、DOM、日志或持久化存储。UI 只处理服务端会话是否建立成功。
 
+文件与下载仍使用 `HbMiniProgramSDKError`，不会新增第三种错误类。业务根据 `error.code` 处理
+picker 取消、授权撤销、文件缺失、quota、下载状态或取消，不依赖 `message` 文案，也不要记录
+真实路径、内部 handle 或响应凭据头。
+
 ## Public modules
 
 ## 能力概览
 
 SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握手状态，并通过 `on()` / `off()` 处理前后台、登录态等生命周期事件。
 
-| 模块         | 用途                                       |
-| ------------ | ------------------------------------------ |
-| `auth`       | 获取交给开发者服务端交换的短期授权码       |
-| `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权 |
-| `share`      | 打开分享、复制链接或截图分享流程           |
-| `ui`         | 展示 Toast 和 Loading                      |
-| `device`     | 调用振动和剪贴板能力                       |
-| `navigation` | 关闭、刷新页面或打开小黑盒页面             |
-| `viewport`   | 读取窗口信息和设置导航栏样式               |
-| `storage`    | 读写当前小程序的隔离存储                   |
-| `cloud`      | 使用小程序云端排行榜                       |
-| `network`    | 发起经过平台授权的网络请求                 |
+| 模块         | 用途                                            |
+| ------------ | ----------------------------------------------- |
+| `auth`       | 获取交给开发者服务端交换的短期授权码            |
+| `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权      |
+| `share`      | 打开分享、复制链接或截图分享流程                |
+| `ui`         | 展示 Toast 和 Loading                           |
+| `device`     | 调用振动和剪贴板能力                            |
+| `navigation` | 关闭、刷新页面或打开小黑盒页面                  |
+| `viewport`   | 读取窗口信息和设置导航栏样式                    |
+| `storage`    | 读写当前小程序的隔离存储                        |
+| `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
+| `cloud`      | 使用小程序云端排行榜                            |
+| `network`    | 发起经过平台授权的网络请求，并声明受控流式下载  |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
@@ -643,7 +786,7 @@ onUnmounted(stopLifecycleEvents)
 - 当前握手状态只通过 `getHandshakeState()` 查询、通过 `onHandshakeStateChange()` 订阅；订阅会立即回放当前值并返回取消函数。
 - `ready` 事件只在握手成功瞬间派发，不会向晚订阅者重放，不能用于驱动按钮可用状态或替代握手状态 API。
 - UI 可见性相关逻辑放在 `show`、`hide`。
-- 使用 Host current-user APIs 的无网络小程序，可以在 `heybox_app_login_change` 后刷新本地状态。已开通网络权限的小程序使用 `auth.login()` 获取 code，并由开发者服务端维护业务会话。
+- 使用 `user.getInfo()` 的小程序可以在 `heybox_app_login_change` 后刷新本地状态。需要开发者服务端会话时使用 `auth.login()` 获取 code；两者都不依赖公开 `network` 权限。
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
 - 生命周期事件只派发给注册当时存在的监听器，不会重放；一次性 `launch` 信息应在页面启动阶段通过业务能力调用处理。
 - 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。