npm - @heybox/hb-sdk - Versions diffs - 0.6.7 → 0.6.8-alpha.0 - Mend

@heybox/hb-sdk 0.6.7 → 0.6.8-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/CHANGELOG.md +226 -0
package/README.md +65 -583
package/dist/cli-chunks/{build-DaHCCSLH.cjs → build-BfhZ07Qv.cjs} +2 -2
package/dist/cli-chunks/{context-cQXupHub.cjs → context-CqoGNt7d.cjs} +1 -1
package/dist/cli-chunks/{create-D2dSw7bl.cjs → create-us7swTbU.cjs} +1 -1
package/dist/cli-chunks/{dev-D6WhI3cC.cjs → dev-Bf49EoR8.cjs} +5 -5
package/dist/cli-chunks/{doctor-CtNS5Tt2.cjs → doctor-CzETlRvH.cjs} +1 -1
package/dist/cli-chunks/{index-B1w-Jpba.cjs → index-BMhV2-vd.cjs} +14 -14
package/dist/cli-chunks/{index-C4y2G95g.cjs → index-Cd37cCQM.cjs} +1 -1
package/dist/cli-chunks/{login-D-ZK-n1E.cjs → login-Cb5ShNVQ.cjs} +2 -2
package/dist/cli-chunks/{project-vite-J4lrUja0.cjs → project-vite-WP6NzC3p.cjs} +1 -1
package/dist/cli-chunks/{remote-BZNHAL5_.cjs → remote-Co84uKvV.cjs} +4 -4
package/dist/cli-chunks/{session-5ryBp2wZ.cjs → session-9A8AY7YK.cjs} +1 -1
package/dist/cli.cjs +1 -1
package/dist/index.cjs.js +1 -1
package/dist/index.esm.js +1 -1
package/dist/vite.cjs.js +1 -1
package/dist/vite.esm.js +1 -1
package/package.json +3 -1
package/skill/references/api-protocol.md +0 -10
package/skill/references/api-root.md +153 -353
package/skill/references/safety-boundaries.md +6 -9
package/skill/scripts/sync-references.mjs +10 -20
package/skill/skill.json +4 -4

package/skill/references/api-root.md CHANGED Viewed

@@ -8,6 +8,10 @@
 - packages/hb-sdk/src/index.ts
 - packages/hb-sdk/src/vite/index.ts
 - packages/hb-sdk/README.md
+- apps/docs/hb-sdk/guide/quick-start.md
+- apps/docs/hb-sdk/guide/error-handling.md
+- apps/docs/hb-sdk/guide/lifecycle.md
+- apps/docs/hb-sdk/guide/cli.md
 ## Contents
@@ -19,7 +23,7 @@
 ## Package metadata
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.7`
+- Version at generation time: `0.6.8-alpha.0`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -357,435 +361,231 @@ function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
 }
 ```
