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

package/skill/references/recipes.md

@@ -24,7 +24,7 @@
 
 # 快速开始
 
-如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
+如果页面不需要小黑盒开放能力，可以不接入 SDK。这是最短接入路径：等待 SDK 就绪，然后读取当前用户登录态。
 
 ```ts
 import hbSDK from '@heybox/hb-sdk'
@@ -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,24 +60,29 @@ 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` 判断。
+`ready()` 表示 SDK 已就绪，可以安全调用开放能力。如果当前不在可用的小程序运行环境中，它会抛出公开错误。`ready()` 不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
 
 ## 默认单例适合什么场景
 
-默认单例适合一个页面只有一个 SDK 上下文的情况。大多数小程序页面都应该使用默认单例，因为它可以避免重复握手和重复维护事件监听。
-
-0.6 起根入口只提供唯一默认实例并在导入时立即握手，不再允许业务创建独立实例。测试需要隔离 bridge 时应在应用边界替换公开模块。
+大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
 
 ## User and login
 
@@ -87,6 +93,10 @@ stopAuthChange()
 
 - `user.getInfo()`：静默读取当前登录态与公开基础资料。
 - `auth.login()`：唤起黑盒登录流程，并返回登录后的最新公开用户资料。
+- `user.getCurrentUserDetail()`：读取当前用户展示详情。
+- `user.getCurrentUserProfile()`：读取当前用户敏感资料，需要对应平台权限。
+- `user.getPlatformAccountOverview()` / `getPlatformAccountInfo()`：读取平台账号概览或指定平台详情。
+- `user.getSteamGameList()`：读取当前用户 Steam 游戏库。
 
 ## 静默读取用户信息
 
@@ -123,9 +133,9 @@ async function ensureLogin() {
 }
 ```
 
-## 暴露字段
+## 基础资料与扩展资料
 
-SDK 只暴露允许给外部小程序读取的公开字段：
+`user.getInfo()` 和 `auth.login()` 的 `userInfo` 只包含三项公开基础字段：
 
 | 字段        | 类型     | 说明         |
 | ----------- | -------- | ------------ |
@@ -135,18 +145,35 @@ SDK 只暴露允许给外部小程序读取的公开字段：
 
 不会暴露 token、cookie、手机号或任何可用于调用主站私有接口的凭据。
 
+current-user scoped API 返回独立的 `UserScopedResult<T>`。未登录时是 `{ isLogin: false, data: null }`；已登录时才有 `data`。其中 `getCurrentUserProfile()` 可能返回生日、邮箱、教育和职业等敏感资料，必须按最小必要原则使用，并以平台权限结果为准；不要把这些字段理解为 `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
@@ -154,41 +181,41 @@ const stop = on('authChange', result => {
 
 # 事件与生命周期
 
-SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
+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)`；不要在注册后的同一执行流里立即取消。
+
 ## 事件列表
 
 | 事件         | 触发时机                 | 典型用途           |
 | ------------ | ------------------------ | ------------------ |
-| `launch`     | 小程序首次完成握手并启动 | 初始化一次性数据   |
-| `ready`      | SDK 可安全调用开放能力   | 标记 bridge 可用   |
+| `launch`     | 小程序首次启动           | 初始化一次性数据   |
+| `ready`      | SDK 可安全调用开放能力 | 标记 SDK 可用      |
 | `show`       | 小程序页面展示           | 刷新可见态数据     |
 | `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
-| `unload`     | 小程序页面即将卸载       | 清理资源           |
-| `error`      | 父容器或开放能力运行异常 | 统一错误上报       |
+| `unload`     | 当前小程序运行环境终止 | 清理资源并停止请求 |
+| `error`      | 小程序或开放能力运行异常 | 统一错误上报       |
 | `authChange` | 登录状态变化             | 刷新用户信息和权限 |
 
 完整载荷与事件名见：
@@ -202,51 +229,69 @@ stop()
 - UI 可见性相关逻辑放在 `show`、`hide`。
 - 用户状态不要只在页面加载时读一次，登录入口附近要监听 `authChange`。
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
+- 事件只派发给注册当时存在的监听器，不会重放；一次性 `launch`/`ready` 状态应以 `ready()` Promise 为准。
+- 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
 
 ## Error handling
 
 
 # 错误处理
 
-SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
+SDK 公开两类标准错误：
+
+- `HbMiniProgramSDKError`：SDK 初始化或开放能力调用失败。
+- `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
 }
 ```
 
-## SDK 内置错误
+## 处理原则
 
-| code              | 场景                              | 建议处理                           |
-| ----------------- | --------------------------------- | ---------------------------------- |
-| `NOT_IN_IFRAME`   | 当前页面不在小程序沙盒 iframe 中  | 提示运行环境错误，检查父容器接入   |
-| `MISSING_NONCE`   | URL 中缺少 `hb_mini_bridge_nonce` | 检查父容器 URL 注入逻辑            |
-| `READY_TIMEOUT`   | SDK 握手超时                      | 检查父容器是否幂等响应重试的 `sdk.handshake` |
-| `REQUEST_TIMEOUT` | 开放能力调用超时                  | 提示重试，并上报 method            |
-| `SDK_DESTROYED`   | SDK 已销毁但仍有请求未完成        | 检查销毁时机和并发请求             |
+- 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
+- 权限失败时给出可理解的提示，不要将它当成未登录。
+- 超时或运行环境不可用时，允许用户重试或退出当前流程。
+- 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
-父容器返回失败响应时，SDK 也会包装成 `HbMiniProgramSDKError`，此时 `code` 由父容器开放能力定义。
+完整错误码和字段见 [HbMiniProgramSDKError](api-root.md) 与 [HbMiniProgramNetworkError](api-root.md)。
 
 ## 业务层建议
 
 ```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
@@ -258,10 +303,6 @@ function reportSDKError(code: string, message: string, data?: unknown) {
 }
 ```
 
-## 超时时间
-
-默认握手超时时间是 10000ms。0.6 起业务不能通过独立实例修改该值；超时应作为 Host/Runtime 启动异常处理。
-
 ## Login gate recipe
 
 

package/skill/scripts/sync-references.mjs

@@ -93,13 +93,24 @@ function rewriteBundledRecipeLinks(markdown) {
   return markdown
     .replaceAll('(../recipes/custom-instance)', '(#custom-instance-recipe)')
     .replaceAll('(../reference/protocol/interfaces/MiniProgramEventPayloadMap)', '(api-root.md)')
-    .replaceAll('(../reference/protocol/types/#miniprogrameventname)', '(api-root.md)');
+    .replaceAll('(../reference/protocol/types/#miniprogrameventname)', '(api-root.md)')
+    .replaceAll('(../reference/root/classes/HbMiniProgramSDKError)', '(api-root.md)')
+    .replaceAll('(../reference/root/classes/HbMiniProgramNetworkError)', '(api-root.md)');
+}
+
+function rewriteBundledCliLinks(markdown) {
+  return markdown.replaceAll(
+    '(./mini-program-publishing-rules)',
+    '(https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)',
+  );
 }
 
 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)');
 }
 
