桌面托盘外壳 hadbilen/dsh-desktop-shell

DSH 桌面外壳

托盘桌面外壳、桌面快捷方式和更新工具，专为 DeepSeek Harness（DSH）打造。

基于 DeepSeek Harness 构建。与 DeepSeek 无附属关系，也未获其背书。

功能一览

DSH 以浏览器 UI 形式发布。本项目让它在 Linux 上表现得像桌面应用：

| 功能 | 你能得到什么 |
| 桌面快捷方式 | 带图标的启动器条目——无需终端 |
| 托盘外壳 | QtWebEngine 窗口；关闭它（X）会隐藏到托盘而非退出 |
| 托盘菜单 | 显示/隐藏、重新加载、服务状态、应用内更新、Tailscale 远程开关与链接复制、真正退出 |
| 会话恢复 | 快捷方式会重新打开上次会话；DSH_NEW_CHAT=1（或 --new-chat）则改为启动干净的提示词会话并自动聚焦。干净会话开关需要托盘外壳——Chrome 回退窗口始终恢复上次会话 |
| systemd 服务 | dsh-web.service 让 DSH 独立于任何窗口持续运行 |
| 桌面通知 | 针对回合、提问和错误事件的系统通知 |
| 应用内更新 | 直接从 GUI 或通知一键检查并应用更新，带实时日志流和自动重新加载 |
| 更新命令行 | dsh-update——npm + GitHub release 渠道，自动备份与回滚，版本清理 |
| Tailscale 远程访问 | 按需启用的认证反向代理，托盘一键开关和链接分享 |

桌面通知

dsh-notify 插件（位于 notify/）会在以下情况发送系统通知：

- 回复完成——智能体结束一个回合
- 需要输入——智能体提问或等待批准
- 运行失败——智能体以错误结束

窗口聚焦时通知会被抑制，子代理会话默认排除，这样长任务不会刷屏。点击通知会把窗口带到前台。

开关在 General settings 页面编辑，位于 Notifications 行，每个偏好一个开关。（DSH 0.2 不会为插件命名空间渲染通用表单，所以插件自己绘制这一行——与 DSH 自带的 Appearance 和 session-log 行的做法相同。）改动立即生效，无需重新加载页面。在某个值被存储之前，下面的默认值持续生效：

| 设置 | 默认值 | 含义 |
| onComplete | true | 回复完成时通知 |
| onQuestion | true | 需要输入时通知 |
| onError | true | 失败时通知 |
| onlyWhenHidden | true | 窗口聚焦时保持安静 |
| includeSubagents | false | 子代理会话也通知 |
| sound | false | 播放系统通知音 |

存储的值位于配置档补丁（~/.dsh/profiles/web/cordis.patch.yml）中，作为条目的 config: 块——在 DSH 0.2 中该文件就是设置文档。手动编辑可行，但需要重启服务重启；设置行会实时应用更改。设置按配置档持久化，而页面通过 loopback 提供服务：浏览器若通过可选的 Tailscale 代理访问 DSH，只会得到仅内存的设置作用域，因此从远程设备所做的更改不会写入配置档。

环境要求

- Linux，且运行 systemd 用户会话
- node（标准 Node.js v20+，带 V8 引擎；注意，伪装成 node 的 Bun 不受 DSH 原生模块支持）以及 DSH 安装（@deepseek-ai/dsh）
- python3 3.10+
- 可选但推荐： python3-pyqt6.qtwebengine，用于托盘外壳。
没有它，启动器会退回到普通浏览器应用窗口。
- 可选： pnpm —— 仅通知插件和 dsh plugin 需要
- 可选： curl —— 只有浏览器窗口回退方案（dsh-app-window.sh）用它在打开窗口前探测服务；托盘外壳不需要

sudo apt install python3-pyqt6.qtwebengine
bun add -g pnpm # or: npm i -g pnpm

安装

git clone https://github.com/hadbilen/dsh-desktop-shell.git
cd dsh-desktop-shell
./install.sh

常用参数：

