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

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
@@ -75,12 +76,16 @@ Top-level `hb-sdk deploy` has been hard-cut and must not be documented as a vali
 新项目可以直接从模板开始：
 
 ```bash
-npx @heybox/hb-sdk@latest create my-miniapp
+npx @heybox/hb-sdk@alpha create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
 ```
 
+默认产物是 Vanilla JavaScript + Vite HelloWorld，只演示一次 `ui.showToast()` 调用，并预填 `android`、`ios`、`ohos` 三个平台。Demo 可以整体删除，项目不绑定 Vue、TypeScript 或测试框架。
+
+当前 `0.8` 模板位于 alpha 发布线；稳定版本发布后，本页会将创建命令切回 `@latest`。
+
 已有项目则在项目目录运行 `npm run dev` 或 `hb-sdk dev`。
 
 Agent rules:
@@ -100,15 +105,17 @@ 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;" />
+默认终端只显示启动结果、调试页地址、小程序地址和手机调试入口。排查启动问题时使用 `hb-sdk dev --verbose` 查看完整启动阶段；手机扫码调试凭证连续重试失败时，默认只在失败和恢复两次状态变化时提示。
 
-`hb-sdk dev` 不支持匿名调试。启动前必须先运行 `hb-sdk login`，并通过 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>` 绑定当前项目；未登录、未绑定或远端 Dev Context 不可用时，CLI 会在启动 Vite 和调试服务前终止。
+<img src="/assets/browser-dev-host-workbench.png" alt="小程序工坊 Vue 3 调试台" style="width: 100%; max-width: 1120px;" />
 
-`hb-sdk dev` 会在启动 Vite 前读取远端权限。只有远端权限快照有效且 `network.request.status=enabled` 时才跳过平台 CSP；`useOfficialDomain` 不参与该判定。本地 Dev Context 权限覆盖不会改变 CSP 决策。
+浏览器调试入口不要求 CLI 登录或项目绑定。没有账号、绑定小程序或远端 Dev Context 时，页面和基础 Browser Mock 仍可启动；依赖这些上下文的能力会返回明确失败。远端管理、部署和发布仍要求完成登录与绑定。
 
-当前调试链路不要求升级 Android、iOS 或 Mac 客户端。Browser Mock 会自动在实时与兼容链路间切换；Mobile 使用 `open_inapp`/`openWindow` 包裹的 LAN 短链接二维码（先开普通 H5 跳转页，再进入小程序并关闭中间页）；PC/Mac 行为保持不变。
+`hb-sdk dev` 从项目 `package.json` 读取开发者声明，并在远端权限快照可用时读取平台批准结果。只有当前版本声明且平台已批准 `network` 时才跳过平台 CSP；`useOfficialDomain` 不参与该判定。调试台不提供权限或平台批准修改入口；快照缺失或无效时保留平台 CSP。
+
+Browser Mock 会自动在实时与兼容链路间切换。手机调试使用 `open_inapp`/`openWindow` 包裹的 LAN 短链接二维码（先开普通 H5 跳转页，再进入小程序并关闭中间页）。
 
 ### 2. 先用浏览器 Mock 验收
 
@@ -118,13 +125,15 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 - SDK 初始化与用户身份授权流程
 - 生命周期、Storage 和排行榜等能力
 
-调试页中调整的权限只影响当前本地调试，不会修改线上配置；切换权限后 Mobile App 会重生成二维码。Debug/Ad-Hoc 的本地增强不可用、过期或读取失败时继续使用原生 Host。恢复初始权限后重新按远端配置验收；工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
+调试台提供紧凑的调用日志、当前小程序隔离作用域内的 Storage 只读快照和问题聚合。日志与网络记录只保留脱敏的诊断字段，不展示 payload、结果、查询参数、凭据或原始错误信息。工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
+
+右侧可切换 iPhone 16 Pro Max（`387 x 821`）与 Pixel 9 Pro（`322 x 716`）两个设备预设。尺寸对应固定上游设备外框的真实屏幕 opening；预设同时决定外框、状态栏、安全区和 viewport。切换设备不会重新加载小程序或重启 Runtime，页面状态和调试会话保持不变。授权与操作弹窗、Toast、Loading 和振动反馈均显示在设备预览内部，不会覆盖整个调试台。
 
-### 3. 再用 Mac 或手机真机验收
+### 3. 再用手机真机验收
 
-需要确认真实客户端表现时，可以使用调试页提供的 Mac 启动入口；手机验收则在「Mobile App」区域选择局域网网卡，再用手机小黑盒 APP 扫码。
+需要确认真实客户端表现时，从调试台右上角唯一的二维码入口打开浮层，选择局域网网卡，再用手机小黑盒 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**。发布前至少完成一次真实客户端验收。
+手机与电脑需要处于同一局域网。二维码走 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 +141,16 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 
 ### 常用参数
 
-| 参数                             | 用途                                                          |
-| -------------------------------- | ------------------------------------------------------------- |
-| `--port <port>`                  | 指定页面开发服务端口。                                        |
-| `--browser-dev-host-port <port>` | 指定 Browser Dev Host 端口。                                  |
-| `--no-open`                      | 启动后不自动打开浏览器。                                      |
-| `--verbose`                      | 出现问题时输出更详细的诊断信息。                              |
+| 参数                             | 用途                             |
+| -------------------------------- | -------------------------------- |
+| `--port <port>`                  | 指定页面开发服务端口。           |
+| `--browser-dev-host-port <port>` | 指定浏览器调试页服务端口。       |
+| `--no-open`                      | 启动后不自动打开浏览器。         |
+| `--verbose`                      | 出现问题时输出更详细的诊断信息。 |
 
-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.
 
@@ -153,7 +164,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` 保留类型检查：
 
@@ -268,8 +279,14 @@ 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
+
+## 版本提醒
+
+CLI 会从 npm 的 `latest` 标签检查稳定版更新，发现新版本时在命令结束后输出一行提醒，包含升级命令和目标版本的[更新日志](https://docs.xiaoheihe.cn/hb_sdk/changelog/)链接。提醒最多每 24 小时检查一次，请求超时或网络异常不会影响原命令；CI 环境默认不检查。
+
+需要临时关闭本地检查时，设置 `HB_SDK_NO_UPDATE_CHECK=1`。版本提醒不会读取 Alpha、Beta 或 RC 等预发布标签。

package/skill/references/examples.md

@@ -1,6 +1,6 @@
 # Smoke examples and anti-examples
 
-> 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
 
@@ -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
@@ -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.

package/skill/references/llms-index.md

@@ -1,6 +1,6 @@
 # LLM documentation index
 
-> 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
 

package/skill/references/recipes.md

@@ -1,6 +1,6 @@
 # Recipes
 
-> 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,7 +26,9 @@
 
 # 快速开始
 
-如果页面不需要小黑盒开放能力，可以不接入 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)。
 
 ## 交互控件与握手状态
 
@@ -37,7 +39,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')
@@ -47,9 +49,9 @@ onUnmounted(stopHandshakeState)
 
 把 `sdkReady` 用作按钮的 `disabled` 条件。订阅会立即回放当前状态，因此晚挂载组件也能得到 `ready` 或 `failed` 终态。`ready` 生命周期事件只在握手成功瞬间派发且不会重放，不能作为当前状态来源。
 
-## 未开通网络权限
+## 读取当前用户
 
-无网络小程序可以在本地能力中使用按小程序隔离的 `app_user_id` 和公开资料：
+声明 `userInfo` 后，可以读取按小程序隔离的 `app_user_id` 和已授权资料。该能力不依赖公开 `network` 权限：
 
 ```ts
 import hbSDK from '@heybox/hb-sdk'
@@ -62,9 +64,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()`，不要先等待其他异步任务，以免首次操作丢失可信手势。
 
