@heybox/hb-sdk 0.3.1 → 0.3.3

package/README.md

@@ -13,7 +13,7 @@ npm install
 npm run dev
 ```
 
-模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。
 
 在已有项目中安装：
 
@@ -57,7 +57,7 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 
@@ -240,8 +240,9 @@ try {
    }
    ```
 2. 已运行过 `hb-sdk login` 登录 Heybox。
-3. 项目根有 `scripts.build`，会被 CLI 通过 lockfile 自动选用的 `pnpm`、`yarn` 或 `npm` 触发；无 lockfile 时回退 `npm`。
-4. 构建产物落在 `dist/`，包含 `index.html` 和 `manifest.json`。
+3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
+4. 项目根有 `scripts.build`，会被 CLI 通过 lockfile 自动选用的 `pnpm`、`yarn` 或 `npm` 触发；无 lockfile 时回退 `npm`。
+5. 构建产物落在 `dist/`，包含 `index.html` 和 `manifest.json`。
 
 执行流程：
 

package/dist/cli.cjs

@@ -75856,6 +75856,7 @@ const MOCK_HOST_ROOT_CANDIDATES = [
 ];
 async function startMiniProgramMockHostServer(options) {
     const root = options.root ?? resolveMiniProgramMockHostRoot(options.rootCandidates);
+    assertCompleteMiniProgramMockHostRoot(root);
     const server = createMiniProgramMockHostServer(root, {
         fetchImpl: options.fetchImpl ?? fetch,
     });
@@ -75878,12 +75879,23 @@ async function startMiniProgramMockHostServer(options) {
     };
 }
 function resolveMiniProgramMockHostRoot(candidates = MOCK_HOST_ROOT_CANDIDATES) {
-    const found = candidates.find((candidate) => fs$4.existsSync(path.join(candidate, 'index.html')));
+    const found = candidates.find(isCompleteMiniProgramMockHostRoot);
     if (!found) {
-        throw new Error('未找到 hb-sdk mock host 静态产物。请先执行 @heybox/hb-sdk 的 build:mock-host。');
+        throw createMissingMockHostError();
     }
     return found;
 }
+function assertCompleteMiniProgramMockHostRoot(root) {
+    if (!isCompleteMiniProgramMockHostRoot(root)) {
+        throw createMissingMockHostError();
+    }
+}
+function isCompleteMiniProgramMockHostRoot(root) {
+    return fs$4.existsSync(path.join(root, 'index.html')) && fs$4.existsSync(path.join(root, 'main.js'));
+}
+function createMissingMockHostError() {
+    return new Error('未找到完整的 hb-sdk mock host 静态产物。请先执行 @heybox/hb-sdk 的 build:mock-host。');
+}
 function createMiniProgramMockHostUrl(options) {
     const url = new URL(`http://${toDisplayHost$1(options.host)}:${options.port}/`);
     url.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, options.appUrl);
@@ -76875,6 +76887,7 @@ function hasPackageDependency(packageJson, name) {
 function createViteServerOptions(projectRoot, options) {
     const configFile = resolveProjectViteConfig(projectRoot);
     const server = {
+        cors: true,
         host: options.host,
         port: options.port ?? DEFAULT_APP_PORT,
         strictPort: false,
@@ -77559,7 +77572,7 @@ async function pathExists$1(filePath) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.3.1';
+const BUILT_CLI_VERSION = '0.3.3';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),

package/dist/devtools/mock-host/index.html

@@ -102,6 +102,65 @@
         background: #2563eb;
       }
 
+      .mac-app-status {
+        display: grid;
+        gap: 8px;
+        margin-top: 10px;
+        color: #475569;
+        font-size: 12px;
+        line-height: 1.5;
+      }
+
+      .mac-app-status[hidden] {
+        display: none;
+      }
+
+      .debug-page-url {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) 32px;
+        align-items: center;
+        gap: 8px;
+      }
+
+      .debug-page-url code {
+        min-width: 0;
+        overflow-wrap: anywhere;
+        word-break: break-word;
+        border: 1px solid #d7dee8;
+        border-radius: 6px;
+        padding: 7px 8px;
+        color: #1f2933;
+        background: #fff;
+      }
+
+      .copy-icon-button {
+        display: inline-grid;
+        place-items: center;
+        width: 32px;
+        height: 32px;
+        border: 1px solid #cad5e2;
+        border-radius: 6px;
+        padding: 0;
+        color: #475569;
+        background: #fff;
+        cursor: pointer;
+      }
+
+      .copy-icon-button:hover {
+        border-color: #2563eb;
+        color: #2563eb;
+      }
+
+      .copy-icon-button svg {
+        width: 16px;
+        height: 16px;
+      }
+
+      .copy-status {
+        min-height: 18px;
+        color: #64748b;
+      }
+
       .field {
         display: grid;
         gap: 6px;
@@ -215,7 +274,25 @@
           <div class="actions" style="margin-top: 10px">
             <button class="primary" id="mac-app-button" type="button">在 Mac 版 APP 中启动</button>
           </div>
-          <pre id="mac-app-status"></pre>
+          <div class="mac-app-status" id="mac-app-status" hidden>
+            <div>如果没有唤起 Mac 版 APP，请在系统浏览器中打开当前调试页面后重试。若 APP 已打开但加载失败，请升级到支持本地小程序调试的 Mac App 版本。</div>
+            <div class="debug-page-url">
+              <code id="debug-page-url"></code>
+              <button
+                class="copy-icon-button"
+                id="copy-debug-page-url-button"
+                type="button"
+                aria-label="复制调试页面地址"
+                title="复制调试页面地址"
+              >
+                <svg viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2">
+                  <rect x="9" y="9" width="13" height="13" rx="2" />
+                  <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+                </svg>
+              </button>
+            </div>
+            <div class="copy-status" id="debug-page-copy-status"></div>
+          </div>
         </section>
 
         <section class="block">

package/dist/devtools/mock-host/main.js

@@ -127,18 +127,16 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
 ];
 
 const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