-## Manifest
-`@heybox/hb-sdk/vite` 提供构建时插件 `miniappManifest()`。项目通过 `hb-sdk build` 完成生产构建后，会在固定的 `dist/` 中写入 `manifest.json`：
-```json
-{
-  "version": "1.2.3",
-  "sdkVersion": "0.6.1"
-}
-```
-`version` 来自小程序项目自身的 `package.json.version`，`sdkVersion` 来自当前安装 SDK 的构建版本且不能由业务覆盖。`hb-sdk build` 要求项目显式注册这个插件；`hb-sdk create` 生成的模板默认已注册，现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
-```ts
-import { miniappManifest } from '@heybox/hb-sdk/vite';
-import { defineConfig } from 'vite';
-export default defineConfig({
-  base: './',
-  plugins: [miniappManifest()],
-});
-```
-`base: './'` 用于让构建产物里的 JS/CSS/图片资源以 `./assets/...` 相对路径引用，避免小程序资源目录不是站点根路径时访问 `/assets/...` 失败。若没有显式配置 `base`，`miniappManifest()` 也会在 build 时默认补成 `./`。
-工坊小程序构建产物只能在兼容的小黑盒 Runtime 中启动。普通浏览器直接打开时不会执行标准业务脚本，并会提示在小黑盒 APP 内打开。项目应使用标准 Vite module 入口。
-插件只接受单页应用：输出目录只能存在入口 `index.html`。build 和 dev 都会把平台 CSP 插入 `<head>` 首位，已有 CSP 始终原样保留；两份策略按浏览器交集生效。平台 CSP 在脚本、样式、图片、字体和媒体指令中放行 `xiaoheihe.cn`、`max-c.com`、`debugmode.cn`、`maxjia.com` 的 HTTPS 根域及子域；入口 HTML 中相应资源标签也可使用这些官方 HTTPS URL。
-平台 CSP 会禁止 `fetch`、XHR、WebSocket、EventSource、Beacon、Worker、iframe、表单和对象加载等浏览器原生出口；`connect-src` 始终为 `'none'`，dev 只额外放行当前 Vite 的精确 HMR WebSocket 地址。需要宿主授权的业务网络请求仍应使用 `network.request()`。
-meta refresh、外部 anchor、`dns-prefetch`、`preconnect`、`prerender`、非官方外部资源 URL 和额外 HTML 会使 build 失败。内联 script/style 允许，但 `unsafe-eval` 不允许。`dev`、`hb-sdk build` 和手动 Vite build 都不请求远端最低 SDK 版本；构建仍会把当前 `sdkVersion` 写入 Manifest，`hb-sdk remote deploy` 仍校验 Manifest 结构并经过服务端 precheck / submit-audit 策略。
-失败与警告语义：
-- 读取 `package.json` 失败或 JSON 解析失败：build 直接失败，并输出具体原因。
-- `package.json.version` 不是非空字符串：build 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：build 直接失败，必须改成实际 SemVer。
-- 版本号不是严格 SemVer、包含 build metadata 或缺少 `sdkVersion`：build/deploy 直接失败。
-`manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
-## App-facing concepts
-## 快速开始
-创建一个新的外部小程序项目：
-```bash
-npx @heybox/hb-sdk create my-miniapp
-cd my-miniapp
-npm install
-npm run dev
-```
-模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。
-在已有项目中安装：
+## 生产构建
 ```bash
