moonbridge-ts 0.5.0 → 0.6.0

package/README.md

@@ -1,303 +1,311 @@
 # moonbridge-ts
 
-基于 MoonBridge 通信协议的 TypeScript IPC 库，面向**仅支持 WebSocket 的环境**（如 WPS 加载项任务窗格、浏览器页面），与 moonbridge-ipc 服务端互通（不限制技术栈），实现稳定、统一 IPC 通信。
+基于 MoonBridge 通信协议的 TypeScript IPC 库，面向 WebSocket 场景（浏览器、WPS 加载项、Node）。
 
----
+## 1. moonbridge-ts 是什么？
 
-## 完全一致原则（与 Flutter 端对齐）
+`moonbridge-ts` 是 moonbridge IPC 的 TypeScript 实现，用于在不同进程/应用之间进行消息通信。
 
-本库以 **moonbridge-ipc-flutter** 的 `lib/` 为**唯一参考**，在以下维度与 Flutter 端保持**完全一致**，便于跨端维护与同一套心智模型：
+角色模型与 Flutter 版本一致：
 
-- **命名**：类名、方法名、枚举名、文件名、目录名与 Flutter 端一致（仅因语言规范导致的拼写风格可微调）。
-- **设计模式**：Flutter 使用的设计模式在 TS 端以相同方式体现；Flutter 用 class 则 TS 用 class，Flutter 用 enum 则 TS 用 enum。
-- **公开 API**：对外方法签名、参数语义、返回值约定与 Flutter 端对应抽象一致，使两端调用方式可互换理解。
-- **目录与层级**：目录结构、模块划分与 Flutter `lib/` 一致（如 `client/`、`general/encode`、`general/message`、`general/transport`），便于按相同路径在两端定位。
-- **平台封装例外**：仅在**平台能力差异**（如 WebSocket 的运行时 API 不同）时，底层实现可不同，但**对外暴露的 API（方法名、参数与语义）须与 Flutter 端抽象完全一致**（如 `TransportClient.connectWithServer()`、`sendData()`、`isClientConnected`、`onErrorAndClose()`）。
-- **实施顺序**：先**第一步**完全还原 `lib/general/`（encode、message、transport、config、error、lock、statistics、utils、app_launch），再**第二步**对齐 client/、extension/ 及根入口 index.ts。
+1. 客户端：发送请求、接收请求、处理回调、发布/订阅事件。
+2. 服务端：负责客户端注册、消息转发、会话建立、唤醒目标客户端。
 
-详见仓库内 `specs/001-moonbridge-js-full-1to1/` 下的规格与契约。
+当前 TS 版本传输层仅提供 WebSocket 通道（`ws://`）。
 
----
+角色环境限制：
 
-## 1. 是什么？
+1. `server` 角色需要监听端口，浏览器环境受限，`MoonBridgeIpcServer` 只能在 Node.js 环境使用。
+2. `client` 角色不需要监听端口，`MoonBridgeIpcClient` 可在 Node.js 和浏览器环境使用。
 
-**适用场景**：moonbridge-ts 面向**仅支持 WebSocket 的环境**（WPS 加载项任务窗格、浏览器页面），无法使用 Node Socket。与 Flutter 端差异：JS 无 Dart 反射、无 build_runner，模块通过 `@MoonBridgeModule` / `@MoonBridgeMethod` 装饰器在**运行时**注册到 MoonBridgeRegistry。
-
-moonbridge-ts 是 **MoonBridge IPC 在 TypeScript 侧的客户端与服务端实现**，与 Flutter 端「客户端 / 服务端」角色模型一致：
-
-- **客户端**：负责消息的发送与接收（本库实现**客户端**角色）。
-- **服务端**：由 NPC 侧 moonbridge-ipc-flutter 承担，负责消息的中转与分发（本库同时提供 **MoonBridgeIpcServer** 用于服务端场景）。
+## 2. 当前提供的能力
 
