Craft Agents Electron IPC 设计解析：channel-map、codec 与 routed-client 协作原理

Craft Agents Electron IPC 设计解析channel-map、codec 与 routed-client 协作原理【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agents 是一款开源 AI Agent 桌面客户端其 Electron IPC 通信层由 channel-map.ts、codec.ts 与 routed-client.ts 三个模块协作实现channel-map 负责方法名 → IPC 通道的统一映射codec 负责消息信封的序列化与安全校验routed-client 则根据通道路由表把每次调用智能分流到本地或远程服务器。本文将带你从入门角度理解这套传输层的设计思路。为什么需要这样一套 IPC 传输层Electron 应用天然分为两个世界渲染进程Renderer你看到的界面运行 React 代码主进程Main/ 服务端真正执行会话、任务、文件等后端逻辑界面里每次点击发送消息、创建会话其实都是一次跨进程 RPC 调用。而 Craft Agents 还有一层更复杂的需求同一个工作区Workspace既可能跑在本机嵌入式服务上也可能跑在远程服务器上。这就意味着客户端必须回答一个问题这次调用到底该发给本地的服务器还是拥有当前工作区的服务器transport 目录下的三个核心模块就是围绕这个问题设计的。channel-map一张方法→通道的总目录打开 channel-map.ts你会看到一个结构清晰的CHANNEL_MAP对象比如getSessions→sessions:get拉取会话列表sendMessage→sessions:sendMessage发送消息onSessionEvent→session:event监听会话事件推送browserPane.create→browser-pane:create创建内嵌浏览器面板它的设计要点有三个单一事实来源Single Source of Truth所有方法到通道的映射只写在这一处由 build-api.ts 统一消费来生成类型安全的客户端 API避免各处散落魔法字符串。两种调用姿态invoke请求-响应式类似 Promise 调用与listener事件订阅式返回取消函数分别对应我要一个结果和我要持续听推送。通道命名规范通道字符串定义在 channels.ts 中按sessions:、tasks:、messaging:等域命名空间组织值本身是稳定的线上协议契约。 小技巧项目用 channel-map-parity.test.ts 做一致性测试确保映射表不会悄悄漂移。codec把消息变成安全信封RPC 消息并不只是随手JSON.stringify。真正的编解码实现在 server-core 的 codec.tsElectron 侧的 codec.ts 只是转发导出它解决三个问题问题解决方案二进制数据无法走纯 JSON递归遍历消息把Uint8Array编码为{ __craftRpcType: u8, base64: ... }再还原消息种类繁杂限定 7 种信封类型handshake、request、response、event、error 等恶意/损坏报文validateEnvelopeShape在反序列化后做结构校验不合格直接抛出Invalid envelope shape这套信封Envelope设计让握手、请求、响应、事件推送共用同一条 WebSocket 通道互不混淆——这是 IPC 协议能长期稳定演进的基础。routed-client真正的分流调度员 routed-client.ts 是整个协作链条的指挥官。它同时持有两个客户端实例localClient永远连接本机嵌入式 Electron 服务器workspaceClient连接当前工作区归属的服务器本地或远程路由规则只有一条LOCAL_ONLY 通道 → 一律走 localClient 其余通道 → 一律走 workspaceClient而哪些通道是 LOCAL_ONLY由 routing.ts 穷举声明LOCAL_ONLY约 200 个需要本地操作系统能力如菜单、Dock 徽章、自动更新、Git Bash 检测、内嵌浏览器面板REMOTE_ELIGIBLE约 150 个工作区内容相关如会话、任务、文件读写、消息网关更有意思的是注释里的一处细节file.READ_USER_ATTACHMENT被特意归入 LOCAL_ONLY——因为草稿里记录的附件路径是用户本机路径即使工作区在远程服务器上也必须由本地进程读取。这类边界 case 正是路由表的价值所在。切换工作区时的make-before-break当用户从一个工作区切换到另一个尤其本地 ↔ 远程之间routed-client 会拦截window:switchWorkspace的响应按需通过工厂函数创建新的远程客户端先在新客户端上重新订阅所有监听器再从旧客户端退订先接上新的、再断旧的确保事件零丢失透明改写参数中的工作区 ID本地 ID → 远程 ID让服务端能正确解析销毁不再需要的旧客户端并触发一次合成重连事件让界面刷新切换期间错过的数据。三者如何协作一次调用的完整旅程以发送一条消息为例数据流如下界面调用 window.craftAPI.sendMessage(...) │ ▼ buildClientApi 依据 CHANNEL_MAP 找到通道 sessions:sendMessage │ ▼ RoutedClient.invoke查路由表 → 非 LOCAL_ONLY → 交给 workspaceClient │ ▼ WsRpcClient 组装信封 → codec 序列化含二进制 base64 编码 │ ▼ WebSocket 送达目标服务器 → 处理 → response 信封返回 → 反序列化 形状校验三个模块各司其职channel-map 管去哪routed-client 管发给谁codec 管怎么传。想继续深入推荐这几个入口 通道命名契约packages/shared/src/protocol/channels.ts路由分类表packages/shared/src/protocol/routing.ts信封编解码实现packages/server-core/src/transport/codec.ts客户端 API 构建apps/electron/src/transport/build-api.ts传输层单元测试apps/electron/src/transport/tests/routed-client.test.ts小结Craft Agents 的 Electron IPC 设计给桌面应用开发者提供了一个很好的参考范式用声明式映射表替代散落的字符串用信封协议统一请求与事件用穷举路由表优雅化解本地 远程双服务器架构。理解 channel-map、codec 与 routed-client 三者的分工也就理解了现代桌面客户端如何把复杂通信变得简单可靠。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考