@heybox/hb-sdk 0.6.9 → 0.7.0-alpha.2

package/skill/SKILL.md

@@ -39,13 +39,16 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 ## Step 4: Implement workshop mini-program code
 
 1. Call `await ready()` or `await hbSDK.ready()` near page startup when the page uses SDK capabilities.
-2. Use `user.getInfo()` to read current login state without triggering login.
-3. Use `auth.login()` only when the user action requires login.
-4. Handle `HbMiniProgramSDKError` for SDK initialization and capability failures.
-5. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
-6. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
-7. Use the default SDK instance exposed by the root package.
-8. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
+2. For a network-enabled mini-program, use `auth.login({ scopes? })` to obtain `{ code, expiresIn: 300, scopes }`. Identity is always implicit; request only optional scopes the business actually needs.
+3. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
+4. For a network-disabled mini-program, call `user.getLocalIdentity()` from a trusted user action to obtain `{ appUserId }`, because first login or identity consent may require UI. It cannot obtain a code or call OpenAPI.
+5. Handle `HbMiniProgramSDKError` for SDK initialization and capability failures.
+6. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
+7. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
+8. Use the default SDK instance exposed by the root package.
+9. When authorization UI is required, call `auth.login()` or `user.getLocalIdentity()` from a trusted user action. Missing gesture returns `USER_GESTURE_REQUIRED`; cancelling, rejecting, or closing returns `AUTHORIZATION_CANCELLED` and does not confirm or change authorization. An already-authorized `auth.login()` request may return a new code silently.
+10. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` and `user.getLocalIdentity()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
+11. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
 
 ## Step 5: Use CLI workflows
 