-npm install @heybox/hb-sdk
+hb-sdk build [--env <name>] [--verbose]
 ```
-然后在页面入口等待父容器 ready：
-```ts
-import hbSDK from '@heybox/hb-sdk';
-await hbSDK.ready();
+`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
-const user = await hbSDK.user.getInfo();
-if (user.isLogin) {
-  console.log(user.userInfo.nickname);
-}
-```
-也可以按需导入：
-```ts
-import { auth, ready, user } from '@heybox/hb-sdk';
-await ready();
-const currentUser = await user.getInfo();
-if (!currentUser.isLogin) {
-  await auth.login();
-}
-```
-## 运行环境
-SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注入 bridge nonce，并通过 `postMessage` 与 SDK 通信。普通浏览器直接打开小程序页面时通常无法完成握手；本地开发请优先使用：
-```bash
-npm run dev
-```
-调试页会通过 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 可以切换开发会话的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR。权限覆盖会持久化到 `hb-sdk` 的用户级本地缓存，并按项目真实路径与启动时绑定的 `miniProgramId` 隔离；即使远端权限暂时读取失败，也会继续使用已知绑定 scope。刷新调试页或重启 `hb-sdk dev` 后仍会恢复，直到点击“恢复初始权限”。未绑定项目使用独立匿名 scope，之后绑定小程序时不会继承匿名覆盖。调试页会分别展示远端基线与本地覆盖；多个调试页或进程写入同一 scope 时以最后成功写入的完整配置为准，不提供冲突合并。缓存写入失败时当前页面仍立即生效，同时明确提示刷新或重启后会丢失。已绑定项目重置时会先重新读取远端权限，读取失败则保留当前覆盖并显示错误；匿名项目直接清除本地覆盖。
-切换或恢复权限时，Mobile App 二维码会同步重生成，重新扫码后的局域网页面使用同一开发权限。二维码不会携带权限内容，只携带指向本机 Mock Host 的 `dev_context_url`；该 URL 使用 256-bit 随机 token，5 分钟后失效，调试页会在会话到期时自动生成新二维码。Runtime Host 会在创建小程序 Runtime 前拉取 token 对应的不可变权限快照，并校验开发页面 origin、会话期限和快照结构。
-Dev Session 中的 `network.request` 通过同一 token 绑定的本地代理转发，不会调用黑盒原生凭据 adapter，也不会携带 Cookie、pkey 等宿主凭据；`useOfficialDomain` 固定为 `false`。旧 `dev_network_request` query 不再提供授权，不能作为 Dev Session 快照的降级或覆盖入口。此链路只调整 Web 侧 CLI、Mock Host 和 Runtime Host，Android/iOS 客户端继续透传 URL，无需修改。官方域名权限只读取线上快照，本地设置不会修改线上权限；调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
-在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
+推荐由项目的 `scripts.build` 保留类型检查：
 ```json
 {
   "scripts": {
-    "dev": "hb-sdk dev"
-  }
-}
-```
-## 错误处理
-bridge、父容器运行时、协议校验或能力调用失败时会抛出 `HbMiniProgramSDKError`，其中包含稳定的 `code`、开发者可读的 `message` 和可选 `data`。
-```ts
-import { HbMiniProgramSDKError, ready } from '@heybox/hb-sdk';
-try {
-  await ready();
-} catch (error) {
-  if (error instanceof HbMiniProgramSDKError) {
-    console.log(error.code, error.message, error.data);
+    "build": "vue-tsc --noEmit && hb-sdk build"
   }
 }
 ```
-网络请求已完成但 HTTP 状态不满足 `validateStatus` 时会抛出 `HbMiniProgramNetworkError`，其 `response` 字段包含标准化后的 `status`、`headers`、`data` 和原始公共请求配置快照。
+构建命令只支持 `--env` 和 `--verbose`。已有项目继续使用 `vite build` 仍然兼容，不会自动迁移。
-## Public modules
+## App-facing concepts
-## 常用能力
-### 用户与登录
+# 快速开始
-`user.getInfo()` 只读取当前登录态，不会主动唤起登录。需要用户操作时再调用 `auth.login()`。
+如果页面不需要小黑盒开放能力，可以不接入 SDK。这是最短接入路径：等待 SDK 就绪，然后读取当前用户登录态。
 ```ts
-import { auth, user } from '@heybox/hb-sdk';
+import hbSDK from '@heybox/hb-sdk'
-const result = await user.getInfo();
+async function bootstrap() {
+  await hbSDK.ready()
-if (!result.isLogin) {
-  const loginResult = await auth.login();
-  console.log(loginResult.userInfo);
+  const result = await hbSDK.user.getInfo()
+  if (result.isLogin && result.userInfo) {
+    console.log(result.userInfo.nickname)
+    return
+  }
+  console.log('当前用户未登录')
 }
+bootstrap()
 ```
