@heybox/hb-sdk 0.6.3 → 0.6.4

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`，并在项目已绑定且 CLI 已登录时尝试查询真实 Runtime 权限快照。项目未绑定、未登录或远端暂时不可用时，命令会输出警告并继续启动 Vite 和内置 mock runtime host；此时使用缺失权限快照，`network.request` 等受管能力默认拒绝。远端权限读取成功时，mock host 使用真实快照，远端明确关闭的能力仍稳定返回 `PERMISSION_DENIED`。本地 `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 扫码。
 
 常用参数：
 
@@ -116,11 +116,13 @@ hb-sdk dev
 
 ## Mock runtime 边界
 
-`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境；浏览器 Mock 的 Runtime 权限只从 mock host 同源只读 bootstrap 接口读取，URL query 不能提供或覆盖权限。项目已绑定时，Mac 协议和手机二维码会把 `package.json.heybox.miniProgramId` 与本地页面地址交给 dev shell；H5 宿主按该 ID 从公开详情接口读取可信 Runtime 权限快照。项目未绑定时仍可使用默认拒绝受管能力的浏览器 Mock，但 Mac 和手机真机入口会明确提示先运行 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>`，并保持不可用。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动、手机扫码调试等调试入口，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。真实 Mac / Mobile App dev shell 加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。Mac 协议和手机二维码始终携带本地页面地址；远端 dev context 可用时还会携带已验证的小程序 ID，不可用时则进入匿名本地沙箱。真机 dev shell 不依赖公开 `detail` 查询完成启动。真实 Mac / Mobile App dev shell 加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
 
-本地 mock runtime 下已授权的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。远端权限可用时 Mock Host 使用远端详情返回的同一份权限快照；不可用时使用缺失快照并默认拒绝受管能力。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。
+浏览器 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。
 
 Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging. The phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell. 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.
 
@@ -132,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/` 读取和上传，复用指定历史版本产物提交审核。
@@ -149,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` 里：
@@ -165,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 策略仍然生效。
-
-默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。如需让指定用户预览未发布候选版本，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
+CLI 的 `dev` 启动、本地 Vite build、`remote deploy` 本地构建和 `--from-version` 路径都不主动查询或比较 `minimumSdkVersion`；Mac / Mobile dev shell 仍会在加载 iframe 前执行宿主侧兼容性与平台配置检查。Manifest 结构校验、版本 precheck 和服务端 submit-audit 策略仍然生效。
 
-内部测试或预发环境可通过 `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。
+默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。`--auto-publish` 只适用于普通低风险版本；重大功能、活动联动、商业化、用户数据、外部账号绑定或风控策略变更应保持手动发布。需要指定用户预览未发布候选版本时，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
 
-`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.
 
@@ -239,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
@@ -260,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:
 
@@ -283,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)');
 }
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.3+skill.e46d946d0d66",
+  "skillVersion": "0.6.4+skill.36b02466ef23",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.3",
-    "compatibility": "0.6.3"
+    "version": "0.6.4",
+    "compatibility": "0.6.4"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-e46d946d0d668d1f9fc60d49d0552ff3f7d8c15d69823e979b20307cdcb42a36"
+  "integrity": "sha256-36b02466ef23a54c71c1eff6f9610dfa63d25d423529b20a6d8d50c8f1e85eaf"
 }

package/types/protocol/runtime-permissions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+export declare function isManagedMiniProgramRuntimePermissionKey(key: string): boolean;
+/** Runtime 权限项的启用状态。 */
+export type MiniProgramRuntimePermissionStatus = 'enabled' | 'disabled';
+/** Runtime 权限快照中的单项权限配置。 */
+export interface MiniProgramRuntimePermissionEntry {
+    /** permission key。 */
+    key: string;
+    /** 当前权限状态。 */
+    status: MiniProgramRuntimePermissionStatus;
+    /** 由具体 permission key 定义的配置。 */
+    config: Record<string, unknown>;
+}
+/** 服务端下发的 Runtime schema v1 权限快照。 */
+export interface MiniProgramRuntimePermissionsSnapshot {
+    /** 权限快照 schema 版本，当前固定为 `1`。 */
+    schema_version: 1;
+    /** 可选的非负整数修订号。 */
+    revision?: number;
+    /** 权限配置列表。 */
+    entries: MiniProgramRuntimePermissionEntry[];
+}
+/** Runtime 权限快照的 fail-closed 解析结果。 */
+export interface ParsedMiniProgramRuntimePermissions {
+    /** 整份快照是否通过格式校验。 */
+    valid: boolean;
+    /** 通过校验的受管权限，以 permission key 索引。 */
+    permissions: Record<string, MiniProgramRuntimePermissionEntry>;
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+export declare function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMiniProgramRuntimePermissions;

package/types/protocol.d.ts

@@ -1,5 +1,7 @@
 export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, 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, MiniProgramBridgeMessageType, MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, RuntimeLocationProbePayload, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKLocationReportPayload, SDKLocationReportTrigger, } from './protocol/types';
 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_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_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, } from './protocol/capabilities';
 export type { MiniProgramDeviceMethod, MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from './protocol/capabilities';
@@ -9,9 +11,9 @@ export type { GetCurrentUserDetailPayload, GetCurrentUserDetailResult, GetCurren
 export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
 export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';
 export type { MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShowShareMenuOptions, } from './modules/share';
-export type { GetStoragePayload, GetStorageResult, SetStoragePayload, } from './modules/storage';
+export type { GetStoragePayload, GetStorageResult, SetStoragePayload } from './modules/storage';
 export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
 export type { MiniProgramNetworkHeaders, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
 export type { HideLoadingPayload, HideLoadingResult, MiniProgramToastStatus, ShowLoadingPayload, ShowLoadingResult, 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, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, ReloadPayload, ReloadResult, } from './modules/navigation';