| 参数 | 作用 |
| --dry-run | 打印将要执行的操作；不做任何更改 |
| --no-services | 跳过 systemd 单元 |
| --no-plugin | 跳过通知插件 |
| --with-proxy | 同时启用远程访问代理（生成 token） |

所有使用方解析的 XDG 变量都与安装器一致（XDG_BIN_HOME、XDG_DATA_HOME、XDG_CONFIG_HOME、DSH_HOME），因此自定义布局绝不会把安装拆到两套路径下。若某个已在运行的单元仍持有先前加载的代码，安装器会明确提醒：enable --now 无法重启它，所以要运行 systemctl --user restart dsh-web.service dsh-proxy.service（重启 dsh-web.service 会结束任何进行中的智能体回合）。

安装器把文件复制到 XDG 目录，用你的真实路径填充 systemd 单元模板，启用服务，并把通知插件链接到你的 web 配置档 —— 包括安装该配置档的依赖树（dsh plugin --profile web install），正是这一步真正生成链接，并校验它修改的配置档补丁。

卸载

./uninstall.sh # removes this project's files
./uninstall.sh --purge # also removes local state and backups
./uninstall.sh --keep-plugin

两者都不会动你的 DSH 版本、会话或 DSH 配置档。--purge 会额外删除本项目自己的状态：更新日志和备份（~/.cache/dsh-update）、代理 token（~/.config/dsh/proxy.env），以及外壳创建的两个浏览器配置档（~/.local/share/dsh-tray、 ~/.local/share/dsh-app）—— 删除这些会让 Web UI 登出，所以下次启动时你得重新认证一次。

更新工具

dsh-update check # status: installed version, newest rc, stray copies
dsh-update ghcheck # official channels only; exit 0 current / 10 update / 1 error
dsh-update plan # describe what apply would do; changes nothing
dsh-update apply # move to the newest version, remove other copies
dsh-update prune # clean up without changing version
dsh-update extras # list DSH artifacts outside the main trees
dsh-update notify # desktop notification if an update exists (timer calls this)
dsh-update full # timer + cleanup + newest version + verify

apply 在动手之前会先备份整个 @deepseek-ai 包目录树，如果安装失败就自动还原，所以更新失败也不会让你失去 DSH。

默认的省心做法是一个 systemd --user 定时器，每天检查两次，有新版本就通知你。

apply 的退出码：0 = 安装成功且干净，2 = 安装成功但残留了其他包副本（警告），1 = 失败（已还原到之前的版本）。

每次运行 apply、prune 和 full 都会把完整日志写到 ~/.cache/dsh-update/logs/<command>-<timestamp>.log（只保留最新的五份，包含完整的 bun 输出）。dsh-update check 会打印最新日志的路径，并在上一次运行留下备份时给出警告——更新没按预期走时，先看这里。

应用内更新

检查或安装更新不需要终端：
- 交互式托盘对话框： 在托盘菜单里选择 Check for updates。如果有更新可用，就会出现 Apply Update 按钮。
- 通知操作： 桌面通知里带一个 View Update 按钮，直接打开更新对话框。
- 实时输出流： 更新前会有一个明确的提示，确认当前活跃的智能体轮次将停止。确认后，dsh-update apply 开始运行，实时输出 stdout/stderr 日志，更新成功后窗口会在 3 秒后自动重新加载。

远程访问（可选）

bin/dsh-tailscale-proxy.mjs 把只监听回环地址的 DSH UI 暴露到私有网络（比如 Tailscale）上。

从托盘管理远程访问

不需要手动配置终端：
1. 打开托盘菜单，勾选 Remote access (Tailscale)。
2. 如果 ~/.config/dsh/proxy.env 还不存在，会自动生成一个安全的 32 字节 token，并绑定到你当前活跃的 Tailscale IP（tailscale ip -4）。
3. 可直接使用的 URL（http://<tailscale-ip>:3000/?token=...）会自动复制到剪贴板。首次访问时，代理会校验这个 token，从服务日志里读出 DSH 当前的启动 token，在服务端与 DSH 完成交换，然后返回一个 303，同时带上两个 cookie（代理自己的 dsh_proxy_token 和 DSH 的会话 cookie）——所以一个从没见过 DSH 的浏览器也能直接落到已登录的页面上。DSH 的启动 token 永远不会到达浏览器，也永远不会出现在你能复制的 URL 里。代理自己的 token 在链接里做了百分号编码，所以 token 里含 + 或 / 也能正常工作。
4. 需要把链接发到手机或远程浏览器时，随时点击托盘菜单里的 Copy remote link。
5. 取消勾选该选项会立即停止 dsh-proxy.service，让 DSH 回到仅监听回环地址的隔离状态。