-SDK 只返回允许暴露给外部小程序的公开资料，不会返回 token、cookie、手机号或其他私有凭据。
+## 推荐业务写法
-需要当前用户更完整资料时，可以使用 current-user scoped API。这些 API 与 `user.getInfo()` 一样不会主动唤起登录；未登录时返回普通未登录结果，业务应只在用户操作后调用 `auth.login()`。
+业务页通常还需要监听登录态变化。下面以 Vue 3 为例：初始化只读取状态，登录必须由按钮等明确的用户操作触发，监听在组件卸载时清理。
 ```ts
-const detail = await user.getCurrentUserDetail();
+import { onUnmounted } from 'vue'
+import hbSDK from '@heybox/hb-sdk'
-if (detail.isLogin) {
-  console.log(detail.data.nickname, detail.data.level_info);
-}
+const stopAuthChange = hbSDK.on('authChange', result => {
+  if (result.isLogin) {
+    console.log('用户已登录', result.userInfo?.heybox_id)
+  }
+})
-const steam = await user.getPlatformAccountInfo('steam');
+await hbSDK.ready()
-if (steam.isLogin && steam.is_bound) {
-  console.log(steam.account_info.steamid);
-}
+const initialUser = await hbSDK.user.getInfo()
-const games = await user.getSteamGameList({
-  limit: 20,
-  sort: 'weeks',
-});
+async function loginFromUserAction() {
+  const result = await hbSDK.auth.login()
+  if (!result.isLogin || !result.userInfo) {
+    return
+  }
-if (games.isLogin && games.isBound) {
-  console.log(games.data.gameList);
+  console.log('用户已登录', result.userInfo.heybox_id)
 }
-```
-`user.getCurrentUserDetail()` 返回当前用户展示资料，`user.getCurrentUserProfile()` 返回更敏感的个人资料字段。`user.getPlatformAccountOverview()` 返回 `steam`、`epic`、`xbox`、`psn`、`switch`、`pc_hardware`、`mobile` 的绑定/隐藏状态；`user.getPlatformAccountInfo(platform)` 只支持这些平台字面量，未绑定平台返回 `account_info: null`，不会抛出未绑定错误。`user.getSteamGameList(options)` 返回当前用户 Steam 游戏库，未登录或未绑定 Steam 时返回状态对象；分页 `limit` 默认 20、最大 100，`sort` 支持 `weeks`、`all`、`achieved`。
-这些 API 仍然只面向当前登录用户，不支持传入 `userid` 查询其他人。平台账号详情和 Steam 游戏库会过滤好友列表、客户端路由协议和页面 UI 状态字段；敏感字段按独立 permission key 管理，后续可由宿主策略按能力或平台收紧。
-### 分享
-```ts
-import { share } from '@heybox/hb-sdk';
-await share.showShareMenu({
-  title: '我的小程序页面',
-  desc: '来自黑盒小程序的分享',
-  imageUrl: 'https://imgheybox.max-c.com/demo.png',
-  post: {
-    topicIds: [235709],
-    topics: ['无畏契约战绩'],
-  },
-});
+onUnmounted(stopAuthChange)
 ```
