托盘看门狗 subfocusx/dsh-tray

dsh-tray

License: MIT

基于 spacecat398/dsh-tray —— 本仓库所构建的原始项目。

把仓库地址给你的 dsh-agent，除了复制粘贴以外你不需要做任何事情。

欢迎你，Agent 👋

这个仓库是一个 Windows 托盘程序：DeepSeek Harness（dsh web）的常驻开关 + 看门狗。托盘负责启动 / 重启 / 停止 dsh web、健康监控、崩溃自动拉起，还带“开启新对话”和日志复制。菜单语言跟随系统（中文 / English），一切参数通过 dsh-tray.json 配置。

下面的协议是给你（安装 / 配置 / 运维它的 Agent）看的操作契约。请先读完协议再动手，尤其是安全规则和完成检查。

📜 给 Agent 的协议（Agent Protocol）

本协议适用于安装、配置、启动、验证 dsh-tray 的 AI Agent。

1. Objective

在一台 Windows 机器上把 dsh-tray 部署为常驻托盘程序：开机自启、托盘控制 dsh web（默认端口 3080）、崩溃自动拉起。优先最小可用配置，不要引入额外依赖。

2. Requirements

- Windows 10/11（自带 PowerShell 5.1+，程序依赖 powershell.exe，不是 pwsh）
- Node.js 全局安装 dsh：npm i -g @deepseek-ai/dsh，且 dsh web 能启动
- 本仓库已克隆到目标机器（例如 C:\dsh-tray\）

3. Install

1. 克隆（如尚未克隆）
git clone https://github.com/subfocusx/dsh-tray.git
2. 复制配置模板 Copy-Item dsh-tray.example.json dsh-tray.json
3. 按需编辑 dsh-tray.json（至少确认 startscript 指向一个能启动 dsh web 的脚本）
4. 启动托盘 wscript //nologo dsh-tray-launch.vbs

零依赖：纯 PowerShell + WinForms，不需要 npm install / pip / Docker。

4. Configure（dsh-tray.json）