手动配置终端（备选方案） bash
mkdir -p ~/.config/dsh
echo "DSH_PROXY_TOKEN=$(head -c 32 /dev/urandom | base64)" > ~/.config/dsh/proxy.env
chmod 600 ~/.config/dsh/proxy.env

Edit the unit to set DSH_PROXY_BIND to your tailscale IP:

Environment=DSH_PROXY_BIND=100.x.y.z

systemctl --user enable --now dsh-proxy.service

然后访问 http://<tailscale-ip>:3000/?token=<your-token>。

安全与网络说明

- 身份验证与会话保持： 访问需要提供共享密钥，形式可以是 Bearer <token>、?token=<secret>，或 dsh_proxy_token cookie。代理在把请求转发给上游之前会剥掉 token 参数，避免与 DSH 内部的 processLaunchToken 冲突；它自己的 bearer token、cookie 以及带 token 的 Referer 也绝不会转发给 DSH。
- Host 与 Origin 归一化： 代理会把收到的 Host 和 Origin 头归一化为上游回环地址，这样 DSH 就能接受经过身份验证的反向代理请求和 WebSocket 升级，同时把原始 host 保留在 X-Forwarded-Host 里。
- URL 里的 token： 托盘复制的链接在 ?token= 里携带的是代理 token；代理会把它转成 HttpOnly 的 SameSite=Lax cookie，并在转发上游前剥掉。代价是 token 会出现在浏览器历史和剪贴板里——把复制到的链接当成密码对待。（Tailscale 本身有 WireGuard 加密，所以 token 不会暴露给本地网络。）如果浏览器无法自动登录（比如服务重启过，journal 里不再有启动 token），代理会退回为直接转发请求，DSH 则显示它自己的「需要身份验证」页面。
- 客户端安全： 代理刻意不注入 window.__DSH_TRANSPORT__ = { ownsHost: true }——这个上游标志会告诉 DSH 客户端它运行在宿主机上，从而给远程浏览器开放宿主机的设置写入路径。

文件

bin/ scripts installed to ~/.local/bin
bin/dsh-yaml-check.py profile patch validator used by both installers (not installed)
bin/dsh-launcher.sh standalone CLI launcher (dsh web in a terminal; not wired
into any unit or desktop entry — the shortcuts use dsh-desktop-launch.sh) units/ systemd user unit templates (filled in by install.sh) applications/ .desktop entries icons/ app icon (png + svg + hicolor sizes) notify/ dsh-notify plugin (host + browser halves) install.sh installer uninstall.sh uninstaller

安装位置：

| 来源 | 目标 |
| bin/（dsh-yaml-check.py 除外） | ~/.local/bin/（设置了 $XDG_BIN_HOME 时用它） |
| units/ | ~/.config/systemd/user/ |
| applications/ | ~/.local/share/applications/ |
| icons/ | ~/.local/share/icons/ |
| notify/ | ~/.local/share/dsh-desktop/notify（由 DSH web 配置档建立链接） |

配置

所有脚本都读取环境变量，没有任何地方写死用户名。

