moonbridge-ts 0.1.0

package/dist/wps-launcher/launcher/wps_app_launcher.js

@@ -0,0 +1,83 @@
+'use strict';
+
+var app_launch_models = require('../../moonbridge-ipc/general/app_launch/model/app_launch_models');
+var logger = require('../../moonbridge-ipc/utils/logger');
+
+const ALL_FALLBACK_METHODS = ["linkClick", "locationHref", "iframe", "windowOpen"];
+const TRY_ALL_INTERVAL_MS = 300;
+class WpsAppLauncher {
+  constructor(options) {
+    var _a, _b;
+    this.appUrl = options.appUrl;
+    this.fallbackMethod = (_a = options.fallbackMethod) != null ? _a : "linkClick";
+    this.tryAllMethods = (_b = options.tryAllMethods) != null ? _b : false;
+  }
+  async launchApp() {
+    try {
+      if (typeof this.appUrl !== "string" || !this.appUrl.includes("://")) {
+        logger.logger.warn("[WPS-Launcher] appUrl \u683C\u5F0F\u5FC5\u987B\u542B ://");
+        return new app_launch_models.AppLaunchResult(false, "appUrl \u683C\u5F0F\u5FC5\u987B\u542B ://");
+      }
+      if (this.tryAllMethods) {
+        for (let i = 0; i < ALL_FALLBACK_METHODS.length; i++) {
+          if (i > 0) await new Promise((r) => setTimeout(r, TRY_ALL_INTERVAL_MS));
+          this.runFallback(ALL_FALLBACK_METHODS[i], this.appUrl);
+        }
+      } else {
+        this.runFallback(this.fallbackMethod, this.appUrl);
+      }
+      return new app_launch_models.AppLaunchResult(true);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      logger.logger.error(`[WPS-Launcher] launchApp \u5F02\u5E38: ${msg}`);
+      return new app_launch_models.AppLaunchResult(false, msg);
+    }
+  }
+  triggerByLinkClick(appUrl) {
+    const a = document.createElement("a");
+    a.href = appUrl;
+    a.style.display = "none";
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  }
+  triggerByLocationHref(appUrl) {
+    window.location.href = appUrl;
+  }
+  triggerByIframe(appUrl) {
+    const iframe = document.createElement("iframe");
+    iframe.style.display = "none";
+    iframe.src = appUrl;
+    document.body.appendChild(iframe);
+    setTimeout(() => {
+      if (iframe.parentNode) document.body.removeChild(iframe);
+    }, 1e3);
+  }
+  triggerByWindowOpen(appUrl) {
+    window.open(appUrl);
+  }
+  runFallback(method, appUrl) {
+    switch (method) {
+      case "linkClick":
+        logger.logger.info(`[WPS-Launcher] \u4F7F\u7528 \u6A21\u62DF\u94FE\u63A5\u70B9\u51FB appUrl=${appUrl}`);
+        this.triggerByLinkClick(appUrl);
+        break;
+      case "locationHref":
+        logger.logger.info(`[WPS-Launcher] \u4F7F\u7528 location.href appUrl=${appUrl}`);
+        this.triggerByLocationHref(appUrl);
+        break;
+      case "iframe":
+        logger.logger.info(`[WPS-Launcher] \u4F7F\u7528 \u9690\u85CF iframe appUrl=${appUrl}`);
+        this.triggerByIframe(appUrl);
+        break;
+      case "windowOpen":
+        logger.logger.info(`[WPS-Launcher] \u4F7F\u7528 window.open appUrl=${appUrl}`);
+        this.triggerByWindowOpen(appUrl);
+        break;
+    }
+  }
+}
+
+exports.WpsAppLauncher = WpsAppLauncher;
+//# sourceMappingURL=wps_app_launcher.js.map
+//# sourceMappingURL=wps_app_launcher.js.map