| 键 | 默认 | 说明 |
| port | 3080 | dsh web 端口。3080 是 dsh 的开箱默认端口（官方 README 与 web-app 包内补丁均为 ?? 3080）；healthurl/dashboardurl 由它派生 |
| startscript | start-dsh.cmd | 启动脚本；托盘以 作为 %1 调用它 |
| dshlogfile | logs\dsh-web.log | “复制最近日志”菜单读取的文件 |
| healthintervalseconds | 10 | 健康检查间隔（秒） |
| startupgraceseconds | 120 | 启动宽限期（期间只显示 Warming up） |
| restartdelayseconds | 5 | 崩溃重启基础延迟；退避上限 ×6 = 30s |
| maxconsecutiverestarts | 10 | v1.7.1 连续崩溃自动重启上限（退避随次数 5s→30s 增长）；达到后停止自动重启，状态显示「需要干预」，手动「重启 dsh」重置计数并恢复自动重启 |
| language | auto | auto（跟随系统）/ zh / ru / en |
| notifications | true | 状态跳变通知气泡开关 |
| whaleicon | true | 健康时使用鲸鱼图标（assets\dsh-whale.png） |
| agentmonitor | true | v1.4.0 开启「代理 (Agents)」子菜单与轮询 |
| agentpollseconds | 5 | v1.4.0 代理轮询间隔（秒，最小 2） |
| agentnotifications | true | v1.4.0 代理启动 / 完成 / 等待时通知气泡 |
| badgeicon | true | v1.4.0 在托盘图标上叠加运行中代理数量徽标 |
| maxagentloglines | 200 | v1.4.0 代理日志窗口显示行数上限 |
| agenthistorylines | 40 | v1.4.0 拉取 subagent.history 事件数（日志尾部） |
| chromeapplnk | (空) | v1.4.1 Chrome App 快捷方式路径。设置后「打开面板」/双击图标/新对话都在独立 Chrome 应用窗口打开，而非新标签页；为空或失效则回退为普通浏览器标签。常见位置：① Start Menu\Programs\Chrome Apps\DeepSeek Harness.lnk；② 若 PWA 安装在某个 Chrome 配置文件内：…\Chrome\User Data\Profile N\Web Applications\_crx_\DeepSeek Harness.lnk（用真实存在的那个，检查其目标是 chrome_proxy.exe 而非 dsh-tray-launch.vbs） |
| menutheme | dark | v1.5.0 / v1.8.0 菜单与 toast 主题：auto（跟随系统明/暗）/ light / dark。v1.8.0 起默认 dark，且可在托盘菜单「主题 / Theme / 主题」子菜单中即时切换（写回 dsh-tray.json，无需重启） |
| toastson | true | v1.5.0 true → 现代 Windows 11 通知（自绘圆角 toast + 强调色条 + 鲸鱼图标）；false → 经典系统气泡（回退） |
| toastduration | 4000 | v1.8.0 toast 自动关闭前停留时间（毫秒，范围 1000–60000）。v1.8.0 修复了 toast「永远不消失」：所有 toast 计时器现在有根引用，另有 250ms 巡检在 duration+2500ms 硬上限强制关闭，任何情况下 toast 都不会无限悬挂 |
| toastmax | 4 | v1.9.0 同时在屏幕上的 toast 数量上限（1–8）。toast 从右上角垂直堆叠、互不重叠，超出上限时最旧的被强制关闭 |
| toastactions | true | v1.9.0 在 toast 上显示动作按钮（打开面板 / 重启 dsh / 更新） |
| toasthistory | 20 | v1.9.0 菜单「通知 / Notifications / Уведомления」中保留的通知历史条数（0 = 关闭历史菜单） |
| toasttranslucent | true | v1.9.0 Win11 下 toast 的轻微半透明（Mica 效果；失败自动回退不透明） |
| menubicons | true | v1.5.0 在菜单项上显示 MDL2 图标（Segoe MDL2 Assets 字体内置绘制，无需外部图片） |
| uifont | Segoe UI Variable Text | v1.6.0 菜单与 toast 的统一字体；系统无此字体时自动回退 Segoe UI |
| uifontsize | 9 | v1.6.0 菜单 / toast 正文字号的基准（pt）；标题自动 +1 |
| updatecheck | true | v1.6.0 是否检查 @deepseek-ai/dsh（npm）的新版本 |
| updateintervalhours | 24 | v1.6.0 自动检查周期（小时）；0 关闭周期检查（仍保留手动菜单项） |
| updateapply | true | v1.6.0 是否允许一键应用更新（npm i -g @deepseek-ai/dsh@latest） |

5. 运行与验证（Completion Check）

报告完成前，逐条核对：

1. dsh-tray.ps1 能被 Windows PowerShell 5.1 正常解析（文件必须保存为 UTF-8 with BOM，否则中文按 ANSI 解码直接语法崩溃）
2. 托盘进程在运行且单实例： Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match '-File.dsh-tray\.ps1' }

3. 托盘菜单完整：状态行 / 打开面板 / 开启新对话 / 重启 dsh / 停止 dsh / 退出 / 复制最近日志 / 开机自启 / 代理 (Agents)
4. dsh web 健康：菜单状态行显示 Healthy (:)，且 Get-NetTCPConnection -LocalPort -State Listen 有监听（默认 3080）
5. 托盘日志 logs\dsh-tray.log 有 Tray application starting ... v1.x.x 记录，无 FATAL
6. 开机自启已按用户意愿设置（托盘菜单勾选，或 powershell -File install-autostart.ps1）

6. 安全规则

- 不要提交或暴露 dsh-tray.json（含本机路径）、logs/、任何 .log（仓库 .gitignore 已排除，保持即可）
- dsh-tray.ps1 含中文，必须 UTF-8 with BOM；编辑后务必重新确认 BOM 存在
- 停止 dsh 时托盘会先校验进程身份（node/bun + 命令行含 dsh）再 taskkill，不要绕过该校验去杀任意进程
- 不要随意改端口，除非用户明确要求（两个 URL 都由 port 派生，改 port 即可，别手改 URL）
- 不要把托盘提升为管理员 / 服务运行 —— 它是普通用户级常驻程序
- 本机安全注意：若系统防火墙 Private 配置文件被关闭，其他 0.0.0.0 监听服务可能对局域网可见（与托盘无关，但值得提醒用户）

7. 运行约束

- 平台：Windows + PowerShell 5.1（powershell.exe），不是 pwsh
- 托盘常驻："停止 dsh" 只停服务、托盘留在系统托盘中；"退出"（v1.4.1） 停止服务并彻底关闭托盘程序本身
- 看门狗只管生命周期、不管快慢：进程活着绝不杀（慢启动不误杀）；进程消失才重启（5s→30s 退避）
- "开启新对话"优先用 UI Automation 驱动 GUI 自己的"新建会话"流程（点按钮→选新条目，创建/切换/持久化全由 GUI 处理）；GUI 不可达时回退 RPC 建会话 + 新标签页
- 健康检查与 dsh web 服务全部绑定 127.0.0.1，不对局域网开放
- 修改 dsh-tray.ps1 后需要重载托盘才生效：先杀旧托盘进程，再运行 dsh-tray-launch.vbs

8. 重要文件

dsh-tray.ps1 # 主控：WinForms 托盘 + 看门狗 + 菜单 + 配置加载 + i18n dsh-tray-launch.vbs # 无窗口启动器（双击 / 开机自启入口） install-autostart.ps1 # 开机自启安装 / 卸载 start-dsh.cmd # 默认 dsh 启动模板（接收 %1 = 端口） dsh-tray.example.json # 配置模板（复制为 dsh-tray.json） assets\dsh-whale.png # 鲸鱼托盘图标 logs\dsh-tray.log # 托盘自身日志（运行时生成，不入库）

功能一览（给人类）

| 功能 | 说明 |
| 🖱️ 托盘菜单 | 状态行 / 打开面板 / 开启新对话 / 代理 (Agents) / 重启 dsh / 停止 dsh / 退出 / 复制最近日志 / 开机自启 |
| 🧭 三语 | 菜单、状态、通知气泡按系统语言自动切换：中文 / English / Русский（language 可强制） |
| 🐳 健康图标 | 健康 = 鲸鱼图标；异常 = 系统警告/错误图标 |
| 🔢 徽标徽章 | v1.4.0 健康时在鲸鱼图标右上角叠加当前运行中代理数量的红色徽章 |
| 🕵️ 代理监控 | v1.4.0 "代理 (Agents)" 子菜单实时列出运行中/等待输入的子代理，每个可「查看日志」「停止」 |
| 📜 代理日志 | v1.4.0 弹窗展示代理最近输出（assistant 正文 + turn 结束原因），点击「查看日志」打开 |
| 🔔 代理通知 | v1.4.0 代理启动 / 完成 / 等待输入时通知气泡（agentnotifications 可关） |
| 💬 通知气泡 | 状态跳变（启动/停止/恢复/异常/自动重启）时通知，不刷屏 |
| 🗂️ Toast 堆叠 | v1.9.0 toast 从右上角垂直堆叠（互不重叠），最多 toastmax 个（默认 4），超出强制关闭最旧；快速同类型事件 500ms 内在原位刷新（不再闪烁）；toast 带动作按钮（打开/重启/更新，toastactions 可关）与类型图标（信息/警告/错误） |
| 📋 通知历史 | v1.9.0 菜单新增「通知 / Notifications / Уведомления」子菜单，记录最近 toasthistory 条通知（标题+时间，点击打开面板），可一键清空 |
| ⏱️ Toast 自动关闭 | v1.8.0 修复 toast 悬挂问题：自动关闭计时器全部根级持有 + 250ms 硬截止扫描（duration+2500ms 强制关闭），toast 再也不会「一直挂着」；停留时长可用 toastduration 调节 |
| 🌙 深色设计 | v1.8.0 默认深色主题；菜单 / toast / 图标全套深色调色板（近黑面板、柔和悬停、高对比文字）；菜单「Тема / Theme / 主题」即时切换 自动/浅色/深色并写入配置 |
| 🪟 Chrome 应用 | v1.4.1 「打开面板」/双击图标/新对话在独立 Chrome 应用（PWA） 窗口打开，而非新标签页（配置 chromeapplnk 指向 Chrome Apps\DeepSeek Harness.lnk；失效则回退普通标签页） |
| 🚪 退出 | v1.4.1 「退出」停止 dsh 服务并彻底关闭托盘程序本身（「停止 dsh」只停服务、托盘留在托盘） |
| 🛡️ 看门狗 | 只管生命周期：进程活着绝不杀；崩溃才重启（5s→30s 退避） |
| 🔍 更新检查 | v1.6.0 「检查更新」菜单 + 周期自动检查 @deepseek-ai/dsh（npm）；发现新版 → Win11 toast；updateapply: true 时「更新到 vN」一键安装并重启 |
| 🔤 平滑字体 | v1.6.0 菜单 / toast / MDL2 图标统一使用平滑抗锯齿字体（uifont，默认 Segoe UI Variable，自动回退）+ 进程级 DPI 感知，不再“锯齿/毛边” |
| 🎯 停止安全 | 杀进程前校验身份（node/bun + 命令行含 dsh），不误杀外来进程 |
| 🆕 开启新对话 | 驱动 GUI 自己的"新建会话"流程，真正打开新空对话 |
| 📋 复制日志 | 一键复制最近 25 行 dsh 日志到剪贴板 |
| 🔄 防双开 | Mutex Local\DshTray- |
| ⚙️ 配置文件 | 所有参数在 dsh-tray.json，无需改脚本 |