-可以类比为：每个"微信用户"是客户端，既能发消息也能收消息；微信服务器负责中转。本库相当于在 WPS 或浏览器里运行的"微信客户端"，通过 WebSocket 连接 NPC 的 MoonBridge IPC 服务端；同时也提供"微信服务器"能力供 NPC 端使用。
+1. 支持单应用/多应用跨进程通信（经 IPC 服务端转发）。
+2. 支持 Request/Response/Error 三类消息与回调链路。
+3. 支持消息拦截（`MessageInterceptor`）。
+4. 支持连接状态监听（`ConnectionObserver`）。
+5. 支持心跳保活（默认开启，默认 3000ms）。
+6. 支持客户端身份认证（服务端白名单 `ClientIdentityProvider`）。
+7. 支持自动唤醒目标应用（`autoLaunch` + `AppLauncher`）。
+8. 支持 1 对 1 指定客户端通信。
+9. 支持 EventBus 广播通信。
+10. 支持端口候选策略（`PortCandidateRule`，服务端按规则尝试绑定端口，客户端按规则尝试连接端口）。
+11. 支持 WPS 场景 deeplink 唤醒（`WpsAppLauncher`）。
 
----
+### 2.1 `PortCandidateRule` 作用说明
 
-## 2. 当前提供的能力
+`PortCandidateRule` 用于在端口不确定或端口可能被占用时，给 server/client 提供一致的端口尝试规则：
 
-### 2.1 客户端能力（MoonBridgeIpcClient）
+1. 服务端启动时，如果初始端口被占用，会按 `PortCandidateRule` 生成的有序端口列表继续尝试绑定，直到某个端口启动成功，或所有候选端口尝试完毕后启动失败。
+2. 客户端连接时，会按同一规则生成的有序端口列表依次尝试连接；每个端口都会执行连接和握手校验，直到连接并握手成功，或所有候选端口尝试完毕后连接失败。
+3. 该机制可避免“固定端口冲突导致整体不可用”，并确保 server 与 client 共享相同的端口探索顺序。
 
-- 基于 **WebSocket（ws）** 的传输层，与 Flutter 端 WebSocket 接入语义一致；wss 预留。
-- **握手与协议**：连接建立后发送 Handshake，校验对端为 MoonBridge IPC 服务后再进入会话。
-- **连接管理**：连接状态机（disconnected / connecting / connected / disconnecting）、有限次数重试与固定间隔（与 Flutter IpcConnectionManager 对齐）。
-- **发送请求并接收响应**：`messenger.postMessage(target, { args: [..., callback] })`，将回调作为 args 末位传入，服务端响应时调用 callback。
-- **接收对端请求**：`registerHandler(moduleName, methodName, handler)` 注册本地方法；对端发送 TYPE_NAME_REQUEST 时派发到 handler，参数中 callbackId 替换为 ResultCallback，业务调用 `callback.invoke(result)` 回写 TYPE_NAME_RESPONSE；未注册则回写 TYPE_NAME_ERROR。协议与 [contracts](../specs/001-moonbridge-js-receive-extensions/contracts/message-formats.md) 一致（仓库内路径）。
-- **心跳保活**：连接建立后按 `heartbeatIntervalMs`（默认 30s）发送 TYPE_NAME_PING；可配置 `heartbeatEnabled`、`heartbeatIntervalMs`。
-- **EventBus**：`client.getEventBus().register(eventName, callback)` 订阅，`client.postEvent(type, source?, data?)` 发布；收到 TYPE_NAME_EVENT 时按事件名派发。
-- **可配置**：serverAddress、serverPort、path、clientName、heartbeatIntervalMs、heartbeatEnabled 等，与 Flutter 端配置概念一致。
+## 3. API 设计概览
 
-### 2.2 服务端能力（MoonBridgeIpcServer）
+### 客户端（`MoonBridgeIpcClient`）
 
-- 基于 **WebSocket（ws）** 的服务端接收与分发。
-- **客户端身份管理**：支持客户端身份认证（ClientIdentity），记录连接客户端信息。
-- **消息派发**：根据 clientName、moduleName、methodName 派发到注册的 handler。
-- **响应回写**：支持同步响应和异步响应（通过 ResultCallback）。
-- **EventBus 事件分发**：收到 TYPE_NAME_EVENT 时向订阅者广播。
+- `MoonBridgeIpcClient.builder()`
+- `connect(onResult?)`
+- `disconnect()`
+- `isConnected()`
+- `messenger.call(target).args(...).onError(...).strategy(...).send()`
+- `rpcServiceFactory.createService(ServiceType, clientName?)`
+- `eventBus.register(subscriber)`
+- `eventBus.unregister(subscriber)`
+- `eventBus.post(event)`
 
