@heybox/hb-sdk 0.5.10 → 0.5.12

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.5.9`
+- Version at generation time: `0.5.11`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -30,13 +30,29 @@
 export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
 export type { MiniProgramSDKOptions } from './core/client';
-export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation } from './core/singleton';
+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 {
+  DeleteCurrentUserLeaderboardEntryPayload,
+  DeleteCurrentUserLeaderboardEntryResult,
+  GetCurrentUserLeaderboardEntryPayload,
+  GetCurrentUserLeaderboardEntryResult,
+  GetLeaderboardInfoPayload,
+  GetLeaderboardInfoResult,
+  GetLeaderboardListPayload,
+  GetLeaderboardListResult,
+  LeaderboardEntry,
+  LeaderboardOrder,
+  MiniProgramCloudLeaderboardModule,
+  MiniProgramCloudModule,
+  SubmitLeaderboardEntryPayload,
+  SubmitLeaderboardEntryResult,
+} from './modules/cloud';
 export type {
   BasePlatformAccountInfo,
   CurrentUserAvatarConfig,
@@ -157,7 +173,7 @@ export type {
   ReloadResult,
 } from './modules/navigation';
 
-import { auth, device, navigation, network, off, on, ready, share, storage, ui, viewport, user } from './core/singleton';
+import { auth, cloud, device, navigation, network, off, on, ready, share, storage, ui, viewport, user } from './core/singleton';
 
 const hbSDK = {
   ready,
@@ -172,6 +188,7 @@ const hbSDK = {
   ui,
   device,
   navigation,
+  cloud,
 };
 
 export default hbSDK;
@@ -543,6 +560,49 @@ const { data } = await storage.getStorage<{ theme: string }>({
 
 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',
+});
+```
+
+排行榜需要先通过管理端创建；管理端创建成功时服务端会同步准备记录集合，之后运行时可立即读写。`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`。
+
+`submit()` 只在本次 `score` 更优时更新当前用户记录，并返回最终 `LeaderboardEntry`；如果分数不更优，`extra` 也不会更新。同一用户同一榜单的并发提交由服务端串行保护，锁冲突时返回 `LEADERBOARD_SUBMIT_LOCKED`，业务可稍后重试。首次提交未传 `extra` 会保存为空对象；已有记录提交更优分数但未传 `extra` 时会保留旧 `extra`，需要清空时请显式传 `{}`。`score` 必须是有限安全数字，绝对值不能超过 `Number.MAX_SAFE_INTEGER`；`extra` 必须是 JSON 对象，序列化后的 UTF-8 长度不能超过 2048 字节。
+
+`getList()` 默认 20 条、最多 100 条；`cursor` 是服务端返回的不透明分页游标，只能把上一页返回的值原样传给下一次 `getList()`，不要解析、拼接或自行构造。非法 cursor 会按参数错误拒绝。服务端会短暂缓存榜单头部结果，当前缓存前 500 条或 `rankLimit` 范围内记录，`submit()`、`deleteCurrentUserEntry()` 和管理端删榜会触发缓存失效；业务不要依赖毫秒级实时刷新。`getInfo()` 返回 `key/order/rankLimit`，其中 `rankLimit` 不包含当前用户记录的 5000 名精确排名计算上限。
+
+排行榜后端错误会保留为 `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 只接受公开请求字段，真实请求由父容器运行时映射到宿主网络能力。
@@ -580,7 +640,7 @@ await network.request({
 
 ## 生命周期事件
 
-使用 `on()` 监听父容器派发的小程序事件。`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
 
 ```ts
 import { on } from '@heybox/hb-sdk';

package/skill/references/cli.md

@@ -10,7 +10,7 @@
 - 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/h5/docs/hb_sdk/src/guide/cli.md
+- apps/docs/hb-sdk/guide/cli.md
 - packages/hb-sdk/README.md
 
 ## Contents
@@ -348,12 +348,12 @@ Agent rules:
 pnpm --filter @heybox/hb-sdk run test:unit
 pnpm --filter @heybox/hb-sdk run build:package
 pnpm --filter @heybox/hb-sdk run check:boundary
-pnpm --filter @heybox/hb-sdk run check:docs-sync
+pnpm exec hbexec hb-sdk check
 ```
 
 `check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。
 
-`check:docs-sync` 用于校验 `README`、文档站 llms 镜像、skill references 与公开 `agent-skills` payload 没有漏同步。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。
+`hbexec hb-sdk check` 只读校验 docs、skill references，并在临时目录生成与校验 `agent-skills` payload；不要求 canonical artifact 已存在，也不包含 changelog。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。
 
 ## Generated template README
 

package/skill/references/examples.md

@@ -5,7 +5,8 @@
 ## Sources
 
 - packages/hb-sdk/README.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/
+- apps/docs/hb-sdk/guide/**
+- apps/docs/hb-sdk/recipes/**
 ## Positive examples
 
 ### Minimal user info

package/skill/references/llms-index.md

@@ -4,42 +4,21 @@
 
 ## Sources
 
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/
-## Local generated docs entrypoint
+- apps/docs/hb-sdk/guide/**
+- apps/docs/hb-sdk/recipes/**
+- apps/docs/hb-sdk/reference/**
+- packages/hb-sdk/src/**
+## Offline references
 
-The docs site maintains `llms.txt` and markdown mirrors under `apps/h5/docs/hb_sdk/src/.vuepress/public/llms/`. Read `llms.txt` first for navigation, then the specific guide/reference/recipe markdown needed for the task.
+The bundled references are generated directly from hand-maintained docs, generated API owner sources, and SDK/CLI sources. They do not depend on the docs site's `.vitepress/public/llms` mirrors.
 
-```md
-# @heybox/hb-sdk
-> LLM-friendly index for the `@heybox/hb-sdk` documentation site. API Reference is auto-generated from public exports and source comments; Guide and Recipes are hand-maintained.
-This site documents the iframe-side SDK for external mini programs. For AI retrieval, fetch this index first, then follow the linked markdown mirrors under `./llms/`.
-## Docs
-- [Documentation home](./llms/README.md): 第一次接入时，按下面顺序读：
-- [Guide index](./llms/guide/README.md): Guide 面向第一次接入 `@heybox/hb-sdk` 的开发者，目标是先跑通，再理解边界。
-- [Reference index](./llms/reference/README.md): Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
-- [Recipes index](./llms/recipes/README.md): Recipes 放可以直接复制到业务里的场景写法。它比 Guide 更具体，比 Reference 更偏组合使用。
-- [LLM usage guide](./llms/guide/llms.md): 文档站会自动维护一份标准的 `llms.txt` 索引，以及一组给 AI 直接读取的 Markdown 镜像页，方便模型按文档树逐步抓取内容。
-## API Reference
-- [Root API](./llms/reference/root/README.md): 该页面收录从 `src/index.ts` 公开导出的 API。
-- [Protocol API](./llms/reference/protocol/README.md): 该页面收录从 `src/protocol.ts` 公开导出的 API。
-- [Root functions](./llms/reference/root/functions/README.md)
-- [Root interfaces](./llms/reference/root/interfaces/README.md): `on/off` 会基于该映射推导 handler 参数类型。 |
-- [Protocol interfaces](./llms/reference/protocol/interfaces/README.md): 所有请求失败都会被规范化成该结构，SDK 侧再包装为 `HbMiniProgramSDKError`。 |
-- [Root types](./llms/reference/root/types/README.md): `navigation.close` 不需要入参。
-- [Protocol types](./llms/reference/protocol/types/README.md): `navigation.close` 不需要入参。
-## Guides
-- [Agent Skill 安装](./llms/guide/agent-skill.md): `hb-sdk` Agent Skill 用来让 AI / Agent 按本仓库约定使用 `@heybox/hb-sdk` 和配套 `hb-sdk` CLI，包括 iframe 小程序接入、`ready`、用户信息、登录、事件、CLI 创建模板、`hb-sdk dev` 本地调试、CLI 登录态、协议边界和常见错误处理。
-- [用户与登录](./llms/guide/auth.md): 用户与授权模块当前分工：
-- [CLI 与本地 mock 调试](./llms/guide/cli.md): `@heybox/hb-sdk` 同时提供 iframe 内使用的 SDK 和配套 `hb-sdk` CLI。CLI 负责项目模板、本地 Vite 服务、浏览器 mock runtime host 和 CLI 自己的 Heybox 登录缓存；它不是 iframe SDK 登录态的替代品。
-- [错误处理](./llms/guide/error-handling.md): SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
-- [安装与运行环境](./llms/guide/installation.md): 如果工坊小程序只是普通展示页面，不调用黑盒开放能力，也不监听 SDK 生命周期事件，可以不安装、不引用、不初始化 `@heybox/hb-sdk`。父容器仍可能在 URL 上注入 `hb_mini_bridge_nonce`，业务页可以直接忽略。
-- [事件与生命周期](./llms/guide/lifecycle.md): SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
-- [小程序工坊上架规则 v2（试行）](./llms/guide/mini-program-publishing-rules.md): 本规则用于说明小程序工坊的小程序发布、上架和持续在线要求。通过审核不等于获得推荐或公开展示；工坊广场、推荐位、搜索等流量分发规则另行制定。
-- [快速开始](./llms/guide/quick-start.md): 如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
-## Recipes
-- [独立 SDK 实例](./llms/recipes/custom-instance.md): 大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。
-- [登录门禁](./llms/recipes/login-gate.md): 当业务动作必须登录后才能继续时，可以把登录态判断收敛成 `ensureLogin`。
-## Optional
-- Full markdown mirrors for the docs site are available under `./llms/guide/`, `./llms/reference/`, and `./llms/recipes/`.
-```
+- Root SDK and Vite API: `references/api-root.md`
+- Host/runtime protocol API: `references/api-protocol.md`
+- CLI and local development: `references/cli.md`
+- Common flows: `references/recipes.md`
+- Security and capability limits: `references/safety-boundaries.md`
+- Examples and evaluation: `references/examples.md`, `references/smoke-evaluation.md`
+
+## Online supplement
+
+Online `llms.txt` and markdown mirrors are optional supplements, not prerequisites for offline Skill use. Their canonical public URL is not frozen: on 2026-07-10 `https://docs.xiaoheihe.cn/hb_sdk/llms.txt` returned 404 and the legacy URL fetch timed out. Do not claim either endpoint is available without a fresh successful response.

