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

package/CHANGELOG.md

@@ -1,11 +1,50 @@
 # Changelog
 
-## 0.8.0-alpha
+## 0.8.0-alpha.3
+
+### SDK / Agent Skill
+
+- Agent Skill 合并至 `@heybox/hb-sdk` npm 包，使用 `hb-sdk skill install`（项目）或 `hb-sdk skill install --global`（用户级）安装。
+- 要求 Node.js `>=22.20.0`；安装会校验项目 SDK 版本并维护 `skills-lock.json`，内容被修改时需使用 `--force` 覆盖。
+- `hb-sdk doctor` 改为本地多 Agent 诊断并支持 `--json`；Open 站点仅保留旧版只读兼容快照，不再持续发布。
+
+## 0.8.0-alpha.2
+
+### SDK
+
+- 新增公开 `files` 模块，定义私有 sandbox、外部 File/Directory picker、UTF-8/Uint8Array 读写、stat 和有界目录列表。
+- `FileHandle` / `DirectoryHandle` 新增 sandbox-only 删除能力；外部 picker/saveFile 及派生授权不允许删除，目录递归删除必须显式开启。
+- 新增 `network.download()`，将 GET 响应流式写入受控 File/Directory target，并提供 AbortSignal 与 request-scoped progress。
+
+### Runtime / Host
+
+- 扩展零依赖 protocol wire、Host filesystem/picker/transfer contract 和稳定文件/下载错误码；当前 Host 均对 files/download fail closed。
+- Host 文件错误统一重建为 canonical code/message，不向 iframe 透传原始 data；每个 Runtime session 的外部 direct handle 上限为 1024，批量超限原子失败。
+- 下载 transfer 以 `writeResource()` resolve 为不可逆提交点并返回 `committedBytes`；取消只在提交前获胜，未消费 resource 的异步清理不阻塞既定终态。
+- 移除原计划面向旧版小黑盒 PC 的 files/download HostBridge 适配；文件/下载体系保持不变，后续直接按新版 PC Host 架构接入。
+- Runtime request/transport 贯通 `withCredentials`、`redirectPolicy` 与 `maxResponseBytes` 的显式覆盖；Mobile Host buffered request 固定 32 MiB 上限并统一 no-follow，凭据选项不改变平台请求路由。
+
+### Docs / Agent Skill
+
+- 将 files/download 的 6 个 canonical callable 纳入 API Reference、兼容性矩阵、LLM 文本与 Agent Skill。
+
+## 0.8.0-alpha.1
 
 ### Breaking Changes
 
 - `miniappManifest({ platforms })` 要求新构建的本地小程序产物显式声明目标平台；通过 `--from-version` 复用的历史产物允许缺失并保持“平台声明未分类”。
 
+### CLI / Browser Dev Host
+
+- Browser Dev Host 硬切为 Vue 3 小程序调试台，复用小黑盒主题与组件；集中展示调用日志、当前小程序 Storage 快照和问题，并提供匹配手机外框的 iPhone、Pixel 屏幕预设与单一真机二维码入口。
+- 浏览器调试不再被 CLI 登录、项目绑定或远端 Dev Context 阻断；移除调试页权限修改和 Mac 启动入口，依赖账号或远端配置的能力改为按当前上下文明确返回结果或失败。
+- 授权、操作弹窗、Toast、Loading 与振动反馈统一限制在设备预览内；`navigation.reload` 在响应投递后只重建预览 iframe，保留整个调试台会话和诊断状态。
+
+### Runtime
+
+- Host 可显式订阅脱敏 capability 完成记录，并通过只读 diagnostics 获取 canonical 小程序作用域的 Storage 快照；不向 iframe 暴露诊断能力或其他小程序数据。
+- 新增 response 成功投递后的脱敏 `bridge_response` trace，供 Host 确定性编排刷新等后续行为，不暴露 request id、payload 或 result。
+
 ### SDK
 
 - 公开运行时 API 使用严格 TSDoc 记录加入版本、支持平台、最低客户端版本、稳定性和废弃信息。
