@isdk/tool-electron 1.0.0

package/README.cn.md

@@ -0,0 +1,588 @@
+# @isdk/tool-electron
+
+> ✨ **Electron 原生 IPC 传输层 —— 为 `ToolFunc` 框架打造**
+> 通过 IPC 构建解耦、类型安全、实时的 Electron 应用，支持 RPC 工具调用和 Pub/Sub 事件总线。
+
+[🌐 English](./README.md) | 🇨🇳 中文文档
+
+[![npm version](https://img.shields.io/npm/v/@isdk/tool-electron.svg?style=flat-square)](https://www.npmjs.com/package/@isdk/tool-electron)
+[![Vitest Tests](https://img.shields.io/badge/tests-vitest-green?style=flat-square)](https://vitest.dev/)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-purple?style=flat-square)](LICENSE)
+
+```bash
+npm install @isdk/tool-electron
+```
+
+基于 [`@isdk/tool-func`](https://github.com/isdk/ai-tools) —— 定义可复用的、自文档化的函数工具。
+
+---
+
+## 📖 目录
+
+- [特点](#-特点)
+- [架构](#-架构)
+- [安全桥接模式](#-安全桥接模式)
+- [快速开始](#-快速开始)
+- [API 参考](#-api-参考)
+- [EventServer/EventClient 集成](#-eventservereventclient-集成)
+- [测试](#-测试)
+- [CI 集成](#-ci-集成)
+- [许可证](#-许可证)
+
+---
+
+## 🌟 特点
+
+与 `@isdk/tool-rpc` / `@isdk/tool-event` 配套使用。将业务逻辑定义一次为工具，然后在渲染进程中像调用本地方法一样调用它们——无需 HTTP。
+
+* ✅ **零网络开销** — 使用 Electron 原生 IPC
+* ✅ **RPC 工具调用** — 从渲染进程调用主进程定义的函数
+* ✅ **实时事件总线** — 双向 Pub/Sub，带自动会话管理
+* ✅ **统一的错误模型** — 通过 `@isdk/common-error`，服务端错误自动作为 `CommonError` 抛给客户端
+* ✅ **AbortSignal 支持** — 客户端可取消等待中的 IPC 调用
+* ✅ **安全桥接模式** — 所有传输类支持注入式桥接对象（`Bridge`、`ServerIpcMain`、`PubSubBridge`、`ServerPubSubIpcMain`），适配 `contextBridge`
+* ✅ **动态命名空间** — 通过 `apiUrl` 参数运行多个隔离的工具/事件总线
+* ✅ **URI Scheme 路由** — `apiUrl` 采用 URI 规范；`electron://` 路由到 IPC 传输层，`http://` 路由到 HTTP；`RpcTransportManager` 自动注册
+* ✅ **IPC 通道命名规范** — 所有通道基于命名空间自动生成，避免冲突
+
+---
+
+## 🔄 架构
+
+```mermaid
+graph LR
+    subgraph "主进程 (Main Process)"
+        A[IpcServerToolTransport] -->|ipcMain.handle| D[(IPC Channel)]
+        C[ElectronServerPubSubTransport] -->|ipcMain.on/send| D
+    end
+
+    subgraph "预加载脚本 (Preload — contextBridge)"
+        P["electronIpc.invoke/on/off/send"] -->|ipcRenderer| D
+    end
+
+    subgraph "渲染进程 (Renderer)"
+        F[IpcClientToolTransport] -->|bridge.invoke| P
+        G[ElectronClientPubSubTransport] -->|bridge.on/off/send| P
+    end
+```
+
+预加载脚本作为安全边界 —— 渲染进程永远不会直接 `import 'electron'`。
+
+### IPC 通道命名约定
+
+所有通道基于 `apiUrl` 命名空间自动生成：
+
+| 通道 | 模式 | 用途 |
+|------|------|------|
+| RPC 发现 | `{namespace}:discover` | 客户端获取服务端工具列表 |
+| RPC 调用 | `{namespace}:rpc` | 客户端调用服务端工具 |
+| PubSub 下行 | `pubsub-downstream:{namespace}` | 服务端 → 客户端事件推送 |
+| PubSub 上行 | `pubsub-upstream:{namespace}` | 客户端 → 服务端事件发送 |
+| PubSub 连接 | `pubsub-connect:{namespace}` | 客户端发起 PubSub 连接 |
+| PubSub 断开 | `pubsub-disconnect:{namespace}` | 客户端断开 PubSub 连接 |
+
+例如，`apiUrl = 'electron://my-app'` 会提取 `my-app` 作为命名空间，生成 `my-app:discover`、`my-app:rpc`、`pubsub-downstream:my-app` 等。
+
+---
+
+## 🔒 安全桥接模式
+
+当启用 `contextIsolation`（Electron 12 起默认开启）时，渲染进程无法直接访问 Node.js 或 Electron API。推荐的做法是：
+
+1. **预加载脚本** — 通过 `contextBridge` 暴露最小化的桥接对象
+2. **主进程** — 可选地注入自定义 `ipcMain` 对象用于测试
+3. **渲染进程** — 使用注入的桥接对象创建传输实例
+
+### 四种可注入桥接类型
+
+| 类型 | 描述 | 方法 | 用于 |
+|------|------|------|------|
+| `Bridge` | 客户端 RPC 桥接 | `invoke(channel, ...args): Promise<any>` | `IpcClientToolTransport` |
+| `ServerIpcMain` | 服务端 RPC 桥接 | `handle(channel, handler)`, `removeHandler(channel)` | `IpcServerToolTransport` |
+| `PubSubBridge` | 客户端 Pub/Sub 桥接 | `on(channel, listener)`, `off(channel, listener)`, `send(channel, ...args)` | `ElectronClientPubSubTransport` |
+| `ServerPubSubIpcMain` | 服务端 Pub/Sub 桥接 | `on(channel, listener)`, `removeAllListeners(channel?)` | `ElectronServerPubSubTransport` |
+
+### 预加载脚本
+
+预加载脚本是唯一能访问 `ipcRenderer` 的地方。只暴露所需的 API：
+
+```ts
+// preload.ts
+import { contextBridge, ipcRenderer } from 'electron';
+
+const electronIpc = {
+  invoke: (ch: string, ...args: any[]) => ipcRenderer.invoke(ch, ...args),
+  on: (ch: string, listener: (event: any, ...args: any[]) => void) => {
+    ipcRenderer.on(ch, listener);
+  },
+  off: (ch: string, listener: (event: any, ...args: any[]) => void) => {
+    ipcRenderer.removeListener(ch, listener);
+  },
+  send: (ch: string, ...args: any[]) => ipcRenderer.send(ch, ...args),
+};
+
+contextBridge.exposeInMainWorld('electronIpc', electronIpc);
+```
+
+---
+
+## 🚀 快速开始
+
+### 1. 主进程 (Server)
+
+```ts
+// main.ts
+import { ServerTools } from '@isdk/tool-rpc';
+import { EventServer } from '@isdk/tool-event';
+import {
+  IpcServerToolTransport,
+  ElectronServerPubSubTransport,
+} from '@isdk/tool-electron';
+
+// 注册一个工具
+ServerTools.register({
+  name: 'getUser',
+  func: async ({ id }: { id: string }) => ({ id, name: 'Alice' }),
+});
+
+// 挂载 RPC 传输层，命名空间 'my-app'
+const server = new IpcServerToolTransport({ apiUrl: 'electron://my-app' });
+server.addDiscoveryHandler('electron://my-app', () => ServerTools.toJSON());
+server.addRpcHandler('electron://my-app');
+await server.start();
+
+// 设置事件总线
+EventServer.setPubSubTransport(
+  new ElectronServerPubSubTransport('electron://my-app-events'),
+);
+EventServer.get()?.register();
+```
+
+> **测试提示：** 可以传入 mock `ipcMain` 对象：
+>
+> ```ts
+> const server = new IpcServerToolTransport({
+>   apiUrl: 'electron://test',
+>   ipcMain: { handle: () => {}, removeHandler: () => {} },
+> });
+> ```
+
+### 2. 预加载脚本
+
+见上方 [预加载脚本](#预加载脚本) 示例。暴露 `electronIpc` 桥接对象。
+
+### 3. 渲染进程 (Renderer)
+
+```ts
+// renderer.ts
+import {
+  IpcClientToolTransport,
+  type Bridge,
+} from '@isdk/tool-electron';
+
+const bridge: Bridge = (window as any).electronIpc;
+
+// 创建传输层，注入桥接对象
+const transport = new IpcClientToolTransport('electron://my-app', { bridge });
+
+// 加载工具定义
+await transport.loadApis();
+
+// 调用远程工具
+const result = await transport._fetch('getUser', { id: '42' });
+console.log(result); // { id: '42', name: 'Alice' }
+```
+
+### 4. 完整示例（RPC + Pub/Sub）
+
+**main.ts**
+
+```ts
+import { ServerTools } from '@isdk/tool-rpc';
+import {
+  IpcServerToolTransport,
+  ElectronServerPubSubTransport,
+} from '@isdk/tool-electron';
+
+ServerTools.register({
+  name: 'getUser',
+  func: async ({ id }: { id: string }) => ({ id, name: 'Alice' }),
+});
+
+const rpcServer = new IpcServerToolTransport({ apiUrl: 'electron://my-app' });
+rpcServer.addDiscoveryHandler('electron://my-app', () => ServerTools.toJSON());
+rpcServer.addRpcHandler('electron://my-app');
+await rpcServer.start();
+
+const pubSubServer = new ElectronServerPubSubTransport('electron://my-app-events');
+pubSubServer.listen();
+```
+
+**preload.ts** — 同上方的预加载脚本示例。
+
+**renderer.ts**
+
+```ts
+import {
+  IpcClientToolTransport,
+  ElectronClientPubSubTransport,
+  type Bridge,
+  type PubSubBridge,
+} from '@isdk/tool-electron';
+
+const bridge: Bridge = (window as any).electronIpc;
+const pubsubBridge: PubSubBridge = (window as any).electronIpc;
+
+const rpc = new IpcClientToolTransport('electron://my-app', { bridge });
+await rpc.loadApis();
+
+const pubsub = new ElectronClientPubSubTransport('electron://my-app-events', {
+  bridge: pubsubBridge,
+});
+const stream = pubsub.connect('electron://my-app-events');
+
+stream.on('server-event', (data) => {
+  console.log('收到事件:', data);
+});
+```
+
+---
+
+## 📦 API 参考
+
+### 类
+
+#### `IpcServerToolTransport`
+
+服务端 RPC 传输层。在 Electron 主进程中使用。
+
+```ts
+class IpcServerToolTransport extends ServerToolTransport {
+  constructor(options?: {
+    apiUrl?: string;          // IPC 通道 URI，默认 'electron://ai-tool'
+    dispatcher?: RpcServerDispatcher; // v2.6 调度器
+    ipcMain?: ServerIpcMain;  // 可注入的自定义 ipcMain
+  });
+
+  addDiscoveryHandler(apiPrefix: string, handler: () => any): void;
+  addRpcHandler(apiPrefix: string, options?: { registry?: any }): void;
+  start(): Promise<void>;
+  stop(force?: boolean): Promise<void>;
+  getRaw(): { ipcMain: ServerIpcMain; channels: Channels };
+}
+```
+
+**选项说明：**
+
+- `apiUrl` — IPC 通道 URI（`electron://` 格式），例如 `'electron://my-app'` 会提取命名空间 `my-app`，生成 `my-app:discover` 和 `my-app:rpc` 两个 IPC 通道
+- `ipcMain` — 可选的桥接对象，用于测试或自定义主进程 IPC 设置。不传时使用 `electron` 的 `ipcMain`
+- `dispatcher` — V2.6 执行调度器，用于并发隔离（影子实例）和任务追踪
+
+#### `IpcClientToolTransport`
+
+客户端 RPC 传输层。在 Electron 渲染进程中使用。
+
+```ts
+class IpcClientToolTransport extends ClientToolTransport {
+  constructor(
+    apiUrl?: string,          // IPC 通道 URI（electron:// 格式），默认 'electron://ai-tool'
+    options?: {
+      bridge?: Bridge;        // 可注入的桥接对象（配合 contextBridge）
+    },
+  );
+
+  setApiUrl(apiUrl: string): void;
+  loadApis(): Promise<Funcs>;
+  _fetch(name: string, args?: any, act?: any, subName?: any, fetchOptions?: any): Promise<any>;
+  toObject(res: any): Promise<any>;
+}
+```
+
+**错误处理：**
+`_fetch` 会在服务端返回错误时直接抛出 `CommonError`，无需手动调用 `toObject()`：
+
+```ts
+import { CommonError } from '@isdk/common-error';
+
+try {
+  const result = await transport._fetch('getUser', { id: 'invalid' });
+} catch (err: any) {
+  if (err instanceof CommonError) {
+    console.error(`错误 [${err.code}]: ${err.message}`, err.data);
+  }
+}
+```
+
+#### `ElectronServerPubSubTransport`
+
+服务端 Pub/Sub 传输层。
+
+```ts
+class ElectronServerPubSubTransport implements IPubSubServerTransport {
+  readonly name = 'electron';
+  readonly protocol = 'electron' as const;
+
+  constructor(
+    namespace: string,         // 必须：命名空间（支持 electron:// 格式），用于生成 IPC 通道
+    options?: {
+      ipcMain?: ServerPubSubIpcMain; // 可注入的自定义 ipcMain
+    },
+  );
+
+  listen(): void;              // 激活 IPC 监听器
+  connect(options?: { req: IpcMainEvent; res: WebContents; events?: string[] }): PubSubServerSession;
+  subscribe(session: PubSubServerSession, events: string[]): void;
+  unsubscribe(session: PubSubServerSession, events: string[]): void;
+  publish(event: string, data: any, target?: { clientId?: string | string[] }, ctx?: PubSubCtx): void;
+  cleanup(): void;
+  onConnection(cb: (s: PubSubServerSession) => void): void;
+  onDisconnect(cb: (s: PubSubServerSession) => void): void;
+  onMessage(cb: (session: PubSubServerSession, event: string, data: any, ctx?: PubSubCtx) => void): void;
+}
+```
+
+**注意：** `listen()` 必须在 `connect()` 被调用前调用一次。`cleanup()` 应在应用退出时调用。
+
+#### `ElectronClientPubSubTransport`
+
+客户端 Pub/Sub 传输层。
+
+```ts
+class ElectronClientPubSubTransport implements IPubSubClientTransport {
+  constructor(
+    apiRoot?: string,          // 命名空间（支持 electron:// 格式）
+    options?: {
+      bridge?: PubSubBridge;   // 可注入的桥接对象
+    },
+  );
+
+  setApiRoot(apiRoot: string): void;
+  connect(toolName: string, params?: any): PubSubClientStream;
+  disconnect(stream: PubSubClientStream): void;
+  cleanup(): Promise<void>;
+}
+```
+
+### 类型
+
+```ts
+// 客户端 RPC 桥接
+type Bridge = {
+  invoke: (channel: string, ...args: any[]) => Promise<any>;
+};
+
+// 服务端 RPC 桥接
+type ServerIpcMain = {
+  handle: (channel: string, handler: (event: any, ...args: any[]) => any) => void;
+  removeHandler: (channel: string) => void;
+};
+
+// 客户端 Pub/Sub 桥接
+type PubSubBridge = {
+  on: (channel: string, listener: (event: any, ...args: any[]) => void) => void;
+  off: (channel: string, listener: (event: any, ...args: any[]) => void) => void;
+  send: (channel: string, ...args: any[]) => void;
+};
+
+// 服务端 Pub/Sub 桥接
+type ServerPubSubIpcMain = {
+  on: (channel: string, listener: (event: any, ...args: any[]) => void) => void;
+  removeAllListeners: (channel?: string) => void;
+};
+
+// IPC 通道
+type Channels = {
+  discover: string;
+  rpc: string;
+};
+```
+
+### PubSub 流
+
+`connect()` 返回的 `PubSubClientStream` 对象：
+
+```ts
+interface PubSubClientStream {
+  clientId: string;
+  protocol: string;
+  readonly readyState: number; // 1 = OPEN, 2 = CLOSED
+
+  on(event: string, listener: (data: any, ctx?: PubSubCtx) => void): () => void;
+  off(event: string, listener: (data: any, ctx?: PubSubCtx) => void): void;
+  send(event: string, data: any, ctx?: PubSubCtx): void;
+  close(): void;
+}
+```
+
+---
+
+## 🔄 EventServer/EventClient 集成
+
+本包可与 `@isdk/tool-event` 的 `EventServer` / `EventClient` 配合使用，在 Electron IPC 上实现完整的事件总线。
+
+### 测试 Fixture 中的配置
+
+实际测试使用了**两套独立的传输层**（均使用 `electron://` URI 格式）：
+
+| 流程 | 传输命名空间 | 触发方式 |
+|------|-------------|----------|
+| 基础 PubSub | `electron://integration-test` | `publishEvent` RPC 工具 → `pubSubServer.publish()` |
+| EventClient | `electron://event-bus` | `eventPublish` RPC 工具 → `EventServer.publish()` |
+
+### 关键注意事项
+
+1. **`eventPublish` 必须调用 `EventServer.publish()`**，而不是 `pubSubServer.publish()`，否则 EventClient 收不到事件
+2. **`backendEventable` 会在回调中前置事件名参数**：`(eventName, data)` 而非 `(data)`
+3. **`forwardEvent` + `emit`** 经由上游 IPC 发送到服务端，服务端自动添加 `client:` 前缀
+4. **事件名称必须预先订阅**：服务端只在 `connect()` 时声明的 `events` 集合范围内过滤事件
+
+---
+
+## 🧪 测试
+
+### 单元测试（55 个）
+
+使用模拟的 Electron API，无需真实 Electron：
+
+```bash
+pnpm test           # 运行一次
+pnpm run test:watch # 监听模式
+```
+
+测试文件位于 `test/` 目录：
+
+- `test/namespaces.test.ts` — 命名空间规范化（含 electron:// URI 提取）
+- `test/ipc-transport.test.ts` — RPC 传输（含 URI scheme 测试）
+- `test/electron-pubsub.test.ts` — PubSub 传输
+- `test/event-server-client.test.ts` — EventServer/EventClient
+
+### 集成测试（13 个）
+
+使用 Playwright + 真实 Electron：
+
+```bash
+pnpm run test:integration
+```
+
+测试场景：
+
+| # | 场景 | 说明 |
+|---|------|------|
+| 1 | 桥接初始化 | 验证 bridge ready |
+| 2 | RPC 调用 | 简单的工具调用 |
+| 3 | RPC 对象参数 | 返回结构化数据的工具 |
+| 4 | RPC 错误 | 抛出 CommonError 的工具 |
+| 5 | 未知工具 | 不存在的工具返回 404 |
+| 6 | PubSub | 订阅 + 发布事件 |
+| 7 | 多窗口 RPC | 两个独立窗口并发调用 |
+| 8 | 多窗口 PubSub | 两个窗口顺序接收事件 |
+| 9 | 窗口关闭/重连 | 新建窗口，关闭旧窗口，验证新窗口 |
+| 10 | 并发 RPC | 15 个并行调用混合成功/错误/慢速 |
+| 11 | EventServer 订阅 | EventClient 接收 EventServer.publish() |
+| 12 | EventClient 转发 | forwardEvent + emit 到服务端 |
+| 13 | EventClient 发布 | publish() RPC 到服务端 |
+
+### 运行全部测试
+
+```bash
+pnpm run test:all  # 构建 + 55 个单元测试 + 13 个集成测试（共 68 个）
+```
+
+### 集成测试共享工具
+
+`test/integration/helpers.ts` 提供了以下共享函数：
+
+| 函数 | 用途 |
+|------|------|
+| `launchElectronApp(mainPath)` | 启动 Electron（`--no-sandbox --disable-gpu`） |
+| `captureConsole(page, logs)` | 捕获渲染进程日志 |
+| `printConsoleLogs(logs)` | 在 afterAll 中打印日志 |
+| `waitForBridge(page)` | 等待 `toolBridge.ready === true` |
+| `callTool(page, name, params)` | 调用 RPC 工具 |
+| `subscribeAndPublish(page, event, data)` | 原子化订阅 + 发布 |
+| `subscribeAndWait(page, event)` | 仅订阅 |
+| `createNewWindow(page, app)` | 通过 `createWindow` RPC 工具创建新窗口 |
+
+### 模板目录
+
+`test/template/electron-integration/` 包含可重用的集成测试模板，供本仓库中其他包快速上手。适配指南：
+
+```bash
+# 复制模板到你的 fixture 目录
+mkdir -p test/fixtures/electron-app
+cp test/template/electron-integration/*.cjs test/fixtures/electron-app/
+cp test/template/electron-integration/*.html test/fixtures/electron-app/
+cp test/template/electron-integration/electron.test.ts test/integration/
+cp test/template/electron-integration/vite.integration.config.mjs .
+```
+
+模板中的 `<<< CHANGE:` 标记指明了需要修改的位置。
+
+### 经验教训
+
+1. **`sandbox: false` 是必须的** — 否则 preload 脚本没有 `__dirname`
+2. **不要添加 `window-all-closed` → `app.quit()`** — 测试需要关闭和重开窗口
+3. **先创建新窗口，再关闭旧窗口** — 不要对已关闭的页面调用 `callTool`
+4. **PubSub 广播竞态** — 多窗口测试务必顺序执行 `subscribeAndPublish`
+5. **服务端订阅过滤** — 事件必须在 `connect()` 时声明的集合内
+6. **使用 `.cjs` 扩展名** — 因为 monorepo 根目录有 `"type": "module"`
+7. **在无头 Linux 上必须使用 `xvfb-run`**
+8. **EventServer 和 EventClient 使用独立的传输命名空间**
+
+---
+
+## 🤖 CI 集成
+
+`.github/workflows/ci.yml` 提供了 GitHub Actions CI 工作流：
+
+- Node 20 和 22 矩阵
+- `npx --yes playwright install-deps electron` 安装系统依赖
+- 单元测试（无需 xvfb）
+- 集成测试在 `xvfb-run --auto-servernum` 下运行
+- ESLint 检查
+- 超时限制 `timeout-minutes: 10`
+
+```yaml
+# 简化的 CI 核心步骤
+- uses: pnpm/action-setup@v4
+- run: pnpm install --frozen-lockfile
+- run: npx --yes playwright install-deps electron
+- run: pnpm run build-fast
+- run: pnpm test              # 55 个单元测试
+- run: xvfb-run --auto-servernum pnpm vitest run --config vite.integration.config.mjs  # 13 个集成测试
+```
+
+---
+
+## 📚 相关文档
+
+- [ToolFunc 核心](https://github.com/isdk/ai-tools/tree/main/packages/tool-func)
+- [RPC 传输指南](https://github.com/isdk/ai-tools/tree/main/packages/tool-rpc)
+- [事件系统指南](https://github.com/isdk/ai-tools/tree/main/packages/tool-event)
+- [PubSub 开发者指南](./pubsub.md)
+- [RPC 深度文档](./tool-rpc.md)
+
+---
+
+## 🤝 贡献
+
+欢迎贡献！
+
+1. Fork → `git clone`
+2. 创建分支 → `git checkout -b feat/your-feature`
+3. 提交 → `git commit -m 'feat: add XYZ'`
+4. 推送 → `git push origin feat/your-feature`
+5. 发起 PR 🎉
+
+请确保测试通过且类型检查无错误。
+
+---
+
+## 📜 许可证
+
+MIT © [ISDK](https://github.com/isdk) — 参见 [LICENSE](LICENSE)
+
+---
+
+> 💡 **小贴士**：使用 `EventServer.forward([...events])` 自动将全局事件中继给所有已连接的客户端！