@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/skill/references/api-root.md

@@ -28,7 +28,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.1`
+- Version at generation time: `0.8.2-alpha.2`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -265,43 +265,90 @@ export default hbSDK;
 
 Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe mini-program business code.
 
-```ts
+````ts
+/**
+ * {@link miniappManifest} 返回的 Vite 插件契约。
+ *
+ * @remarks
+ * 业务项目只需把 `miniappManifest()` 放入 `vite.config.ts` 的 `plugins` 数组，通常不需要直接构造该接口，
+ * 也不应手动调用这些 Vite hook。该接口不包含小程序声明；目标平台、权限、窗口、游戏绑定和 Companion
+ * 等配置统一来自距离 Vite `root` 最近的 `package.json#heybox`。
+ */
 export interface MiniappManifestPlugin {
+    /** 固定为 `heybox-miniapp-manifest`，同一份 Vite 配置必须且只能注册一个实例。 */
     name: string;
+    /** 校验资源基准路径，并向 Vite 注入 SDK 版本和开发期日志开关。 */
     config: (config: MiniappManifestUserConfig, env?: {
         command: 'build' | 'serve';
     }) => MiniappManifestUserConfig | void;
+    /** 记录 Vite 根目录、输出目录、运行命令和开发期 HMR 地址。 */
     configResolved: (resolved: MiniappManifestResolvedConfig) => void;
+    /** 为 `hb-sdk dev` 注册本机调试能力；生产构建不会创建开发服务。 */
     configureServer: (server: MiniappManifestDevServer) => void;
-    /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
+    /** 保留 Rollup/Vite 已报告的构建错误，避免产物校验用二次错误掩盖原始原因。 */
     buildEnd: (error?: Error) => void;
+    /** 向入口 HTML 注入 Runtime Gate 和平台 CSP；serve 时还会加入受限的 HMR 与日志调试支持。 */
     transformIndexHtml: (html: string) => string;
+    /** serve 关闭时直接完成；生产构建结束时校验单页产物并写入 Manifest 和 Companion 归档。 */
     closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
 }
 
+/**
+ * {@link MiniappManifestPlugin.configureServer} 消费的最小 Vite 开发服务形状。
+ *
+ * @remarks
+ * 这是插件返回值暴露的 hook 类型，不是 `miniappManifest()` 的配置项。业务项目应让 Vite 创建并传入服务实例。
+ */
 export interface MiniappManifestDevServer {
+    /** Vite 底层 HTTP 服务；middleware mode 或尚未监听时可能为空。 */
     httpServer?: Server | null;
+    /** Vite 配置重载入口；插件会在重载期间保留当前本地调试快照。 */
     restart?: (forceOptimize?: boolean) => Promise<void>;
+    /** 用于挂载 `hb-sdk dev` 本机调试中间件的 Connect middleware 容器。 */
     middlewares: {
         use: (handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void) => void;
     };
 }
 
+/**
+ * {@link MiniappManifestPlugin.config} 读取和返回的最小 Vite 用户配置形状。
+ *
+ * @remarks
+ * 该接口描述 Vite hook 数据，不是插件 options；`miniappManifest()` 必须无参调用。小程序声明请写入
+ * `package.json#heybox`，不要写入 Vite 配置。
+ */
 export interface MiniappManifestUserConfig {
+    /**
+     * Vite 资源基准路径。省略时插件返回 `./`；显式配置只接受空字符串或 `./`，以便版本目录内相对加载资源。
+     */
     base?: string;
+    /** 插件返回给 Vite 的编译期常量；业务项目无需通过该接口传入或覆盖。 */
     define?: Record<string, string>;
 }
 
+/** {@link MiniappManifestPlugin.closeBundle} 使用的最小 Rollup 插件上下文。 */
 export interface MiniappManifestPluginContext {
+    /** 输出缺少迁移期声明等非阻断构建警告。 */
     warn: (message: string) => void;
 }
 
+/**
+ * {@link MiniappManifestPlugin.configResolved} 消费的最小 Vite 已解析配置形状。
+ *
+ * @remarks
+ * 这是 Vite 传给插件的 hook 数据，不是应用作者需要创建的 options。插件从中确定项目根目录、输出目录、
+ * serve/build 分支和 HMR WebSocket 白名单。
+ */
 export interface MiniappManifestResolvedConfig {
+    /** Vite 项目根目录；小程序配置从该目录向上找到的最近 `package.json` 读取。 */
     root: string;
+    /** `serve` 只准备本地调试，`build` 还会校验产物并生成 `manifest.json`。 */
     command: 'build' | 'serve';
+    /** Vite 构建输出目录；Manifest 和 Companion 归档写入该目录。 */
     build: {
         outDir: string;
     };
+    /** 开发服务网络配置，用于收窄注入 HTML 的 HMR WebSocket CSP。 */
     server: {
         host?: string | boolean;
         https?: boolean | Record<string, unknown>;
@@ -313,13 +360,112 @@ export interface MiniappManifestResolvedConfig {
             protocol?: 'ws' | 'wss';
         };
     };
+    /** 已解析插件列表；存在时用于拒绝重复注册 `miniappManifest()`。 */
     plugins?: readonly {
         name?: string;
     }[];
 }
 