| 变量 | 使用者 | 默认值 |
| DSH_WEB_URL | 托盘、浏览器窗口、代理、更新器 | http://127.0.0.1:3080 |
| DSH_TRAY_WINDOW | 托盘启动器 | maximized（fullscreen/normal） |
| DSH_NEW_CHAT | 托盘启动器 | 0（默认：恢复上次会话）/ 1（全新的干净会话） |
| DSH_CHROME | 浏览器窗口兜底 | 自动检测（Chrome、Chromium、Brave、Edge） |
| DSH_NODE | 启动器、安装器 | 自动检测 |
| DSH_BIN | 启动器、安装器 | 自动检测 |
| DSH_HOME | 插件安装 | ~/.dsh |
| BUN_INSTALL | 更新器、安装器 | ~/.bun（或 PATH） |
| DSH_PROXY_TOKEN | 代理 | 留空 → 仅限回环地址 |
| DSH_PROXY_BIND | 代理 | 127.0.0.1 |
| DSH_PROXY_PORT | 代理 | 3000 |
| DSH_PROXY_UPSTREAM_TIMEOUT_MS | 代理 | 30000（只针对响应头；流式传输不会被切断） |
| DSH_UPDATE_BUN_TIMEOUT | 更新器 | bun add/bun install 超时 900 秒 |
| XDG_BIN_HOME | 安装器、启动器、托盘、更新器 | ~/.local/bin |
| XDG_DATA_HOME | 安装器、托盘、更新器 | ~/.local/share |
| XDG_CONFIG_HOME | 安装器、托盘、更新器（proxy.env、units） | ~/.config |

要改窗口模式，编辑 ~/.local/bin/dsh-desktop-launch.sh 里的 DSH_TRAY_WINDOW。

桌面环境支持

本项目不绑定任何桌面环境。 代码不会根据你的桌面名称走不同分支：系统托盘和 D-Bus 会话总线都在运行时探测，其余部分（窗口处理、通知、服务）用的都是 freedesktop 和 systemd 接口，主流桌面环境都支持。安装器读取 XDG_CURRENT_DESKTOP，只是为了打印针对当前环境的建议。

| 环境 | 会话 | 托盘图标 | 说明 |
| KDE Plasma | X11 / Wayland | ✅ 内置 | 开箱即用 |
| GNOME | X11 / Wayland | ⚠️ 需要扩展 | 安装 gnome-shell-extension-appindicator（或 AppIndicator 扩展）。不装也能用窗口，只是少了「隐藏到托盘」 |
| XFCE | X11 | ⚠️ 需要插件 | 往面板里加 Status Tray Plugin |
| MATE | X11 | ⚠️ 需要小程序 | 添加 Notification Area 小程序 |
| Cinnamon | X11 / Wayland | ✅ 内置 | 如果没有，启用 XApp Status Applet |
| Budgie | X11 / Wayland | ✅ 内置 | — |
| Sway / Hyprland / i3 | Wayland / X11 | ⚠️ 需要状态栏 | 用 StatusNotifier 宿主，比如 waybar 加 tray 模块 |
| LXQt | X11 | ✅ 内置 | — |

shell 检测不到托盘时，会明确告诉你该为当前桌面装什么，然后继续正常工作：窗口直接关闭，而不是隐藏。
不同环境之间有什么区别，为什么不会出问题

| 关注点 | 处理方式 |
| 托盘可用性 | 用 QSystemTrayIcon.isSystemTrayAvailable() 探测，再加一次实时托盘检查；如果托盘在会话中途消失，看门狗会把窗口恢复回来 |
| 通知投递 | dsh-update notify 会发现会话总线（先看 DBUS_SESSION_BUS_ADDRESS，再看 $XDG_RUNTIME_DIR/bus，最后看 /run/user/<uid>/bus），而不是假定它存在；失败时会报出确切原因。更新检查单元只导出 XDG_RUNTIME_DIR=%t —— 脚本自己从它推导出总线地址。固定 DBUS_SESSION_BUS_ADDRESS=unix:path=%t/bus 的单元是 dsh-web.service |
| 服务启动 | 单元绑定到 default.target/timers.target，这两个目标在任何 systemd 安装上都存在。刻意避开 graphical-session.target，因为 XFCE/MATE/Cinnamon 会话不一定会拉起它，那样定时器会永远处于未激活状态 |
| 桌面快捷方式位置 | 通过 xdg-user-dir DESKTOP 解析，解析不到就回退到 ~/Desktop |
| 菜单 / 图标缓存 | 只在 update-desktop-database 和 gtk-update-icon-cache 存在时才调用 |
| 窗口匹配 | X11 上用 StartupWMClass；Wayland 上 Qt shell 直接设置自己的 app id |
| 密码存储 | --password-store=basic 可以避开没有 KWallet/GNOME Keyring 集成的环境里密钥环卡住的问题。密码以明文存放在本项目自己的配置档目录里 |

