dsh-windows-tray

DeepSeek Harness（dsh）的 Windows 托盘管家：官方鲸鱼状态图标 + Web/TUI 双状态 + 一键启停。 纯 PowerShell + WinForms，零依赖、无编译、不改 dsh 源码，卸载即还原。版本沿革 → CHANGELOG.md。

基础功能公开可用：他人 npm i -g dsh-windows-tray → dsh-tray install；本机自用走源码：install.ps1（见「快速开始」）。备份面默认关闭（见「功能开关」）；包内不含备份引擎，缺引擎显式「未就绪」并给装法（不假装能用、也不谎报失败）。

是什么

把 dsh web 的前台命令行窗口变成标准 Windows 托盘应用：蓝/灰鲸鱼 = Web 运行中/未运行（官方 favicon 生成），菜单顶部 Web/TUI 双状态（含 PID），双击开界面 + 右键按 DSH/TUI 分组一键启停。托盘是独立常驻进程：dsh 停止时它仍在（显示未运行 + 一键启动），退出托盘不影响 dsh。浅色圆角菜单。

前置依赖（先读这条）

本包只含托盘本体，不含备份引擎。 菜单里的 备份 ▸ 需要引擎 dsh-backup.mjs（personal-docs 仓分发，不随本包发布）。装托盘见「快速开始」；装引擎（一次性，都走源码仓不走 npm）：pwsh -File dsh/config/install.ps1 -Only tools。

只装托盘也照常可用（Web/TUI 启停、状态、自更新）；只有「备份」面显式未就绪（气泡给装法，退出码 3）。

定位：作者本人工作流的个人工具（按 personal-docs 约定）；不承诺适配他人环境。

功能特性

| 交互 | 行为 | | :--- | :--- | | 双击 | 打开 Web UI（未运行先提示启动） || 右键菜单 | 顶部 Web UI 状态/TUI 状态/备份 三状态行；Web UI ▸（打开/启动/停止(确认)/重启）；TUI ▸（启动/停止）；备份 ▸（立即备份 / 打开备份目录）；版本信息 ▸（版本/检查更新/更新到最新版）；退出托盘。「立即备份」= data+runtime+vault 三对象各备一次 | | 备份状态（仅开关开启时出现） | 第三行 备份: N h 前 ✅/⚠（对象）：读库内 status.json（30 s 节流），显示最旧对象；异常五文案（未配置 / 损坏 / 从未成功 / 时钟异常 / 上次失败 N h 前）。「立即备份」有过程与结果反馈（气泡 + 状态行 + 菜单置灰）。取舍：只做"可见 + 人工触发"。库位置：$env:DSH_BACKUP_STORE > <DSH_HOME>\backup-store.txt > 自动发现；都没有 ⇒ 首次「立即备份」自动挑盘建库。恢复用引擎 recover 或按 SOP | | 菜单智能禁用 | Web 运行中禁用「启动 Web UI」；TUI 运行中禁用「启动 TUI」 | | 自更新 | 「版本信息 ▸」对比 npm 源 ⇒ npm 安装版可一键更新；本机源码版版本更高时提示「以源码为准」，不会把本地降级 | | 状态通知 | Web/TUI 启停弹通知；就绪弹一次提示 | | 开机自启 | 登录后托盘自动出现 + dsh Web 静默拉起（启动文件夹快捷方式：「DSH 系统托盘.lnk」→ dsh-tray.ps1；「DeepSeek Harness (dsh).lnk」→ dsh-boot.ps1） |

适配与依赖

| 项 | 说明 | | :--- | :--- | | dsh 内核 | 声明（package.json → dshCompatibility）：range = >=0.1.1-rc.2 <0.3.0，testedVersions = 0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-rc.1 / 0.1.5-rc.2 / 0.2.0-rc.2 / 0.2.1-rc.2；install.ps1 软校验（不阻断）。外部工具，不声明 peerDependencies。rc.1 起引入一次性 launch token 鉴权 ⇒ 打开/重启 Web UI 需托盘 ≥1.0.11（解析 web-menu.out.log 的 token 探活；无 token/失效回退裸 URL） | | Web 服务 | dsh web 默认监听 127.0.0.1:3080——托盘用 TCP 探测该端口判断状态（端口改了同步改 dsh-lib.ps1 的 $PORT） | | TUI 插件 | 适配 @deepseek-harness-tui/dsh-tui ^0.9.2（含 0.10.0-beta.4）；托盘按命令行 dsh-tui 检测，与插件版本解耦 | | Node.js / PowerShell | Node ≥ 18；PowerShell 7（缺省回退 5.1） | | 运行时依赖 | 零 npm 依赖——纯 PowerShell + WinForms + 系统 API；不改 dsh、不注入内容 |

界面预览

| 运行中（品牌蓝 #4176E6） | 未运行（中性灰 #81858C） | | :---: | :---: | | | |

图标源 = dsh 官方 favicon（鲸鱼）；node plugins/dsh-windows-tray/bin/dsh-tray.js icons 可重新生成。

快速开始

前置：Windows 10/11 + PowerShell 7（缺失回退 5.1）+ Node.js ≥ 18 + dsh。

# 1. 一键部署（他人：npm i -g dsh-windows-tray + dsh-tray install；本机自用：从源码仓跑这条）
pwsh -NoProfile -ExecutionPolicy Bypass -File plugins/dsh-windows-tray/install.ps1 -Auto -NoTrayStart -EnableBackup

