@heybox/hb-sdk 0.2.0-alpha.0 → 0.2.0-alpha.1

package/README.md

@@ -1,420 +1,116 @@
 # @heybox/hb-sdk
 
-面向黑盒外部小程序 iframe 沙盒的前端 SDK。它负责与父容器完成握手、收发 bridge 消息，并以受控模块的形式向外部小程序开放授权、用户、分享、视口、隔离 storage 与网络请求能力。
+黑盒外部小程序前端 SDK。业务页面运行在黑盒父容器创建的 iframe 沙盒中，通过这个 SDK 等待容器 ready、获取登录态、唤起登录、分享、读取窗口信息、使用隔离 storage，以及发起受控网络请求。
 
-## 为什么需要它
-
-外部小程序运行在父容器创建的 iframe 沙盒中，业务页面不能直接读取主站登录态，也不应该关心底层 `postMessage` 协议、nonce 校验、请求响应关联、超时清理、客户端协议参数过滤等细节。
-
-`@heybox/hb-sdk` 将这些通信细节封装为稳定接口，让小程序只通过被允许的能力访问父容器。父容器仍负责调用黑盒客户端协议，并在运行时过滤不适合开放给外部小程序的内部参数。网络请求能力同样遵循这个边界：SDK 提供 axios-like 的窄接口，运行时负责协议映射。
+## 快速开始
 
-## 当前对外导出
+创建一个新的外部小程序项目：
 
-> 以 `src/index.ts` 为准；历史目录、旧示例或构建产物若与当前入口不一致，以当前源码导出能力为准。
+```bash
+npx @heybox/hb-sdk create my-miniapp
+cd my-miniapp
+npm install
+npm run dev
+```
 
-- 默认导出 `hbSDK`：包含 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`、`network`。
-- 命名导出 `ready` / `on` / `off` / `auth` / `user` / `share` / `viewport` / `storage` / `network`：默认 SDK 单例能力。
-- `createMiniProgramSDK` / `MiniProgramSDK`：创建独立 SDK 实例，适合测试、多实例或显式生命周期管理场景。
-- `HbMiniProgramSDKError`：bridge / 运行时 / 协议失败时的标准错误类型。
-- `HbMiniProgramNetworkError`：HTTP 已完成但未通过 SDK `validateStatus` 校验时的网络错误类型。
-- `MiniProgramRequester` / `MiniProgramSDKOptions`：底层请求与 SDK 初始化配置类型。
-- bridge 协议常量、类型与守卫：根入口保留导出；运行时等宿主侧包应优先从 `@heybox/hb-sdk/protocol` 子入口导入，避免误依赖 SDK core / singleton。
-- 模块类型与方法常量：`MiniProgramAuthModule`、`MiniProgramUserModule`、`MiniProgramShareModule`、`MiniProgramViewportModule`、`MiniProgramStorageModule`、`MiniProgramNetworkModule` 以及各模块 method 常量。
+模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
 
-> 本版本为破坏性模块重排：登录归属 `auth`，窗口归属 `viewport`，存储归属 `storage`；旧的 `user.login()` 与 `system.*` 入口已移除。
+在已有项目中安装：
 
-## 快速开始
+```bash
+npm install @heybox/hb-sdk
+```
 
-最小示例：
+然后在页面入口等待父容器 ready：
 
 ```ts
 import hbSDK from '@heybox/hb-sdk';
 
 await hbSDK.ready();
 
-const result = await hbSDK.user.getInfo();
+const user = await hbSDK.user.getInfo();
 
