@heybox/hb-sdk-protocol 0.9.1-alpha.2 → 0.9.1-alpha.4

package/dist/index.cjs.js

@@ -68,6 +68,7 @@ const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
 const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
 const DEVICE_VIBRATE_METHOD = 'device.vibrate';
 const DEVICE_SET_CLIPBOARD_METHOD = 'device.setClipboard';
+const DEVICE_EXECUTE_PROTOCOL_METHOD = 'device.executeProtocol';
 const NAVIGATION_CLOSE_METHOD = 'navigation.close';
 const NAVIGATION_RELOAD_METHOD = 'navigation.reload';
 const NAVIGATION_OPEN_APP_PAGE_METHOD = 'navigation.openAppPage';
@@ -310,6 +311,13 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['clipboard'] },
         risk: 'medium',
     },
+    {
+        method: DEVICE_EXECUTE_PROTOCOL_METHOD,
+        module: 'device',
+        capability: DEVICE_EXECUTE_PROTOCOL_METHOD,
+        requirement: { kind: 'all', permissions: ['appProtocol'] },
+        risk: 'high',
+    },
     { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
     { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
     {
@@ -1177,6 +1185,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'leaderboard',
     'network',
     'companion',
+    'appProtocol',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -1312,6 +1321,16 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         ],
         conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
     },
+    {
+        key: 'appProtocol',
+        name: '应用协议执行',
+        description: '执行任意小黑盒客户端协议。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: ['device.executeProtocol'],
+        conditions: ['最高危险权限：批准后该入口可执行任意协议，并绕过其他 SDK 能力权限及专用授权流程。'],
+    },
 ];
 const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'user.revokeAuthorization',