@@ -16,6 +55,10 @@
 - 新项目模板显式预填 `android`、`ios`、`ohos` 三个平台；该初始值不是 Runtime fallback 或真机验收证明。
 - canonical Docs 增加独立阻断 CI 门禁，校验 TSDoc、Manifest、API 图、生成物 freshness、链接和桌面/移动端阅读体验。
 
+### Tooling
+
+- 补齐 Browser Dev Host Vue 类型检查、资源完整性与第三方声明校验。
+
 ## 0.7.6-alpha.0
 
 ### Runtime

package/README.md

@@ -2,6 +2,8 @@
 
 小黑盒 APP 小程序工坊的前端 SDK 与开发 CLI，用于创建、调试、构建和发布工坊小程序，并在业务页面中调用小黑盒开放能力。
 
+运行环境要求 Node.js `>=22.20.0`。`@heybox/hb-sdk` npm 包同时包含与当前 SDK 版本严格对应的 Agent Skill；Skill 不再依赖 Open 远端分发。
+
 SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部协议、登录凭据或私有实现入口。本地浏览器调试请使用 `hb-sdk dev` 提供的 Mock 环境，发布前仍需在小黑盒 APP 中完成真机验收。
 
 宿主集成边界：`@heybox/hb-sdk-runtime` 运行在 iframe 外并负责 bridge/Host Port；跨 iframe 的 wire contract 唯一维护在零依赖 `@heybox/hb-sdk-protocol`。业务页面不需要创建 Runtime、实现 Host Port 或导入协议包；客户端 SDK 只依赖已兼容 re-export 的 `@heybox/hb-sdk/protocol`。
@@ -17,7 +19,7 @@ npm install
 npm run dev
 ```
 
-脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试页进入 Mac 或手机端验收。
+脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试台的二维码入口使用手机小黑盒 APP 验收。
 
 ### 接入已有项目
 
@@ -25,6 +27,24 @@ npm run dev
 npm install @heybox/hb-sdk
 ```
 
+### 安装 Agent Skill
+
+在项目目录安装到项目 Agent 目录：
+
+```bash
+hb-sdk skill install
+```
+
+安装到当前用户目录，或指定 Agent：
+
+```bash
+hb-sdk skill install --global
+hb-sdk skill install --agent codex cursor
+hb-sdk skill install --all-agents
+```
+
+使用 `hb-sdk doctor` 或 `hb-sdk doctor --json` 检查各 Agent 的 Skill 是否与当前 npm 包匹配；已有内容被修改时，使用 `--force` 才会覆盖。
+
 SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。未开通网络权限的小程序通过 `user.getInfo()` 静默读取当前小程序内的隔离身份和公开资料：
 
 需要可信用户手势的按钮不能在点击回调里等待握手。页面加载时先用 `getHandshakeState()` 读取当前状态，再用 `onHandshakeStateChange()` 订阅并立即接收当前状态；仅在 `status === 'ready'` 时启用按钮，并在组件或页面销毁时调用订阅返回的取消函数。`ready` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
@@ -84,6 +104,45 @@ export default defineConfig({
 
 完整接入步骤见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start)。
 
+## 文件与下载
+
+`files` 提供当前小程序私有 sandbox 和由用户选择授予的外部 File/Directory；
+`network.download()` 将 GET 响应直接流式写入受控目标，下载字节不经过 iframe bridge。
+
+```ts
+const exportDirectory = hbSDK.files.sandbox.directory('exports');
+await exportDirectory.create({ recursive: true });
+
+const staleFile = exportDirectory.file('stale.json');
+if (await staleFile.exists()) await staleFile.remove();
+
+const controller = new AbortController();
+const downloaded = 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(progress) {
+    console.log(progress.loaded, progress.total, progress.lengthComputable);
+  },
+});
+
+console.log(await downloaded.readText());
+```
+
+本次保留 `files`、`network.download()`、协议 wire 和 Runtime Host Port 体系，但暂不在现有 Host
+开放。此前的实现用于适配旧版小黑盒 PC；由于新版 PC 即将启用，这套旧版适配不再发布，后续会
+直接按照新版 PC 的 Host 架构接入。当前 Host 调用这些 method 时返回 `METHOD_FORBIDDEN`；旧
+Runtime 不认识新 method 时返回 `METHOD_NOT_FOUND`，且不提供 Blob 或内存假实现。
+
+外部 picker 必须从可信用户操作触发。`files.saveFile({ suggestedName })` 会打开系统保存对话框并返回
+精确 File 授权，不会额外保留 Directory 授权；V1 不接受 `accept`。只有 `pickFiles()` 支持扩展名过滤。完整路径、创建、存在性和
+下载语义见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start#文件与下载)。
+
+`remove()` 只允许删除 sandbox 对象；外部 picker、`saveFile()` 及其派生项即使是 `readwrite` 也返回 `FILE_ACCESS_DENIED`。单个 Runtime session 最多保留 1024 个外部 direct handle，超限返回 `FILE_QUOTA_EXCEEDED`。Host 文件错误只向 SDK 暴露稳定 code 与 canonical 安全文案，业务不要依赖平台原始 message 或附加 data。
+
 ## 错误处理
 
 握手失败会保留在持久状态中，可在订阅回放时直接处理原始错误：
@@ -106,18 +165,19 @@ window.addEventListener('unload', stopHandshakeState, { once: true });
 
 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/)。
 