package/skill/references/recipes.md

@@ -4,12 +4,12 @@
 
 ## Sources
 
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md
+- apps/docs/hb-sdk/guide/quick-start.md
+- apps/docs/hb-sdk/guide/auth.md
+- apps/docs/hb-sdk/guide/lifecycle.md
+- apps/docs/hb-sdk/guide/error-handling.md
+- apps/docs/hb-sdk/recipes/login-gate.md
+- apps/docs/hb-sdk/recipes/custom-instance.md
 
 ## Contents
 
@@ -76,7 +76,7 @@ stopAuthChange()
 
 默认单例适合一个页面只有一个 SDK 上下文的情况。大多数小程序页面都应该使用默认单例，因为它可以避免重复握手和重复维护事件监听。
 
-需要控制 `timeout`、注入测试 window 或隔离多个上下文时，再使用 [独立实例](../recipes/custom-instance.md)。
+需要控制 `timeout`、注入测试 window 或隔离多个上下文时，再使用 [独立实例](../recipes/custom-instance)。
 
 ## User and login
 
@@ -193,8 +193,8 @@ stop()
 
 完整载荷与事件名见：
 
-- [MiniProgramEventPayloadMap](../reference/protocol/interfaces/MiniProgramEventPayloadMap.md)
-- [MiniProgramEventName](../reference/protocol/types/README.md#miniprogrameventname)
+- [MiniProgramEventPayloadMap](../reference/protocol/interfaces/MiniProgramEventPayloadMap)
+- [MiniProgramEventName](../reference/protocol/types/#miniprogrameventname)
 
 ## 生命周期建议
 

package/skill/references/safety-boundaries.md

@@ -5,12 +5,13 @@
 ## Sources
 
 - packages/hb-sdk/README.md
-- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md
+- apps/docs/hb-sdk/guide/auth.md
 ## Required boundaries
 
 ## 能力边界
 
-- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
+- SDK 实例创建后会自动开始握手；默认单例仍按需懒创建，`ready()`、`on()` 或任意模块能力调用都会创建默认单例并开始握手。
+- `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 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。

package/skill/scripts/sync-references.mjs

@@ -177,16 +177,14 @@ 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/h5/docs/hb_sdk/src/guide/cli.md'));
-const llmsTxt = read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt');
-const quickStart = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md')); 
-const authGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md')); 
-const lifecycleGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md')); 
-const errorGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md')); 
-const loginGate = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md')); 
-const customInstance = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md')); 
-const referenceHome = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/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'));
+const authGuide = frontmatterless(read('apps/docs/hb-sdk/guide/auth.md'));
+const lifecycleGuide = frontmatterless(read('apps/docs/hb-sdk/guide/lifecycle.md'));
+const errorGuide = frontmatterless(read('apps/docs/hb-sdk/guide/error-handling.md'));
+const loginGate = frontmatterless(read('apps/docs/hb-sdk/recipes/login-gate.md'));
+const customInstance = frontmatterless(read('apps/docs/hb-sdk/recipes/custom-instance.md'));
+const referenceHome = frontmatterless(read('apps/docs/hb-sdk/reference/index.md'));
 const quickStartSection = extractSection(readme, '## 快速开始');
 const runtimeEnvironment = extractSection(readme, '## 运行环境');
 const publicCapabilities = extractSection(readme, '## 常用能力');
@@ -300,7 +298,7 @@ ${lifecycleEvents}
 files.set('api-protocol.md', `${header('Protocol API reference', [
   'packages/hb-sdk/src/protocol.ts',
   'packages/hb-sdk/README.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md',
+  'apps/docs/hb-sdk/reference/index.md',
 ])}${contents([
   ['Host/runtime-only warning', 'hostruntime-only-warning'],
   ['Public protocol entrypoint', 'public-protocol-entrypoint'],
@@ -330,7 +328,7 @@ files.set('cli.md', `${header('CLI reference', [
   '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/h5/docs/hb_sdk/src/guide/cli.md',
+  'apps/docs/hb-sdk/guide/cli.md',
   'packages/hb-sdk/README.md',
 ])}${contents([
   ['When to use the CLI', 'when-to-use-the-cli'],
@@ -463,12 +461,12 @@ ${fenced('md', cliTemplateReadme)}
 `);
 
 files.set('recipes.md', `${header('Recipes', [
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md',
+  'apps/docs/hb-sdk/guide/quick-start.md',
+  'apps/docs/hb-sdk/guide/auth.md',
+  'apps/docs/hb-sdk/guide/lifecycle.md',
+  'apps/docs/hb-sdk/guide/error-handling.md',
+  'apps/docs/hb-sdk/recipes/login-gate.md',
+  'apps/docs/hb-sdk/recipes/custom-instance.md',
 ])}${contents([
   ['Quick start', 'quick-start'],
   ['User and login', 'user-and-login'],
@@ -503,7 +501,7 @@ ${customInstance}
 
 files.set('safety-boundaries.md', `${header('Safety boundaries', [
   'packages/hb-sdk/README.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md',
+  'apps/docs/hb-sdk/guide/auth.md',
 ])}## Required boundaries
 
 ${capabilityBoundaries}
@@ -521,18 +519,30 @@ ${capabilityBoundaries}
 `);
 
 files.set('llms-index.md', `${header('LLM documentation index', [
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/',
-])}## Local generated docs entrypoint
+  'apps/docs/hb-sdk/guide/**',
+  'apps/docs/hb-sdk/recipes/**',
+  'apps/docs/hb-sdk/reference/**',
+  'packages/hb-sdk/src/**',
+])}## Offline references
+
+The bundled references are generated directly from hand-maintained docs, generated API owner sources, and SDK/CLI sources. They do not depend on the docs site's \`.vitepress/public/llms\` mirrors.
+
+- Root SDK and Vite API: \`references/api-root.md\`
+- Host/runtime protocol API: \`references/api-protocol.md\`
+- CLI and local development: \`references/cli.md\`
+- Common flows: \`references/recipes.md\`
+- Security and capability limits: \`references/safety-boundaries.md\`
+- Examples and evaluation: \`references/examples.md\`, \`references/smoke-evaluation.md\`
 
-The docs site maintains \`llms.txt\` and markdown mirrors under \`apps/h5/docs/hb_sdk/src/.vuepress/public/llms/\`. Read \`llms.txt\` first for navigation, then the specific guide/reference/recipe markdown needed for the task.
+## Online supplement
 
-${fenced('md', llmsTxt)}
+Online \`llms.txt\` and markdown mirrors are optional supplements, not prerequisites for offline Skill use. Their canonical public URL is not frozen: on 2026-07-10 \`https://docs.xiaoheihe.cn/hb_sdk/llms.txt\` returned 404 and the legacy URL fetch timed out. Do not claim either endpoint is available without a fresh successful response.
 `);
 
 files.set('examples.md', `${header('Smoke examples and anti-examples', [
   'packages/hb-sdk/README.md',
-  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/',
+  'apps/docs/hb-sdk/guide/**',
+  'apps/docs/hb-sdk/recipes/**',
 ])}## Positive examples
 
 ### Minimal user info

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.9+skill.02be68ce07ce",
+  "skillVersion": "0.5.11+skill.c0b2205c74df",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.5.9",
-    "compatibility": "0.5.9"
+    "version": "0.5.11",
+    "compatibility": "0.5.11"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-02be68ce07ce1cf0ecba354d764a47977e4fc3c189b5e4aed3cee1f844fddfd4"
+  "integrity": "sha256-c0b2205c74df6a619a08d4f9a974d89a796d1783cc30a1d698d875bd179fd8c3"
 }

package/types/core/client.d.ts

@@ -18,7 +18,7 @@ export interface MiniProgramSDKOptions {
     /** 精准 postMessage 目标 origin；未传时尝试推断，失败则回退为 `*`。 */
     targetOrigin?: string;
 }
-type MiniProgramRequesterArgs<Method extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayload<Method> extends void ? [payload?: MiniProgramCapabilityPayload<Method>] : [payload: MiniProgramCapabilityPayload<Method>];
+type MiniProgramRequesterArgs<Method extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayload<Method> extends void ? [payload?: MiniProgramCapabilityPayload<Method>] : undefined extends MiniProgramCapabilityPayload<Method> ? [payload?: MiniProgramCapabilityPayload<Method>] : [payload: MiniProgramCapabilityPayload<Method>];
 /** 模块 API 发起请求所需的最小能力。 */
 export interface MiniProgramRequester {
     /** 向父容器调用指定开放能力。 */
@@ -42,6 +42,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private readyTimer?;
     private handshakeRetryTimer?;
     private destroyed;
+    private runtimeUnavailable;
+    private runtimeUnavailableError?;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     ready(): Promise<void>;
@@ -62,6 +64,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private resolveReadyOnce;
     private failReady;
     private clearReadyTimers;
+    private markRuntimeUnavailable;
+    private getRuntimeUnavailableError;
     private rejectAllPending;
 }
 export {};

package/types/core/sdk.d.ts

@@ -1,5 +1,6 @@
 import { type MiniProgramSDKOptions } from './client';
 import { type MiniProgramAuthModule } from '../modules/auth';
+import { type MiniProgramCloudModule } from '../modules/cloud';
 import { type MiniProgramShareModule } from '../modules/share';
 import { type MiniProgramStorageModule } from '../modules/storage';
 import { type MiniProgramNetworkModule } from '../modules/network';
@@ -50,6 +51,8 @@ export declare class MiniProgramSDK {
     readonly device: MiniProgramDeviceModule;
     /** 导航与容器控制相关开放能力。 */
     readonly navigation: MiniProgramNavigationModule;
+    /** 云端数据相关开放能力。 */
+    readonly cloud: MiniProgramCloudModule;
     constructor(options?: MiniProgramSDKOptions);
     /**
      * 等待 SDK 与父容器完成握手。

package/types/core/singleton.d.ts

@@ -1,4 +1,5 @@
 import type { MiniProgramAuthModule } from '../modules/auth';
+import type { MiniProgramCloudModule } from '../modules/cloud';
 import type { MiniProgramShareModule } from '../modules/share';
 import type { MiniProgramStorageModule } from '../modules/storage';
 import type { MiniProgramNetworkModule } from '../modules/network';
@@ -49,5 +50,7 @@ export declare const ui: MiniProgramUiModule;
 export declare const device: MiniProgramDeviceModule;
 /** 默认 SDK 实例的 navigation 模块。 */
 export declare const navigation: MiniProgramNavigationModule;
+/** 默认 SDK 实例的 cloud 模块。 */
+export declare const cloud: MiniProgramCloudModule;
 /** 重置默认 SDK 实例，仅用于测试。 */
 export declare function resetDefaultSDKForTest(): void;

package/types/index.d.ts

@@ -1,9 +1,10 @@
 export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
 export type { MiniProgramSDKOptions } from './core/client';
-export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation } from './core/singleton';
+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 { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, LeaderboardEntry, LeaderboardOrder, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, } from './modules/cloud';
 export type { BasePlatformAccountInfo, CurrentUserAvatarConfig, CurrentUserAvatarDecoration, CurrentUserBbsInfo, CurrentUserDetail, CurrentUserLevelInfo, CurrentUserMedal, CurrentUserProfile, EpicPlatformAccountInfo, GetCurrentUserDetailPayload, GetCurrentUserDetailResult, GetCurrentUserProfilePayload, GetCurrentUserProfileResult, GetPlatformAccountInfoPayload, GetPlatformAccountInfoResult, GetPlatformAccountOverviewPayload, GetPlatformAccountOverviewResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, MiniProgramUserInfo, MiniProgramUserInfoResult, MiniProgramUserModule, MobilePlatformAccountInfo, PcHardwareAccountInfo, PlatformAccountInfoMap, PlatformAccountOverview, PlatformAccountResult, PlatformAccountType, PlatformStatItem, PsnPlatformAccountInfo, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SteamPlatformAccountInfo, SwitchPlatformAccountInfo, UserScopedResult, XboxPlatformAccountInfo, } from './modules/user';
 export type { MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareModule, MiniProgramShowShareMenuOptions, ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult, } from './modules/share';
 export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramViewportModule, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
@@ -26,5 +27,6 @@ declare const hbSDK: {
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;
     navigation: import(".").MiniProgramNavigationModule;
+    cloud: import(".").MiniProgramCloudModule;
 };
 export default hbSDK;

package/types/miniapp-publish/index.d.ts

@@ -10,6 +10,10 @@ export declare const CREATE_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_mi
 export declare const DETAIL_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/detail";
 export declare const USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist";
 export declare const UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist/update";
+export declare const CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/create";
+export declare const DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/detail";
+export declare const LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/list";
+export declare const DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = "/mall/developer/user_miniprogram/leaderboard/delete";
 export declare const PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/precheck";
 export declare const SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = "/mall/developer/user_miniprogram/version/submit_audit";
 export declare const USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = "/mall/developer/user_miniprogram/version/preview_info";

package/types/modules/cloud/index.d.ts

@@ -0,0 +1,100 @@
+import type { MiniProgramRequester } from '../../core/client';
+export { 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, } from '../../protocol/capabilities';
+/** 排行榜排序方向。 */
+export type LeaderboardOrder = 'asc' | 'desc';
+/** 排行榜记录。 */
+export interface LeaderboardEntry {
+    /** 排名；未进入展示范围或超出当前用户排名计算上限时为 0。 */
+    rank: number;
+    /** 是否进入展示范围并位于当前用户排名计算上限内。 */
+    ranked: boolean;
+    /** 当前记录所属用户 ID，由平台注入，前端不能传入。 */
+    userId: string;
+    /** 分数，排行榜唯一排序字段。 */
+    score: number;
+    /** 展示附加信息，不参与排序和查询。 */
+    extra: Record<string, unknown>;
+    /** 记录创建时间，秒级时间戳。 */
+    createdAt: number;
+    /** 记录更新时间，秒级时间戳。 */
+    updatedAt: number;
+}
+/** 提交当前用户排行榜分数。 */
+export interface SubmitLeaderboardEntryPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+    /** 本次提交分数，必须是有限安全数字，范围不超过 JavaScript safe number。 */
+    score: number;
+    /** 展示附加信息，不参与排序和查询；已有记录更新为更优分数时不传则保留旧值，序列化后不超过 2048 字节。 */
+    extra?: Record<string, unknown>;
+}
+/** 提交排行榜分数后返回的当前用户最终记录。 */
+export type SubmitLeaderboardEntryResult = LeaderboardEntry;
+/** 读取排行榜列表。 */
+export interface GetLeaderboardListPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+    /** 每页数量，默认 20，最大 100。 */
+    limit?: number;
+    /** 服务端返回的不透明分页游标；只能原样传回下一页，不能自行构造或解析。 */
+    cursor?: string;
+}
+/** 读取排行榜列表的分页结果。 */
+export interface GetLeaderboardListResult {
+    /** 当前页排行榜记录。 */
+    entries: LeaderboardEntry[];
+    /** 下一页不透明分页游标；仅当 hasMore 为 true 时可能返回。 */
+    cursor?: string;
+    /** 是否还有下一页。 */
+    hasMore: boolean;
+}
+/** 读取当前用户在排行榜中的记录。 */
+export interface GetCurrentUserLeaderboardEntryPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+}
+/** 当前用户排行榜记录；不存在时返回 undefined。 */
+export type GetCurrentUserLeaderboardEntryResult = LeaderboardEntry | undefined;
+/** 删除当前用户在排行榜中的记录。 */
+export interface DeleteCurrentUserLeaderboardEntryPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+}
+/** 删除当前用户排行榜记录的结果。 */
+export interface DeleteCurrentUserLeaderboardEntryResult {
+    /** 是否实际删除了已有记录。 */
+    deleted: boolean;
+}
+/** 读取排行榜基础信息。 */
+export interface GetLeaderboardInfoPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+}
+/** 排行榜基础配置。 */
+export interface GetLeaderboardInfoResult {
+    /** 排行榜 key。 */
+    key: string;
+    /** 排行榜排序方向。 */
+    order: LeaderboardOrder;
+    /** 列表展示名次上限；0 表示不限制。当前用户记录仍最多精确计算前 5000 名。 */
+    rankLimit: number;
+}
+/** 外部小程序可调用的云端排行榜模块。 */
+export interface MiniProgramCloudLeaderboardModule {
+    /** 提交当前用户分数。 */
+    submit(options: SubmitLeaderboardEntryPayload): Promise<SubmitLeaderboardEntryResult>;
+    /** 读取排行榜列表。 */
+    getList(options?: GetLeaderboardListPayload): Promise<GetLeaderboardListResult>;
+    /** 读取当前用户记录。 */
+    getCurrentUserEntry(options?: GetCurrentUserLeaderboardEntryPayload): Promise<GetCurrentUserLeaderboardEntryResult>;
+    /** 删除当前用户记录。 */
+    deleteCurrentUserEntry(options?: DeleteCurrentUserLeaderboardEntryPayload): Promise<DeleteCurrentUserLeaderboardEntryResult>;
+    /** 读取排行榜基础信息。 */
+    getInfo(options?: GetLeaderboardInfoPayload): Promise<GetLeaderboardInfoResult>;
+}
+/** 外部小程序可调用的云端能力模块。 */
+export interface MiniProgramCloudModule {
+    leaderboard: MiniProgramCloudLeaderboardModule;
+}
+export type { MiniProgramCloudMethod } from '../../protocol/capabilities';
+export declare function createCloudModule(requester: MiniProgramRequester): MiniProgramCloudModule;