package/dist/wps-launcher/launcher/wps_app_launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/wps-launcher/launcher/wps_app_launcher.ts"],"names":["logger","AppLaunchResult"],"mappings":"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","file":"wps_app_launcher.js","sourcesContent":["/**\n * WPS 加载项专属的 AppLauncher 实现。\n * 使用 electron.shell.openExternal 或多种 fallback（模拟链接点击、location.href、iframe、window.open）触发 deeplink；\n * 不包含 WPS.ShowTip、引导下载页等业务层能力，由 wps-addin 负责。\n */\n\nimport type { AppLauncher } from '../../moonbridge-ipc/general/app_launch/app_launcher';\nimport { AppLaunchResult } from '../../moonbridge-ipc/general/app_launch/model/app_launch_models';\nimport { logger } from '../../moonbridge-ipc/utils/logger';\n\n/**\n * fallback 触发方式：模拟链接点击、location.href、隐藏 iframe、window.open \n */\nexport type FallbackMethod = 'linkClick' | 'locationHref' | 'iframe' | 'windowOpen';\n\n/**\n * WpsAppLauncher 的配置项。\n * 仅包含唤起所需参数；用户反馈（WPS.ShowTip、引导下载页）由 wps-addin 业务层负责。\n */\nexport interface WpsAppLauncherOptions {\n  /**\n   * 完整的 Deeplink URL，格式必须为 scheme + \"://\" + \"xxx\"（xxx 可选）。\n   * 例如：server:// 或 server://link?source=wps。\n   * 强制要求：`://` 必须存在，调用方传入什么就使用什么，不做二次加工。\n   */\n  appUrl: string;\n  /**\n   * electron 不可用时使用的 fallback 方式。默认 linkClick（模拟链接点击，多数 WebView 允许）。\n   * 可切换为 locationHref、iframe、windowOpen 用于测试。\n   */\n  fallbackMethod?: FallbackMethod;\n  /**\n   * 为 true 时依次执行 linkClick、locationHref、iframe、window.open（间隔 300ms），用于调试。\n   * 会多次触发 scheme，仅用于验证哪种方式在 WPS WebView 中有效。\n   */\n  tryAllMethods?: boolean;\n}\n\ndeclare global {\n  interface Window {\n    electron?: {\n      shell?: {\n        openExternal: (url: string) => void;\n      };\n    };\n  }\n}\n\nconst ALL_FALLBACK_METHODS: FallbackMethod[] = ['linkClick', 'locationHref', 'iframe', 'windowOpen'];\nconst TRY_ALL_INTERVAL_MS = 300;\n\n/**\n * WPS 加载项专属的 AppLauncher 实现。\n */\nexport class WpsAppLauncher implements AppLauncher {\n  private readonly appUrl: string;\n  private readonly fallbackMethod: FallbackMethod;\n  private readonly tryAllMethods: boolean;\n\n  constructor(options: WpsAppLauncherOptions) {\n    this.appUrl = options.appUrl;\n    this.fallbackMethod = options.fallbackMethod ?? 'linkClick';\n    this.tryAllMethods = options.tryAllMethods ?? false;\n  }\n\n  async launchApp(): Promise<AppLaunchResult> {\n    try {\n      if (typeof this.appUrl !== 'string' || !this.appUrl.includes('://')) {\n        logger.warn('[WPS-Launcher] appUrl 格式必须含 ://');\n        return new AppLaunchResult(false, 'appUrl 格式必须含 ://');\n      }\n      if (this.tryAllMethods) {\n        for (let i = 0; i < ALL_FALLBACK_METHODS.length; i++) {\n          if (i > 0) await new Promise((r) => setTimeout(r, TRY_ALL_INTERVAL_MS));\n          this.runFallback(ALL_FALLBACK_METHODS[i], this.appUrl);\n        }\n      } else {\n        this.runFallback(this.fallbackMethod, this.appUrl);\n      }\n      return new AppLaunchResult(true);\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : String(e);\n      logger.error(`[WPS-Launcher] launchApp 异常: ${msg}`);\n      return new AppLaunchResult(false, msg);\n    }\n  }\n\n  private triggerByLinkClick(appUrl: string): void {\n    const a = document.createElement('a');\n    a.href = appUrl;\n    a.style.display = 'none';\n    document.body.appendChild(a);\n    a.click();\n    document.body.removeChild(a);\n  }\n\n  private triggerByLocationHref(appUrl: string): void {\n    window.location.href = appUrl;\n  }\n\n  private triggerByIframe(appUrl: string): void {\n    const iframe = document.createElement('iframe');\n    iframe.style.display = 'none';\n    iframe.src = appUrl;\n    document.body.appendChild(iframe);\n    setTimeout(() => {\n      if (iframe.parentNode) document.body.removeChild(iframe);\n    }, 1000);\n  }\n\n  private triggerByWindowOpen(appUrl: string): void {\n    window.open(appUrl);\n  }\n\n  private runFallback(method: FallbackMethod, appUrl: string): void {\n    switch (method) {\n      case 'linkClick':\n        logger.info(`[WPS-Launcher] 使用 模拟链接点击 appUrl=${appUrl}`);\n        this.triggerByLinkClick(appUrl);\n        break;\n      case 'locationHref':\n        logger.info(`[WPS-Launcher] 使用 location.href appUrl=${appUrl}`);\n        this.triggerByLocationHref(appUrl);\n        break;\n      case 'iframe':\n        logger.info(`[WPS-Launcher] 使用 隐藏 iframe appUrl=${appUrl}`);\n        this.triggerByIframe(appUrl);\n        break;\n      case 'windowOpen':\n        logger.info(`[WPS-Launcher] 使用 window.open appUrl=${appUrl}`);\n        this.triggerByWindowOpen(appUrl);\n        break;\n    }\n  }\n}\n"]}

package/dist/wps-launcher/launcher/wps_app_launcher.mjs