-if (result.isLogin) {
-  console.log(result.userInfo.nickname);
+if (user.isLogin) {
+  console.log(user.userInfo.nickname);
 }
 ```
 
-按需导入：
+也可以按需导入：
 
 ```ts
-import { on, ready, user } from '@heybox/hb-sdk';
-
-const unsubscribe = on('show', (payload) => {
-  console.log('小程序展示', payload.timestamp, payload.source);
-});
+import { auth, ready, user } from '@heybox/hb-sdk';
 
 await ready();
 
 const currentUser = await user.getInfo();
 
-unsubscribe();
-```
-
-分享、storage 与 network：
-
-```ts
-import { network, share, storage } from '@heybox/hb-sdk';
-
-const response = await network.request<{ ok: boolean }>({
-  url: 'https://api.example.com/demo',
-  method: 'GET',
-});
-
-console.log(response.status, response.data.ok);
-
-
-await share.showShareMenu({
-  title: '分享标题',
-  desc: '分享描述',
-  url: 'https://web.xiaoheihe.cn/tools/demo',
-  imageUrl: 'https://imgheybox.max-c.com/demo.png',
-});
-
-await storage.setStorage({
-  key: 'settings',
-  data: {
-    theme: 'dark',
-  },
-});
-
-const { data } = await storage.getStorage<{ theme: string }>({
-  key: 'settings',
-});
-```
-
-网络请求默认只把 `2xx` 视为成功；`4xx/5xx` 这类已完成 HTTP 响应会在 SDK 模块层抛出 `HbMiniProgramNetworkError`，而 bridge / 运行时 / 协议失败仍然抛出 `HbMiniProgramSDKError`。`validateStatus` 仅在 SDK 本地执行，不会把函数值透传给父容器。
-
-## 核心概念
-
-### 默认单例
-
-普通小程序页面优先使用默认导出的 `hbSDK`，或直接按需导入 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`。默认单例会在首次调用时懒创建，业务不需要手动初始化。
-
-```ts
-import { ready, viewport } from '@heybox/hb-sdk';
-
-await ready();
-const windowInfo = await viewport.getWindowInfo();
-```
-
-### 独立实例
-
-需要显式控制生命周期、注入测试环境 window、调整超时时间，或同页存在多套沙盒通信上下文时，可以使用 `createMiniProgramSDK`。
-
-```ts
-import { createMiniProgramSDK } from '@heybox/hb-sdk';
-
-const sdk = createMiniProgramSDK({
-  timeout: 5000,
-});
-
-await sdk.ready();
-
-const loginResult = await sdk.auth.login();
-
-sdk.destroy();
-```
-
-### bridge 通信
-
-SDK 与父容器之间通过 `postMessage` 通信，消息会带上固定命名空间、协议版本与 iframe 实例 nonce。SDK 内部负责：
-
-- 从 URL query 读取 `hb_mini_bridge_nonce`，也支持通过 `MiniProgramSDKOptions.nonce` 显式传入。
-- 支持通过 `MiniProgramSDKOptions.targetOrigin` 显式指定发往父容器的 `postMessage targetOrigin`；未传时会尝试推断父容器 origin，失败则兼容回退为 `*`。
-- 向父容器发送 `sdk.handshake` 握手消息；如果还没有收到 `ready` 事件，会在总超时窗口内短间隔重试。
-- 为每次能力调用生成请求 ID，匹配父容器返回的 response。
-- 过滤非小程序消息、非当前 nonce 消息以及非目标父窗口消息。
-- 处理请求超时、握手总超时和销毁后的未完成请求。
-
-父容器应幂等响应握手：重复 `sdk.handshake` 只代表 SDK 在补偿早期消息丢失，父容器可以重复派发 `ready`，但不应重复执行一次性启动副作用。
-
-### 标准错误
-
-请求失败和 SDK 内部错误会统一包装为 `HbMiniProgramSDKError`，包含稳定的 `code`、面向开发者的 `message` 和可选 `data`。
-
-```ts
-import { HbMiniProgramSDKError, auth } from '@heybox/hb-sdk';
-
-try {
+if (!currentUser.isLogin) {
   await auth.login();
-} catch (error) {
-  if (error instanceof HbMiniProgramSDKError) {
-    console.log(error.code, error.message, error.data);
-  }
 }
 ```
 
-## 模块说明
-
-### Core
-
-核心模块位于 `src/core`，负责 SDK 实例、默认单例、bridge client、事件总线、错误和工具函数。
-
-| 模块 | 作用 | 代表导出 |
-| --- | --- | --- |
-| `core/sdk` | SDK 实例封装 | `MiniProgramSDK`、`createMiniProgramSDK` |
-| `core/singleton` | 默认单例入口 | `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage` |
-| `core/client` | bridge 握手、请求响应、事件分发 | `MiniProgramSDKOptions`、`MiniProgramRequester` |
-| `core/errors` | 标准错误类型 | `HbMiniProgramSDKError` |
-
-### Auth
-
-授权模块位于 `src/modules/auth`，承载登录授权类能力。
-
-| API | 对应父容器能力 | 说明 |
-| --- | --- | --- |
-| `auth.login()` | `auth.login` | 唤起黑盒登录流程，并返回登录后的最新用户公开资料。 |
-
-### User
-
-用户模块位于 `src/modules/user`，只暴露允许小程序访问的公开用户资料能力。
-
-| API | 说明 |
-| --- | --- |
-| `user.getInfo()` | 获取当前用户登录态与公开基础资料。未登录时不会触发登录流程。 |
-
-用户信息只包含允许暴露给外部小程序的公开字段：
-
-```ts
-interface MiniProgramUserInfo {
-  heybox_id: string;
-  nickname: string;
-  avatar: string;
-}
-
-interface MiniProgramUserInfoResult {
-  isLogin: boolean;
-  userInfo: MiniProgramUserInfo | null;
-}
-```
-
-SDK 不会向小程序暴露 token、cookie、手机号或任何可用于直接调用主站私有接口的凭据。
-
-### Network
-
-网络模块位于 `src/modules/network`，提供一个窄化的 axios-like `network.request()` 接口。SDK 只暴露公共请求字段，父容器运行时负责把这些字段映射到实际协议。
-
-| API | 对应父容器能力 | 说明 |
-| --- | --- | --- |
-| `network.request(config)` | `network.request` | 发起网络请求；默认仅 `2xx` 视为成功。 |
-
-```ts
-interface MiniProgramNetworkRequestConfig {
-  url: string;
-  method?: string;
-  params?: Record<string, unknown>;
-  data?: unknown;
-  headers?: Record<string, string>;
-  timeout?: number;
-  withCredentials?: boolean;
-  validateStatus?: (status: number) => boolean;
-}
-
-interface MiniProgramNetworkResponse<T = unknown> {
-  data: T;
-  status: number;
-  statusText?: string;
-  headers: Record<string, string>;
-  config: MiniProgramNetworkRequestConfig;
-}
-```
-
-约束说明：
-
-- `validateStatus` 只在 SDK 本地执行，不会跨 bridge 传输函数。
-- `config` 是 SDK 公共请求配置快照，不包含任何原始 `sendRequestV2` 字段。
-- 公开响应头为 `Record<string, string>`；无法可靠解析时应视为 `{}`。
-- v1 不提供原始协议字段、回调函数、拦截器或上传下载进度等高级能力。
-
-### Share
-
-分享模块位于 `src/modules/share`，对外提供简洁配置，父容器侧再映射到黑盒客户端协议。
-
-| API | 对应父容器能力 | 说明 |
-| --- | --- | --- |
-| `share.showShareMenu(options)` | `share.showShareMenu` -> `share` 协议 | 展示基础分享面板。 |
-| `share.screenshot(options?)` | `share.screenshot` -> `screenShotShareV2` 协议 | 截图并唤起分享。 |
+## 运行环境
 
-基础分享参数：
+SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注入 bridge nonce，并通过 `postMessage` 与 SDK 通信。普通浏览器直接打开小程序页面时通常无法完成握手；本地开发请优先使用：
 
-```ts
-interface MiniProgramShowShareMenuOptions {
-  title: string;
-  desc: string;
-  url: string;
-  imageUrl?: string;
-  channel?: 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
-}
-```
-
-截图分享参数：
-
-```ts
-interface MiniProgramScreenshotOptions {
-  rect?: {
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-  };
-  delay?: number;
-  saveToAlbum?: boolean;
-}
+```bash
+npm run dev
 ```
 
-为了保持外部 API 稳定，`share` 模块不开放 raw protocol、JS callback、活动上报、发帖、自定义按钮、upload-only 等内部能力。
-
-### Viewport
-
-Viewport 模块位于 `src/modules/viewport`，承载窗口、视口和安全区域相关能力。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。
 
-| API | 对应父容器能力 | 说明 |
-| --- | --- | --- |
-| `viewport.getWindowInfo()` | `viewport.getWindowInfo` | 获取窗口、屏幕、安全区域等信息。 |
+在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 
-`getWindowInfo()` 返回字段对齐微信小程序 `wx.getWindowInfo` 的常用字段：
-
-```ts
-interface MiniProgramWindowInfoResult {
-  pixelRatio: number;
-  screenWidth: number;
-  screenHeight: number;
-  windowWidth: number;
-  windowHeight: number;
-  statusBarHeight: number;
-  safeArea: {
-    left: number;
-    right: number;
-    top: number;
-    bottom: number;
-    width: number;
-    height: number;
-  };
-  screenTop: number;
+```json
+{
+  "scripts": {
+    "dev": "hb-sdk dev"
+  }
 }
 ```
 
-### Storage
+## 常用能力
 
-Storage 模块位于 `src/modules/storage`，承载小程序隔离存储能力。
+### 用户与登录
 
-| API | 对应父容器能力 | 说明 |
-| --- | --- | --- |
-| `storage.getStorage(options)` | `storage.getStorage` -> `getStorage` 协议 | 读取小程序隔离 storage。 |
-| `storage.setStorage(options)` | `storage.setStorage` -> `setStorage` 协议 | 写入小程序隔离 storage。 |
-
-storage API：
+`user.getInfo()` 只读取当前登录态，不会主动唤起登录。需要用户操作时再调用 `auth.login()`。
 
 ```ts
-await storage.setStorage({
-  key: 'settings',
-  data: {
-    enabled: true,
-  },
-});
-
-const result = await storage.getStorage<{ enabled: boolean }>({
-  key: 'settings',
-});
-```
-
-storage 只开放 `get` / `set`，不开放 `removeStorage`、`clearStorage`、`getStorageInfo`、`getStorageV2`。父容器会强制加小程序级命名空间，外部小程序不能读写黑盒客户端全局 storage key。用户传入的 `key` 只允许 1-128 位字母、数字、下划线和连字符。
-
-### Protocol
-
-协议模块位于 `src/protocol`，定义父容器与 iframe SDK 之间的消息格式、事件名、事件 payload 映射、协议常量和消息守卫。
-
-当前支持的小程序事件：
-
-- `launch`：小程序首次完成握手并启动。
-- `ready`：SDK 已可安全调用开放能力。
-- `show`：小程序页面展示。
-- `hide`：小程序页面隐藏。
-- `unload`：小程序页面即将卸载。
-- `error`：父容器或开放能力运行异常。
-- `authChange`：登录状态发生变化后的最新用户信息。
-
-## 常见场景示例
-
-### 场景 1：进入页面后获取用户信息
-
-```ts
-import { ready, user } from '@heybox/hb-sdk';
-
-await ready();
+import { auth, user } from '@heybox/hb-sdk';
 
 const result = await user.getInfo();
 
 if (!result.isLogin) {
-  // 可按业务需要展示登录按钮，不会在 getInfo 阶段自动唤起登录。
-  return;
+  const loginResult = await auth.login();
+  console.log(loginResult.userInfo);
 }
-
-renderUser(result.userInfo);
 ```
 
-### 场景 2：点击按钮唤起登录
-
-```ts
-import { auth } from '@heybox/hb-sdk';
+SDK 只返回允许暴露给外部小程序的公开资料，不会返回 token、cookie、手机号或其他私有凭据。
 
-async function handleLoginClick() {
-  const result = await auth.login();
-
-  if (result.isLogin) {
-    renderUser(result.userInfo);
-  }
-}
-```
-
-### 场景 3：展示分享面板
-
-```ts
-import { share } from '@heybox/hb-sdk';
-
-async function handleShareClick() {
-  await share.showShareMenu({
-    title: '我的小程序页面',
-    desc: '来自黑盒小程序的分享',
-    url: location.href,
-    imageUrl: 'https://imgheybox.max-c.com/demo.png',
-    channel: 'wechatSession',
-  });
-}
-```
-
-### 场景 4：截图分享当前页面
+### 分享
 
 ```ts
 import { share } from '@heybox/hb-sdk';
 
-async function handleScreenshotShare() {
-  await share.screenshot({
-    delay: 100,
-    saveToAlbum: true,
-  });
-}
+await share.showShareMenu({
+  title: '我的小程序页面',
+  desc: '来自黑盒小程序的分享',
+  url: window.location.href,
+  imageUrl: 'https://imgheybox.max-c.com/demo.png',
+});
 ```
 
-也可以指定截图区域：
+截图分享：
 
 ```ts
 await share.screenshot({
-  rect: {
-    left: 0,
-    top: 0,
-    width: 375,
-    height: 667,
-  },
+  delay: 100,
+  saveToAlbum: true,
 });
 ```
 
-### 场景 5：读取窗口信息
+### 窗口信息
 
 ```ts
 import { viewport } from '@heybox/hb-sdk';
@@ -424,173 +120,151 @@ const windowInfo = await viewport.getWindowInfo();
 console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
 ```
 
-### 场景 6：使用隔离 storage
+### 隔离 Storage
 
 ```ts
 import { storage } from '@heybox/hb-sdk';
 
 await storage.setStorage({
-  key: 'card_mode',
+  key: 'settings',
   data: {
-    enabled: true,
+    theme: 'dark',
   },
 });
 
-const { data } = await storage.getStorage<{ enabled: boolean }>({
-  key: 'card_mode',
+const { data } = await storage.getStorage<{ theme: string }>({
+  key: 'settings',
 });
-
-if (data?.enabled) {
-  enableCardMode();
-}
 ```
 
-### 场景 7：监听生命周期与登录态变化
+storage key 只允许 1-128 位字母、数字、下划线和连字符。父容器会按小程序维度隔离 key，外部小程序不能读写黑盒客户端全局 storage。
 
-```ts
-import { off, on } from '@heybox/hb-sdk';
+### 网络请求
 
-const handleShow = (payload) => {
-  console.log('页面展示', payload.timestamp);
-};
+`network.request()` 提供窄化的 axios-like 接口。SDK 只接受公开请求字段，真实请求由父容器运行时映射到宿主网络能力。
 
-const handleAuthChange = (payload) => {
-  console.log('登录态变化', payload.isLogin, payload.userInfo);
-};
+```ts
+import { HbMiniProgramNetworkError, network } from '@heybox/hb-sdk';
 
-on('show', handleShow);
-on('authChange', handleAuthChange);
+try {
+  const response = await network.request<{ ok: boolean }>({
+    url: 'https://api.example.com/demo',
+    method: 'GET',
+    headers: {
+      accept: 'application/json',
+    },
+  });
 
-// 页面销毁时移除监听
-off('show', handleShow);
-off('authChange', handleAuthChange);
+  console.log(response.status, response.data.ok);
+} catch (error) {
+  if (error instanceof HbMiniProgramNetworkError) {
+    console.log(error.response.status, error.response.data);
+  }
+}
 ```
 
-也可以使用 `on` 返回的取消函数：
+默认只有 `2xx` 会 resolve；`4xx/5xx` 这类已完成 HTTP 响应会抛出 `HbMiniProgramNetworkError`。可以用 `validateStatus` 调整 SDK 本地判定逻辑，函数不会跨 bridge 传给父容器。
 
 ```ts
-const unsubscribe = on('hide', (payload) => {
-  console.log('页面隐藏', payload.timestamp);
+await network.request({
+  url: 'https://api.example.com/demo',
+  validateStatus: status => status < 500,
 });
-
-unsubscribe();
 ```
 
-### 场景 8：测试中注入通信环境
-
-```ts
-import { createMiniProgramSDK } from '@heybox/hb-sdk';
+支持的 HTTP method 为 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`。
 
-const sdk = createMiniProgramSDK({
-  nonce: 'test_nonce',
-  selfWindow: window,
-  targetWindow: parentWindow,
-  timeout: 100,
-});
+## 生命周期事件
 
-await sdk.ready();
-sdk.destroy();
-```
+使用 `on()` 监听父容器派发的小程序事件。`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
 
-## 与 `@heybox/hb-sdk-runtime` 的关系与兼容矩阵
+```ts
+import { on } from '@heybox/hb-sdk';
 
-`@heybox/hb-sdk` 是 iframe 内部使用的客户端 SDK，`@heybox/hb-sdk-runtime` 是 iframe 外部宿主壳层使用的运行时实现。当前仓库选择将 **协议 / 契约相关内容继续维护在 `@heybox/hb-sdk` 内部**，而不是额外拆出一个 contract 包，以减少包数量、发布面和维护成本。
+const unsubscribeShow = on('show', payload => {
+  console.log('页面展示', payload.timestamp, payload.source);
+});
 
-约定如下：
+const unsubscribeAuth = on('authChange', payload => {
+  console.log('登录态变化', payload.isLogin, payload.userInfo);
+});
 
-- `@heybox/hb-sdk-runtime` 可以依赖 `@heybox/hb-sdk` 中的 **协议常量、类型、消息守卫** 等契约层内容。
-- `@heybox/hb-sdk-runtime` **不应依赖** `@heybox/hb-sdk` 的 `core/*`、默认单例、客户端请求实现等客户端运行时逻辑。
-- 协议变更时，`@heybox/hb-sdk` 与 `@heybox/hb-sdk-runtime` 应按一组联动能力来评审和发布，而不是分别独立演进。
+unsubscribeShow();
+unsubscribeAuth();
+```
 
-### 兼容矩阵（当前约定）
+当前可监听事件包括 `launch`、`ready`、`show`、`hide`、`unload`、`error`、`authChange`。
 
-| `@heybox/hb-sdk` | `@heybox/hb-sdk-runtime` | 说明 |
-| --- | --- | --- |
-| 同一仓库主线版本 | 同一仓库主线版本 | 默认开发模式，按同一批次代码联动验证 |
-| 仅补丁级变更 | 仅补丁级变更 | 允许，但必须保持协议常量、消息结构、事件名和 payload 兼容 |
-| 协议字段 / 方法名 / 事件名变更 | 需要同步升级 | 不允许单边发布后假定另一侧自动兼容 |
+## 错误处理
 
-### 后续 CI 兼容性检查（待补）
+bridge、父容器运行时、协议校验或能力调用失败时会抛出 `HbMiniProgramSDKError`，其中包含稳定的 `code`、开发者可读的 `message` 和可选 `data`。
 
-后续补 CI 时，至少应增加以下检查：
+```ts
+import { HbMiniProgramSDKError, ready } from '@heybox/hb-sdk';
 
-1. **依赖边界检查**
-   - 禁止 `@heybox/hb-sdk-runtime` 引用 `@heybox/hb-sdk/core/*`、默认单例或客户端实现层。
-   - 只允许引用协议 / 契约层入口（例如 `@heybox/hb-sdk/protocol`）。
-2. **协议兼容性检查**
-   - 当 `MINI_PROGRAM_MESSAGE_*` 常量、事件名、方法名、payload 类型变更时，要求 `hb-sdk` 与 `hb-sdk-runtime` 相关测试同时通过。
-3. **联动验证检查**
-   - 至少跑一组 `hb-sdk` 单测 + `hb-sdk-runtime` 单测，确保客户端与宿主运行时没有单边漂移。
-4. **导出面检查**
-   - 若协议层导出发生调整，CI 需提醒评审同步检查 runtime 使用面，而不是默认为向后兼容。
+try {
+  await ready();
+} catch (error) {
+  if (error instanceof HbMiniProgramSDKError) {
+    console.log(error.code, error.message, error.data);
+  }
+}
+```
 
-## 能力边界与注意事项
+网络请求已完成但 HTTP 状态不满足 `validateStatus` 时会抛出 `HbMiniProgramNetworkError`，其 `response` 字段包含标准化后的 `status`、`headers`、`data` 和原始公共请求配置快照。
 
-- SDK 只能在父容器创建的小程序 iframe 沙盒中正常完成握手；非 iframe 环境会抛出 `NOT_IN_IFRAME`。
-- 父容器必须在小程序 URL 上注入 `hb_mini_bridge_nonce`，否则会抛出 `MISSING_NONCE`。
-- 父容器需要幂等响应 `sdk.handshake`；SDK 会在收到 `ready` 前自动重试握手，不引用 SDK 的普通页面不会触发握手。
-- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
-- `user.getInfo()` 只查询登录态，不会主动唤起登录。
-- `auth.login()` 只返回公开用户资料，不返回 token、cookie 或私有凭据。
-- `share.showShareMenu()` 只开放基础分享字段，不开放活动任务上报、发帖、自定义按钮等内部协议参数。
-- `share.screenshot()` 只做截图并分享，不开放 upload-only 和客户端 JS callback。
-- `viewport.getWindowInfo()` 的 `statusBarHeight`、`screenTop`、`safeArea.top` 在黑盒容器内按顶部可用偏移处理。
-- `storage.getStorage()` / `storage.setStorage()` 只访问小程序隔离 storage；业务 key 必须符合 `/^[A-Za-z0-9_-]{1,128}$/`。
-- `on()` 会返回取消监听函数；页面卸载或组件销毁时应及时取消监听。
-- 独立实例不再使用时应调用 `destroy()`，以移除 message 监听并拒绝未完成请求。
+## CLI
 
-## CLI 创建外部小程序模板
+`@heybox/hb-sdk` 随包提供 `hb-sdk` CLI。脚手架项目已在 npm scripts 中接好常用命令；已有项目也可以自行添加 scripts。
 
-`hb-sdk create <project-name>` 会生成一个外部独立小程序开发模板，默认使用 Vue 3、Vite、TypeScript 和 npm。
+| 命令 | 作用 |
+| --- | --- |
+| `hb-sdk create <project-name>` | 创建外部小程序模板。 |
+| `hb-sdk dev` | 启动当前项目的 Vite dev server 和浏览器 mock 宿主环境，并默认打开调试页。 |
+| `hb-sdk login` | 登录 Heybox，并把 CLI 自己需要的登录态保存在本地缓存中。 |
+| `hb-sdk login status` | 查看脱敏后的 CLI 登录态。 |
+| `hb-sdk login clear` | 清理 CLI 登录态。 |
+| `hb-sdk doctor` | 检查本机 `hb-sdk` Agent Skill 是否匹配当前 SDK，并输出手动安装/刷新命令。 |
 
-```bash
-hb-sdk create my-miniapp
-cd my-miniapp
-npm install
-npm run dev:mock
-```
+CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe SDK，也不会改变 `auth.login()`、`user.getInfo()`、`network.request()` 或 mock 宿主中的用户状态。
 
-生成规则：
+CLI 会在成功执行命令后检查 npm registry 上的 `@heybox/hb-sdk@latest`。如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒。
 
-- `project-name` 同时作为项目目录名和 `package.json` 的 `name`，必须是合法的非 scoped npm 包名，例如 `my-miniapp`。
-- 目标目录不存在时会自动创建；目标目录已存在但非空时会拒绝覆盖。
-- CLI 只生成文件，不会自动安装依赖、初始化 git 或打开编辑器。
-- 模板内置轻量 SDK 能力演示页和 Vitest 单测配置；`npm run dev:mock` 会启动本地 Vite 服务和 hb-sdk mock runtime host。
+## SDK 与 Runtime
 
-## CLI 登录态
+`@heybox/hb-sdk` 跑在 iframe 内部，由外部小程序业务页面使用。`@heybox/hb-sdk-runtime` 跑在 iframe 外部，由黑盒宿主壳层使用，负责启动 iframe、注入 nonce、维护 bridge server、注册能力 handler、转发宿主生命周期与登录态变化。
 
-`hb-sdk` CLI 内置 Heybox 浏览器登录流，登录态只保存在 `hb-sdk` 自己的本地缓存命名空间里，供 `hb-sdk` CLI 命令内部调用 Heybox 接口时复用。
+两者共享同一套 bridge 协议。协议字段、事件名或能力 payload 发生变化时，应按同一批次联动升级 SDK 与 runtime；不要只升级其中一侧后假定另一侧自动兼容。
 
-```bash
-hb-sdk login
-hb-sdk login status
-hb-sdk login clear
-```
+## 能力边界
 
-- `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
-- `hb-sdk login status` 只展示脱敏状态、`heyboxId`、登录时间和 cache 路径，不输出 `pkey`、cookie 或完整请求头。
-- `hb-sdk login clear` 只清理 `hb-sdk` 自己命名空间中的 Heybox 登录态。
+- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
+- `user.getInfo()` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
+- 分享、截图、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
+- `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
+- `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
+- 使用 `createMiniProgramSDK()` 创建独立实例后，不再需要时应调用 `destroy()`。
 
-这份 CLI 登录态不会注入 iframe SDK，也不会改变 `hb-sdk dev --mock` 的 mock 用户、`auth.login()`、`user.getInfo()` 或 `network.request()` 行为。
+## 导出
 
-## 开发命令
+默认导出 `hbSDK`，包含 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`、`network`。
 
-优先使用仓库统一的 `hbexec` 入口：
+常用命名导出：
 
-```bash
-# 运行单元测试
-pnpm exec hbexec test unit @heybox/hb-sdk
+- `ready`、`on`、`off`
+- `auth`、`user`、`share`、`viewport`、`storage`、`network`
+- `createMiniProgramSDK`、`MiniProgramSDK`
+- `HbMiniProgramSDKError`、`HbMiniProgramNetworkError`
+- 各模块公开类型，例如 `MiniProgramNetworkRequestConfig`、`MiniProgramNetworkResponse`、`MiniProgramUserInfoResult`
 
-# 构建产物与类型声明
-pnpm exec hbexec build package -d packages/hb-sdk
-```
+协议常量、消息类型和守卫仍通过根入口与 `@heybox/hb-sdk/protocol` 子入口导出。宿主运行时等非业务页面代码应优先使用 `@heybox/hb-sdk/protocol`。
 
-也可以直接运行包内脚本：
+## 本仓库开发
 
 ```bash
-# 运行单元测试
 pnpm --filter @heybox/hb-sdk run test:unit
-
-# 运行单元测试并生成覆盖率
-pnpm --filter @heybox/hb-sdk run test:unit:coverage
+pnpm --filter @heybox/hb-sdk run build:package
+pnpm --filter @heybox/hb-sdk run check:boundary
 ```
+
+`check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。