@@ -56,7 +59,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 5. Keep `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the required Manifest or Runtime gate output is missing.
 6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
 7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
-8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for development and publishing commands. This login does not change the mini-program user's login state.
+8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for development and publishing commands. This login does not change `auth.login()`, `user.getLocalIdentity()`, or the mini-program user's authorization state.
 9. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
 10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
 11. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
@@ -79,16 +82,17 @@ For workshop mini-program business code:
 4. Use only the public `network.request` configuration.
 5. Do not use private package paths or client protocols.
 6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
+7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
+8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
 
 For CLI and local development:
 
 1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
-2. Do not use `hb-sdk login` as a workaround for mini-program user authentication.
+2. Do not use `hb-sdk login` as a workaround for `auth.login()` or mini-program user authorization.
 3. Use the built-in local debugging page instead of creating another browser Mock.
 4. Keep the Vite `miniappManifest()` plugin enabled.
-5. Treat Dev Context permission changes as persistent local overrides, not online configuration changes. `hb-sdk` scopes them by real project path and `miniProgramId`, restores them after page refresh or `hb-sdk dev` restart, and clears them only after an explicit reset successfully refetches remote permissions. A regenerated Mobile App QR code may carry only a `dev_context_url` backed by a 256-bit token that expires after 5 minutes; it must not embed a permission snapshot.
-6. Require the Runtime Host to fetch the immutable Dev Session snapshot before startup. Dev Session `network.request` must use the token-bound local proxy, never a native credential adapter, and must force `useOfficialDomain: false`.
-7. Do not treat the legacy `dev_network_request` query as authorization or as a fallback. This Web-only flow must preserve existing Android/iOS URL pass-through behavior without requiring client changes.
+5. Treat permission changes made in the `hb-sdk dev` debugging page as local debugging overrides, not online configuration changes. Use the page's reset action to return to the remote baseline.
+6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-protocol.md

@@ -23,13 +23,16 @@ 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 {
+  isOfficialMiniProgramNetworkUrl,
+  isProtectedMiniProgramNetworkPath,
+  MINI_PROGRAM_NETWORK_PROTECTED_PATHS,
+  normalizeMiniProgramNetworkPathname,
+} from './protocol/network-policy';
 export type {
   MiniProgramRuntimePermissionEntry,
   MiniProgramRuntimePermissionStatus,
@@ -43,12 +46,7 @@ export type {
   MiniProgramEventHandler,
   MiniProgramEventName,
   MiniProgramEventPayloadMap,
-  RuntimeLocationProbePayload,
-  SDKCSPBlockedResourceType,
-  SDKCSPViolationPayload,
   SDKHandshakePayload,
-  SDKLocationReportPayload,
-  SDKLocationReportTrigger,
 } from './protocol/types';
 export {
   AUTH_LOGIN_METHOD,
@@ -71,12 +69,10 @@ export {
   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_LOCAL_IDENTITY_METHOD,
+  USER_REVOKE_AUTHORIZATION_METHOD,
   USER_GET_STEAM_GAME_LIST_METHOD,
+  USER_GET_INFO_METHOD,
   VIEWPORT_GET_WINDOW_INFO_METHOD,
   VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
 } from './protocol/capabilities';
@@ -100,7 +96,7 @@ export type {
   MiniProgramUserMethod,
   MiniProgramViewportMethod,
 } from './protocol/capabilities';
-export type { LoginPayload, LoginResult } from './modules/auth';
+export type { LoginOptions, LoginPayload, LoginResult, LoginScope } from './modules/auth';
 export type {
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
@@ -116,25 +112,23 @@ export type {
   SubmitLeaderboardEntryResult,
 } from './modules/cloud';
 export type {
-  GetCurrentUserDetailPayload,
-  GetCurrentUserDetailResult,
-  GetCurrentUserProfilePayload,
-  GetCurrentUserProfileResult,
-  GetPlatformAccountInfoPayload,
-  GetPlatformAccountInfoResult,
-  GetPlatformAccountOverviewPayload,
-  GetPlatformAccountOverviewResult,
+  AuthorizedUserInfo,
+  GetLocalIdentityPayload,
+  GetLocalIdentityResult,
+  GetUserInfoPayload,
+  GetUserInfoResult,
+  RevokeAuthorizationPayload,
+  RevokeAuthorizationResult,
   GetSteamGameListOptions,
   GetSteamGameListPayload,
   GetSteamGameListResult,
-  GetUserInfoPayload,
-  GetUserInfoResult,
-  MiniProgramUserInfo,
   MiniProgramUserInfoResult,
+  UserInfoAuthorization,
+  UserInfoAuthorizationStatus,
   SteamGameListData,
   SteamGameListItem,
-  SteamGameListSort,
   SteamGamePrice,
+  SteamGameListSort,
 } from './modules/user';
 export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
 export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';
@@ -213,7 +207,7 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 3 | 67 | 57 | 0 |
-| Protocol API | 0 | 3 | 44 | 67 | 32 |
+| Root API | 2 | 3 | 51 | 52 | 0 |
+| Protocol API | 0 | 6 | 46 | 65 | 31 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
 | Vite API | 0 | 1 | 0 | 0 | 0 |

package/skill/references/api-root.md

@@ -20,10 +20,11 @@
 - [Vite plugin export](#vite-plugin-export)
 - [App-facing concepts](#app-facing-concepts)
 - [Public modules](#public-modules)
+- [Cloud leaderboard](#cloud-leaderboard)
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.9`
+- Version at generation time: `0.7.0-alpha.2`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -33,12 +34,8 @@
 ```ts
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
 export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud } from './core/singleton';
-export type {
-  MiniProgramEventHandler,
-  MiniProgramEventName,
-  MiniProgramEventPayloadMap,
-} from './protocol/types';
-export type { LoginPayload, LoginResult, MiniProgramAuthModule } from './modules/auth';
+export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
+export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
 export type {
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
@@ -56,47 +53,24 @@ export type {
   SubmitLeaderboardEntryResult,
 } from './modules/cloud';
 export type {
-  BasePlatformAccountInfo,
-  CurrentUserAvatarConfig,
-  CurrentUserAvatarDecoration,
-  CurrentUserBbsInfo,
-  CurrentUserDetail,
-  CurrentUserLevelInfo,
-  CurrentUserMedal,
-  CurrentUserProfile,
-  EpicPlatformAccountInfo,
-  GetCurrentUserDetailPayload,
-  GetCurrentUserDetailResult,
-  GetCurrentUserProfilePayload,
-  GetCurrentUserProfileResult,
-  GetPlatformAccountInfoPayload,
-  GetPlatformAccountInfoResult,
-  GetPlatformAccountOverviewPayload,
-  GetPlatformAccountOverviewResult,
+  AuthorizedUserInfo,
+  GetLocalIdentityPayload,
+  GetLocalIdentityResult,
+  GetUserInfoPayload,
+  GetUserInfoResult,
+  RevokeAuthorizationPayload,
+  RevokeAuthorizationResult,
   GetSteamGameListOptions,
   GetSteamGameListPayload,
   GetSteamGameListResult,
-  GetUserInfoPayload,
-  GetUserInfoResult,
-  MiniProgramUserInfo,
   MiniProgramUserInfoResult,
   MiniProgramUserModule,
-  MobilePlatformAccountInfo,
-  PcHardwareAccountInfo,
-  PlatformAccountInfoMap,
-  PlatformAccountOverview,
-  PlatformAccountResult,
-  PlatformAccountType,
-  PlatformStatItem,
-  PsnPlatformAccountInfo,
+  UserInfoAuthorization,
+  UserInfoAuthorizationStatus,
   SteamGameListData,
   SteamGameListItem,
-  SteamGameListSort,
   SteamGamePrice,
-  SteamPlatformAccountInfo,
-  SwitchPlatformAccountInfo,
-  UserScopedResult,
-  XboxPlatformAccountInfo,
+  SteamGameListSort,
 } from './modules/user';
 export type {
   MiniProgramScreenshotOptions,
@@ -121,12 +95,7 @@ export type {
   SetNavigationBarStylePayload,
   SetNavigationBarStyleResult,
 } from './modules/viewport';
-export type {
-  GetStoragePayload,
-  GetStorageResult,
-  MiniProgramStorageModule,
-  SetStoragePayload,
-} from './modules/storage';
+export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload } from './modules/storage';
 export type {
   MiniProgramNetworkHeaders,
   MiniProgramNetworkModule,
@@ -391,63 +360,66 @@ hb-sdk build [--env <name>] [--verbose]
 
 # 快速开始
 
-如果页面不需要小黑盒开放能力，可以不接入 SDK。这是最短接入路径：等待 SDK 就绪，然后读取当前用户登录态。
+如果页面不需要小黑盒开放能力，可以不接入 SDK。需要开放能力时，先等待 `ready()`，再根据小程序是否开通网络权限选择身份流程。
+
+## 未开通网络权限
+
+无网络小程序可以在本地能力中使用按小程序隔离的 `appUserId`：
 
 ```ts
