dsh-desktop-tray

为 DSH Desktop 提供系统托盘支持：常驻托盘图标 + 设置里开关"最小化到托盘 / 关闭时隐藏到托盘"，并能在应用自动更新后自愈恢复。

System tray support for DSH Desktop: a tray icon plus settings to hide the main window to the tray on minimize or close, with self-healing after application updates.

> ## ⚠️ 重要警示 / WARNING > > 本插件会修改 DSH Desktop 的主程序文件，属于破坏性修改（不是纯只读插件）。 > > 安装后，插件会把托盘代码注入到以下文件（注入前会各备份一份 *.dsh-tray.bak）： > > - resources/app/out/main/index.js > - resources/app/out/preload/index.cjs > - resources/app/package.json（main 改为指向注入启动器） > - 并在 resources/app/out/main/ 新增 tray-boot.js > > 如果 DSH Desktop 无法启动（例如重装/更新过程中出现异常），按以下顺序处理： > > 1. 还原备份：用 out/main/index.js.dsh-tray.bak / out/preload/index.cjs.dsh-tray.bak 覆盖还原对应文件； > 2. 恢复入口：把 resources/app/package.json 的 "main" 改回 "./out/main/index.js"； > 3. 删除启动器：删除 resources/app/out/main/tray-boot.js； > 4. 移除触发条目：编辑 %APPDATA%\dsh-desktop\harness\profiles\web\cordis.patch.yml，删除其中 dsh-desktop-tray 的 - insert: 条目（若 Harness 报 duplicate loader entry id: dsh-desktop-tray，同时检查 resources/dsh-desktop.patch.yml 是否残留同名条目，一并删除）； > 5. 仍然无法启动：重新安装 DSH Desktop（卸载后重装，或覆盖安装最新版）。 > > 如果重装后只想保留插件而 Harness 启动失败，第 4 步通常就能解决——插件本体在 AppData，重装不会清除，只需保证加载条目只有一份。

功能 / Features

• 最小化到托盘 / Minimize to tray — 点击最小化按钮时隐藏到托盘，而不是任务栏。
• 关闭时隐藏到托盘 / Hide on close — 关闭窗口时保持后台运行（默认开启）。
• 立即隐藏到托盘 / Hide to tray now — 一键隐藏主窗口。
• 托盘图标左键单击/双击 → 显示主窗口；右键菜单 → 显示主窗口 / 退出。
• 设置界面：设置 → 系统托盘（Settings → System tray），中英文双语。

安装 / Install

通过 DSH Desktop 的插件市场（dsh-market）安装，或在 web profile 中直接添加：

dsh plugin --profile web add github:wodongx123/dsh-desktop-tray

安装后重启 DSH Desktop（不是只重启 Harness）。首次启动时插件会：

1. 把启动器 out/main/tray-boot.js 安装进应用，并把 package.json 的 main 指向它； 2. 把托盘代码按锚点注入到 out/main/index.js 与 out/preload/index.cjs（原文件先备份为 *.dsh-tray.bak）； 3. 在设置界面注册"系统托盘"页。

工作原理 / How it works

DSH Desktop 是 Electron 应用，托盘只能在主进程里创建，而 Harness 插件运行在独立的 Node 进程里，无法直接调用 Electron API。因此本插件采用"启动时自愈注入"：

应用启动
  └─ main → out/main/tray-boot.js（启动器）
       ├─ 读取插件内的补丁定义（main-patch.js）
       ├─ 检查 out/main/index.js / out/preload/index.cjs 是否已注入
       │    ├─ 未注入 → 按锚点注入 + 备份 + 写标记 // dsh-desktop-tray:patched
       │    └─ 已注入 → 跳过（幂等，绝不重复注入）
       └─ 加载真正的入口 ./index.js

更新自愈：应用自动更新会整体覆盖 resources/app，把注入和启动器全部清掉。本插件的本体安装在 AppData 的 web profile 中（应用更新不会删除），Harness 每次启动时插件会：

• 通过 $DSH_HOME/desktop-app-path.json（启动器写入的"应用位置记忆"）定位应用目录；
• 重新注入主进程代码、重建启动器、恢复 main 指向；
• 清理 app 内补丁的残留条目（resources/dsh-desktop.patch.yml），确保加载条目唯一，避免重装/更新过渡期出现 duplicate loader entry id 导致 Harness 无法启动。

因此更新/重装后第一次启动是无托盘的原始版本，重启一次即自动恢复。如果新版应用的主进程代码结构变化导致锚点失配，插件会跳过注入并记录日志（绝不破坏文件），等插件版本跟进适配。

安全设计 / Safety

• 防重复注入（五重防护）：

1. 幂等标记：已带 // dsh-desktop-tray:patched 的文件不再改动； 2. 锚点消费：注入 = 锚点替换，锚点被消费后无法二次叠加； 3. 内容检测：无标记但内容已存在 → 只补标记，不重复注入； 4. 整体原子性：任一锚点失配 → 整文件不写，不产生半修补文件； 5. 备份 + 原子写：注入前备份 *.dsh-tray.bak，临时文件 + rename。

• 回滚：保留备份，可手工还原（见上方警示步骤）。

卸载 / Uninstall

1. 移除 profile 中的插件：dsh plugin --profile web remove dsh-desktop-tray，并删除 profiles/web/cordis.patch.yml 中的 dsh-desktop-tray 条目； 2. 手动恢复应用文件（如果不再需要托盘）： - resources/app/package.json：main 改回 ./out/main/index.js； - 删除 resources/app/out/main/tray-boot.js； - 用 index.js.dsh-tray.bak / index.cjs.dsh-tray.bak 覆盖还原对应文件。

包结构 / Layout

dsh-desktop-tray/
├── package.json      # 插件清单（dsh.client 声明）
├── index.js          # 服务端守护插件（状态路由 + 补丁守护 + 去重自愈）
├── client.js         # 客户端设置界面（设置 → 系统托盘）
├── main-patch.js     # 主进程补丁定义与注入引擎（纯 Node，五重防重复）
├── boot/
│   └── tray-boot.js  # 启动器模板（写入 out/main/）
└── README.md

License

MIT