-const MINI_PROGRAM_DEV_QUERY_PARAM = 'hb_mini_dev';
-const MINI_PROGRAM_DETAIL_URL = 'https://www.xiaoheihe.cn/tools/user_miniprogram/detail';
+const MINI_PROGRAM_DEV_SHELL_URL = 'heybox-mini-dev://sandbox';
 function createMacAppProtocol(appUrl) {
-    const detailUrl = new URL(MINI_PROGRAM_DETAIL_URL);
-    detailUrl.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, appUrl);
-    detailUrl.searchParams.set(MINI_PROGRAM_DEV_QUERY_PARAM, '1');
+    const devShellUrl = new URL(MINI_PROGRAM_DEV_SHELL_URL);
+    devShellUrl.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, appUrl);
     const protocolPayload = {
         protocol_type: 'openWindow',
         full_screen: true,
         mini_program: '1',
         webview: {
-            url: detailUrl.toString(),
+            url: devShellUrl.toString(),
             pull: false,
             refresh: false,
         },
@@ -772,6 +770,9 @@ let currentUser = {
 };
 const elements = {
     bridgeStatus: queryElement('#bridge-status'),
+    copyDebugPageUrlButton: queryElement('#copy-debug-page-url-button'),
+    debugPageCopyStatus: queryElement('#debug-page-copy-status'),
+    debugPageUrl: queryElement('#debug-page-url'),
     device: queryElement('#device'),
     logs: queryElement('#logs'),
     macAppButton: queryElement('#mac-app-button'),
@@ -815,8 +816,13 @@ queryElement('#hide-button').addEventListener('click', () => {
     postEvent('hide', { timestamp: Date.now(), source: 'mock-host' });
 });
 elements.macAppButton.addEventListener('click', () => {
-    elements.macAppStatus.textContent = '已尝试唤起 Mac 版 APP';
-    window.location.href = createMacAppProtocol(miniProgramUrl);
+    const protocol = createMacAppProtocol(miniProgramUrl);
+    console.log('[hb-sdk] Mac App launch protocol:', protocol);
+    showMacAppLaunchHint();
+    window.location.href = protocol;
+});
+elements.copyDebugPageUrlButton.addEventListener('click', () => {
+    void copyDebugPageUrl();
 });
 function createBrowserMockRuntimeAdapter() {
     return {
@@ -1053,6 +1059,41 @@ function updateUserStatus() {
 function updateStorageSnapshot() {
     elements.storageSnapshot.textContent = JSON.stringify(Object.fromEntries(Array.from(storage.entries()).map(([key, value]) => [key, safeJsonParse(value)])), null, 2);
 }
+function showMacAppLaunchHint() {
+    elements.debugPageUrl.textContent = location.href;
+    elements.debugPageCopyStatus.textContent = '';
+    elements.macAppStatus.hidden = false;
+}
+async function copyDebugPageUrl() {
+    try {
+        await copyText(location.href);
+        elements.debugPageCopyStatus.textContent = '已复制调试页面地址';
+    }
+    catch {
+        elements.debugPageCopyStatus.textContent = '复制失败，请手动复制调试页面地址';
+    }
+}
+async function copyText(value) {
+    if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(value);
+        return;
+    }
+    const textarea = document.createElement('textarea');
+    textarea.value = value;
+    textarea.setAttribute('readonly', '');
+    textarea.style.position = 'fixed';
+    textarea.style.left = '-9999px';
+    document.body.appendChild(textarea);
+    textarea.select();
+    try {
+        if (!document.execCommand('copy')) {
+            throw new Error('copy command failed');
+        }
+    }
+    finally {
+        textarea.remove();
+    }
+}
 function pushLog(method, detail) {
     logs.unshift({
         method,

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

@@ -15,7 +15,7 @@ npm run deploy
 
 ## 开发模式
 
-- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
 - `npm run deploy`：构建并发布当前小程序。发布前需要先把 `package.json` 中的 `heybox.miniProgramId` 改成后台分配的真实小程序 id，并执行过 `npx hb-sdk login`。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "",
   "exports": {
     ".": {
@@ -26,6 +26,7 @@
     },
     "./vite": {
       "types": "./types/vite/index.d.ts",
+      "heybox": "./src/vite/index.ts",
       "import": "./dist/vite.esm.js",
       "require": "./dist/vite.cjs.js",
       "default": "./dist/vite.esm.js"
@@ -75,7 +76,7 @@
     "rimraf": "^5.0.5",
     "rollup": "^4.52.4",
     "typescript": "^5.9.3",
-    "vue": "2.7.16",
+    "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4"
   },
@@ -102,10 +103,10 @@
   },
   "scripts": {
     "dev": "vite",
-    "build:package": "nx exec -- sh -c \"pnpm run clean && pnpm run build:lib && pnpm run build:cli && pnpm run build:mock-host && pnpm run build:templates && pnpm run build:types\"",
+    "build:package": "nx exec -- sh -c \"pnpm run clean && pnpm run build:lib && pnpm run build:cli && pnpm run build:templates && pnpm run build:types\"",
     "build:watch": "pnpm run build:lib -w & pnpm run build:types -w",
     "build:lib": "rollup -c rollup.config.ts  --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
-    "build:cli": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
+    "build:cli": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}' && pnpm run build:mock-host",
     "build:mock-host": "node scripts/copy-mock-host.cjs",
     "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",

package/skill/SKILL.md

@@ -50,7 +50,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 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.
+5. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container; if the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
 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.

package/skill/references/api-protocol.md

@@ -131,5 +131,5 @@ Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 3 | 5 | 28 | 29 | 12 |
+| Root API | 3 | 4 | 22 | 17 | 0 |
 | Protocol API | 0 | 1 | 20 | 29 | 13 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.3.1`
+- Version at generation time: `0.3.3`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -198,7 +198,7 @@ npm install
 npm run dev
 ```
 
-模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。
 
 在已有项目中安装：
 
@@ -242,7 +242,7 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 

package/skill/references/cli.md

@@ -228,7 +228,7 @@ Agent rules:
 hb-sdk dev
 ```
 
-`hb-sdk dev` 会从当前目录向上查找最近的 `package.json` 作为项目根目录，加载该项目安装的 `vite`，并优先使用项目内的 Vite 配置文件。命令会同时启动内置 mock runtime host 并默认打开调试页；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。项目没有安装 Vite 时，命令会提示安装依赖或把 Vite 放到 `devDependencies`。
+`hb-sdk dev` 会从当前目录向上查找最近的 `package.json` 作为项目根目录，加载该项目安装的 `vite`，并优先使用项目内的 Vite 配置文件。命令会同时启动内置 mock runtime host 并默认打开调试页；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。项目没有安装 Vite 时，命令会提示安装依赖或把 Vite 放到 `devDependencies`。
 
 常用参数：
 
@@ -241,13 +241,13 @@ hb-sdk dev
 
 ## Mock runtime 边界
 
-`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动等调试按钮，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。
+`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动等调试按钮，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
 
 本地 mock runtime 下的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。
 
-Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
+Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
 
 ## CLI login cache
 
@@ -348,7 +348,7 @@ npm run deploy
 
 ## 开发模式
 
-- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
 - `npm run deploy`：构建并发布当前小程序。发布前需要先把 `package.json` 中的 `heybox.miniProgramId` 改成后台分配的真实小程序 id，并执行过 `npx hb-sdk login`。
 

package/skill/references/llms-index.md

@@ -24,7 +24,7 @@ This site documents the iframe-side SDK for external mini programs. For AI retri
 - [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): 所有请求失败都会被规范化成该结构，SDK 侧再包装为 `HbMiniProgramSDKError`。 |
+- [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): `user.getInfo` 不需要入参。
 - [Protocol types](./llms/reference/protocol/types/README.md): `user.getInfo` 不需要入参。

package/skill/scripts/sync-references.mjs

@@ -326,7 +326,7 @@ Agent rules:
 
 ${cliDevSection}
 
-Use \`hb-sdk dev\` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
+Use \`hb-sdk dev\` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the \`heybox://\` protocol handoff.
 
 ## CLI login cache
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.3.1+skill.3af1f225a627",
+  "skillVersion": "0.3.3+skill.cb20a91e9529",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.3.1",
-    "compatibility": "0.3.1"
+    "version": "0.3.3",
+    "compatibility": "0.3.3"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-3af1f225a627e3a1f6f4e01a98cc4e38bc571cb911a0e27cf0919784c6b9014f"
+  "integrity": "sha256-cb20a91e95291420a1f1d1b8a1601bbf21ba8bcd4dac64265d0c033e009d9456"
 }