-工坊小程序通常不要传 `url`；宿主 runtime 会按当前小程序生成
-`/tools/common_share?user_miniprogram_id=...` 分享落地页。只有确实要分享外部
-HTTP(S) 页面时才显式传 `url`。
-`post` 用于给“转发到社区”预置可编辑的分区与话题。`topicIds` 接受正整数或非空字符串并按首次出现顺序去重；`topics` 只传话题内容，不要包含首尾 `#`。`showShareMenu()` 只支持一个默认分区，并且不能与 `channel` 同时使用；本地 Mock、App Dev Shell 和开发 Runtime 会直接拒绝这类错误，生产 Runtime 会过滤非法项、只取第一个分区并继续普通分享。`post: null` 等同于不配置。
+把 `loginFromUserAction` 绑定到登录按钮；不要在页面 bootstrap 阶段自动调用 `auth.login()`。
-截图分享：
+## ready 的含义
-```ts
-await share.screenshot({
-  delay: 100,
-  saveToAlbum: true,
-  post: {
-    topicIds: [235709, 66739],
-    topics: ['无畏契约战绩'],
-  },
-});
-```
+`ready()` 表示 SDK 已就绪，可以安全调用开放能力。如果当前不在可用的小程序运行环境中，它会抛出公开错误。`ready()` 不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
-截图分享支持多个预置分区；分区与话题仍由用户在客户端发帖页中确认和修改，SDK 不会直接发布内容。通过截图分享进入社区发帖流程时，客户端会自动把帖子关联到当前小程序，开发者无需配置额外来源字段。
+## 默认单例适合什么场景
-### 基础 UI
+大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
-```ts
-import { ui } from '@heybox/hb-sdk';
-await ui.showToast({
-  message: '保存成功',
-  status: 'success',
-});
+# 错误处理
-await ui.showLoading({
-  dismissible: true,
-});
+SDK 公开两类标准错误：
-await ui.hideLoading();
-```
-`showToast()` 的 `message` 会 trim 后发送给宿主，不能为空，最长 120 个字符；`status` 只支持 `success` 和 `error`，不传时展示普通文本 toast。loading 是全局单例，多次 `showLoading()` 会覆盖当前配置，`hideLoading()` 在未展示时也会成功。
-### 设备能力
+- `HbMiniProgramSDKError`：SDK 初始化或开放能力调用失败。
+- `HbMiniProgramNetworkError`：网络请求已返回，但 HTTP 状态未通过 `validateStatus`。
 ```ts
-import { device } from '@heybox/hb-sdk';
-await device.vibrate({
-  intensity: 'light',
-  delay: 0,
-});
-await device.setClipboard({
-  text: 'hello',
-});
-```
+import {
+  HbMiniProgramNetworkError,
+  HbMiniProgramSDKError,
+  network,
+} from '@heybox/hb-sdk'
-`vibrate()` 的 `intensity` 默认为 `light`，还支持 `medium` 和 `heavy`；`delay` 默认为 `0`，必须是 `0..5000` 的整数毫秒。`setClipboard()` 第一版只支持文本写入，`text` 必须是非空字符串，最长 10000 个字符，不会自动 trim 写入内容，也不提供读取或清空剪贴板能力。
+try {
+  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
+  }
-```ts
-import { navigation } from '@heybox/hb-sdk';
-await navigation.reload();
-await navigation.close();
-await navigation.openAppPage({
-  target: 'game_detail',
-  appId: 578080,
-  gameType: 'pc',
-});
-await navigation.openAppPage({
-  target: 'user_detail',
-  userId: '239040',
-});
-await navigation.openAppPage({
-  target: 'post_detail',
-  linkId: 57670836,
-  rootCommentId: 123,
-  commentId: 456,
-});
+  throw error
+}
 ```
-`navigation.close()` 请求宿主关闭当前小程序容器，`navigation.reload()` 请求宿主重载当前小程序页面/容器。调用后 JS 上下文可能被宿主销毁，不保证后续代码继续执行；这两个能力不接受 `reason`、`force`、`confirm` 或 `fallbackUrl` 等扩展参数。
+## 处理原则
-`navigation.openAppPage()` 请求宿主打开受 SDK 白名单约束的黑盒 App 页面。当前支持 `target: 'game_detail'`，必填 `appId` 与 `gameType`；`gameType` 支持 `pc`、`console`、`mobile`，可选 `page: 'game' | 'wiki'`、`hSrc`、`skuId`。也支持 `target: 'user_detail'`，必填 `userId`；支持 `target: 'post_detail'`，必填 `linkId`，可选 `rootCommentId` 与 `commentId` 定位评论。
+- 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
+- 权限失败时给出可理解的提示，不要将它当成未登录。
+- 超时或运行环境不可用时，允许用户重试或退出当前流程。
+- 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
-### 窗口信息
-```ts
-import { viewport } from '@heybox/hb-sdk';
+完整错误码和字段见 [HbMiniProgramSDKError](api-root.md) 与 [HbMiniProgramNetworkError](api-root.md)。
-const windowInfo = await viewport.getWindowInfo();
-console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
-```
-### 导航栏样式
+## 业务层建议
 ```ts
-import { viewport } from '@heybox/hb-sdk';
-await viewport.setNavigationBarStyle({
-  foregroundStyle: 'light',
-});
-```
-`foregroundStyle` 设置导航栏关闭按钮与状态栏图标/文字的明暗样式：`light` 表示白色前景，适合深色背景；`dark` 表示黑色前景，适合浅色背景。该能力不设置导航栏背景色，也不支持关闭按钮与状态栏分别配置。
-### 隔离 Storage
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+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 { status: 'ready', user: await hbSDK.user.getInfo() }
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError) {
+      reportSDKError(error.code, error.message, error.data)
+      return { status: 'failed', error }
+    }
+    throw error
+  }
+}
-```ts
-import { storage } from '@heybox/hb-sdk';
-await storage.setStorage({
-  key: 'settings',
-  data: {
-    theme: 'dark',
-  },
-});
-const { data } = await storage.getStorage<{ theme: string }>({
-  key: 'settings',
-});
+function reportSDKError(code: string, message: string, data?: unknown) {
+  console.log('[hb-sdk]', code, message, data)
+}
 ```
