DSH-X Electron 外壳完全解析:如何同时实现 Windows/macOS 双平台、内部标签页与托盘常驻

原创2026-10-28 22:22:351,450 阅读
文章标签:桌面应用插件系统AI 插件本地部署

DSH-X Electron 外壳完全解析:如何同时实现 Windows/macOS 双平台、内部标签页与托盘常驻

DSH-X 是 DeepSeek Harness 的轻量桌面启动器,Windows 与 macOS 两个平台的桌面端都跑在同一套 Electron 外壳上:一套代码管理启动项与多实例、版本、插件、整合包、MCP 和技能。本文带你拆解它的双平台窗口适配、Chromium 内部标签页、托盘常驻机制是怎么实现的,几乎不需要你懂任何代码也能看懂。

DSH-X 桌面启动器主界面与启动项列表

一套外壳,两个平台:目录结构与启动流程

整个外壳只有 6 个文件,全部位于 shell/ 目录,分工非常清晰:

文件 职责
shell/main.mjs 主进程:窗口、托盘、权限、退出流程
shell/tabs.mjs 内部标签页状态机(BrowserTabs)
shell/model.mjs 地址判定、托盘状态解析等纯函数
shell/pages.mjs 外壳自绘的本地提示页
shell/env.mjs 补 PATH、标记「外壳托管」环境变量
shell/preload.cjs 给页面注入 window.ipc 通道

