moonbridge-ts 0.1.0

package/src/moonbridge-ipc/client/internal/ipc/keep/ipc_connection_keeper.ts

@@ -0,0 +1,70 @@
+// 对应：
+// moonbridge-ipc-flutter/lib/client/internal/ipc/keep/ipc_connection_keeper.dart
+//
+// IPC 连接保持器，定期检查并维持 IPC 连接的活跃状态。
+// 012 US4：心跳间隔来源与定时行为与 Flutter 一致（从 settings.heartbeatInterval 读取；Flutter 为 Duration，JS 为毫秒，在 Settings 层已对齐默认 3 秒）。组件引用为强引用，Flutter 使用 WeakReference，为已知差异。
+
+import { IpcClientComponentProvider } from '../ipc_client_component_provider';
+import { logger } from '../../../../utils/logger';
+
+export class IpcConnectionKeeper {
+  /** 组件提供者（强引用；Flutter 使用 WeakReference<IpcClientComponentProvider>） */
+  private readonly componentProvider: IpcClientComponentProvider;
+
+  private clientName = '';
+  private heartbeatEnabled = false;
+  private heartbeatIntervalMs = 0;
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(componentProvider: IpcClientComponentProvider) {
+    this.componentProvider = componentProvider;
+  }
+
+  initialize(): void {
+    const settings = this.componentProvider.settings;
+    this.clientName = settings.clientName;
+    this.heartbeatEnabled = settings.enableHeartbeat;
+    this.heartbeatIntervalMs = settings.heartbeatInterval;
+  }
+
+  startHeartbeat(): void {
+    if (!this.heartbeatEnabled || this.heartbeatTimer) {
+      return;
+    }
+
+    this.heartbeatTimer = setInterval(() => {
+      this.heartbeatTick();
+    }, this.heartbeatIntervalMs);
+  }
+
+  stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+  }
+
+  private heartbeatTick(): void {
+    const connectionManager = this.componentProvider.connectionManager;
+
+    if (connectionManager.isConnected()) {
+      logger.info('当前连接中，忽略本次心跳');
+      return;
+    }
+
+    connectionManager.connect((isConnected, error) => {
+      if (isConnected) {
+        logger.info(
+          `客户端(${this.clientName}) 通过心跳，重新成功建立连接.`,
+        );
+      } else {
+        logger.error(
+          `客户端(${this.clientName}) 心跳建立连接失败，error: ${String(
+            error,
+          )}`,
+        );
+      }
+    });
+  }
+}
+

package/src/moonbridge-ipc/client/internal/moonbridge_ipc_client.internal.ts