-storage key 只允许 1-128 位字母、数字、下划线和连字符。父容器会按小程序维度隔离 key，外部小程序不能读写黑盒客户端全局 storage。
-### 云端排行榜
-`cloud.leaderboard` 是平台托管的远端排行榜能力，不是本地 storage，也不是通用网络请求。小程序页面不能传 `userId`；宿主和服务端会按当前登录用户注入身份。
-```ts
-import { cloud } from '@heybox/hb-sdk';
-const entry = await cloud.leaderboard.submit({
-  key: 'cube_run_total',
-  score: 150,
-  extra: {
-    run: 2,
-  },
-});
-const list = await cloud.leaderboard.getList({
-  key: 'cube_run_total',
-  limit: 20,
-});
-const current = await cloud.leaderboard.getCurrentUserEntry({
-  key: 'cube_run_total',
-});
-await cloud.leaderboard.deleteCurrentUserEntry({
-  key: 'cube_run_total',
-});
-const info = await cloud.leaderboard.getInfo({
-  key: 'cube_run_total',
-});
-```
+## Public modules
-排行榜需要先通过管理端创建；管理端创建成功时服务端会同步准备记录集合，之后运行时可立即读写。`key` 不传时服务端会查找当前小程序已创建的 `default` 榜单，不存在时会拒绝请求，不会自动创建空榜。单个小程序最多创建 3 个排行榜，超出时服务端返回 `LEADERBOARD_LIMIT_EXCEEDED`。
+## 能力概览
-`order` 在创建榜单时固定，`desc` 表示分数越大越靠前，`asc` 表示分数越小越靠前。同分时按更早更新时间优先，再按 `userId` 稳定排序。`rankLimit` 为 `0` 表示列表不限制展示名次；大于 `0` 时限制 `getList()` 展示范围。当前用户记录仍会保留，但 `submit()` 和 `getCurrentUserEntry()` 只精确计算前 5000 名，且会优先受 `rankLimit` 限制；超过 `min(rankLimit, 5000)`（`rankLimit=0` 时按 5000）时返回 `ranked: false`、`rank: 0`。
+除 `ready()` 外，SDK 还提供 `on()` 和 `off()` 处理前后台、登录态等生命周期事件。
-`submit()` 只在本次 `score` 更优时更新当前用户记录，并返回最终 `LeaderboardEntry`；如果分数不更优，`extra` 也不会更新。同一用户同一榜单的并发提交由服务端串行保护，锁冲突时返回 `LEADERBOARD_SUBMIT_LOCKED`，业务可稍后重试。首次提交未传 `extra` 会保存为空对象；已有记录提交更优分数但未传 `extra` 时会保留旧 `extra`，需要清空时请显式传 `{}`。`score` 必须是有限安全数字，绝对值不能超过 `Number.MAX_SAFE_INTEGER`；`extra` 必须是 JSON 对象，序列化后的 UTF-8 长度不能超过 2048 字节。
+| 模块         | 用途                             |
+| ------------ | -------------------------------- |
+| `auth`       | 由用户操作触发登录               |
+| `user`       | 读取当前用户、账号资料和游戏数据 |
+| `share`      | 打开分享或截图分享流程           |
+| `ui`         | 展示 Toast 和 Loading            |
+| `device`     | 调用振动和剪贴板能力             |
+| `navigation` | 关闭、刷新页面或打开小黑盒页面   |
+| `viewport`   | 读取窗口信息和设置导航栏样式     |
+| `storage`    | 读写当前小程序的隔离存储         |
+| `cloud`      | 使用小程序云端排行榜             |
+| `network`    | 发起经过平台授权的网络请求       |
-`getList()` 默认 20 条、最多 100 条；`cursor` 是服务端返回的不透明分页游标，只能把上一页返回的值原样传给下一次 `getList()`，不要解析、拼接或自行构造。非法 cursor 会按参数错误拒绝。服务端会短暂缓存榜单头部结果，当前缓存前 500 条或 `rankLimit` 范围内记录，`submit()`、`deleteCurrentUserEntry()` 和管理端删榜会触发缓存失效；业务不要依赖毫秒级实时刷新。`getInfo()` 返回 `key/order/rankLimit`，其中 `rankLimit` 不包含当前用户记录的 5000 名精确排名计算上限。
+具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
-排行榜后端错误会保留为 `HbMiniProgramSDKError.code`，常见值包括 `LEADERBOARD_DEFAULT_NOT_FOUND`、`LEADERBOARD_LIMIT_EXCEEDED`、`LEADERBOARD_SUBMIT_LOCKED`、`LEADERBOARD_TABLE_NOT_READY`、`InvalidArgument`、`NotFound`、`ResourceExhausted`、`Unauthenticated`。业务可以按 `code` 区分未建榜、并发提交、数据表配置异常、参数错误、容量限制和未登录等场景。
-### 网络请求
+# 事件与生命周期
-`network.request()` 提供窄化的 axios-like 接口。SDK 只接受公开请求字段，真实请求由父容器运行时映射到宿主网络能力。
+SDK 通过 `on` 监听小程序生命周期和业务事件。
 ```ts
-import { HbMiniProgramNetworkError, network } from '@heybox/hb-sdk';
-try {
-  const response = await network.request<{ ok: boolean }>({
-    url: 'https://api.example.com/demo',
-    method: 'GET',
-    headers: {
-      accept: 'application/json',
-    },
-  });
+import { onUnmounted } from 'vue'
+import { on } from '@heybox/hb-sdk'
-  console.log(response.status, response.data.ok);
-} catch (error) {
-  if (error instanceof HbMiniProgramNetworkError) {
-    console.log(error.response.status, error.response.data);
-  }
+function handleShow(payload: { timestamp: number; source?: string }) {
+  console.log('show from', payload.source)
 }
-```
-默认只有 `2xx` 会 resolve；`4xx/5xx` 这类已完成 HTTP 响应会抛出 `HbMiniProgramNetworkError`。可以用 `validateStatus` 调整 SDK 本地判定逻辑，函数不会跨 bridge 传给父容器。
+const stopShow = on('show', handleShow)
+const stopHide = on('hide', () => {
+  console.log('小程序页面隐藏')
+})
-```ts
-await network.request({
-  url: 'https://api.example.com/demo',
-  validateStatus: (status) => status < 500,
-});
-```
-支持的 HTTP method 为 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`。
-`network.request` 由平台 Runtime 权限控制。未授权时 SDK 会收到 `PERMISSION_DENIED` 和“当前小程序暂不支持网络请求”；即使已开启网络请求，访问黑盒官方域名仍需要运营侧单独开启官方域名配置。业务代码不能自行请求或注入 Cookie、pkey 等官方凭据。
+function stopLifecycleEvents() {
+  stopShow()
+  stopHide()
+}
-权限开启后，`network.request` 可以访问任意 HTTP(S) 目标，包括本机、局域网和保留地址。Runtime 不按目标地址类别拦截请求；宿主网络适配器仍负责实际连接、重定向和系统网络错误。
+onUnmounted(stopLifecycleEvents)
+```
-## 生命周期事件
+框架外也可以保存 `on()` 返回的取消函数，在页面或业务模块真正销毁时调用。需要按 handler 精确移除时再使用 `off(event, handler)`；不要在注册后的同一执行流里立即取消。
-导入 SDK 根包时会 eager 创建唯一默认实例并立即开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时不会创建第二个实例；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+## 事件列表
-```ts
-import { on } from '@heybox/hb-sdk';
+| 事件         | 触发时机                 | 典型用途           |
+| ------------ | ------------------------ | ------------------ |
+| `launch`     | 小程序首次启动           | 初始化一次性数据   |
+| `ready`      | SDK 可安全调用开放能力 | 标记 SDK 可用      |
+| `show`       | 小程序页面展示           | 刷新可见态数据     |
+| `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
+| `unload`     | 当前小程序运行环境终止 | 清理资源并停止请求 |
+| `error`      | 小程序或开放能力运行异常 | 统一错误上报       |
+| `authChange` | 登录状态变化             | 刷新用户信息和权限 |
-const unsubscribeShow = on('show', (payload) => {
-  console.log('页面展示', payload.timestamp, payload.source);
-});
+完整载荷与事件名见：
-const unsubscribeAuth = on('authChange', (payload) => {
-  console.log('登录态变化', payload.isLogin, payload.userInfo);
-});
+- [MiniProgramEventPayloadMap](api-root.md)
+- [MiniProgramEventName](api-root.md)
-unsubscribeShow();
-unsubscribeAuth();
-```
+## 生命周期建议
-当前可监听事件包括 `launch`、`ready`、`show`、`hide`、`unload`、`error`、`authChange`。
+- 初始化开放能力前先 `await ready()`。
+- UI 可见性相关逻辑放在 `show`、`hide`。
+- 用户状态不要只在页面加载时读一次，登录入口附近要监听 `authChange`。
+- 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
+- 事件只派发给注册当时存在的监听器，不会重放；一次性 `launch`/`ready` 状态应以 `ready()` Promise 为准。
+- 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。

package/skill/references/safety-boundaries.md CHANGED Viewed

@@ -8,16 +8,13 @@
 - apps/docs/hb-sdk/guide/auth.md
 ## Required boundaries
-## 能力边界
+## 关键约束
-- 导入 SDK 根包时会 eager 创建唯一默认实例并立即开始握手；`ready()` 只等待这次握手结果。
-- `ready()` 只等待已有握手结果，不主动触发新的握手；调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
-- `user.getInfo()`、`user.getCurrentUserDetail()`、`user.getCurrentUserProfile()`、`user.getPlatformAccountOverview()`、`user.getPlatformAccountInfo(platform)` 和 `user.getSteamGameList(options)` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
-- 当前用户详情和平台账号 API 只允许读取当前登录用户，不支持传入 `userid` 查询其他人，也不透传 `/account/home_v2/` 原始响应。
-- 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
-- `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
-- `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
-- 构建产物可以包含 `dist/manifest.json`，业务代码不应自行 fetch 已部署的 manifest；这个文件由发布流水线读取并上送后台。
+- `ready()` 不代表用户已登录；使用 `user.getInfo()` 判断登录状态。
+- `auth.login()` 只能由明确的用户操作触发，不要在页面初始化时自动登录。
+- `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
+- 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
 ## Agent rules