-### 2.3 模块化能力（@MoonBridgeModule / @MoonBridgeMethod）
+### 服务端（`MoonBridgeIpcServer`）
 
-- 通过装饰器注册模块和方法，运行时自动注册到 MoonBridgeRegistry。
-- 支持 `BridgeModule` 基类，提供与 Flutter 端一致的模块抽象。
-- 支持方法拦截、日志等横切关注点。
+- `MoonBridgeIpcServer.builder()`
+- `start(): Promise<boolean>`
+- `stop(): Promise<void>`
+- `clientIdentityProviders([...])`
+- `messagePreprocessor(...)`
+- `onMessageReceived(...)`
+- `wakeAppInterceptor(...)`
 
-### 2.4 WPS 应用启动能力（WpsAppLauncher）
+### 传输层（与 Flutter 抽象保持一致）
 
-- 支持通过 AppLaunchIdentifier 启动 WPS 应用。
-- 支持应用安装路径查询和类型转换。
+`TransportClient` 统一接口：
 
----
+- `connectWithServer()`
+- `sendData(data)`
+- `onMessage(cb)`
+- `onErrorAndClose({ onError, onServerClose })`
+- `close()`
+- `isClientConnected`
 
-## 3. 架构与分层（与 Flutter lib/ 一一对应）
+## 4. 接入流程与示例
 
-与 moonbridge-ipc-flutter 保持**一致的分层与目录**，便于按相同路径在两端定位：
+### 4.1 安装
 
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│  moonbridge/              核心模块层                                        │
-│  ├── kernel/              Bridge、BridgeModule 核心抽象                    │
-│  ├── annotation/          @MoonBridgeModule、@MoonBridgeMethod 装饰器      │
-│  └── logger/              日志抽象                                         │
-├──────────────────────────────────────────────────────────────────────────┤
-│  moonbridge-ipc/          IPC 通信层                                       │
-│  ├── client/              IPC 客户端（MoonBridgeIpcClient）                │
-│  │   ├── internal/        内部实现（连接管理、桥接、执行器等）               │
-│  │   └── types/           客户端类型定义                                    │
-│  ├── server/              IPC 服务端（MoonBridgeIpcServer）                │
-│  │   └── credential/      客户端身份认证                                   │
-│  ├── general/             通用层（与 Flutter lib/general 对应）            │
-│  │   ├── encode/          IpcMessageEncoder 消息编码                      │
-│  │   ├── message/         消息类型常量、负载类型                           │
-│  │   └── error/           IpcError 与错误码                               │
-│  └── extension/           扩展能力                                         │
-├──────────────────────────────────────────────────────────────────────────┤
-│  wps-launcher/            WPS 应用启动层                                   │
-│  └── launcher/            WpsAppLauncher 实现                             │
-└──────────────────────────────────────────────────────────────────────────┘
+```bash
+npm install moonbridge-ts
 ```
 
