moonbridge-ts 0.1.0

package/src/moonbridge-ipc/client/internal/ipc/connect/ipc_connection_manager.ts

@@ -0,0 +1,454 @@
+// 对应：
+// moonbridge-ipc-flutter/lib/client/internal/ipc/connect/ipc_connection_manager.dart
+//
+// IPC 连接管理器，负责维护 IPC 通信的连接状态。
+// 012 US1：JS 端仅使用 webSocketServerEndpoint 构造 WebSocket 客户端，不使用 socketServerEndpoint。
+// 010 US1：握手在 performHandshake 内等待服务端 TYPE_NAME_HANDSHAKE 响应并校验 magic/role，与 Flutter 一致。
+// 010 US4：当直接连接失败且 shouldAttemptWakeUp 为 true 时，调用 settings.appLauncher.launchApp() 后重试。
+// 019：连接探测——唤醒后立即尝试连接，失败则短间隔重试，成功即停止；launchApp 返回 AppLaunchResult。
+
+import { IpcClientComponentProvider } from '../ipc_client_component_provider';
+import { IpcClientSettings } from '../../settings/ipc_client_settings';
+import { IpcMessageStrategy } from '../../../types/ipc_message_strategy';
+import { IpcConnectionCompletionHandler } from '../../../types/ipc_types';
+import { TransportClient } from '../../../../general/transport/interface/transport_client';
+import { PortCandidateRule } from '../../../../general/config/port_candidate_rule';
+import { Handshake } from '../../../../general/message/handshake';
+import { IpcSessionSetupRequest, IpcSessionSetupResponse } from '../../../../general/message/session_setup';
+import { Request } from '../../../../general/message/request';
+import { IpcError } from '../../../../general/error/ipc_error';
+import { MessageType } from '../../../../general/message/constants/message_types';
+import { IpcMessageDecoder } from '../../../../general/encode/ipc_message_decoder';
+import { PlatformAppLauncherFactory } from '../../../../general/app_launch/platform_app_launcher';
+import { logger } from '../../../../utils/logger';
+import { sendHandshake, setupSession, } from '../../../../general/transport/interface/transport_client_extension';
+import { WebSocketClient } from '../../../../general/transport/websocket/websocket_client';
+
+/** 
+ * IPC 通信环境构建结果回调
+ */
+export type IpcSessionSetupCallback = (success: boolean, error?: IpcError) => void;
+
+/**
+ * IPC 连接管理器，负责维护 IPC 通信的连接状态
+ */
+export class IpcConnectionManager {
+  private readonly settings: IpcClientSettings;
+  private readonly componentProvider: IpcClientComponentProvider;
+  private readonly clientName: string;
+
+  private transportClient: TransportClient;
+  private connectionHandlers: Array<IpcConnectionCompletionHandler> = [];
+  private sessionSetupCallbacks: Map<string, Array<IpcSessionSetupCallback>> = new Map();
+  private onMessageReceivedListener?: (message: string) => void;
+
+  constructor(componentProvider: IpcClientComponentProvider) {
+    this.componentProvider = componentProvider;
+    this.settings = componentProvider.settings;
+    this.clientName = componentProvider.settings.clientName;
+
+    // 初始化传输通道（JS 端仅实现 WebSocket 通道）
+    const ws = this.settings.webSocketServerEndpoint;
+    if (!ws) {
+      throw new Error(
+        'IpcConnectionManager: webSocketServerEndpoint must be provided in IpcClientSettings for JS client.',
+      );
+    }
+    const ports = this.getPortList(ws.port, ws.portCandidateRule ?? undefined);
+    // 使用首个端口创建初始 client；有 portCandidateRule 时 attemptConnection 会按端口列表依次尝试
+    this.transportClient = new WebSocketClient(
+      ws.address,
+      ports[0],
+      ws.path,
+      ws.useTls,
+    );
+  }
+
+  initialize(): void {
+    this.bindTransportEvents();
+  }
+
+  onMessageReceived(listener: (message: string) => void): void {
+    this.onMessageReceivedListener = listener;
+    this.transportClient.onMessage(listener);
+  }
+
+  async connect(
+    onResult?: IpcConnectionCompletionHandler,
+    options?: { autoLaunch?: boolean },
+  ): Promise<void> {
+    logger.debug(`[ConnectionManager] connect 开始 clientName=${this.clientName}`);
+    if (this.isConnected()) {
+      this.handleAlreadyConnected(onResult);
+      return;
+    }
+
+    if (onResult) {
+      this.connectionHandlers.push(onResult);
+    }
+    if (this.connectionHandlers.length > 1) {
+      return;
+    }
+
+    if (
+      await this.attemptConnection({
+        maxConnectionAttempts: 2,
+        notifyIfConnectionFailed: false,
+      })
+    ) {
+      logger.info('直接建立与服务端进程的连接成功!');
+      return;
+    }
+
+    const shouldWakeUp = this.shouldAttemptWakeUp(options?.autoLaunch);
+    if (shouldWakeUp) {
+      logger.warn('服务端进程不存在，尝试唤醒服务端并建立连接.');
+      const appLauncher = this.settings.appLauncher ?? PlatformAppLauncherFactory.create({
+        appIdentifier: this.settings.serverLaunchIdentifier,
+        appInstallationPath: this.settings.serverInstallationPath,
+      });
+
+      const result = await appLauncher.launchApp();
+      if (!result.isSuccess) {
+        logger.fatal(`客户端('${this.clientName}')唤醒服务端 App 失败: ${result.error ?? '未知原因'}`);
+        this.handleConnectionFailed(result.error);
+        return;
+      }
+      logger.info(`客户端('${this.clientName}')已触发唤醒，即将进行连接探测!`);
+      const connected = await this.attemptConnectionWithProbe();
+      if (connected) return;
+      this.handleConnectionFailed();
+    } else {
+      logger.warn('服务端进程不存在，触发服务端 socket 关闭事件.');
+      this.onServerClose();
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    await this.componentProvider.communicationAgent.unregister();
+    await this.transportClient.close();
+  }
+
+  isConnected(): boolean {
+    return this.transportClient.isClientConnected;
+  }
+
+  setupSession(
+    request: Request,
+    callback: IpcSessionSetupCallback,
+    autoLaunch: boolean,
+  ): void {
+    if (!this.isConnected()) {
+      logger.info(`客户端('${this.clientName}')未连接，尝试建立连接...`);
+      void this.connect((success, error) => {
+        if (success) {
+          this.setupSessionAfterConnection(request, callback, autoLaunch);
+        } else {
+          callback(false, error ?? undefined);
+        }
+      }, { autoLaunch });
+      return;
+    }
+
+    this.setupSessionAfterConnection(request, callback, autoLaunch);
+  }
+
+  onSessionSetupCallback(response: IpcSessionSetupResponse): void {
+    const callbacks = this.sessionSetupCallbacks.get(response.callbackId);
+    if (!callbacks) {
+      return;
+    }
+    this.sessionSetupCallbacks.delete(response.callbackId);
+
+    const error = new IpcError(
+      IpcError.ERROR_IPC_SESSION_ABNORMAL,
+      response.message,
+      response.userInfo ?? undefined,
+    );
+    const result = response.result === IpcSessionSetupResponse.success;
+
+    for (const cb of callbacks) {
+      cb(result, result ? undefined : error);
+    }
+  }
+
+  get transportClientInstance(): TransportClient {
+    return this.transportClient;
+  }
+
+  // PRIVATE HELPERS
+
+  private bindTransportEvents(): void {
+    this.transportClient.onErrorAndClose({
+      onError: this.onError.bind(this),
+      onServerClose: this.onServerClose.bind(this),
+    });
+
+    if (this.onMessageReceivedListener) {
+      this.transportClient.onMessage(this.onMessageReceivedListener);
+    }
+  }
+
+  private getPortList(port: number, portCandidateRule?: PortCandidateRule): Array<number> {
+    if (portCandidateRule) {
+      return portCandidateRule.toOrderedPortList();
+    }
+    return [port];
+  }
+
+  /**
+   * 生成环境回调 ID，与 Flutter _generateSessionCallbackId 一致。
+   * 同一 (fromClient, toClient) 对的多个请求共享同一 sessionCallbackId，仅首次会发送 IpcSessionSetupRequest。
+   */
+  private generateSessionCallbackId(request: Request): string {
+    return `${request.fromClient}_${request.toClient}`;
+  }
+
+  /**
+   * 对指定 client 执行应用层握手，与 Flutter _performHandshake 语义一致：
+   * 发送握手请求后，在短超时内等待带相同 magic 与 server 角色的握手响应，成功才返回 true。
+   */
+  private async performHandshake(client: TransportClient): Promise<boolean> {
+    logger.debug(`[ConnectionManager] 开始握手 clientName=${this.clientName}`);
+    const hello = new Handshake(
+      this.clientName,
+      Handshake.ipcMagic,
+      Handshake.clientRole,
+      Handshake.ipcVersion,
+    );
+    const sent = await sendHandshake(client, hello);
+    if (!sent) {
+      return false;
+    }
+
+    let settled = false;
+    let complete: (value: boolean) => void;
+    const handshakePromise = new Promise<boolean>((resolve) => {
+      complete = resolve;
+    });
+    const resolveOnce = (value: boolean) => {
+      if (settled) return;
+      settled = true;
+      complete(value);
+    };
+
+    const onMessage = (message: string): void => {
+      if (settled) return;
+      // 约定：首条应用层消息若非握手响应，则判定非目标 IPC 服务，立即失败
+      if (!message.includes(MessageType.HANDSHAKE)) {
+        resolveOnce(false);
+        return;
+      }
+      try {
+        const hs = IpcMessageDecoder.decodeHandshake(message);
+        const isTargetServer =
+          hs.magic === Handshake.ipcMagic && hs.role === Handshake.serverRole;
+        resolveOnce(isTargetServer);
+      } catch {
+        resolveOnce(false);
+      }
+    };
+
+    client.onMessage(onMessage);
+
+    const timeoutMs = 1000;
+    const timeoutId = setTimeout(() => {
+      resolveOnce(false);
+    }, timeoutMs);
+
+    try {
+      const result = await handshakePromise;
+      logger.debug(`[ConnectionManager] 握手结束 clientName=${this.clientName} success=${result}`);
+      return result;
+    } finally {
+      clearTimeout(timeoutId);
+      if (this.onMessageReceivedListener) {
+        client.onMessage(this.onMessageReceivedListener);
+      }
+    }
+  }
+
+  /**
+   * 019：唤醒后连接探测。立即尝试连接，失败则短间隔重试，成功即停止；支持多轮端口遍历。
+   */
+  private async attemptConnectionWithProbe(): Promise<boolean> {
+    const intervalMs = this.settings.wakeUpProbeIntervalMs;
+    const timeoutMs = this.settings.wakeUpProbeTimeoutMs;
+    const start = Date.now();
+    let round = 0;
+
+    // eslint-disable-next-line no-constant-condition -- 连接探测循环，通过 return 退出
+    while (true) {
+      round += 1;
+      logger.debug(
+        `[ConnectionManager] 连接探测 第 ${round} 轮 clientName=${this.clientName}`,
+      );
+      const ok = await this.attemptConnection({
+        maxConnectionAttempts: 1,
+        notifyIfConnectionFailed: false,
+      });
+      if (ok) {
+        logger.info(`客户端('${this.clientName}')连接探测成功`);
+        return true;
+      }
+      const elapsed = Date.now() - start;
+      if (elapsed >= timeoutMs) {
+        logger.warn(
+          `客户端('${this.clientName}')连接探测超时，已耗时 ${elapsed}ms`,
+        );
+        return false;
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+
+  private async attemptConnection(options?: {
+    maxConnectionAttempts?: number;
+    notifyIfConnectionFailed?: boolean;
+  }): Promise<boolean> {
+    const maxAttempts = options?.maxConnectionAttempts ?? 1;
+    const ws = this.settings.webSocketServerEndpoint;
+    if (!ws) return false;
+
+    const portList = this.getPortList(ws.port, ws.portCandidateRule ?? undefined);
+    const hasPortRule = portList.length > 1;
+
+    if (hasPortRule) {
+      // 有 portCandidateRule 时：遍历端口列表，依次尝试 9100、9101、9102...
+      logger.debug(`[ConnectionManager] attemptConnection 遍历端口列表，共 ${portList.length} 个端口`);
+      for (const port of portList) {
+        try {
+          const client = new WebSocketClient(ws.address, port, ws.path, ws.useTls);
+          if (await client.connectWithServer()) {
+            const ok = await this.performHandshake(client);
+            if (ok) {
+              await this.transportClient.close();
+              this.transportClient = client;
+              this.bindTransportEvents();
+              const registered = await this.componentProvider.communicationAgent.register();
+              if (registered) {
+                logger.info(`客户端(${this.clientName})注册成功.`);
+              }
+              this.notifyConnectionResult(true, undefined);
+              return true;
+            }
+            await client.close();
+          }
+        } catch (e) {
+          this.handleConnectionException(e);
+        }
+      }
+    } else {
+      // 无 portCandidateRule：沿用原逻辑，重试同一端口
+      logger.debug(`[ConnectionManager] attemptConnection maxAttempts=${maxAttempts}`);
+      for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+          if (await this.transportClient.connectWithServer()) {
+            const ok = await this.performHandshake(this.transportClient);
+            if (ok) {
+              const registered = await this.componentProvider.communicationAgent.register();
+              if (registered) {
+                logger.info(`客户端(${this.clientName})注册成功.`);
+              }
+              this.notifyConnectionResult(true, undefined);
+              return true;
+            }
+            await this.transportClient.close();
+          }
+        } catch (e) {
+          this.handleConnectionException(e);
+        }
+      }
+    }
+
+    if (options?.notifyIfConnectionFailed ?? true) {
+      this.handleConnectionFailed();
+    }
+    return false;
+  }
+
+  private handleConnectionFailed(launchError?: string): void {
+    const message = launchError
+      ? `Connect server socket failed! Launch error: ${launchError}`
+      : 'Connect server socket failed!';
+    const userInfo = launchError ? { launchError } : undefined;
+    this.notifyConnectionResult(
+      false,
+      new IpcError(IpcError.ERROR_BIND_SERVER, message, userInfo),
+    );
+    logger.error(`客户端('${this.clientName}')与服务端建立连接失败${launchError ? `: ${launchError}` : ''}`);
+  }
+
+  private handleConnectionException(e: unknown): void {
+    this.notifyConnectionResult(
+      false,
+      new IpcError(
+        IpcError.ERROR_BIND_SERVER_EXCEPTION,
+        'Connect server socket exception!',
+      ),
+    );
+    logger.error(`客户端('${this.clientName}')与服务端建立连接异常: ${String(e)}`);
+  }
+
+  private handleAlreadyConnected(handler?: IpcConnectionCompletionHandler): void {
+    if (handler) {
+      handler(true, undefined);
+    }
+  }
+
+  private shouldAttemptWakeUp(autoLaunchOverride?: boolean): boolean {
+    if (typeof autoLaunchOverride === 'boolean') {
+      return autoLaunchOverride;
+    }
+    const strategy: IpcMessageStrategy = this.settings.messageStrategy;
+    return strategy.autoLaunch;
+  }
+
+  private setupSessionAfterConnection(
+    request: Request,
+    callback: IpcSessionSetupCallback,
+    autoLaunch: boolean,
+  ): void {
+    const sessionCallbackId = this.generateSessionCallbackId(request);
+    const callbacks =
+      this.sessionSetupCallbacks.get(sessionCallbackId) ?? [];
+    callbacks.push(callback);
+    this.sessionSetupCallbacks.set(sessionCallbackId, callbacks);
+
+    // 仅首次构建目标会话时发起 IpcSessionSetupRequest（与 Flutter 一致）
+    if (callbacks.length === 1) {
+      const setupRequest = new IpcSessionSetupRequest(
+        this.clientName,
+        request.toClient,
+        sessionCallbackId,
+        autoLaunch,
+      );
+      setupSession(this.transportClient, setupRequest);
+    }
+  }
+
+  private onError(_error: unknown): void {
+    logger.error(`客户端('${this.clientName}')与服务端连接出错: ${String(_error)}!`);
+    this.notifyConnectionResult(
+      false,
+      new IpcError(IpcError.ERROR_DISCONNECTED_WITH_SERVER, 'Disconnected from server!'),
+    );
+  }
+
+  private onServerClose(): void {
+    logger.error(`客户端('${this.clientName}')断开与服务端的连接，服务端 socket 关闭!`);
+    this.notifyConnectionResult(
+      false,
+      new IpcError(IpcError.ERROR_SERVER_SOCKET_CLOSED, 'Server socket closed!'),
+    );
+  }
+
+  private notifyConnectionResult(success: boolean, error?: IpcError): void {
+    const handlers = this.connectionHandlers;
+    this.connectionHandlers = [];
+    for (const handler of handlers) {
+      handler(success, error ?? undefined);
+    }
+  }
+}
+

package/src/moonbridge-ipc/client/internal/ipc/coordinator/ipc_request_coordinator.ts

@@ -0,0 +1,147 @@
+// 对应：
+// moonbridge-ipc-flutter/lib/client/internal/ipc/coordinator/ipc_request_coordinator.dart
+//
+// IPC 客户端请求与响应协调器。
+
+import { IpcClientComponentProvider } from '../ipc_client_component_provider';
+import { IpcErrorCallback, IpcResponseCallback } from '../../../types/ipc_types';
+import { Request } from '../../../../general/message/request';
+import { Response } from '../../../../general/message/response';
+import { Error } from '../../../../general/message/error';
+import { IpcError } from '../../../../general/error/ipc_error';
+import { logger } from '../../../../utils/logger';
+import { generateRandomString } from '../../../../utils/string_utils';
+
+/**
+ * IPC 客户端请求与响应协调器类
+ * 负责构建 IPC 请求的参数并管理相应的回调处理。
+ */
+export class IpcRequestCoordinator {
+  private readonly clientName: string;
+
+  private readonly responseCallbacks: Map<
+    string,
+    Map<string, IpcResponseCallback>
+  > = new Map();
+
+  private readonly errorCallbacks: Map<string, IpcErrorCallback> = new Map();
+
+  constructor(componentProvider: IpcClientComponentProvider) {
+    this.clientName = componentProvider.settings.clientName;
+  }
+
+  initialize(): void {
+    // 与 Dart 保持一致，当前无初始化逻辑。
+  }
+
+  prepareAndCreateIpcRequest(options: {
+    toClient: string;
+    moduleName: string;
+    methodName: string;
+    arguments?: Array<unknown>;
+    onError?: IpcErrorCallback;
+  }): Request {
+    const {
+      toClient,
+      moduleName,
+      methodName,
+      arguments: args = [],
+      onError,
+    } = options;
+
+    const requestId = this.generateRequestId(
+      this.clientName,
+      toClient,
+      moduleName,
+      methodName,
+    );
+
+    if (onError) {
+      this.errorCallbacks.set(requestId, onError);
+    }
+
+    const ipcArgs: Array<unknown> = [];
+    const callbackMap: Map<string, IpcResponseCallback> = new Map();
+
+    for (let i = 0; i < args.length; i += 1) {
+      const arg = args[i];
+      let ipcArg = arg;
+
+      if (typeof arg === 'function') {
+        if (callbackMap.size === 0) {
+          this.responseCallbacks.set(requestId, callbackMap);
+        }
+
+        const callbackId = this.generateCallbackId(requestId, i);
+        ipcArg = callbackId;
+        callbackMap.set(callbackId, arg as IpcResponseCallback);
+      }
+
+      ipcArgs.push(ipcArg);
+    }
+
+    return new Request(
+      requestId,
+      this.clientName,
+      toClient,
+      moduleName,
+      methodName,
+      ipcArgs,
+    );
+  }
+
+  onResponse(response: Response): void {
+    const callbackMap = this.responseCallbacks.get(response.requestId);
+    if (response.finished) {
+      this.responseCallbacks.delete(response.requestId);
+      this.errorCallbacks.delete(response.requestId);
+    }
+
+    if (!callbackMap) {
+      logger.error('接收到响应消息但回调失败，callbackMap 为空！');
+      return;
+    }
+
+    const callback = callbackMap.get(response.callbackId);
+    if (!callback) {
+      logger.error('接收到响应消息但回调失败，callback 为空！');
+      return;
+    }
+
+    callback(response.response);
+  }
+
+  onError(error: Error): void {
+    logger.error(`接收到错误消息，error: ${String(error)}.`);
+
+    const errorCallback = this.errorCallbacks.get(error.requestId);
+    this.errorCallbacks.delete(error.requestId);
+    this.responseCallbacks.delete(error.requestId);
+
+    if (errorCallback) {
+      errorCallback(
+        new IpcError(error.code, error.message ?? undefined, error.userInfo ?? undefined),
+      );
+    }
+  }
+
+  private generateRequestId(
+    fromClient: string,
+    toClient: string,
+    moduleName: string,
+    methodName: string,
+  ): string {
+    const timestamp = new Date().toISOString();
+    const random = generateRandomString(6);
+    return `${fromClient}~${toClient}|${moduleName}@${methodName}|${timestamp}-${random}`;
+  }
+
+  private generateCallbackId(requestId: string, index: number): string {
+    if (requestId.length < 6) {
+      return `_$_mb_callback_$_[${index}]`;
+    }
+    const suffix = requestId.slice(-6);
+    return `_$_mb_callback_$_[${index}]-${suffix}`;
+  }
+}
+

package/src/moonbridge-ipc/client/internal/ipc/eventbus/ipc_event_bus.ts

@@ -0,0 +1,75 @@
+// 对应：
+// moonbridge-ipc-flutter/lib/client/internal/ipc/eventbus/ipc_event_bus.dart
+//
+// 实现 EventBus 接口的 IPC 事件总线类。
+
+import { IpcClientComponentProvider } from '../ipc_client_component_provider';
+import { EventBus, Subscriber } from '../../../types/ipc_event_bus';
+import { Event } from '../../../../general/message/event';
+import { IpcError } from '../../../../general/error/ipc_error';
+import { logger } from '../../../../utils/logger';
+
+export class IpcEventBus implements EventBus {
+  private readonly componentProvider: IpcClientComponentProvider;
+  private readonly subscriberMap: Map<string, Array<Subscriber>> = new Map();
+
+  constructor(componentProvider: IpcClientComponentProvider) {
+    this.componentProvider = componentProvider;
+  }
+
+  initialize(): void {
+    // 与 Dart 一致，当前无需额外初始化逻辑。
+  }
+
+  private get connectionManager() {
+    return this.componentProvider.connectionManager;
+  }
+
+  private get communicationAgent() {
+    return this.componentProvider.communicationAgent;
+  }
+
+  onEvent(event: Event): void {
+    const subscribers = this.subscriberMap.get(event.type);
+    if (subscribers) {
+      for (const subscriber of [...subscribers]) {
+        subscriber.onEvent(event);
+      }
+    }
+  }
+
+  register(subscriber: Subscriber): void {
+    const list = this.subscriberMap.get(subscriber.eventType) ?? [];
+    list.push(subscriber);
+    this.subscriberMap.set(subscriber.eventType, list);
+  }
+
+  unregister(subscriber: Subscriber): void {
+    const list = this.subscriberMap.get(subscriber.eventType);
+    if (!list) return;
+    const next = list.filter((s) => s !== subscriber);
+    if (next.length === 0) {
+      this.subscriberMap.delete(subscriber.eventType);
+    } else {
+      this.subscriberMap.set(subscriber.eventType, next);
+    }
+  }
+
+  async post(event: Event): Promise<void> {
+    this.connectionManager.connect(
+      (isConnected: boolean, error?: IpcError) => {
+        if (isConnected && !error) {
+          void this.communicationAgent.postEvent(event);
+        } else {
+          logger.fatal(
+            `发布 EventBus 事件时，与服务端的连接建立失败，error: ${String(
+              error,
+            )}`,
+          );
+        }
+      },
+      { autoLaunch: undefined },
+    );
+  }
+}
+

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

@@ -0,0 +1,28 @@
+/**
+ * IpcClientComponentProvider 的默认实现，与 Flutter RealMoonBridgeIpcClient 的组件装配顺序一致。
+ * 由本类统一 new 各 IPC 组件，调用方仅需提供 IpcClientSettings。
+ * 012 对齐说明：Flutter 仅有抽象接口 IpcClientComponentProvider，装配在 RealMoonBridgeIpcClient 构造函数内；
+ * JS 保留本实现类，RealMoonBridgeIpcClient 通过继承此类获得组件，装配顺序与 Flutter 一致，Bridge 不传 moduleFactories。
+ */
+
+import { IpcClientSettings } from '../settings/ipc_client_settings';
+import { IpcConnectionManager } from './connect/ipc_connection_manager';
+import { IpcRequestCoordinator } from './coordinator/ipc_request_coordinator';
+import { IpcCommunicationAgent } from './communication/ipc_communication_agent';
+import { IpcEventBus } from './eventbus/ipc_event_bus';
+import { IpcConnectionKeeper } from './keep/ipc_connection_keeper';
+import { IpcClientBridge } from '../bridge/ipc_client_bridge';
+
+/**
+ * 单一装配点：按 Flutter 顺序创建并初始化 ConnectionManager → RequestCoordinator →
+ * CommunicationAgent → EventBus → ConnectionKeeper → Bridge。
+ */
+export interface IpcClientComponentProvider {
+  readonly settings: IpcClientSettings;
+  readonly connectionManager: IpcConnectionManager;
+  readonly requestCoordinator: IpcRequestCoordinator;
+  readonly communicationAgent: IpcCommunicationAgent;
+  readonly ipcEventBus: IpcEventBus;
+  readonly connectionKeeper: IpcConnectionKeeper;
+  readonly bridge: IpcClientBridge;
+}