@@ -189,7 +200,6 @@ const rootEntry = read('packages/hb-sdk/src/index.ts');
 const protocolEntry = read('packages/hb-sdk/src/protocol.ts');
 const viteEntry = read('packages/hb-sdk/src/vite/index.ts');
 const cliEntry = read('packages/hb-sdk/src/cli/index.ts');
-const cliTemplateReadme = read('packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs');
 const readme = read('packages/hb-sdk/README.md');
 const cliGuide = frontmatterless(read('apps/docs/hb-sdk/guide/cli.md'));
 const quickStart = frontmatterless(read('apps/docs/hb-sdk/guide/quick-start.md'));
@@ -208,20 +218,16 @@ const sdkRuntimeRelation = extractSection(readme, '## SDK 与 Runtime');
 const capabilityBoundaries = extractSection(readme, '## 能力边界');
 const manifestSection = extractSection(readme, '## Manifest');
 const cliSummarySection = extractSection(readme, '## CLI');
-const repositoryDevelopment = extractSection(readme, '## 本仓库开发');
-const cliCreateSection = extractSection(cliGuide, '## 创建外部小程序模板');
-const cliDevSection = [
-  extractSection(cliGuide, '## 本地开发模式'),
-  extractSection(cliGuide, '## Mock runtime 边界'),
-].filter(Boolean).join('\n\n');
+const cliCreateSection = extractSection(cliGuide, '## 创建工坊小程序');
+const cliDevSection = extractSection(cliGuide, '## 推荐调试流程');
 const cliDeploySection = extractSection(cliGuide, '## 部署发布');
 const cliRemoteSection = extractSection(cliGuide, '## 远端管理命令');
 const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
 const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
 const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
 const cliCommandSurface = `hb-sdk create <project-name>
-hb-sdk dev [--port <port>] [--mock-port <port>] [--runtime-url <url>] [--no-open]
-hb-sdk login [--login-base-url <url>] [--no-select-entity]
+hb-sdk dev [--port <port>] [--mock-port <port>] [--no-open]
+hb-sdk login
 hb-sdk login status
 hb-sdk login clear
 hb-sdk doctor
@@ -249,17 +255,15 @@ hb-sdk remote square show
 
 Removed: hb-sdk deploy`;
 