Wayland 与 X11 注意事项

- StartupWMClass 只在 X11 上有效；Wayland 上 Qt shell 直接设置自己的 app id，所以托盘 shell 的窗口匹配依然可用。
- Wayland 上 showMaximized 状态归合成器管。托盘单独保存你的窗口意图，并回退到它，所以隐藏再恢复不会把你的窗口缩小。
- 如果托盘本身在会话中途消失，看门狗会把窗口带回来，而不是留下一个看不见、杀不掉的进程。

故障排查

窗口一直不出现 / 提示「already running」托盘 shell 会持有一个锁文件。如果上一次运行卡住了：先 pkill -f dsh-tray.py，再重新启动。

服务启动超时 / 提示「Starting DeepSeek Harness…」
如果 dsh-web.service 在 30 秒内无法访问，shell 会显示一个交互式诊断界面，上面有服务 URL、相关的 journalctl 检查命令，以及一个直接的「Retry Connection」按钮。

出现的是 Chrome 窗口，而不是托盘 shell 缺少 PyQt6 WebEngine：sudo apt install python3-pyqt6.qtwebengine。
启动器现在回退时会打印出确切原因。

401 界面 / 登录循环删掉引导标记再重新启动：
rm ~/.local/share/dsh-tray/.bootstrapped
shell 会自动找到启动 token；如果找不到，现在它会明说，而不是静默失败。

收不到通知
1. 检查浏览器对 DSH 页面的通知权限。
2. 确认插件已加载：dsh --profile web --dump-config | grep notify
3. 安装插件后要重启 DSH —— 客户端名单在启动时构建。
4. 默认情况下，只有子代理活动不会发通知（includeSubagents）。

开关都打开了，通知却一直不出现

系统或浏览器权限被拒绝时，这一行会显示「Notifications are blocked by the browser」。给页面放行通知（QtWebEngine 和 Chrome 各自维护自己的权限存储），然后重新加载。权限是在你操作这一行里任意开关时请求的；挂载时发起的请求没有用户手势，通常会被拒绝。

General 设置页里没有 Notifications 这一行客户端 bundle 在页面加载时才拉取，所以先重新加载界面 —— 关掉窗口或标签页再打开（托盘外壳里，Reload 菜单项效果相同）。如果插件更新还是没到，清掉外壳的 HTTP 缓存；会话 cookie 存在 profile/ 里，不受影响： bash pkill -f dsh-tray.py; sleep 1; rm -rf ~/.local/share/dsh-tray/cache

如果这一行在，但开关是灰的，行内会说明原因：设置文档还在加载，或者部署没有提供 notify 命名空间 —— 这时用 dsh --profile web --dump-config | grep -A5 notify 看看这个条目到底有没有被组装进去。

更新检查说「up to date」，但明明有新版本这个工具会跟踪 rc 版本，也会识别更新的稳定版。如果只有 GitHub release、npm 还没发布，那就没有可安装的东西 —— dsh-update check 会明确说明。

更新失败，或者提示「leftovers remain」每次 apply/prune/full 运行都会往 ~/.cache/dsh-update/logs/ 写日志；dsh-update check 会打印最新一份，并在某次中断的运行留下备份时给出警告（下一次 apply 会替换并删除它）。运行失败会自动恢复上一个版本，并在日志末尾打印手动回滚命令。Leftovers（exit code 2）表示新版本已经装好，只剩过期的包文件 —— dsh-update apply 会清掉它们。

License

MIT。见 LICENSE。

「DeepSeek Harness」是 DeepSeek 的商标。本项目按官方品牌指南在名称中使用缩写「DSH」，是一个独立的社区项目。