+/**
+ * 创建工坊小程序使用的 Vite 插件。
+ *
+ * @returns 可直接加入 Vite `plugins` 数组的
+ * [MiniappManifestPlugin](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/interfaces/MiniappManifestPlugin)。插件固定名为
+ * `heybox-miniapp-manifest`，并提供 `config`、`configResolved`、`configureServer`、`buildEnd`、
+ * `transformIndexHtml`、`closeBundle` hooks；这些 hooks 由 Vite 调用，应用代码不应手动调用。
+ * @throws `Error` `config` 阶段发现 Vite `base` 不是 `''` 或 `'./'`，或无法解析当前 SDK 版本时抛出。
+ * @throws `Error` `configResolved` 阶段发现已解析插件列表中 `miniappManifest()` 数量不是一个时抛出。
+ * @throws `Error` HTML 缺少 `<head>`，包含 `meta refresh`、`<base>`、禁止的 resource hint，或资源 URL
+ * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
+ * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
+ * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
+ * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
+ *
+ * @remarks
+ * 该函数必须从 `@heybox/hb-sdk/vite` 导入，在 `vite.config.ts` 中无参调用且只注册一次；它不是
+ * iframe 业务代码 API，也没有 options 对象。小程序声明统一来自从 Vite `root` 向上找到的最近一个
+ * `package.json`，插件只读取和规范化，不会改写源文件：
+ *
+ * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
+ *   `0.0.0`；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
+ *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
+ * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
+ * - `heybox.bindAppIds`：可选的最多 20 个正 int32 字符串 App ID；校验、去重并按数值排序，空数组
+ *   在本地产物中等同不写；
+ * - `heybox.companions`：可选的受管桌面程序声明；`source` 相对上述 `package.json` 所在目录解析，
+ *   必须同时声明启用的 `companion` 权限和匹配的 Windows/macOS 目标平台。
+ *
+ * 产物中的 `sdkVersion` 来自当前实际安装的 `@heybox/hb-sdk`，不是项目可配置字段。Vite options、页面
+ * 代码和普通环境变量不能覆盖上述 package 声明；插件也不会联网确认 App ID、平台批准或远端版本状态。
+ *
+ * Hook 行为如下：
+ *
+ * - `config`：省略 `base` 时补为 `'./'`，显式值只接受 `''` / `'./'`；注入 SDK 构建版本，且仅
+ *   `vite serve` 注入开发日志编译常量；
+ * - `configResolved`：确认插件唯一性，记录真实 `root`、`build.outDir`、`serve|build` 命令和精确 HMR
+ *   WebSocket 地址；直接 `vite build` 使用该实际 `outDir`，`hb-sdk build` 则由 CLI 固定为 `dist/`；
+ * - `configureServer`：为 `hb-sdk dev` 注册设备日志、本地小程序 Manifest 与 Companion Manifest/ZIP
+ *   中间件；敏感路由只接受数值 loopback socket/Host、`GET|HEAD` 和 CLI 注入的独立短期令牌，快照在
+ *   配置重载时按 digest 保留，并在服务真正关闭时清理；
+ * - `transformIndexHtml`：校验 HTML URL/标签策略，注入 Runtime Gate；默认注入平台 CSP，serve 时
+ *   `connect-src` 只开放解析出的 HMR WebSocket，并额外注入调试日志 bootstrap；
+ * - `buildEnd`：记住更早的 Rollup/Vite 错误，避免 `closeBundle` 的二次产物错误遮盖根因；
+ * - `closeBundle`：serve 时直接完成；build 时复检最终 HTML，要求整个输出树只有根 `index.html`，再于
+ *   `build.outDir` 写入 `manifest.json`，并把 Companion 目录打包成
+ *   `companions/<alias>/<target>.zip`，记录 size、SHA-256、固定入口与 args。
+ *
+ * HTML 策略会隔离业务 script/modulepreload，直到父 Runtime Gate 以 namespace、版本、nonce、source
+ * 以及 referrer 可确定时的 origin 完成探测；失败时显示只能在小黑盒 App 内打开的安全页。策略拒绝自动跳转、`<base>`、危险
+ * resource hints 和不受支持的外部 URL，并按标签只允许相对 URL、明确允许的 `data:` / `blob:` 或
+ * 小黑盒官方 HTTPS 资源。开发者自行提供的 CSP 会保留；插件管理的 CSP marker 可重复转换而不会叠加。
+ *
+ * 平台 CSP 默认始终保留，直接 `vite build` / `hb-sdk build` 不会因项目声明
+ * `heybox.permissions.network.useOfficialDomain` 而跳过。只有官方 `hb-sdk dev` 或
+ * `hb-sdk remote deploy` 将当前版本的 `network` 声明与远端批准结果求交并确认最终启用后，才会
+ * 建立 verified 上下文供插件读取内部
+ * `HB_SDK_RUNTIME_PERMISSION_CONTEXT` + `HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN` 组合跳过平台 CSP；单独设置
+ * 任一值无效。0.8 兼容期对完全缺失权限声明的项目仍按迁移规则处理；`useOfficialDomain` 不参与
+ * CSP 跳过决定。Runtime Gate、HTML 校验和 Manifest 生成始终保留。
+ *
+ * `HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN`、`HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN`、
+ * `HB_SDK_SKIP_COMPANIONS` 以及上述 CSP 上下文均是 CLI/发布链路内部开关，不是项目配置项。它们在
+ * 插件创建时捕获；开发服务配置重载只会从同一服务的内存快照恢复 CLI 令牌。业务代码和 Vite 配置
+ * 不应手工设置、读取、记录或转发令牌值。正式声明必须继续写在 `package.json#heybox`，内部环境变量
+ * 不能替代声明校验。
+ *
+ * `manifest.json` 是 release pipeline 元数据，不是部署后供页面 fetch 的 CDN 资源。发布链路使用
+ * [isValidVersion](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion) 复核版本、
+ * [resolveMiniappManifestPlatforms](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/resolveMiniappManifestPlatforms)
+ * 解析平台硬切规则、
+ * [parseMiniappBindAppIds](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/parseMiniappBindAppIds) 复核游戏绑定，
+ * 并通过 [shouldUploadDistFile](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 将根
+ * `manifest.json` 排除出普通 CDN 文件。Web/Companion 上传预算由
+ * [validateUploadTotalSize](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/validateUploadTotalSize) 等发布 helper
+ * 独立校验，不能用插件成功代替 deploy 预检。
+ *
+ * @example
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * import { miniappManifest } from '@heybox/hb-sdk/vite'
+ * import { defineConfig } from 'vite'
+ *
+ * export default defineConfig({
+ *   // base 省略时 miniappManifest() 会补为 './'
+ *   plugins: [vue(), miniappManifest()],
+ * })
+ * ```
+ *
+ * @see [MiniappManifestPlugin](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/interfaces/MiniappManifestPlugin) 返回插件及各 hook 类型。
+ * @see [安装](https://docs.xiaoheihe.cn/hb_sdk/guide/installation) Vite 接入、相对资源路径和构建命令。
+ * @see [权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions) `heybox.permissions` 严格 schema 与迁移规则。
+ * @see [窗口尺寸与可缩放性](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size) `heybox.window` 字段与 Host 消费语义。
+ * @see [受管桌面程序](https://docs.xiaoheihe.cn/hb_sdk/guide/companion) Companion 声明、归档和本地联调边界。
+ */
 export declare function miniappManifest(): MiniappManifestPlugin;