@@ -0,0 +1,81 @@
+import { AppLaunchResult } from '../../moonbridge-ipc/general/app_launch/model/app_launch_models';
+import { logger } from '../../moonbridge-ipc/utils/logger';
+
+const ALL_FALLBACK_METHODS = ["linkClick", "locationHref", "iframe", "windowOpen"];
+const TRY_ALL_INTERVAL_MS = 300;
+class WpsAppLauncher {
+  constructor(options) {
+    var _a, _b;
+    this.appUrl = options.appUrl;
+    this.fallbackMethod = (_a = options.fallbackMethod) != null ? _a : "linkClick";
+    this.tryAllMethods = (_b = options.tryAllMethods) != null ? _b : false;
+  }
+  async launchApp() {
+    try {
+      if (typeof this.appUrl !== "string" || !this.appUrl.includes("://")) {
+        logger.warn("[WPS-Launcher] appUrl \u683C\u5F0F\u5FC5\u987B\u542B ://");
+        return new AppLaunchResult(false, "appUrl \u683C\u5F0F\u5FC5\u987B\u542B ://");
+      }
+      if (this.tryAllMethods) {
+        for (let i = 0; i < ALL_FALLBACK_METHODS.length; i++) {
+          if (i > 0) await new Promise((r) => setTimeout(r, TRY_ALL_INTERVAL_MS));
+          this.runFallback(ALL_FALLBACK_METHODS[i], this.appUrl);
+        }
+      } else {
+        this.runFallback(this.fallbackMethod, this.appUrl);
+      }
+      return new AppLaunchResult(true);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      logger.error(`[WPS-Launcher] launchApp \u5F02\u5E38: ${msg}`);
+      return new AppLaunchResult(false, msg);
+    }
+  }
+  triggerByLinkClick(appUrl) {
+    const a = document.createElement("a");
+    a.href = appUrl;
+    a.style.display = "none";
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  }
+  triggerByLocationHref(appUrl) {
+    window.location.href = appUrl;
+  }
+  triggerByIframe(appUrl) {
+    const iframe = document.createElement("iframe");
+    iframe.style.display = "none";
+    iframe.src = appUrl;
+    document.body.appendChild(iframe);
+    setTimeout(() => {
+      if (iframe.parentNode) document.body.removeChild(iframe);
+    }, 1e3);
+  }
+  triggerByWindowOpen(appUrl) {
+    window.open(appUrl);
+  }
+  runFallback(method, appUrl) {
+    switch (method) {
+      case "linkClick":
+        logger.info(`[WPS-Launcher] \u4F7F\u7528 \u6A21\u62DF\u94FE\u63A5\u70B9\u51FB appUrl=${appUrl}`);
+        this.triggerByLinkClick(appUrl);
+        break;
+      case "locationHref":
+        logger.info(`[WPS-Launcher] \u4F7F\u7528 location.href appUrl=${appUrl}`);
+        this.triggerByLocationHref(appUrl);
+        break;
+      case "iframe":
+        logger.info(`[WPS-Launcher] \u4F7F\u7528 \u9690\u85CF iframe appUrl=${appUrl}`);
+        this.triggerByIframe(appUrl);
+        break;
+      case "windowOpen":
+        logger.info(`[WPS-Launcher] \u4F7F\u7528 window.open appUrl=${appUrl}`);
+        this.triggerByWindowOpen(appUrl);
+        break;
+    }
+  }
+}
+
+export { WpsAppLauncher };
+//# sourceMappingURL=wps_app_launcher.mjs.map
+//# sourceMappingURL=wps_app_launcher.mjs.map

