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

package/skill/SKILL.md

@@ -51,17 +51,19 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 11. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
 12. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
 13. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the default mini-program share link. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
+14. Treat `files` and `network.download()` as a retained public contract that is not yet enabled by a current Host. The legacy PC adapter was dropped because the new PC will implement the Host ports directly. Until then, legacy PC, Mobile, Web, and Browser Dev Host return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Once a supporting Host is available, call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
+15. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
 
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a workshop mini-program.
-2. Use `hb-sdk dev` for Browser Mock, Mac App, or Mobile App debugging. It requires an active CLI login, a bound Mini-program, and an available remote Dev Context; it must stop before starting Vite or any debugging service when a prerequisite is missing. Mobile uses the `open_inapp` and `heybox://` `openWindow` wrapper with a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
-3. Treat debugging-page permission overrides as local development behavior; overrides do not change remote permissions. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
+2. Use `hb-sdk dev` for Browser Mock and Mobile App debugging. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need those inputs fail explicitly. Mobile uses the single QR entry with the `open_inapp` and `heybox://` `openWindow` wrapper around a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
+3. The debugging page does not edit permissions. Treat the validated remote permission snapshot as canonical Runtime input. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
 5. Keep `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the required Manifest or Runtime gate output is missing.
 6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
 7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
-8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for development, publishing, and Browser Mock Host `heybox-session` requests. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
+8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
 9. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
 10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
 11. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
@@ -81,11 +83,12 @@ For workshop mini-program business code:
 1. Do not read or request tokens, cookies, phone numbers, or private credentials from the SDK.
 2. Do not expose raw share protocol fields, JS callbacks, activity reporting, custom buttons, direct post publishing, or upload-only flows. Public `share.*({ post })` options only preset an editable client post flow and never publish automatically.
 3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
-4. Use only the public `network.request` configuration.
+4. Use only the public `network.request` / `network.download` configurations.
 5. Do not use private package paths or client protocols.
 6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
+9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
 
 For CLI and local development:
 
@@ -93,8 +96,9 @@ For CLI and local development:
 2. Do not skip `auth.login()` in mini-program code. Browser Mock may reuse the Node `hb-sdk login` session for Host network requests, but the page must still call `auth.login()` and handle the authorization dialog. Never paste CLI credentials into page JavaScript.
 3. Use the built-in local debugging page instead of creating another browser Mock.
 4. Keep the Vite `miniappManifest()` plugin enabled.
-5. Treat permission changes made in the `hb-sdk dev` debugging page as local debugging overrides, not online configuration changes. Use the page's reset action to return to the remote baseline.
+5. Do not suggest changing or resetting permissions in the `hb-sdk dev` debugging page; that UI does not exist. Diagnose permission behavior from the remote snapshot and capability result.
 6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
+7. The Browser Dev Host offers iPhone 16 Pro Max (`440 x 956`) and Pixel 9 Pro (`410 x 914`) presets. Switching a preset must preserve the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Use the upper-right QR popover as the only Mobile QR entry.
 
 For host/runtime/protocol-maintenance code:
 
@@ -110,17 +114,16 @@ For host/runtime/protocol-maintenance code:
    - `cat packages/hb-sdk/DOC_SYNC_CHECKLIST.md`
 3. When preparing a package release, run `pnpm --filter @heybox/hb-sdk run release:prepare -- --bump patch` or `pnpm --filter @heybox/hb-sdk run release:prepare -- --version <x.y.z>`. The release assistant updates the Protocol/Runtime/SDK family versions, inserts `packages/hb-sdk/CHANGELOG.md`, and runs `check:changelog`. Use `--ai-command "<command>"` or `HB_SDK_CHANGELOG_AI_COMMAND` when an AI writer should rewrite the Conventional Commit draft. Review the entry for Mini-program developers and Host/Runtime integration maintainers, and do not expose Runtime internal adapter, state-machine, or security-policy details.
 4. When modifying this repo's source skill at `packages/hb-sdk/skill` and preparing distributable artifacts, also run:
-   - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
+   - `node packages/hb-sdk/scripts/skill/sync-references.mjs`
+   - `node packages/hb-sdk/scripts/skill/validate-skill.mjs`
 5. When modifying CLI, local debugging, package exports, or package dependency direction, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
-6. Inspect the generated zip before distribution:
-   - `unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'`
-7. When adding or modifying the deploy command or its upload pipeline, also run:
+6. When adding or modifying the deploy command or its upload pipeline, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
    - Verify `dist/cli.cjs` does not have any `require('cos-nodejs-sdk-v5')` left after `build:cli`; the boundary check enforces this automatically.
-8. Verify the canonical payload before publishing:
-   - `pnpm exec hbexec hb-sdk sync`
-   - `pnpm exec hbexec hb-sdk check`
-   - For a release artifact, run `pnpm exec hbexec hb-sdk sync --out-dir <payload-dir>` and then `pnpm exec hbexec hb-sdk check-artifact --artifact-dir <payload-dir>`.
+7. Verify the canonical payload before publishing:
+   - `node packages/hb-sdk/scripts/skill/sync-references.mjs`
+   - `node packages/hb-sdk/scripts/skill/validate-skill.mjs`
+   - For a release artifact, run `npm pack --dry-run` and `node packages/hb-sdk/scripts/skill/verify-tarball-install.mjs`.

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';
 ```
@@ -201,12 +297,12 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | 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=2; fingerprint=cb985ad876f7066639ee3b72d545185f251ed6ad597b8276425e02615bb608ba -->
 
 ## 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.3`
 - 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,
@@ -428,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')
@@ -484,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 起不再对业务代码提供独立实例工厂。
@@ -523,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` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -571,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

@@ -1,6 +1,6 @@
 # CLI 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
 
@@ -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.
 
@@ -40,7 +40,8 @@ hb-sdk build [--env <name>] [--verbose]
 hb-sdk login
 hb-sdk login status
 hb-sdk login clear
-hb-sdk doctor
+hb-sdk skill install [--global] [--agent <agent>] [--all-agents] [--force]
+hb-sdk doctor [--agent <agent>] [--all-agents] [--json]
 hb-sdk remote access
 hb-sdk remote entity list
 hb-sdk remote entity current
@@ -100,15 +101,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 +119,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 +135,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.
 
@@ -268,8 +273,8 @@ Agent rules:
 
 Agent rules:
 
-- Use `hb-sdk doctor` for read-only diagnosis of local SDK, remote latest skill metadata, and local skill metadata.
-- Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-- If doctor reports `SDK_MISMATCH`, tell the user to upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+- Use `hb-sdk doctor [--agent <agent>] [--all-agents] [--json]` for read-only diagnosis of the locally installed SDK and its bundled Skill.
+- Use `hb-sdk skill install` to install or refresh the Skill bundled with the matching npm package. Add `--global` for user scope, `--agent <agent>` for one Agent, or `--all-agents` for every supported Agent.
+- If doctor reports `SDK_MISMATCH`, upgrade the project dependency to the matching @heybox/hb-sdk version before reinstalling the skill.
 
 ## Update reminders