@@ -1512,7 +1531,7 @@ function isRecord$2(value) {
 }
 
 /** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
-const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion'];
+const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion', 'appProtocol'];
 /**
  * 严格解析本地 grant。任何未知字段、重复权限或非法配置都拒绝整份输入。
  * 只校验数据合同；票据、身份、摘要、过期时间和 CLI lease 必须由 Host 另行验证。
@@ -1544,6 +1563,11 @@ function parseMiniProgramLocalDevGrant(value) {
                 return { valid: false };
             entries.push({ key: 'companion', status: 'enabled', config: {} });
         }
+        else if (entry.key === 'appProtocol') {
+            if (!hasExactFields(entry.config, []))
+                return { valid: false };
+            entries.push({ key: 'appProtocol', status: 'enabled', config: {} });
+        }
         else {
             return { valid: false };
         }
@@ -1559,7 +1583,7 @@ function createMiniProgramLocalDevGrant(options) {
     if (!Number.isSafeInteger(options.revision) || options.revision < 0)
         throw new Error('本地调试权限 revision 必须是非负安全整数');
     const approvals = parseMiniProgramRuntimePermissions(options.runtimePermissions);
-    const eligible = new Set(options.eligiblePermissionKeys ?? ['network']);
+    const eligible = new Set(options.eligiblePermissionKeys ?? ['network', 'appProtocol']);
     const entries = [];
     for (const key of LOCAL_DEV_GRANT_PERMISSION_KEYS) {
         if (!eligible.has(key) || options.declaredPermissions[key]?.enabled !== true)
@@ -1790,6 +1814,7 @@ exports.COMPANION_SESSION_OWNERSHIP_LOST_EVENT = COMPANION_SESSION_OWNERSHIP_LOS
 exports.COMPANION_SESSION_TERMINATE_METHOD = COMPANION_SESSION_TERMINATE_METHOD;
 exports.COMPANION_SESSION_WRITE_METHOD = COMPANION_SESSION_WRITE_METHOD;
 exports.COMPANION_SHOW_NOTIFICATION_METHOD = COMPANION_SHOW_NOTIFICATION_METHOD;
+exports.DEVICE_EXECUTE_PROTOCOL_METHOD = DEVICE_EXECUTE_PROTOCOL_METHOD;
 exports.DEVICE_SET_CLIPBOARD_METHOD = DEVICE_SET_CLIPBOARD_METHOD;
 exports.DEVICE_VIBRATE_METHOD = DEVICE_VIBRATE_METHOD;
 exports.DIRECTORY_CREATE_METHOD = DIRECTORY_CREATE_METHOD;

package/dist/index.esm.js

@@ -66,6 +66,7 @@ const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
 const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
 const DEVICE_VIBRATE_METHOD = 'device.vibrate';
 const DEVICE_SET_CLIPBOARD_METHOD = 'device.setClipboard';
+const DEVICE_EXECUTE_PROTOCOL_METHOD = 'device.executeProtocol';
 const NAVIGATION_CLOSE_METHOD = 'navigation.close';
 const NAVIGATION_RELOAD_METHOD = 'navigation.reload';
 const NAVIGATION_OPEN_APP_PAGE_METHOD = 'navigation.openAppPage';
@@ -308,6 +309,13 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['clipboard'] },
         risk: 'medium',
     },
+    {
+        method: DEVICE_EXECUTE_PROTOCOL_METHOD,
+        module: 'device',
+        capability: DEVICE_EXECUTE_PROTOCOL_METHOD,
+        requirement: { kind: 'all', permissions: ['appProtocol'] },
+        risk: 'high',
+    },
     { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
     { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
     {
@@ -1175,6 +1183,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'leaderboard',
     'network',
     'companion',
+    'appProtocol',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -1310,6 +1319,16 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         ],
         conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
     },
+    {
+        key: 'appProtocol',
+        name: '应用协议执行',
+        description: '执行任意小黑盒客户端协议。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: ['device.executeProtocol'],
+        conditions: ['最高危险权限：批准后该入口可执行任意协议，并绕过其他 SDK 能力权限及专用授权流程。'],
+    },
 ];
 const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'user.revokeAuthorization',
@@ -1510,7 +1529,7 @@ function isRecord$2(value) {
 }
 
 /** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
-const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion'];
+const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion', 'appProtocol'];
 /**
  * 严格解析本地 grant。任何未知字段、重复权限或非法配置都拒绝整份输入。
  * 只校验数据合同；票据、身份、摘要、过期时间和 CLI lease 必须由 Host 另行验证。
@@ -1542,6 +1561,11 @@ function parseMiniProgramLocalDevGrant(value) {
                 return { valid: false };
             entries.push({ key: 'companion', status: 'enabled', config: {} });
         }
+        else if (entry.key === 'appProtocol') {
+            if (!hasExactFields(entry.config, []))
+                return { valid: false };
+            entries.push({ key: 'appProtocol', status: 'enabled', config: {} });
+        }
         else {
             return { valid: false };
         }
@@ -1557,7 +1581,7 @@ function createMiniProgramLocalDevGrant(options) {
     if (!Number.isSafeInteger(options.revision) || options.revision < 0)
         throw new Error('本地调试权限 revision 必须是非负安全整数');
     const approvals = parseMiniProgramRuntimePermissions(options.runtimePermissions);
-    const eligible = new Set(options.eligiblePermissionKeys ?? ['network']);
+    const eligible = new Set(options.eligiblePermissionKeys ?? ['network', 'appProtocol']);
     const entries = [];
     for (const key of LOCAL_DEV_GRANT_PERMISSION_KEYS) {
         if (!eligible.has(key) || options.declaredPermissions[key]?.enabled !== true)
@@ -1765,4 +1789,4 @@ const COMPANION_ERROR_CODES = [
     'COMPANION_TERMINATE_FAILED',
 ];
 
-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, COMPANION_ALIAS_PATTERN, COMPANION_CANCEL_PREPARATION_METHOD, COMPANION_ERROR_CODES, COMPANION_GET_ACTIVE_SESSION_METHOD, COMPANION_GET_INFO_METHOD, COMPANION_GET_PREPARATION_STATUS_METHOD, COMPANION_LAUNCH_METHOD, COMPANION_OPEN_ATTACHMENT_METHOD, COMPANION_PREPARE_METHOD, COMPANION_SESSION_ACK_OUTPUT_METHOD, COMPANION_SESSION_CLOSE_STDIN_METHOD, COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, COMPANION_SESSION_TERMINATE_METHOD, COMPANION_SESSION_WRITE_METHOD, COMPANION_SHOW_NOTIFICATION_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, LOCAL_DEV_GRANT_PERMISSION_KEYS, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES, MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION, MINI_PROGRAM_NATIVE_HOST_DESCRIPTION, MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT, MINI_PROGRAM_NATIVE_HOST_OBJECT, MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION, MINI_PROGRAM_NATIVE_OPERATIONS, MINI_PROGRAM_NO_DECLARATION_METHODS, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PERMISSION_CATALOG, MINI_PROGRAM_PERMISSION_KEYS, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_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_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, composeLocalDevRuntimePermissions, createMiniProgramLocalDevGrant, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramNativeBinaryChunk, isMiniProgramNativeHostDescription, isMiniProgramNativeHostMessage, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramLocalDevGrant, parseMiniProgramRuntimePermissions };
+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, COMPANION_ALIAS_PATTERN, COMPANION_CANCEL_PREPARATION_METHOD, COMPANION_ERROR_CODES, COMPANION_GET_ACTIVE_SESSION_METHOD, COMPANION_GET_INFO_METHOD, COMPANION_GET_PREPARATION_STATUS_METHOD, COMPANION_LAUNCH_METHOD, COMPANION_OPEN_ATTACHMENT_METHOD, COMPANION_PREPARE_METHOD, COMPANION_SESSION_ACK_OUTPUT_METHOD, COMPANION_SESSION_CLOSE_STDIN_METHOD, COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, COMPANION_SESSION_TERMINATE_METHOD, COMPANION_SESSION_WRITE_METHOD, COMPANION_SHOW_NOTIFICATION_METHOD, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, LOCAL_DEV_GRANT_PERMISSION_KEYS, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES, MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION, MINI_PROGRAM_NATIVE_HOST_DESCRIPTION, MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT, MINI_PROGRAM_NATIVE_HOST_OBJECT, MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION, MINI_PROGRAM_NATIVE_OPERATIONS, MINI_PROGRAM_NO_DECLARATION_METHODS, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PERMISSION_CATALOG, MINI_PROGRAM_PERMISSION_KEYS, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_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_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, composeLocalDevRuntimePermissions, createMiniProgramLocalDevGrant, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramNativeBinaryChunk, isMiniProgramNativeHostDescription, isMiniProgramNativeHostMessage, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramLocalDevGrant, parseMiniProgramRuntimePermissions };

package/generated/permission-catalog.json

@@ -1,5 +1,5 @@
 {
-  "hash": "6a5978e344f22fd060ff55f77a1248a7c161cd8fbf5be2b8c73eddd308e8fe78",
+  "hash": "92694eef8e1c284ec0b03e87ca23cf00dc5824c4bc81fb72bd9a3f883ea2d26d",
   "permissions": [
     {
       "key": "userInfo",
@@ -168,6 +168,20 @@
       "conditions": [
         "声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。"
       ]
+    },
+    {
+      "key": "appProtocol",
+      "name": "应用协议执行",
+      "description": "执行任意小黑盒客户端协议。",
+      "access": "platform-approval",
+      "risk": "high",
+      "config": {},
+      "methods": [
+        "device.executeProtocol"
+      ],
+      "conditions": [
+        "最高危险权限：批准后该入口可执行任意协议，并绕过其他 SDK 能力权限及专用授权流程。"
+      ]
     }
   ],
   "noDeclarationMethods": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk-protocol",
-  "version": "0.9.1-alpha.2",
+  "version": "0.9.1-alpha.4",
   "description": "Heybox mini-program iframe bridge wire contracts.",
   "sideEffects": false,
   "exports": {

package/src/capabilities.ts

@@ -37,6 +37,8 @@ import type {
   DirectoryRemovePayload,
   DirectoryRemoveResult,
   DownloadProgressPayload,
+  ExecuteProtocolInput,
+  ExecuteProtocolResult,
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
   GetCurrentUserLeaderboardEntryPayload,
@@ -143,6 +145,7 @@ export const UI_SHOW_LOADING_METHOD = 'ui.showLoading' as const;
 export const UI_HIDE_LOADING_METHOD = 'ui.hideLoading' as const;
 export const DEVICE_VIBRATE_METHOD = 'device.vibrate' as const;
 export const DEVICE_SET_CLIPBOARD_METHOD = 'device.setClipboard' as const;
+export const DEVICE_EXECUTE_PROTOCOL_METHOD = 'device.executeProtocol' as const;
 export const NAVIGATION_CLOSE_METHOD = 'navigation.close' as const;
 export const NAVIGATION_RELOAD_METHOD = 'navigation.reload' as const;
 export const NAVIGATION_OPEN_APP_PAGE_METHOD = 'navigation.openAppPage' as const;
@@ -189,7 +192,7 @@ export type MiniProgramDirectoryMethod =
   | typeof DIRECTORY_EXISTS_METHOD
   | typeof DIRECTORY_LIST_METHOD;
 export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_LOADING_METHOD | typeof UI_HIDE_LOADING_METHOD;
-export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
+export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD | typeof DEVICE_EXECUTE_PROTOCOL_METHOD;
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
 export type MiniProgramCloudMethod =
   | typeof CLOUD_LEADERBOARD_SUBMIT_METHOD
@@ -478,6 +481,13 @@ export const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     requirement: { kind: 'all', permissions: ['clipboard'] },
     risk: 'medium',
   },
+  {
+    method: DEVICE_EXECUTE_PROTOCOL_METHOD,
+    module: 'device',
+    capability: DEVICE_EXECUTE_PROTOCOL_METHOD,
+    requirement: { kind: 'all', permissions: ['appProtocol'] },
+    risk: 'high',
+  },
   { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
   { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
   {
@@ -579,6 +589,7 @@ export interface MiniProgramCapabilityPayloadMap {
   [UI_HIDE_LOADING_METHOD]: HideLoadingPayload;
   [DEVICE_VIBRATE_METHOD]: VibratePayload;
   [DEVICE_SET_CLIPBOARD_METHOD]: SetClipboardPayload;
+  [DEVICE_EXECUTE_PROTOCOL_METHOD]: ExecuteProtocolInput;
   [NAVIGATION_CLOSE_METHOD]: ClosePayload;
   [NAVIGATION_RELOAD_METHOD]: ReloadPayload;
   [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPagePayload;
@@ -636,6 +647,7 @@ export interface MiniProgramCapabilityResultMap {
   [UI_HIDE_LOADING_METHOD]: HideLoadingResult;
   [DEVICE_VIBRATE_METHOD]: VibrateResult;
   [DEVICE_SET_CLIPBOARD_METHOD]: SetClipboardResult;
+  [DEVICE_EXECUTE_PROTOCOL_METHOD]: ExecuteProtocolResult;
   [NAVIGATION_CLOSE_METHOD]: CloseResult;
   [NAVIGATION_RELOAD_METHOD]: ReloadResult;
   [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPageResult;

package/src/local-dev-grant.ts

@@ -2,11 +2,12 @@ import { MINI_PROGRAM_PERMISSION_KEYS, type MiniProgramPermissionKey } from './p
 import { parseMiniProgramRuntimePermissions, type MiniProgramRuntimePermissionsSnapshot } from './permissions';
 
 /** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
-export const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion'] as const;
+export const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion', 'appProtocol'] as const;
 export type MiniProgramLocalDevPermissionKey = (typeof LOCAL_DEV_GRANT_PERMISSION_KEYS)[number];
 export type MiniProgramLocalDevGrantEntry =
   | { key: 'network'; status: 'enabled'; config: { useOfficialDomain: false } }
-  | { key: 'companion'; status: 'enabled'; config: Record<string, never> };
+  | { key: 'companion'; status: 'enabled'; config: Record<string, never> }
+  | { key: 'appProtocol'; status: 'enabled'; config: Record<string, never> };
 
 /** CLI-owned Dev Context 合同，不属于小程序业务 API 或线上批准快照。 */
 export interface MiniProgramLocalDevGrant {
@@ -51,6 +52,9 @@ export function parseMiniProgramLocalDevGrant(value: unknown): ParsedMiniProgram
     } else if (entry.key === 'companion') {
       if (!hasExactFields(entry.config, [])) return { valid: false };
       entries.push({ key: 'companion', status: 'enabled', config: {} });
+    } else if (entry.key === 'appProtocol') {
+      if (!hasExactFields(entry.config, [])) return { valid: false };
+      entries.push({ key: 'appProtocol', status: 'enabled', config: {} });
     } else {
       return { valid: false };
     }