package/dist/wps-launcher/launcher/wps_app_launcher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/wps-launcher/launcher/wps_app_launcher.ts"],"names":[],"mappings":"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","file":"wps_app_launcher.mjs","sourcesContent":["/**\n * WPS 加载项专属的 AppLauncher 实现。\n * 使用 electron.shell.openExternal 或多种 fallback（模拟链接点击、location.href、iframe、window.open）触发 deeplink；\n * 不包含 WPS.ShowTip、引导下载页等业务层能力，由 wps-addin 负责。\n */\n\nimport type { AppLauncher } from '../../moonbridge-ipc/general/app_launch/app_launcher';\nimport { AppLaunchResult } from '../../moonbridge-ipc/general/app_launch/model/app_launch_models';\nimport { logger } from '../../moonbridge-ipc/utils/logger';\n\n/**\n * fallback 触发方式：模拟链接点击、location.href、隐藏 iframe、window.open \n */\nexport type FallbackMethod = 'linkClick' | 'locationHref' | 'iframe' | 'windowOpen';\n\n/**\n * WpsAppLauncher 的配置项。\n * 仅包含唤起所需参数；用户反馈（WPS.ShowTip、引导下载页）由 wps-addin 业务层负责。\n */\nexport interface WpsAppLauncherOptions {\n  /**\n   * 完整的 Deeplink URL，格式必须为 scheme + \"://\" + \"xxx\"（xxx 可选）。\n   * 例如：server:// 或 server://link?source=wps。\n   * 强制要求：`://` 必须存在，调用方传入什么就使用什么，不做二次加工。\n   */\n  appUrl: string;\n  /**\n   * electron 不可用时使用的 fallback 方式。默认 linkClick（模拟链接点击，多数 WebView 允许）。\n   * 可切换为 locationHref、iframe、windowOpen 用于测试。\n   */\n  fallbackMethod?: FallbackMethod;\n  /**\n   * 为 true 时依次执行 linkClick、locationHref、iframe、window.open（间隔 300ms），用于调试。\n   * 会多次触发 scheme，仅用于验证哪种方式在 WPS WebView 中有效。\n   */\n  tryAllMethods?: boolean;\n}\n\ndeclare global {\n  interface Window {\n    electron?: {\n      shell?: {\n        openExternal: (url: string) => void;\n      };\n    };\n  }\n}\n\nconst ALL_FALLBACK_METHODS: FallbackMethod[] = ['linkClick', 'locationHref', 'iframe', 'windowOpen'];\nconst TRY_ALL_INTERVAL_MS = 300;\n\n/**\n * WPS 加载项专属的 AppLauncher 实现。\n */\nexport class WpsAppLauncher implements AppLauncher {\n  private readonly appUrl: string;\n  private readonly fallbackMethod: FallbackMethod;\n  private readonly tryAllMethods: boolean;\n\n  constructor(options: WpsAppLauncherOptions) {\n    this.appUrl = options.appUrl;\n    this.fallbackMethod = options.fallbackMethod ?? 'linkClick';\n    this.tryAllMethods = options.tryAllMethods ?? false;\n  }\n\n  async launchApp(): Promise<AppLaunchResult> {\n    try {\n      if (typeof this.appUrl !== 'string' || !this.appUrl.includes('://')) {\n        logger.warn('[WPS-Launcher] appUrl 格式必须含 ://');\n        return new AppLaunchResult(false, 'appUrl 格式必须含 ://');\n      }\n      if (this.tryAllMethods) {\n        for (let i = 0; i < ALL_FALLBACK_METHODS.length; i++) {\n          if (i > 0) await new Promise((r) => setTimeout(r, TRY_ALL_INTERVAL_MS));\n          this.runFallback(ALL_FALLBACK_METHODS[i], this.appUrl);\n        }\n      } else {\n        this.runFallback(this.fallbackMethod, this.appUrl);\n      }\n      return new AppLaunchResult(true);\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : String(e);\n      logger.error(`[WPS-Launcher] launchApp 异常: ${msg}`);\n      return new AppLaunchResult(false, msg);\n    }\n  }\n\n  private triggerByLinkClick(appUrl: string): void {\n    const a = document.createElement('a');\n    a.href = appUrl;\n    a.style.display = 'none';\n    document.body.appendChild(a);\n    a.click();\n    document.body.removeChild(a);\n  }\n\n  private triggerByLocationHref(appUrl: string): void {\n    window.location.href = appUrl;\n  }\n\n  private triggerByIframe(appUrl: string): void {\n    const iframe = document.createElement('iframe');\n    iframe.style.display = 'none';\n    iframe.src = appUrl;\n    document.body.appendChild(iframe);\n    setTimeout(() => {\n      if (iframe.parentNode) document.body.removeChild(iframe);\n    }, 1000);\n  }\n\n  private triggerByWindowOpen(appUrl: string): void {\n    window.open(appUrl);\n  }\n\n  private runFallback(method: FallbackMethod, appUrl: string): void {\n    switch (method) {\n      case 'linkClick':\n        logger.info(`[WPS-Launcher] 使用 模拟链接点击 appUrl=${appUrl}`);\n        this.triggerByLinkClick(appUrl);\n        break;\n      case 'locationHref':\n        logger.info(`[WPS-Launcher] 使用 location.href appUrl=${appUrl}`);\n        this.triggerByLocationHref(appUrl);\n        break;\n      case 'iframe':\n        logger.info(`[WPS-Launcher] 使用 隐藏 iframe appUrl=${appUrl}`);\n        this.triggerByIframe(appUrl);\n        break;\n      case 'windowOpen':\n        logger.info(`[WPS-Launcher] 使用 window.open appUrl=${appUrl}`);\n        this.triggerByWindowOpen(appUrl);\n        break;\n    }\n  }\n}\n"]}

package/docs/REFACTOR_SCOPE.md

@@ -0,0 +1,53 @@
+# 本次改造范围（Refactor Scope）
+
+本清单供 001-moonbridge-js-refactor 各 Phase 对照使用，不修改业务行为，仅做注释、单文件分区、顶层函数收拢与文档更新。
+
+## 核心文件清单
+
+### client/
+
+- `src/client/config.ts`
+- `src/client/connection_manager.ts`
+- `src/client/event_bus.ts`
+- `src/client/handler_registry.ts`
+- `src/client/interceptors.ts`
+- `src/client/moonbridge_client.ts`
+- `src/client/result_callback.ts`
+- `src/client/retry_policy.ts`
+- `src/client/rpc_proxy.ts`
+- `src/client/types.ts`
+
+### transport/
+
+- `src/transport/ITransportClient.ts`
+- `src/transport/WebSocketClient.ts`
+
+### core/
+
+- `src/core/error_encoder.ts`
+- `src/core/event_encoder.ts`
+- `src/core/handshake.ts`
+- `src/core/ping_encoder.ts`
+- `src/core/request_encoder.ts`
+- `src/core/response_encoder.ts`
+- `src/core/types.ts`
+- `src/core/constants/callback.ts`
+- `src/core/constants/connection.ts`
+- `src/core/constants/handshake.ts`
+- `src/core/constants/index.ts`
+- `src/core/constants/message_types.ts`
+
+### utils/
+
+- `src/utils/logger.ts`
+- `src/utils/index.ts`
+
+### 入口
+
+- `src/index.ts`
+
+## 规范与契约引用
+
+- 单文件结构约定：`specs/001-moonbridge-js-refactor/contracts/file-structure.md`
+- 注释约定：`specs/001-moonbridge-js-refactor/contracts/comment-convention.md`
+- Flutter–JS 一比一对应：`specs/001-moonbridge-js-refactor/contracts/flutter-js-1-to-1.md`

package/docs/ROADMAP.md

@@ -0,0 +1,143 @@
+# moonbridge-js 与 moonbridge-ipc-flutter 能力差距与补全规划
+
+本文档对照 Flutter 端 README 与源码（含 `lib/client/internal/bridge/`），梳理 moonbridge-js 当前缺失能力，并给出分阶段补全建议，便于逐步对齐。
+
+---
+
+## 一、Flutter 端已提供且 README 中明确的能力（摘要）
+
+1. 单应用内跨进程 / 多应用进程间通信  
+2. IPC 消息拦截 / 校验  
+3. 连接状态心跳保活  
+4. 客户端身份认证  
+5. 非存活态应用主动唤醒  
+6. 1 对 1 指定路径通信  
+7. 1 对多广播方式通信  
+8. 动态分配 IP 及端口  
+9. RPC 方式调用  
+10. **WebSocket 传输**（已支持）  
+11. **客户端接收消息**：通过 `BridgeModule` + `methodsToExport()` 注册模块方法，对端 Request 到达后由 `IpcClientExecutor` 派发到对应模块方法执行，支持回调参数（ResultCallback）回写 Response  
+
+---
+
+## 二、moonbridge-js 当前已实现
+
+| 能力 | 说明 |
+|------|------|
+| WebSocket 传输 | 仅 ws；与 Flutter WebSocket 客户端语义一致 |
+| 握手 | 连接后 Handshake 请求/响应校验，确认对端为 MoonBridge IPC 服务 |
+| 连接状态机与重试 | 与 IpcConnectionManager 行为对齐（次数、间隔） |
+| 发送 Request、接收 Response | `call(moduleName, methodName, args)`，requestId 匹配 |
+| **接收 Request + 模块注册 + ResultCallback** | `registerHandler(moduleName, methodName, handler)`；对端请求派发到 handler，参数中 callbackId 替换为 ResultCallback，`invoke` 回写 TYPE_NAME_RESPONSE；未注册回写 TYPE_NAME_ERROR |
+| **心跳保活** | 连接建立后按 `heartbeatIntervalMs`（默认 30_000）发送 TYPE_NAME_PING；可配置 `heartbeatEnabled` |
+| **EventBus** | `getEventBus().register(eventName, cb)`、`postEvent(type, source?, data?)`；收到 TYPE_NAME_EVENT 按事件名派发 |
+| **消息拦截** | `getInterceptors().registerBeforeSend(fn)`、`registerAfterReceive(fn)`；发送前/接收后链，返回 false 或异常视为拒绝 |
+| **RPC 风格代理** | `createService(client, moduleName, methods)` 返回代理对象，方法调用转为 `client.call(module, method, args)` |
+| 连接状态订阅 | `onStateChange` |
+| 配置 | clientName、serverAddress、serverPort、path、heartbeatIntervalMs、heartbeatEnabled |
+
+---
+
+## 三、与 Flutter 对比所欠缺的能力（按优先级）
+
+### P0：接收对端 Request 与 BridgeModule 风格方法注册（核心缺口）
+
+**Flutter 行为简述**：
+
+- `IpcClientBridge` 继承 `Bridge`，持有 `IpcClientExecutor`、`ModuleCreator`、`MessageParserManager`。
+- 收到 `Request` 后，`IpcClientExecutor.invokeMethod`：解析为 `Message`，用 `moduleName` 从 `ModuleCreator.getModule(moduleName)` 取 `BridgeModule`，再按 `methodName` 从 `module.methodsToExport()` 取方法，参数中的回调 ID（如 `_\$_mb_callback_\$_...`）会转成 `ResultCallback`，执行方法后通过 `ResultCallback.invoke` 回写 `Response`。
+- `BridgeModule` 抽象：`methodsToExport(): Map<String, Function>`，即「模块名 → 方法名 → 可调用函数」。
+
+**moonbridge-js 现状**：
+
+- `registerHandler(moduleName, methodName, handler)` 为占位，未实现请求派发。
+- 未实现：收到 `TYPE_NAME_REQUEST` 后解析 `moduleName`/`methodName`/`arguments`、将回调参数转为「可发送 TYPE_NAME_RESPONSE 的 ResultCallback」、调用已注册 handler 并回写响应。
+
+**补全方向**：
+
+1. 在 client 层增加「模块注册表」：`Map<moduleName, Map<methodName, Handler>>`，由 `registerHandler` 写入；或引入与 Flutter 对齐的「ModuleFactory + BridgeModule」抽象（见下）。
+2. 在 `handleIncoming` 中识别 `TYPE_NAME_REQUEST`，解析 payload，根据 `moduleName`/`methodName` 查找 handler。
+3. 对 `arguments` 中形如 `_\$_mb_callback_\$_xxx` 的字符串，替换为 JS 侧的 `ResultCallback` 对象，其 `invoke(response, finished)` 会编码并发送 `TYPE_NAME_RESPONSE`。
+4. 调用 handler(...convertedArgs)，若有 ResultCallback 则由业务在适当时机调用 `callback.invoke(result)`。
+
+可选：引入与 Flutter 同名的概念（Bridge、Executor、ModuleCreator、BridgeModule、MethodInvoker），便于文档与跨端对照；若优先简化，可先实现「注册表 + Request 派发 + ResultCallback」的最小闭环。
+
+---
+
+### P1：心跳保活
+
+**Flutter**：心跳间隔可配置，通过 PING 等消息保活。  
+
+**JS**：当前无心跳。  
+
+**补全**：在 ConnectionManager 或独立 Keeper 中，连接成功后按配置间隔发送 PING（或 Flutter 端约定的心跳类型），并在一定时间内未收到响应时置为断开或触发重连。
+
+---
+
+### P2：EventBus（1 对多 / 事件广播）
+
+**Flutter**：`MoonBridgeIpcClient().eventBus.register(Subscriber(...))`、`eventBus.post(Event(...))`。  
+
+**JS**：未实现。  
+
+**补全**：在 client 层增加 EventBus：`register(eventName, callback)`、`post(event)`；收到 `TYPE_NAME_EVENT` 时反序列化并派发到已注册回调。发送事件则编码为 TYPE_NAME_EVENT 通过 transport 发出。
+
+---
+
+### P3：消息拦截 / 校验
+
+**Flutter**：消息拦截、校验扩展点。  
+
+**JS**：无。  
+
+**补全**：在发送/接收路径上增加拦截器链（如 beforeSend、afterReceive），可做校验、日志、修改报文等。
+
+---
+
+### P4：RPC 风格接口（注解 + 代码生成）
+
+**Flutter**：`@IpcRemoteClient`、`@IpcRemoteCall`、`@IpcCallRetry` + build_runner 生成 RpcServiceFactory，通过 `messenger.createService(CallPhoneService)` 得到代理，调用即发 Request。  
+
+**JS**：无代码生成，仅有 `call(moduleName, methodName, args)`。  
+
+**补全**：可后续做「手写或轻量代码生成」的 RPC 代理层：根据接口定义生成 `call('Module','method', args)` 的封装，便于业务类型安全调用；非必须与 Flutter 注解体系一致。
+
+---
+
+### P5：客户端身份认证与动态端口（可选）
+
+**Flutter**：ClientIdentity、服务端 clientIdentityProviders；端口候选规则等。  
+
+**JS**：当前仅 clientName，无结构化 ClientIdentity；端口为配置项，无动态尝试。  
+
+**补全**：若 NPC 端要求更严格身份或端口发现，再在 JS 侧增加 ClientIdentity 结构与端口候选尝试逻辑。**当前为可选**，按需实现。
+
+---
+
+### P6：非存活态应用唤醒（通常不适用 JS）
+
+**Flutter**：通过 App 路径 / Scheme 唤醒未启动的应用。  
+
+**JS**：运行在浏览器/WPS 内，无法直接唤醒本地 App，一般由用户或 NPC 端负责。可文档说明为「不适用」或「由宿主/产品侧解决」。
+
+---
+
+## 四、建议实施顺序（路线图）
+
+| 阶段 | 内容 | 产出 |
+|------|------|------|
+| **Phase 1** | 接收 Request + BridgeModule 风格注册 + ResultCallback | 与 Flutter 端「客户端接收消息并回写 Response」行为对齐，可被 NPC 主动调用 |
+| **Phase 2** | 心跳保活 | 长连接稳定性，与 Flutter 端能力一致 |
+| **Phase 3** | EventBus | 1 对多、事件订阅与发布 |
+| **Phase 4** | 消息拦截/校验、RPC 封装、身份与端口（按需） | 增强可观测性、易用性与部署灵活性 |
+
+**状态**：Phase 1～4 已实现（接收 Request、ResultCallback、心跳、EventBus、拦截器、RpcProxy.createService）；客户端身份与动态端口仍为可选，见上 P5。
+
+---
+
+## 五、本轮改造（001-moonbridge-js-refactor）
+
+- **目标**：结构与注释对齐、单文件分区规范、与 Flutter 一比一翻译（命名、目录映射、对外 API 一致）。
+- **原则**：moonbridge-js 以 moonbridge-ipc-flutter 为参考，命名与实现形态尽量一致；Flutter 用 class 则 TS 用 class；仅平台能力（如 WebSocket 底层 API）可内部实现不同，**对外 API 须与 Flutter 抽象一致**。
+- **已完成**：注释与文件头、单文件分区（// IMPORTS、// CLASS 等）、ClientConfig/ResultCallback/RpcProxy 类静态工厂、docs/STRUCTURE.md 映射表、README 规范与约定、规范豁免说明。
+- **可选后续**：core 编解码收拢为 IpcMessageEncoder 类静态方法、handshake 收拢为 Handshake 类静态方法；物理目录迁移（client/internal、general/encode 等）见 plan。

package/docs/STRUCTURE.md

@@ -0,0 +1,47 @@
+# Flutter ↔ moonbridge-js 结构与类名对应表
+
+本表实现 spec「一比一翻译」与 FR-004，便于从 Flutter 端定位到 JS 端实现。平台封装（如 WebSocket）对外 API 语义与 Flutter 一致，方法名按语言习惯可略有差异（见下表说明）。
+
+## 客户端层（client/）
+
+| Flutter（moonbridge-ipc-flutter） | moonbridge-js | 说明 |
+|----------------------------------|---------------|------|
+| `client/moonbridge_ipc_client.dart`（MoonBridgeIpcClient） | `src/client/moonbridge_client.ts`（MoonbridgeClient） | IPC 客户端入口 |
+| `client/internal/ipc/connect/ipc_connection_manager.dart`（IpcConnectionManager） | `src/client/connection_manager.ts`（ConnectionManager） | 连接状态机、重试、握手 |
+| `client/internal/bridge/`（IpcClientBridge, IpcClientExecutor） | 当前逻辑在 MoonbridgeClient / ConnectionManager 内；后续可拆为 `client/internal/bridge/` | 桥接与执行器 |
+| `client/types/`（IClientConfig、连接状态等） | `src/client/types.ts`、`src/client/config.ts`（ClientConfig.create） | 配置与类型 |
+| HandlerRegistry / ModuleCreator | `src/client/handler_registry.ts`（HandlerRegistry） | 模块/方法注册与派发 |
+| ResultCallback | `src/client/result_callback.ts`（ResultCallback.create、IResultCallback） | 跨端回调封装 |
+| EventBus | `src/client/event_bus.ts`（EventBus） | 事件订阅与发布 |
+| 拦截器 | `src/client/interceptors.ts`（Interceptors） | 发送前/接收后拦截 |
+| RPC 代理 / RpcServiceProxy | `src/client/rpc_proxy.ts`（RpcProxy.createService） | RPC 风格代理 |
+| RetryPolicy | `src/client/retry_policy.ts` | 重试策略 |
+
+## 协议层（core/ ↔ general/）
+
+| Flutter（general/） | moonbridge-js | 说明 |
+|---------------------|---------------|------|
+| `general/encode/ipc_message_encoder.dart`（IpcMessageEncoder） | `src/core/request_encoder.ts`、`response_encoder.ts`、`ping_encoder.ts`、`error_encoder.ts`、`event_encoder.ts` | Request/Response/Ping/Event/Error 编码；与 Flutter 类静态方法对应 |
+| `general/message/`（request、response、handshake、ping、event、error） | `src/core/types.ts`、`src/core/constants/message_types.ts` | 消息类型与常量 |
+| `general/.../handshake` | `src/core/handshake.ts` | 握手编码、解码、校验 |
+| `general/transport/interface/transport_client.dart`（TransportClient） | `src/transport/ITransportClient.ts`（ITransportClient） | 传输层抽象；语义一致：connect ↔ connectWithServer，send ↔ sendData，isConnected ↔ isClientConnected |
+| `general/transport/websocket/websocket_client.dart`（WebSocketClient） | `src/transport/WebSocketClient.ts`（WebSocketClient） | WebSocket 实现；对外 API 与 Flutter 一致（connect、send、close、onMessage、onError、onClose） |
+
+## 常量与类型
+
+| Flutter | moonbridge-js |
+|---------|---------------|
+| message types（TYPE_NAME_REQUEST 等） | `src/core/constants/message_types.ts`（MessageTypeName） |
+| Handshake 常量 | `src/core/constants/handshake.ts` |
+| 连接/重试常量 | `src/core/constants/connection.ts` |
+| Callback 前缀等 | `src/core/constants/callback.ts` |
+
+## 平台封装（WebSocket）对外 API 一致性
+
+- **Flutter**：`connectWithServer()`、`sendData(String)`、`onMessage(void Function(String))`、`onErrorAndClose({onError, onServerClose})`、`close()`、`isClientConnected`。
+- **JS**：`connect()`、`send(data)`、`onMessage(cb)`、`onError(cb)`、`onClose(cb)`、`close()`、`isConnected`。语义一一对应，方法名按语言习惯（如 `connect`/`send`）与 Flutter 命名等价。
+
+## 实施说明（001-moonbridge-js-refactor）
+
+- **目录**：当前采用「映射表 + 现有物理路径」；未做 client/internal/bridge、general/encode 等物理目录迁移，以降低单次 MR 风险。目标状态见 plan 与 contracts/flutter-js-1-to-1.md；若需物理重组，可后续分步执行。
+- **平台封装**：WebSocketClient、ITransportClient 对外方法名与语义已与 Flutter 端抽象一致，见上表。

