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

package/dist/index.cjs.js

@@ -240,8 +240,9 @@ class MiniProgramBridgeClient {
         this.eventBus.off(eventName, handler);
     }
     /** 调用父容器开放能力。 */
-    async request(method, payload) {
+    async request(method, ...args) {
         await this.ready();
+        const payload = args[0];
         const id = createMessageId();
         const message = {
             namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
@@ -888,25 +889,12 @@ const hbSDK = {
     network,
 };
 
-exports.AUTH_LOGIN_METHOD = AUTH_LOGIN_METHOD;
 exports.HbMiniProgramNetworkError = HbMiniProgramNetworkError;
 exports.HbMiniProgramSDKError = HbMiniProgramSDKError;
-exports.MINI_PROGRAM_BRIDGE_NONCE_PARAM = MINI_PROGRAM_BRIDGE_NONCE_PARAM;
-exports.MINI_PROGRAM_MESSAGE_NAMESPACE = MINI_PROGRAM_MESSAGE_NAMESPACE;
-exports.MINI_PROGRAM_MESSAGE_VERSION = MINI_PROGRAM_MESSAGE_VERSION;
 exports.MiniProgramSDK = MiniProgramSDK;
-exports.NETWORK_REQUEST_METHOD = NETWORK_REQUEST_METHOD;
-exports.SDK_HANDSHAKE_METHOD = SDK_HANDSHAKE_METHOD;
-exports.SHARE_SCREENSHOT_METHOD = SHARE_SCREENSHOT_METHOD;
-exports.SHARE_SHOW_SHARE_MENU_METHOD = SHARE_SHOW_SHARE_MENU_METHOD;
-exports.STORAGE_GET_STORAGE_METHOD = STORAGE_GET_STORAGE_METHOD;
-exports.STORAGE_SET_STORAGE_METHOD = STORAGE_SET_STORAGE_METHOD;
-exports.USER_GET_INFO_METHOD = USER_GET_INFO_METHOD;
-exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
 exports.auth = auth;
 exports.createMiniProgramSDK = createMiniProgramSDK;
 exports.default = hbSDK;
-exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
 exports.network = network;
 exports.off = off;
 exports.on = on;

package/dist/index.esm.js

@@ -236,8 +236,9 @@ class MiniProgramBridgeClient {
         this.eventBus.off(eventName, handler);
     }
     /** 调用父容器开放能力。 */
-    async request(method, payload) {
+    async request(method, ...args) {
         await this.ready();
+        const payload = args[0];
         const id = createMessageId();
         const message = {
             namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
@@ -884,4 +885,4 @@ const hbSDK = {
     network,
 };
 
-export { AUTH_LOGIN_METHOD, HbMiniProgramNetworkError, HbMiniProgramSDKError, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MiniProgramSDK, 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, auth, createMiniProgramSDK, hbSDK as default, isMiniProgramBridgeMessage, network, off, on, ready, share, storage, user, viewport };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, MiniProgramSDK, auth, createMiniProgramSDK, hbSDK as default, network, off, on, ready, share, storage, user, viewport };

package/dist/miniapp-publish.cjs.js

@@ -1,14 +1,15 @@
 'use strict';
 
+const PUBLISH_VERSION_RE = /^\d+\.\d+\.\d+$/;
+function isValidMiniappManifestVersion(version) {
+    return PUBLISH_VERSION_RE.test(String(version || '').trim());
+}
+
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
-const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
-function isValidVersion(version) {
-    return VERSION_PATTERN.test(String(version || '').trim());
-}
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
@@ -70,7 +71,7 @@ exports.MINIAPP_UPLOAD_SCOPE = MINIAPP_UPLOAD_SCOPE;
 exports.PUBLISH_USER_MINIPROGRAM_API_PATH = PUBLISH_USER_MINIPROGRAM_API_PATH;
 exports.getMiniProgramUploadAlias = getMiniProgramUploadAlias;
 exports.getMiniappUploadKey = getMiniappUploadKey;
-exports.isValidVersion = isValidVersion;
+exports.isValidVersion = isValidMiniappManifestVersion;
 exports.normalizeRelativePath = normalizeRelativePath;
 exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
 exports.shouldUploadDistFile = shouldUploadDistFile;

package/dist/miniapp-publish.esm.js

@@ -1,12 +1,13 @@
+const PUBLISH_VERSION_RE = /^\d+\.\d+\.\d+$/;
+function isValidMiniappManifestVersion(version) {
+    return PUBLISH_VERSION_RE.test(String(version || '').trim());
+}
+
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
-const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
-function isValidVersion(version) {
-    return VERSION_PATTERN.test(String(version || '').trim());
-}
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
@@ -63,4 +64,4 @@ function shouldUploadDistFile(relativePath) {
     return true;
 }
 
-export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, MINIAPP_UPLOAD_SCOPE, PUBLISH_USER_MINIPROGRAM_API_PATH, getMiniProgramUploadAlias, getMiniappUploadKey, isValidVersion, normalizeRelativePath, relativePathContainsNodeModulesSegment, shouldUploadDistFile, validateUploadPaths };
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, MINIAPP_UPLOAD_SCOPE, PUBLISH_USER_MINIPROGRAM_API_PATH, getMiniProgramUploadAlias, getMiniappUploadKey, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, relativePathContainsNodeModulesSegment, shouldUploadDistFile, validateUploadPaths };

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

@@ -10,12 +10,14 @@ npm run dev
 npm run typecheck
 npm run test:unit
 npm run build
+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/dist/templates/vue3-vite-ts/package.json.ejs

@@ -3,8 +3,13 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
+  "heybox": {
+    "miniProgramId": ""
+  },
   "scripts": {
+    "hb-sdk": "hb-sdk",
     "dev": "hb-sdk dev",
+    "deploy": "hb-sdk deploy",
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",

package/dist/vite.cjs.js

@@ -3,32 +3,37 @@
 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`);
-        },
-    };
+const MINIAPP_TEMPLATE_VERSION = '0.0.0';
+const BUILD_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+function getMiniappManifestBuildWarning(version) {
+    if (version === MINIAPP_TEMPLATE_VERSION) {
+        return '@heybox/hb-sdk 提示：package.json.version 仍是模板默认的 0.0.0；manifest 会写入，但发布前必须改成实际 x.y.z 版本';
+    }
+    if (!BUILD_VERSION_RE.test(version)) {
+        return `package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`;
+    }
+    return undefined;
+}
+function renderMiniappManifest(manifest) {
+    return `${JSON.stringify({ version: manifest.version }, null, 2)}\n`;
 }
-function readMiniappVersion(root) {
-    const packageJsonPath = path.join(root, 'package.json');
+
+function findNearestPackageJsonPath(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(current, 'package.json');
+        if (node_fs.existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.join(path.resolve(startDir), 'package.json');
+        }
+        current = parent;
+    }
+}
+function readMiniappVersionFromPackageJson(root) {
+    const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
     try {
         content = node_fs.readFileSync(packageJsonPath, 'utf8');
@@ -46,11 +51,7 @@ function readMiniappVersion(root) {
     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;
+    return packageJson.version.trim();
 }
 function formatReason(error) {
     if (error instanceof Error && error.message) {
@@ -59,4 +60,27 @@ function formatReason(error) {
     return String(error);
 }
 
+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 = readMiniappVersionFromPackageJson(root);
+            const warning = getMiniappManifestBuildWarning(version);
+            if (warning) {
+                this.warn(warning);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+            node_fs.writeFileSync(manifestPath, renderMiniappManifest({ version }));
+        },
+    };
+}
+
 exports.miniappManifest = miniappManifest;

package/dist/vite.esm.js

@@ -1,32 +1,37 @@
-import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } 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`);
-        },
-    };
+const MINIAPP_TEMPLATE_VERSION = '0.0.0';
+const BUILD_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+function getMiniappManifestBuildWarning(version) {
+    if (version === MINIAPP_TEMPLATE_VERSION) {
+        return '@heybox/hb-sdk 提示：package.json.version 仍是模板默认的 0.0.0；manifest 会写入，但发布前必须改成实际 x.y.z 版本';
+    }
+    if (!BUILD_VERSION_RE.test(version)) {
+        return `package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`;
+    }
+    return undefined;
+}
+function renderMiniappManifest(manifest) {
+    return `${JSON.stringify({ version: manifest.version }, null, 2)}\n`;
 }
-function readMiniappVersion(root) {
-    const packageJsonPath = path.join(root, 'package.json');
+
+function findNearestPackageJsonPath(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(current, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.join(path.resolve(startDir), 'package.json');
+        }
+        current = parent;
+    }
+}
+function readMiniappVersionFromPackageJson(root) {
+    const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
     try {
         content = readFileSync(packageJsonPath, 'utf8');
@@ -44,11 +49,7 @@ function readMiniappVersion(root) {
     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;
+    return packageJson.version.trim();
 }
 function formatReason(error) {
     if (error instanceof Error && error.message) {
@@ -57,4 +58,27 @@ function formatReason(error) {
     return String(error);
 }
 
+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 = readMiniappVersionFromPackageJson(root);
+            const warning = getMiniappManifestBuildWarning(version);
+            if (warning) {
+                this.warn(warning);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            mkdirSync(path.dirname(manifestPath), { recursive: true });
+            writeFileSync(manifestPath, renderMiniappManifest({ version }));
+        },
+    };
+}
+
 export { miniappManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.2.0-alpha.2",
+  "version": "0.3.2",
   "description": "",
   "exports": {
     ".": {
@@ -43,9 +43,7 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "dependencies": {
-    "cos-nodejs-sdk-v5": "2.15.4"
-  },
+  "dependencies": {},
   "peerDependencies": {
     "vite": ">=5"
   },
@@ -66,6 +64,7 @@
     "@types/node": "24.10.1",
     "@vitest/coverage-v8": "^3.2.4",
     "commander": "^12.1.0",
+    "cos-nodejs-sdk-v5": "2.15.4",
     "ejs": "^3.1.10",
     "env-paths": "^2.2.1",
     "fs-extra": "^11.3.0",

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-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.2.0-alpha.2`
+- Version at generation time: `0.3.2`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -29,49 +29,13 @@
 ```ts
 export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export type { MiniProgramRequester, MiniProgramSDKOptions } from './core/client';
+export type { MiniProgramSDKOptions } from './core/client';
 export { ready, on, off, auth, user, share, viewport, storage, network } from './core/singleton';
-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,
-  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, MiniProgramAuthModule } from './modules/auth';
 export type {
   GetUserInfoPayload,
@@ -138,12 +102,13 @@ export default hbSDK;
 Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe mini-program business code.
 
 ```ts
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } 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 改成实际版本号再发布';
+import {
+  getMiniappManifestBuildWarning,
+  renderMiniappManifest,
+} from '../miniapp-manifest/schema';
+import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
 
 type MiniappManifestPlugin = {
   name: string;
@@ -175,57 +140,19 @@ export function miniappManifest(): MiniappManifestPlugin {
       outDir = resolved.build.outDir;
     },
     writeBundle() {
-      const version = readMiniappVersion(root);
+      const version = readMiniappVersionFromPackageJson(root);
+      const warning = getMiniappManifestBuildWarning(version);
 
-      if (!SEMVER_LIKE_RE.test(version)) {
-        this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+      if (warning) {
+        this.warn(warning);
       }
 
       const manifestPath = path.resolve(root, outDir, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+      writeFileSync(manifestPath, renderMiniappManifest({ version }));
     },
   };
 }
-
-function readMiniappVersion(root: string): string {
-  const packageJsonPath = path.join(root, 'package.json');
-  let content: string;
-
-  try {
-    content = readFileSync(packageJsonPath, 'utf8');
-  } catch (error) {
-    throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
-  }
-
-  let packageJson: { version?: unknown };
-
-  try {
-    packageJson = JSON.parse(content) as { version?: unknown };
-  } 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: unknown): string {
-  if (error instanceof Error && error.message) {
-    return error.message;
-  }
-
-  return String(error);
-}
 ```
 
 ## Manifest
@@ -253,7 +180,7 @@ export default defineConfig({
 
 - 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
 - `package.json.version` 不是非空字符串：`vite build` 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 直接失败，并提示把模板默认版本改成实际版本号再发布。
+- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
 - 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
 
 `manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
@@ -271,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 时，请先在系统浏览器中打开调试页。
 
 在已有项目中安装：
 
@@ -315,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
 
@@ -343,12 +343,14 @@ npm run dev
 npm run typecheck
 npm run test:unit
 npm run build
+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/scripts/skill-metadata.mjs

@@ -2,7 +2,10 @@ import { createHash } from 'node:crypto';
 
 export const HB_SDK_SKILL_NAME = 'hb-sdk';
 export const HB_SDK_PACKAGE_NAME = '@heybox/hb-sdk';
-export const HB_SDK_SKILL_SOURCE = 'https://open.xiaoheihe.cn/agent-skills/hb-sdk';
+export const HB_SDK_AGENT_SKILLS_BASE_URL = 'https://open.xiaoheihe.cn/agent-skills';
+export const HB_SDK_SKILL_SOURCE = `${HB_SDK_AGENT_SKILLS_BASE_URL}/${HB_SDK_SKILL_NAME}`;
+export const HB_SDK_SKILL_INDEX_URL = `${HB_SDK_AGENT_SKILLS_BASE_URL}/.well-known/agent-skills/index.json`;
+export const HB_SDK_SKILL_INSTALL_COMMAND = `npx skills add ${HB_SDK_SKILL_SOURCE}`;
 
 export function createSkillContentHash(fileEntries) {
   const hash = createHash('sha256');

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.2.0-alpha.2+skill.57e0cec11058",
+  "skillVersion": "0.3.2+skill.f845392336aa",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.2.0-alpha.2",
-    "compatibility": "0.2.0-alpha.2"
+    "version": "0.3.2",
+    "compatibility": "0.3.2"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-57e0cec1105894712e82600045659d9f08fedc9e0e4c3159445168eaec6675e7"
+  "integrity": "sha256-f845392336aabd50713f07fe9570e9208e1801f1e20eecb7ccd58941ab83ab64"
 }