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

package/skill/references/api-protocol.md

@@ -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';
 ```
@@ -201,7 +297,19 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 4 | 51 | 57 | 1 |
-| Protocol API | 0 | 3 | 44 | 68 | 31 |
+| 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 | 0 | 0 | 0 |
+| Vite API | 0 | 1 | 5 | 1 | 1 |
+
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=2; fingerprint=904f09f0012164f5d6b18c0f93477bb2bd541a41b99da8f270d0a40b93e96602 -->
+
+## SDK API
+
+- [兼容性总览](https://docs.xiaoheihe.cn/hb_sdk/reference/compatibility)
+
+## 常用 API
+
+- [`user.getInfo`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/user/getInfo)
+- [`auth.login`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/auth/login)
+- [`cloud.leaderboard.submit`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/cloud/leaderboard/submit)

package/skill/references/api-root.md

@@ -24,7 +24,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.7.5-alpha.0`
+- Version at generation time: `0.8.0-alpha.2`
 - 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,
@@ -210,12 +232,18 @@ Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { HB_SDK_VERSION } from '../core/version';
-import { renderMiniappManifest, validateMiniappPackageVersionForBuild } from '../miniapp-manifest/schema';
+import {
+  MINIAPP_PLATFORM_VALUES,
+  renderMiniappManifest,
+  validateMiniappPackageVersionForBuild,
+  validateMiniappPlatforms,
+  type MiniappPlatform,
+} from '../miniapp-manifest/schema';
 import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
 import { enforceMiniappHtmlPolicy } from './html-policy';
 import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
 