-- **moonbridge/**：对应 Flutter 端核心抽象，提供 Bridge、BridgeModule、装饰器等。
-- **moonbridge-ipc/client**：对应 Flutter `lib/client/`，对外暴露 `MoonBridgeIpcClient`。
-- **moonbridge-ipc/server**：对应 Flutter 服务端实现，对外暴露 `MoonBridgeIpcServer`。
-- **moonbridge-ipc/general**：对应 Flutter `lib/general/`，协议常量与编解码。
-- **wps-launcher/**：对应 Flutter `lib/app_launch/`，WPS 应用启动能力。
-
----
-
-## 4. 目录结构
-
-```text
-moonbridge-ts/
-├── src/
-│   ├── moonbridge/              # 核心模块层
-│   │   ├── kernel/
-│   │   │   ├── bridge.ts       # Bridge 抽象
-│   │   │   ├── bridge_module.ts # BridgeModule 基类
-│   │   │   ├── result_callback.ts # 结果回调
-│   │   │   └── executor.ts     # 执行器
-│   │   ├── annotation/
-│   │   │   ├── decorators.ts  # @MoonBridgeModule、@MoonBridgeMethod
-│   │   │   └── registry.ts     # MoonBridgeRegistry
-│   │   ├── message/            # 消息解析
-│   │   ├── module/             # 模块创建与方法调用
-│   │   ├── logger/
-│   │   │   └── logger.ts       # 日志抽象
-│   │   └── index.ts            # 对外导出
-│   ├── moonbridge-ipc/         # IPC 通信层
-│   │   ├── client/
-│   │   │   ├── moonbridge_ipc_client.ts  # 客户端入口
-│   │   │   ├── internal/       # 内部实现
-│   │   │   │   ├── bridge/     # 桥接与执行
-│   │   │   │   ├── ipc/        # IPC 核心
-│   │   │   │   └── settings/   # 配置
-│   │   │   └── types/          # 类型定义
-│   │   ├── server/
-│   │   │   ├── moonbridge_ipc_server.ts  # 服务端入口
-│   │   │   ├── credential/     # 客户端身份
-│   │   │   └── internal/       # 内部实现
-│   │   ├── general/
-│   │   │   ├── encode/         # 消息编码
-│   │   │   ├── message/        # 消息类型
-│   │   │   └── error/          # 错误定义
-│   │   ├── extension/         # 扩展
-│   │   └── index.ts            # 对外导出
-│   ├── wps-launcher/           # WPS 应用启动
-│   │   ├── launcher/
-│   │   │   └── wps_app_launcher.ts
-│   │   └── index.ts            # 对外导出
-│   └── index.ts                # 根入口
-├── tests/
-│   ├── unit/
-│   └── integration/
-├── docs/
-│   ├── ROADMAP.md
-│   ├── REFACTOR_SCOPE.md
-│   └── STRUCTURE.md
-├── DEPENDENCIES.md
-├── package.json
-└── README.md
-```
+### 4.2 初始化服务端（Node）
+
+```ts
+import {
+  MoonBridgeIpcServer,
+  WebSocketServerEndpoint,
+  ClientIdentity,
+} from 'moonbridge-ts';
 
----
+const endpoint = new WebSocketServerEndpoint({
+  address: '0.0.0.0',
+  port: 9091,
+  path: '/ws',
+  useTls: false,
+});
 
-## 5. 使用示例
+const getClientIdentity = (clientName: string) => {
+  switch (clientName) {
+    case 'client_a':
+      return new ClientIdentity('client_a');
+    case 'client_b':
+      return new ClientIdentity('client_b');
+    default:
+      return undefined;
+  }
+};
 
-### 5.1 安装
+const server = MoonBridgeIpcServer.builder()
+  .serverName('moonbridge_server')
+  .useWebSocketChannel(endpoint)
+  .clientIdentityProviders([getClientIdentity])
+  .build(true);
 
-```bash
-npm install moonbridge-ts
-# 或本地引用
-# "moonbridge-ts": "path:../moonbridge-ts"
+const started = await server.start();
+if (!started) {
+  throw new Error('IPC server start failed');
+}
 ```
 
-### 5.2 客户端初始化与连接
+### 4.3 初始化客户端
 
-```typescript
+```ts
 import {
-  MoonBridgeIpcClientBuilder,
+  MoonBridgeIpcClient,
   WebSocketServerEndpoint,
+  IpcMessageStrategy,
 } from 'moonbridge-ts';
 
-const client = MoonBridgeIpcClientBuilder.builder()
+const client = MoonBridgeIpcClient.builder()
   .clientName('client_a')
-  .useWebSocketChannel(new WebSocketServerEndpoint('127.0.0.1', 9100, '/ws'))
+  .useWebSocketChannel(
+    new WebSocketServerEndpoint({
+      address: '127.0.0.1',
+      port: 9091,
+      path: '/ws',
+      useTls: false,
+    }),
+  )
+  .messageStrategy(new IpcMessageStrategy(1, true))
   .build(true);
 
-client.connect((success, error) => {
-  if (success) console.log('连接成功');
-  else console.error('连接失败', error);
+client.connect((isConnected, error) => {
+  if (isConnected) {
+    console.log('connect success');
+    return;
+  }
+  console.error('connect failed', error);
 });
 ```
 
-### 5.3 发送消息
-
-```typescript
-// 极简调用：仅传核心定位 + 参数
-client.messenger.postMessage(
-  { clientName: 'client_b', moduleName: 'Printer', methodName: 'print' },
-  ['hello']
-);
-
-// 完整调用：传定位 + 全量配置（含 args、strategy、onError）
-client.messenger.postMessage(
-  { clientName: 'npc', moduleName: 'explainPage', methodName: 'call' },
-  {
-    args: [{ slide: 1, docPath: '/path/to.pptx' }, (res) => console.log(res)],
-    onError: (err) => console.error(err),
+### 4.4 客户端接收消息（模块方式）
+
+```ts
+import {
+  Bridge,
+  BridgeModule,
+  MoonBridgeMethod,
+  MoonBridgeModule,
+  ResultCallback,
+} from 'moonbridge-ts';
+
+@MoonBridgeModule('CallPhone')
+export class CallModule extends BridgeModule {
+  constructor(bridge: Bridge) {
+    super(bridge);
   }
-);
-```
 
-### 5.4 模块实现（宿主侧）
+  @MoonBridgeMethod('callWithCallback')
+  callWithCallback(phoneNumber: string, callback: ResultCallback): void {
+    console.log(`[MoonBridge] call: ${phoneNumber}`);
+    callback.invoke(['callback - Success']);
+  }
+}
+```
 
-```typescript
-import { BridgeModule } from 'moonbridge-ts';
-import { Bridge } from 'moonbridge-ts';
-import { MoonBridgeModule, MoonBridgeMethod } from 'moonbridge-ts';
+`tsconfig.json` 需开启：
 
-@MoonBridgeModule('Printer')
-class PrintModule extends BridgeModule {
-  constructor(bridge: Bridge) { super(bridge); }
-  @MoonBridgeMethod('print')
-  printMessage(msg: string) { console.log('[MoonBridge] print', msg); }
+```json
+{
+  "experimentalDecorators": true,
+  "emitDecoratorMetadata": true,
+  "useDefineForClassFields": false
 }
 ```
 
-**装饰器配置**（tsconfig.json）：`"experimentalDecorators": true`，必要时 `"useDefineForClassFields": false`。
+### 4.5 客户端发送消息
 
-### 5.5 服务端示例
+```ts
+// 方式：call（推荐）
+client.messenger
+  .call({ clientName: 'client_b', moduleName: 'CallPhone', methodName: 'callWithCallback' })
+  .args('0431-4610123', (response) => console.log('response:', response))
+  .onError((error) => console.error('ipc error:', error))
+  .send();
+```
 
-```typescript
-import { MoonBridgeIpcServerBuilder, WebSocketServerEndpoint } from 'moonbridge-ts';
+### 4.6 EventBus（订阅与发布）
 
-const server = MoonBridgeIpcServerBuilder.builder()
-  .serverName('moonbridge_server')
-  .useWebSocketChannel(new WebSocketServerEndpoint('0.0.0.0', 9100, '/ws'))
-  .build();
+```ts
+import { Subscriber } from 'moonbridge-ts';
+import { Event } from 'moonbridge-ts/moonbridge-ipc/general/message/event';
 
-server.start((success, error) => {
-  if (success) console.log('服务端启动成功');
-  else console.error('服务端启动失败', error);
+const subscriber = new Subscriber('TestEvent', (event) => {
+  console.log('event:', event.type, event.data);
 });
-```
 
-### 5.6 在 WPS 加载项中集成
+client.eventBus.register(subscriber);
+await client.eventBus.post(new Event('TestEvent', 'client_a', { key: 'hello' }));
+```
 
-1. 构建本库：`npm install && npm run build`，得到 `dist/`（含 CJS、ESM、IIFE）。
-2. 在任务窗格页面中引入 IIFE：`<script src="path/to/index.global.js"></script>`，会暴露 `window.MoonbridgeJS`（含 `MoonBridgeIpcClientBuilder`、`WebSocketServerEndpoint` 等）。
-3. 使用仓库内 `wps-addin/src/ipc/moonbridge/client.js` 提供的 `createNpcClient()`，内部会读取 `getConfig()` 的 npcWsUrl/npcWsPort 并组装 WebSocket 通道。
-4. 端口与地址需按环境配置（见 `window.getConfig()` 或 `__NPC_LINK_CONFIG__`），避免误用固定配置。
-5. 为「连接」「讲解当前页」「发送消息」等按钮绑定 `createNpcClient().connect()`、`client.messenger.postMessage(...)` 即可。
+### 4.7 WPS 场景唤醒（可选）
 
-详见仓库根目录下 `specs/005-moonbridge-js-ipc/quickstart.md`。
+```ts
+import {
+  MoonBridgeIpcClient,
+  WebSocketServerEndpoint,
+  WpsAppLauncher,
+} from 'moonbridge-ts';
 
----
+const client = MoonBridgeIpcClient.builder()
+  .clientName('client_a')
+  .useWebSocketChannel(
+    new WebSocketServerEndpoint({
+      address: '127.0.0.1',
+      port: 9091,
+      path: '/ws',
+      useTls: false,
+    }),
+  )
+  .appLauncher(
+    new WpsAppLauncher({
+      appUrl: 'server://',
+      fallbackMethod: 'linkClick',
+    }),
+  )
+  .build();
+```
 
-## 6. 与 moonbridge-ipc-flutter 的对应关系
+### 4.8 RPC 风格调用（装饰器 + rpcServiceFactory）
 
-| Flutter 端                        | moonbridge-ts                      |
-| --------------------------------- | ---------------------------------- |
-| MoonBridgeIpcClient               | MoonBridgeIpcClient                |
-| MoonBridgeIpcServer               | MoonBridgeIpcServer                |
-| IpcConnectionManager              | IpcConnectionManager               |
-| TransportClient / WebSocketClient | ITransportClient / WebSocketClient |
-| Handshake、Request/Response 协议  | general/encode、general/message    |
-| 连接重试、握手超时                | connection_manager + retry_policy  |
-| ClientIdentity                    | ClientIdentity                     |
-| ResultCallback                    | ResultCallback                     |
+```ts
+import {
+  IpcCallRetry,
+  IpcRemoteCall,
+  IpcRemoteClient,
+  IpcRequestJob,
+  MoonBridgeIpcClient,
+} from 'moonbridge-ts';
 
-报文格式与 Flutter 端对齐，详见 **docs/ROADMAP.md** 与特性契约 `specs/001-moonbridge-js-receive-extensions/contracts/message-formats.md`。客户端身份与动态端口为可选扩展，见 ROADMAP。
+@IpcRemoteClient({ name: 'client_b' })
+abstract class CallPhoneService {
+  @IpcCallRetry({ retries: 3 })
+  @IpcRemoteCall({ module: 'CallPhone', method: 'callPhone' })
+  callPhone(_number: string): IpcRequestJob {
+    return IpcRequestJob.stub();
+  }
 
----
+  @IpcRemoteCall({ module: 'CallPhone', method: 'callWithCallback' })
+  callPhoneWithCallback(_number: string, _onResponse: (response: unknown[]) => void): IpcRequestJob {
+    return IpcRequestJob.stub();
+  }
+}
 
-## 7. 开发与测试
+const client = MoonBridgeIpcClient.builder()
+  .clientName('client_a')
+  // ...省略 useWebSocketChannel(...)
+  .build(true);
 
-```bash
-npm install
-npm run build      # 产出 dist/
-npm run test       # 单元测试（Vitest）
-npm run lint       # ESLint
-npm run format     # Prettier
-```
+const service = client.rpcServiceFactory.createService(CallPhoneService);
 
----
+service?.callPhone('11111').onIpcError((error) => {
+  console.error('IPC error:', error);
+}).send();
 
-## 8. 注意事项
+service?.callPhoneWithCallback('176****0000', (response) => {
+  console.log('response:', response);
+}).onIpcError((error) => {
+  console.error('IPC error:', error);
+}).send();
+```
 
-- 仅使用 **ws**，未实现 wss；与当前 Flutter 端保持一致。
-- 客户端身份与鉴权与 Flutter 端一致：基于 clientName 及可选的 ClientIdentity，无 Token/Cookie。
-- 本库**实现客户端和服务端**，客户端连接 NPC（moonbridge-ipc-flutter），服务端可供 NPC 或其他客户端连接。
+## 5. 与 Flutter README 的对齐点
 
----
+1. 角色模型一致：客户端负责收发，服务端负责转发与会话构建。
+2. Builder 使用方式一致：链式配置后 `build(...)`。
+3. 协议语义一致：握手、注册、请求、响应、错误、心跳、事件。
+4. 模块能力一致：`@MoonBridgeModule` + `@MoonBridgeMethod`。
+5. 客户端身份机制一致：服务端白名单控制可接入客户端。
 
-## 9. 规范与约定（贡献与维护）
+## 6. 重要差异与注意事项
 
-**本项目不做向后兼容，只保留最新方案。** 方案升级或更新时，不保留废弃实现、无需考虑向后兼容，仅保留最新实现，以避免历史兼容逻辑堆积、降低维护成本。
+1. `MoonBridgeIpcServer` 只能在 Node.js 环境使用（浏览器无法监听端口）。
+2. `MoonBridgeIpcClient` 可在 Node.js 和浏览器环境使用（仅需主动连接，不需监听端口）。
+3. TS 端当前只支持 WebSocket，不支持 TCP Socket 客户端。
+4. `useTls: true`（`wss`）当前未实现，需使用 `ws`。
+5. 服务端如果不配置 `clientIdentityProviders`，客户端会因白名单校验失败而无法完成注册。
+6. 模块通过装饰器运行时注册，模块文件必须被加载（import）后才能生效。
+7. RPC 服务代理依赖装饰器元数据：服务类型需使用 `@IpcRemoteClient` 和 `@IpcRemoteCall` 标注后再通过 `client.rpcServiceFactory.createService(...)` 创建。
 
-moonbridge-ts 与 moonbridge-ipc-flutter 采用**一比一翻译**原则：命名、目录层级、对外 API 语义尽量一致；仅在平台能力差异（如 WebSocket 底层 API）时内部实现可不同，**对外暴露的 API 须与 Flutter 端抽象一致**。
+## 7. 开发命令
 
-- **与 Flutter 的详细对应**：见 [docs/STRUCTURE.md](docs/STRUCTURE.md)。
-- **单文件结构约定**（分区、`// IMPORTS`、`// CLASS: Xxx` 等）：见 [specs/001-moonbridge-js-refactor/contracts/file-structure.md](../specs/001-moonbridge-js-refactor/contracts/file-structure.md)。
-- **注释约定**（文件头、JSDoc、与 Flutter 对应注明）：见 [specs/001-moonbridge-js-refactor/contracts/comment-convention.md](../specs/001-moonbridge-js-refactor/contracts/comment-convention.md)。
-- **Flutter–JS 一比一对应约定**：见 [specs/001-moonbridge-js-refactor/contracts/flutter-js-1-to-1.md](../specs/001-moonbridge-js-refactor/contracts/flutter-js-1-to-1.md)。
-- **禁止顶层业务函数**：业务逻辑应封装在 class/interface 中；client/ 与 transport/ 不新增无归属的顶层函数（工厂等使用类静态方法，如 `ClientConfig.create`、`ResultCallback.create`、`RpcProxy.createService`）。协议层编解码过渡期可保留顶层函数，须在注释中标明与 Flutter 对应。
-- **查阅 specs 与 contracts**：仓库内 `specs/001-moonbridge-js-refactor/` 含本改造的 spec、plan、tasks、contracts；`contracts/` 下为单文件结构、注释、Flutter–JS 一比一约定。
-- **规范豁免**：自动生成代码（如未来 RPC 生成器产物）、对第三方 API 的极薄 wrapper 可豁免完整注释与分区规范，仅需文件头与对外入口简短说明；见 research.md 与 spec Edge Cases。
+```bash
+npm run build
+npm run test
+npm run lint
+```

package/dist/moonbridge-ipc/client/internal/moonbridge_ipc_client.internal.d.ts

@@ -1,11 +1,10 @@
 /**
  * MoonBridge IPC 客户端实际实现与注册表，对应 Flutter lib/client/internal/moonbridge_ipc_client.internal.dart。
- * JS 端不实现 RPC（getService 恒返回 undefined）。
  */
 import { IpcClientSettings } from './settings/ipc_client_settings';
 import { IpcConnectionCompletionHandler } from '../types/ipc_types';
 import { MoonBridgeIpcClient } from '../moonbridge_ipc_client';