# 2. 唤起托盘（首次；之后随登录自启）：桌面「DSH 系统托盘」
# 3. 首次使用：把任务栏 ^ 溢出区里的鲸鱼拖到任务栏（一次性）

常用命令

| 命令 | 作用 | | :--- | :--- | | node plugins/dsh-windows-tray/bin/dsh-tray.js | 启动托盘（已有实例则提示，不重复启动） | | … bin/dsh-tray.js install | 一键部署 / 重新部署（可透传 -DshRoot 等参数） | | … bin/dsh-tray.js icons | 重新生成鲸鱼图标 | | … bin/dsh-tray.js info | 查看版本 / 安装位置 / 部署状态 |

⛔ npm 与源码是两条通道，别混（dsh-tray 命令与 ~\.dsh\launcher 的来源会分不清）。他人走 npm i -g → dsh-tray install；源码机一律用 node … bin/dsh-tray.js … 或 install.ps1。

功能开关（备份面默认关闭）

备份面默认关：关着时菜单无任何备份痕迹，动作入口也拒绝（exit 4：不 init、不建库、不写库）。

| 项 | 说明 | | :--- | :--- | | 开关 | features.backup（bool，默认 false） | | 位置 | $DSH_HOME\plugin-config\dsh-windows-tray.json（包外 ⇒ 重部署不冲掉） | | 启用 | install.ps1 -EnableBackup · node …\bin\dsh-tray.js features --enable backup · 临时 $env:DSH_TRAY_BACKUP=1 | | 查看 / 关闭 | … features --list · … features --disable backup | | 优先级 | $env:DSH_TRAY_BACKUP（临时、不落盘）> 配置文件 > 默认关；改完需重启托盘 | | 异常 | 配置缺失 ⇒ 默认关（不创建文件）；损坏 / 类型不对 / version 过高 ⇒ 一律按默认关，不抛错、不阻断启动 |

⚠ 开关只管"显不显示"，不会替你装引擎——真要能备份还需 personal-docs\dsh\config\install.ps1 -Only tools。 ⚠ 改开关必须重启托盘：菜单启动时构建、动作闸每次现读 ⇒ 只 --disable 不重启会出现"菜单还在、点下去弹未启用"的混态。

如何更新

# 他人（npm 安装版）：菜单「版本信息 ▸ → 更新到最新版」，或
npm up -g dsh-windows-tray ; dsh-tray install

# 本机源码版：从源码仓重部署
pwsh -NoProfile -ExecutionPolicy Bypass -File plugins/dsh-windows-tray/install.ps1 -Auto -NoTrayStart -EnableBackup
# 然后重启托盘（右键「退出托盘」后重新登录 / 双击桌面快捷方式）

⚠ 两条通道别混（见上 ⛔）。部署目录固定 ~\.dsh\launcher，更新覆盖不残留。

卸载

npm rm -g dsh-windows-tray   # 清掉 npm 全局残留（留着会被误当正身）
# ② 删除快捷方式: 「DSH 系统托盘.lnk」(启动文件夹 + 桌面) + 「DeepSeek Harness (dsh).lnk」(启动文件夹)
# ③ 删除部署目录 ~\.dsh\launcher (如与 dsh 控制台共用, 确认无需保留再删)

工作原理

• 托盘：pwsh 常驻，2s 轮询 127.0.0.1:3080（Web）+ node 命令行含 'dsh-tui'（TUI）；命名互斥锁单实例
• 动作隔离：菜单动作走 dsh-actions.ps1 独立隐藏进程；自更新走 dsh-update.ps1
• 日志：~\.dsh\logs\dsh-windows-tray\（dsh-tray.log / dsh-tray-actions.log / dsh-boot.log）
• 单点配置：端口/路径常量集中在 launcher/dsh-lib.ps1，安装时按本机改写——包与机器无关

配置

| 项 | 位置 | 默认 | | :--- | :--- | :--- | | 监控端口 | ~\.dsh\launcher\dsh-lib.ps1 顶部 $PORT | 3080 | | dsh 路径 | 同上（安装时自动改写） | 自动探测 | | 图标颜色 | build/build-tray-icons.ps1（运行蓝/停止灰） | #4176E6 / #81858C |

常见问题

| 问题 | 处理 | | :--- | :--- | | 停止 Web UI 会关掉浏览器界面 | 对——停止前有确认；Web 与当前会话都在 3080 上 | | 托盘退出了怎么唤回 | 双击桌面「DSH 系统托盘」/ 重新登录 / node plugins/dsh-windows-tray/bin/dsh-tray.js | | 检查更新失败 | 网络或 npm 不可用；托盘继续工作，稍后再试 | | dsh 内核升级了，托盘要动吗 | 不用——只探测 3080 端口与 TUI 命令行，与内核版本解耦 | | 开机后 dsh Web 没自动起 | 看 ~\.dsh\logs\dsh-windows-tray\dsh-boot.log：boot ok (started) = 正常；boot FAILED 后跟错误即原因（隐藏窗口下日志是唯一线索），常见是 ~\.dsh\launcher 被移走/删除 |

文档

• docs/system-tray-guide.md — 使用手册（安装部署 / 功能一览 / 更新 / 卸载 / 故障排查）
• docs/tray-dev-archive.md — 开发归档（架构决策与历史记录）
• CHANGELOG.md — 版本沿革

许可

MIT