-type MiniappManifestPlugin = {
+export interface MiniappManifestPlugin {
   name: string;
   config: (config: MiniappManifestUserConfig) => MiniappManifestUserConfig | void;
   configResolved: (resolved: MiniappManifestResolvedConfig) => void;
@@ -223,18 +251,18 @@ type MiniappManifestPlugin = {
   buildEnd: (error?: Error) => void;
   transformIndexHtml: (html: string) => string;
   closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
-};
+}
 
-interface MiniappManifestUserConfig {
+export interface MiniappManifestUserConfig {
   base?: string;
   define?: Record<string, string>;
 }
 
-interface MiniappManifestPluginContext {
+export interface MiniappManifestPluginContext {
   warn: (message: string) => void;
 }
 
-interface MiniappManifestResolvedConfig {
+export interface MiniappManifestResolvedConfig {
   root: string;
   command: 'build' | 'serve';
   build: {
@@ -253,12 +281,21 @@ interface MiniappManifestResolvedConfig {
           protocol?: 'ws' | 'wss';
         };
   };
+  plugins?: readonly { name?: string }[];
+}
+
+export { MINIAPP_PLATFORM_VALUES };
+export type { MiniappPlatform };
+
+export interface MiniappManifestOptions {
+  platforms: readonly MiniappPlatform[];
 }
 
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 
-export function miniappManifest(): MiniappManifestPlugin {
+export function miniappManifest(options: MiniappManifestOptions): MiniappManifestPlugin {
+  const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
   const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
   let root = process.cwd();
   let outDir = 'dist';
@@ -279,6 +316,12 @@ export function miniappManifest(): MiniappManifestPlugin {
       };
     },
     configResolved(resolved) {
+      if (resolved.plugins) {
+        const manifestPluginCount = resolved.plugins.filter((plugin) => plugin.name === 'heybox-miniapp-manifest').length;
+        if (manifestPluginCount !== 1) {
+          throw new Error(`Vite 配置必须且只能包含一个 miniappManifest() 插件，当前数量：${manifestPluginCount}`);
+        }
+      }
       root = resolved.root;
       outDir = resolved.build.outDir;
       command = resolved.command;
@@ -322,7 +365,7 @@ export function miniappManifest(): MiniappManifestPlugin {
 
       const manifestPath = path.join(outputRoot, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));
+      writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
     },
   };
 }
@@ -407,7 +450,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')
@@ -463,6 +506,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 起不再对业务代码提供独立实例工厂。
@@ -502,6 +641,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` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -550,24 +693,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/)。
 

package/skill/references/cli.md

@@ -27,7 +27,7 @@
 - [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.
 
@@ -100,15 +100,15 @@ Agent rules:
 hb-sdk dev
 ```
 
-CLI 会启动页面服务并自动打开本地调试页。调试页会展示小程序、浏览器 Mock、Mac 启动入口和手机二维码。
+CLI 会启动页面服务并自动打开 Vue 3 本地调试台。左侧集中放置调用日志、Storage 和问题三个诊断页签，右侧保持稳定的小程序内容与设备预览。
 
-<img src="https://static.max-c.com/static/heybox/webapp/heybox-docs/docs-hb_sdk/assets/local-preview-debug-page.png" alt="hb-sdk 本地调试页、浏览器 Mock 和真机调试入口" style="width: 100%; max-width: 860px;" />
+<img src="/assets/browser-dev-host-workbench.png" alt="小程序工坊 Vue 3 调试台" style="width: 100%; max-width: 1120px;" />
 
-`hb-sdk dev` 不支持匿名调试。启动前必须先运行 `hb-sdk login`，并通过 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>` 绑定当前项目；未登录、未绑定或远端 Dev Context 不可用时，CLI 会在启动 Vite 和调试服务前终止。
+浏览器调试入口不要求 CLI 登录或项目绑定。没有账号、绑定小程序或远端 Dev Context 时，页面和基础 Browser Mock 仍可启动；依赖这些上下文的能力会返回明确失败。远端管理、部署和发布仍要求完成登录与绑定。
 
-`hb-sdk dev` 会在启动 Vite 前读取远端权限。只有远端权限快照有效且 `network.request.status=enabled` 时才跳过平台 CSP；`useOfficialDomain` 不参与该判定。本地 Dev Context 权限覆盖不会改变 CSP 决策。
+`hb-sdk dev` 在远端权限快照可用时读取它。只有快照有效且 `network.request.status=enabled` 时才跳过平台 CSP；`useOfficialDomain` 不参与该判定。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入；快照缺失或无效时保留平台 CSP。
 
-当前调试链路不要求升级 Android、iOS 或 Mac 客户端。Browser Mock 会自动在实时与兼容链路间切换；Mobile 使用 `open_inapp`/`openWindow` 包裹的 LAN 短链接二维码（先开普通 H5 跳转页，再进入小程序并关闭中间页）；PC/Mac 行为保持不变。
+Browser Mock 会自动在实时与兼容链路间切换。手机调试使用 `open_inapp`/`openWindow` 包裹的 LAN 短链接二维码（先开普通 H5 跳转页，再进入小程序并关闭中间页）。
 
 ### 2. 先用浏览器 Mock 验收
 
@@ -118,13 +118,15 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 - SDK 初始化与用户身份授权流程
 - 生命周期、Storage 和排行榜等能力
 
-调试页中调整的权限只影响当前本地调试，不会修改线上配置；切换权限后 Mobile App 会重生成二维码。Debug/Ad-Hoc 的本地增强不可用、过期或读取失败时继续使用原生 Host。恢复初始权限后重新按远端配置验收；工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
+调试台提供紧凑的调用日志、当前小程序隔离作用域内的 Storage 只读快照和问题聚合。日志与网络记录只保留脱敏的诊断字段，不展示 payload、结果、查询参数、凭据或原始错误信息。工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
 
-### 3. 再用 Mac 或手机真机验收
+右侧可切换 iPhone 16 Pro Max（`387 x 821`）与 Pixel 9 Pro（`322 x 716`）两个设备预设。尺寸对应固定上游设备外框的真实屏幕 opening；预设同时决定外框、状态栏、安全区和 viewport。切换设备不会重新加载小程序或重启 Runtime，页面状态和调试会话保持不变。授权与操作弹窗、Toast、Loading 和振动反馈均显示在设备预览内部，不会覆盖整个调试台。
 
-需要确认真实客户端表现时，可以使用调试页提供的 Mac 启动入口；手机验收则在「Mobile App」区域选择局域网网卡，再用手机小黑盒 APP 扫码。
+### 3. 再用手机真机验收
 
-手机与电脑需要处于同一局域网。二维码走 HTTPS `open_inapp` 与 `heybox://` `openWindow`，其中 `webview.url` 是局域网短链 `http://<lan-ip>:<browser-dev-host-port>/l/<token>`。短链返回跳转页：先打开带 `mini_url`、小程序身份、启动票、SDK 版本和局域网 Dev Context 的完整 `heybox-mini-dev://sandbox` 协议，约 500ms 后再发 `closeWindow` 关掉中间页。权限、网卡或启动票变化时调试页会刷新二维码并轮换 Dev Session。多网卡时选择手机实际可达的 **Network**。发布前至少完成一次真实客户端验收。
+需要确认真实客户端表现时，从调试台右上角唯一的二维码入口打开浮层，选择局域网网卡，再用手机小黑盒 APP 扫码。页面不再提供 Browser/Mobile 切换页签或其他二维码入口。
+
+手机与电脑需要处于同一局域网。二维码走 HTTPS `open_inapp` 与 `heybox://` `openWindow`，其中 `webview.url` 是局域网短链 `http://<lan-ip>:<browser-dev-host-port>/l/<token>`。短链返回跳转页：先打开带 `mini_url`、小程序身份、启动票、SDK 版本和局域网 Dev Context 的完整 `heybox-mini-dev://sandbox` 协议，约 500ms 后再发 `closeWindow` 关掉中间页。网卡或启动票变化时调试台会刷新二维码并轮换 Dev Session。多网卡时选择手机实际可达的 **Network**。发布前至少完成一次真实客户端验收。
 
 ### 浏览器 Mock 的边界
 
@@ -132,14 +134,16 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 
 ### 常用参数
 
-| 参数                             | 用途                                                          |
-| -------------------------------- | ------------------------------------------------------------- |
-| `--port <port>`                  | 指定页面开发服务端口。                                        |
-| `--browser-dev-host-port <port>` | 指定 Browser Dev Host 端口。                                  |
-| `--no-open`                      | 启动后不自动打开浏览器。                                      |
-| `--verbose`                      | 出现问题时输出更详细的诊断信息。                              |
+| 参数                             | 用途                             |
+| -------------------------------- | -------------------------------- |
+| `--port <port>`                  | 指定页面开发服务端口。           |
+| `--browser-dev-host-port <port>` | 指定 Browser Dev Host 端口。     |
+| `--no-open`                      | 启动后不自动打开浏览器。         |
+| `--verbose`                      | 出现问题时输出更详细的诊断信息。 |
+
+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.
 
-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.
+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.
 

package/skill/references/examples.md

@@ -105,6 +105,33 @@ try {
 }
 ```
 
+### Sandbox download contract (Host pending)
+
+```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
 
 ```ts
@@ -144,7 +171,7 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest()],
+  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
 });
 ```
 
@@ -158,6 +185,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.