@@ -0,0 +1,154 @@
+/**
+ * MoonBridge IPC 客户端实际实现与注册表，对应 Flutter lib/client/internal/moonbridge_ipc_client.internal.dart。
+ * JS 端不实现 RPC（getService 恒返回 undefined）。
+ */
+
+import { IpcClientSettings } from './settings/ipc_client_settings';
+import { IpcMessageStrategy } from '../types/ipc_message_strategy';
+import { IpcConnectionCompletionHandler, IpcErrorCallback } from '../types/ipc_types';
+import { MoonBridgeIpcClient } from '../moonbridge_ipc_client';
+import { Messenger, MessageEndpoint, MessageCallOptions } from '../types/ipc_messenger';
+import { EventBus } from '../types/ipc_event_bus';
+import { logger } from '../../utils/logger';
+import { IpcClientComponentProvider } from './ipc/ipc_client_component_provider';
+import { IpcConnectionManager } from './ipc/connect/ipc_connection_manager';
+import { IpcRequestCoordinator } from './ipc/coordinator/ipc_request_coordinator';
+import { IpcCommunicationAgent } from './ipc/communication/ipc_communication_agent';
+import { IpcEventBus } from './ipc/eventbus/ipc_event_bus';
+import { IpcConnectionKeeper } from './ipc/keep/ipc_connection_keeper';
+import { IpcClientBridge } from './bridge/ipc_client_bridge';
+
+/**
+ * 实际 IPC 客户端实现：继承组件装配，并实现 MoonBridgeIpcClient、Messenger。
+ * 装配顺序与 Flutter RealMoonBridgeIpcClient 一致；JS 不传入 moduleFactories（见 spec 012）。
+ */
+export class RealMoonBridgeIpcClient implements IpcClientComponentProvider, MoonBridgeIpcClient, Messenger {
+  readonly settings: IpcClientSettings;
+  readonly connectionManager: IpcConnectionManager;
+  readonly requestCoordinator: IpcRequestCoordinator;
+  readonly communicationAgent: IpcCommunicationAgent;
+  readonly ipcEventBus: IpcEventBus;
+  readonly connectionKeeper: IpcConnectionKeeper;
+  readonly bridge: IpcClientBridge;
+
+  // CONSTRUCTOR
+
+  constructor(settings: IpcClientSettings) {
+    this.settings = settings;
+
+    this.connectionManager = new IpcConnectionManager(this);
+    this.requestCoordinator = new IpcRequestCoordinator(this);
+    this.communicationAgent = new IpcCommunicationAgent(this);
+    this.ipcEventBus = new IpcEventBus(this);
+    this.connectionKeeper = new IpcConnectionKeeper(this);
+    this.bridge = new IpcClientBridge(this, this.communicationAgent);
+
+    this.connectionManager.initialize();
+    this.requestCoordinator.initialize();
+    this.communicationAgent.initialize();
+    this.ipcEventBus.initialize();
+    this.connectionKeeper.initialize();
+    this.bridge.initialize();
+
+    logger.info(`[MoonBridgeIpcClient] 客户端 "${settings.clientName}" 已创建`);
+  }
+
+  // PUBLIC METHODS
+
+  get clientName(): string {
+    return this.settings.clientName;
+  }
+
+  connect(onResult?: IpcConnectionCompletionHandler): void {
+    this.connectionManager.connect(onResult);
+    this.connectionKeeper.startHeartbeat();
+  }
+
+  async disconnect(): Promise<void> {
+    await this.connectionManager.disconnect();
+    this.connectionKeeper.stopHeartbeat();
+  }
+
+  isConnected(): boolean {
+    return this.connectionManager.isConnected();
+  }
+
+  get messenger(): Messenger {
+    return this;
+  }
+
+  get eventBus(): EventBus {
+    return this.ipcEventBus;
+  }
+
+  postMessage(
+    target: MessageEndpoint,
+    argsOrOptions?: unknown[] | MessageCallOptions,
+  ): void {
+    const args = Array.isArray(argsOrOptions)
+      ? argsOrOptions
+      : (argsOrOptions?.args ?? []);
+    const strategy =
+      argsOrOptions && !Array.isArray(argsOrOptions)
+        ? argsOrOptions.strategy ?? this.settings.messageStrategy
+        : this.settings.messageStrategy;
+    const onError =
+      argsOrOptions && !Array.isArray(argsOrOptions)
+        ? argsOrOptions.onError
+        : undefined;
+    const remainingRetries = Math.max(strategy.retries, 0);
+    this.realPostMessage(
+      target.clientName,
+      target.moduleName,
+      target.methodName,
+      args,
+      onError,
+      strategy,
+      remainingRetries,
+    );
+  }
+
+  getService<T = unknown>(_clientName?: string): T | undefined {
+    return undefined;
+  }
+
+  // PRIVATE METHODS
+
+  private realPostMessage(
+    clientName: string,
+    moduleName: string,
+    methodName: string,
+    argumentsList: unknown[],
+    onError: IpcErrorCallback | undefined,
+    strategy: IpcMessageStrategy,
+    remainingRetries: number,
+  ): void {
+    const request = this.requestCoordinator.prepareAndCreateIpcRequest({
+      toClient: clientName,
+      moduleName,
+      methodName,
+      arguments: argumentsList,
+      onError,
+    });
+
+    this.communicationAgent.sendRequestAfterSetupSession(
+      request,
+      strategy,
+      (success, error) => {
+        if (remainingRetries - 1 <= 0) {
+          if (!success && error) onError?.(error);
+          return;
+        }
+        this.realPostMessage(
+          clientName,
+          moduleName,
+          methodName,
+          argumentsList,
+          onError,
+          strategy,
+          remainingRetries - 1,
+        );
+      },
+    );
+  }
+}

package/src/moonbridge-ipc/client/internal/settings/ipc_client_settings.ts