@@ -93,6 +95,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 起不再对业务代码提供独立实例工厂。
@@ -104,16 +202,17 @@ async function loginFromUserAction() {
 
 `app_user_id` 是平台为“用户 × 当前小程序”生成的稳定、隔离标识，不是黑盒用户 ID。它是不透明字符串，只能在当前小程序内使用，不能解析或跨小程序关联。
 
-用户身份接入取决于小程序是否已开通 `network.request`。两类小程序使用不同的身份入口：
+身份能力与公开 `network` 权限相互独立。根据业务需要选择入口，并在 `package.json#heybox.permissions` 声明对应权限：
 
-| 小程序类型     | 身份入口                  | 结果用途                                               |
-| -------------- | ------------------------- | ------------------------------------------------------ |
-| 已开通网络权限 | `auth.login({ scopes? })` | 获取短期授权码，由开发者服务端换取 OpenAPI token       |
-| 未开通网络权限 | `user.getInfo()`          | 静默读取隔离身份及昵称头像，隐式授予本地用户 scopes    |
+| 身份入口                  | 权限           | 结果用途                                         |
+| ------------------------- | -------------- | ------------------------------------------------ |
+| `auth.login({ scopes? })` | `userInfo`     | 获取短期授权码，由开发者服务端换取 OpenAPI token |
+| `user.getInfo()`          | `userInfo`     | 读取当前用户的隔离身份及已授权资料               |
+| `user.getSteamGameList()` | `steamLibrary` | 读取当前用户的 Steam 游戏库                      |
 
 不要混用两条路径。SDK 不向小程序页面提供 token、cookie、黑盒用户 ID 或平台私有凭据。
 
-## 已开通网络权限
+## 获取服务端授权码
 
 在登录、绑定账号或读取资料等明确的用户操作中调用 `auth.login()`：
 
@@ -167,9 +266,13 @@ async function loginFromUserAction() {
 
 用户已授权所需 scope 时，`auth.login()` 可以不展示 UI，静默返回新的短期授权码。业务仍应把可能出现的授权 UI 设计在明确的用户操作之后，不要在页面初始化阶段自动调用。
 
+`auth.login()` 内部使用 Host 的受信请求，不会调用小程序公开的 `network.request()`，因此不要求声明 `network`。如果页面需要把 code 通过 `network.request()` 发给开发者服务端，则该请求本身仍需声明并获得 `network` 的平台批准。
+
+OpenAPI 凭据、授权码和 access token 的生命周期也不由 `network` 权限开启或关闭。
+
 ## 撤销当前小程序授权
 
-已开通和未开通网络权限的小程序都可以在明确的用户操作中撤销授权：
+任何小程序都可以在明确的用户操作中撤销授权；`user.revokeAuthorization()` 位于无需声明白名单：
 
 ```ts
 async function revokeAuthorizationFromUserAction() {
@@ -183,22 +286,11 @@ async function revokeAuthorizationFromUserAction() {
 
 `user.revokeAuthorization()` 不接收参数。小程序页面不能提交小程序 ID、黑盒用户 ID 或手势标记；Runtime 从 Host 启动上下文和用户操作状态注入可信值。调用缺少可信用户手势时返回 `USER_GESTURE_REQUIRED`。
 
-撤销成功后，后续 `auth.login()` 会重新进入授权流程；无网络小程序再次调用 `user.getInfo()` 时会重新建立隔离身份。业务必须立即停止使用并清理此前保存的 `app_user_id`、用户资料和开发者服务端会话；SDK 不会删除业务自己的 localStorage、数据库或 cookie。
-
-## 当前用户资料由服务端读取
-
-已开通网络权限后，页面不再直接读取 Host 当前用户资料。`@heybox/hb-sdk` 根包实际导出的以下调用统一返回 `SERVER_API_REQUIRED`：
-
-- `user.getInfo()`
-- `user.getSteamGameList(options)`
+撤销成功后，后续 `auth.login()` 会重新进入授权流程；再次调用 `user.getInfo()` 时会按现有用户授权规则读取身份。业务必须立即停止使用并清理此前保存的 `app_user_id`、用户资料和开发者服务端会话；SDK 不会删除业务自己的 localStorage、数据库或 cookie。
 
-其他 Host current-user capabilities 属于 Host/runtime 集成边界，不是小程序可从 SDK 根包调用的方法。需要对应数据时，先取得授权码，再由开发者服务端按后端 OpenAPI 文档换取 token 并调用对应接口。不要把 `SERVER_API_REQUIRED` 当作未登录或权限弹窗失败。
+## 读取当前用户资料
 
-`user.revokeAuthorization()` 是例外：它是授权变更操作，在两种网络模式下都可用，但始终要求可信用户手势。
-
-## 未开通网络权限
-
-未开通网络权限的小程序不走授权码流程。需要当前用户在本小程序内的稳定隔离身份和公开资料时调用：
+需要当前用户在本小程序内的稳定隔离身份和已授权资料时调用：
 
 ```ts
 import hbSDK from '@heybox/hb-sdk'
@@ -209,14 +301,16 @@ async function getCurrentUser() {
 }
 ```
 
-`user.getInfo()` 是静默本地用户接口，不展示授权弹窗，也不要求可信用户手势。未登录时返回 `isHeyboxAppLoggedIn: false`；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），建立并返回当前小程序隔离的 `app_user_id`、`profile.nickname` 和 `profile.avatar`。每次成功调用都会广播一次 `user_info_authorization_change`，其中 `identity` 与 `profile` 均为 `granted`，即使授权状态没有发生变化。撤销授权后再次调用仍会静默建立新的隔离身份并恢复无网络模式的隐式授权。
+`user.getInfo()` 不依赖 `network`，但必须声明 `userInfo`。它延续现有交互：不展示授权弹窗，也不要求可信用户手势。未登录时返回 `isHeyboxAppLoggedIn: false`；已登录时按现有用户授权状态返回当前小程序隔离的 `app_user_id`，以及已授权的 `profile.nickname` 和 `profile.avatar` 等可用资料。用户授权与开发者权限声明是两层独立门禁，不能用声明代替用户同意。
 
-这类小程序无法获取授权码，也无法调用 OpenAPI；在未开通网络权限时调用 `auth.login()` 同样返回 `SERVER_API_REQUIRED`。隐式 full-scope 仅适用于 Host 本地用户资料能力，不代表开放网络或服务端凭据；页面不能把其中的身份或资料发送到外部服务。
+Steam 游戏库使用 `user.getSteamGameList(options)`，要求声明 `steamLibrary`，同样不依赖 `network`。Host current-user capabilities 的既有账号绑定和数据可用性规则保持不变。
 
 ## 网络请求边界
 
 `network.request()` 只用于访问开发者自己的业务服务。平台保留的 runtime auth 与 OpenAPI 内部路径不能通过该能力访问；身份交换必须由开发者服务端按公开后端文档完成。
 
+完整权限配置与错误区别见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
+
 ## CLI 登录与用户登录
 
 `hb-sdk login` 只给本地开发和远端管理命令建立 CLI 登录态，与小程序页面的 `auth.login()`、`user.getInfo()` 和用户授权完全无关。
@@ -274,7 +368,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 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
@@ -313,9 +407,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` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -364,12 +464,16 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 
 授权码在取得后立即交给开发者服务端交换，不要写入页面状态、DOM、日志或持久化存储。UI 只处理服务端会话是否建立成功。
 
+文件与下载仍使用 `HbMiniProgramSDKError`，不会新增第三种错误类。业务根据 `error.code` 处理
+picker 取消、授权撤销、文件缺失、quota、下载状态或取消，不依赖 `message` 文案，也不要记录
+真实路径、内部 handle 或响应凭据头。
+
 ## Login gate recipe
 
 
 # 服务端登录门禁
 
-已开通网络权限的小程序可以把“取得授权码并交给开发者服务端”收敛成一个用户操作函数：
+声明 `userInfo` 后，小程序可以把“取得授权码并交给开发者服务端”收敛成一个用户操作函数。`auth.login()` 本身不依赖 `network`；以下示例使用 `network.request()` 传递 code，因此还需声明并获得 `network` 的平台批准：
 
 示例中的 URL 是开发者自己的后端接口，不是黑盒 OpenAPI 地址。
 
@@ -419,7 +523,7 @@ async function handleSubmit() {
 
 ## 普通分享
 
-普通分享只支持一个默认分区，并且配置 `post` 时不要同时指定站外 `channel`。
+普通分享的落地页固定为当前小程序的 `common_share`，不接受自定义 `url`。普通分享只支持一个默认分区，并且配置 `post` 时不要同时指定站外 `channel`。
 
 ```ts
 import { share } from '@heybox/hb-sdk'
@@ -451,7 +555,7 @@ await share.screenshot({
 
 ## 恢复分享页面状态
 
-使用默认通用分享链接时，可以通过 `extra` 携带由小程序自行定义的页面状态。分享方只负责写入状态，接收方负责决定如何使用：
+通过固定通用分享链接分享时，可以使用 `extra` 携带由小程序自行定义的页面状态。分享方只负责写入状态，接收方负责决定如何使用：
 
 ```ts
 await share.showShareMenu({
@@ -484,7 +588,7 @@ if (sharedState && typeof sharedState === 'object' && !Array.isArray(sharedState
 }
 ```
 
-`getExtra()` 不依赖异步请求；没有有效数据时返回 `undefined`，业务应回退到默认首页。`extra` 只支持 JSON-compatible 数据，最多 8 层，单个数组或对象最多 64 项，内容不超过 128 字节；不能与自定义 `url` 同时使用，也不要存放 token、个人信息等敏感数据。`copyLink()` 不会继承当前启动链接中的 `extra`，只携带本次显式传入的数据。
+`getExtra()` 不依赖异步请求；没有有效数据时返回 `undefined`，业务应回退到默认首页。`extra` 只支持 JSON-compatible 数据，最多 8 层，单个数组或对象最多 64 项，内容不超过 128 字节，也不要存放 token、个人信息等敏感数据。`copyLink()` 不会继承当前启动链接中的 `extra`，只携带本次显式传入的数据。
 
 ## 参数边界
 
@@ -507,7 +611,6 @@ if (sharedState && typeof sharedState === 'object' && !Array.isArray(sharedState
 
 ```ts
 import hbSDK from '@heybox/hb-sdk'
-
 ```
 
 ## 测试环境注入 window

package/skill/references/safety-boundaries.md

@@ -1,6 +1,6 @@
 # Safety boundaries
 
-> 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
 
@@ -15,15 +15,24 @@
 - `ready` 生命周期事件是不可重放的边沿通知，不代表可查询状态，也不能替代握手状态 API。
 - `auth.login({ scopes? })` 只返回 `{ code, expiresIn: 300, scopes }`；identity 隐式强制包含，code 只能提交给开发者服务端。
 - 需要授权 UI 时，`auth.login()` 必须来自可信用户手势，否则返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`。已授权时可以静默返回新 code。
-- `user.getSteamGameList()` 仅供未开通网络权限的小程序通过 Host 读取；已开通网络权限时返回 `SERVER_API_REQUIRED`，且授权码与 OpenAPI 不提供 Steam 游戏库 scope 或资源接口。
-- 已开通网络权限时，公开的 `user.getInfo()` 返回 `SERVER_API_REQUIRED`；对应身份和资料数据应由开发者服务端通过 OpenAPI 获取。
-- 未开通网络权限时，`user.getInfo()` 隐式授予 `identity` 与 `profile`，静默返回 `userInfo.app_user_id`、昵称和头像；这条路径仍不能获取 code 或调用 OpenAPI。
+- `auth.login()`、`user.getInfo()` 和 `user.getSteamGameList()` 的可用性不由 `network` 决定；它们分别要求 `userInfo` 或 `steamLibrary`，并继续遵循各自的用户授权和数据规则。
 - `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`，文件上传请走专用上传能力。
-- 仅当远端已启用 `network.request` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
+- 当前 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` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
 - 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
 ## Agent rules

package/skill/skill.json

@@ -1,11 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.0-alpha+skill.e73cb0ba5184",
+  "skillVersion": "0.8.0-alpha.10+skill.4d468f0653d9",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0-alpha",
-    "compatibility": "0.8.0-alpha"
+    "version": "0.8.0-alpha.10",
+    "compatibility": "0.8.0-alpha.10"
   },
-  "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-e73cb0ba518459e1b262d09fb0ead87a7163c8e5358430184a9dd4f085049357"
+  "distribution": {
+    "type": "npm",
+    "package": "@heybox/hb-sdk",
+    "version": "0.8.0-alpha.10",
+    "path": "skill"
+  },
+  "integrity": "sha256-4d468f0653d9f6eac9578d47d85b955c01e84dd38b91d123a2b832e60f50b34c"
 }

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;