-```
+````
 
 ## 生产构建
 
@@ -461,11 +607,11 @@ async function getCurrentUser() {
 }
 ```
 
-`user.getInfo()` 不展示授权弹窗，也不要求可信用户手势。未登录时返回未登录状态；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），静默返回 `userInfo.app_user_id`、`profile.nickname` 和 `profile.avatar`。这条路径不能获取授权码或调用 OpenAPI，也不能把身份或资料发送到外部服务。
+`user.getInfo()` 不展示授权弹窗，也不要求可信用户手势。未登录时返回未登录状态；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），静默返回 `userInfo.app_user_id`、`profile.nickname` 和 `profile.avatar`。平台为当前版本启用 Steam 账号能力且小程序未开通网络权限时，还会授予 `steam_account`，已绑定用户返回可选 `userInfo.steam_id`。这条路径不能获取授权码或调用 OpenAPI，也不能把身份或资料发送到外部服务。
 
 ## 获取服务端授权码
 
-声明 `userInfo` 后，可通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作。该调用内部使用 Host 受信请求，不依赖公开 `network` 权限；示例中的 `network.request()` 另需声明并获得 `network` 平台批准。
+声明 `userInfo` 后，可通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作。平台为当前版本启用 Steam 账号能力后，联网小程序可在 `scopes` 中按需加入 `steam_account`，并由开发者服务端通过 OpenAPI 读取 `steam_id`。该调用内部使用 Host 受信请求，不依赖公开 `network` 权限；示例中的 `network.request()` 另需声明并获得 `network` 平台批准。
 
 SDK 会自动完成握手。登录按钮应按上面的持久握手状态启用；点击回调直接调用 `auth.login()`，不要先等待其他异步任务，以免首次操作丢失可信手势。
 