@@ -0,0 +1,142 @@
+// IPC 客户端配置，对应
+// moonbridge-ipc-flutter/lib/client/internal/settings/ipc_client_settings.dart
+// 012 US3：字段、必填/可选、默认值与 Flutter 一致；appLauncher 为 JS 扩展；heartbeatInterval 用毫秒存储，默认 3000 对应 Flutter Duration(seconds: 3)。
+
+import { WebSocketServerEndpoint } from '../../../general/config/websocket_server_endpoint';
+import {
+  AppInstallationPath,
+  AppLaunchIdentifier,
+} from '../../../general/app_launch/model/app_info';
+import { AppLauncher } from '../../../general/app_launch/app_launcher';
+import { IpcMessageStrategy } from '../../types/ipc_message_strategy';
+import { ConnectionObserver, MessageInterceptor } from '../../types/ipc_types';
+
+/** 心跳间隔默认值（毫秒），对应 Flutter Duration(seconds: 3) */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 3000;
+/** 唤醒后连接探测间隔（毫秒），每次失败后等待再重试 */
+const DEFAULT_WAKE_UP_PROBE_INTERVAL_MS = 400;
+/** 唤醒后连接探测总超时（毫秒），超过则返回失败 */
+const DEFAULT_WAKE_UP_PROBE_TIMEOUT_MS = 12000;
+
+/**
+ * 构造函数参数类型。
+ * 使用独立的 options 类型，避免在构造函数上直接声明复杂对象类型。
+ */
+export interface IpcClientSettingsOptions {
+  clientName: string;
+  serverInstallationPath?: AppInstallationPath;
+  serverLaunchIdentifier?: AppLaunchIdentifier;
+  enableHeartbeat?: boolean;
+  /**
+   * 心跳检测间隔时间（毫秒）。与 Flutter Duration 对应：默认 3000 即 Flutter 的 Duration(seconds: 3)。
+   */
+  heartbeatIntervalMs?: number;
+  messageStrategy?: IpcMessageStrategy;
+  messageInterceptor?: MessageInterceptor;
+  connectionObserver?: ConnectionObserver;
+  webSocketServerEndpoint?: WebSocketServerEndpoint;
+  /** US4：可选注入，用于跨进程唤醒服务端；未提供时使用 StubAppLauncher */
+  appLauncher?: AppLauncher;
+  /**
+   * 019：唤醒后连接探测间隔（毫秒）；默认 400。
+   * 每次连接尝试失败后等待此间隔再重试。
+   */
+  wakeUpProbeIntervalMs?: number;
+  /**
+   * 019：唤醒后连接探测总超时（毫秒）；默认 12000。
+   * 超过此时长未连上则返回失败。
+   */
+  wakeUpProbeTimeoutMs?: number;
+}
+
+/**
+ * IPC 客户端配置类。
+ *
+ * 传输方式由 socketServerEndpoint 或 webSocketServerEndpoint 二选一决定，至多一个非 null。
+ */
+export class IpcClientSettings {
+  /** 客户端名称 */
+  readonly clientName: string;
+
+  /** 服务器应用路径，用于唤醒服务器应用 */
+  readonly serverInstallationPath?: AppInstallationPath;
+
+  /** 服务端应用标识符信息，用于唤醒服务器应用 */
+  readonly serverLaunchIdentifier?: AppLaunchIdentifier;
+
+  /** 是否启用心跳检测 */
+  readonly enableHeartbeat: boolean;
+
+  /** 心跳检测间隔时间（毫秒） */
+  readonly heartbeatInterval: number;
+
+  /** 消息策略 */
+  readonly messageStrategy: IpcMessageStrategy;
+
+  /** 消息拦截器，可选 */
+  readonly messageInterceptor?: MessageInterceptor;
+
+  /** 连接状态观察者，可选 */
+  readonly connectionObserver?: ConnectionObserver;
+
+  /**
+   * WebSocket 连接配置；
+   */
+  readonly webSocketServerEndpoint?: WebSocketServerEndpoint;
+
+  /** JS 扩展：可选注入的唤醒器（Flutter 暂无此字段）；未提供时 ConnectionManager 使用 StubAppLauncher。 */
+  readonly appLauncher?: AppLauncher;
+
+  /** 019：唤醒后连接探测间隔（毫秒）；默认 400 */
+  readonly wakeUpProbeIntervalMs: number;
+
+  /** 019：唤醒后连接探测总超时（毫秒）；默认 12000 */
+  readonly wakeUpProbeTimeoutMs: number;
+
+  constructor(options: IpcClientSettingsOptions) {
+    this.clientName = options.clientName;
+    this.serverInstallationPath = options.serverInstallationPath;
+    this.serverLaunchIdentifier = options.serverLaunchIdentifier;
+    this.enableHeartbeat = options.enableHeartbeat ?? true;
+    this.heartbeatInterval = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.messageStrategy = options.messageStrategy ?? new IpcMessageStrategy();
+    this.messageInterceptor = options.messageInterceptor;
+    this.connectionObserver = options.connectionObserver;
+    this.webSocketServerEndpoint = options.webSocketServerEndpoint;
+    this.appLauncher = options.appLauncher;
+    this.wakeUpProbeIntervalMs = options.wakeUpProbeIntervalMs ?? DEFAULT_WAKE_UP_PROBE_INTERVAL_MS;
+    this.wakeUpProbeTimeoutMs = options.wakeUpProbeTimeoutMs ?? DEFAULT_WAKE_UP_PROBE_TIMEOUT_MS;
+  }
+
+  /** 有效服务端地址（来自当前使用的传输配置） */
+  get serverAddress(): string {
+    return this.webSocketServerEndpoint!.address;
+  }
+
+  /** 有效服务端端口（来自当前使用的传输配置） */
+  get serverPort(): number {
+    return this.webSocketServerEndpoint!.port;
+  }
+
+  /** 是否使用 WebSocket 传输（由“哪个配置非 null”推断） */
+  get useWebSocket(): boolean {
+    return this.webSocketServerEndpoint != null;
+  }
+
+  /** WebSocket 端口（仅当使用 WebSocket 时有效） */
+  get webSocketPort(): number | undefined {
+    return this.webSocketServerEndpoint?.port;
+  }
+
+  /** WebSocket 升级路径（仅当使用 WebSocket 时有效） */
+  get webSocketPath(): string {
+    return this.webSocketServerEndpoint?.path ?? '/';
+  }
+
+  /** 是否使用 wss（仅当使用 WebSocket 时有效） */
+  get useTls(): boolean {
+    return this.webSocketServerEndpoint?.useTls ?? false;
+  }
+}
+
+

