托盘助手 Hope-Phenom/dsh-desktop-tray

dsh-desktop-tray — DSH 托盘助手

一个 WPF（.NET Framework 4.6.2）桌面托盘助手，服务于 DeepSeek Harness（dsh）。它常驻托盘，专治环境配置和 Web UI 启停的难用痛点——不用再手动开终端窗口，不用再背 URL。

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

功能

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

| 项目 | 能力 |
| 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 分钟），带分步进度；网络不通的项目会优雅降级（比如显示「远程版本查询失败」）——界面绝不卡死。

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

- 端口可配置（1-65535）或用随机端口（--port 0，由系统分配），后台隐藏启动
- 从 dsh 输出里解析出真实 URL（随机端口也准）；服务就绪（健康探测通过）后自动打开浏览器（可关闭）
- 浏览器跳转由本工具接管：较新的 dsh（≥ 0.1.0-rc.8）会自己开标签页，所以本工具追加 --no-open——勾选 = 恰好一个标签页，不勾 = 一个都不开。较旧的 dsh（< 0.1.0-rc.8）不加这个参数，行为与之前完全一致
- 启动前做端口占用预检 + 外部 dsh 实例扫描：防止两个实例并发写同一个 DSH_HOME 弄坏会话
- 停止 = 杀进程树（taskkill /T /F）；异常退出会被检测到、发出通知，并重置状态
- 完整运行日志面板（实时流式输出 stdout/stderr，方便排查）

托盘

- 菜单：Start / Stop / Restart DSH、Open Web UI、Copy URL、Environment Check、Main Window、Auto-start at logon、Exit
- Exit = 先停掉 DSH 服务，不会留下孤立的 node 进程
- 运行状态图标带绿色角标；关闭主窗口会隐藏到托盘；单实例（再次启动会激活已有窗口）
- 默认双击托盘图标打开主窗口；可以在 Settings 里改成打开 Web UI

通知增强（Notification Enhancements 标签页）

- 每轮 dsh turn/end（每轮回复结束）都会通知
- 可选：子代理/子任务也通知
- 支持托盘通知，也可以执行你自定义的外部命令（比如已有的 Python 通知脚本）
- 一键安装/更新/卸载内置的 dsh-notify-hook 插件
- 通知内容包含 sessionId、parentSessionId、turn、reason 和 durationMs

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

其他

- 轻量：只用原生 WPF 构建，仅支持 Windows；启动快、内存占用低，不依赖笨重的运行时
- 中英双语界面（中文 / English）：启动时自动识别系统语言，无需配置；随时可在 Settings 页面切换，立即生效并自动保存
- 开机自启用 HKCU 注册表 Run 键，不需要管理员权限（仅当前用户）
- 可选：托盘程序启动时自动拉起 DSH 服务
- 清理 dsh 环境（Settings 页面）：停掉 dsh → 卸载全局 npm 包 → 把数据目录（API 凭据和会话）重命名为 .dsh.bak-<date>，这是备份而不是删除（可恢复）→ 移除登录自启项；全程日志实时输出，可取消；不会卸载 Node.js
- 设置保存到 %APPDATA%\DshNotifyicon\settings.json（原子写入；文件损坏会先备份再恢复默认值）
- 所有后台操作（npm/winget/install）都异步执行，日志实时推到界面，不阻塞界面

环境要求

- Windows 10 / 11（.NET Framework 4.6.2 随系统自带，不用额外装运行时）
- Node.js ≥ 18（可在工具里一键安装，Environment 标签页）
- 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 状态；哪一项缺失就点哪一项的按钮修复。
如果 Node.js 或 pnpm 不在 PATH 里（便携版、nvm、自定义安装目录），用该分组里的 指定路径…：填入可执行文件的完整路径，或者只填所在文件夹；留空 = 自动检测。路径会当场校验（文件名必须匹配，而且必须真的能报出版本号）；校验失败会说明原因，你仍然可以保存。如果保存后依然校验不通过，健康检查会退回自动检测，并说明原因，而不是悄悄用别处的工具。
3. 服务标签页：设置端口（或勾选随机端口）→ 启动 DSH → 浏览器自动打开 Web UI。
4. 托盘：日常操作都在这里——运行时图标会多一个绿点；悬停可查看当前 URL。
5. 界面语言（可选）：默认跟随系统；随时在设置里的「界面语言」下拉框中切换 中文 / 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. 点击 Save Settings，如果 dsh 已在运行，重启它。
5. 以后想移除插件，点击 Uninstall dsh Notification Plugin。

外部命令占位符：

{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 大约每 ~5s 持久化一次会话，所以最多可能丢失 ~5s 的尾部对话（不是优雅关闭）
- 镜像默认只作用于本工具发出的 npm 命令；「Write Global 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 解析 .ps1 优先于 .cmd）。本工具不受影响（它通过 node 直接调用 npm-cli.js，不走脚本 shim）。手动使用时，调用 npm.cmd，或运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（无需管理员） |
| 启动 DSH 一直停在「Starting」 | 查看日志面板：首次启动要初始化 web 配置档，可能较慢；如果提示端口被占用，按对话框处理 |
| dsh 安装失败（npm E404/ETARGET） | 本工具始终用 @latest，避免自定义 tag 的问题；如果仍然失败，复制日志面板内容再排查（网络/镜像不可达） |
| Node.js UAC 提示被取消 | 本工具会打印 nodejs.org 的手动安装说明；装好后重新跑健康检查 |
| 开机自启不生效 | 在设置里勾选复选框；企业/域策略环境可能禁用 HKCU Run 键（个人电脑上不会出现这个问题） |
| 健康检查像是卡住了 | 不可能：整个检查有时间上限（120s），每次网络查询最多 45s，失败会降级为「检查超时 / 远程版本查询失败」，不会挂起；如果仍然异常，查看日志面板 |
| 清理后想找回数据 | 先停止 dsh，再把 %USERPROFILE%\.dsh.bak-<date> 改回 .dsh（里面含凭据和会话） |
| 托盘图标消失了 | 单实例行为：再次启动 exe 会激活正在运行的实例；如果它确实已退出，在任务管理器中结束 DshNotifyicon.exe 再重新启动 |
| 工具崩溃 / 无响应 | 所有异常都会写入 %APPDATA%\DshNotifyicon\crash-*.log（异常详情 + 最近的日志快照），下次启动时弹出托盘气泡提示；复现后把该文件发给开发者 |
| 启动失败，日志里出现 unknown option '--no-open' | 本工具针对 dsh 的能力规则已过时（dsh 重命名或移除了该参数）；日志里会明确写出是哪个。把本工具更新到最新版本 |

目录结构

DshNotifyicon/
├─ DshNotifyicon.slnx Solution
├─ DshNotifyicon/
│ ├─ App.xaml(.cs) Single instance, tray lifecycle, --smoke mode, event wiring, applies UI language at startup
│ ├─ MainWindow.xaml(.cs) Environment / Service / Settings / Notification Enhancements / About tabs; refreshes all static texts on language switch
│ ├─ TrayIcon.cs Tray icon & menu (built in code with Hardcodet; texts refresh with the language)
│ ├─ PathPickerDialog.cs "Specify path…" input dialog (shared by Node / pnpm; built in code) │ ├─ AppServices.cs Service container: settings / DSH process / main window / tray │ ├─ Services/ │ │ ├─ Settings.cs Settings model (incl. Language field & notification settings) & atomic persistence │ │ ├─ Localization.cs CN/EN string table, auto-detection & language switching (Loc.T / Loc.Changed) │ │ ├─ ProcessRunner.cs Hidden process execution, separated stdout/stderr, timeout, process-tree kill │ │ ├─ NodeService.cs Node.js detection (incl. manual path override) / winget+MSI install / PATH refresh │ │ ├─ NpmService.cs npm wrapper (@latest, per-command --registry, serialized queue, semver) │ │ ├─ DshProcessManager.cs State machine, preflight, URL parsing, health probe, start/stop, DSH_NOTIFY parsing │ │ ├─ DshCapabilities.cs Version lookup & web-CLI capability rules for the installed dsh (--no-open gating) │ │ └─ EnvironmentCheckService.cs Health-check aggregation │ └─ Assets/app.ico Icon (rendered from DeepSeek's official favicon.svg; app-running has a green dot) └─ tools/ ├─ dsh-notify-hook/ dsh plugin that emits DSH_NOTIFY lines on turn/end ├─ gen-icons.js Icon regeneration script (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 使用显式 <Compile Include> 条目——新增源文件（如 Services\Localization.cs）必须手动添加
- 界面文案：一律通过 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 分开收集，保持解析干净