dsh-tray：DeepSeek Harness Windows 系统托盘插件

前言¶

DeepSeek Harness（DSH）采用插件化架构。在 Windows 端开发或运行 DSH 时，直接通过浏览器访问界面可能不够便捷。此时，一个系统托盘程序可以提供常驻入口，方便随时打开界面、查看状态或退出。

dsh-tray 插件旨在解决这一问题。它通过 Windows 任务栏提供托盘图标、下拉菜单和气泡通知，并兼容 Headless 运行模式。

插件定位¶

• 名称：dsh-tray
• 维护者：qing3a
• 分类：客户端
• 协议：MIT
• 核心价值：为 DSH 提供 Windows 系统托盘支持，替代手动打开浏览器或命令行窗口进行管理。

核心功能¶

1. 系统托盘图标
   默认使用 default.ico，可通过配置项 iconPath 自定义图标（支持 .ico 或 .png Buffer）。
2. 托盘菜单
   包含三个操作：
   • 打开界面：动态读取 webServer.port 并拼接 URL 打开浏览器。
   • 状态：显示当前状态。
   • 退出：关闭托盘程序。
3. 气泡通知
   支持弹出 info 风格的通知消息。
4. Headless 兼容
   当环境中没有 webServer 时，插件会自动降级，不会导致程序崩溃或阻塞加载。

安装与启用¶

安装时需要使用 --profile web 参数。

pnpm dsh plugin --profile web add @qing3a/dsh-tray
pnpm dsh --profile web

安装完成后，Windows 任务栏应会出现 DSH 托盘图标。

配置¶

插件支持以下配置项（通常在 DSH 的配置文件中设置）：

实现细节¶

该插件基于 trayicon@1.2.2 开发，是一个 win32-only 的插件（无 native 编译依赖）。

• 避免文件句柄冲突：代码中直接 spawn 包内的 exe，没有使用 useTempDir 复制文件到临时目录，从而避免了 Windows 下常见的 spawn EBUSY 错误。
• 并发控制：start() 方法设计为幂等，通过共享 pending promise 来去重，防止并发调用导致出现两个托盘实例。
• 平台兼容：在非 win32 平台（如 Linux 或 macOS），插件会自动跳过加载。
• Headless 支持：通过 ctx.inject 动态获取 webServer，确保在无 webServer 环境下不会报错阻塞。

卸载¶

如需移除插件，执行以下命令：

pnpm dsh plugin --profile web remove @qing3a/dsh-tray

总结¶

dsh-tray 通过封装 trayicon 库，为 DSH 在 Windows 环境下提供了标准化的托盘交互能力。它解决了 Headless 模式下的兼容性问题，并优化了进程启动和并发逻辑。

更多细节可参考：
* 插件目录
* GitHub 仓库