@heybox/hb-sdk-protocol 0.8.1-alpha.2 → 0.8.1-alpha.6

package/README.md

@@ -1,5 +1,7 @@
 # @heybox/hb-sdk-protocol
 
+目录引用的 `relativePath` 允许完整 `.` 表示当前根；普通相对路径及文件引用仍拒绝点段、父目录和绝对路径。
+
 小黑盒外部小程序 SDK 与宿主 Runtime 共用的零依赖 wire contract。它只描述跨 iframe 边界传输的数据和校验规则，不执行 bridge、网络、登录、存储或任何平台能力。
 
 ## 边界
@@ -39,7 +41,11 @@ import { MINI_PROGRAM_PROTOCOL_CAPABILITIES, type MiniProgramBridgeMessage } fro
 
 ## 权限快照
 
-`MINI_PROGRAM_PERMISSION_CATALOG` 定义 8 个公开权限，`MINI_PROGRAM_PROTOCOL_CAPABILITIES[].requirement` 将每个 bridge method 显式分类为无需声明或要求全部列出的权限。`parseMiniProgramRuntimePermissions()` 是 schema v1 的 fail-closed 解析器；旧 `network.request` entry 仅在解析边界归一为 `network`，不得进入新配置。跨语言目录由 `generated/permission-catalog.json` 提供。
+`MINI_PROGRAM_PERMISSION_CATALOG` 定义 9 个公开权限，`MINI_PROGRAM_PROTOCOL_CAPABILITIES[].requirement` 将每个 bridge method 显式分类为无需声明或要求全部列出的权限。`companion` 是无配置项的高风险平台审批权限，覆盖准备、启动、活动 Session 控制、stdio、附件与通知 wire method。`parseMiniProgramRuntimePermissions()` 是 schema v1 的 fail-closed 解析器；旧 `network.request` entry 仅在解析边界归一为 `network`，不得进入新配置。未知权限 entry 会被忽略，即使 `config` 为 `null` 或缺失，也不能让已认识的批准失效。跨语言目录由 `generated/permission-catalog.json` 提供。
+
+耗时能力通过 `MiniProgramCapabilityProgressMap` 按 method 绑定进度 payload；当前覆盖 `network.download` 与 `companion.prepare`。Companion Session wire 只携带不透明 Session ID、controller generation、原始字节 chunk/ack、exit 和 ownership-lost 事件，不暴露 PID、路径或原生句柄。
+
+`CompanionInfo.source` 由可信 Host 标识 `local-dev` 或 `released`，与 `signatureStatus` 一起供授权展示使用；旧 Host 未提供来源时保持未知，不能推定为已审核产物。
 
 协议包不决定业务授权。`auth.login()` 的 UI、账号会话、授权码签发和 OpenAPI 都由 Host/服务端负责；协议层只传递经过约束的 request/response 数据。
 

package/dist/index.cjs.js

@@ -1,5 +1,17 @@
 'use strict';
 
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
+const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
+const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
+const COMPANION_SESSION_OUTPUT_EVENT = 'companion.session.output';
+const COMPANION_SESSION_EXIT_EVENT = 'companion.session.exit';
+const COMPANION_SESSION_OWNERSHIP_LOST_EVENT = 'companion.session.ownershipLost';
+
 const AUTH_LOGIN_METHOD = 'auth.login';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
@@ -41,6 +53,18 @@ const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList';
 const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry';
 const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry';
 const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo';
+const COMPANION_GET_INFO_METHOD = 'companion.getInfo';
+const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus';
+const COMPANION_PREPARE_METHOD = 'companion.prepare';
+const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation';
+const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession';
+const COMPANION_LAUNCH_METHOD = 'companion.launch';
+const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write';
+const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin';
+const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate';
+const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
+const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
+const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     {
         method: AUTH_LOGIN_METHOD,
@@ -287,17 +311,28 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['leaderboard'] },
         risk: 'low',
     },
+    ...[
+        COMPANION_GET_INFO_METHOD,
+        COMPANION_GET_PREPARATION_STATUS_METHOD,
+        COMPANION_PREPARE_METHOD,
+        COMPANION_CANCEL_PREPARATION_METHOD,
+        COMPANION_GET_ACTIVE_SESSION_METHOD,
+        COMPANION_LAUNCH_METHOD,
+        COMPANION_SESSION_WRITE_METHOD,
+        COMPANION_SESSION_CLOSE_STDIN_METHOD,
+        COMPANION_SESSION_TERMINATE_METHOD,
+        COMPANION_SESSION_ACK_OUTPUT_METHOD,
+        COMPANION_OPEN_ATTACHMENT_METHOD,
+        COMPANION_SHOW_NOTIFICATION_METHOD,
+    ].map((method) => ({
+        method,
+        module: 'companion',
+        capability: method,
+        requirement: { kind: 'all', permissions: ['companion'] },
+        risk: 'high',
+    })),
 ];
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
-const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
-const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
-const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
-const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
-
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$1(value))
         return false;