使用：双击 dsh-tray-launch.vbs 启动；开机自启在菜单里勾选"开机自启"；"停止 dsh" 只停服务（托盘留下），"退出" 停服务并彻底关闭托盘。

📜 版本历史

| 版本 | 内容 |
| v1.9.0 | 🗂️ 堆叠 toast + 通知历史 + 动作按钮：修复 toast 相互重叠——toast 改为右上角垂直堆叠（各自独立插槽、滑动进入，最多 toastmax 个，默认 4，超出强制关闭最旧）；每类事件有类型图标（信息/警告/错误，MDL2 圆形徽章）与动作按钮（打开面板 / 重启 dsh / 更新，toastactions 可关）；快速同类型事件 500ms 内在原位刷新，启动连跳不再闪烁。新增菜单「通知 / Notifications / Уведомления」子菜单，保留最近 toasthistory 条通知历史（点击打开面板，可清空）。Win11 下 toast 支持轻微半透明（Mica，toasttranslucent，失败回退不透明）。新增配置 toastmax / toastactions / toasthistory / toasttranslucent。 |
| v1.8.0 | 🔔 toast 自动关闭修复 + 深色设计：修复通知「挂在屏幕永不消失」——根因是 fade-out / 自动关闭的 WinForms Timer 作为事件闭包里的无根局部变量被 GC 回收，fade 永不执行；现在所有 toast 计时器挂在脚本级注册表（$script:ToastTimers）+ toast 上下文包，另加 250ms 硬截止扫描（duration+2500ms 强制关闭），toast 寿命有严格上限。新增 toastduration（毫秒，默认 4000）。🌇 深色设计：默认 menutheme: dark，菜单/toast/图标深色调色板重做（更漆黑的表面、更柔和的悬停、深色下更高对比）；菜单图标按主题即时重绘；新增菜单「Тема ▸ 自动/浅色/深色」子菜单，即时切换并把 menutheme 写回 dsh-tray.json。 |
| v1.7.1 | 🛡️ 崩溃-循环稳定化 + 不再卡 UI 的菜单动作：修复 backoff 永不增长的 bug（RestartCount 不再在每次 Start-Process 后被清零，只在真正 Healthy 时重置 → 退避 5s→30s 真实生效）；新增 maxconsecutiverestarts（默认 10）上限，超过后停止自动重启、状态「需要干预」+ 一次错误 toast，手动「重启 dsh」重置。「开启新对话」与「停止代理」改为后台 runspace 执行（UI Automation / RPC 不再阻塞点击，新对话菜单项在执行期间显示禁用/"…"）；Read-Config 数值字段校验（非数字/非正/越界 → WARN + 回退默认值）。 |
| v1.6.0 | ✨ 统一平滑字体 + 更新检查：菜单/图标/toast 统一使用配置字体（uifont，默认 Win11 的 Segoe UI Variable，自动回退 Segoe UI）；MDL2 图标与文字改用平滑抗锯齿（Antialias 替代 AntiAliasGridFit），消除“锯齿/毛边”；新增进程级 DPI 感知。新增「检查更新」菜单 + 周期自动检查（updatecheck/updateintervalhours）@deepseek-ai/dsh（npm）新版本；发现新版 → Win11 toast「发现新版本 X → Y」；updateapply: true 时「更新到 vN」一键 npm i -g 并重启 dsh。 |
| v1.5.0 | ✨ Windows 11 现代 UI：菜单改用 fluent 配色 + 跟随系统明/暗主题 + DWM 圆角；菜单项加 MDL2 图标（保留 DeepSeek 鲸鱼品牌）；状态/错误/停止托盘图标改为鲸鱼 + 彩色圆环（不再用系统标准图标，并修复旧 DrawIcon 徽标 WARN）；通知由经典气泡升级为自绘 Windows 11 toast（圆角 + 强调色条 + 鲸鱼 + 点击打开 + 4 秒自关）。新配置：menutheme / toastson / menubicons |
| v1.4.1 | 🪟 打开独立 Chrome 应用窗口：明确「打开面板」与「开启新对话」的走向——打开面板/双击图标→ 打开/激活 Chrome 应用窗口；开启新对话 → 优先在已打开的 Chrome 应用窗口内驱动 GUI 新建会话，不可达时回退 RPC 建会话 + 打开 Chrome 应用；新增 「退出」 菜单（停止 dsh 服务并彻底关闭托盘程序）；配置 chromeapplnk 指向 Chrome Apps\DeepSeek Harness.lnk，为空/失效时自动回退普通标签页。launch.cmd 同步改为打开同一个 PWA 快捷方式（原先硬编码的 Profile 1 与真实 Profile 5 不符） |
| v1.4.0 | 🕵️ 代理监控 + 通知 + 徽章：新增「代理 (Agents)」子菜单（实时运行/等待列表，查看日志、停止）；代理启动/完成/等待输入通知气泡；鲸鱼图标右上角运行数量徽章；新增 agentmonitor / agentpollseconds / agentnotifications / badgeicon / maxagentloglines / agenthistorylines 配置；菜单新增 Русский 语言 |
| v1.3.0 | 🔧 默认端口修正为 3080：此前默认 3090 实为作者本机 profile 覆盖（为与 WSL 实例共存），dsh 开箱默认是 3080（官方 README + 包内补丁确认）；本地配置显式写端口则不受影响 |
| v1.2.0 | 🔥 开启新对话真正生效：UI Automation 驱动 GUI 自身流程，彻底绕开浏览器 localStorage 限制；GUI 不可用时回退 RPC + 新标签页 |
| v1.1.1 | 修复新对话不可见：会话挂到当前工作区 + 唯一 fragment 强制新标签页 |
| v1.1.0 | 正式发布版：配置文件、中英双语、新菜单、通知气泡、看门狗强化 |