package/src/moonbridge-ipc/client/moonbridge_ipc_client.ts

@@ -0,0 +1,222 @@
+/**
+ * MoonBridge IPC 客户端入口类，对应 Flutter lib/client/moonbridge_ipc_client.dart。
+ * 定义连接管理、消息发送与事件总线等公开 API；不含 RPC（JS 端不实现）。
+ */
+
+import { WebSocketServerEndpoint } from '../general/config/websocket_server_endpoint';
+import { AppInstallationPath, AppLaunchIdentifier } from '../general/app_launch/model/app_info';
+import { AppLauncher } from '../general/app_launch/app_launcher';
+import { IpcClientSettings } from './internal/settings/ipc_client_settings';
+import { IpcMessageStrategy } from './types/ipc_message_strategy';
+import { ConnectionObserver, IpcConnectionCompletionHandler, MessageInterceptor } from './types/ipc_types';
+import { EventBus } from './types/ipc_event_bus';
+import { Messenger } from './types/ipc_messenger';
+import { RealMoonBridgeIpcClient } from './internal/moonbridge_ipc_client.internal';
+
+/** MoonBridge IPC 客户端抽象接口 */
+export interface MoonBridgeIpcClient {
+  /** 
+   * 连接到 IPC 服务器 
+   */
+  connect(onResult?: IpcConnectionCompletionHandler): void;
+  /** 
+   * 断开与 IPC 服务器的连接 
+   */
+  disconnect(): Promise<void>;
+  /** 
+   * 检查是否已连接到 IPC 服务器 
+   */
+  isConnected(): boolean;
+  /** 
+   * 客户端名称 
+   */
+  readonly clientName: string;
+  /** 
+   * 消息发送器 
+   */
+  readonly messenger: Messenger;
+  /** 
+   * 事件总线 
+   */
+  readonly eventBus: EventBus;
+}
+
+// PUBLIC CLASS
+
+/** 构造器，用于链式配置并构建客户端实例 */
+export class MoonBridgeIpcClientBuilder {
+  private _clientName = '';
+  private _webSocketServerEndpoint?: WebSocketServerEndpoint;
+  private _serverInstallationPath?: AppInstallationPath;
+  private _serverLaunchIdentifier?: AppLaunchIdentifier;
+  private _enableHeartbeat?: boolean;
+  private _heartbeatIntervalMs?: number;
+  private _messageStrategy?: IpcMessageStrategy;
+  private _messageInterceptor?: MessageInterceptor;
+  private _connectionObserver?: ConnectionObserver;
+  private _appLauncher?: AppLauncher;
+
+  // PUBLIC METHODS
+
+  /**
+   * 创建客户端构建器 
+   */
+  static builder(): MoonBridgeIpcClientBuilder {
+    return new MoonBridgeIpcClientBuilder();
+  }
+
+  /**
+   * 设置客户端名称 
+   */
+  clientName(name: string): this {
+    this._clientName = name;
+    return this;
+  }
+
+  /**
+   * 设置 WebSocket 连接配置 
+   */
+  useWebSocketChannel(endpoint: WebSocketServerEndpoint | undefined): this {
+    this._webSocketServerEndpoint = endpoint;
+    return this;
+  }
+
+  /**
+   * 设置服务器应用路径 
+   */
+  serverInstallationPath(path: AppInstallationPath): this {
+    this._serverInstallationPath = path;
+    return this;
+  }
+
+  /**
+   * 设置服务器应用标识符 
+   */
+  serverLaunchIdentifier(identifier: AppLaunchIdentifier): this {
+    this._serverLaunchIdentifier = identifier;
+    return this;
+  }
+
+  /**
+   * 设置是否启用心跳检测 
+   */
+  enableHeartbeat(enable: boolean): this {
+    this._enableHeartbeat = enable;
+    return this;
+  }
+
+  /**
+   * 设置心跳检测间隔时间 
+   */
+  heartbeatIntervalMs(ms: number): this {
+    this._heartbeatIntervalMs = ms;
+    return this;
+  }
+
+  /**
+   * 设置消息策略 
+   */
+  messageStrategy(strategy: IpcMessageStrategy): this {
+    this._messageStrategy = strategy;
+    return this;
+  }
+
+  /**
+   * 设置消息拦截器 
+   */
+  messageInterceptor(interceptor?: MessageInterceptor): this {
+    this._messageInterceptor = interceptor;
+    return this;
+  }
+
+  /**
+   * 设置连接状态观察者 
+   */
+  connectionObserver(observer?: ConnectionObserver): this {
+    this._connectionObserver = observer;
+    return this;
+  }
+
+  /** 
+   * 注入应用启动器
+   * 用于覆盖默认的唤醒方式（如 wps-addin 通过 URL Scheme 唤起） 
+   */
+  appLauncher(launcher: AppLauncher | undefined): this {
+    this._appLauncher = launcher;
+    return this;
+  }
+
+  /**
+   * 构建客户端实例并可选注册为默认客户端。
+   */
+  build(makeDefault = false): MoonBridgeIpcClient {
+    if (!this._clientName || this._clientName.trim() === '') {
+      throw new Error('clientName must be non-empty.');
+    }
+    if (!this._webSocketServerEndpoint) {
+      throw new Error(
+        'Call useWebSocketChannel to set the transport configuration.',
+      );
+    }
+
+    const settings = new IpcClientSettings({
+      clientName: this._clientName,
+      webSocketServerEndpoint: this._webSocketServerEndpoint,
+      serverInstallationPath: this._serverInstallationPath,
+      serverLaunchIdentifier: this._serverLaunchIdentifier,
+      enableHeartbeat: this._enableHeartbeat,
+      heartbeatIntervalMs: this._heartbeatIntervalMs,
+      messageStrategy: this._messageStrategy,
+      messageInterceptor: this._messageInterceptor,
+      connectionObserver: this._connectionObserver,
+      appLauncher: this._appLauncher,
+    });
+
+    const client = new RealMoonBridgeIpcClient(settings);
+    MoonBridgeIpcClientRegistry.getInstance().register(client);
+    if (makeDefault) {
+      MoonBridgeIpcClientRegistry.getInstance().setDefault(client);
+    }
+    return client;
+  }
+}
+
+
+/** 
+ * 客户端注册表单例 
+ */
+export class MoonBridgeIpcClientRegistry {
+  private static _instance: MoonBridgeIpcClientRegistry;
+  private readonly _clientMap = new Map<string, MoonBridgeIpcClient>();
+
+  /**
+   * 获取客户端注册表单例 
+   */
+  static getInstance(): MoonBridgeIpcClientRegistry {
+    if (!MoonBridgeIpcClientRegistry._instance) {
+      MoonBridgeIpcClientRegistry._instance = new MoonBridgeIpcClientRegistry();
+    }
+    return MoonBridgeIpcClientRegistry._instance;
+  }
+
+  /**
+   * 设置默认客户端 
+   */
+  setDefault(client: MoonBridgeIpcClient): void {
+    this._clientMap.set('__default__', client);
+  }
+
+  /**
+   * 注册客户端 
+   */
+  register(client: MoonBridgeIpcClient): void {
+    this._clientMap.set(client.clientName, client);
+  }
+
+  /**
+   * 获取客户端 
+   */
+  get(clientName?: string): MoonBridgeIpcClient | undefined {
+    return this._clientMap.get(clientName ?? '__default__');
+  }
+}

