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

package/dist/protocol.esm.js

@@ -31,7 +31,6 @@ function isMiniProgramBridgeMessage(value) {
  * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
 const AUTH_LOGIN_METHOD = 'auth.login';
-
 /**
  * 用户信息能力方法名。
  *
@@ -39,7 +38,13 @@ const AUTH_LOGIN_METHOD = 'auth.login';
  * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
 const USER_GET_INFO_METHOD = 'user.getInfo';
-
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 /**
  * 截图分享能力方法名。
  *
@@ -47,15 +52,13 @@ const USER_GET_INFO_METHOD = 'user.getInfo';
  * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
-
 /**
- * 展示分享面板能力方法名。
+ * 视口窗口信息能力方法名。
  *
  * @remarks
  * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
-const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
-
+const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
 /**
  * 读取小程序隔离 storage 能力方法名。
  *
@@ -70,21 +73,76 @@ const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
  * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
 const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
-
 /**
- * 视口窗口信息能力方法名。
+ * 发起网络请求能力方法名。
  *
  * @remarks
  * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
-const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
-
+const NETWORK_REQUEST_METHOD = 'network.request';
 /**
- * 发起网络请求能力方法名。
+ * 小程序开放能力目录。
  *
  * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ * 新增 bridge method 时应先更新这里，再分别补齐 SDK 模块、runtime handler 与测试。
  */
-const NETWORK_REQUEST_METHOD = 'network.request';
+const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
+    {
+        method: AUTH_LOGIN_METHOD,
+        module: 'auth',
+        capability: AUTH_LOGIN_METHOD,
+        permission: 'auth.login',
+        risk: 'medium',
+    },
+    {
+        method: USER_GET_INFO_METHOD,
+        module: 'user',
+        capability: USER_GET_INFO_METHOD,
+        permission: 'user.getInfo',
+        risk: 'medium',
+    },
+    {
+        method: SHARE_SHOW_SHARE_MENU_METHOD,
+        module: 'share',
+        capability: SHARE_SHOW_SHARE_MENU_METHOD,
+        permission: 'share.basic',
+        risk: 'low',
+    },
+    {
+        method: SHARE_SCREENSHOT_METHOD,
+        module: 'share',
+        capability: SHARE_SCREENSHOT_METHOD,
+        permission: 'share.screenshot',
+        risk: 'medium',
+    },
+    {
+        method: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        permission: 'viewport.windowInfo',
+        risk: 'low',
+    },
+    {
+        method: STORAGE_GET_STORAGE_METHOD,
+        module: 'storage',
+        capability: STORAGE_GET_STORAGE_METHOD,
+        permission: 'storage.read',
+        risk: 'low',
+    },
+    {
+        method: STORAGE_SET_STORAGE_METHOD,
+        module: 'storage',
+        capability: STORAGE_SET_STORAGE_METHOD,
+        permission: 'storage.write',
+        risk: 'medium',
+    },
+    {
+        method: NETWORK_REQUEST_METHOD,
+        module: 'network',
+        capability: NETWORK_REQUEST_METHOD,
+        permission: 'network.request',
+        risk: 'high',
+    },
+];
 
-export { AUTH_LOGIN_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, NETWORK_REQUEST_METHOD, SDK_HANDSHAKE_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, USER_GET_INFO_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, isMiniProgramBridgeMessage };
+export { AUTH_LOGIN_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NETWORK_REQUEST_METHOD, SDK_HANDSHAKE_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, USER_GET_INFO_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, isMiniProgramBridgeMessage };

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -6,7 +6,6 @@
 
 ```bash
 npm install
-npm run dev:mock
 npm run dev
 npm run typecheck
 npm run test:unit
@@ -15,12 +14,9 @@ npm run build
 
 ## 开发模式
 
-- `npm run dev:mock`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力。
-- `npm run dev`：只启动小程序页面服务，适合被真实黑盒小程序容器加载。
+- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
 
-普通浏览器直接打开 `npm run dev` 的页面时，SDK 会因为缺少小程序 iframe 容器或 bridge nonce 而显示错误状态。开发时请优先使用 `npm run dev:mock`。
-
 ## 更多能力
 
 模板页面只保留最小接入示例。其他常用能力可以直接从 `@heybox/hb-sdk` 调用：

package/dist/templates/vue3-vite-ts/package.json.ejs

@@ -5,7 +5,6 @@
   "type": "module",
   "scripts": {
     "dev": "hb-sdk dev",
-    "dev:mock": "hb-sdk dev --mock --open",
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",

package/dist/templates/vue3-vite-ts/vite.config.ts

@@ -1,6 +1,7 @@
 import vue from '@vitejs/plugin-vue';
+import { miniappManifest } from '@heybox/hb-sdk/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
-  plugins: [vue()],
+  plugins: [vue(), miniappManifest()],
 });

package/dist/vite.cjs.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var path = require('node:path');
+
+const TEMPLATE_VERSION = '0.0.0';
+const SEMVER_LIKE_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const TEMPLATE_VERSION_ERROR = '@heybox/hb-sdk 提示：请把 package.json.version 从模板默认的 0.0.0 改成实际版本号再发布';
+function miniappManifest() {
+    let root = process.cwd();
+    let outDir = 'dist';
+    return {
+        name: 'heybox-miniapp-manifest',
+        apply: 'build',
+        configResolved(resolved) {
+            root = resolved.root;
+            outDir = resolved.build.outDir;
+        },
+        writeBundle() {
+            const version = readMiniappVersion(root);
+            if (!SEMVER_LIKE_RE.test(version)) {
+                this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+            node_fs.writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+        },
+    };
+}
+function readMiniappVersion(root) {
+    const packageJsonPath = path.join(root, 'package.json');
+    let content;
+    try {
+        content = node_fs.readFileSync(packageJsonPath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
+    }
+    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+        throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
+    }
+    const version = packageJson.version.trim();
+    if (version === TEMPLATE_VERSION) {
+        throw new Error(TEMPLATE_VERSION_ERROR);
+    }
+    return version;
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
+exports.miniappManifest = miniappManifest;

package/dist/vite.esm.js

@@ -0,0 +1,60 @@
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const TEMPLATE_VERSION = '0.0.0';
+const SEMVER_LIKE_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const TEMPLATE_VERSION_ERROR = '@heybox/hb-sdk 提示：请把 package.json.version 从模板默认的 0.0.0 改成实际版本号再发布';
+function miniappManifest() {
+    let root = process.cwd();
+    let outDir = 'dist';
+    return {
+        name: 'heybox-miniapp-manifest',
+        apply: 'build',
+        configResolved(resolved) {
+            root = resolved.root;
+            outDir = resolved.build.outDir;
+        },
+        writeBundle() {
+            const version = readMiniappVersion(root);
+            if (!SEMVER_LIKE_RE.test(version)) {
+                this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            mkdirSync(path.dirname(manifestPath), { recursive: true });
+            writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+        },
+    };
+}
+function readMiniappVersion(root) {
+    const packageJsonPath = path.join(root, 'package.json');
+    let content;
+    try {
+        content = readFileSync(packageJsonPath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
+    }
+    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+        throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
+    }
+    const version = packageJson.version.trim();
+    if (version === TEMPLATE_VERSION) {
+        throw new Error(TEMPLATE_VERSION_ERROR);
+    }
+    return version;
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
+export { miniappManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.2",
   "description": "",
   "exports": {
     ".": {
@@ -16,6 +16,19 @@
       "node": "./dist/protocol.cjs.js",
       "browser": "./dist/protocol.esm.js",
       "default": "./dist/protocol.esm.js"
+    },
+    "./miniapp-publish": {
+      "types": "./types/miniapp-publish/index.d.ts",
+      "heybox": "./src/miniapp-publish/index.ts",
+      "node": "./dist/miniapp-publish.cjs.js",
+      "browser": "./dist/miniapp-publish.esm.js",
+      "default": "./dist/miniapp-publish.esm.js"
+    },
+    "./vite": {
+      "types": "./types/vite/index.d.ts",
+      "import": "./dist/vite.esm.js",
+      "require": "./dist/vite.cjs.js",
+      "default": "./dist/vite.esm.js"
     }
   },
   "bin": {
@@ -24,11 +37,23 @@
   "files": [
     "bin",
     "dist",
+    "skill",
     "types"
   ],
   "keywords": [],
   "author": "",
   "license": "ISC",
+  "dependencies": {
+    "cos-nodejs-sdk-v5": "2.15.4"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
@@ -47,10 +72,12 @@
     "get-port": "^7.1.0",
     "happy-dom": "^19.0.2",
     "open": "^10.2.0",
+    "picocolors": "^1.1.1",
     "rimraf": "^5.0.5",
     "rollup": "^4.52.4",
     "typescript": "^5.9.3",
     "vue": "2.7.16",
+    "vite": "^8.0.12",
     "vitest": "^3.2.4"
   },
   "publishConfig": {
@@ -84,9 +111,11 @@
     "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",
     "check:boundary": "node scripts/check-boundary.cjs",
+    "check:docs-sync": "node scripts/check-docs-sync.cjs",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",
+    "test:vite": "vitest run --config vitest.vite.config.ts",
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest"
   }
 }

package/skill/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: hb-sdk
+description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, and host/runtime protocol integration. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
+---
+
+# hb-sdk Agent Procedure
+
+Apply these instructions when writing, reviewing, or debugging code that consumes `@heybox/hb-sdk` or uses the companion `hb-sdk` CLI.
+
+## Step 1: Classify the task
+
+1. If the task is iframe mini-program business code, use the root package import path `@heybox/hb-sdk`.
+2. If the task is parent-container runtime, bridge-server, protocol contract, or `@heybox/hb-sdk-runtime` work, use `@heybox/hb-sdk/protocol` only for shared constants and types.
+3. If the task is project scaffolding, local Vite startup, browser mock runtime, CLI login cache, Agent Skill version diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
+4. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
+5. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, or protocol contracts, do not apply this skill.
+
+## Step 2: Load only the needed reference
+
+1. For root SDK imports, singleton usage, modules, and errors, read `references/api-root.md`.
+2. For host/runtime protocol contracts only, read `references/api-protocol.md`. Do not use this reference to build iframe business-code bridge messages.
+3. For common business flows, read `references/recipes.md`.
+4. For CLI commands, local mock runtime, generated templates, CLI login cache, Agent Skill doctor, and update reminders, read `references/cli.md`.
+5. For allowed/forbidden capabilities and security boundaries, read `references/safety-boundaries.md`.
+6. For Vite build manifest behavior, read `references/api-root.md` and `references/safety-boundaries.md`.
+7. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
+8. For smoke-test expectations, positive examples, and anti-examples, read `references/examples.md`.
+9. For evaluating whether another agent followed this skill, read `references/smoke-evaluation.md`.
+
+## Step 3: Follow import rules
+
+1. Import app-facing SDK APIs from `@heybox/hb-sdk`.
+2. Import protocol contracts from `@heybox/hb-sdk/protocol` only in host/runtime/protocol-maintenance code.
+3. Never import from internal hb-sdk implementation paths; only use the documented package entrypoints.
+4. Prefer named imports for focused code and the default `hbSDK` singleton for compact page-level examples.
+
+## Step 4: Implement iframe mini-program code
+
+1. Call `await ready()` or `await hbSDK.ready()` near page startup when the page uses SDK capabilities.
+2. Use `user.getInfo()` to read current login state without triggering login.
+3. Use `auth.login()` only when the user action requires login.
+4. Handle `HbMiniProgramSDKError` for bridge/runtime/protocol failures.
+5. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
+6. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
+7. Call `destroy()` on independent instances created by `createMiniProgramSDK()` when they are no longer needed.
+
+## Step 5: Use CLI workflows
+
+1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
+2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host.
+3. Use `hb-sdk deploy` to build and publish the current project. It reads `package.json.heybox.miniProgramId`, runs the project's `build` script via the package manager auto-detected by lockfile, then uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`) and calls the publish API.
+4. Use `hb-sdk deploy --skip-build` only when the `dist/` directory is already prepared by an upstream CI stage. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
+5. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
+6. Use `--port`, `--mock-port`, `--host`, and `--no-open` when the default Vite/mock ports, host, or browser opening behavior need to be controlled.
+7. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache.
+8. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+9. 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`.
+10. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+11. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
+12. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+13. Do not pass `mini_program_id` as a CLI flag or environment variable; it must come from `package.json.heybox.miniProgramId`.
+14. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publishing is `@heybox/hb-sdk/miniapp-publish`.
+
+## Step 6: Preserve capability boundaries
+
+For iframe mini-program business code:
+
+1. Do not read or request tokens, cookies, phone numbers, or private credentials from the SDK.
+2. Do not expose raw share protocol fields, JS callbacks, activity reporting, custom buttons, post publishing, or upload-only flows.
+3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
+4. Do not pass raw host protocol fields through `network.request`; use only the public axios-like request config.
+5. Do not construct bridge envelopes, nonce logic, or raw `postMessage` calls.
+6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
+
+For CLI and local development:
+
+1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
+2. Do not use `hb-sdk login` as a workaround for iframe SDK authentication.
+3. Do not bypass `hb-sdk dev` by adding a second browser mock host.
+
+For host/runtime/protocol-maintenance code:
+
+1. Use `@heybox/hb-sdk/protocol` for shared constants and type contracts.
+2. Keep raw protocol details inside the host/runtime boundary; do not leak them into app-facing SDK examples or iframe business code.
+3. Keep bridge handshake and nonce behavior idempotent and compatible with existing SDK clients.
+
+## Step 7: Validate changes
+
+1. Run the nearest package tests and builds with repo-native commands when editing this repository.
+2. When modifying docs, skill instructions, CLI guidance, or public agent-skill sync points, start with:
+   - `pnpm --filter @heybox/hb-sdk run check:docs-sync`
+   - `cat packages/hb-sdk/DOC_SYNC_CHECKLIST.md`
+3. When modifying this repo's source skill at `packages/hb-sdk/skill` and preparing distributable artifacts, also run:
+   - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
+4. When modifying CLI, mock runtime, package exports, or package dependency direction, also run:
+   - `pnpm --filter @heybox/hb-sdk run check:boundary`
+   - `pnpm --filter @heybox/hb-sdk run test:unit`
+5. Inspect the generated zip before distribution:
+   - `unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'`
+6. When adding or modifying the deploy command or its upload pipeline, also run:
+   - `pnpm --filter @heybox/hb-sdk run check:boundary`
+   - `pnpm --filter @heybox/hb-sdk run test:unit`
+   - Verify `dist/cli.cjs` does not have any `require('cos-nodejs-sdk-v5')` left after `build:cli`; the boundary check enforces this automatically.
+6. Verify public payload sync before publishing:
+   - `pnpm --filter @heybox-spa/open run sync:agent-skills`
+   - `pnpm --filter @heybox-spa/open run check:agent-skills`