-const cliRemoteEntitySection = `Developer entity selection lives under \`hb-sdk remote entity\`:
+const cliRemoteEntitySection = `Developer account selection lives under \`hb-sdk remote entity\`:
 
 ${fenced('bash', `hb-sdk remote entity list
 hb-sdk remote entity current
 hb-sdk remote entity switch <entity-id>`)}
 
-The authoritative current entity is the developer platform server-side current entity. The CLI auth cache may contain a \`selectedEntity\` value, but that value is only a hint snapshot for \`hb-sdk login status\` display and drift troubleshooting. Do not use \`selectedEntity\` as the source of truth for permissions, ownership, create, bind, deploy, or release decisions.
+Remote management commands use the current developer account. Use \`current\` to confirm it and \`switch\` to change it before creating, binding, or publishing a mini-program.`;
 
-\`hb-sdk login\` tries to make the server-side current entity explicit after browser login. Zero entities leaves login successful and prints a guidance message. One entity is displayed and, when needed, switched to current. Multiple entities in a TTY prompt for a choice; multiple entities in non-interactive mode do not block login but tell the user to run \`hb-sdk remote entity switch <entity-id>\`. Passing \`--no-select-entity\` writes only the login state and does not modify the server-side current entity.`;
-
-const cliRemoteEntityDeploySection = `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.`;
+const cliRemoteEntityDeploySection = `Before publishing, \`hb-sdk remote deploy\` verifies that the bound mini-program belongs to the current developer account. If it does not, the command stops and asks the user to switch accounts.`;
 
 const files = new Map();
 