package/src/moonbridge-ipc/client/types/ipc_event_bus.ts

@@ -0,0 +1,28 @@
+/**
+ * IPC 事件总线接口与订阅者类型，对应 Flutter lib/client/types/ipc_event_bus.dart。
+ */
+
+import { Event } from '../../general/message/event';
+
+/** IPC 事件总线接口。 */
+export interface EventBus {
+  /** 注册事件订阅者，订阅特定类型的事件。 */
+  register(subscriber: Subscriber): void;
+
+  /** 注销事件订阅者，取消订阅事件。 */
+  unregister(subscriber: Subscriber): void;
+
+  /** 发布事件，通知所有订阅者。 */
+  post(event: Event): Promise<void>;
+}
+
+/** IPC 事件订阅者，定义处理特定类型 IPC 事件的方式。 */
+export class Subscriber {
+  constructor(
+    /** 事件类型 */
+    public readonly eventType: string,
+    /** 匹配到感兴趣事件类型时的处理函数 */
+    public readonly onEvent: (event: Event) => void,
+  ) { }
+}
+

package/src/moonbridge-ipc/client/types/ipc_message_strategy.ts

@@ -0,0 +1,21 @@
+/**
+ * IPC 消息策略类，对应 Flutter lib/client/types/ipc_message_strategy.dart IpcMessageStrategy。
+ */
+
+export class IpcMessageStrategy {
+  constructor(
+    /** 重试次数，默认为 1 */
+    public readonly retries: number = 1,
+    /** 是否应该自动启动目标应用，默认为 true */
+    public readonly autoLaunch: boolean = true,
+  ) {
+    if (this.retries < 0) {
+      throw new Error('retries must be greater than 0');
+    }
+  }
+
+  toString(): string {
+    return `IpcMessageStrategy(retries: ${this.retries}, autoLaunch: ${this.autoLaunch})`;
+  }
+}
+