@@ -719,9 +865,25 @@ try {
 }
 ```
 
+## 错误边界
+
+| 结果                                    | 表示什么                                                            | 常见处理                                            |
+| --------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------- |
+| `HbMiniProgramSDKError`                 | 握手、参数、权限、Host 能力或模块操作失败                           | 按稳定 `code` 分支，`message` 仅用于开发者提示      |
+| `HbMiniProgramNetworkError`             | `network.request()` 已获得 HTTP 响应，但状态未通过 `validateStatus` | 读取 `status`、`data` 和安全响应头                  |
+| `undefined` / `deleted: false` 等空结果 | API 明确定义的正常结果，例如排行榜中没有当前用户记录                | 正常渲染空态，不进入错误上报                        |
+| 其他异常                                | 业务回调、页面代码或非 SDK 依赖抛出的错误                           | 不要伪装成 SDK 错误；保留原异常继续交给统一错误边界 |
+
+`HbMiniProgramNetworkError` 不是“所有网络失败”的父类：只有已形成标准 HTTP 响应且状态校验失败时才使用它。
+握手、bridge、Host transport 或权限失败仍属于 `HbMiniProgramSDKError`。业务不应通过 `status === 0` 猜测网络错误。
+
+`HbMiniProgramSDKError.data` 是按错误码提供的可选诊断信息，不保证所有 Host 版本结构一致。读取前应做类型收窄，
+日志上报也必须先移除 token、授权码、文件路径、请求正文和用户隐私数据。
+
 ## 处理原则
 
 - 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
+- 对未知 `code` 使用通用失败 UI 并保留诊断信息；不要用穷举 `switch` 的 `default` 自动重试。
 - 权限失败时给出可理解的提示，不要将它当成未登录。
 - `PERMISSION_NOT_DECLARED` 表示当前版本没有在 `package.json#heybox.permissions` 声明所需权限，应修改项目配置并重新构建、提交版本。
 - `PERMISSION_DENIED` 表示权限已声明，但需要的平台批准缺失或批准配置不足。首期只有 `network` 需要平台批准。
