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

package/README.md

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

package/bin/hb-sdk.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli.cjs').runCli();