Linux 自愈宿主 Moritz230127/dsh-electron

DSH Electron — 官方 DeepSeek Harness Web UI 的稳定 Linux 宿主

非官方。 DeepSeek Harness（DSH）官方仅提供 Windows 和 macOS 桌面应用。
本项目提供缺失的 Linux 等价方案：一个自愈、版本解耦的宿主，加载官方、未经修改的 DSH Web UI。

- 联系方式：moritz001@163.com
- 仓库：
- 许可证：MIT（见 LICENSE）
- 状态：v0.1.0，已独立验证；见 docs/V0.2-HANDOFF.md 和 verification/REPORT.md

DSH Electron 不是 DSH 的分支。它从不修补前端，从不替换官方资源，也从不复制或改写你的 ~/.dsh 数据。它仅监管官方 dsh web 进程，并在沙箱窗口中显示官方 Web UI。

它解决了什么问题？

官方 DSH Web UI 通常以 dsh web 运行并在浏览器中显示。在 Linux 上，使用 Chrome 已安装的 PWA 窗口作为宿主存在实际问题：

- PWA 与日常浏览共享同一个浏览器进程、GPU 进程和资源预算；
- 它绕过了用户的浏览器包装器标志；
- 它没有监管器：渲染器/GPU 崩溃会留下空白窗口；
- DSH 是一个预览项目，变化很快，有时会发布损坏的版本。

DSH Electron 将关注点分离：

| 层 | 职责 |
| dsh web 子进程 | 官方服务器：配置文件、会话、插件、任务 |
| 监管器 | 生命周期、健康检查、已知良好回退、重启、日志 |
| Electron UI | 仅显示：沙箱化的官方 Web UI + 托盘 |
| systemd 用户单元 | 在登录时启动监管器，并在其死亡时重启 |

核心原则

1. 官方 Web UI 不受触碰窗口加载 dsh web 打印的真实回环 URL。没有前端补丁，没有注入脚本，没有修改的静态资源。
2. 生命周期分离 DSH 服务器和 Electron UI 是一个监管器下相互独立的子进程。关闭或崩溃 UI 不会停止任务；重启 DSH 不会杀死 UI。
3. 自愈 systemd 重启监管器。监管器以有界、窗口化的预算和指数退避重启 DSH 或 UI；它从不紧密循环。
4. 内部已知良好运行时回退在 DSH 运行时成功启动后，监管器会在本地为该运行时创建快照。如果新安装的 DSH 版本启动失败，它会自动回退到针对同一 ~/.dsh 的快照；用户看到的是正常的官方 UI，而不是回滚流程。
5. 零用户维护安装一次，登录时自动启动。DSH 更新会在下次宿主启动时被拾取；损坏的预览更新在内部处理。没有版本选择器，没有检查脚本，没有手动回滚命令。
6. 小兼容面宿主仅依赖 dsh web CLI 标志、stdout 上的就绪 URL 行、一个原子 URL 文件和官方 HTTP/WebSocket UI。它不导入 DSH 内部实现。

架构

systemd --user dsh-host.service (enabled, Restart=always)
└── supervisor (Node, no Electron import)
├── dsh web child (official server, random loopback port)
│ └── ready URL → $XDG_RUNTIME_DIR/dsh-host/current-url (0600)
│ $XDG_RUNTIME_DIR/dsh-host/status.json (0600)
└── Electron child (attach mode) (sandboxed official Web UI + tray)
└── polls current-url, loads/reloads the official UI

已知良好的快照和状态位于 $XDG_STATE_HOME/dsh-host/ 下（默认 ~/.local/state/dsh-host/）。~/.dsh 仍然是唯一的事实来源，且从不由此项目管理。

GUI 关闭 / 退出行为

- 关闭窗口会将其隐藏到托盘，并记录日志 main window hidden to tray; DSH host keeps running。DSH 任务在后台继续运行。
- 托盘菜单：显示 DSH / 重启 Harness / 隐藏界面（DSH 后台继续）。
- 要停止整个平台（supervisor + DSH + UI）：
systemctl --user stop dsh-host.service。

DSH 更新行为