@@ -733,7 +895,10 @@ try {
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
 - `COMPANION_NOT_PREPARED` 表示启动前尚未显式准备；应由新的用户操作调用 `companion.prepare()`，不要在 `launch()` 中自动重试。
+- `COMPANION_PREPARATION_CANCELLED` 表示取消意图已结束当前观察；原子提交可能已完成，应重新查询准备状态再更新 UI。
 - `COMPANION_SESSION_OWNERSHIP_LOST` 表示 Session controller 已由新的 Runtime generation 接管；停止旧 controller 写入，需要继续取得控制权时重新取得活动 Session。
+- `COMPANION_SESSION_EXITED` / `COMPANION_PIPE_CLOSED` 表示当前 Session 或 stdin 已进入终态；不要对同一 controller 重放写入。
+- `COMPANION_PROCESS_CRASHED` / `COMPANION_OUTPUT_LIMIT` 表示进程异常退出或输出越界；先展示退出状态并保存诊断，再由新的用户操作决定是否重启。
 - `COMPANION_DESCRIPTOR_UNAVAILABLE` 表示授权或描述符暂时不可用，Runtime 会保留 `retryable: true`。
 - `COMPANION_INTEGRITY_FAILED`、`COMPANION_ARCHIVE_INVALID` 或操作系统拦截都不能绕过；停止重试并修正归档后提交新审核版本。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
@@ -966,12 +1131,30 @@ Host 可信授权；已 ready 或加入同一在途准备时不会重复授权
 
 `prepare()` 与 `getInfo()` 返回的 `CompanionInfo.source` 标明 Host 确认的产物来源：`local-dev` 是本地开发产物，`preview` 是审核前预览产物，`released` 是已发布版本产物；旧 Host 缺省时 `source` 为 `undefined`，表示来源未知。不要用 `alias`、`displayName` 或文件路径自行推断来源，也不要把 `preview` 产物当作已发布版本；当前 PC Host 不支持审核前预览时以 `COMPANION_PREVIEW_UNSUPPORTED` 失败。
 
+准备状态是可恢复的 Host 状态，不等于当前页面 Promise 的状态：
+
+| `getPreparationStatus()` 状态 | 含义                                  | 推荐动作                                                         |
+| ----------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `not-prepared`                | 当前版本产物尚未准备                  | 等待新的可信用户操作调用 `prepare()`                             |
+| `preparing`                   | Host 正在下载、校验或解压             | 展示 `progress`；需要继续观察时再次调用 `prepare()` 加入同一操作 |
+| `ready`                       | 产物已原子提交，可独立触发 `launch()` | 展示可启动状态；`preparedAt` 是 Host 提供的时间戳                |
+| `failed`                      | 最近一次准备失败                      | 根据 `error.retryable` 和 `error.code` 决定重试或停止            |
+
+`AbortSignal` 取消的是当前调用并向 Host 发出取消意图，不是页面本地的同步回滚。若原子提交已开始，当前 Promise
+可能因取消而失败，但稍后查询仍可能得到 `ready`；取消后需要用 `getPreparationStatus()` 对账，不要直接把 UI 固定为
+`not-prepared`。
+
 ## Session 与 stdio
 
 同一小程序 identity 与 alias 同时最多有一个活动 Session。`getActiveSession(alias)` 会取得当前活动 Session
 的控制权；新 Runtime generation 接管后，旧 controller 的写入、关闭 stdin、终止、附件和通知操作都会失败。
 进程退出后 `getActiveSession()` 返回 `undefined`，业务结果应由小程序自行持久化。
 
+`CompanionSession.state` 只有 `running` 和 `exited`。`onExit()` 在 Session 已退出后注册时会立即收到保存的退出结果，
+`waitForExit()` 对同一 Session 始终等待同一次退出；组件销毁时仍应调用所有 `on*()` 返回的取消订阅函数。
+失去 controller 不等于进程退出，也不会让 `waitForExit()` 提前完成。收到 `onOwnershipLost()` 后应停止写入；确有继续
+控制的需要时重新调用 `getActiveSession(alias)`，不要对旧 controller 操作做无界重试。
+
 stdio 仅在 Manifest 声明 `stdio` 时存在，输入输出都是原始 `Uint8Array`。SDK 不做 UTF-8、换行、NDJSON、
 RPC 或业务状态解析。输出采用 at-least-once 投递，收到 chunk 后 SDK 会确认 sequence；断连与重取控制权可能
 导致重复，因此业务 framing 必须携带可去重标识，并能处理拆包、粘包和重放。
@@ -979,9 +1162,10 @@ RPC 或业务状态解析。输出采用 at-least-once 投递，收到 chunk 后
 ```ts
 const session = await companion.getActiveSession('runner')
 if (session?.stdio) {
-  const stop = session.stdio.onStdout(bytes => decodeBusinessFrame(bytes))
+  const stopOutput = session.stdio.onStdout(bytes => decodeBusinessFrame(bytes))
+  const stopOwnership = session.onOwnershipLost(() => setControlsEnabled(false))
   await session.stdio.write(encodeBusinessFrame({ type: 'status' }))
-  // 组件销毁时调用 stop()；业务退出协议可先写入，再 closeStdin()。
+  // 组件销毁时调用 stopOutput() 和 stopOwnership()；业务退出协议可先写入，再 closeStdin()。
 }
 ```
 

package/skill/references/recipes.md

@@ -64,11 +64,11 @@ async function getCurrentUser() {
 }
 ```
 
-`user.getInfo()` 不展示授权弹窗，也不要求可信用户手势。未登录时返回未登录状态；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），静默返回 `userInfo.app_user_id`、`profile.nickname` 和 `profile.avatar`。这条路径不能获取授权码或调用 OpenAPI，也不能把身份或资料发送到外部服务。
+`user.getInfo()` 不展示授权弹窗，也不要求可信用户手势。未登录时返回未登录状态；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），静默返回 `userInfo.app_user_id`、`profile.nickname` 和 `profile.avatar`。平台为当前版本启用 Steam 账号能力且小程序未开通网络权限时，还会授予 `steam_account`，已绑定用户返回可选 `userInfo.steam_id`。这条路径不能获取授权码或调用 OpenAPI，也不能把身份或资料发送到外部服务。
 
 ## 获取服务端授权码
 
-声明 `userInfo` 后，可通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作。该调用内部使用 Host 受信请求，不依赖公开 `network` 权限；示例中的 `network.request()` 另需声明并获得 `network` 平台批准。
+声明 `userInfo` 后，可通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作。平台为当前版本启用 Steam 账号能力后，联网小程序可在 `scopes` 中按需加入 `steam_account`，并由开发者服务端通过 OpenAPI 读取 `steam_id`。该调用内部使用 Host 受信请求，不依赖公开 `network` 权限；示例中的 `network.request()` 另需声明并获得 `network` 平台批准。
 
 SDK 会自动完成握手。登录按钮应按上面的持久握手状态启用；点击回调直接调用 `auth.login()`，不要先等待其他异步任务，以免首次操作丢失可信手势。
 
@@ -259,9 +259,9 @@ async function loginFromUserAction() {
 - `expiresIn` 是服务端返回的有效期（当前为 `300` 秒）；服务端应尽快使用，失败或过期后重新获取，不要在业务代码中硬编码该值。
 - `scopes` 是本次授权码实际包含的 scope。
 
-`identity` 始终隐式包含，不需要也不能通过省略它来申请匿名授权。`scopes` 只填写业务确实需要的可选资料，例如 `profile`；不需要额外资料时直接调用 `auth.login()`。
+`identity` 始终隐式包含，不需要也不能通过省略它来申请匿名授权。`scopes` 只填写业务确实需要的可选资料，例如 `profile`。平台为当前版本启用 Steam 账号能力后，需要主绑定 SteamID64 的联网小程序可申请 `steam_account`；不需要额外资料时直接调用 `auth.login()`。
 
-小程序页面只把 `code` 发送到自己的服务端。开发者服务端再按后端 OpenAPI 文档，用服务端保存的应用凭据交换 token；页面不得自行交换，也不得持有应用私密凭据。`auth.login()` 不返回 user、profile、`app_user_id` 或 token。
+小程序页面只把 `code` 发送到自己的服务端。开发者服务端再按后端 OpenAPI 文档，用服务端保存的应用凭据交换 token；页面不得自行交换，也不得持有应用私密凭据。`auth.login()` 不返回 user、profile、`steam_id`、`app_user_id` 或 token。
 
 ## 后端 OpenAPI
 
@@ -310,7 +310,7 @@ async function getCurrentUser() {
 }
 ```
 
-`user.getInfo()` 不依赖 `network`，但必须声明 `userInfo`。它延续现有交互：不展示授权弹窗，也不要求可信用户手势。未登录时返回 `isHeyboxAppLoggedIn: false`；已登录时按现有用户授权状态返回当前小程序隔离的 `app_user_id`，以及已授权的 `profile.nickname` 和 `profile.avatar` 等可用资料。用户授权与开发者权限声明是两层独立门禁，不能用声明代替用户同意。
+`user.getInfo()` 必须声明 `userInfo`。它延续现有交互：不展示授权弹窗，也不要求可信用户手势。未登录时返回 `isHeyboxAppLoggedIn: false`；已登录时按授权状态返回当前小程序隔离的 `app_user_id`、`profile.nickname` 和 `profile.avatar`。平台为当前版本启用 Steam 账号能力后，未开通网络权限的小程序会隐式获得 `steam_account`，当前用户有主绑定时返回可选 `steam_id`；已开通网络权限的小程序改由开发者服务端通过 OpenAPI 读取这些资料，页面调用返回 `SERVER_API_REQUIRED`。用户授权与开发者权限声明是两层独立门禁，不能用声明代替用户同意。
 
 Steam 游戏库使用 `user.getSteamGameList(options)`，要求声明 `steamLibrary`，同样不依赖 `network`。Host current-user capabilities 的既有账号绑定和数据可用性规则保持不变。
 
@@ -414,9 +414,25 @@ try {
 }
 ```
 
+## 错误边界
+
+| 结果                                    | 表示什么                                                            | 常见处理                                            |
+| --------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------- |
+| `HbMiniProgramSDKError`                 | 握手、参数、权限、Host 能力或模块操作失败                           | 按稳定 `code` 分支，`message` 仅用于开发者提示      |
+| `HbMiniProgramNetworkError`             | `network.request()` 已获得 HTTP 响应，但状态未通过 `validateStatus` | 读取 `status`、`data` 和安全响应头                  |
+| `undefined` / `deleted: false` 等空结果 | API 明确定义的正常结果，例如排行榜中没有当前用户记录                | 正常渲染空态，不进入错误上报                        |
+| 其他异常                                | 业务回调、页面代码或非 SDK 依赖抛出的错误                           | 不要伪装成 SDK 错误；保留原异常继续交给统一错误边界 |
+
+`HbMiniProgramNetworkError` 不是“所有网络失败”的父类：只有已形成标准 HTTP 响应且状态校验失败时才使用它。
+握手、bridge、Host transport 或权限失败仍属于 `HbMiniProgramSDKError`。业务不应通过 `status === 0` 猜测网络错误。
+
+`HbMiniProgramSDKError.data` 是按错误码提供的可选诊断信息，不保证所有 Host 版本结构一致。读取前应做类型收窄，
+日志上报也必须先移除 token、授权码、文件路径、请求正文和用户隐私数据。
+
 ## 处理原则
 
 - 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
+- 对未知 `code` 使用通用失败 UI 并保留诊断信息；不要用穷举 `switch` 的 `default` 自动重试。
 - 权限失败时给出可理解的提示，不要将它当成未登录。
 - `PERMISSION_NOT_DECLARED` 表示当前版本没有在 `package.json#heybox.permissions` 声明所需权限，应修改项目配置并重新构建、提交版本。
 - `PERMISSION_DENIED` 表示权限已声明，但需要的平台批准缺失或批准配置不足。首期只有 `network` 需要平台批准。
@@ -428,7 +444,10 @@ try {
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
 - `COMPANION_NOT_PREPARED` 表示启动前尚未显式准备；应由新的用户操作调用 `companion.prepare()`，不要在 `launch()` 中自动重试。
+- `COMPANION_PREPARATION_CANCELLED` 表示取消意图已结束当前观察；原子提交可能已完成，应重新查询准备状态再更新 UI。
 - `COMPANION_SESSION_OWNERSHIP_LOST` 表示 Session controller 已由新的 Runtime generation 接管；停止旧 controller 写入，需要继续取得控制权时重新取得活动 Session。
+- `COMPANION_SESSION_EXITED` / `COMPANION_PIPE_CLOSED` 表示当前 Session 或 stdin 已进入终态；不要对同一 controller 重放写入。
+- `COMPANION_PROCESS_CRASHED` / `COMPANION_OUTPUT_LIMIT` 表示进程异常退出或输出越界；先展示退出状态并保存诊断，再由新的用户操作决定是否重启。
 - `COMPANION_DESCRIPTOR_UNAVAILABLE` 表示授权或描述符暂时不可用，Runtime 会保留 `retryable: true`。
 - `COMPANION_INTEGRITY_FAILED`、`COMPANION_ARCHIVE_INVALID` 或操作系统拦截都不能绕过；停止重试并修正归档后提交新审核版本。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
@@ -581,12 +600,30 @@ Host 可信授权；已 ready 或加入同一在途准备时不会重复授权
 
 `prepare()` 与 `getInfo()` 返回的 `CompanionInfo.source` 标明 Host 确认的产物来源：`local-dev` 是本地开发产物，`preview` 是审核前预览产物，`released` 是已发布版本产物；旧 Host 缺省时 `source` 为 `undefined`，表示来源未知。不要用 `alias`、`displayName` 或文件路径自行推断来源，也不要把 `preview` 产物当作已发布版本；当前 PC Host 不支持审核前预览时以 `COMPANION_PREVIEW_UNSUPPORTED` 失败。
 
+准备状态是可恢复的 Host 状态，不等于当前页面 Promise 的状态：
+
+| `getPreparationStatus()` 状态 | 含义                                  | 推荐动作                                                         |
+| ----------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `not-prepared`                | 当前版本产物尚未准备                  | 等待新的可信用户操作调用 `prepare()`                             |
+| `preparing`                   | Host 正在下载、校验或解压             | 展示 `progress`；需要继续观察时再次调用 `prepare()` 加入同一操作 |
+| `ready`                       | 产物已原子提交，可独立触发 `launch()` | 展示可启动状态；`preparedAt` 是 Host 提供的时间戳                |
+| `failed`                      | 最近一次准备失败                      | 根据 `error.retryable` 和 `error.code` 决定重试或停止            |
+
+`AbortSignal` 取消的是当前调用并向 Host 发出取消意图，不是页面本地的同步回滚。若原子提交已开始，当前 Promise
+可能因取消而失败，但稍后查询仍可能得到 `ready`；取消后需要用 `getPreparationStatus()` 对账，不要直接把 UI 固定为
+`not-prepared`。
+
 ## Session 与 stdio
 
 同一小程序 identity 与 alias 同时最多有一个活动 Session。`getActiveSession(alias)` 会取得当前活动 Session
 的控制权；新 Runtime generation 接管后，旧 controller 的写入、关闭 stdin、终止、附件和通知操作都会失败。
 进程退出后 `getActiveSession()` 返回 `undefined`，业务结果应由小程序自行持久化。
 
+`CompanionSession.state` 只有 `running` 和 `exited`。`onExit()` 在 Session 已退出后注册时会立即收到保存的退出结果，
+`waitForExit()` 对同一 Session 始终等待同一次退出；组件销毁时仍应调用所有 `on*()` 返回的取消订阅函数。
+失去 controller 不等于进程退出，也不会让 `waitForExit()` 提前完成。收到 `onOwnershipLost()` 后应停止写入；确有继续
+控制的需要时重新调用 `getActiveSession(alias)`，不要对旧 controller 操作做无界重试。
+
 stdio 仅在 Manifest 声明 `stdio` 时存在，输入输出都是原始 `Uint8Array`。SDK 不做 UTF-8、换行、NDJSON、
 RPC 或业务状态解析。输出采用 at-least-once 投递，收到 chunk 后 SDK 会确认 sequence；断连与重取控制权可能
 导致重复，因此业务 framing 必须携带可去重标识，并能处理拆包、粘包和重放。
@@ -594,9 +631,10 @@ RPC 或业务状态解析。输出采用 at-least-once 投递，收到 chunk 后
 ```ts
 const session = await companion.getActiveSession('runner')
 if (session?.stdio) {
-  const stop = session.stdio.onStdout(bytes => decodeBusinessFrame(bytes))
+  const stopOutput = session.stdio.onStdout(bytes => decodeBusinessFrame(bytes))
+  const stopOwnership = session.onOwnershipLost(() => setControlsEnabled(false))
   await session.stdio.write(encodeBusinessFrame({ type: 'status' }))
-  // 组件销毁时调用 stop()；业务退出协议可先写入，再 closeStdin()。
+  // 组件销毁时调用 stopOutput() 和 stopOwnership()；业务退出协议可先写入，再 closeStdin()。
 }
 ```
 

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.1+skill.326b19d2bdf1",
+  "skillVersion": "0.8.2-alpha.2+skill.3a104594d594",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1",
-    "compatibility": "0.8.1"
+    "version": "0.8.2-alpha.2",
+    "compatibility": "0.8.2-alpha.2"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1",
+    "version": "0.8.2-alpha.2",
     "path": "skill"
   },
-  "integrity": "sha256-326b19d2bdf15cecbbfb8f0670ec53ddbffc1eb11cbe8faa4b0e45ad8c4a6f92"
+  "integrity": "sha256-3a104594d594cf199062a74cd2688c1582ac08d57ce7487e6f4f2050700bbc03"
 }