-import hbSDK from '@heybox/hb-sdk'
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-async function bootstrap() {
+async function getLocalIdentityFromUserAction() {
   await hbSDK.ready()
 
-  const result = await hbSDK.user.getInfo()
-  if (result.isLogin && result.userInfo) {
-    console.log(result.userInfo.nickname)
-    return
+  try {
+    const { appUserId } = await hbSDK.user.getLocalIdentity()
+    return appUserId
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return undefined
+    }
+    throw error
   }
-
-  console.log('当前用户未登录')
 }
-
-bootstrap()
 ```
 
-## 推荐业务写法
+把 `getLocalIdentityFromUserAction` 绑定到按钮点击等可信用户操作。首次登录或 identity consent 需要 UI 而缺少可信手势时返回 `USER_GESTURE_REQUIRED`；取消或关闭时返回 `AUTHORIZATION_CANCELLED`，不会确认或改变授权状态。这条路径不能获取授权码或调用 OpenAPI，也不要把 `appUserId` 发送到外部服务。
 
-业务页通常还需要监听登录态变化。下面以 Vue 3 为例：初始化只读取状态，登录必须由按钮等明确的用户操作触发，监听在组件卸载时清理。
+## 已开通网络权限
 
-```ts
-import { onUnmounted } from 'vue'
-import hbSDK from '@heybox/hb-sdk'
+有网络小程序通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作：
 
-const stopAuthChange = hbSDK.on('authChange', result => {
-  if (result.isLogin) {
-    console.log('用户已登录', result.userInfo?.heybox_id)
-  }
-})
+```ts
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 await hbSDK.ready()
 
-const initialUser = await hbSDK.user.getInfo()
-
 async function loginFromUserAction() {
-  const result = await hbSDK.auth.login()
-  if (!result.isLogin || !result.userInfo) {
-    return
-  }
+  try {
+    const result = await hbSDK.auth.login({ scopes: ['profile'] })
 
-  console.log('用户已登录', result.userInfo.heybox_id)
+    await hbSDK.network.request({
+      url: 'https://api.example.com/session/heybox',
+      method: 'POST',
+      data: { code: result.code },
+    })
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return
+    }
+    throw error
+  }
 }
-
-onUnmounted(stopAuthChange)
 ```
 
-把 `loginFromUserAction` 绑定到登录按钮；不要在页面 bootstrap 阶段自动调用 `auth.login()`。
+返回值与边界以[用户身份与登录](/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
 
 ## ready 的含义
 
-`ready()` 表示 SDK 已就绪，可以安全调用开放能力。如果当前不在可用的小程序运行环境中，它会抛出公开错误。`ready()` 不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
+`ready()` 只表示 SDK 已就绪，可以安全调用开放能力。它不表示已经取得用户授权，也不返回用户身份。
 
-## 默认单例适合什么场景
+## 默认单例
 
 大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
 
@@ -460,11 +432,7 @@ SDK 公开两类标准错误：
 - `HbMiniProgramNetworkError`：网络请求已返回，但 HTTP 状态未通过 `validateStatus`。
 
 ```ts
-import {
-  HbMiniProgramNetworkError,
-  HbMiniProgramSDKError,
-  network,
-} from '@heybox/hb-sdk'
+import { HbMiniProgramNetworkError, HbMiniProgramSDKError, network } from '@heybox/hb-sdk'
 
 try {
   await network.request({ url: 'https://api.example.com/data' })
@@ -487,6 +455,9 @@ try {
 
 - 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
 - 权限失败时给出可理解的提示，不要将它当成未登录。
+- `USER_GESTURE_REQUIRED` 表示潜在授权 UI 缺少可信用户手势，应让用户点击按钮后重试。
+- `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
+- `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
 - 超时或运行环境不可用时，允许用户重试或退出当前流程。
 - 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -497,16 +468,22 @@ try {
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-type UserViewState =
-  | { status: 'ready'; user: Awaited<ReturnType<typeof hbSDK.user.getInfo>> }
+type LoginViewState =
+  | { status: 'ready' }
+  | { status: 'cancelled' }
   | { status: 'failed'; error: HbMiniProgramSDKError }
 
-async function loadUser(): Promise<UserViewState> {
+async function loginFromUserAction(): Promise<LoginViewState> {
   try {
     await hbSDK.ready()
-    return { status: 'ready', user: await hbSDK.user.getInfo() }
+    const result = await hbSDK.auth.login()
+    await exchangeCodeWithDeveloperServer(result.code)
+    return { status: 'ready' }
   } catch (error) {
     if (error instanceof HbMiniProgramSDKError) {
+      if (error.code === 'AUTHORIZATION_CANCELLED') {
+        return { status: 'cancelled' }
+      }
       reportSDKError(error.code, error.message, error.data)
       return { status: 'failed', error }
     }
@@ -515,29 +492,39 @@ async function loadUser(): Promise<UserViewState> {
   }
 }
 
-function reportSDKError(code: string, message: string, data?: unknown) {
-  console.log('[hb-sdk]', code, message, data)
+async function exchangeCodeWithDeveloperServer(code: string) {
+  await hbSDK.network.request({
+    url: 'https://api.example.com/session/heybox',
+    method: 'POST',
+    data: { code },
+  })
+}
+
+function reportSDKError(errorCode: string, message: string, data?: unknown) {
+  console.log('[hb-sdk]', errorCode, message, data)
 }
 ```
 
+授权码在取得后立即交给开发者服务端交换，不要写入页面状态、DOM、日志或持久化存储。UI 只处理服务端会话是否建立成功。
+
 ## Public modules
 
 ## 能力概览
 
 除 `ready()` 外，SDK 还提供 `on()` 和 `off()` 处理前后台、登录态等生命周期事件。
 
-| 模块         | 用途                             |
-| ------------ | -------------------------------- |
-| `auth`       | 由用户操作触发登录               |
-| `user`       | 读取当前用户、账号资料和游戏数据 |
-| `share`      | 打开分享或截图分享流程           |
-| `ui`         | 展示 Toast 和 Loading            |
-| `device`     | 调用振动和剪贴板能力             |
-| `navigation` | 关闭、刷新页面或打开小黑盒页面   |
-| `viewport`   | 读取窗口信息和设置导航栏样式     |
-| `storage`    | 读写当前小程序的隔离存储         |
-| `cloud`      | 使用小程序云端排行榜             |
-| `network`    | 发起经过平台授权的网络请求       |
+| 模块         | 用途                                                         |
+| ------------ | ------------------------------------------------------------ |
+| `auth`       | 获取交给开发者服务端交换的短期授权码                         |
+| `user`       | 使用 Host current-user APIs 或读取无网络小程序的本地隔离身份 |
+| `share`      | 打开分享或截图分享流程                                       |
+| `ui`         | 展示 Toast 和 Loading                                        |
+| `device`     | 调用振动和剪贴板能力                                         |
+| `navigation` | 关闭、刷新页面或打开小黑盒页面                               |
+| `viewport`   | 读取窗口信息和设置导航栏样式                                 |
+| `storage`    | 读写当前小程序的隔离存储                                     |
+| `cloud`      | 使用小程序云端排行榜                                         |
+| `network`    | 发起经过平台授权的网络请求                                   |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
@@ -571,15 +558,15 @@ onUnmounted(stopLifecycleEvents)
 
 ## 事件列表
 
-| 事件         | 触发时机                 | 典型用途           |
-| ------------ | ------------------------ | ------------------ |
-| `launch`     | 小程序首次启动           | 初始化一次性数据   |
-| `ready`      | SDK 可安全调用开放能力 | 标记 SDK 可用      |
-| `show`       | 小程序页面展示           | 刷新可见态数据     |
-| `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
-| `unload`     | 当前小程序运行环境终止 | 清理资源并停止请求 |
-| `error`      | 小程序或开放能力运行异常 | 统一错误上报       |
-| `authChange` | 登录状态变化             | 刷新用户信息和权限 |
+| 事件                      | 触发时机                 | 典型用途                         |
+| ------------------------- | ------------------------ | -------------------------------- |
+| `launch`                  | 小程序首次启动           | 初始化一次性数据                 |
+| `ready`                   | SDK 可安全调用开放能力   | 标记 SDK 可用                    |
+| `show`                    | 小程序页面展示           | 刷新可见态数据                   |
+| `hide`                    | 小程序页面隐藏           | 暂停轮询、暂停播放               |
+| `unload`                  | 当前小程序运行环境终止   | 清理资源并停止请求               |
+| `error`                   | 小程序或开放能力运行异常 | 统一错误上报                     |
+| `heybox_app_login_change` | 黑盒 APP 登录状态变化    | 刷新依赖 Host 当前用户的本地能力 |
 
 完整载荷与事件名见：
 
@@ -590,7 +577,35 @@ onUnmounted(stopLifecycleEvents)
 
 - 初始化开放能力前先 `await ready()`。
 - UI 可见性相关逻辑放在 `show`、`hide`。
-- 用户状态不要只在页面加载时读一次，登录入口附近要监听 `authChange`。
+- 使用 Host current-user APIs 的无网络小程序，可以在 `heybox_app_login_change` 后刷新本地状态。已开通网络权限的小程序使用 `auth.login()` 获取 code，并由开发者服务端维护业务会话。
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
 - 事件只派发给注册当时存在的监听器，不会重放；一次性 `launch`/`ready` 状态应以 `ready()` Promise 为准。
 - 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
+
+## 云端排行榜
+
+删除当前用户的排行榜成绩属于破坏性操作，只能在明确的用户操作和二次确认后执行：
+
+```ts
+async function deleteMyLeaderboardEntryFromUserAction() {
+  const confirmed = window.confirm('确定删除自己的榜单成绩吗？');
+  if (!confirmed) return;
+
+  try {
+    await hbSDK.cloud.leaderboard.deleteCurrentUserEntry({ key: 'cube_run_total' });
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError) {
+      console.error(error.code, error.message);
+    }
+    throw error;
+  }
+}
+```
+
+排行榜记录的 `extra` 会展示给榜单中的其他读取者，只能包含公开展示必需的数据；不得写入个人身份信息（PII）、token、设备标识或非必要行为数据。
+
+管理员删除完整榜单及其排名记录时，必须显式传入匹配的榜单 key 进行确认：
+
+```bash
+hb-sdk remote cloud leaderboard delete <key> --confirm <key>
+```

package/skill/references/cli.md

@@ -29,7 +29,7 @@
 
 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.
 
-`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.
+`hb-sdk login` is for development and publishing commands only. It does not authorize mini-program users and does not change `auth.login()`, `user.getLocalIdentity()`, or `network.request()` inside a mini-program.
 
 ## Command surface
 
@@ -113,12 +113,12 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 浏览器 Mock 支持热更新，适合快速检查：
 
 - 页面布局和主要交互
-- SDK 初始化、用户状态与登录流程
+- SDK 初始化与用户身份授权流程
 - 生命周期、Storage 和排行榜等能力
 
-Dev Context 中调整的 `network.request` 权限不会修改线上配置，但会持久化到 `hb-sdk` 用户级本地缓存，并按项目真实路径与启动时绑定的 `miniProgramId` 隔离；远端权限暂时读取失败时仍会使用已知绑定 scope。刷新调试页或重启 `hb-sdk dev` 后覆盖仍然生效，直到点击“恢复初始权限”；未绑定项目使用独立匿名 scope，之后绑定小程序时不会继承匿名覆盖。调试页会分别展示远端基线与本地覆盖，多页面或多进程写入同一 scope 时以最后成功写入的完整配置为准，不提供冲突合并。缓存写入失败时当前页面仍立即生效，并提示刷新或重启后会丢失。已绑定项目重置时会先重新读取远端权限，读取失败则保留当前覆盖；匿名项目直接清除本地覆盖。
+Dev Context 中调整的权限只影响当前本地调试，不会修改线上配置。调试页会区分线上基线与本地覆盖；恢复初始权限后重新按远端配置验收。
 
-切换权限后 Mobile App 二维码会自动重生成；二维码只携带使用 256-bit 随机 token 的 `dev_context_url`，并在 5 分钟后失效，调试页会在会话到期时自动生成新二维码。重新扫码后，Runtime Host 会拉取对应的不可变权限快照，再启动手机局域网预览。工坊小程序默认不能进行网络请求，网络权限暂未开放申请；不要把本地调试结果当成线上能力。
+切换权限后 Mobile App 二维码会自动重生成；旧二维码失效时按调试页提示重新扫码。工坊小程序默认不能进行网络请求，网络权限暂未开放申请；不要把本地调试结果当成线上能力。
 
 ### 3. 再用 Mac 或手机真机验收
 
@@ -127,20 +127,21 @@ Dev Context 中调整的 `network.request` 权限不会修改线上配置，但
 - 点击「在 Mac 版 APP 中启动」。
 - 在「Mobile App」区域选择局域网网卡，再用手机小黑盒 APP 扫码。
 
-手机与电脑需要处于同一局域网。二维码无法访问时，先确认选择了正确的 **Network** 网卡。发布前至少完成一次真实客户端验收。
+手机与电脑需要处于同一局域网。二维码默认使用 HTTPS `open_inapp` 包装链接；需要二维码直接编码裸 `heybox://` 协议时，以 `hb-sdk dev --raw-protocol` 启动。二维码无法访问时，先确认选择了正确的 **Network** 网卡。发布前至少完成一次真实客户端验收。
 
 ### 浏览器 Mock 的边界
 
-浏览器 Mock 用于提高开发效率，不代表正式线上环境。Dev Session 的网络请求只对绑定 token 的本机或局域网开发页面生效，通过本地代理转发，不使用黑盒原生凭据 adapter；`useOfficialDomain` 始终为 `false`。代理允许访问本机、局域网和保留地址，并对初始 URL 与每次重定向分别解析和固定连接地址。旧 `dev_network_request` query 不再授权，权限只能来自有效的不可变 Dev Session 快照。该方案不要求修改 Android/iOS 客户端；用户状态仍只保存在浏览器 Mock，线上权限、客户端兼容性和最终交互仍需按真实发布配置验收。
+浏览器 Mock 用于提高开发效率，不代表正式线上环境。本地网络调试通过开发工具转发，不提供黑盒原生凭据，也不能访问平台保留的 runtime auth 与 OpenAPI 内部路径。线上权限、客户端兼容性和最终交互仍需按真实发布配置验收。
 
 ### 常用参数
 
-| 参数                  | 用途                             |
-| --------------------- | -------------------------------- |
-| `--port <port>`       | 指定页面开发服务端口。           |
-| `--mock-port <port>`  | 指定本地调试端口。           |
-| `--no-open`           | 启动后不自动打开浏览器。         |
-| `--verbose`           | 出现问题时输出更详细的诊断信息。 |
+| 参数                 | 用途                                      |
+| -------------------- | ----------------------------------------- |
+| `--port <port>`      | 指定页面开发服务端口。                    |
+| `--mock-port <port>` | 指定本地调试端口。                        |
+| `--raw-protocol`     | 让手机二维码直接编码裸 `heybox://` 协议。 |
+| `--no-open`          | 启动后不自动打开浏览器。                  |
+| `--verbose`          | 出现问题时输出更详细的诊断信息。          |
 
 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.
 
@@ -196,13 +197,7 @@ hb-sdk remote deploy --release-note "修复登录状态展示"
 
 这条命令会完成检查、执行项目的 `scripts.build`、上传和提交审核，因此项目定义的类型检查仍会执行。默认在审核通过后等待手动发布；普通低风险版本可以追加 `--auto-publish`。完整命令见 `hb-sdk remote --help`，提交要求见[小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)。
 
-构建产物上传从 `0.6.8` 起强制使用服务端上传 session，`0.6.7` 及更早版本不能继续部署，请先升级 `@heybox/hb-sdk`。deploy 从整包签名开始到上传结束都把 `dist/` 视为稳定输出，不要在此期间由其他进程修改构建目录；上传中断后可重新执行 deploy，服务端会按已确认回执恢复缺失文件。
-
-普通 deploy 会按 API 环境、`miniProgramId` 和版本在本机缓存目录获取短文件锁，避免两个 CLI 进程同时构建并上传同一版本。进程异常退出后锁可按 PID 回收；缓存目录不可用时会降级为无锁执行，不影响上传主流程。`--from-version` 不执行本地构建和上传，因此不会获取该锁。
-
-上传信息、上传凭证和上传回调按每批最多 50 个文件串行处理，批内保持 4 并发。CLI 每批获取一次仅授权当前 session 目录前缀的凭证，并校验服务端返回的 key 和 size 与本地文件完全一致；任何异常都会停止后续上传且不会提交审核。
-
-普通构建上传时，CLI 会计算整包签名，并把相对路径和文件大小一起提交给服务端创建或恢复上传会话；同一账号下签名和文件清单一致时，服务端返回已有 session 与 `uploaded_keys`，CLI 只上传缺失文件。CLI 不保存本地上传会话缓存。构建产物变化时服务端会创建新的隔离目录，并尽力清理旧目录。上传回调在当前命令内失败会重试；仍失败时可重新执行 deploy，服务端根据 `uploaded_keys` 继续恢复，同 key 的 COS 重传是幂等的。
+`0.6.7` 及更早版本不能继续部署，请先升级 `@heybox/hb-sdk`。部署期间不要由其他进程修改 `dist/`；上传中断后可重新执行同一命令恢复。
 
 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.
 
@@ -255,7 +250,7 @@ Agent rules:
 
 ## CLI 登录态
 
-CLI 登录态只用于开发工具和远端管理，不等同于小程序内的用户登录态，也不会改变 `auth.login()` 或 `user.getInfo()` 的结果。
+CLI 登录态只用于开发工具和远端管理，不等同于小程序内的用户登录态，也不会改变 `auth.login()`、`user.getLocalIdentity()` 或开发者服务端会话。
 
 ```bash
 hb-sdk login status