-import { Messenger, MessageEndpoint, MessageCallOptions } from '../types/ipc_messenger';
+import { Messenger, MessageEndpoint, RoutedMessage } from '../types/ipc_messenger';
 import { EventBus } from '../types/ipc_event_bus';
 import { IpcClientComponentProvider } from './ipc/ipc_client_component_provider';
 import { IpcConnectionManager } from './ipc/connect/ipc_connection_manager';
@@ -14,6 +13,7 @@ import { IpcCommunicationAgent } from './ipc/communication/ipc_communication_age
 import { IpcEventBus } from './ipc/eventbus/ipc_event_bus';
 import { IpcConnectionKeeper } from './ipc/keep/ipc_connection_keeper';
 import { IpcClientBridge } from './bridge/ipc_client_bridge';
+import { RpcServiceFactory } from '../rpc/rpc_service_factory';
 /**
  * 实际 IPC 客户端实现：继承组件装配，并实现 MoonBridgeIpcClient、Messenger。
  * 装配顺序与 Flutter RealMoonBridgeIpcClient 一致；JS 不传入 moduleFactories（见 spec 012）。
@@ -26,6 +26,7 @@ export declare class RealMoonBridgeIpcClient implements IpcClientComponentProvid
     readonly ipcEventBus: IpcEventBus;
     readonly connectionKeeper: IpcConnectionKeeper;
     readonly bridge: IpcClientBridge;
+    readonly rpcServiceFactory: RpcServiceFactory;
     constructor(settings: IpcClientSettings);
     get clientName(): string;
     connect(onResult?: IpcConnectionCompletionHandler): void;
@@ -33,8 +34,8 @@ export declare class RealMoonBridgeIpcClient implements IpcClientComponentProvid
     isConnected(): boolean;
     get messenger(): Messenger;
     get eventBus(): EventBus;
-    postMessage(target: MessageEndpoint, argsOrOptions?: unknown[] | MessageCallOptions): void;
-    getService<T = unknown>(_clientName?: string): T | undefined;
+    call(target: MessageEndpoint): RoutedMessage;
+    private sendMessage;
     private realPostMessage;
 }
 //# sourceMappingURL=moonbridge_ipc_client.internal.d.ts.map

package/dist/moonbridge-ipc/client/internal/moonbridge_ipc_client.internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moonbridge_ipc_client.internal.d.ts","sourceRoot":"","sources":["../../../../src/moonbridge-ipc/client/internal/moonbridge_ipc_client.internal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,EAAE,8BAA8B,EAAoB,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAE,MAAM,6CAA6C,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,0BAA0B,EAAE,mBAAmB,EAAE,SAAS;IACxG,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,oBAAoB,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;IACnD,QAAQ,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;gBAIrB,QAAQ,EAAE,iBAAiB;IAsBvC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,OAAO,CAAC,QAAQ,CAAC,EAAE,8BAA8B,GAAG,IAAI;IAKlD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,WAAW,IAAI,OAAO;IAItB,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,WAAW,CACT,MAAM,EAAE,eAAe,EACvB,aAAa,CAAC,EAAE,OAAO,EAAE,GAAG,kBAAkB,GAC7C,IAAI;IAwBP,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAM5D,OAAO,CAAC,eAAe;CAqCxB"}
+{"version":3,"file":"moonbridge_ipc_client.internal.d.ts","sourceRoot":"","sources":["../../../../src/moonbridge-ipc/client/internal/moonbridge_ipc_client.internal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,EAAE,8BAA8B,EAAoB,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAE,MAAM,6CAA6C,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAA4B,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEzF;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,0BAA0B,EAAE,mBAAmB,EAAE,SAAS;IACxG,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,oBAAoB,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;IACnD,QAAQ,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;gBAIlC,QAAQ,EAAE,iBAAiB;IAuBvC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,OAAO,CAAC,QAAQ,CAAC,EAAE,8BAA8B,GAAG,IAAI;IAKlD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,WAAW,IAAI,OAAO;IAItB,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa;IAgB5C,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,eAAe;CAqCxB"}