@heybox/hb-sdk 0.6.4-alpha.0 → 0.6.4

package/dist/protocol.cjs.js

@@ -32,6 +32,58 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -364,4 +416,6 @@ exports.USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD = USER_GET_PLATFORM_ACCOUNT_OV
 exports.USER_GET_STEAM_GAME_LIST_METHOD = USER_GET_STEAM_GAME_LIST_METHOD;
 exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
 exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
+exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
+exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;

package/dist/protocol.esm.js

@@ -30,6 +30,58 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -327,4 +379,4 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     },
 ];
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isMiniProgramBridgeMessage };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, parseMiniProgramRuntimePermissions };

package/dist/vite.cjs.js

@@ -7,7 +7,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.4-alpha.0';
+    : '0.6.4';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.4-alpha.0';
+    : '0.6.4';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.4-alpha.0",
+  "version": "0.6.4",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",

package/skill/references/api-protocol.md

@@ -31,6 +31,13 @@ export {
   SDK_LOCATION_REPORT_METHOD,
 } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
+export { isManagedMiniProgramRuntimePermissionKey, parseMiniProgramRuntimePermissions } from './protocol/runtime-permissions';
+export type {
+  MiniProgramRuntimePermissionEntry,
+  MiniProgramRuntimePermissionStatus,
+  MiniProgramRuntimePermissionsSnapshot,
+  ParsedMiniProgramRuntimePermissions,
+} from './protocol/runtime-permissions';
 export type {
   MiniProgramBridgeError,
   MiniProgramBridgeMessage,
@@ -139,11 +146,7 @@ export type {
   MiniProgramShareChannel,
   MiniProgramShowShareMenuOptions,
 } from './modules/share';
-export type {
-  GetStoragePayload,
-  GetStorageResult,
-  SetStoragePayload,
-} from './modules/storage';
+export type { GetStoragePayload, GetStorageResult, SetStoragePayload } from './modules/storage';
 export type {
   GetWindowInfoPayload,
   GetWindowInfoResult,
@@ -173,13 +176,7 @@ export type {
   ShowToastPayload,
   ShowToastResult,
 } from './modules/ui';
-export type {
-  MiniProgramVibrateIntensity,
-  SetClipboardPayload,
-  SetClipboardResult,
-  VibratePayload,
-  VibrateResult,
-} from './modules/device';
+export type { MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult } from './modules/device';
 export type {
   ClosePayload,
   CloseResult,
@@ -210,18 +207,22 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | 说明 |
 | --- | --- |
-| [Root API](api-root.md) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
-| [Protocol API](#public-protocol-entrypoint) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
+| [Root API](api-root.md) | `@heybox/hb-sdk` 的默认导出、命名导出与公开能力。 |
+| [Protocol API](#public-protocol-entrypoint) | `@heybox/hb-sdk/protocol` 的协议常量、消息类型与 method 契约。 |
+| [Miniapp Publish API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/) | `@heybox/hb-sdk/miniapp-publish` 的构建产物发布前的公开校验工具。 |
+| [Vite API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/) | `@heybox/hb-sdk/vite` 的Vite 工坊小程序插件。 |
 
 ## 查询建议
 
 - 想查业务接入路径：先看 [Guide](recipes.md)。
-- 想查导出符号：从 Root API 或 Protocol API 进入对应分类页。
+- 想查导出符号：从上方对应公开入口进入分类页。
 - 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
 
 ## 统计
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 3 | 66 | 57 | 4 |
-| Protocol API | 0 | 1 | 43 | 68 | 35 |
+| Root API | 2 | 3 | 66 | 57 | 0 |
+| Protocol API | 0 | 3 | 43 | 67 | 32 |
+| Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
+| Vite API | 0 | 1 | 0 | 0 | 0 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.4-alpha.0`
+- Version at generation time: `0.6.4`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -450,9 +450,9 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。需要定位降级原因时可使用 `hb-sdk dev --verbose`；详细错误只写入本地调试日志，其中 URL 用户名、密码和敏感 query/hash 会被遮蔽，不会进入 LAN bootstrap。
 
-Mock Host 可以在内存中调整 devtools-only 权限模拟，不会重建 iframe，因此不影响 Vite HMR；本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+Mock Host 可以在内存中切换 devtools-only 的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR；官方域名权限只读取线上快照，本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 

package/skill/references/cli.md

@@ -76,13 +76,13 @@ Top-level `hb-sdk deploy` has been hard-cut and must not be documented as a vali
 ## 创建外部小程序模板
 
 ```bash
-hb-sdk create my-miniapp
+npx @heybox/hb-sdk create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
 ```
 
-`hb-sdk create <project-name>` 会生成 Vue 3、Vite、TypeScript 和 npm 模板。`project-name` 同时作为目录名和 `package.json` 的 `name`，必须是合法的非 scoped npm 包名。目标目录不存在时会创建；目标目录已存在但非空时会拒绝覆盖。
+`hb-sdk create <target-path>` 会生成 Vue 3、Vite、TypeScript 和 npm 模板。参数可以是目录名、相对/绝对路径或 `.`；生成的 `package.json.name` 取解析后目标目录的 basename，并校验为合法的非 scoped npm 包名。目标目录不存在时会创建；目标目录已存在但非空时会拒绝覆盖。模板使用 Vite 8，需要 Node.js `^20.19.0` 或 `>=22.12.0`。
 
 CLI 只生成文件，不会自动安装依赖、初始化 git 或打开编辑器。生成模板后优先运行 `npm run dev`，它会启动 Vite 服务和内置 mock runtime host。
 
@@ -103,7 +103,7 @@ Agent rules:
 hb-sdk dev
 ```
 
-`hb-sdk dev` 会从当前目录向上查找最近的 `package.json`。Vite、内置 mock runtime host、Mac 启动协议和手机二维码的基础启动只依赖本地页面地址，不要求项目先绑定或 CLI 先登录。项目已绑定时，CLI 会限时 3 秒读取远端 dev context；成功后用真实 Runtime 权限快照初始化 Mock Host，失败或超时则输出脱敏警告并继续匿名调试，`network.request` 等受管能力默认拒绝。公开 `detail` 查询不再是 dev 启动门禁。本地 `package.json` 无法解析等配置错误不会被降级，命令会直接报错。调试页默认自动打开；需要真实黑盒小程序容器加载同一页面时，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。
+`hb-sdk dev` 会从当前目录向上查找最近的 `package.json`。Vite、内置 mock runtime host、Mac 启动协议和手机二维码的基础启动只依赖本地页面地址，不要求项目先绑定或 CLI 先登录。项目已绑定时，CLI 会限时 3 秒读取远端 dev context；成功后用真实 Runtime 权限快照初始化 Mock Host，失败或超时则输出脱敏警告并继续匿名调试，`network.request` 等受管能力默认拒绝。需要定位降级原因时可使用 `hb-sdk dev --verbose`；详细错误只写入本地调试日志，其中 URL 用户名、密码和敏感 query/hash 会被遮蔽，不会进入 LAN bootstrap。公开 `detail` 查询不再是 dev 启动门禁。本地 `package.json` 无法解析等配置错误不会被降级，命令会直接报错。调试页默认自动打开；需要真实黑盒小程序容器加载同一页面时，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。
 
 常用参数：
 
@@ -120,7 +120,7 @@ hb-sdk dev
 
 不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
 
-浏览器 Mock 的权限状态只存在于 Mock Host 内存中，URL query 不能提供或覆盖权限。远端 dev context 可用时，Mock Host 以线上快照作为初始值；不可用时匿名状态默认拒绝受管能力。开发者可以在调试页临时调整 `network.request` 和官方域名权限，变更只会重建 devtools-only mock runtime，不会重建 iframe 或中断 Vite HMR，也不会修改线上配置。调试页会对比线上快照并提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。
+浏览器 Mock 的权限状态只存在于 Mock Host 内存中，URL query 不能提供或覆盖权限。远端 dev context 可用时，Mock Host 以线上快照作为初始值；不可用时匿名状态默认拒绝受管能力。开发者可以在调试页临时切换 `network.request` 权限；官方域名权限只读取线上快照，不能在 devtools 中手动调整。变更只会重建 devtools-only mock runtime，不会重建 iframe 或中断 Vite HMR，也不会修改线上配置。调试页会对比线上快照并提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。
 
 本地 mock runtime 下已授权的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。CLI 登录态和远端 dev context 也不会注入 iframe。
 
@@ -134,16 +134,13 @@ Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "
 hb-sdk remote deploy --release-note "修复登录状态展示，补充异常提示"
 hb-sdk remote deploy --release-note "审核通过后自动发布" --auto-publish
 hb-sdk remote deploy --from-version 1.2.3 --release-note "复用 1.2.3 历史产物"
-hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
-hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
-HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.0.1:8080 --release-note "本地后台联调"
 ```
 
 `hb-sdk remote deploy` 把预检、构建、上传和提交审核串成一条命令。顶层 `hb-sdk deploy` 已硬切删除，不再作为兼容别名保留：
 
 1. 读取 `package.json.heybox.miniProgramId`，缺失即报错。
 2. 校验登录态，需先 `hb-sdk login`。
-3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
+3. 运行 `hb-sdk remote access` 确认当前主体具备开发者资格；未开通时按开放平台的小程序工坊申请入口提交申请。
 4. 读取并校验 `--release-note`；TTY 环境缺失时会提示输入，CI / 非 TTY 环境缺失时直接失败。建议让 AI 生成 1-5 条简短发布日志。
 5. 普通 remote deploy 先读取 `package.json.version`，登录后、build 前调用版本预检接口；预检通过后才执行 `<pm> run build`。
 6. `--from-version <version>` 跳过本地构建、`dist/` 读取和上传，复用指定历史版本产物提交审核。
@@ -151,8 +148,8 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 8. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
 9. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
 10. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
-11. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
-12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
+11. CLI 会分批上传构建产物并校验平台返回的文件集合；任何批次异常都会停止后续上传且不会提交审核。
+12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会补充逐文件诊断，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
 13. 全部上传成功后调用提交审核接口；`--from-version` 路径会直接提交 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL。
 
 `mini_program_id` 没有 CLI flag，必须落在 `package.json` 里：
@@ -167,30 +164,22 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 
 `manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。小程序构建产物需要使用相对资源路径；`hb-sdk create` 模板会显式配置 `base: './'`，未配置 `base` 的项目也会由 `miniappManifest()` 在 build 时默认补成 `./`。构建产物只能在兼容的小黑盒 Runtime 中启动，普通浏览器直接打开时不会执行标准业务脚本。
 
-`dev`、手动 Vite build、`remote deploy` 的本地构建和 `--from-version` 路径都不执行客户端 `minimumSdkVersion` 查询或比较；Manifest 结构校验、版本 precheck 和服务端 submit-audit 策略仍然生效。
+CLI 的 `dev` 启动、本地 Vite build、`remote deploy` 本地构建和 `--from-version` 路径都不主动查询或比较 `minimumSdkVersion`；Mac / Mobile dev shell 仍会在加载 iframe 前执行宿主侧兼容性与平台配置检查。Manifest 结构校验、版本 precheck 和服务端 submit-audit 策略仍然生效。
 
-默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。如需让指定用户预览未发布候选版本，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
+默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。`--auto-publish` 只适用于普通低风险版本；重大功能、活动联动、商业化、用户数据、外部账号绑定或风控策略变更应保持手动发布。需要指定用户预览未发布候选版本时，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
 
-内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，优先用 `--service-tag <tag>` 或 `HB_SDK_SERVICE_TAG`。path-prefix 级 `special_tag` 仍可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
-
-`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
-
-切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。CLI 支持加载 `.env.<name>` 预设，把其中的 `HB_SDK_*` 变量一次性注入当前进程（不覆盖已有值）：`--env <name>` 读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级更高，也可用 `HB_SDK_ENV=<name>` 触发。使用 `--env <name>` 或 `HB_SDK_ENV=<name>` 执行 `remote deploy` 时，CLI 还会把同一个 `name` 作为 `--mode <name>` 传给项目 build，使 CLI 后端环境与 Vite mode 保持一致。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。
+需要给构建选择 Vite mode 时，可以使用 `--env <name>` 或 `HB_SDK_ENV=<name>`。CLI 会从当前目录向上找到项目根，读取 `.env.<name>`，把其中所有合法 key 注入当前进程和后续 build（不覆盖已有值），并将同一个 `name` 作为 `--mode <name>` 传给项目 build。`--env-file <path>` 可以相对调用目录指定其他预设文件，且优先级高于 `--env`。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过，其他读取错误会直接失败。
 
 ```bash
-# 项目根准备 .env.test
-#   HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
-#   HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
-#   HB_SDK_SERVICE_TAG=my-test-tag
-
-hb-sdk remote deploy --env test --release-note "测试环境验证"
-hb-sdk remote info --env test
-HB_SDK_ENV=test hb-sdk remote versions
-hb-sdk remote deploy --env-file .env.local --release-note "本地联调"
-hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
+# 项目根准备 .env.preview
+#   VITE_API_ORIGIN=https://api.example.com
+
+hb-sdk remote deploy --env preview --release-note "预览模式构建"
+HB_SDK_ENV=preview hb-sdk remote deploy --release-note "预览模式构建"
+hb-sdk remote deploy --env-file .env.local --release-note "本地配置构建"
 ```
 
-`--env-file` 优先于 `--env`，`--service-tag` / `--api-base-url` / `--login-base-url` 优先于 `.env` 预设注入的同名变量，而预设又不会覆盖进程已有的环境变量，因此优先级为 flag > 进程 env > `.env` 预设 > 默认值。
+预设不会覆盖进程已有的同名环境变量，因此优先级为进程 env > `.env` 预设 > 默认值。
 
 Before precheck, build, upload, or submit audit, `hb-sdk remote deploy` must verify that the current project's bound mini-program belongs to the server-side current entity. If `detail.entity_id` differs from the current entity, the command fails with both entity ids/names and suggests `hb-sdk remote entity switch <entity-id>`. It must not auto-switch entities and must not continue into precheck/build/upload/submit on mismatch.
 
@@ -241,6 +230,9 @@ Agent rules:
 
 ```bash
 hb-sdk remote access
+hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>
 hb-sdk remote list
 hb-sdk remote create
 hb-sdk remote bind mp_xxxxxxxx
@@ -262,9 +254,9 @@ hb-sdk remote square show
 
 `hb-sdk remote square hide` 会隐藏当前绑定小程序在普通用户侧的小程序工坊广场展示；白名单用户仍可在小程序工坊广场看到，直接链接访问已发布版本也不受影响。`hb-sdk remote square show` 会恢复普通用户侧的小程序工坊广场展示。
 
-`hb-sdk remote release`、`hb-sdk remote withdraw`、`hb-sdk remote take-down`、`hb-sdk remote reopen` 和 `hb-sdk remote square hide` 会改变审核、发布或用户侧可见状态。交互式终端会展示小程序 id、名称、当前状态、目标版本和操作，再要求确认；非 TTY 环境必须传 `--yes`。
+`hb-sdk remote release`、`withdraw`、`take-down`、`reopen` 和 `square hide` 会改变审核、发布或用户侧可见状态。交互式终端会展示目标和变更内容后要求确认；非 TTY 环境必须传 `--yes`。`entity switch`、`square show` 和 allowlist 写操作当前不会进行这层 CLI 确认，自动化脚本不要为它们假设存在确认保护。
 
-所有 `hb-sdk remote` 子命令都支持 `--json`。开启后 stdout 只输出一个 JSON 对象；进度、警告、版本提醒和 verbose 诊断不能污染 stdout。
+所有 `hb-sdk remote` 子命令都支持 `--json`。开启后 stdout 只输出一个 JSON 对象；进度、警告、版本提醒和 verbose 诊断不能污染 stdout。`remote deploy --json` 不进行交互式 release note 提示，必须显式传 `--release-note`。
 
 Agent rules:
 
@@ -285,13 +277,12 @@ Agent rules:
 
 ```bash
 hb-sdk login
-hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
 hb-sdk login status
 hb-sdk login clear
 ```
 
 - `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
-- `hb-sdk login --login-base-url <url>` 会打开指定登录 origin，并把该登录环境写入 CLI 登录态。
+- 登录成功后默认还会查询开发者主体；`--no-select-entity` 会跳过登录后的主体选择。
 - `hb-sdk login status` 默认展示脱敏状态、`heyboxId`、`loginBaseUrl` 和登录时间；`--verbose` 额外展示 cache 路径。不输出 `pkey`、cookie 或完整请求头。
 - `hb-sdk login clear` 只清理 `hb-sdk` 自己命名空间中的 Heybox 登录态。
 

package/skill/references/recipes.md

@@ -46,9 +46,10 @@ bootstrap()
 
 ## 推荐业务写法
 
-业务页通常还需要监听登录态变化：
+业务页通常还需要监听登录态变化。下面以 Vue 3 为例：初始化只读取状态，登录必须由按钮等明确的用户操作触发，监听在组件卸载时清理。
 
 ```ts
+import { onUnmounted } from 'vue'
 import hbSDK from '@heybox/hb-sdk'
 
 const stopAuthChange = hbSDK.on('authChange', result => {
@@ -59,15 +60,22 @@ const stopAuthChange = hbSDK.on('authChange', result => {
 
 await hbSDK.ready()
 
-const result = await hbSDK.user.getInfo()
-if (!result.isLogin) {
-  await hbSDK.auth.login()
+const initialUser = await hbSDK.user.getInfo()
+
+async function loginFromUserAction() {
+  const result = await hbSDK.auth.login()
+  if (!result.isLogin || !result.userInfo) {
+    return
+  }
+
+  console.log('用户已登录', result.userInfo.heybox_id)
 }
 
-// 页面卸载时清理监听
-stopAuthChange()
+onUnmounted(stopAuthChange)
 ```
 
+把 `loginFromUserAction` 绑定到登录按钮；不要在页面 bootstrap 阶段自动调用 `auth.login()`。
+
 ## ready 的含义
 
 `ready()` 表示 SDK 已完成与父容器的握手，可以安全调用开放能力。SDK 在收到 `ready` 前会自动重试握手；如果超过总超时时间仍未成功，会抛出 `READY_TIMEOUT`。它不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
@@ -87,6 +95,10 @@ stopAuthChange()
 
 - `user.getInfo()`：静默读取当前登录态与公开基础资料。
 - `auth.login()`：唤起黑盒登录流程，并返回登录后的最新公开用户资料。
+- `user.getCurrentUserDetail()`：读取当前用户展示详情。
+- `user.getCurrentUserProfile()`：读取当前用户敏感资料，需要对应 Runtime 权限。
+- `user.getPlatformAccountOverview()` / `getPlatformAccountInfo()`：读取平台账号概览或指定平台详情。
+- `user.getSteamGameList()`：读取当前用户 Steam 游戏库。
 
 ## 静默读取用户信息
 
@@ -123,9 +135,9 @@ async function ensureLogin() {
 }
 ```
 
-## 暴露字段
+## 基础资料与扩展资料
 
-SDK 只暴露允许给外部小程序读取的公开字段：
+`user.getInfo()` 和 `auth.login()` 的 `userInfo` 只包含三项公开基础字段：
 
 | 字段        | 类型     | 说明         |
 | ----------- | -------- | ------------ |
@@ -135,18 +147,35 @@ SDK 只暴露允许给外部小程序读取的公开字段：
 
 不会暴露 token、cookie、手机号或任何可用于调用主站私有接口的凭据。
 
+current-user scoped API 返回独立的 `UserScopedResult<T>`。未登录时是 `{ isLogin: false, data: null }`；已登录时才有 `data`。其中 `getCurrentUserProfile()` 可能返回生日、邮箱、教育和职业等敏感资料，必须按最小必要原则使用，并以 Runtime 权限结果为准；不要把这些字段理解为 `getInfo()` 的默认返回值。
+
+```ts
+const profile = await user.getCurrentUserProfile()
+if (profile.isLogin) {
+  console.log(profile.data.email)
+}
+
+const platforms = await user.getPlatformAccountOverview()
+if (platforms.isLogin) {
+  console.log(platforms.data)
+}
+```
+
 ## 监听登录态变化
 
 如果页面上同时存在登录按钮、权限态 UI 和业务数据，建议监听 `authChange`。
 
 ```ts
+import { onUnmounted } from 'vue'
 import { on } from '@heybox/hb-sdk'
 
-const stop = on('authChange', result => {
+const stopAuthChange = on('authChange', result => {
   if (result.isLogin) {
     console.log('登录态更新', result.userInfo?.heybox_id)
   }
 })
+
+onUnmounted(stopAuthChange)
 ```
 
 ## Lifecycle events
@@ -157,28 +186,28 @@ const stop = on('authChange', result => {
 SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
 
 ```ts
-import { on, off } from '@heybox/hb-sdk'
+import { onUnmounted } from 'vue'
+import { on } from '@heybox/hb-sdk'
 
 function handleShow(payload: { timestamp: number; source?: string }) {
   console.log('show from', payload.source)
 }
 
-on('show', handleShow)
-off('show', handleShow)
-```
-
-`on` 也会返回取消监听函数，推荐在组件卸载时调用：
-
-```ts
-import { on } from '@heybox/hb-sdk'
-
-const stop = on('hide', () => {
+const stopShow = on('show', handleShow)
+const stopHide = on('hide', () => {
   console.log('小程序页面隐藏')
 })
 
-stop()
+function stopLifecycleEvents() {
+  stopShow()
+  stopHide()
+}
+
+onUnmounted(stopLifecycleEvents)
 ```
 
+框架外也可以保存 `on()` 返回的取消函数，在页面或业务模块真正销毁时调用。需要按 handler 精确移除时再使用 `off(event, handler)`；不要在注册后的同一执行流里立即取消。
+
 ## 事件列表
 
 | 事件         | 触发时机                 | 典型用途           |
@@ -187,7 +216,7 @@ stop()
 | `ready`      | SDK 可安全调用开放能力   | 标记 bridge 可用   |
 | `show`       | 小程序页面展示           | 刷新可见态数据     |
 | `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
-| `unload`     | 小程序页面即将卸载       | 清理资源           |
+| `unload`     | 当前 Runtime 上下文终止  | 清理资源并停止请求 |
 | `error`      | 父容器或开放能力运行异常 | 统一错误上报       |
 | `authChange` | 登录状态变化             | 刷新用户信息和权限 |
 
@@ -202,23 +231,37 @@ stop()
 - UI 可见性相关逻辑放在 `show`、`hide`。
 - 用户状态不要只在页面加载时读一次，登录入口附近要监听 `authChange`。
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
+- 事件只派发给注册当时存在的监听器，不会重放；一次性 `launch`/`ready` 状态应以 `ready()` Promise 为准。
+- 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
 
 ## Error handling
 
 
 # 错误处理
 
-SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
+SDK 公开两类标准错误：`HbMiniProgramSDKError` 表示 handshake、bridge、Runtime 或 capability 故障；`HbMiniProgramNetworkError` 表示 HTTP 已完成，但状态没有通过 `validateStatus`。
 
 ```ts
-import { HbMiniProgramSDKError, ready } from '@heybox/hb-sdk'
+import {
+  HbMiniProgramNetworkError,
+  HbMiniProgramSDKError,
+  network,
+} from '@heybox/hb-sdk'
 
 try {
-  await ready()
+  await network.request({ url: 'https://api.example.com/data' })
 } catch (error) {
+  if (error instanceof HbMiniProgramNetworkError) {
+    console.log(error.status, error.data, error.headers)
+    return
+  }
+
   if (error instanceof HbMiniProgramSDKError) {
     console.log(error.code, error.message, error.data)
+    return
   }
+
+  throw error
 }
 ```
 
@@ -229,8 +272,10 @@ try {
 | `NOT_IN_IFRAME`   | 当前页面不在小程序沙盒 iframe 中  | 提示运行环境错误，检查父容器接入   |
 | `MISSING_NONCE`   | URL 中缺少 `hb_mini_bridge_nonce` | 检查父容器 URL 注入逻辑            |
 | `READY_TIMEOUT`   | SDK 握手超时                      | 检查父容器是否幂等响应重试的 `sdk.handshake` |
+| `HANDSHAKE_FAILED` | 握手消息发送失败                 | 检查 iframe、nonce 与 Host 消息通道 |
+| `RUNTIME_UNAVAILABLE` | Runtime 已执行 `unload`       | 停止当前上下文请求并结束页面工作 |
 | `REQUEST_TIMEOUT` | 开放能力调用超时                  | 提示重试，并上报 method            |
-| `SDK_DESTROYED`   | SDK 已销毁但仍有请求未完成        | 检查销毁时机和并发请求             |
+| `INVALID_NETWORK_RESPONSE` | Host 返回的网络响应结构无效 | 上报 Host/Runtime 协议问题 |
 
 父容器返回失败响应时，SDK 也会包装成 `HbMiniProgramSDKError`，此时 `code` 由父容器开放能力定义。
 
@@ -239,14 +284,18 @@ try {
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-async function loadUser() {
+type UserViewState =
+  | { status: 'ready'; user: Awaited<ReturnType<typeof hbSDK.user.getInfo>> }
+  | { status: 'failed'; error: HbMiniProgramSDKError }
+
+async function loadUser(): Promise<UserViewState> {
   try {
     await hbSDK.ready()
-    return await hbSDK.user.getInfo()
+    return { status: 'ready', user: await hbSDK.user.getInfo() }
   } catch (error) {
     if (error instanceof HbMiniProgramSDKError) {
       reportSDKError(error.code, error.message, error.data)
-      return { isLogin: false, userInfo: null }
+      return { status: 'failed', error }
     }
 
     throw error

package/skill/scripts/sync-references.mjs

@@ -100,6 +100,8 @@ function rewriteBundledProtocolIndexLinks(markdown) {
   return markdown
     .replaceAll('(./root/)', '(api-root.md)')
     .replaceAll('(./protocol/)', '(#public-protocol-entrypoint)')
+    .replaceAll('(./miniapp-publish/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/)')
+    .replaceAll('(./vite/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/)')
     .replaceAll('(../guide/)', '(recipes.md)');
 }