启动顺序是:env.mjs 必须第一个被加载,它把自带的 node/ 目录排进 PATH 最前,并写入两个关键标记 DSH_APP_WINDOW=1 和 DSSHX_INTERNAL_TABS=1(对应 env.mjs#L24-L25)。管理服务(server.js)随后直接跑在主进程里,监听 http://127.0.0.1:<端口>/,主窗口加载的正是这个本地地址。

这里藏着一个体积优化:打包后的外壳不额外携带 Node.js,而是让 Electron 本体设置 ELECTRON_RUN_AS_NODE=1 后当 Node 用(推导逻辑在 platform.js#L33-L39),安装包直接省下 80MB 以上。

DSH-X 深色主题下的启动项列表

Windows 与 macOS 的差异,只体现在这几处

两个平台共用同一个 main.mjs,平台差异被压缩到几个常量里,源码里的注释把原因写得很明白(main.mjs#L26-L38):

窗口框架

  • macOS 保留系统「红绿灯」按钮,titleBarStyle: 'hidden' 让页面铺满窗口,红绿灯位置精确换算到 { x: 18, y: 15 }(main.mjs#L54-L59),与页面顶栏中线对齐;
  • Windows 用无边框窗口(frame: false),最小化 / 最大化 / 关闭三个按钮由页面自己画出来,拖动则靠 CSS 的 -webkit-app-region。

DSH-X 深色模式下的 macOS 风格界面

菜单与快捷键

  • macOS 必须有应用菜单,否则 ⌘Q、⌘C/⌘V 都不工作,外壳专门构建了一个精简菜单(main.mjs#L419-L443),其中「Quit」不走系统预设项,而是走和托盘相同的服务收尾流程;
  • Windows 干脆 Menu.setApplicationMenu(null),Ctrl+C/V 由 Chromium 自己处理。

其它小差异:Windows 设置 AppUserModelID 让任务栏能正确分组与弹通知;托盘图标尺寸 macOS 18pt、Windows 16px,给 2 倍图防止发糊(main.mjs#L65-L67)。

内部标签页:每个实例一块独立的 WebContentsView

DSH-X 最重要的体验是「内部标签页」:多个 dsh 实例不弹浏览器,直接在启动器窗口里像浏览器标签页一样切换。

DSH-X 内部标签页多实例界面

实现上有三个值得注意的设计:

  1. 不用 iframe。每个实例是一块独立的 WebContentsView,叠在管理页之上、菜单栏之下(tabs.mjs#L5-L12),既避开跨源嵌入限制,切换标签也不会重载会话、丢失正在输入的草稿。
  2. 带请求编号的呈现协议。标签条由管理页(public/internal-tabs.js)绘制,选中、拖拽排序都带递增编号;外壳只有收到「管理页画完了」的回执 present(serial) 之后才切换原生视图的可见性,切换全程不露出底层、不闪烁。快速连点产生的旧回执会被直接忽略。
  3. 崩溃自愈。旧版 WebKit 外壳的标签页会随机黑屏,迁移到 Chromium 后,标签页进程一旦崩溃(render-process-gone),外壳会重新导航回带启动 token 的认证地址而不是简单 reload(tabs.mjs#L221-L231),实例重启换了端口 / token 时标签页也会自动跟上新地址。

安全上同样收口:标签页里的链接,同源的自己接住,外部网页交给系统浏览器(main.mjs#L244-L270);远端页面不装预加载脚本,拿不到任何外壳通道,伪造不了标签页操作。

托盘常驻:关窗口不等于退出

DSH-X 的常驻体验来自三个环环相扣的机制:

① 关窗口只是隐藏。 主窗口的 close 事件被拦截为 hide()(main.mjs#L179-L184),独立 DSH 窗口同理。托盘还在、dsh 实例照常运行,从托盘、程序坞或任务栏再叫回来即可。

② 轮询 + 按需重建菜单。 外壳每 1.5 秒请求一次 /api/tray(纯文本 key=value 协议,服务端实现在 server.js#L5169-L5186),解析函数 parseTrayState 是纯函数、可用 node --test 直接测。菜单只在内容真正变化时才重建(对比 JSON 指纹,main.mjs#L462-L486),避免轮询把用户正展开的子菜单拆掉。

③ 每个启动项都有四个操作。 托盘子菜单为每个启动项列出「启动 / 打开 / 重启 / 停止」(model.mjs#L178-L195),按状态自动置灰;操作是后台请求,超时上限 2 分钟,失败时会把管理页叫出来并提示原因。平台差异只有一处:Windows 托盘左键点一下就叫回管理页(右键才是菜单),macOS 则遵循系统习惯弹菜单。

退出路径刻意收敛:⌘Q 和托盘「退出」都先请求 /api/quit 让管理服务收尾(停掉 dsh 子进程、通知页面),再放行窗口的 close 退出 Electron(main.mjs#L599-L614)。连系统直接结束进程的情况(注销、关机)也被 before-quit 拦下来走同一收尾,防止 dsh 子进程被遗留。

DSH-X 外观设置页:主题跟随系统与悬浮窗透明度

几个提升稳定性的细节

  • 单实例锁:第二次打开应用不会起新进程,而是把已有实例的窗口叫出来;端口被别的副本占用(EALREADY)时主动唤醒对方后安静退出(main.mjs#L125-L139)。
  • 最小权限:只有本机地址的麦克风 / 摄像头请求会弹出原生询问框,通知、定位等权限一律拒绝;复制诊断信息的剪贴板写入也单独放行(main.mjs#L540-L568)。
  • 下载接管:Electron 不像浏览器会自己保存文件,外壳接管 will-download,先问保存路径再写盘,并在页面提示结果(main.mjs#L574-L597)。
  • 深浅色跟随系统:监听 nativeTheme 的 updated 事件,外壳自绘的「实例已停止」提示页也会跟着重画。
  • 导航护栏:管理页的任何就地导航都会被拦下——外部链接交给系统浏览器,属于某个实例的链接按用户设置进内部标签或独立窗口(main.mjs#L302-L341)。

小结

DSH-X 的 Electron 外壳示范了一种「薄外壳、厚服务」的架构:所有业务逻辑都在本地服务里,外壳只负责窗口、标签、托盘这三件平台相关的事,因此 Windows 与 macOS 的打包物几乎零差别。如果你也在做跨平台桌面工具,这套「WebContentsView 标签 + 轮询式托盘 + 关窗不退出」的组合值得直接参考,完整实现见 shell/ 目录,迁移过程中的两个历史 bug 复盘可看 docs/electron-migration-bugs.md。

登录后查看全文
DSH-X