@@ -71,7 +75,7 @@ export function createMiniProgramLocalDevGrant(options: {
 }): MiniProgramLocalDevGrant {
   if (!Number.isSafeInteger(options.revision) || options.revision < 0) throw new Error('本地调试权限 revision 必须是非负安全整数');
   const approvals = parseMiniProgramRuntimePermissions(options.runtimePermissions);
-  const eligible = new Set(options.eligiblePermissionKeys ?? ['network']);
+  const eligible = new Set(options.eligiblePermissionKeys ?? ['network', 'appProtocol']);
   const entries: MiniProgramLocalDevGrantEntry[] = [];
   for (const key of LOCAL_DEV_GRANT_PERMISSION_KEYS) {
     if (!eligible.has(key) || options.declaredPermissions[key]?.enabled !== true) continue;

package/src/payloads.ts

@@ -611,6 +611,33 @@ export interface SetClipboardPayload {
 }
 export type SetClipboardResult = void;
 
+/**
+ * `device.executeProtocol` 的 JSON 协议对象形态。
+ *
+ * @remarks
+ * 对象保留调用方构造的协议字段与嵌套结构，SDK 不维护协议类型白名单，也不把它重组为
+ * `navigation.openAppPage` 的目标联合。`protocol_type` 必须是非空字符串；其余字段按协议自身
+ * 语义原样交给 Host。对象只承诺 JSON 数据：不支持函数、`symbol`、`BigInt`、非有限数字或循环
+ * 引用，无法序列化时以 `INVALID_PARAMS` 拒绝且不产生投递。
+ */
+export interface ExecuteProtocolObject {
+  /** 小黑盒客户端协议类型，如 `openRouterPath`。 */
+  protocol_type: string;
+  [key: string]: unknown;
+}
+
+/**
+ * `device.executeProtocol` 的入参：完整协议字符串或 JSON 协议对象。
+ *
+ * @remarks
+ * 字符串使用已有协议工具的 scheme 与编码规则，SDK 不另建解析规则；对象通过既有 bridge
+ * 序列化传递。两种形态都不会因为缺少 SDK 侧协议白名单而被拒绝，非法输入形态在执行前
+ * 以 `INVALID_PARAMS` 拒绝。
+ */
+export type ExecuteProtocolInput = string | ExecuteProtocolObject;
+/** 成功只表示协议已投递，不表示业务动作完成。 */
+export type ExecuteProtocolResult = void;
+
 /**
  * `navigation.close` 的无参 wire payload。
  *

package/src/permission-catalog.ts

@@ -10,6 +10,7 @@ export const MINI_PROGRAM_PERMISSION_KEYS = [
   'leaderboard',
   'network',
   'companion',
+  'appProtocol',
 ] as const;
 
 export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
@@ -170,6 +171,16 @@ export const MINI_PROGRAM_PERMISSION_CATALOG = [
     ],
     conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
   },
+  {
+    key: 'appProtocol',
+    name: '应用协议执行',
+    description: '执行任意小黑盒客户端协议。',
+    access: 'platform-approval',
+    risk: 'high',
+    config: {},
+    methods: ['device.executeProtocol'],
+    conditions: ['最高危险权限：批准后该入口可执行任意协议，并绕过其他 SDK 能力权限及专用授权流程。'],
+  },
 ] as const satisfies readonly MiniProgramPermissionDefinition[];
 
 export const MINI_PROGRAM_NO_DECLARATION_METHODS = [

package/types/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { CompanionCancelPreparationPayload, CompanionCancelPreparationResult, CompanionGetActiveSessionPayload, CompanionGetActiveSessionResult, CompanionGetInfoPayload, CompanionGetInfoResult, CompanionGetPreparationStatusPayload, CompanionGetPreparationStatusResult, CompanionLaunchPayload, CompanionLaunchResult, CompanionOpenAttachmentPayload, CompanionOpenAttachmentResult, CompanionPreparePayload, CompanionPrepareProgress, CompanionPrepareResult, CompanionSessionAckOutputPayload, CompanionSessionAckOutputResult, CompanionSessionCloseStdinPayload, CompanionSessionCloseStdinResult, CompanionSessionTerminatePayload, CompanionSessionTerminateResult, CompanionSessionWritePayload, CompanionSessionWriteResult, CompanionShowNotificationPayload, CompanionShowNotificationResult, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetDisplayPayload, SetDisplayResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
+import type { CompanionCancelPreparationPayload, CompanionCancelPreparationResult, CompanionGetActiveSessionPayload, CompanionGetActiveSessionResult, CompanionGetInfoPayload, CompanionGetInfoResult, CompanionGetPreparationStatusPayload, CompanionGetPreparationStatusResult, CompanionLaunchPayload, CompanionLaunchResult, CompanionOpenAttachmentPayload, CompanionOpenAttachmentResult, CompanionPreparePayload, CompanionPrepareProgress, CompanionPrepareResult, CompanionSessionAckOutputPayload, CompanionSessionAckOutputResult, CompanionSessionCloseStdinPayload, CompanionSessionCloseStdinResult, CompanionSessionTerminatePayload, CompanionSessionTerminateResult, CompanionSessionWritePayload, CompanionSessionWriteResult, CompanionShowNotificationPayload, CompanionShowNotificationResult, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, ExecuteProtocolInput, ExecuteProtocolResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetDisplayPayload, SetDisplayResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
 import type { MiniProgramPermissionRequirement } from './permission-catalog';
 export declare const AUTH_LOGIN_METHOD: "auth.login";
 export declare const USER_GET_INFO_METHOD: "user.getInfo";
@@ -34,6 +34,7 @@ export declare const UI_SHOW_LOADING_METHOD: "ui.showLoading";
 export declare const UI_HIDE_LOADING_METHOD: "ui.hideLoading";
 export declare const DEVICE_VIBRATE_METHOD: "device.vibrate";
 export declare const DEVICE_SET_CLIPBOARD_METHOD: "device.setClipboard";
+export declare const DEVICE_EXECUTE_PROTOCOL_METHOD: "device.executeProtocol";
 export declare const NAVIGATION_CLOSE_METHOD: "navigation.close";
 export declare const NAVIGATION_RELOAD_METHOD: "navigation.reload";
 export declare const NAVIGATION_OPEN_APP_PAGE_METHOD: "navigation.openAppPage";
@@ -64,7 +65,7 @@ export type MiniProgramFilesMethod = typeof FILES_PICK_FILES_METHOD | typeof FIL
 export type MiniProgramFileMethod = typeof FILE_CREATE_METHOD | typeof FILE_REMOVE_METHOD | typeof FILE_EXISTS_METHOD | typeof FILE_READ_TEXT_METHOD | typeof FILE_WRITE_TEXT_METHOD | typeof FILE_READ_BYTES_METHOD | typeof FILE_WRITE_BYTES_METHOD | typeof FILE_STAT_METHOD;
 export type MiniProgramDirectoryMethod = typeof DIRECTORY_CREATE_METHOD | typeof DIRECTORY_REMOVE_METHOD | typeof DIRECTORY_EXISTS_METHOD | typeof DIRECTORY_LIST_METHOD;
 export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_LOADING_METHOD | typeof UI_HIDE_LOADING_METHOD;
-export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
+export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD | typeof DEVICE_EXECUTE_PROTOCOL_METHOD;
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
 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;
 export type MiniProgramCompanionMethod = typeof COMPANION_GET_INFO_METHOD | typeof COMPANION_GET_PREPARATION_STATUS_METHOD | typeof COMPANION_PREPARE_METHOD | typeof COMPANION_CANCEL_PREPARATION_METHOD | typeof COMPANION_GET_ACTIVE_SESSION_METHOD | typeof COMPANION_LAUNCH_METHOD | typeof COMPANION_SESSION_WRITE_METHOD | typeof COMPANION_SESSION_CLOSE_STDIN_METHOD | typeof COMPANION_SESSION_TERMINATE_METHOD | typeof COMPANION_SESSION_ACK_OUTPUT_METHOD | typeof COMPANION_OPEN_ATTACHMENT_METHOD | typeof COMPANION_SHOW_NOTIFICATION_METHOD;
@@ -395,6 +396,15 @@ export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
         readonly permissions: readonly ["clipboard"];
     };
     readonly risk: "medium";
+}, {
+    readonly method: "device.executeProtocol";
+    readonly module: "device";
+    readonly capability: "device.executeProtocol";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["appProtocol"];
+    };
+    readonly risk: "high";
 }, {
     readonly method: "navigation.close";
     readonly module: "navigation";
@@ -509,6 +519,7 @@ export interface MiniProgramCapabilityPayloadMap {
     [UI_HIDE_LOADING_METHOD]: HideLoadingPayload;
     [DEVICE_VIBRATE_METHOD]: VibratePayload;
     [DEVICE_SET_CLIPBOARD_METHOD]: SetClipboardPayload;
+    [DEVICE_EXECUTE_PROTOCOL_METHOD]: ExecuteProtocolInput;
     [NAVIGATION_CLOSE_METHOD]: ClosePayload;
     [NAVIGATION_RELOAD_METHOD]: ReloadPayload;
     [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPagePayload;
@@ -565,6 +576,7 @@ export interface MiniProgramCapabilityResultMap {
     [UI_HIDE_LOADING_METHOD]: HideLoadingResult;
     [DEVICE_VIBRATE_METHOD]: VibrateResult;
     [DEVICE_SET_CLIPBOARD_METHOD]: SetClipboardResult;
+    [DEVICE_EXECUTE_PROTOCOL_METHOD]: ExecuteProtocolResult;
     [NAVIGATION_CLOSE_METHOD]: CloseResult;
     [NAVIGATION_RELOAD_METHOD]: ReloadResult;
     [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPageResult;

package/types/local-dev-grant.d.ts

@@ -1,7 +1,7 @@
 import { type MiniProgramPermissionKey } from './permission-catalog';
 import { type MiniProgramRuntimePermissionsSnapshot } from './permissions';
 /** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
-export declare const LOCAL_DEV_GRANT_PERMISSION_KEYS: readonly ["network", "companion"];
+export declare const LOCAL_DEV_GRANT_PERMISSION_KEYS: readonly ["network", "companion", "appProtocol"];
 export type MiniProgramLocalDevPermissionKey = (typeof LOCAL_DEV_GRANT_PERMISSION_KEYS)[number];
 export type MiniProgramLocalDevGrantEntry = {
     key: 'network';
@@ -13,6 +13,10 @@ export type MiniProgramLocalDevGrantEntry = {
     key: 'companion';
     status: 'enabled';
     config: Record<string, never>;
+} | {
+    key: 'appProtocol';
+    status: 'enabled';
+    config: Record<string, never>;
 };
 /** CLI-owned Dev Context 合同，不属于小程序业务 API 或线上批准快照。 */
 export interface MiniProgramLocalDevGrant {

package/types/payloads.d.ts

@@ -576,6 +576,31 @@ export interface SetClipboardPayload {
     text: string;
 }
 export type SetClipboardResult = void;
+/**
+ * `device.executeProtocol` 的 JSON 协议对象形态。
+ *
+ * @remarks
+ * 对象保留调用方构造的协议字段与嵌套结构，SDK 不维护协议类型白名单，也不把它重组为
+ * `navigation.openAppPage` 的目标联合。`protocol_type` 必须是非空字符串；其余字段按协议自身
+ * 语义原样交给 Host。对象只承诺 JSON 数据：不支持函数、`symbol`、`BigInt`、非有限数字或循环
+ * 引用，无法序列化时以 `INVALID_PARAMS` 拒绝且不产生投递。
+ */
+export interface ExecuteProtocolObject {
+    /** 小黑盒客户端协议类型，如 `openRouterPath`。 */
+    protocol_type: string;
+    [key: string]: unknown;
+}
+/**
+ * `device.executeProtocol` 的入参：完整协议字符串或 JSON 协议对象。
+ *
+ * @remarks
+ * 字符串使用已有协议工具的 scheme 与编码规则，SDK 不另建解析规则；对象通过既有 bridge
+ * 序列化传递。两种形态都不会因为缺少 SDK 侧协议白名单而被拒绝，非法输入形态在执行前
+ * 以 `INVALID_PARAMS` 拒绝。
+ */
+export type ExecuteProtocolInput = string | ExecuteProtocolObject;
+/** 成功只表示协议已投递，不表示业务动作完成。 */
+export type ExecuteProtocolResult = void;
 /**
  * `navigation.close` 的无参 wire payload。
  *

package/types/permission-catalog.d.ts

@@ -1,5 +1,5 @@
 import type { MiniProgramBridgeMethod, MiniProgramCapabilityRisk } from './capabilities';
-export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion"];
+export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion", "appProtocol"];
 export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
 export type MiniProgramPermissionRequirement = {
     readonly kind: 'none';
@@ -112,6 +112,15 @@ export declare const MINI_PROGRAM_PERMISSION_CATALOG: readonly [{
     readonly config: {};
     readonly methods: readonly ["companion.getInfo", "companion.getPreparationStatus", "companion.prepare", "companion.cancelPreparation", "companion.getActiveSession", "companion.launch", "companion.session.write", "companion.session.closeStdin", "companion.session.terminate", "companion.session.ackOutput", "companion.openAttachment", "companion.showNotification"];
     readonly conditions: readonly ["声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。"];
+}, {
+    readonly key: "appProtocol";
+    readonly name: "应用协议执行";
+    readonly description: "执行任意小黑盒客户端协议。";
+    readonly access: "platform-approval";
+    readonly risk: "high";
+    readonly config: {};
+    readonly methods: readonly ["device.executeProtocol"];
+    readonly conditions: readonly ["最高危险权限：批准后该入口可执行任意协议，并绕过其他 SDK 能力权限及专用授权流程。"];
 }];
 export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "viewport.setDisplay", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
 export declare function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey;