Hope-Phenom/dsh-desktop-tray

dsh-desktop-tray — DSH 托盘助手

Build
Release
License: MIT

一个面向 DeepSeek Harness（dsh）的 WPF（.NET Framework 4.6.2）桌面托盘助手。它常驻托盘，解决环境配置和 Web UI 启停的易用性痛点——不再需要手动打开终端窗口，不再需要记住 URL。

项目主页：hope-phenom.github.io/dsh-desktop-tray
仓库：github.com/Hope-Phenom/dsh-desktop-tray

功能特性

环境检查与一键修复（环境标签页）

| 项目 | 能力 |
|---|---|
| Node.js | 自动检测版本（PATH + 常见安装位置）；缺失时一键安装：优先 winget install OpenJS.NodeJS.LTS，回退到官方 MSI（实时获取最新 LTS）；安装后自动刷新 PATH |
| npm 镜像 | 显示当前 registry；可针对本工具发起的 npm 操作按命令指定镜像（--registry，不影响你的全局配置）；可选的“写入全局 npmrc”（仅在明确确认后才影响全局配置） |
| dsh | 本地版本与远程最新版本对比（内置 semver 比较）；一键安装/更新（npm install -g @deepseek-ai/dsh@latest，显式 @latest 避免自定义 tag 配置陷阱）；有可用更新时弹出托盘气泡通知 |

整个健康检查有时间上限（约 2 分钟），并带有分步进度；网络不可达的项目会优雅降级（例如“远程版本查询失败”）——UI 永不卡死。

DSH 服务启停（服务标签页 / 托盘菜单）

- 可配置端口（1-65535）或随机端口（--port 0，由操作系统分配），在后台隐藏启动
- 从 dsh 输出中解析真实 URL（随机端口也能准确解析）；健康探测（HTTP 200）通过后自动打开浏览器（可禁用）
- 启动前进行端口占用预检 + 外部 dsh 实例扫描：防止两个实例并发写入同一个 DSH_HOME 而损坏会话
- 停止 = 结束进程树（taskkill /T /F）；检测到意外退出时会通知并重置状态
- 完整的运行时日志面板（实时流式输出 stdout/stderr，便于诊断）

托盘

- 菜单：启动 / 停止 / 重启 DSH、打开 Web UI、复制 URL、环境检查、主窗口、开机自启动、退出
- 退出 = 先停止 DSH 服务，因此不会留下孤立的 node 进程
- 运行状态图标显示绿色徽章；关闭主窗口时隐藏到托盘；单实例（再次启动会激活已有窗口）
- 默认双击托盘图标打开主窗口；你可以在设置中将其改为打开 Web UI

通知增强（通知增强选项卡）

- 每次 dsh turn/end（每一轮响应）时通知
- 可选地也为子代理/子任务通知
- 显示托盘通知和/或运行用户定义的外部命令（例如现有的 Python 通知脚本）
- 一键安装/更新/卸载捆绑的 dsh-notify-hook 插件
- 通知负载包含 sessionId、parentSessionId、turn、reason 和 durationMs

仅当通过 dsh-desktop-tray 启动 dsh 时才会发出通知（它会注入 DSH_NOTIFY_ENABLED=1）。

其他

- 轻量：仅使用原生 WPF 为 Windows 构建；启动快、内存占用低，且无繁重运行时
- 双语界面（中文 / English）：启动时自动检测系统语言——无需配置；可随时从设置页面切换，立即生效并自动保存
- 自启动使用 HKCU 注册表 Run 键，无需管理员权限（仅当前用户）
- 托盘应用启动时可选择自动启动 DSH 服务
- 清理 dsh 环境（设置页面）：停止 dsh → 卸载全局 npm 包 → 将数据目录（API 凭据和会话）重命名为 .dsh.bak- 作为备份，而非删除（可恢复）→ 移除登录自启动项；完整日志流式输出，可取消；不会卸载 Node.js
- 设置持久化到 %APPDATA%\DshNotifyicon\settings.json（原子写入；损坏的文件会被备份并恢复默认值）
- 所有后台操作（npm/winget/install）均异步运行并流式输出到 UI，不会阻塞 UI

要求

- Windows 10 / 11（.NET Framework 4.6.2 随操作系统提供——无需额外安装运行时）
- Node.js ≥ 18（可从工具中一键安装，环境选项卡）
- dsh：npm install -g @deepseek-ai/dsh（可从工具中一键安装/更新）

构建

需要 Visual Studio（带有 .NET Framework 4.6.2 目标包）或带有 MSBuild 的命令行。

msbuild DshNotifyicon.slnx /restore /p:Configuration=Release

输出：DshNotifyicon\bin\Release\DshNotifyicon.exe（双击运行，无需安装）。
NuGet 依赖项：Hardcodet.NotifyIcon.Wpf（托盘）、Newtonsoft.Json（设置序列化）。

若要分发，请将 exe 与同一输出目录中的 Hardcodet.NotifyIcon.Wpf.dll、Newtonsoft.Json.dll 以及 tools\dsh-notify-hook 文件夹一起复制。

用法

1. 首次启动：显示主窗口；之后默认隐藏到托盘（可通过设置中的“启动时显示主窗口”更改）。
2. 环境选项卡 → 健康检查：查看 Node.js / npm 镜像 / dsh 状态；点击任何缺失项的按钮进行修复。
3. 服务选项卡：设置端口（或勾选随机端口）→ 启动 DSH → 浏览器自动打开 Web UI。
4. 托盘：日常操作都在这里——运行时图标会显示一个绿点；悬停可查看当前 URL。
5. UI 语言（可选）：默认跟随系统；可随时在设置中的“UI Language”下拉菜单切换到中文 / English——立即生效。
6. 通知增强选项卡（可选）：安装/更新 dsh 通知插件，然后选择托盘通知和/或外部命令。

安装类操作（Node.js / dsh）会自动切换到服务选项卡的日志面板以流式显示进度，同时环境选项卡会显示进度条；
安装按钮会变为“取消”——随时点击即可中止（进程树会被清理）；成功后应用会返回环境选项卡并重新运行健康检查。

常见场景

- 端口被占用：在启动前检测到；弹窗提供“直接在该端口打开浏览器”或取消。
- 发现其他 dsh 实例（例如手动打开的终端窗口）：三种选择——停止它们并启动新实例 / 仅打开浏览器 / 中止。这可以防止两个实例同时写入同一数据目录并损坏会话。
- 随机端口模式：URL 会从 dsh 输出中自动解析；托盘提示、日志面板和“打开 Web UI”都会显示真实地址。

通知增强（可选）

1. 打开通知增强选项卡。
2. 点击安装/更新 dsh 通知插件，将捆绑的 dsh-notify-hook 插件安装到 web 配置文件中。
dsh 的插件管理需要 pnpm。如果未安装 pnpm，该工具会自动运行 npm install -g pnpm 然后继续；你也可以在环境选项卡的健康检查下查看它，并一键安装。
3. 选择你的选项：
- 启用通知增强——总开关。
- 子代理/子任务也通知——子代理 turn/end 时也通知。
- 显示托盘通知——每次响应后显示原生托盘气泡。
- 启用外部命令——运行自定义命令/脚本，例如现有的 Python 通知脚本。
4. 点击保存设置，如果 dsh 已在运行，则重启它。
5. 以后若要移除插件，点击卸载 dsh 通知插件。

外部命令占位符：

{event} {title} {sessionId} {parentSessionId} {turn} {reason} {durationMs}

示例：

Command: python
Arguments: E:\QuickStart\send_notification.py {sessionId} {reason} {durationMs}

托盘设置

- 双击托盘图标：可设置为打开主窗口或直接打开 Web UI。
- 托盘启动后自动启动 DSH：启用后，dsh-desktop-tray 一启动，DSH 就会自动启动。

无头冒烟测试

DshNotifyicon.exe --smoke
运行环境检查 + 真实的 dsh 启动/停止（随机端口）+ HTTP 探测，将结果写入 %TEMP%\DshNotifyiconSmoke.txt 并以 0/1 退出。不会创建托盘或窗口——适用于自动化回归测试。

已知限制

- 停止是强制终止（taskkill /T /F）：dsh 大约每 ~5 秒持久化一次会话，因此最多可能丢失 ~5 秒的末尾对话（并非优雅关闭）
- 镜像默认仅适用于此工具发出的 npm 命令；“写入全局 npmrc”会永久影响该用户的所有 npm 操作（已在 UI 中确认）
- 如果此工具本身从任务管理器中被强制终止，dsh 可能会被遗留：外部实例扫描会在下次启动时检测到它并提示处理
- --host 仅支持 127.0.0.1（dsh 的限制；此工具不暴露此选项）
- Debug 和 Release 构建共享单实例互斥体，无法同时运行
- 黑色透明图标在深色 Windows 任务栏上对比度较低（运行状态的绿点仍会显示状态）
- UI 语言切换立即生效并会被保存；托盘气泡按钮由 Windows 自身本地化（内容跟随 UI 语言）

故障排除