@@ -319,7 +354,7 @@ function isMiniProgramBridgeMessage(value) {
         if (!isNonEmptyString(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
         return value.id === undefined || isNonEmptyString(value.id);
     }
@@ -357,7 +392,7 @@ function isMiniProgramDirectoryRef(value) {
     if (isNonEmptyString(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
-    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+    return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$1(value) &&
@@ -400,6 +435,24 @@ function isMiniProgramDownloadProgressPayload(value) {
         return value.total === undefined;
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
+function isMiniProgramCompanionPrepareProgress(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.phase === 'downloading') {
+        return (isNonNegativeSafeInteger(value.loaded) &&
+            (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+            hasOnlyKeys(value, ['phase', 'loaded', 'total']));
+    }
+    if (value.phase !== 'verifying' && value.phase !== 'extracting')
+        return false;
+    return (isNonNegativeSafeInteger(value.processed) &&
+        isNonNegativeSafeInteger(value.total) &&
+        value.processed <= value.total &&
+        hasOnlyKeys(value, ['phase', 'processed', 'total']));
+}
+function isMiniProgramOperationProgressPayload(value) {
+    return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
 function isSDKHandshakePayload(value) {
     return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }
@@ -428,6 +481,34 @@ function isRecord$1(value) {
 
 /** 当前用户信息与登录能力支持的完整 scope 目录。 */
 const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+const COMPANION_ERROR_CODES = [
+    'COMPANION_UNSUPPORTED',
+    'COMPANION_NOT_DECLARED',
+    'COMPANION_TARGET_UNSUPPORTED',
+    'COMPANION_NOT_PREPARED',
+    'COMPANION_PREPARATION_CANCELLED',
+    'COMPANION_DOWNLOAD_FAILED',
+    'COMPANION_DESCRIPTOR_UNAVAILABLE',
+    'COMPANION_ARCHIVE_INVALID',
+    'COMPANION_INTEGRITY_FAILED',
+    'COMPANION_ENTRYPOINT_INVALID',
+    'COMPANION_USER_CANCELLED',
+    'COMPANION_ELEVATION_DENIED',
+    'COMPANION_OS_BLOCKED',
+    'COMPANION_LAUNCH_FAILED',
+    'COMPANION_SESSION_VERSION_MISMATCH',
+    'COMPANION_SESSION_OWNERSHIP_LOST',
+    'COMPANION_SESSION_EXITED',
+    'COMPANION_PIPE_CLOSED',
+    'COMPANION_OUTPUT_LIMIT',
+    'COMPANION_PROCESS_CRASHED',
+    'COMPANION_ATTACHMENT_NOT_FOUND',
+    'COMPANION_NOTIFICATION_UNAVAILABLE',
+    'COMPANION_TERMINATE_FAILED',
+];
 
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
@@ -438,6 +519,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -550,6 +632,29 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         methods: ['network.request', 'network.download'],
         conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
     },
+    {
+        key: 'companion',
+        name: '桌面辅助应用',
+        description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: [
+            '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',
+        ],
+        conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+    },
 ];
 const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'user.revokeAuthorization',
@@ -592,8 +697,8 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         seenKeys.add(key);
         if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-            if (!isRecord(rawEntry.config))
-                return { valid: false, permissions: {} };
+            // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+            // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
             continue;
         }
         if (key === 'network') {
@@ -629,6 +734,23 @@ exports.CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = CLOUD_LEADERBOARD_GET_
 exports.CLOUD_LEADERBOARD_GET_INFO_METHOD = CLOUD_LEADERBOARD_GET_INFO_METHOD;
 exports.CLOUD_LEADERBOARD_GET_LIST_METHOD = CLOUD_LEADERBOARD_GET_LIST_METHOD;
 exports.CLOUD_LEADERBOARD_SUBMIT_METHOD = CLOUD_LEADERBOARD_SUBMIT_METHOD;
+exports.COMPANION_ALIAS_PATTERN = COMPANION_ALIAS_PATTERN;
+exports.COMPANION_CANCEL_PREPARATION_METHOD = COMPANION_CANCEL_PREPARATION_METHOD;
+exports.COMPANION_ERROR_CODES = COMPANION_ERROR_CODES;
+exports.COMPANION_GET_ACTIVE_SESSION_METHOD = COMPANION_GET_ACTIVE_SESSION_METHOD;
+exports.COMPANION_GET_INFO_METHOD = COMPANION_GET_INFO_METHOD;
+exports.COMPANION_GET_PREPARATION_STATUS_METHOD = COMPANION_GET_PREPARATION_STATUS_METHOD;
+exports.COMPANION_LAUNCH_METHOD = COMPANION_LAUNCH_METHOD;
+exports.COMPANION_OPEN_ATTACHMENT_METHOD = COMPANION_OPEN_ATTACHMENT_METHOD;
+exports.COMPANION_PREPARE_METHOD = COMPANION_PREPARE_METHOD;
+exports.COMPANION_SESSION_ACK_OUTPUT_METHOD = COMPANION_SESSION_ACK_OUTPUT_METHOD;
+exports.COMPANION_SESSION_CLOSE_STDIN_METHOD = COMPANION_SESSION_CLOSE_STDIN_METHOD;
+exports.COMPANION_SESSION_EXIT_EVENT = COMPANION_SESSION_EXIT_EVENT;
+exports.COMPANION_SESSION_OUTPUT_EVENT = COMPANION_SESSION_OUTPUT_EVENT;
+exports.COMPANION_SESSION_OWNERSHIP_LOST_EVENT = COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
+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_SET_CLIPBOARD_METHOD = DEVICE_SET_CLIPBOARD_METHOD;
 exports.DEVICE_VIBRATE_METHOD = DEVICE_VIBRATE_METHOD;
 exports.DIRECTORY_CREATE_METHOD = DIRECTORY_CREATE_METHOD;
@@ -680,6 +802,7 @@ exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_S
 exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
 exports.isMiniProgramByteArray = isMiniProgramByteArray;
+exports.isMiniProgramCompanionPrepareProgress = isMiniProgramCompanionPrepareProgress;
 exports.isMiniProgramDirectoryDescriptor = isMiniProgramDirectoryDescriptor;
 exports.isMiniProgramDirectoryRef = isMiniProgramDirectoryRef;
 exports.isMiniProgramDownloadProgressPayload = isMiniProgramDownloadProgressPayload;
@@ -687,6 +810,7 @@ exports.isMiniProgramFileDescriptor = isMiniProgramFileDescriptor;
 exports.isMiniProgramFileRef = isMiniProgramFileRef;
 exports.isMiniProgramFileStat = isMiniProgramFileStat;
 exports.isMiniProgramFileSystemEntityDescriptor = isMiniProgramFileSystemEntityDescriptor;
+exports.isMiniProgramOperationProgressPayload = isMiniProgramOperationProgressPayload;
 exports.isMiniProgramPathRootRef = isMiniProgramPathRootRef;
 exports.isMiniProgramPermissionKey = isMiniProgramPermissionKey;
 exports.isMiniProgramRelativePath = isMiniProgramRelativePath;

package/dist/index.esm.js

@@ -1,3 +1,15 @@
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
+const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
+const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
+const COMPANION_SESSION_OUTPUT_EVENT = 'companion.session.output';
+const COMPANION_SESSION_EXIT_EVENT = 'companion.session.exit';
+const COMPANION_SESSION_OWNERSHIP_LOST_EVENT = 'companion.session.ownershipLost';
+
 const AUTH_LOGIN_METHOD = 'auth.login';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
@@ -39,6 +51,18 @@ const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList';
 const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry';
 const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry';
 const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo';
+const COMPANION_GET_INFO_METHOD = 'companion.getInfo';
+const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus';
+const COMPANION_PREPARE_METHOD = 'companion.prepare';
+const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation';
+const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession';
+const COMPANION_LAUNCH_METHOD = 'companion.launch';
+const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write';
+const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin';
+const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate';
+const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
+const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
+const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     {
         method: AUTH_LOGIN_METHOD,
@@ -285,17 +309,28 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['leaderboard'] },
         risk: 'low',
     },
+    ...[
+        COMPANION_GET_INFO_METHOD,
+        COMPANION_GET_PREPARATION_STATUS_METHOD,
+        COMPANION_PREPARE_METHOD,
+        COMPANION_CANCEL_PREPARATION_METHOD,
+        COMPANION_GET_ACTIVE_SESSION_METHOD,
+        COMPANION_LAUNCH_METHOD,
+        COMPANION_SESSION_WRITE_METHOD,
+        COMPANION_SESSION_CLOSE_STDIN_METHOD,
+        COMPANION_SESSION_TERMINATE_METHOD,
+        COMPANION_SESSION_ACK_OUTPUT_METHOD,
+        COMPANION_OPEN_ATTACHMENT_METHOD,
+        COMPANION_SHOW_NOTIFICATION_METHOD,
+    ].map((method) => ({
+        method,
+        module: 'companion',
+        capability: method,
+        requirement: { kind: 'all', permissions: ['companion'] },
+        risk: 'high',
+    })),
 ];
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
-const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
-const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
-const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
-const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
-
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$1(value))
         return false;
@@ -317,7 +352,7 @@ function isMiniProgramBridgeMessage(value) {
         if (!isNonEmptyString(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
         return value.id === undefined || isNonEmptyString(value.id);
     }
@@ -355,7 +390,7 @@ function isMiniProgramDirectoryRef(value) {
     if (isNonEmptyString(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
-    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+    return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$1(value) &&
@@ -398,6 +433,24 @@ function isMiniProgramDownloadProgressPayload(value) {
         return value.total === undefined;
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
+function isMiniProgramCompanionPrepareProgress(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.phase === 'downloading') {
+        return (isNonNegativeSafeInteger(value.loaded) &&
+            (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+            hasOnlyKeys(value, ['phase', 'loaded', 'total']));
+    }
+    if (value.phase !== 'verifying' && value.phase !== 'extracting')
+        return false;
+    return (isNonNegativeSafeInteger(value.processed) &&
+        isNonNegativeSafeInteger(value.total) &&
+        value.processed <= value.total &&
+        hasOnlyKeys(value, ['phase', 'processed', 'total']));
+}
+function isMiniProgramOperationProgressPayload(value) {
+    return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
 function isSDKHandshakePayload(value) {
     return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }
@@ -426,6 +479,34 @@ function isRecord$1(value) {
 
 /** 当前用户信息与登录能力支持的完整 scope 目录。 */
 const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+const COMPANION_ERROR_CODES = [
+    'COMPANION_UNSUPPORTED',
+    'COMPANION_NOT_DECLARED',
+    'COMPANION_TARGET_UNSUPPORTED',
+    'COMPANION_NOT_PREPARED',
+    'COMPANION_PREPARATION_CANCELLED',
+    'COMPANION_DOWNLOAD_FAILED',
+    'COMPANION_DESCRIPTOR_UNAVAILABLE',
+    'COMPANION_ARCHIVE_INVALID',
+    'COMPANION_INTEGRITY_FAILED',
+    'COMPANION_ENTRYPOINT_INVALID',
+    'COMPANION_USER_CANCELLED',
+    'COMPANION_ELEVATION_DENIED',
+    'COMPANION_OS_BLOCKED',
+    'COMPANION_LAUNCH_FAILED',
+    'COMPANION_SESSION_VERSION_MISMATCH',
+    'COMPANION_SESSION_OWNERSHIP_LOST',
+    'COMPANION_SESSION_EXITED',
+    'COMPANION_PIPE_CLOSED',
+    'COMPANION_OUTPUT_LIMIT',
+    'COMPANION_PROCESS_CRASHED',
+    'COMPANION_ATTACHMENT_NOT_FOUND',
+    'COMPANION_NOTIFICATION_UNAVAILABLE',
+    'COMPANION_TERMINATE_FAILED',
+];
 
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
@@ -436,6 +517,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -548,6 +630,29 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         methods: ['network.request', 'network.download'],
         conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
     },
+    {
+        key: 'companion',
+        name: '桌面辅助应用',
+        description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: [
+            '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',
+        ],
+        conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+    },
 ];
 const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'user.revokeAuthorization',
@@ -590,8 +695,8 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         seenKeys.add(key);
         if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-            if (!isRecord(rawEntry.config))
-                return { valid: false, permissions: {} };
+            // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+            // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
             continue;
         }
         if (key === 'network') {
@@ -621,4 +726,4 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-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, 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, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, 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_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, 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_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, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, 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_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };

package/package.json

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

package/src/bridge.ts

@@ -1,5 +1,19 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { DownloadProgressPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
+import {
+  COMPANION_SESSION_EXIT_EVENT,
+  COMPANION_SESSION_OUTPUT_EVENT,
+  COMPANION_SESSION_OWNERSHIP_LOST_EVENT,
+  MINI_PROGRAM_MESSAGE_NAMESPACE,
+  MINI_PROGRAM_OPERATION_PROGRESS_METHOD,
+} from './constants';
+import type {
+  CompanionSessionExitPayload,
+  CompanionSessionOutputPayload,
+  CompanionSessionOwnershipLostPayload,
+  DownloadProgressPayload,
+  MiniProgramRuntimeEnvironmentInfo,
+  UserInfoAuthorization,
+} from './payloads';
+import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName =
@@ -10,7 +24,10 @@ export type MiniProgramEventName =
   | 'unload'
   | 'error'
   | 'heybox_app_login_change'
-  | 'user_info_authorization_change';
+  | 'user_info_authorization_change'
+  | typeof COMPANION_SESSION_OUTPUT_EVENT
+  | typeof COMPANION_SESSION_EXIT_EVENT
+  | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
 
 export interface MiniProgramBridgeError {
   code: string;
@@ -71,12 +88,14 @@ export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage
   error?: never;
 }
 
-export interface MiniProgramBridgeProgressMessage extends MiniProgramBridgeMessage<DownloadProgressPayload> {
+export interface MiniProgramBridgeProgressMessage<
+  TMethod extends MiniProgramProgressMethod = MiniProgramProgressMethod,
+> extends MiniProgramBridgeMessage<MiniProgramCapabilityProgress<TMethod>> {
   version: 2;
   type: 'event';
   id: string;
   method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
-  payload: DownloadProgressPayload;
+  payload: MiniProgramCapabilityProgress<TMethod>;
   error?: never;
 }
 export interface MiniProgramEventPayloadMap {
@@ -88,4 +107,7 @@ export interface MiniProgramEventPayloadMap {
   error: MiniProgramBridgeError;
   heybox_app_login_change: { isHeyboxAppLoggedIn: boolean };
   user_info_authorization_change: UserInfoAuthorization;
+  [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
+  [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
+  [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
 }

package/src/capabilities.ts

@@ -1,4 +1,29 @@
 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,
@@ -11,6 +36,7 @@ import type {
   DirectoryListResult,
   DirectoryRemovePayload,
   DirectoryRemoveResult,
+  DownloadProgressPayload,
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
   GetCurrentUserLeaderboardEntryPayload,
@@ -122,6 +148,18 @@ export const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList' as
 export const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry' as const;
 export const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry' as const;
 export const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo' as const;
+export const COMPANION_GET_INFO_METHOD = 'companion.getInfo' as const;
+export const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus' as const;
+export const COMPANION_PREPARE_METHOD = 'companion.prepare' as const;
+export const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation' as const;
+export const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession' as const;
+export const COMPANION_LAUNCH_METHOD = 'companion.launch' as const;
+export const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write' as const;
+export const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin' as const;
+export const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate' as const;
+export const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput' as const;
+export const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment' as const;
+export const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification' as const;
 
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
@@ -153,6 +191,19 @@ export type MiniProgramCloudMethod =
   | 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;
 export type MiniProgramBridgeMethod =
   | MiniProgramAuthMethod
   | MiniProgramUserMethod
@@ -166,7 +217,8 @@ export type MiniProgramBridgeMethod =
   | MiniProgramUiMethod
   | MiniProgramDeviceMethod
   | MiniProgramNavigationMethod
-  | MiniProgramCloudMethod;
+  | MiniProgramCloudMethod
+  | MiniProgramCompanionMethod;
 export type MiniProgramCapabilityModule =
   | 'auth'
   | 'user'
@@ -180,7 +232,8 @@ export type MiniProgramCapabilityModule =
   | 'ui'
   | 'device'
   | 'navigation'
-  | 'cloud';
+  | 'cloud'
+  | 'companion';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 
 export interface MiniProgramCapabilityDefinition {
@@ -437,6 +490,26 @@ export const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'low',
   },
+  ...[
+    COMPANION_GET_INFO_METHOD,
+    COMPANION_GET_PREPARATION_STATUS_METHOD,
+    COMPANION_PREPARE_METHOD,
+    COMPANION_CANCEL_PREPARATION_METHOD,
+    COMPANION_GET_ACTIVE_SESSION_METHOD,
+    COMPANION_LAUNCH_METHOD,
+    COMPANION_SESSION_WRITE_METHOD,
+    COMPANION_SESSION_CLOSE_STDIN_METHOD,
+    COMPANION_SESSION_TERMINATE_METHOD,
+    COMPANION_SESSION_ACK_OUTPUT_METHOD,
+    COMPANION_OPEN_ATTACHMENT_METHOD,
+    COMPANION_SHOW_NOTIFICATION_METHOD,
+  ].map((method) => ({
+    method,
+    module: 'companion' as const,
+    capability: method,
+    requirement: { kind: 'all' as const, permissions: ['companion' as const] },
+    risk: 'high' as const,
+  })),
 ] as const satisfies readonly MiniProgramCapabilityDefinition[];
 
 export interface MiniProgramCapabilityPayloadMap {
@@ -481,6 +554,18 @@ export interface MiniProgramCapabilityPayloadMap {
   [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;
+  [COMPANION_GET_INFO_METHOD]: CompanionGetInfoPayload;
+  [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusPayload;
+  [COMPANION_PREPARE_METHOD]: CompanionPreparePayload;
+  [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationPayload;
+  [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionPayload;
+  [COMPANION_LAUNCH_METHOD]: CompanionLaunchPayload;
+  [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWritePayload;
+  [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinPayload;
+  [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminatePayload;
+  [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputPayload;
+  [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentPayload;
+  [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationPayload;
 }
 
 export interface MiniProgramCapabilityResultMap {
@@ -525,7 +610,27 @@ export interface MiniProgramCapabilityResultMap {
   [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryResult;
   [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryResult;
   [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoResult;
+  [COMPANION_GET_INFO_METHOD]: CompanionGetInfoResult;
+  [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusResult;
+  [COMPANION_PREPARE_METHOD]: CompanionPrepareResult;
+  [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationResult;
+  [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionResult;
+  [COMPANION_LAUNCH_METHOD]: CompanionLaunchResult;
+  [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWriteResult;
+  [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinResult;
+  [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminateResult;
+  [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputResult;
+  [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentResult;
+  [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationResult;
 }
 
+export interface MiniProgramCapabilityProgressMap {
+  [NETWORK_DOWNLOAD_METHOD]: DownloadProgressPayload;
+  [COMPANION_PREPARE_METHOD]: CompanionPrepareProgress;
+}
+
+export type MiniProgramProgressMethod = keyof MiniProgramCapabilityProgressMap;
+export type MiniProgramCapabilityProgress<T extends MiniProgramProgressMethod> = MiniProgramCapabilityProgressMap[T];
+
 export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];
 export type MiniProgramCapabilityResult<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityResultMap[T];

package/src/constants.ts

@@ -6,3 +6,6 @@ export const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe' as const;
 export const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report' as const;
 export const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation' as const;
 export const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress' as const;
+export const COMPANION_SESSION_OUTPUT_EVENT = 'companion.session.output' as const;
+export const COMPANION_SESSION_EXIT_EVENT = 'companion.session.exit' as const;
+export const COMPANION_SESSION_OWNERSHIP_LOST_EVENT = 'companion.session.ownershipLost' as const;

package/src/guards.ts

@@ -1,6 +1,7 @@
 import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, SDK_HANDSHAKE_METHOD } from './constants';
 import type { MiniProgramBridgeMessage } from './bridge';
 import type {
+  CompanionPrepareProgress,
   DownloadProgressPayload,
   MiniProgramDirectoryDescriptor,
   MiniProgramDirectoryRef,
@@ -33,7 +34,7 @@ export function isMiniProgramBridgeMessage(value: unknown): value is MiniProgram
   if (value.type === 'event') {
     if (!isNonEmptyString(value.method) || value.error !== undefined) return false;
     if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-      return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+      return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
     }
     return value.id === undefined || isNonEmptyString(value.id);
   }
@@ -75,7 +76,7 @@ export function isMiniProgramDirectoryRef(value: unknown): value is MiniProgramD
     return hasOnlyKeys(value, ['kind', 'handleId']);
   }
   return (
-    isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
+    isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
   );
 }
 
@@ -133,6 +134,28 @@ export function isMiniProgramDownloadProgressPayload(value: unknown): value is D
   return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 
+export function isMiniProgramCompanionPrepareProgress(value: unknown): value is CompanionPrepareProgress {
+  if (!isRecord(value)) return false;
+  if (value.phase === 'downloading') {
+    return (
+      isNonNegativeSafeInteger(value.loaded) &&
+      (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+      hasOnlyKeys(value, ['phase', 'loaded', 'total'])
+    );
+  }
+  if (value.phase !== 'verifying' && value.phase !== 'extracting') return false;
+  return (
+    isNonNegativeSafeInteger(value.processed) &&
+    isNonNegativeSafeInteger(value.total) &&
+    value.processed <= value.total &&
+    hasOnlyKeys(value, ['phase', 'processed', 'total'])
+  );
+}
+
+export function isMiniProgramOperationProgressPayload(value: unknown): value is DownloadProgressPayload | CompanionPrepareProgress {
+  return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
+
 function isSDKHandshakePayload(value: unknown) {
   return isRecord(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }

package/src/payloads.ts

@@ -484,3 +484,137 @@ export interface GetLeaderboardInfoResult {
   order: LeaderboardOrder;
   rankLimit: number;
 }
+
+/** 受管桌面程序可选能力。 */
+export type CompanionCapability = 'stdio' | 'attachments' | 'notifications';
+export type CompanionTarget = 'windows-x64' | 'macos-arm64';
+export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unknown';
+
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+export const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+export const COMPANION_ERROR_CODES = [
+  'COMPANION_UNSUPPORTED',
+  'COMPANION_NOT_DECLARED',
+  'COMPANION_TARGET_UNSUPPORTED',
+  'COMPANION_NOT_PREPARED',
+  'COMPANION_PREPARATION_CANCELLED',
+  'COMPANION_DOWNLOAD_FAILED',
+  'COMPANION_DESCRIPTOR_UNAVAILABLE',
+  'COMPANION_ARCHIVE_INVALID',
+  'COMPANION_INTEGRITY_FAILED',
+  'COMPANION_ENTRYPOINT_INVALID',
+  'COMPANION_USER_CANCELLED',
+  'COMPANION_ELEVATION_DENIED',
+  'COMPANION_OS_BLOCKED',
+  'COMPANION_LAUNCH_FAILED',
+  'COMPANION_SESSION_VERSION_MISMATCH',
+  'COMPANION_SESSION_OWNERSHIP_LOST',
+  'COMPANION_SESSION_EXITED',
+  'COMPANION_PIPE_CLOSED',
+  'COMPANION_OUTPUT_LIMIT',
+  'COMPANION_PROCESS_CRASHED',
+  'COMPANION_ATTACHMENT_NOT_FOUND',
+  'COMPANION_NOTIFICATION_UNAVAILABLE',
+  'COMPANION_TERMINATE_FAILED',
+] as const;
+export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
+
+export interface CompanionInfo {
+  alias: string;
+  displayName: string;
+  target: CompanionTarget;
+  capabilities: readonly CompanionCapability[];
+  archiveBytes: number;
+  signatureStatus: CompanionSignatureStatus;
+  /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
+  source?: 'local-dev' | 'released';
+}
+
+export interface CompanionErrorSummary {
+  code: CompanionErrorCode;
+  message: string;
+  retryable: boolean;
+}
+
+export type CompanionPrepareProgress =
+  | { phase: 'downloading'; loaded: number; total?: number }
+  | { phase: 'verifying'; processed: number; total: number }
+  | { phase: 'extracting'; processed: number; total: number };
+
+export type CompanionPreparationStatus =
+  | { state: 'not-prepared' }
+  | { state: 'preparing'; progress: CompanionPrepareProgress }
+  | { state: 'ready'; preparedAt: number }
+  | { state: 'failed'; error: CompanionErrorSummary };
+
+export type CompanionExitReason = 'exited' | 'terminated' | 'crashed' | 'host-shutdown' | 'permission-revoked' | 'output-limit';
+export type CompanionExit = { reason: 'exited'; exitCode: number } | { reason: Exclude<CompanionExitReason, 'exited'>; exitCode?: number };
+
+/** 活动 Session 的 wire 快照；不包含路径、PID 或原生句柄。 */
+export interface CompanionSessionSnapshot {
+  id: string;
+  alias: string;
+  target: CompanionTarget;
+  capabilities: readonly CompanionCapability[];
+  state: 'running';
+  controllerGeneration: number;
+}
+
+export interface CompanionAliasPayload {
+  alias: string;
+}
+export type CompanionGetInfoPayload = CompanionAliasPayload;
+export type CompanionGetInfoResult = CompanionInfo;
+export type CompanionGetPreparationStatusPayload = CompanionAliasPayload;
+export type CompanionGetPreparationStatusResult = CompanionPreparationStatus;
+export type CompanionPreparePayload = CompanionAliasPayload;
+export type CompanionPrepareResult = CompanionInfo;
+export type CompanionCancelPreparationPayload = CompanionAliasPayload;
+export type CompanionCancelPreparationResult = void;
+export type CompanionGetActiveSessionPayload = CompanionAliasPayload;
+export type CompanionGetActiveSessionResult = CompanionSessionSnapshot | undefined;
+export type CompanionLaunchPayload = CompanionAliasPayload;
+export type CompanionLaunchResult = CompanionSessionSnapshot;
+
+export interface CompanionSessionControllerPayload {
+  sessionId: string;
+  controllerGeneration: number;
+}
+export interface CompanionSessionWritePayload extends CompanionSessionControllerPayload {
+  data: Uint8Array;
+}
+export type CompanionSessionWriteResult = void;
+export type CompanionSessionCloseStdinPayload = CompanionSessionControllerPayload;
+export type CompanionSessionCloseStdinResult = void;
+export type CompanionSessionTerminatePayload = CompanionSessionControllerPayload;
+export type CompanionSessionTerminateResult = void;
+export interface CompanionSessionAckOutputPayload extends CompanionSessionControllerPayload {
+  stream: 'stdout' | 'stderr';
+  sequence: number;
+}
+export type CompanionSessionAckOutputResult = void;
+export interface CompanionOpenAttachmentPayload extends CompanionSessionControllerPayload {
+  id: string;
+}
+export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
+export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
+export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
+  category: CompanionNotificationCategory;
+}
+export type CompanionShowNotificationResult = void;
+
+export interface CompanionSessionOutputPayload extends CompanionSessionControllerPayload {
+  stream: 'stdout' | 'stderr';
+  sequence: number;
+  data: Uint8Array;
+}
+export interface CompanionSessionExitPayload {
+  sessionId: string;
+  exit: CompanionExit;
+}
+export interface CompanionSessionOwnershipLostPayload {
+  sessionId: string;
+  controllerGeneration: number;
+}

package/src/permission-catalog.ts

@@ -9,6 +9,7 @@ export const MINI_PROGRAM_PERMISSION_KEYS = [
   'clipboard',
   'leaderboard',
   'network',
+  'companion',
 ] as const;
 
 export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
@@ -146,6 +147,29 @@ export const MINI_PROGRAM_PERMISSION_CATALOG = [
     methods: ['network.request', 'network.download'],
     conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
   },
+  {
+    key: 'companion',
+    name: '桌面辅助应用',
+    description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+    access: 'platform-approval',
+    risk: 'high',
+    config: {},
+    methods: [
+      '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',
+    ],
+    conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+  },
 ] as const satisfies readonly MiniProgramPermissionDefinition[];
 
 export const MINI_PROGRAM_NO_DECLARATION_METHODS = [

package/src/permissions.ts

@@ -42,7 +42,8 @@ export function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMin
     }
     seenKeys.add(key);
     if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-      if (!isRecord(rawEntry.config)) return { valid: false, permissions: {} };
+      // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+      // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
       continue;
     }
     if (key === 'network') {

package/types/bridge.d.ts

@@ -1,7 +1,8 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { DownloadProgressPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
+import { COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
+import type { CompanionSessionExitPayload, CompanionSessionOutputPayload, CompanionSessionOwnershipLostPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
+import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
-export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change';
+export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change' | typeof COMPANION_SESSION_OUTPUT_EVENT | typeof COMPANION_SESSION_EXIT_EVENT | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
 export interface MiniProgramBridgeError {
     code: string;
     message: string;
@@ -59,12 +60,12 @@ export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage
     payload?: never;
     error?: never;
 }
-export interface MiniProgramBridgeProgressMessage extends MiniProgramBridgeMessage<DownloadProgressPayload> {
+export interface MiniProgramBridgeProgressMessage<TMethod extends MiniProgramProgressMethod = MiniProgramProgressMethod> extends MiniProgramBridgeMessage<MiniProgramCapabilityProgress<TMethod>> {
     version: 2;
     type: 'event';
     id: string;
     method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
-    payload: DownloadProgressPayload;
+    payload: MiniProgramCapabilityProgress<TMethod>;
     error?: never;
 }
 export interface MiniProgramEventPayloadMap {
@@ -91,4 +92,7 @@ export interface MiniProgramEventPayloadMap {
         isHeyboxAppLoggedIn: boolean;
     };
     user_info_authorization_change: UserInfoAuthorization;
+    [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
+    [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
+    [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
 }

package/types/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, 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, 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, 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, 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";
@@ -41,6 +41,18 @@ export declare const CLOUD_LEADERBOARD_GET_LIST_METHOD: "cloud.leaderboard.getLi
 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 declare const COMPANION_GET_INFO_METHOD: "companion.getInfo";
+export declare const COMPANION_GET_PREPARATION_STATUS_METHOD: "companion.getPreparationStatus";
+export declare const COMPANION_PREPARE_METHOD: "companion.prepare";
+export declare const COMPANION_CANCEL_PREPARATION_METHOD: "companion.cancelPreparation";
+export declare const COMPANION_GET_ACTIVE_SESSION_METHOD: "companion.getActiveSession";
+export declare const COMPANION_LAUNCH_METHOD: "companion.launch";
+export declare const COMPANION_SESSION_WRITE_METHOD: "companion.session.write";
+export declare const COMPANION_SESSION_CLOSE_STDIN_METHOD: "companion.session.closeStdin";
+export declare const COMPANION_SESSION_TERMINATE_METHOD: "companion.session.terminate";
+export declare const COMPANION_SESSION_ACK_OUTPUT_METHOD: "companion.session.ackOutput";
+export declare const COMPANION_OPEN_ATTACHMENT_METHOD: "companion.openAttachment";
+export declare const COMPANION_SHOW_NOTIFICATION_METHOD: "companion.showNotification";
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
 export type MiniProgramShareMethod = typeof SHARE_COPY_LINK_METHOD | typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
@@ -54,8 +66,9 @@ export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_L
 export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_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 MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramFilesMethod | MiniProgramFileMethod | MiniProgramDirectoryMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod;
-export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'files' | 'file' | 'directory' | 'ui' | 'device' | 'navigation' | 'cloud';
+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;
+export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramFilesMethod | MiniProgramFileMethod | MiniProgramDirectoryMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod | MiniProgramCompanionMethod;
+export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'files' | 'file' | 'directory' | 'ui' | 'device' | 'navigation' | 'cloud' | 'companion';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 export interface MiniProgramCapabilityDefinition {
     method: MiniProgramBridgeMethod;
@@ -423,7 +436,16 @@ export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
         readonly permissions: readonly ["leaderboard"];
     };
     readonly risk: "low";
-}];
+}, ...{
+    method: "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";
+    module: "companion";
+    capability: "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";
+    requirement: {
+        kind: "all";
+        permissions: "companion"[];
+    };
+    risk: "high";
+}[]];
 export interface MiniProgramCapabilityPayloadMap {
     [AUTH_LOGIN_METHOD]: LoginPayload;
     [USER_GET_INFO_METHOD]: GetUserInfoPayload;
@@ -466,6 +488,18 @@ export interface MiniProgramCapabilityPayloadMap {
     [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;
+    [COMPANION_GET_INFO_METHOD]: CompanionGetInfoPayload;
+    [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusPayload;
+    [COMPANION_PREPARE_METHOD]: CompanionPreparePayload;
+    [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationPayload;
+    [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionPayload;
+    [COMPANION_LAUNCH_METHOD]: CompanionLaunchPayload;
+    [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWritePayload;
+    [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinPayload;
+    [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminatePayload;
+    [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputPayload;
+    [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentPayload;
+    [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationPayload;
 }
 export interface MiniProgramCapabilityResultMap {
     [AUTH_LOGIN_METHOD]: LoginResult;
@@ -509,6 +543,24 @@ export interface MiniProgramCapabilityResultMap {
     [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryResult;
     [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryResult;
     [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoResult;
+    [COMPANION_GET_INFO_METHOD]: CompanionGetInfoResult;
+    [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusResult;
+    [COMPANION_PREPARE_METHOD]: CompanionPrepareResult;
+    [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationResult;
+    [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionResult;
+    [COMPANION_LAUNCH_METHOD]: CompanionLaunchResult;
+    [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWriteResult;
+    [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinResult;
+    [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminateResult;
+    [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputResult;
+    [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentResult;
+    [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationResult;
 }
+export interface MiniProgramCapabilityProgressMap {
+    [NETWORK_DOWNLOAD_METHOD]: DownloadProgressPayload;
+    [COMPANION_PREPARE_METHOD]: CompanionPrepareProgress;
+}
+export type MiniProgramProgressMethod = keyof MiniProgramCapabilityProgressMap;
+export type MiniProgramCapabilityProgress<T extends MiniProgramProgressMethod> = MiniProgramCapabilityProgressMap[T];
 export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];
 export type MiniProgramCapabilityResult<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityResultMap[T];

package/types/constants.d.ts

@@ -6,3 +6,6 @@ export declare const RUNTIME_LOCATION_PROBE_METHOD: "runtime.location.probe";
 export declare const SDK_LOCATION_REPORT_METHOD: "sdk.location.report";
 export declare const SDK_CSP_VIOLATION_METHOD: "sdk.csp.violation";
 export declare const MINI_PROGRAM_OPERATION_PROGRESS_METHOD: "operation.progress";
+export declare const COMPANION_SESSION_OUTPUT_EVENT: "companion.session.output";
+export declare const COMPANION_SESSION_EXIT_EVENT: "companion.session.exit";
+export declare const COMPANION_SESSION_OWNERSHIP_LOST_EVENT: "companion.session.ownershipLost";

package/types/guards.d.ts

@@ -1,5 +1,5 @@
 import type { MiniProgramBridgeMessage } from './bridge';
-import type { DownloadProgressPayload, MiniProgramDirectoryDescriptor, MiniProgramDirectoryRef, MiniProgramFileDescriptor, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramPathRootRef } from './payloads';
+import type { CompanionPrepareProgress, DownloadProgressPayload, MiniProgramDirectoryDescriptor, MiniProgramDirectoryRef, MiniProgramFileDescriptor, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramPathRootRef } from './payloads';
 export declare function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage;
 export declare function isMiniProgramRelativePath(value: unknown): value is string;
 export declare function isMiniProgramPathRootRef(value: unknown): value is MiniProgramPathRootRef;
@@ -11,3 +11,5 @@ export declare function isMiniProgramFileSystemEntityDescriptor(value: unknown):
 export declare function isMiniProgramByteArray(value: unknown): value is Uint8Array;
 export declare function isMiniProgramFileStat(value: unknown): value is MiniProgramFileStat;
 export declare function isMiniProgramDownloadProgressPayload(value: unknown): value is DownloadProgressPayload;
+export declare function isMiniProgramCompanionPrepareProgress(value: unknown): value is CompanionPrepareProgress;
+export declare function isMiniProgramOperationProgressPayload(value: unknown): value is DownloadProgressPayload | CompanionPrepareProgress;

package/types/payloads.d.ts

@@ -463,4 +463,124 @@ export interface GetLeaderboardInfoResult {
     order: LeaderboardOrder;
     rankLimit: number;
 }
+/** 受管桌面程序可选能力。 */
+export type CompanionCapability = 'stdio' | 'attachments' | 'notifications';
+export type CompanionTarget = 'windows-x64' | 'macos-arm64';
+export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unknown';
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+export declare const COMPANION_ALIAS_PATTERN: RegExp;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+export declare const COMPANION_ERROR_CODES: readonly ["COMPANION_UNSUPPORTED", "COMPANION_NOT_DECLARED", "COMPANION_TARGET_UNSUPPORTED", "COMPANION_NOT_PREPARED", "COMPANION_PREPARATION_CANCELLED", "COMPANION_DOWNLOAD_FAILED", "COMPANION_DESCRIPTOR_UNAVAILABLE", "COMPANION_ARCHIVE_INVALID", "COMPANION_INTEGRITY_FAILED", "COMPANION_ENTRYPOINT_INVALID", "COMPANION_USER_CANCELLED", "COMPANION_ELEVATION_DENIED", "COMPANION_OS_BLOCKED", "COMPANION_LAUNCH_FAILED", "COMPANION_SESSION_VERSION_MISMATCH", "COMPANION_SESSION_OWNERSHIP_LOST", "COMPANION_SESSION_EXITED", "COMPANION_PIPE_CLOSED", "COMPANION_OUTPUT_LIMIT", "COMPANION_PROCESS_CRASHED", "COMPANION_ATTACHMENT_NOT_FOUND", "COMPANION_NOTIFICATION_UNAVAILABLE", "COMPANION_TERMINATE_FAILED"];
+export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
+export interface CompanionInfo {
+    alias: string;
+    displayName: string;
+    target: CompanionTarget;
+    capabilities: readonly CompanionCapability[];
+    archiveBytes: number;
+    signatureStatus: CompanionSignatureStatus;
+    /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
+    source?: 'local-dev' | 'released';
+}
+export interface CompanionErrorSummary {
+    code: CompanionErrorCode;
+    message: string;
+    retryable: boolean;
+}
+export type CompanionPrepareProgress = {
+    phase: 'downloading';
+    loaded: number;
+    total?: number;
+} | {
+    phase: 'verifying';
+    processed: number;
+    total: number;
+} | {
+    phase: 'extracting';
+    processed: number;
+    total: number;
+};
+export type CompanionPreparationStatus = {
+    state: 'not-prepared';
+} | {
+    state: 'preparing';
+    progress: CompanionPrepareProgress;
+} | {
+    state: 'ready';
+    preparedAt: number;
+} | {
+    state: 'failed';
+    error: CompanionErrorSummary;
+};
+export type CompanionExitReason = 'exited' | 'terminated' | 'crashed' | 'host-shutdown' | 'permission-revoked' | 'output-limit';
+export type CompanionExit = {
+    reason: 'exited';
+    exitCode: number;
+} | {
+    reason: Exclude<CompanionExitReason, 'exited'>;
+    exitCode?: number;
+};
+/** 活动 Session 的 wire 快照；不包含路径、PID 或原生句柄。 */
+export interface CompanionSessionSnapshot {
+    id: string;
+    alias: string;
+    target: CompanionTarget;
+    capabilities: readonly CompanionCapability[];
+    state: 'running';
+    controllerGeneration: number;
+}
+export interface CompanionAliasPayload {
+    alias: string;
+}
+export type CompanionGetInfoPayload = CompanionAliasPayload;
+export type CompanionGetInfoResult = CompanionInfo;
+export type CompanionGetPreparationStatusPayload = CompanionAliasPayload;
+export type CompanionGetPreparationStatusResult = CompanionPreparationStatus;
+export type CompanionPreparePayload = CompanionAliasPayload;
+export type CompanionPrepareResult = CompanionInfo;
+export type CompanionCancelPreparationPayload = CompanionAliasPayload;
+export type CompanionCancelPreparationResult = void;
+export type CompanionGetActiveSessionPayload = CompanionAliasPayload;
+export type CompanionGetActiveSessionResult = CompanionSessionSnapshot | undefined;
+export type CompanionLaunchPayload = CompanionAliasPayload;
+export type CompanionLaunchResult = CompanionSessionSnapshot;
+export interface CompanionSessionControllerPayload {
+    sessionId: string;
+    controllerGeneration: number;
+}
+export interface CompanionSessionWritePayload extends CompanionSessionControllerPayload {
+    data: Uint8Array;
+}
+export type CompanionSessionWriteResult = void;
+export type CompanionSessionCloseStdinPayload = CompanionSessionControllerPayload;
+export type CompanionSessionCloseStdinResult = void;
+export type CompanionSessionTerminatePayload = CompanionSessionControllerPayload;
+export type CompanionSessionTerminateResult = void;
+export interface CompanionSessionAckOutputPayload extends CompanionSessionControllerPayload {
+    stream: 'stdout' | 'stderr';
+    sequence: number;
+}
+export type CompanionSessionAckOutputResult = void;
+export interface CompanionOpenAttachmentPayload extends CompanionSessionControllerPayload {
+    id: string;
+}
+export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
+export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
+export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
+    category: CompanionNotificationCategory;
+}
+export type CompanionShowNotificationResult = void;
+export interface CompanionSessionOutputPayload extends CompanionSessionControllerPayload {
+    stream: 'stdout' | 'stderr';
+    sequence: number;
+    data: Uint8Array;
+}
+export interface CompanionSessionExitPayload {
+    sessionId: string;
+    exit: CompanionExit;
+}
+export interface CompanionSessionOwnershipLostPayload {
+    sessionId: string;
+    controllerGeneration: number;
+}
 export {};

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"];
+export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion"];
 export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
 export type MiniProgramPermissionRequirement = {
     readonly kind: 'none';
@@ -103,6 +103,15 @@ export declare const MINI_PROGRAM_PERMISSION_CATALOG: readonly [{
     };
     readonly methods: readonly ["network.request", "network.download"];
     readonly conditions: readonly ["声明后仍需平台批准，并继续执行网络安全策略。"];
+}, {
+    readonly key: "companion";
+    readonly name: "桌面辅助应用";
+    readonly description: "下载、准备并运行随当前小程序版本发布的受管桌面程序。";
+    readonly access: "platform-approval";
+    readonly risk: "high";
+    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 校验。"];
 }];
 export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
 export declare function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey;