@heybox/hb-sdk 0.5.11 → 0.5.12

package/README.md

@@ -330,7 +330,7 @@ await network.request({
 
 ## 生命周期事件
 
-使用 `on()` 监听父容器派发的小程序事件。`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
 
 ```ts
 import { on } from '@heybox/hb-sdk';
@@ -516,7 +516,8 @@ CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe
 
 ## 能力边界
 
-- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
+- SDK 实例创建后会自动开始握手；默认单例仍按需懒创建，`ready()`、`on()` 或任意模块能力调用都会创建默认单例并开始握手。
+- `ready()` 只等待已有握手结果，不主动触发新的握手；调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()`、`user.getCurrentUserDetail()`、`user.getCurrentUserProfile()`、`user.getPlatformAccountOverview()`、`user.getPlatformAccountInfo(platform)` 和 `user.getSteamGameList(options)` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
 - 当前用户详情和平台账号 API 只允许读取当前登录用户，不支持传入 `userid` 查询其他人，也不透传 `/account/home_v2/` 原始响应。
 - 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
@@ -580,9 +581,9 @@ export default defineConfig({
 pnpm --filter @heybox/hb-sdk run test:unit
 pnpm --filter @heybox/hb-sdk run build:package
 pnpm --filter @heybox/hb-sdk run check:boundary
-pnpm --filter @heybox/hb-sdk run check:docs-sync
+pnpm exec hbexec hb-sdk check
 ```
 
 `check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。
 
-`check:docs-sync` 用于校验 `README`、文档站 llms 镜像、skill references 与公开 `agent-skills` payload 没有漏同步。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。
+`hbexec hb-sdk check` 只读校验 docs、skill references，并在临时目录生成与校验 `agent-skills` payload；不要求 canonical artifact 已存在，也不包含 changelog。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。

package/dist/cli-chunks/{create-BaqN3jeW.cjs → create-Ba353lSg.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-BROIiSNN.cjs');
+var index = require('./index-DeamIV1-.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-DUZgcgYE.cjs → dev-BhPFNef-.cjs}

@@ -9,7 +9,7 @@ var node_url = require('node:url');
 var net = require('node:net');
 var node_http = require('node:http');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-BROIiSNN.cjs');
+var index = require('./index-DeamIV1-.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');

package/dist/cli-chunks/{doctor-DUjQij7b.cjs → doctor-CP4kwgAn.cjs}

@@ -4,7 +4,7 @@ var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-BROIiSNN.cjs');
+var index = require('./index-DeamIV1-.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-6W5M4MLF.cjs → index-BfpHPA6k.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-BROIiSNN.cjs');
+var index$2 = require('./index-DeamIV1-.cjs');
 var require$$0$2 = require('fs');
 var require$$2$1 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$3 = require('assert');
 var require$$4$2 = require('events');
 var require$$1$1 = require('util');
-var remote = require('./remote-ChGmIJC1.cjs');
+var remote = require('./remote-gXUjRvGB.cjs');
 var require$$0$5 = require('net');
 var require$$0$4 = require('url');
 var require$$2$2 = require('http');

package/dist/cli-chunks/{index-BROIiSNN.cjs → index-DeamIV1-.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BROIiSNN.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-DeamIV1-.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BROIiSNN.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-DeamIV1-.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BROIiSNN.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-DeamIV1-.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BROIiSNN.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-DeamIV1-.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BROIiSNN.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-DeamIV1-.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13094,7 +13094,7 @@ function readErrorMessage(error, options = {}) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.5.11';
+const BUILT_CLI_VERSION = '0.5.12';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13411,31 +13411,31 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-BejyA1mX.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DMNap0-y.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-BejyA1mX.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DMNap0-y.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-BejyA1mX.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DMNap0-y.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BaqN3jeW.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-Ba353lSg.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DUZgcgYE.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-BhPFNef-.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DUjQij7b.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-CP4kwgAn.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-ChGmIJC1.cjs'); }).then(function (n) { return n.remote; });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-gXUjRvGB.cjs'); }).then(function (n) { return n.remote; });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{login-BejyA1mX.cjs → login-DMNap0-y.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-jHF9KWBo.cjs');
+var session = require('./session-D5Vf-fNZ.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-BROIiSNN.cjs');
+var index = require('./index-DeamIV1-.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{remote-ChGmIJC1.cjs → remote-gXUjRvGB.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var session = require('./session-jHF9KWBo.cjs');
+var session = require('./session-D5Vf-fNZ.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
-var index = require('./index-BROIiSNN.cjs');
+var index = require('./index-DeamIV1-.cjs');
 
 var re = {exports: {}};
 
@@ -3115,7 +3115,7 @@ async function createDefaultCosClient(uploadToken) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-6W5M4MLF.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-BfpHPA6k.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{session-jHF9KWBo.cjs → session-D5Vf-fNZ.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-BROIiSNN.cjs');
+var index = require('./index-DeamIV1-.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-BROIiSNN.cjs');
+var index = require('./cli-chunks/index-DeamIV1-.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');

package/dist/index.cjs.js

@@ -211,6 +211,8 @@ class MiniProgramBridgeClient {
     readyTimer;
     handshakeRetryTimer;
     destroyed = false;
+    runtimeUnavailable = false;
+    runtimeUnavailableError;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -224,15 +226,14 @@ class MiniProgramBridgeClient {
             this.rejectReady = reject;
         });
         this.readyPromise.catch(() => undefined);
+        this.ensureStarted();
     }
     /** 等待父容器握手完成。 */
     ready() {
-        this.ensureStarted();
         return this.readyPromise;
     }
     /** 注册小程序事件监听。 */
     on(eventName, handler) {
-        this.ensureStarted();
         return this.eventBus.on(eventName, handler);
     }
     /** 移除小程序事件监听。 */
@@ -241,7 +242,19 @@ class MiniProgramBridgeClient {
     }
     /** 调用父容器开放能力。 */
     async request(method, ...args) {
+        if (this.destroyed) {
+            throw createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
+        }
+        if (this.runtimeUnavailable) {
+            throw this.getRuntimeUnavailableError();
+        }
         await this.ready();
+        if (this.destroyed) {
+            throw createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
+        }
+        if (this.runtimeUnavailable) {
+            throw this.getRuntimeUnavailableError();
+        }
         const payload = args[0];
         const id = createMessageId();
         const message = {
@@ -286,6 +299,10 @@ class MiniProgramBridgeClient {
             this.failReady(createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁'));
             return;
         }
+        if (this.runtimeUnavailable) {
+            this.failReady(this.getRuntimeUnavailableError());
+            return;
+        }
         if (this.started) {
             return;
         }
@@ -305,7 +322,14 @@ class MiniProgramBridgeClient {
         try {
             this.postHandshake();
             this.handshakeRetryTimer = setInterval(() => {
-                this.postHandshake();
+                try {
+                    this.postHandshake();
+                }
+                catch (error) {
+                    this.failReady(error instanceof HbMiniProgramSDKError
+                        ? error
+                        : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
+                }
             }, HANDSHAKE_RETRY_INTERVAL);
         }
         catch (error) {
@@ -348,7 +372,10 @@ class MiniProgramBridgeClient {
     }
     handleEvent(message) {
         const eventName = message.method;
-        if (eventName === 'ready') {
+        if (eventName === 'unload') {
+            this.markRuntimeUnavailable();
+        }
+        else if (eventName === 'ready' && !this.runtimeUnavailable) {
             this.resolveReadyOnce();
         }
         this.eventBus.emit(eventName, message.payload);
@@ -401,6 +428,22 @@ class MiniProgramBridgeClient {
             this.handshakeRetryTimer = undefined;
         }
     }
+    markRuntimeUnavailable() {
+        if (this.runtimeUnavailable) {
+            return;
+        }
+        const error = this.getRuntimeUnavailableError();
+        this.runtimeUnavailable = true;
+        this.clearReadyTimers();
+        this.failReady(error);
+        this.rejectAllPending(error);
+    }
+    getRuntimeUnavailableError() {
+        if (!this.runtimeUnavailableError) {
+            this.runtimeUnavailableError = createSDKError('RUNTIME_UNAVAILABLE', '小程序运行时已卸载');
+        }
+        return this.runtimeUnavailableError;
+    }
     rejectAllPending(error) {
         this.pendingRequests.forEach(pending => {
             clearTimeout(pending.timer);

package/dist/index.esm.js

@@ -207,6 +207,8 @@ class MiniProgramBridgeClient {
     readyTimer;
     handshakeRetryTimer;
     destroyed = false;
+    runtimeUnavailable = false;
+    runtimeUnavailableError;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -220,15 +222,14 @@ class MiniProgramBridgeClient {
             this.rejectReady = reject;
         });
         this.readyPromise.catch(() => undefined);
+        this.ensureStarted();
     }
     /** 等待父容器握手完成。 */
     ready() {
-        this.ensureStarted();
         return this.readyPromise;
     }
     /** 注册小程序事件监听。 */
     on(eventName, handler) {
-        this.ensureStarted();
         return this.eventBus.on(eventName, handler);
     }
     /** 移除小程序事件监听。 */
@@ -237,7 +238,19 @@ class MiniProgramBridgeClient {
     }
     /** 调用父容器开放能力。 */
     async request(method, ...args) {
+        if (this.destroyed) {
+            throw createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
+        }
+        if (this.runtimeUnavailable) {
+            throw this.getRuntimeUnavailableError();
+        }
         await this.ready();
+        if (this.destroyed) {
+            throw createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
+        }
+        if (this.runtimeUnavailable) {
+            throw this.getRuntimeUnavailableError();
+        }
         const payload = args[0];
         const id = createMessageId();
         const message = {
@@ -282,6 +295,10 @@ class MiniProgramBridgeClient {
             this.failReady(createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁'));
             return;
         }
+        if (this.runtimeUnavailable) {
+            this.failReady(this.getRuntimeUnavailableError());
+            return;
+        }
         if (this.started) {
             return;
         }
@@ -301,7 +318,14 @@ class MiniProgramBridgeClient {
         try {
             this.postHandshake();
             this.handshakeRetryTimer = setInterval(() => {
-                this.postHandshake();
+                try {
+                    this.postHandshake();
+                }
+                catch (error) {
+                    this.failReady(error instanceof HbMiniProgramSDKError
+                        ? error
+                        : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
+                }
             }, HANDSHAKE_RETRY_INTERVAL);
         }
         catch (error) {
@@ -344,7 +368,10 @@ class MiniProgramBridgeClient {
     }
     handleEvent(message) {
         const eventName = message.method;
-        if (eventName === 'ready') {
+        if (eventName === 'unload') {
+            this.markRuntimeUnavailable();
+        }
+        else if (eventName === 'ready' && !this.runtimeUnavailable) {
             this.resolveReadyOnce();
         }
         this.eventBus.emit(eventName, message.payload);
@@ -397,6 +424,22 @@ class MiniProgramBridgeClient {
             this.handshakeRetryTimer = undefined;
         }
     }
+    markRuntimeUnavailable() {
+        if (this.runtimeUnavailable) {
+            return;
+        }
+        const error = this.getRuntimeUnavailableError();
+        this.runtimeUnavailable = true;
+        this.clearReadyTimers();
+        this.failReady(error);
+        this.rejectAllPending(error);
+    }
+    getRuntimeUnavailableError() {
+        if (!this.runtimeUnavailableError) {
+            this.runtimeUnavailableError = createSDKError('RUNTIME_UNAVAILABLE', '小程序运行时已卸载');
+        }
+        return this.runtimeUnavailableError;
+    }
     rejectAllPending(error) {
         this.pendingRequests.forEach(pending => {
             clearTimeout(pending.timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.5.11",
+  "version": "0.5.12",
   "description": "",
   "exports": {
     ".": {
@@ -116,9 +116,7 @@
     "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",
-    "sync:agent-skills-payload": "node skill/scripts/sync-agent-skills-payload.mjs",
-    "check:agent-skills-payload": "node skill/scripts/sync-agent-skills-payload.mjs --check",
+    "check:docs-sync": "pnpm -w exec hbexec hb-sdk check",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",

package/skill/SKILL.md

@@ -118,6 +118,7 @@ For host/runtime/protocol-maintenance code:
    - `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.
-8. Verify public payload sync before publishing:
-   - `pnpm --filter @heybox-spa/open run sync:agent-skills`
-   - `pnpm --filter @heybox-spa/open run check:agent-skills`
+8. Verify the canonical payload before publishing:
+   - `pnpm exec hbexec hb-sdk sync`
+   - `pnpm exec hbexec hb-sdk check`
+   - For a release artifact, run `pnpm exec hbexec hb-sdk sync --out-dir <payload-dir>` and then `pnpm exec hbexec hb-sdk check-artifact --artifact-dir <payload-dir>`.

package/skill/references/api-protocol.md

@@ -6,7 +6,7 @@
 
 - packages/hb-sdk/src/protocol.ts
 - packages/hb-sdk/README.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md
+- apps/docs/hb-sdk/reference/index.md
 
 ## Contents
 
@@ -197,16 +197,16 @@ export type {
 
 # Reference
 
-Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
+Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
 
 | 导出面 | 说明 |
 | --- | --- |
-| [Root API](./root/README.md) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
-| [Protocol API](./protocol/README.md) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
+| [Root API](./root/) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
+| [Protocol API](./protocol/) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
 
 ## 查询建议
 
-- 想查业务接入路径：先看 [Guide](../guide/README.md)。
+- 想查业务接入路径：先看 [Guide](../guide/)。
 - 想查导出符号：从 Root API 或 Protocol API 进入对应分类页。
 - 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
 
@@ -214,5 +214,5 @@ Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 3 | 4 | 53 | 45 | 3 |
-| Protocol API | 0 | 1 | 30 | 57 | 26 |
+| Root API | 3 | 4 | 67 | 57 | 4 |
+| Protocol API | 0 | 1 | 39 | 66 | 32 |

package/skill/references/api-root.md

@@ -640,7 +640,7 @@ await network.request({
 
 ## 生命周期事件
 
-使用 `on()` 监听父容器派发的小程序事件。`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
 
 ```ts
 import { on } from '@heybox/hb-sdk';

package/skill/references/cli.md

@@ -10,7 +10,7 @@
 - packages/hb-sdk/src/cli/commands/dev.ts
 - packages/hb-sdk/src/cli/commands/login.ts
 - packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs
-- apps/h5/docs/hb_sdk/src/guide/cli.md
+- apps/docs/hb-sdk/guide/cli.md
 - packages/hb-sdk/README.md
 
 ## Contents
@@ -348,12 +348,12 @@ Agent rules:
 pnpm --filter @heybox/hb-sdk run test:unit
 pnpm --filter @heybox/hb-sdk run build:package
 pnpm --filter @heybox/hb-sdk run check:boundary
-pnpm --filter @heybox/hb-sdk run check:docs-sync
+pnpm exec hbexec hb-sdk check
 ```
 
 `check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。
 
-`check:docs-sync` 用于校验 `README`、文档站 llms 镜像、skill references 与公开 `agent-skills` payload 没有漏同步。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。
+`hbexec hb-sdk check` 只读校验 docs、skill references，并在临时目录生成与校验 `agent-skills` payload；不要求 canonical artifact 已存在，也不包含 changelog。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。
 
 ## Generated template README
 

package/skill/references/examples.md

@@ -5,7 +5,8 @@
 ## Sources
 
 - packages/hb-sdk/README.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/
+- apps/docs/hb-sdk/guide/**
+- apps/docs/hb-sdk/recipes/**
 ## Positive examples
 
 ### Minimal user info

package/skill/references/llms-index.md

@@ -4,42 +4,21 @@
 
 ## Sources
 
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/
-## Local generated docs entrypoint
+- apps/docs/hb-sdk/guide/**
+- apps/docs/hb-sdk/recipes/**
+- apps/docs/hb-sdk/reference/**
+- packages/hb-sdk/src/**
+## Offline references
 
-The docs site maintains `llms.txt` and markdown mirrors under `apps/h5/docs/hb_sdk/src/.vuepress/public/llms/`. Read `llms.txt` first for navigation, then the specific guide/reference/recipe markdown needed for the task.
+The bundled references are generated directly from hand-maintained docs, generated API owner sources, and SDK/CLI sources. They do not depend on the docs site's `.vitepress/public/llms` mirrors.
 
-```md
-# @heybox/hb-sdk
-> LLM-friendly index for the `@heybox/hb-sdk` documentation site. API Reference is auto-generated from public exports and source comments; Guide and Recipes are hand-maintained.
-This site documents the iframe-side SDK for external mini programs. For AI retrieval, fetch this index first, then follow the linked markdown mirrors under `./llms/`.
-## Docs
-- [Documentation home](./llms/README.md): 第一次接入时，按下面顺序读：
-- [Guide index](./llms/guide/README.md): Guide 面向第一次接入 `@heybox/hb-sdk` 的开发者，目标是先跑通，再理解边界。
-- [Reference index](./llms/reference/README.md): Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
-- [Recipes index](./llms/recipes/README.md): Recipes 放可以直接复制到业务里的场景写法。它比 Guide 更具体，比 Reference 更偏组合使用。
-- [LLM usage guide](./llms/guide/llms.md): 文档站会自动维护一份标准的 `llms.txt` 索引，以及一组给 AI 直接读取的 Markdown 镜像页，方便模型按文档树逐步抓取内容。
-## API Reference
-- [Root API](./llms/reference/root/README.md): 该页面收录从 `src/index.ts` 公开导出的 API。
-- [Protocol API](./llms/reference/protocol/README.md): 该页面收录从 `src/protocol.ts` 公开导出的 API。
-- [Root functions](./llms/reference/root/functions/README.md)
-- [Root interfaces](./llms/reference/root/interfaces/README.md): `on/off` 会基于该映射推导 handler 参数类型。 |
-- [Protocol interfaces](./llms/reference/protocol/interfaces/README.md): 所有请求失败都会被规范化成该结构，SDK 侧再包装为 `HbMiniProgramSDKError`。 |
-- [Root types](./llms/reference/root/types/README.md): `navigation.close` 不需要入参。
-- [Protocol types](./llms/reference/protocol/types/README.md): `navigation.close` 不需要入参。
-## Guides
-- [Agent Skill 安装](./llms/guide/agent-skill.md): `hb-sdk` Agent Skill 用来让 AI / Agent 按本仓库约定使用 `@heybox/hb-sdk` 和配套 `hb-sdk` CLI，包括 iframe 小程序接入、`ready`、用户信息、登录、事件、CLI 创建模板、`hb-sdk dev` 本地调试、CLI 登录态、协议边界和常见错误处理。
-- [用户与登录](./llms/guide/auth.md): 用户与授权模块当前分工：
-- [CLI 与本地 mock 调试](./llms/guide/cli.md): `@heybox/hb-sdk` 同时提供 iframe 内使用的 SDK 和配套 `hb-sdk` CLI。CLI 负责项目模板、本地 Vite 服务、浏览器 mock runtime host 和 CLI 自己的 Heybox 登录缓存；它不是 iframe SDK 登录态的替代品。
-- [错误处理](./llms/guide/error-handling.md): SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
-- [安装与运行环境](./llms/guide/installation.md): 如果工坊小程序只是普通展示页面，不调用黑盒开放能力，也不监听 SDK 生命周期事件，可以不安装、不引用、不初始化 `@heybox/hb-sdk`。父容器仍可能在 URL 上注入 `hb_mini_bridge_nonce`，业务页可以直接忽略。
-- [事件与生命周期](./llms/guide/lifecycle.md): SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
-- [小程序工坊上架规则 v2（试行）](./llms/guide/mini-program-publishing-rules.md): 本规则用于说明小程序工坊的小程序发布、上架和持续在线要求。通过审核不等于获得推荐或公开展示；工坊广场、推荐位、搜索等流量分发规则另行制定。
-- [快速开始](./llms/guide/quick-start.md): 如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
-## Recipes
-- [独立 SDK 实例](./llms/recipes/custom-instance.md): 大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。
-- [登录门禁](./llms/recipes/login-gate.md): 当业务动作必须登录后才能继续时，可以把登录态判断收敛成 `ensureLogin`。
-## Optional
-- Full markdown mirrors for the docs site are available under `./llms/guide/`, `./llms/reference/`, and `./llms/recipes/`.
-```
+- Root SDK and Vite API: `references/api-root.md`
+- Host/runtime protocol API: `references/api-protocol.md`
+- CLI and local development: `references/cli.md`
+- Common flows: `references/recipes.md`
+- Security and capability limits: `references/safety-boundaries.md`
+- Examples and evaluation: `references/examples.md`, `references/smoke-evaluation.md`
+
+## Online supplement
+
+Online `llms.txt` and markdown mirrors are optional supplements, not prerequisites for offline Skill use. Their canonical public URL is not frozen: on 2026-07-10 `https://docs.xiaoheihe.cn/hb_sdk/llms.txt` returned 404 and the legacy URL fetch timed out. Do not claim either endpoint is available without a fresh successful response.

package/skill/references/recipes.md

@@ -4,12 +4,12 @@
 
 ## Sources
 
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md
+- apps/docs/hb-sdk/guide/quick-start.md
+- apps/docs/hb-sdk/guide/auth.md
+- apps/docs/hb-sdk/guide/lifecycle.md
+- apps/docs/hb-sdk/guide/error-handling.md
+- apps/docs/hb-sdk/recipes/login-gate.md
+- apps/docs/hb-sdk/recipes/custom-instance.md
 
 ## Contents
 
@@ -76,7 +76,7 @@ stopAuthChange()
 
 默认单例适合一个页面只有一个 SDK 上下文的情况。大多数小程序页面都应该使用默认单例，因为它可以避免重复握手和重复维护事件监听。
 
-需要控制 `timeout`、注入测试 window 或隔离多个上下文时，再使用 [独立实例](../recipes/custom-instance.md)。
+需要控制 `timeout`、注入测试 window 或隔离多个上下文时，再使用 [独立实例](../recipes/custom-instance)。
 
 ## User and login
 
@@ -193,8 +193,8 @@ stop()
 
 完整载荷与事件名见：
 
-- [MiniProgramEventPayloadMap](../reference/protocol/interfaces/MiniProgramEventPayloadMap.md)
-- [MiniProgramEventName](../reference/protocol/types/README.md#miniprogrameventname)
+- [MiniProgramEventPayloadMap](../reference/protocol/interfaces/MiniProgramEventPayloadMap)
+- [MiniProgramEventName](../reference/protocol/types/#miniprogrameventname)
 
 ## 生命周期建议
 

package/skill/references/safety-boundaries.md

@@ -5,12 +5,13 @@
 ## Sources
 
 - packages/hb-sdk/README.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md
+- apps/docs/hb-sdk/guide/auth.md
 ## Required boundaries
 
 ## 能力边界
 
-- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
+- SDK 实例创建后会自动开始握手；默认单例仍按需懒创建，`ready()`、`on()` 或任意模块能力调用都会创建默认单例并开始握手。
+- `ready()` 只等待已有握手结果，不主动触发新的握手；调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()`、`user.getCurrentUserDetail()`、`user.getCurrentUserProfile()`、`user.getPlatformAccountOverview()`、`user.getPlatformAccountInfo(platform)` 和 `user.getSteamGameList(options)` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
 - 当前用户详情和平台账号 API 只允许读取当前登录用户，不支持传入 `userid` 查询其他人，也不透传 `/account/home_v2/` 原始响应。
 - 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。

package/skill/scripts/sync-references.mjs

@@ -177,16 +177,14 @@ const viteEntry = read('packages/hb-sdk/src/vite/index.ts');
 const cliEntry = read('packages/hb-sdk/src/cli/index.ts');
 const cliTemplateReadme = read('packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs');
 const readme = read('packages/hb-sdk/README.md');
-const cliGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/guide/cli.md'));
-const llmsTxt = read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt');
-const quickStart = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md')); 
-const authGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md')); 
-const lifecycleGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md')); 
-const errorGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md')); 
-const loginGate = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md')); 
-const customInstance = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md')); 
-const referenceHome = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md'));
-
+const cliGuide = frontmatterless(read('apps/docs/hb-sdk/guide/cli.md'));
+const quickStart = frontmatterless(read('apps/docs/hb-sdk/guide/quick-start.md'));
+const authGuide = frontmatterless(read('apps/docs/hb-sdk/guide/auth.md'));
+const lifecycleGuide = frontmatterless(read('apps/docs/hb-sdk/guide/lifecycle.md'));
+const errorGuide = frontmatterless(read('apps/docs/hb-sdk/guide/error-handling.md'));
+const loginGate = frontmatterless(read('apps/docs/hb-sdk/recipes/login-gate.md'));
+const customInstance = frontmatterless(read('apps/docs/hb-sdk/recipes/custom-instance.md'));
+const referenceHome = frontmatterless(read('apps/docs/hb-sdk/reference/index.md'));
 const quickStartSection = extractSection(readme, '## 快速开始');
 const runtimeEnvironment = extractSection(readme, '## 运行环境');
 const publicCapabilities = extractSection(readme, '## 常用能力');
@@ -300,7 +298,7 @@ ${lifecycleEvents}
 files.set('api-protocol.md', `${header('Protocol API reference', [
   'packages/hb-sdk/src/protocol.ts',
   'packages/hb-sdk/README.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md',
+  'apps/docs/hb-sdk/reference/index.md',
 ])}${contents([
   ['Host/runtime-only warning', 'hostruntime-only-warning'],
   ['Public protocol entrypoint', 'public-protocol-entrypoint'],
@@ -330,7 +328,7 @@ files.set('cli.md', `${header('CLI reference', [
   'packages/hb-sdk/src/cli/commands/dev.ts',
   'packages/hb-sdk/src/cli/commands/login.ts',
   'packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs',
-  'apps/h5/docs/hb_sdk/src/guide/cli.md',
+  'apps/docs/hb-sdk/guide/cli.md',
   'packages/hb-sdk/README.md',
 ])}${contents([
   ['When to use the CLI', 'when-to-use-the-cli'],
@@ -463,12 +461,12 @@ ${fenced('md', cliTemplateReadme)}
 `);
 
 files.set('recipes.md', `${header('Recipes', [
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md',
+  'apps/docs/hb-sdk/guide/quick-start.md',
+  'apps/docs/hb-sdk/guide/auth.md',
+  'apps/docs/hb-sdk/guide/lifecycle.md',
+  'apps/docs/hb-sdk/guide/error-handling.md',
+  'apps/docs/hb-sdk/recipes/login-gate.md',
+  'apps/docs/hb-sdk/recipes/custom-instance.md',
 ])}${contents([
   ['Quick start', 'quick-start'],
   ['User and login', 'user-and-login'],
@@ -503,7 +501,7 @@ ${customInstance}
 
 files.set('safety-boundaries.md', `${header('Safety boundaries', [
   'packages/hb-sdk/README.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md',
+  'apps/docs/hb-sdk/guide/auth.md',
 ])}## Required boundaries
 
 ${capabilityBoundaries}
@@ -521,18 +519,30 @@ ${capabilityBoundaries}
 `);
 
 files.set('llms-index.md', `${header('LLM documentation index', [
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/',
-])}## Local generated docs entrypoint
+  'apps/docs/hb-sdk/guide/**',
+  'apps/docs/hb-sdk/recipes/**',
+  'apps/docs/hb-sdk/reference/**',
+  'packages/hb-sdk/src/**',
+])}## Offline references
+
+The bundled references are generated directly from hand-maintained docs, generated API owner sources, and SDK/CLI sources. They do not depend on the docs site's \`.vitepress/public/llms\` mirrors.
+
+- Root SDK and Vite API: \`references/api-root.md\`
+- Host/runtime protocol API: \`references/api-protocol.md\`
+- CLI and local development: \`references/cli.md\`
+- Common flows: \`references/recipes.md\`
+- Security and capability limits: \`references/safety-boundaries.md\`
+- Examples and evaluation: \`references/examples.md\`, \`references/smoke-evaluation.md\`
 
-The docs site maintains \`llms.txt\` and markdown mirrors under \`apps/h5/docs/hb_sdk/src/.vuepress/public/llms/\`. Read \`llms.txt\` first for navigation, then the specific guide/reference/recipe markdown needed for the task.
+## Online supplement
 
-${fenced('md', llmsTxt)}
+Online \`llms.txt\` and markdown mirrors are optional supplements, not prerequisites for offline Skill use. Their canonical public URL is not frozen: on 2026-07-10 \`https://docs.xiaoheihe.cn/hb_sdk/llms.txt\` returned 404 and the legacy URL fetch timed out. Do not claim either endpoint is available without a fresh successful response.
 `);
 
 files.set('examples.md', `${header('Smoke examples and anti-examples', [
   'packages/hb-sdk/README.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/',
+  'apps/docs/hb-sdk/guide/**',
+  'apps/docs/hb-sdk/recipes/**',
 ])}## Positive examples
 
 ### Minimal user info

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.11+skill.20c209340580",
+  "skillVersion": "0.5.11+skill.c0b2205c74df",
   "sdk": {
     "package": "@heybox/hb-sdk",
     "version": "0.5.11",
     "compatibility": "0.5.11"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-20c209340580ee5507bb72eb8cd044693b29e109472e93fc3d8302a53b4770d2"
+  "integrity": "sha256-c0b2205c74df6a619a08d4f9a974d89a796d1783cc30a1d698d875bd179fd8c3"
 }

package/types/core/client.d.ts

@@ -42,6 +42,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private readyTimer?;
     private handshakeRetryTimer?;
     private destroyed;
+    private runtimeUnavailable;
+    private runtimeUnavailableError?;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     ready(): Promise<void>;
@@ -62,6 +64,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private resolveReadyOnce;
     private failReady;
     private clearReadyTimers;
+    private markRuntimeUnavailable;
+    private getRuntimeUnavailableError;
     private rejectAllPending;
 }
 export {};