Craft Agents WebUI适配层设计浏览器如何复用Electron渲染层【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agents 是一个开源 AI 智能体桌面应用其 WebUI 适配层的核心思路是让浏览器零重复地复用 Electron 渲染层的全部 UI 组件。这套适配层通过一个与桌面端同名的接口代理、一组构建期模块垫片shims把原本只能跑在 Electron 里的界面原封不动搬进了普通浏览器。本文带你快速看懂它的完整设计。一句话理解一套界面两种宿主Craft Agents 的界面由大量 React 组件构成它们运行在 Electron 的渲染进程中。但组件并不是直接调用桌面能力而是统一通过一个约定好的接口window.electronAPI访问系统功能——打开链接、选文件、发通知、切换工作区……WebUI 适配层apps/webui/src/adapter/web-api.ts做了一件非常聪明的事在浏览器里手工实现了同一个接口。它内部复用了桌面端的三件法宝WsRpcClientWebSocket RPC 客户端负责与无头headless服务器通信buildClientApi()根据通道映射表批量生成接口代理CHANNEL_MAP桌面端使用的方法名到 RPC 通道的映射表也就是说浏览器版与桌面版走的是同一套通信协议和同一套方法定义差异只发生在本地能力这一层。装配过程在组件挂载前注入假桌面 API入口文件 App.tsx 的初始化流程只有四步非常清晰通过 Cookie 认证向服务器请求/api/config拿到 WebSocket 地址调用createWebApi()创建接口代理和 WS 客户端在 Electron 组件挂载之前把代理挂到window.electronAPI连接 WebSocket再懒加载桌面端的App组件第 3 步是整个设计的卡点只要接口在渲染前就位Electron 渲染层里几百个组件就完全感知不到自己正运行在浏览器中。浏览器 ──▶ window.electronAPIWeb 适配层实现 │ 普通方法 → 直接走 WebSocket RPC 到服务器 └─ 本地方法 → 覆盖为浏览器等价实现构建期的障眼法Vite 别名 模块垫片浏览器里没有 Node.js怎么办vite.config.ts 用别名把问题挡在了构建期别名指向作用../electron/src/renderer直接复用 Electron 渲染层的组件、Hooks、页面wsshims/ws.ts改用浏览器原生 WebSocketelectron-log、sentry/electronshims/electron-log.ts、shims/sentry-electron.ts日志重定向到 console监控空操作fs、path、crypto等 Node 内建模块shims/node-builtins.ts提供最小可用的替身满足打包器静态分析垫片里大部分函数是空实现或调用即抛错——因为真正执行这些代码的路径在浏览器里根本走不到所有文件、进程操作都被适配层拦截后转成了 RPC 请求。垫片只是为了让打包器闭眼通过不增加运行时体积。开发体验同样被照顾到Vite 开发服务器会把/api、/ws代理到本地无头服务器默认 9100 端口还自动检测 TLS 证书改完代码热更新即生效。浏览器里的降级清单不是所有桌面能力都能在浏览器里等价实现。适配层用一张覆盖表webOverrides逐一处理策略分为三类浏览器等价物文件选择改用input typefile、通知改用 Web Notifications API、系统主题用matchMedia监听、剪贴板菜单映射到document.execCommand优雅降级craftagents://深链、跨服务器 RPC、自动更新等直接空操作或提示例如在新标签页打开会话替代在新窗口打开安全替代OAuth 授权采用预先打开空白弹窗的技巧——因为 iOS Safari 等严格的弹窗拦截器要求window.open()必须在点击事件内同步调用否则会静默失败认证Cookie 让浏览器免持令牌桌面端连接服务器要用 token浏览器端则更原生登录时服务器签发一个 24 小时有效的 JWT写入 HttpOnly Cookie实现见 auth.ts。之后每次 HTTP 请求和 WebSocket 升级请求都会自动带上这个 Cookie前端不需要管理任何令牌。会话过期时/api/config返回 401页面自动跳转到登录页。关键文件速查文件职责adapter/web-api.tsWebAPI 适配层主体接口实现 本地方法覆盖 OAuth 降级App.tsx引导流程取配置 → 建代理 → 注入接口 → 懒加载桌面 Appvite.config.ts路径别名、模块垫片映射、开发代理shims/五个浏览器垫片Node 内建、ws、日志、监控、openauth.ts服务器端 Cookie/JWT 会话认证docs/cli.md同一 WebSocket 协议的 CLI 客户端参考文档总结为什么这套设计值得学Craft Agents 的 WebUI 适配层展示了接口先行架构的收益当渲染层只依赖抽象接口而不依赖 Electron 本身时把应用搬进浏览器只需要三样东西——一个同接口的实现、一份构建期垫片、一张本地能力降级表。UI 代码一行不改维护成本几乎减半。如果你也在做多端桌面 Web产品这个模式非常值得借鉴。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考