package/types/core/errors.d.ts

@@ -6,12 +6,34 @@ import type { MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse } from
  * @remarks
  * 该错误用于表示握手失败、bridge 调用失败、父容器运行时错误等
  * 非 HTTP 结果错误。其 `code` 字段可用于业务分支处理，
- * `data` 仅作为可选调试信息，不保证结构稳定。
+ * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
+ * `message` 只用于日志和开发者提示，不应作为机器判断条件。
+ *
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
+ * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
+ *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
+ * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
+ * 不要把所有错误都当作可重试错误，也不要把 `data` 当成稳定的序列化协议。
+ *
+   * @example
+   * ```ts
+   * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+   *
+   * try {
+   *   await hbSDK.auth.login({ scopes: ['profile'] })
+ * } catch (error) {
+ *   if (error instanceof HbMiniProgramSDKError && error.code === 'USER_GESTURE_REQUIRED') {
+ *     showRetryButton()
+ *     return
+ *   }
+ *   throw error
+ * }
+ * ```
  */
 export declare class HbMiniProgramSDKError extends Error {
-    /** 稳定错误码。 */
+    /** 稳定错误码；业务分支应比较该字段，不要比较 `message`。 */
     code: string;
-    /** 可选调试数据。 */
+    /** 可选调试数据；结构由具体错误码决定，可能随 Host 版本变化。 */
     data?: unknown;
     constructor(error: MiniProgramBridgeError);
 }