package/skill/references/api-protocol.md

@@ -0,0 +1,135 @@
+# Protocol API 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.
+
+## Sources
+
+- packages/hb-sdk/src/protocol.ts
+- packages/hb-sdk/README.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md
+
+## Contents
+
+- [Host/runtime-only warning](#hostruntime-only-warning)
+- [Public protocol entrypoint](#public-protocol-entrypoint)
+- [Protocol context](#protocol-context)
+- [Generated reference index](#generated-reference-index)
+## Host/runtime-only warning
+
+Use `@heybox/hb-sdk/protocol` only for parent-container runtime, bridge-server, protocol-contract, or `@heybox/hb-sdk-runtime` integration tasks. Iframe mini-program business code must use root SDK APIs and must not construct bridge envelopes, nonce handling, or raw `postMessage` flows.
+
+## Public protocol entrypoint
+
+```ts
+export {
+  MINI_PROGRAM_BRIDGE_NONCE_PARAM,
+  MINI_PROGRAM_MESSAGE_NAMESPACE,
+  MINI_PROGRAM_MESSAGE_VERSION,
+  SDK_HANDSHAKE_METHOD,
+} from './protocol/constants';
+export { isMiniProgramBridgeMessage } from './protocol/guards';
+export type {
+  MiniProgramBridgeError,
+  MiniProgramBridgeMessage,
+  MiniProgramBridgeMessageType,
+  MiniProgramEventHandler,
+  MiniProgramEventName,
+  MiniProgramEventPayloadMap,
+} from './protocol/types';
+export {
+  AUTH_LOGIN_METHOD,
+  MINI_PROGRAM_PROTOCOL_CAPABILITIES,
+  NETWORK_REQUEST_METHOD,
+  SHARE_SCREENSHOT_METHOD,
+  SHARE_SHOW_SHARE_MENU_METHOD,
+  STORAGE_GET_STORAGE_METHOD,
+  STORAGE_SET_STORAGE_METHOD,
+  USER_GET_INFO_METHOD,
+  VIEWPORT_GET_WINDOW_INFO_METHOD,
+} from './protocol/capabilities';
+export type {
+  MiniProgramAuthMethod,
+  MiniProgramBridgeMethod,
+  MiniProgramCapabilityDefinition,
+  MiniProgramCapabilityModule,
+  MiniProgramCapabilityPayload,
+  MiniProgramCapabilityPayloadMap,
+  MiniProgramCapabilityResult,
+  MiniProgramCapabilityResultMap,
+  MiniProgramCapabilityRisk,
+  MiniProgramNetworkMethod,
+  MiniProgramShareMethod,
+  MiniProgramStorageMethod,
+  MiniProgramUserMethod,
+  MiniProgramViewportMethod,
+} from './protocol/capabilities';
+export type { LoginPayload, LoginResult } from './modules/auth';
+export type {
+  GetUserInfoPayload,
+  GetUserInfoResult,
+  MiniProgramUserInfo,
+  MiniProgramUserInfoResult,
+} from './modules/user';
+export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
+export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';
+export type {
+  MiniProgramScreenshotOptions,
+  MiniProgramScreenshotRect,
+  MiniProgramShareChannel,
+  MiniProgramShowShareMenuOptions,
+} from './modules/share';
+export type {
+  GetStoragePayload,
+  GetStorageResult,
+  SetStoragePayload,
+} from './modules/storage';
+export type {
+  GetWindowInfoPayload,
+  GetWindowInfoResult,
+  MiniProgramSafeArea,
+  MiniProgramWindowInfoResult,
+} from './modules/viewport';
+export type {
+  MiniProgramNetworkHeaders,
+  MiniProgramNetworkParams,
+  MiniProgramNetworkRequestConfig,
+  MiniProgramNetworkRequestMethod,
+  MiniProgramNetworkResponse,
+  MiniProgramNetworkValidateStatus,
+  NetworkRequestPayload,
+  NetworkResponsePayload,
+} from './modules/network';
+```
+
+## Protocol context
+
+## SDK 与 Runtime
+
+`@heybox/hb-sdk` 跑在 iframe 内部，由外部小程序业务页面使用。`@heybox/hb-sdk-runtime` 跑在 iframe 外部，由黑盒宿主壳层使用，负责启动 iframe、注入 nonce、维护 bridge server、注册能力 handler、转发宿主生命周期与登录态变化。
+
+两者共享同一套 bridge 协议。协议字段、事件名或能力 payload 发生变化时，应按同一批次联动升级 SDK 与 runtime；不要只升级其中一侧后假定另一侧自动兼容。
+
+## Generated reference index
+
+
+# Reference
+
+Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
+
+| 导出面 | 说明 |
+| --- | --- |
+| [Root API](./root/README.md) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
+| [Protocol API](./protocol/README.md) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
+
+## 查询建议
+
+- 想查业务接入路径：先看 [Guide](../guide/README.md)。
+- 想查导出符号：从 Root API 或 Protocol API 进入对应分类页。
+- 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
+
+## 统计
+
+| 导出面 | Classes | Functions | Interfaces | Types | Constants |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Root API | 3 | 5 | 28 | 29 | 12 |
+| Protocol API | 0 | 1 | 20 | 29 | 13 |