| 症状 | 修复方法 |
|---|---|
| 在 PowerShell 中手动运行 npm 报告“running scripts is disabled” | 执行策略阻止了 npm.ps1（PowerShell 在 .cmd 之前解析 .ps1）。此工具不受影响（它通过 node 直接调用 npm-cli.js，不使用脚本垫片）。手动使用时，请调用 npm.cmd 或运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（无需管理员权限） |
| 启动 DSH 一直停留在“Starting” | 检查日志面板：首次启动会初始化 web 配置文件，可能较慢；如果报告端口被占用，请按照对话框操作 |
| dsh 安装失败（npm E404/ETARGET） | 此工具始终使用 @latest 以避免自定义 tag 问题；如果仍然失败，请复制日志面板内容并排查（网络/镜像不可达） |
| Node.js UAC 提示被取消 | 此工具会打印 nodejs.org 的手动安装说明；安装后再次运行健康检查 |
| 自动启动不工作 | 在设置中勾选该复选框；企业/域策略环境可能会禁用 HKCU Run 键（在个人电脑上不是问题） |
| 健康检查似乎卡住 | 不可能发生：整个检查有时间限制（120 秒），网络查询每次上限为 45 秒，失败会降级为“检查超时 / 远程版本查询失败”而不会挂起；如果仍然异常，请检查日志面板 |
| 清理后想恢复数据 | 停止 dsh，然后将 %USERPROFILE%\.dsh.bak- 重命名回 .dsh（包含凭据和会话） |
| 托盘图标消失 | 单实例行为：再次启动 exe 会激活正在运行的实例；如果它确实已退出，请在任务管理器中结束 DshNotifyicon.exe 并重新启动 |
| 工具崩溃 / 无响应 | 所有异常都会写入 %APPDATA%\DshNotifyicon\crash-*.log（异常详情 + 最近的日志快照），并在下次启动时显示托盘气泡提示；复现后将该文件发送给开发者 |

目录结构

DshNotifyicon/
├─ DshNotifyicon.slnx        解决方案
├─ DshNotifyicon/
│  ├─ App.xaml(.cs)          单实例、托盘生命周期、--smoke 模式、事件接线、启动时应用 UI 语言
│  ├─ MainWindow.xaml(.cs)   环境 / 服务 / 设置 / 通知增强 / 关于 选项卡；语言切换时刷新所有静态文本
│  ├─ TrayIcon.cs            托盘图标与菜单（使用 Hardcodet 以代码构建；文本随语言刷新）
│  ├─ AppServices.cs         服务容器：设置 / DSH 进程 / 主窗口 / 托盘
│  ├─ Services/
│  │  ├─ Settings.cs         设置模型（含 Language 字段与通知设置）及原子化持久化
│  │  ├─ Localization.cs     中/英字符串表、自动检测与语言切换（Loc.T / Loc.Changed）
│  │  ├─ ProcessRunner.cs    隐藏进程执行、分离 stdout/stderr、超时、进程树终止
│  │  ├─ NodeService.cs      Node.js 检测 / winget+MSI 安装 / PATH 刷新
│  │  ├─ NpmService.cs       npm 封装（@latest、按命令 --registry、串行队列、semver）
│  │  ├─ DshProcessManager.cs  状态机、预检、URL 解析、健康探测、启动/停止、DSH_NOTIFY 解析
│  │  └─ EnvironmentCheckService.cs  健康检查聚合
│  └─ Assets/app.ico         图标（由 DeepSeek 官方 favicon.svg 渲染；应用运行中带绿点）
└─ tools/
├─ dsh-notify-hook/       在回合/结束时发出 DSH_NOTIFY 行的 dsh 插件
├─ gen-icons.js           图标重新生成脚本（node）
└─ favicon.svg            官方图标源文件

site/ 是 GitHub Pages 落地页源文件（单文件双语 index.html + 图标资源），由 .github/workflows/pages.yml 自动部署到 hope-phenom.github.io/dsh-desktop-tray。

开发说明

- 技术栈：.NET Framework 4.6.2（旧式 csproj，LangVersion=7.3），无需附带运行时；服务层不依赖 WPF，便于无头验证
- 新文件必须在 csproj 中注册：旧式 csproj 使用显式的  条目——新增源文件（例如 Services\Localization.cs）必须手动添加
- UI 文本：始终通过 Loc.T("key") 获取——禁止硬编码字符串；先在 Localization.cs 表中注册新文本（[0]=zh，[1]=en）；语言切换通过 Loc.Changed 事件传播
- 图标重新生成：node tools/gen-icons.js（复用 dsh 依赖树中的 sharp；npm i -g sharp 也可行），然后重新构建（图标为嵌入资源）
- 设计不变量：npm 包名始终显式使用 @latest；镜像通过 --registry 按命令注入；外部实例扫描使用 PowerShell -EncodedCommand 以避免引号转义问题；stdout/stderr 分别收集以保持解析清晰