package/package.json

@@ -0,0 +1,64 @@
+{
+    "name": "moonbridge-ts",
+    "version": "0.1.0",
+    "description": "MoonBridge IPC by WebSocket for node(server) and browser(client).",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        },
+        "./src/*": {
+            "types": "./dist/*.d.ts",
+            "import": "./dist/*.mjs",
+            "require": "./dist/*.js"
+        },
+        "./*": {
+            "types": "./dist/*.d.ts",
+            "import": "./dist/*.mjs",
+            "require": "./dist/*.js"
+        }
+    },
+    "scripts": {
+        "build": "tsup && npm run build:types",
+        "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+        "dev": "tsup --watch",
+        "lint": "eslint src --ext .ts",
+        "lint:fix": "eslint src --ext .ts --fix",
+        "format": "prettier --write \"src/**/*.ts\"",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "keywords": [
+        "moonbridge",
+        "ipc",
+        "websocket",
+        "wps"
+    ],
+    "author": "liang",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/node": "^20.10.0",
+        "@types/ws": "^8.18.1",
+        "@typescript-eslint/eslint-plugin": "^6.19.0",
+        "@typescript-eslint/parser": "^6.19.0",
+        "eslint": "^8.56.0",
+        "eslint-config-prettier": "^9.1.0",
+        "prettier": "^3.2.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.3.0",
+        "vitest": "^1.2.0"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "optionalDependencies": {
+        "ws": "^8.18.0"
+    },
+    "overrides": {
+        "esbuild": "^0.25.0"
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './moonbridge';
+export * from './moonbridge-ipc';
+export * from './wps-launcher';

package/src/moonbridge/annotation/decorators.ts

@@ -0,0 +1,109 @@
+/**
+ * MoonBridge 注解装饰器，对应 Flutter 中的模块 / 方法注解。
+ * 使用 TypeScript 装饰器在运行时向全局注册表写入元信息。
+ *
+ * 装饰器执行顺序：TypeScript 中方法装饰器先于类装饰器执行。
+ * 因此 @MoonBridgeMethod 执行时，@MoonBridgeModule 尚未注册类。
+ * 使用 pendingMethodRegistrations 缓存待注册方法，待 @MoonBridgeModule 执行时消费。
+ */
+
+/**
+ * 使用 @MoonBridgeModule 和 @MoonBridgeMethod 装饰器时，需要配置 tsconfig.json 如下：
+ * 
+ * ```json
+ * "experimentalDecorators": true,    // 必选：启用装饰器语法
+ * "emitDecoratorMetadata": true,     // 必选：启用装饰器元数据（如反射获取类型）
+ * "useDefineForClassFields": false,  // 必选：兼容装饰器与类字段（TS 3.7+ 建议配置）
+ * ```
+ */
+
+import { Bridge } from '../kernel/bridge';
+import { BridgeModule } from '../kernel/bridge_module';
+import { logger } from '../utils/logger';
+import { MoonBridgeRegistry } from './registry';
+
+// CONSTANTS
+
+/** 键：className；值：待注册方法列表。方法装饰器先于类装饰器执行，故需缓存。 */
+const pendingMethodRegistrations = new Map<
+  string,
+  Array<{ methodAlias: string; methodName: string }>
+>();
+
+// PUBLIC METHODS
+
+/**
+ * 模块装饰器，对应 Flutter 侧的模块 annotation。
+ * 用于声明某个类是可桥接模块，并绑定模块名。
+ *
+ * 约定：
+ * - 被装饰的类必须继承自 BridgeModule
+ * - 构造函数签名为 new (bridge: Bridge)
+ *
+ * - name: 模块名
+ *
+ * 执行时先 registerModule，再消费 pendingMethodRegistrations 中该类的待注册方法。
+ */
+export function MoonBridgeModule(name: string) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function (target: new (bridge: Bridge) => BridgeModule | any): void {
+    logger.info(`[MoonBridgeModule] 装饰器执行 moduleName=${name}`);
+    MoonBridgeRegistry.getInstance().registerModule(name, target);
+
+    // 消费方法装饰器写入的待注册项（方法装饰器先于类装饰器执行）
+    const className = target.name;
+    const pending = pendingMethodRegistrations.get(className);
+    if (pending) {
+      const registry = MoonBridgeRegistry.getInstance();
+      for (const { methodAlias, methodName } of pending) {
+        registry.registerMethod(name, methodAlias, { className, methodName });
+      }
+      pendingMethodRegistrations.delete(className);
+    }
+  };
+}
+
+/**
+ * 方法装饰器，对应 Flutter 侧的方法 annotation。
+ * 用于给方法声明对外暴露的别名。
+ *
+ * - name: 方法别名（可选）；未传时使用 propertyKey 作为别名
+ *
+ * 因方法装饰器先于类装饰器执行，若类尚未注册则写入 pendingMethodRegistrations，
+ * 待 @MoonBridgeModule 执行时消费。
+ */
+export function MoonBridgeMethod(name?: string) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function (target: any, propertyKey: string, _descriptor: PropertyDescriptor): void {
+    const clazz = target.constructor;
+    const className = clazz.name;
+    const methodAlias = name ?? propertyKey;
+    logger.info(`[MoonBridgeMethod] 装饰器执行 methodAlias=${methodAlias} propertyKey=${propertyKey}`);
+    const registry = MoonBridgeRegistry.getInstance();
+
+    // 根据 class 名称找到对应的 moduleName（类装饰器可能已执行）
+    let matchedModuleName = '';
+    for (const [moduleName, ctor] of registry.moduleCtorMap) {
+      if (ctor.name === className) {
+        matchedModuleName = moduleName;
+        break;
+      }
+    }
+
+    if (matchedModuleName) {
+      registry.registerMethod(matchedModuleName, methodAlias, {
+        className,
+        methodName: propertyKey,
+      });
+    } else {
+      // 类尚未注册，写入待注册缓存
+      let list = pendingMethodRegistrations.get(className);
+      if (!list) {
+        list = [];
+        pendingMethodRegistrations.set(className, list);
+      }
+      list.push({ methodAlias, methodName: propertyKey });
+    }
+  };
+}
+