📄 许可证

MIT

英文

dsh-tray 是面向 DeepSeek Harness（dsh web）的 Windows 原生托盘开关 + 看门狗。把仓库 URL 交给你的 dsh-agent——你只需复制粘贴，无需做任何其他事。

- 菜单：状态 / 打开面板 / 开启新对话 / 代理 / 重启 / 停止 / 退出 / 复制最近日志 / 随 Windows 启动。（“停止”仅停止服务器；“退出”（v1.4.1）会停止服务器并彻底关闭托盘程序）
- 代理监控（v1.4.0）： 实时“代理”子菜单列出正在运行 + 等待输入的子代理，每项都有 查看日志（显示最近输出的窗口）和 停止；代理启动 / 完成 / 等待时触发原生气泡通知；鲸鱼图标显示运行数量徽章。所有开关均可通过配置控制：agentmonitor、agentpollseconds、agentnotifications、badgeicon、maxagentloglines、agenthistorylines。
- 语言：中文 / 英文 / 俄语（自动跟随系统 UI）。
- 开启新对话通过 UI Automation 驱动 GUI 自身流程——真正打开一个全新的空对话
- Watchdog 管理的是生命周期，而非存活状态：一个存活但缓慢的进程永远不会被杀死；崩溃后以 5 秒 → 30 秒的退避重启；Stop 在 taskkill 之前会验证进程身份
- 配置：复制 dsh-tray.example.json → dsh-tray.json；默认端口 3080（dsh 开箱即用的默认值）
- Chrome App (v1.4.1)： “Open Dashboard”、双击和 New Conversation 会在已安装的 Chrome App (PWA) 窗口中打开 UI（使用自己的 profile-directory + --app-id），而不是新标签页；将 chromeapplnk 设置为 Chrome Apps\DeepSeek Harness.lnk 路径，若未设置/缺失则回退到常规标签页。
- 现代 Windows 11 UI (v1.5.0)： 流畅菜单，跟随系统浅色/深色主题（menutheme: auto|light|dark），带有 MDL2 项目图标（menubicons）和 DWM 圆角；托盘状态图标保持品牌化（鲸鱼 + 彩色圆环），而非使用系统自带的 SystemIcons；通知为自绘的 Win11 toast（圆角、强调色条、鲸鱼图标、点击打开、自动消失）——设置 toastson: false 可回退到经典气泡通知。
- 平滑字体 + 更新检查 (v1.6.0)： 统一的可配置 UI 字体（uifont，默认 Win11 的 “Segoe UI Variable”，自动回退到 Segoe UI；uifontsize）应用于菜单、toast 和 MDL2 图标；MDL2 字形和文本现在使用平滑抗锯齿（Antialias 而非 AntiAliasGridFit）以及进程级 DPI 感知，消除了锯齿/“粗糙”边缘。一个 「Check for Updates」 菜单项加上定期自动检查（updatecheck、updateintervalhours）会轮询 npm 上的 @deepseek-ai/dsh；有新版本时会弹出 Win11 toast “New version X → Y”，并且在 updateapply: true 时，一个 「Update to vN」 项会运行 npm i -g @deepseek-ai/dsh@latest 并一键重启 dsh。
- 需要 npm i -g @deepseek-ai/dsh；Windows PowerShell 5.1+；dsh-tray.ps1 需要 UTF-8 带 BOM（包含非 ASCII 的中文/俄文）——一个不带 BOM 的纯 UTF-8 文件会被当作 ANSI 解码，从而无法解析
- 崩溃循环加固 (v1.7.1)： 重启退避现在真正会升级（5 秒 → 30 秒，restartdelayseconds * min(restarts, 6)），因为崩溃计数器只有在 dsh 再次被确认为 Healthy 时才会重置；在连续崩溃达到 maxconsecutiverestarts（默认 10）次后，托盘会停止自动重启，显示“Needs intervention”状态 + 一条错误 toast，手动 Restart dsh 项会重置计数器。“New Conversation”和“Stop agent”菜单操作会在后台 runspace 上执行其 UI-Automation/RPC 工作，因此点击永远不会阻塞 UI；Read-Config 现在会拒绝垃圾数字配置值，并记录一条 WARN。
- Toast 自动关闭修复 + 深色设计（v1.8.0）： toast 不再永远停留在屏幕上——自动关闭/淡出计时器现在位于脚本作用域注册表以及 toast 自身的上下文中，并且每 250ms 进行一次清扫，强制关闭任何超过 toastduration（默认 4000 ms）+ 2.5 s 的 toast，因此 toast 的生命周期被严格限制。应用现在默认采用深色主题（menutheme: dark），并重新设计了菜单、fluent 颜色表和 toast 的深色调色板；新增 Theme 子菜单（Auto / Light / Dark），可实时切换外观并将 menutheme 持久化到 dsh-tray.json。
- 堆叠 toast + 通知历史（v1.9.0）： toast 不再重叠——它们在右上角垂直堆叠（每个都有自己的槽位，滑入显示），上限为 toastmax（默认 4，超过上限时最旧的会被强制关闭）。每个事件都会获得一个类型图标（info / warning / error MDL2 徽章）和一个操作按钮（Open Dashboard / Restart dsh / Update，可通过 toastactions 切换）；快速发生的同类事件会在 500 ms 内就地刷新顶部 toast（无启动闪烁）。新增 Notifications 子菜单会保留最近 toasthistory 条通知（点击打开仪表板，一键清除）。toast 在 Win11 上支持微妙的 Mica 半透明效果（toasttranslucent，不支持时回退为不透明）。新增配置：toastmax、toastactions、toasthistory、toasttranslucent。