@heybox/hb-sdk 0.2.0-alpha.0 → 0.2.0-alpha.1

package/skill/scripts/validate-skill.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import {
+  HB_SDK_PACKAGE_NAME,
+  HB_SDK_SKILL_NAME,
+  validateSkillManifest,
+} from './skill-metadata.mjs';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(scriptDir, '..');
+const packageRoot = path.resolve(skillRoot, '..');
+const repoRoot = findRepoRoot(process.cwd()) ?? findRepoRoot(skillRoot) ?? process.cwd();
+const errors = [];
+const warnings = [];
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    if (existsSync(path.join(dir, 'package.json')) && existsSync(path.join(dir, 'packages/hb-sdk/package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function rel(filePath) {
+  return path.relative(repoRoot, filePath).split(path.sep).join('/');
+}
+
+function skillRel(filePath) {
+  return path.relative(skillRoot, filePath).split(path.sep).join('/');
+}
+
+function fail(message) {
+  errors.push(message);
+}
+
+function warn(message) {
+  warnings.push(message);
+}
+
+function read(filePath) {
+  return readFileSync(filePath, 'utf8');
+}
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const fullPath = path.join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) out.push(...walk(fullPath));
+    else out.push(fullPath);
+  }
+  return out;
+}
+
+function parseFrontmatter(markdown) {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  const fields = new Map();
+  for (const line of match[1].split('\n')) {
+    const field = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (field) fields.set(field[1], field[2].replace(/^['"]|['"]$/g, ''));
+  }
+  return fields;
+}
+
+const requiredFiles = [
+  'SKILL.md',
+  'skill.json',
+  'references/api-root.md',
+  'references/api-protocol.md',
+  'references/cli.md',
+  'references/recipes.md',
+  'references/safety-boundaries.md',
+  'references/llms-index.md',
+  'references/examples.md',
+  'references/smoke-evaluation.md',
+  'scripts/sync-references.mjs',
+  'scripts/check-references.mjs',
+  'scripts/skill-metadata.mjs',
+  'scripts/validate-skill.mjs',
+  'scripts/package-skill.mjs',
+  'scripts/package-skill.sh',
+];
+
+for (const file of requiredFiles) {
+  const absolutePath = path.join(skillRoot, file);
+  if (!existsSync(absolutePath)) fail(`Missing required file: ${rel(absolutePath)}`);
+}
+
+const skillMdPath = path.join(skillRoot, 'SKILL.md');
+const packageJsonPath = path.join(repoRoot, 'packages/hb-sdk/package.json');
+const skillJsonPath = path.join(skillRoot, 'skill.json');
+
+if (existsSync(skillJsonPath) && existsSync(packageJsonPath)) {
+  try {
+    const skillJson = JSON.parse(read(skillJsonPath));
+    const packageJson = JSON.parse(read(packageJsonPath));
+
+    for (const error of validateSkillManifest({ manifest: skillJson, sdkVersion: packageJson.version })) {
+      fail(error);
+    }
+  } catch (error) {
+    fail(`skill.json must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+if (existsSync(skillMdPath)) {
+  const skillMd = read(skillMdPath);
+  const frontmatter = parseFrontmatter(skillMd);
+  if (!frontmatter) {
+    fail('SKILL.md must start with YAML frontmatter.');
+  } else {
+    const allowedFrontmatter = new Set(['name', 'description']);
+    for (const key of frontmatter.keys()) {
+      if (!allowedFrontmatter.has(key)) fail(`SKILL.md frontmatter must only include name and description; found ${key}.`);
+    }
+    const name = frontmatter.get('name');
+    const description = frontmatter.get('description');
+    if (name !== HB_SDK_SKILL_NAME) fail('SKILL.md frontmatter name must be `hb-sdk`.');
+    if (!description) fail('SKILL.md frontmatter description is required.');
+    if (description && description.length > 1024) fail('SKILL.md description must be <= 1024 characters.');
+    if (description && !description.includes("Don't use")) warn('Description should include negative triggers for discoverability.');
+  }
+
+  const lineCount = skillMd.split('\n').length;
+  if (lineCount > 500) fail(`SKILL.md must stay under 500 lines; found ${lineCount}.`);
+  if (!skillMd.includes('references/api-root.md')) fail('SKILL.md must point agents to references/api-root.md.');
+  if (!skillMd.includes('references/api-protocol.md')) fail('SKILL.md must point agents to references/api-protocol.md.');
+  if (!skillMd.includes('references/cli.md')) fail('SKILL.md must point agents to references/cli.md.');
+  if (!skillMd.includes('references/smoke-evaluation.md')) fail('SKILL.md must point evaluators to references/smoke-evaluation.md.');
+  if (!skillMd.includes('host/runtime') && !skillMd.includes('Host/runtime')) fail('SKILL.md must gate protocol usage to host/runtime tasks.');
+}
+
+const nestedReferenceFiles = existsSync(path.join(skillRoot, 'references'))
+  ? walk(path.join(skillRoot, 'references')).filter(file => path.dirname(path.relative(path.join(skillRoot, 'references'), file)).includes(path.sep))
+  : [];
+for (const file of nestedReferenceFiles) fail(`References must be one level deep: ${skillRel(file)}`);
+
+if (existsSync(path.join(skillRoot, 'README.md'))) fail('Do not create README.md inside hb-sdk skill; keep human distribution docs outside the skill folder.');
+if (existsSync(path.join(skillRoot, 'CHANGELOG.md'))) fail('Do not create CHANGELOG.md inside hb-sdk skill.');
+if (existsSync(path.join(skillRoot, 'INSTALLATION_GUIDE.md'))) fail('Do not create INSTALLATION_GUIDE.md inside hb-sdk skill.');
+
+const textFiles = existsSync(skillRoot)
+  ? walk(skillRoot).filter(file => /\.(md|yaml|yml|json|txt)$/.test(file))
+  : [];
+
+const negativeMarkers = [
+  'do not',
+  "don't",
+  'does not',
+  'must not',
+  'never',
+  'no ',
+  'without',
+  'forbidden',
+  'refuse',
+  'block',
+  'fail',
+  'negative',
+  '不会',
+  '不应',
+  '不要',
+  '不能',
+  '不开放',
+  '无',
+  '禁止',
+];
+const positiveCredentialPattern = /\b(read|extract|forward|store|persist|depend on|use|request|expose|get|parse|send)\b.*\b(token|cookie|credentials?|phone number|login state)\b/i;
+const unsupportedStoragePattern = /\b(removeStorage|clearStorage|getStorageInfo|getStorageV2|delete storage|clear storage)\b/i;
+const rawProtocolPattern = /\b(raw postMessage|construct bridge|bridge envelope|nonce handling|mutate bridge|sdk\.handshake)\b/i;
+const removedUserLoginPattern = /\b(?:hbSDK\.)?user\.login\s*\(/;
+
+for (const file of textFiles) {
+  const relative = skillRel(file);
+  const content = read(file);
+  if (removedUserLoginPattern.test(content)) {
+    fail(`Removed API guidance found in ${relative}: use auth.login() instead of user.login().`);
+  }
+
+  if (new RegExp(`${HB_SDK_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/(?!protocol\\b)[A-Za-z0-9_./-]+`).test(content)) {
+    fail(`Deep/internal hb-sdk import guidance found in ${relative}. Only @heybox/hb-sdk and @heybox/hb-sdk/protocol are allowed.`);
+  }
+
+  const lines = content.split('\n');
+  lines.forEach((line, index) => {
+    const lower = line.toLowerCase();
+    const isNegative = negativeMarkers.some(marker => lower.includes(marker));
+    if (positiveCredentialPattern.test(line) && !isNegative) {
+      fail(`Unsafe positive credential guidance in ${relative}:${index + 1}: ${line.trim()}`);
+    }
+    if (unsupportedStoragePattern.test(line) && !isNegative) {
+      fail(`Unsupported storage capability guidance in ${relative}:${index + 1}: ${line.trim()}`);
+    }
+    if (rawProtocolPattern.test(line) && !isNegative && !/host\/runtime|runtime|protocol|parent-container|parent container|父容器/i.test(line)) {
+      fail(`Raw protocol guidance without host/runtime context in ${relative}:${index + 1}: ${line.trim()}`);
+    }
+  });
+}
+
+const recipesPath = path.join(skillRoot, 'references/recipes.md');
+if (existsSync(recipesPath)) {
+  const recipes = read(recipesPath);
+  if (/api-protocol\.md/.test(recipes) && !/host\/runtime-only|host\/runtime|runtime only/i.test(recipes)) {
+    fail('references/recipes.md references api-protocol.md without a nearby host/runtime-only warning.');
+  }
+}
+
+const protocolPath = path.join(skillRoot, 'references/api-protocol.md');
+if (existsSync(protocolPath)) {
+  const protocol = read(protocolPath);
+  if (!/Host\/runtime-only warning/i.test(protocol)) fail('references/api-protocol.md must include a Host/runtime-only warning section.');
+}
+
+const zipPath = path.join(packageRoot, 'hb-sdk.zip');
+if (existsSync(zipPath)) {
+  const size = statSync(zipPath).size;
+  if (size <= 0) fail('packages/hb-sdk/hb-sdk.zip exists but is empty.');
+}
+
+for (const warning of warnings) console.error(`warning: ${warning}`);
+if (errors.length > 0) {
+  for (const error of errors) console.error(`error: ${error}`);
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, skillRoot: rel(skillRoot), checkedFiles: textFiles.length, warnings: warnings.length }));

package/skill/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "hb-sdk",
+  "skillVersion": "0.2.0-alpha.1+skill.66c7559e5e13",
+  "sdk": {
+    "package": "@heybox/hb-sdk",
+    "version": "0.2.0-alpha.1",
+    "compatibility": "0.2.0-alpha.1"
+  },
+  "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
+  "integrity": "sha256-66c7559e5e13eaaefc9718b0f643dffd5853c864913e57e5a65ab0c663553797"
+}

package/types/index.d.ts

@@ -5,12 +5,14 @@ export { ready, on, off, auth, user, share, viewport, storage, network } from '.
 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 * from './modules/auth';
-export * from './modules/user';
-export * from './modules/share';
-export * from './modules/viewport';
-export * from './modules/storage';
-export * from './modules/network';
+export { AUTH_LOGIN_METHOD, NETWORK_REQUEST_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, USER_GET_INFO_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, } from './protocol/capabilities';
+export type { MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from './protocol/capabilities';
+export type { LoginPayload, LoginResult, MiniProgramAuthModule } from './modules/auth';
+export type { GetUserInfoPayload, GetUserInfoResult, MiniProgramUserInfo, MiniProgramUserInfoResult, MiniProgramUserModule, } from './modules/user';
+export type { MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareModule, MiniProgramShowShareMenuOptions, ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult, } from './modules/share';
+export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramSafeArea, MiniProgramViewportModule, MiniProgramWindowInfoResult, } from './modules/viewport';
+export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload, } from './modules/storage';
+export type { MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
 import { off, on, ready } from './core/singleton';
 declare const hbSDK: {
     ready: typeof ready;

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

@@ -1,18 +1,11 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramUserInfoResult } from '../user';
-/**
- * 登录授权能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const AUTH_LOGIN_METHOD: "auth.login";
+export { AUTH_LOGIN_METHOD } from '../../protocol/capabilities';
 /** `auth.login` 不需要入参。 */
 export type LoginPayload = void;
 /** `auth.login` 返回登录流程结束后的最新用户登录态与公开基础资料。 */
 export type LoginResult = MiniProgramUserInfoResult;
-/** 授权模块开放的方法名。 */
-export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
+export type { MiniProgramAuthMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的授权模块。 */
 export interface MiniProgramAuthModule {
     /**

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

@@ -1,15 +1,11 @@
 import type { MiniProgramRequester } from '../../core/client';
-/**
- * 发起网络请求能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const NETWORK_REQUEST_METHOD: "network.request";
+export { NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
 /** `network.request` 请求头。 */
 export type MiniProgramNetworkHeaders = Record<string, string>;
 /** `network.request` 查询参数。 */
 export type MiniProgramNetworkParams = Record<string, unknown>;
+/** `network.request` 支持的 HTTP 方法。 */
+export type MiniProgramNetworkRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 /**
  * SDK 侧可配置的状态校验函数。
  *
@@ -31,7 +27,7 @@ export interface MiniProgramNetworkRequestConfig {
     /** 请求地址。 */
     url: string;
     /** HTTP 方法，默认 `GET`。 */
-    method?: string;
+    method?: MiniProgramNetworkRequestMethod;
     /** 查询参数，会被编码到请求 URL。 */
     params?: MiniProgramNetworkParams;
     /** 请求体。 */
@@ -53,7 +49,7 @@ export interface MiniProgramNetworkRequestConfig {
  */
 export interface NetworkRequestPayload {
     url: string;
-    method?: string;
+    method?: MiniProgramNetworkRequestMethod;
     params?: MiniProgramNetworkParams;
     data?: unknown;
     headers?: MiniProgramNetworkHeaders;
@@ -80,8 +76,7 @@ export interface MiniProgramNetworkResponse<T = unknown> extends NetworkResponse
     /** 发起请求时的 SDK 公共配置快照。 */
     config: MiniProgramNetworkRequestConfig;
 }
-/** 网络模块开放的方法名。 */
-export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD;
+export type { MiniProgramNetworkMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的网络模块。 */
 export interface MiniProgramNetworkModule {
     /**

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

@@ -1,17 +1,11 @@
 import type { MiniProgramRequester } from '../../core/client';
-import { SHARE_SCREENSHOT_METHOD, type ScreenshotResult } from './screenshot';
-import { SHARE_SHOW_SHARE_MENU_METHOD, type ShowShareMenuPayload, type ShowShareMenuResult } from './show-share-menu';
+import { type ScreenshotResult } from './screenshot';
+import { type ShowShareMenuPayload, type ShowShareMenuResult } from './show-share-menu';
 import type { MiniProgramScreenshotOptions } from './types';
 export * from './screenshot';
 export * from './show-share-menu';
 export * from './types';
-/**
- * 分享模块开放的方法名。
- *
- * @remarks
- * 该联合类型用于约束分享模块向父容器发起的 bridge method 集合。
- */
-export type MiniProgramShareMethod = typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
+export type { MiniProgramShareMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的分享模块。 */
 export interface MiniProgramShareModule {
     /** 展示基础分享面板。 */

package/types/modules/share/screenshot.d.ts

@@ -1,12 +1,6 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramScreenshotOptions } from './types';
-/**
- * 截图分享能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
+export { SHARE_SCREENSHOT_METHOD } from '../../protocol/capabilities';
 /** `share.screenshot` 入参。 */
 export type ScreenshotPayload = MiniProgramScreenshotOptions | undefined;
 /** `share.screenshot` 返回值由客户端协议决定。 */

package/types/modules/share/show-share-menu.d.ts

@@ -1,12 +1,6 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramShowShareMenuOptions } from './types';
-/**
- * 展示分享面板能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
+export { SHARE_SHOW_SHARE_MENU_METHOD } from '../../protocol/capabilities';
 /** `share.showShareMenu` 入参。 */
 export type ShowShareMenuPayload = MiniProgramShowShareMenuOptions;
 /** `share.showShareMenu` 返回值由客户端协议决定。 */

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

@@ -1,18 +1,5 @@
 import type { MiniProgramRequester } from '../../core/client';
-/**
- * 读取小程序隔离 storage 能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const STORAGE_GET_STORAGE_METHOD: "storage.getStorage";
-/**
- * 写入小程序隔离 storage 能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const STORAGE_SET_STORAGE_METHOD: "storage.setStorage";
+export { STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD } from '../../protocol/capabilities';
 /** `storage.getStorage` 入参。 */
 export interface GetStoragePayload {
     /** storage key。 */
@@ -34,8 +21,7 @@ export interface SetStoragePayload {
     /** 需要写入的数据。 */
     data: unknown;
 }
-/** Storage 模块开放的方法名。 */
-export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
+export type { MiniProgramStorageMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的 storage 模块。 */
 export interface MiniProgramStorageModule {
     /** 获取小程序隔离 storage。 */

package/types/modules/user/get-info.d.ts

@@ -1,12 +1,6 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramUserInfoResult } from './types';
-/**
- * 用户信息能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const USER_GET_INFO_METHOD: "user.getInfo";
+export { USER_GET_INFO_METHOD } from '../../protocol/capabilities';
 /**
  * `user.getInfo` 不需要入参。
  */

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

@@ -1,14 +1,8 @@
 import type { MiniProgramRequester } from '../../core/client';
-import { USER_GET_INFO_METHOD, type GetUserInfoResult } from './get-info';
+import { type GetUserInfoResult } from './get-info';
 export * from './get-info';
 export * from './types';
-/**
- * 用户模块开放的方法名。
- *
- * @remarks
- * 该联合类型用于约束用户模块向父容器发起的 bridge method 集合。
- */
-export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD;
+export type { MiniProgramUserMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的用户模块。 */
 export interface MiniProgramUserModule {
     /**

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

@@ -43,19 +43,12 @@ export interface MiniProgramWindowInfoResult {
     /** 窗口上边缘的 y 值。 */
     screenTop: number;
 }
-/**
- * 视口窗口信息能力方法名。
- *
- * @remarks
- * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
- */
-export declare const VIEWPORT_GET_WINDOW_INFO_METHOD: "viewport.getWindowInfo";
+export { VIEWPORT_GET_WINDOW_INFO_METHOD } from '../../protocol/capabilities';
 /** `viewport.getWindowInfo` 不需要入参。 */
 export type GetWindowInfoPayload = void;
 /** `viewport.getWindowInfo` 返回当前小程序可用窗口信息。 */
 export type GetWindowInfoResult = MiniProgramWindowInfoResult;
-/** Viewport 模块开放的方法名。 */
-export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD;
+export type { MiniProgramViewportMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的 Viewport 模块。 */
 export interface MiniProgramViewportModule {
     /** 获取当前小程序窗口信息。 */

package/types/protocol/capabilities.d.ts

@@ -0,0 +1,180 @@
+import type { LoginPayload, LoginResult } from '../modules/auth';
+import type { NetworkRequestPayload, NetworkResponsePayload } from '../modules/network';
+import type { ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult } from '../modules/share';
+import type { GetStoragePayload, GetStorageResult, SetStoragePayload } from '../modules/storage';
+import type { GetUserInfoPayload, GetUserInfoResult } from '../modules/user';
+import type { GetWindowInfoPayload, GetWindowInfoResult } from '../modules/viewport';
+/**
+ * 登录授权能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const AUTH_LOGIN_METHOD: "auth.login";
+/**
+ * 用户信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const USER_GET_INFO_METHOD: "user.getInfo";
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
+/**
+ * 截图分享能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
+/**
+ * 视口窗口信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const VIEWPORT_GET_WINDOW_INFO_METHOD: "viewport.getWindowInfo";
+/**
+ * 读取小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const STORAGE_GET_STORAGE_METHOD: "storage.getStorage";
+/**
+ * 写入小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const STORAGE_SET_STORAGE_METHOD: "storage.setStorage";
+/**
+ * 发起网络请求能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const NETWORK_REQUEST_METHOD: "network.request";
+/** 授权模块开放的方法名。 */
+export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
+/** 用户模块开放的方法名。 */
+export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD;
+/** 分享模块开放的方法名。 */
+export type MiniProgramShareMethod = typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
+/** Viewport 模块开放的方法名。 */
+export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD;
+/** Storage 模块开放的方法名。 */
+export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
+/** 网络模块开放的方法名。 */
+export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD;
+/** 父容器开放给小程序调用的 bridge method。 */
+export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod;
+/** 小程序开放能力所属模块。 */
+export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network';
+/** 小程序开放能力风险级别，用于权限、审计和灰度策略。 */
+export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
+/**
+ * 小程序开放能力定义。
+ *
+ * @remarks
+ * 这是 SDK 与 runtime 共享的能力目录元数据。runtime 可以在此基础上绑定 handler，
+ * 但 method、module、capability、permission 与 risk 不应在 runtime 侧重复维护。
+ */
+export interface MiniProgramCapabilityDefinition {
+    /** bridge method exposed to iframe SDK. */
+    method: MiniProgramBridgeMethod;
+    /** Module that owns this capability. */
+    module: MiniProgramCapabilityModule;
+    /** Runtime instance switch key. */
+    capability: MiniProgramBridgeMethod;
+    /** Platform permission key reserved for mini-program level authorization. */
+    permission: string;
+    /** Audit / rollout hint for policy composition. */
+    risk: MiniProgramCapabilityRisk;
+}
+/**
+ * 小程序开放能力目录。
+ *
+ * @remarks
+ * 新增 bridge method 时应先更新这里，再分别补齐 SDK 模块、runtime handler 与测试。
+ */
+export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
+    readonly method: "auth.login";
+    readonly module: "auth";
+    readonly capability: "auth.login";
+    readonly permission: "auth.login";
+    readonly risk: "medium";
+}, {
+    readonly method: "user.getInfo";
+    readonly module: "user";
+    readonly capability: "user.getInfo";
+    readonly permission: "user.getInfo";
+    readonly risk: "medium";
+}, {
+    readonly method: "share.showShareMenu";
+    readonly module: "share";
+    readonly capability: "share.showShareMenu";
+    readonly permission: "share.basic";
+    readonly risk: "low";
+}, {
+    readonly method: "share.screenshot";
+    readonly module: "share";
+    readonly capability: "share.screenshot";
+    readonly permission: "share.screenshot";
+    readonly risk: "medium";
+}, {
+    readonly method: "viewport.getWindowInfo";
+    readonly module: "viewport";
+    readonly capability: "viewport.getWindowInfo";
+    readonly permission: "viewport.windowInfo";
+    readonly risk: "low";
+}, {
+    readonly method: "storage.getStorage";
+    readonly module: "storage";
+    readonly capability: "storage.getStorage";
+    readonly permission: "storage.read";
+    readonly risk: "low";
+}, {
+    readonly method: "storage.setStorage";
+    readonly module: "storage";
+    readonly capability: "storage.setStorage";
+    readonly permission: "storage.write";
+    readonly risk: "medium";
+}, {
+    readonly method: "network.request";
+    readonly module: "network";
+    readonly capability: "network.request";
+    readonly permission: "network.request";
+    readonly risk: "high";
+}];
+/** bridge method 到请求 payload 的映射。 */
+export interface MiniProgramCapabilityPayloadMap {
+    [AUTH_LOGIN_METHOD]: LoginPayload;
+    [USER_GET_INFO_METHOD]: GetUserInfoPayload;
+    [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuPayload;
+    [SHARE_SCREENSHOT_METHOD]: ScreenshotPayload;
+    [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoPayload;
+    [STORAGE_GET_STORAGE_METHOD]: GetStoragePayload;
+    [STORAGE_SET_STORAGE_METHOD]: SetStoragePayload;
+    [NETWORK_REQUEST_METHOD]: NetworkRequestPayload;
+}
+/** bridge method 到标准化响应 payload 的映射。 */
+export interface MiniProgramCapabilityResultMap {
+    [AUTH_LOGIN_METHOD]: LoginResult;
+    [USER_GET_INFO_METHOD]: GetUserInfoResult;
+    [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuResult;
+    [SHARE_SCREENSHOT_METHOD]: ScreenshotResult;
+    [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoResult;
+    [STORAGE_GET_STORAGE_METHOD]: GetStorageResult;
+    [STORAGE_SET_STORAGE_METHOD]: void;
+    [NETWORK_REQUEST_METHOD]: NetworkResponsePayload;
+}
+/** 指定 bridge method 的请求 payload。 */
+export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];
+/** 指定 bridge method 的标准化响应 payload。 */
+export type MiniProgramCapabilityResult<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityResultMap[T];