1. 宿主从系统中启动当前已安装的 dsh。
2. 如果它成功就绪并保持稳定，该运行时会被快照为已知良好。
3. 如果新安装的运行时在就绪之前失败，supervisor 会记录该失败并改为启动已知良好的快照。
4. 后续成功的版本会自动成为新的已知良好快照。
5. 同版本快速路径可避免反复等待已知损坏的 DSH 版本。

supervisor 只能看到 dsh web CLI 及其就绪行。因此，DSH 更新通常无需对此宿主做任何更改；如果 CLI 契约发生变化，只需对 src/main/runtime/ready-url.js / src/host/supervisor.js 做小幅适配。

特性

- 官方 Web UI，零前端补丁
- 沙箱化渲染器：contextIsolation、nodeIntegration:false、sandbox:true，无 webViewTag
- 严格的导航和权限允许列表（音频媒体 + 剪贴板，仅限运行时源）
- 有界渲染器恢复（滚动 60 秒 / 3 次重载 / 5 秒冷却）
- GPU 回退阶梯：default → --disable-gpu-sandbox → --disable-gpu --disable-gpu-compositing
- 内部已知良好 DSH 运行时回退
- 原子性 0600 URL/状态文件
- systemd 用户单元、XDG 自启动/启动器集成、官方 DSH 托盘图标
- 对 niri/Wayland 友好的窗口规则（将窗口排除在全局模糊/透明度之外）
- Linux 打包：解压目录、AppImage、pacman 包

安装

前置条件

先安装官方 DSH CLI：

npm install -g @deepseek-ai/dsh

AUR 包（源码）

PKGBUILD 位于 aur/dsh-electron/PKGBUILD。它使用 npm ci 和 npm run package:dir 从 GitHub 发布 tarball 构建宿主，然后将其安装到 /opt/DSH Electron 下。

cd aur/dsh-electron
makepkg -si
systemctl --user enable --now dsh-host.service
该软件包还会安装一个用户 systemd 单元和一个桌面启动器。它并非由本仓库发布到官方 AUR；如有需要，用户必须使用自己的 AUR 账户提交（参见 aur/README.md）。

从源码构建

npm install --foreground-scripts
npm test
npm run package:dir
开发运行：
node scripts/run-dsh-host.js --app-root "$PWD"

打包产物

npm run package:dir → dist/linux-unpacked/
npm run package:linux → AppImage 和 pacman 包（在 Arch 上需要 libcrypt-compat 以供 electron-builder 的
fpm 使用；参见 packaging/electron-builder-notes.md）。

GitHub 发布版还附带 dsh-electron-0.1.0-1-x86_64.pkg.tar.zst，这是一个标准的 makepkg/pacman 包，在已验证的载荷之上安装 systemd 用户单元、启动器、官方 DSH 托盘图标和文档。

sudo pacman -U dsh-electron-0.1.0-1-x86_64.pkg.tar.zst
systemctl --user enable --now dsh-host.service

验证

npm test 当前通过 207/207 项测试。v0.2 功能集已由独立验证者使用真实 DSH 和
真实 Electron E2E 阶段（官方 UI 加载、UI 终止独立性、DSH 重启 + URL 刷新、已知良好回退、有界重启预算、打包后的附加/托管冒烟测试）进行验证。参见 verification/REPORT.md。

安全说明

- 监督进程、URL 文件和状态文件均为用户级，权限模式为 0600；UI 仅加载由官方服务器发布的回环 URL。
- DSH 服务器在临时端口（--port 0）上绑定 127.0.0.1。
- Electron 窗口阻止导航到运行时源和本地恢复页面之外的地址。
- 权限请求默认被拒绝；仅允许来自运行时源的显式音频媒体。
- 本项目从不读取或写入官方 dsh web 进程所拥有之外的任何凭据。

免责声明

DeepSeek Harness、DeepSeek 及相关标识归其各自所有者所有。这是一个独立的、非官方 Linux 宿主。官方 DSH Web UI 未经修改地加载，其仍为 DeepSeek Harness 项目的作品。

联系方式

邮箱：moritz001@163.com