@@ -32,20 +54,22 @@ export declare function createSDKError(code: string, message: string, data?: unk
  *
  * @remarks
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
- * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
+ * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。网络请求没有收到
+ * 可判定的 HTTP 响应时，SDK 会抛出 `HbMiniProgramSDKError` 或原始 transport 错误，
+ * 不应把本类当作网络不可达的统一错误类型。
  *
  * @typeParam T - 标准化响应数据的类型。
  */
 export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
-    /** HTTP 状态码。 */
+    /** HTTP 状态码；由 `validateStatus` 判定为失败的响应状态。 */
     status: number;
-    /** 标准化响应数据。 */
+    /** 标准化响应数据；类型由 `network.request<T>()` 的泛型参数决定。 */
     data: T;
-    /** 标准化响应头。 */
+    /** 标准化响应头；敏感响应头会在进入错误对象前被脱敏或移除。 */
     headers: Record<string, string>;
-    /** SDK 公共请求配置快照。 */
+    /** SDK 公共请求配置快照；可能含原始 URL、请求头或请求数据，记录日志前必须自行脱敏。 */
     config: MiniProgramNetworkRequestConfig;
-    /** 完整标准化响应。 */
+    /** 完整标准化响应，包含状态、头、数据和请求配置。 */
     response: MiniProgramNetworkResponse<T>;
     /**
      * @param response - 已完成请求的标准化网络响应。

package/types/core/handshake-state.d.ts

@@ -1,5 +1,23 @@
 import type { HbMiniProgramSDKError } from './errors';
-/** SDK 与 Host 握手的持久状态。 */
+/**
+ * SDK 与 Host 握手的持久状态。
+ *
+ * @remarks
+ * 状态是按 `status` 判别的只读联合类型：
+ *
+ * - `connecting`：默认 SDK 已开始初始握手但尚未落定；
+ * - `ready`：初始握手已成功；
+ * - `failed`：初始握手已失败，`error` 是导致失败的原始
+ *   [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。
+ *
+ * 新实例只会从 `connecting` 迁移一次到 `ready` 或 `failed`，终态不会回退或互相转换；重复的
+ * `ready` 事件也不会建立第二次状态迁移。每个状态 wrapper 都经过 `Object.freeze()`，调用方不能
+ * 替换 `status` 或 `failed.error`；冻结是浅层的，`error` 保留原始实例而不是克隆或冻结副本。
+ *
+ * `ready` 只记录初始握手已经成功，不是 Runtime 的持续存活探针；后续收到 `unload` 或销毁实例时
+ * 仍不会回退。该持久状态适合驱动交互控件；生命周期 `ready` 事件只是一条不会向晚订阅者重放的
+ * 边沿通知，不能替代当前状态。
+ */
 export type MiniProgramSDKHandshakeState = {
     readonly status: 'connecting';
 } | {
@@ -8,7 +26,19 @@ export type MiniProgramSDKHandshakeState = {
     readonly status: 'failed';
     readonly error: HbMiniProgramSDKError;
 };
-/** SDK 握手状态变化处理函数。 */
+/**
+ * SDK 握手状态变化处理函数。
+ *
+ * @param state - 当前冻结的
+ * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState)：
+ * `connecting` 表示尚未落定，`ready` 表示初始握手成功，`failed.error` 保留原始握手错误。
+ *
+ * @remarks
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 会在注册过程中同步调用
+ * handler 一次；若当前为 `connecting`，状态落定时至多再同步调用一次。SDK 会隔离 handler 的同步
+ * 异常，使其不阻断状态落定或其他订阅者；返回值会被忽略且 Promise 不会被等待，因此异步 handler
+ * 必须自行处理 rejected Promise。
+ */
 export type MiniProgramSDKHandshakeStateHandler = (state: MiniProgramSDKHandshakeState) => void;
 /** 保存握手终态，并向订阅者同步派发唯一一次状态迁移。 */
 export declare class MiniProgramSDKHandshakeStateStore {