@heybox/hb-sdk 0.5.9 → 0.5.11

package/skill/scripts/sync-agent-skills-payload.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+import { Buffer } from 'node:buffer';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { HB_SDK_PACKAGE_NAME } from './skill-metadata.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HB_SDK_ROOT = path.resolve(SCRIPT_DIR, '../..');
+const REPO_ROOT = path.resolve(HB_SDK_ROOT, '../..');
+const WELL_KNOWN_ROOT = path.join('.well-known', 'agent-skills');
+const AGENT_SKILL_PACKAGES = [
+  {
+    packageName: HB_SDK_PACKAGE_NAME,
+    skillDir: 'skill',
+  },
+];
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+const TEXT_FILE_RE = /\.(?:md|mjs|js|cjs|ts|tsx|json|txt|sh|yaml|yml)$/i;
+const PREFERRED_ORDER = new Map([
+  ['SKILL.md', 0],
+  ['skill.json', 1],
+  ['references/api-root.md', 100],
+  ['references/api-protocol.md', 101],
+  ['references/cli.md', 102],
+  ['references/recipes.md', 103],
+  ['references/safety-boundaries.md', 104],
+  ['references/llms-index.md', 105],
+  ['references/examples.md', 106],
+  ['references/smoke-evaluation.md', 107],
+  ['scripts/sync-references.mjs', 200],
+  ['scripts/check-references.mjs', 201],
+  ['scripts/validate-skill.mjs', 202],
+  ['scripts/package-skill.mjs', 203],
+  ['scripts/package-skill.sh', 204],
+]);
+
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  let outDir = path.resolve(process.cwd(), '.agent-skills-payload');
+  let check = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--check') {
+      check = true;
+      continue;
+    }
+    if (arg === '--out-dir') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error('--out-dir requires a path argument');
+      }
+      outDir = path.resolve(process.cwd(), value);
+      index += 1;
+    }
+  }
+
+  return { outDir, check };
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function assertSafeRelativePath(relativePath, context) {
+  const normalized = path.posix.normalize(relativePath);
+
+  if (path.isAbsolute(relativePath) || normalized.startsWith('../') || normalized === '..') {
+    throw new Error(`${context} has unsafe path: ${relativePath}`);
+  }
+
+  if (normalized !== relativePath) {
+    throw new Error(`${context} must be normalized: ${relativePath}`);
+  }
+
+  if (relativePath.includes('/../') || relativePath.endsWith('/..')) {
+    throw new Error(`${context} cannot contain parent traversal: ${relativePath}`);
+  }
+
+  if (/\.zip$/i.test(relativePath)) {
+    throw new Error(`${context} must not include zip archives: ${relativePath}`);
+  }
+}
+
+function parseFrontmatter(skillText, skillPath) {
+  const match = skillText.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new Error(`${skillPath} is missing YAML frontmatter`);
+  }
+
+  const metadata = {};
+  for (const rawLine of match[1].split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#') || line.startsWith('metadata:')) {
+      continue;
+    }
+
+    const keyValue = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!keyValue) {
+      continue;
+    }
+
+    const [, key, rawValue] = keyValue;
+    metadata[key] = rawValue.replace(/^['"]|['"]$/g, '').trim();
+  }
+
+  return metadata;
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonFile(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+async function resolvePackageRoot(packageSource) {
+  if (packageSource.packageName !== HB_SDK_PACKAGE_NAME) {
+    throw new Error(`Unsupported agent skill package: ${packageSource.packageName}`);
+  }
+
+  if (!(await exists(path.join(HB_SDK_ROOT, 'package.json')))) {
+    throw new Error(`Cannot resolve ${packageSource.packageName}: missing package root at ${toPosixPath(HB_SDK_ROOT)}`);
+  }
+
+  return HB_SDK_ROOT;
+}
+
+async function listFilesRecursive(rootDir, relativeBase = '', options = {}) {
+  if (!(await exists(rootDir))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (!options.includeHidden && entry.name.startsWith('.')) {
+      continue;
+    }
+
+    const absolutePath = path.join(rootDir, entry.name);
+    const relativePath = path.posix.join(relativeBase, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(absolutePath, relativePath, options)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+function sortSkillFiles(files) {
+  return [...files].sort((left, right) => {
+    const leftOrder = PREFERRED_ORDER.get(left) ?? 10_000;
+    const rightOrder = PREFERRED_ORDER.get(right) ?? 10_000;
+    return leftOrder - rightOrder || left.localeCompare(right);
+  });
+}
+
+async function discoverSkill(packageSource) {
+  const packageRoot = await resolvePackageRoot(packageSource);
+  const skillDir = path.join(packageRoot, packageSource.skillDir);
+  const skillMarkdownPath = path.join(skillDir, 'SKILL.md');
+
+  if (!(await exists(skillMarkdownPath))) {
+    throw new Error(`${packageSource.packageName} must provide ${packageSource.skillDir}/SKILL.md.`);
+  }
+
+  const skillMarkdown = await fs.readFile(skillMarkdownPath, 'utf8');
+  const frontmatter = parseFrontmatter(skillMarkdown, skillMarkdownPath);
+  const skillName = frontmatter.name;
+
+  if (!skillName) {
+    throw new Error(`${skillMarkdownPath} frontmatter must include name`);
+  }
+
+  if (!frontmatter.description) {
+    throw new Error(`${skillMarkdownPath} frontmatter must include description`);
+  }
+
+  const files = ['SKILL.md'];
+  const skillJsonPath = path.join(skillDir, 'skill.json');
+  let metadata = null;
+
+  if (await exists(skillJsonPath)) {
+    const relativeFile = 'skill.json';
+    assertSafeRelativePath(relativeFile, `${skillName} source file`);
+    files.push(relativeFile);
+    metadata = await readJsonFile(skillJsonPath);
+    if (metadata.name !== skillName) {
+      throw new Error(`${skillJsonPath} name (${metadata.name}) must match SKILL.md frontmatter (${skillName})`);
+    }
+  }
+
+  for (const topLevelDir of ['references', 'scripts', 'assets']) {
+    const nestedFiles = await listFilesRecursive(path.join(skillDir, topLevelDir), topLevelDir);
+    for (const relativeFile of nestedFiles) {
+      if (!TEXT_FILE_RE.test(relativeFile)) {
+        continue;
+      }
+      assertSafeRelativePath(relativeFile, `${skillName} source file`);
+      files.push(relativeFile);
+    }
+  }
+
+  return {
+    sourceDir: skillDir,
+    name: skillName,
+    description: frontmatter.description,
+    files: sortSkillFiles(files),
+    metadata,
+  };
+}
+
+async function discoverSkills() {
+  const skills = [];
+
+  for (const packageSource of AGENT_SKILL_PACKAGES) {
+    skills.push(await discoverSkill(packageSource));
+  }
+
+  if (skills.length === 0) {
+    throw new Error('No configured agent skills found.');
+  }
+
+  return skills;
+}
+
+export function createSkillIndex(skills) {
+  return {
+    skills: skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      ...(skill.metadata
+        ? {
+            version: skill.metadata.skillVersion,
+            sdk: skill.metadata.sdk,
+            source: skill.metadata.source,
+            integrity: skill.metadata.integrity,
+          }
+        : {}),
+      files: skill.files,
+    })),
+  };
+}
+
+async function addIndexFile(outputFiles, baseDir, skills) {
+  const indexPath = path.join(baseDir, WELL_KNOWN_ROOT, 'index.json');
+  const index = createSkillIndex(skills);
+
+  outputFiles.set(indexPath, Buffer.from(`${JSON.stringify(index, null, 2)}\n`, 'utf8'));
+}
+
+async function addSkillFiles(outputFiles, baseDir, skills) {
+  for (const skill of skills) {
+    for (const relativeFile of skill.files) {
+      assertSafeRelativePath(relativeFile, `${skill.name} generated file`);
+      const sourcePath = path.join(skill.sourceDir, ...relativeFile.split('/'));
+      const targetPath = path.join(baseDir, WELL_KNOWN_ROOT, skill.name, ...relativeFile.split('/'));
+      outputFiles.set(targetPath, await fs.readFile(sourcePath));
+    }
+  }
+}
+
+async function buildExpectedOutput(skills, targetRoot) {
+  const outputFiles = new Map();
+
+  await addIndexFile(outputFiles, targetRoot, skills);
+  await addSkillFiles(outputFiles, targetRoot, skills);
+
+  return outputFiles;
+}
+
+async function listExistingGeneratedFiles(targetRoot) {
+  if (!(await exists(targetRoot))) {
+    return [];
+  }
+
+  const relativeFiles = await listFilesRecursive(targetRoot, '', { includeHidden: true });
+  return relativeFiles.map((relativeFile) => path.join(targetRoot, ...relativeFile.split('/')));
+}
+
+async function syncFiles(expectedOutput, targetRoot) {
+  await fs.rm(targetRoot, { recursive: true, force: true });
+
+  for (const [targetPath, content] of [...expectedOutput.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content);
+  }
+}
+
+async function checkFiles(expectedOutput, targetRoot) {
+  const expectedPaths = new Set(expectedOutput.keys());
+  const existingPaths = new Set(await listExistingGeneratedFiles(targetRoot));
+  const problems = [];
+
+  for (const expectedPath of [...expectedPaths].sort()) {
+    if (!existingPaths.has(expectedPath)) {
+      problems.push(`missing ${path.relative(REPO_ROOT, expectedPath)}`);
+      continue;
+    }
+
+    const actual = await fs.readFile(expectedPath);
+    const expected = expectedOutput.get(expectedPath);
+    if (!actual.equals(expected)) {
+      problems.push(`stale ${path.relative(REPO_ROOT, expectedPath)}`);
+    }
+  }
+
+  for (const existingPath of [...existingPaths].sort()) {
+    if (!expectedPaths.has(existingPath)) {
+      problems.push(`extra ${path.relative(REPO_ROOT, existingPath)}`);
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new Error(`Agent skills payload is out of sync:\n${problems.map((problem) => `- ${problem}`).join('\n')}`);
+  }
+}
+
+async function main() {
+  const { outDir, check } = parseCliArgs(process.argv);
+  const skills = await discoverSkills();
+  const expectedOutput = await buildExpectedOutput(skills, outDir);
+
+  if (check) {
+    await checkFiles(expectedOutput, outDir);
+    console.log(
+      `Agent skills payload is in sync at ${toPosixPath(path.relative(REPO_ROOT, outDir))} (${expectedOutput.size} files, ${skills.length} skills).`,
+    );
+    return;
+  }
+
+  await syncFiles(expectedOutput, outDir);
+  console.log(
+    `Synced ${skills.length} skills to ${toPosixPath(path.relative(REPO_ROOT, outDir))} (${expectedOutput.size} files).`,
+  );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.9+skill.06627017a5ee",
+  "skillVersion": "0.5.11+skill.20c209340580",
   "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-06627017a5ee6a42c9d684c5d498bd255857a256139547fc5683f9a0af269f9a"
+  "integrity": "sha256-20c209340580ee5507bb72eb8cd044693b29e109472e93fc3d8302a53b4770d2"
 }

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 {
     /** 向父容器调用指定开放能力。 */

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;

package/types/protocol/capabilities.d.ts

@@ -1,4 +1,5 @@
 import type { LoginPayload, LoginResult } from '../modules/auth';
+import type { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult } from '../modules/cloud';
 import type { SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult } from '../modules/device';
 import type { ClosePayload, CloseResult, OpenAppPagePayload, OpenAppPageResult, ReloadPayload, ReloadResult } from '../modules/navigation';
 import type { NetworkRequestPayload, NetworkResponsePayload } from '../modules/network';
@@ -96,6 +97,16 @@ export declare const NAVIGATION_CLOSE_METHOD: "navigation.close";
 export declare const NAVIGATION_RELOAD_METHOD: "navigation.reload";
 /** 打开黑盒 App 页面能力方法名。 */
 export declare const NAVIGATION_OPEN_APP_PAGE_METHOD: "navigation.openAppPage";
+/** 提交当前用户排行榜分数能力方法名。 */
+export declare const CLOUD_LEADERBOARD_SUBMIT_METHOD: "cloud.leaderboard.submit";
+/** 读取排行榜列表能力方法名。 */
+export declare const CLOUD_LEADERBOARD_GET_LIST_METHOD: "cloud.leaderboard.getList";
+/** 读取当前用户排行榜记录能力方法名。 */
+export declare const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD: "cloud.leaderboard.getCurrentUserEntry";
+/** 删除当前用户排行榜记录能力方法名。 */
+export declare const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD: "cloud.leaderboard.deleteCurrentUserEntry";
+/** 读取排行榜基础信息能力方法名。 */
+export declare const CLOUD_LEADERBOARD_GET_INFO_METHOD: "cloud.leaderboard.getInfo";
 /** 授权模块开放的方法名。 */
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 /** 用户模块开放的方法名。 */
@@ -114,10 +125,12 @@ export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_L
 export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
 /** Navigation 模块开放的方法名。 */
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
+/** Cloud 模块开放的方法名。 */
+export type MiniProgramCloudMethod = typeof CLOUD_LEADERBOARD_SUBMIT_METHOD | typeof CLOUD_LEADERBOARD_GET_LIST_METHOD | typeof CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD | typeof CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD | typeof CLOUD_LEADERBOARD_GET_INFO_METHOD;
 /** 父容器开放给小程序调用的 bridge method。 */
-export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod;
+export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod;
 /** 小程序开放能力所属模块。 */
-export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'ui' | 'device' | 'navigation';
+export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'ui' | 'device' | 'navigation' | 'cloud';
 /** 小程序开放能力风险级别，用于权限、审计和灰度策略。 */
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 /**
@@ -277,6 +290,36 @@ export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
     readonly capability: "navigation.openAppPage";
     readonly permission: "navigation.openAppPage";
     readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.submit";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.submit";
+    readonly permission: "cloud.leaderboard.write";
+    readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.getList";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.getList";
+    readonly permission: "cloud.leaderboard.read";
+    readonly risk: "low";
+}, {
+    readonly method: "cloud.leaderboard.getCurrentUserEntry";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.getCurrentUserEntry";
+    readonly permission: "cloud.leaderboard.currentUserEntry.read";
+    readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.deleteCurrentUserEntry";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.deleteCurrentUserEntry";
+    readonly permission: "cloud.leaderboard.currentUserEntry.delete";
+    readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.getInfo";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.getInfo";
+    readonly permission: "cloud.leaderboard.info.read";
+    readonly risk: "low";
 }];
 /** bridge method 到请求 payload 的映射。 */
 export interface MiniProgramCapabilityPayloadMap {
@@ -302,6 +345,11 @@ export interface MiniProgramCapabilityPayloadMap {
     [NAVIGATION_CLOSE_METHOD]: ClosePayload;
     [NAVIGATION_RELOAD_METHOD]: ReloadPayload;
     [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPagePayload;
+    [CLOUD_LEADERBOARD_SUBMIT_METHOD]: SubmitLeaderboardEntryPayload;
+    [CLOUD_LEADERBOARD_GET_LIST_METHOD]: GetLeaderboardListPayload | undefined;
+    [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryPayload | undefined;
+    [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryPayload | undefined;
+    [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoPayload | undefined;
 }
 /** bridge method 到标准化响应 payload 的映射。 */
 export interface MiniProgramCapabilityResultMap {
@@ -327,6 +375,11 @@ export interface MiniProgramCapabilityResultMap {
     [NAVIGATION_CLOSE_METHOD]: CloseResult;
     [NAVIGATION_RELOAD_METHOD]: ReloadResult;
     [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPageResult;
+    [CLOUD_LEADERBOARD_SUBMIT_METHOD]: SubmitLeaderboardEntryResult;
+    [CLOUD_LEADERBOARD_GET_LIST_METHOD]: GetLeaderboardListResult;
+    [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryResult;
+    [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryResult;
+    [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoResult;
 }
 /** 指定 bridge method 的请求 payload。 */
 export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];

package/types/protocol.d.ts

@@ -1,9 +1,10 @@
 export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, SDK_HANDSHAKE_METHOD, } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
 export type { MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, } from './protocol/types';
-export { AUTH_LOGIN_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, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from './protocol/capabilities';
+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';
 export type { LoginPayload, LoginResult } from './modules/auth';
+export type { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, LeaderboardEntry, LeaderboardOrder, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, } from './modules/cloud';
 export type { GetCurrentUserDetailPayload, GetCurrentUserDetailResult, GetCurrentUserProfilePayload, GetCurrentUserProfileResult, GetPlatformAccountInfoPayload, GetPlatformAccountInfoResult, GetPlatformAccountOverviewPayload, GetPlatformAccountOverviewResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, MiniProgramUserInfo, MiniProgramUserInfoResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, } from './modules/user';
 export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
 export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';