package/src/moonbridge-ipc/client/types/ipc_messenger.ts

@@ -0,0 +1,42 @@
+/**
+ * IPC 消息信使抽象，对应 Flutter lib/client/types/ipc_messenger.dart Messenger。
+ * 仅定义接口，不包含具体实现。
+ */
+
+import { IpcErrorCallback } from './ipc_types';
+import { IpcMessageStrategy } from './ipc_message_strategy';
+
+/**
+ * 消息端点类型
+ * 用于唯一标识一个方法，包括客户端名称、模块名称和方法名称。
+ */
+export type MessageEndpoint = {
+  clientName: string;
+  moduleName: string;
+  methodName: string;
+};
+
+/**
+ * 消息调用配置类型
+ * 用于传递消息调用时的参数和配置。
+ */
+export interface MessageCallOptions {
+  args?: unknown[];
+  strategy?: IpcMessageStrategy;
+  onError?: IpcErrorCallback;
+}
+
+export interface Messenger {
+  /** 极简调用：仅传核心定位+参数 */
+  postMessage(target: MessageEndpoint, args?: unknown[]): void;
+  /** 完整调用：传定位+全量配置 */
+  postMessage(target: MessageEndpoint, options?: MessageCallOptions): void;
+
+  /**
+   * 获取指定 RPC 服务接口的代理实例。
+   *
+   * @param clientName 目标客户端名称，可选
+   * @returns 类型为 T 的服务代理实例，或 undefined（如客户端不存在 / 服务未注册）。US2：统一使用 undefined。
+   */
+  getService<T = unknown>(clientName?: string): T | undefined;
+}