@@ -134,8 +194,19 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- 公开 `network.request()` 与 `network.download()` 均使用 no-follow redirect policy；3xx 不会在 Host 内静默跳转。
 - `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
+- 当前 Host（包括旧版 PC、Mobile、Web 与 Browser Dev Host）均未开放 `files` / `network.download()`；新版 PC 将按同一公开合同重新接入，期间不提供内存或 Blob 假实现。
+- picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`。
+- `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
+- `file()` / `directory()` 只接受以 `/` 分隔的规范相对路径；拒绝绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符和控制字符。
+- `create()` 的 `recursive` / `exclusive` 默认都是 `false`；`exists()` 仅把缺失祖先、缺失目标或 kind mismatch 归一为 `false`，不会吞授权和 I/O 错误。
+- `remove()` 只允许删除 sandbox 对象；外部 picker/saveFile 授权返回 `FILE_ACCESS_DENIED`。非空目录默认返回 `DIRECTORY_NOT_EMPTY`，需显式调用 `remove({ recursive: true })`。
+- `directory.list()` 默认最多返回 1000 项，`limit` 也不能超过 1000；超限返回 `DIRECTORY_LIST_LIMIT_EXCEEDED`。
+- 单个 Runtime session 最多保留 1024 个 picker/saveFile direct handle；整批授权超限时返回 `FILE_QUOTA_EXCEEDED`，不会保留部分结果。
+- Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
+- `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
 - 仅当远端已启用 `network.request` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
 - 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
@@ -199,7 +270,9 @@ hb-sdk remote deploy --release-note "本次更新说明"
 | `hb-sdk build`         | 执行生产构建与产物校验，不包含类型检查 |
 | `hb-sdk remote deploy` | 构建、上传并提交当前版本审核           |
 
-`hb-sdk dev` 不要求升级 Android、iOS 或 Mac 客户端。启动前必须先运行 `hb-sdk login` 并通过 `hb-sdk remote create` 或 `hb-sdk remote bind` 绑定小程序；未登录、未绑定或远端 Dev Context 不可用时不会启动 Vite、Browser Dev Host、Mac 或 Mobile 调试入口。Browser Mock 会自动在实时与兼容链路间切换；Mobile 统一使用 `open_inapp` 与 `heybox://` `openWindow` 包装的局域网短链 `http://<lan-ip>:<browser-dev-host-port>/l/<token>`。短链返回跳转页，先打开带 `heybox-mini-dev://sandbox`、`mini_url`、身份、启动票和 LAN Dev Context 的完整协议，约 500ms 后再发 `closeWindow` 关掉中间页。调试页权限覆盖只影响本地状态，不会修改线上配置。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
+`hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示调用日志、当前小程序作用域内的 Storage 快照和问题，右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
+
+浏览器调试入口不要求 CLI 登录或项目绑定；需要账号或远端配置的能力会按当前可用上下文返回结果或明确失败。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
 
 远端提交前需要完成 CLI 登录和小程序绑定。完整的登录、绑定、预览、版本与发布流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。