@@ -341,29 +345,23 @@ files.set('cli.md', `${header('CLI reference', [
   'packages/hb-sdk/src/cli/commands/create.ts',
   'packages/hb-sdk/src/cli/commands/dev.ts',
   'packages/hb-sdk/src/cli/commands/login.ts',
-  'packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs',
   'apps/docs/hb-sdk/guide/cli.md',
-  'packages/hb-sdk/README.md',
 ])}${contents([
   ['When to use the CLI', 'when-to-use-the-cli'],
   ['Command surface', 'command-surface'],
   ['Create a mini-program template', 'create-a-mini-program-template'],
-  ['Local dev and mock runtime', 'local-dev-and-mock-runtime'],
-  ['Deploy and backend operations', 'deploy-and-backend-operations'],
-  ['Remote entity scope', 'remote-entity-scope'],
+  ['Local debugging', 'local-debugging'],
+  ['Deploy and publish', 'deploy-and-publish'],
+  ['Developer account scope', 'developer-account-scope'],
   ['Remote management commands', 'remote-management-commands'],
-  ['CLI login cache', 'cli-login-cache'],
+  ['CLI login', 'cli-login'],
   ['Agent Skill doctor', 'agent-skill-doctor'],
   ['Update reminders', 'update-reminders'],
-  ['Repository validation commands', 'repository-validation-commands'],
-  ['Generated template README', 'generated-template-readme'],
 ])}## When to use the CLI
 
-Use the bundled \`hb-sdk\` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, managing the CLI's own Heybox auth cache, or inspecting/switching the developer platform current entity for remote mini-program management.
+Use the bundled \`hb-sdk\` CLI to create a workshop mini-program, open the local debugging page, test in the Heybox Mac or mobile App, or manage and publish a remote mini-program.
 
-Do not use the CLI to replace iframe SDK calls. \`hb-sdk login\` is for CLI commands only and does not change \`auth.login()\`, \`user.getInfo()\`, \`network.request()\`, or mock-host user state.
-
-The CLI, templates, and mock host are owned by \`${packageJson.name}\`. Do not create a second mock runtime package or move CLI guidance outside this package unless the package boundary changes.
+\`hb-sdk login\` is for development and publishing commands only. It does not change \`auth.login()\`, \`user.getInfo()\`, or \`network.request()\` inside a mini-program.
 
 ## Command surface
 
@@ -377,20 +375,20 @@ ${cliCreateSection}
 
 Agent rules:
 
-- Prefer \`hb-sdk create <project-name>\` for a new standalone external mini-program template.
+- Prefer \`hb-sdk create <project-name>\` for a new workshop mini-program.
 - After creation, the expected next steps are \`npm install\` and \`npm run dev\`.
 - Do not claim the CLI installs dependencies, initializes git, opens an editor, or overwrites non-empty directories.
 - Treat \`project-name\` as an unscoped npm package name and project directory.
 
-## Local dev and mock runtime
+## Local debugging
 
 ${cliDevSection}
 
-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.
+Use \`hb-sdk dev\` to open the local debugging page. The "在 Mac 版 APP 中启动" button opens the page in the Mac App; the "Mobile App" QR code opens it in the phone App after a LAN interface is selected. These entries remain available without CLI login or project binding, but managed capabilities are denied by default. The phone and computer must be on the same LAN. If an embedded browser cannot open the App, use the system browser.
 
-## Deploy and backend operations
+## Deploy and publish
 
-${cliDeploySection}
+${rewriteBundledCliLinks(cliDeploySection)}
 
 ${cliRemoteEntityDeploySection}
 
@@ -398,25 +396,18 @@ Agent rules:
 
 - Use \`hb-sdk remote deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
 - Use \`hb-sdk remote deploy --from-version <version> --release-note <text>\` to reuse a remote history artifact.
-- Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
+- If the bound mini-program does not belong to the current developer account, stop and ask the user to switch accounts.
 - Never recommend top-level \`hb-sdk deploy\`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest \`hb-sdk remote versions\` and then \`hb-sdk remote release <version>\` after approval. Do not send the user to Open for manual publish when the CLI command exists.
 - Use \`hb-sdk remote allowlist add <heybox_id>\` when preview access needs to be granted.
-- Use \`--api-base-url <url>\` or \`HB_SDK_API_BASE_URL\` for remote platform backend APIs.
-- Use \`--allow-unsafe-api-base-url\` or \`HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1\` only for local backend debugging against non-Heybox or non-HTTPS API origins.
-- Use \`--login-base-url <url>\` or \`HB_SDK_LOGIN_BASE_URL\` for CLI browser login and remote command login-environment validation.
-- Use \`packages/hb-sdk/src/cli/config.ts\` with \`RylaiServiceTagConfig\` only when Heybox backend API requests need the development-only \`x-rylai-service-tag\` header and matching \`special_tag\` query parameter.
-- Custom base URLs must be origin-only; API origins must be Heybox trusted HTTPS unless the unsafe debug switch is explicit. Do not include path, query, or hash.
-- Do not expect custom base URLs to affect \`hb-sdk doctor\`, npm latest checks, or mock-host \`network.request()\`.
 
-## Remote entity scope
+## Developer account scope
 
 ${cliRemoteEntitySection}
 
 Agent rules:
 
-- Treat the server-side current entity as the authority for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, reopen, and square-display workflows.
-- Treat CLI \`selectedEntity\` as a display/debug snapshot only; it can drift from the server-side current entity and must not be used as a permission source.
+- Treat the current developer account as the scope for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, reopen, and square-display workflows.
 - Use \`hb-sdk remote entity current\` when a user needs to confirm which entity create/deploy will use.
 - Use \`hb-sdk remote entity switch <entity-id>\` to change entity scope. Do not recommend \`--entity-id\` or an environment variable as a remote command override.
 - \`hb-sdk remote list\` lists mini-programs in the current entity scope only; do not promise cross-entity aggregation.
@@ -438,14 +429,13 @@ Agent rules:
 - Require confirmation or \`--yes\` for \`hb-sdk remote release\`, \`hb-sdk remote withdraw\`, \`hb-sdk remote take-down\`, \`hb-sdk remote reopen\`, and \`hb-sdk remote square hide\`.
 - Use \`--json\` for script consumption and keep stdout as exactly one JSON object.
 
-## CLI login cache
+## CLI login
 
 ${cliLoginSection}
 
 Agent rules:
 
-- Keep CLI auth cache separate from iframe SDK login state.
-- Keep \`selectedEntity\` guidance explicit: it is only a hint snapshot, while every remote command uses the server-side current entity.
+- Keep CLI login separate from the mini-program user login state.
 - It is correct to say status output is redacted.
 - Do not expose or template pkey, cookie, token, or private credential values.
 - Use \`hb-sdk login clear\` only to clear the \`hb-sdk\` CLI namespace.
@@ -459,19 +449,11 @@ Agent rules:
 - Use \`hb-sdk doctor\` for read-only diagnosis of local SDK, remote latest skill metadata, and local skill metadata.
 - Do not use \`hb-sdk doctor\` to auto-install skills; when installation or refresh is needed, tell the user to run \`npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk\`.
 - If doctor reports \`SDK_MISMATCH\`, tell the user to upgrade \`${packageJson.name}@latest\` before reinstalling the skill.
-- The supported local skill path is \`$CODEX_HOME/skills/hb-sdk/skill.json\`, falling back to \`~/.codex/skills/hb-sdk/skill.json\`.
 
 ## Update reminders
 
 ${cliUpdateSection}
 
-## Repository validation commands
-
-${repositoryDevelopment}
-
-## Generated template README
-
-${fenced('md', cliTemplateReadme)}
 `);
 
 files.set('recipes.md', `${header('Recipes', [

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.4-alpha.0+skill.20921fb44039",
+  "skillVersion": "0.6.5+skill.648cee8ae511",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.4-alpha.0",
-    "compatibility": "0.6.4-alpha.0"
+    "version": "0.6.5",
+    "compatibility": "0.6.5"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-20921fb44039d21908fb692fc7d593c1dbc3b4f5dfa8f36f24aa0258ce150d13"
+  "integrity": "sha256-648cee8ae5111e01f8e69264187b9501c9167eca7c53693079e2a487ef230106"
 }

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';