English | 中文
# @7dgroup/dsh-7d-tray-win
**作者：7DGroup**
DeepSeek Harness（dsh）的 **Windows 专属**系统托盘插件。在 `dsh web` 运行期间，系统托盘会自动出现 DeepSeek 鲸鱼图标；服务停止后，托盘图标 3 秒内自动消失——托盘与服务同生命周期。同时自动维护一个静默桌面启动器 `DSH.lnk`，双击即可无窗口启动服务并打开浏览器。
---
## 📌 项目信息
| 字段 | 值 |
|---|---|
| 作者 | 7DGroup |
| 版本 | 0.3.0 |
| 运行平台 | Windows 10/11（win32；其他平台自动跳过） |
| 运行时 | Node `^22.19.0 \|\| >=24.0.0` · pnpm 10+ · dsh CLI |
| 插件名称 | `tray-7d-win` |
| Peer dependency | `@deepseek-ai/cordis` `^4.0.1` |
| 仓库 | [github.com/7dgroup-ai/dsh-7d-tray-win](https://github.com/7dgroup-ai/dsh-7d-tray-win) |
| 许可证 | MIT |
## 🖼️ 插件效果
运行 `dsh web` 后，系统托盘区将出现 DeepSeek 鲸鱼图标，同时桌面会自动生成 `DSH.lnk` 快捷方式：
- **双击图标**：打开 Web UI（端口自动从服务配置读取）
- **右键菜单**：打开 DSH Web / 打开日志文件夹 / 重启服务 / 退出（停止服务）
服务退出（含崩溃）后，托盘图标与托盘代理进程自动消失。
## ✨ 核心功能
- **托盘图标**：官方 DeepSeek 鲸鱼标志；双击打开 Web UI，右键菜单支持打开日志、重启服务、退出。
- **一键重启**：右键 →「重启服务」弹出确认对话框，确认后自动杀掉服务进程树并通过 npx 重新启动 `dsh web`。
- **动态端口解析**：托盘 URL 在运行时从 webserver 服务读取，不硬编码端口——无论用户配置了什么端口都能正确打开。
- **生命周期同步**：无论通过桌面快捷方式、命令行还是脚本启动 `dsh web`，托盘都会自动出现；服务退出后托盘 3 秒内自动消失。
- **静默桌面启动器**：自动维护桌面 `DSH.lnk`，双击后无任何窗口，服务在后台启动并自动打开浏览器。
- **自带干净启动链**：内置 PowerShell 启动脚本与 npmmirror 镜像源配置，避免宿主环境变量污染，国内网络也可正常启动。
- **零核心改动 / 官方升级无影响**：纯 Cordis 组合层插件，仅通过 `cordis.patch.yml` 在 profile 组合层中插入一行；不覆盖、不修改 DSH 官方包内的任何文件。执行 `dsh plugin remove` 即可恢复原始状态；只要 Cordis 生命周期保持兼容，升级 DSH 官方版本不会与本插件产生冲突。
## ✅ 功能清单
- ✅ Windows 系统托盘自动显隐
- ✅ 双击托盘打开 Web UI
- ✅ 右键菜单：打开 DSH Web / 打开日志文件夹 / 重启服务 / 退出
- ✅ 一键重启（带确认对话框）
- ✅ 动态端口解析（从 cordis 运行时读取，不硬编码端口）
- ✅ 服务停止后托盘自动清理
- ✅ 静默桌面启动器 `DSH.lnk` 自动维护
- ✅ 首次启动时自动编译 .NET 启动器（需 .NET Framework 4）
- ✅ 每次启动自动刷新插件携带的最新资源
- ✅ 非 win32 平台自动跳过，不报错
## 📂 项目结构
```
dsh-7d-tray-win/
├── assets/ # 随包发布的资源文件
│ ├── DSH.ico # 托盘图标
│ ├── tray-agent.ps1 # 托盘代理脚本
│ ├── starter.ps1 # dsh web 启动链脚本
│ ├── starter-launcher.cs # 静默桌面启动器源码
│ └── make-shortcut.ps1 # 桌面快捷方式维护脚本
├── lib/ # 运行时入口
│ └── index.js # Cordis 插件：托盘控制逻辑
├── cordis.patch.yml # 组合层补丁
├── package.json
├── LICENSE
├── README.md
└── README.zh.md
```
## 🚀 快速开始
### 环境要求
- Windows 10/11（win32）
- Node.js `^22.19.0 || >=24.0.0`
- pnpm 10+
- `.NET Framework 4`（系统自带，用于一次性编译静默启动器）
- PowerShell（系统自带）
### 安装到 `web` profile（推荐）
大多数会话默认启动 `web` profile（`dsh web` 是 `dsh --profile web` 的简写），因此推荐直接安装到 `web` profile：
```powershell
dsh plugin --profile web add @7dgroup/dsh-7d-tray-win
```
或从本地路径安装（开发/测试时）：
```powershell
dsh plugin --profile web add C:\path\to\dsh-7d-tray-win
```
安装后启动 `dsh web`，托盘图标与桌面快捷方式即自动生效。
### 安装到其他 profile
如果你使用自定义 profile，请将上述命令中的 `web` 替换为对应的 profile 名称。插件只在它被安装到的 profile 中生效。
## 💡 使用说明
### 托盘图标交互
| 操作 | 行为 |
|---|---|
| 双击图标 | 打开 Web UI（端口自动检测） |
| 右键 → 打开 DSH Web | 打开 Web UI（端口自动检测） |
| 右键 → 打开日志文件夹 | 打开 `%LOCALAPPDATA%\dsh-7d-tray-win\` |
| 右键 → 重启服务 | 确认后杀掉并重启 `dsh web` |
| 右键 → 退出 | 停止 dsh web 服务并关闭托盘 |
### 静默桌面启动器
插件首次启动时会编译 `starter-launcher.cs` 为 `starter-launcher.exe`，并生成/刷新桌面 `DSH.lnk`。此后：
- 双击桌面 `DSH.lnk` → 无任何窗口弹出
- `dsh web` 在后台启动（端口从 cordis 配置读取）
- 浏览器自动打开 Web UI
- 系统托盘出现 DeepSeek 鲸鱼图标
## 📁 运行时目录
所有运行资源与日志存放在 `%LOCALAPPDATA%\dsh-7d-tray-win\`：
| 文件 | 用途 |
|---|---|
| `DSH.ico` | 托盘图标 |
| `tray-agent.ps1` | 托盘代理脚本 |
| `starter.ps1` | dsh web 启动链脚本 |
| `starter-launcher.cs` | 静默启动器源码 |
| `starter-launcher.exe` | 编译后的静默启动器 |
| `make-shortcut.ps1` | 快捷方式维护脚本 |
| `dsh-launch.log` | 服务启动链日志（npx/dsh 输出） |
| `tray-agent.log` | 托盘代理生命周期日志 |
| `plugin-debug.log` | 插件 apply/spawn/卸载调试日志 |
每次服务启动时，插件都会将携带的最新资源刷新到该目录。
## ⚠️ 注意事项
1. **Windows 专属**：插件在检测到非 `win32` 平台时会自动跳过，不会安装托盘或报错。
2. **首次编译**：首次运行需要 .NET Framework 4 编译静默启动器；若缺少 `csc.exe`，桌面快捷方式功能将不可用，但托盘功能不受影响。
3. **启动器无托盘**：`DSH.lnk` 本身不显示托盘；托盘由本插件在 `dsh web` 运行时提供。
4. **资源刷新**：每次 `dsh web` 启动都会覆盖 `%LOCALAPPDATA%\dsh-7d-tray-win\` 下的资源文件为插件携带的最新版本，请勿在该目录中存放需要持久化的自定义文件。
5. **动态端口**：托盘图标 URL 在运行时从 `webServer` cordis 服务读取，自动跟随 `dsh web` 实际监听的端口——无论是通过 `cordis.patch.yml` 还是 `--port` 参数自定义的端口都能正确打开。
6. **官方版本升级无影响**：本插件是纯 Cordis 组合层插件，不覆盖、不修改 DSH 官方包内的任何文件；只要 Cordis 生命周期保持兼容，升级 DSH 官方版本不会破坏本插件。
7. **建议单实例运行**：所有运行中的实例共享运行时目录 `%LOCALAPPDATA%\dsh-7d-tray-win\` 与桌面快捷方式 `DSH.lnk`；若同时运行多个 `dsh web` 实例，后启动的实例会覆盖共享文件，请同一时间只运行 1 个实例。
## ❓ 常见问题
**Q: 安装时提示找不到 pnpm？**
A: `dsh plugin` 会调用 pnpm 安装依赖，请确保 pnpm 已安装并在 PATH 中：
```powershell
npm install -g pnpm@10
```
**Q: 托盘图标没有出现？**
A: 请确认：
- 当前系统为 Windows 10/11；
- 插件安装到了你实际启动的 profile（默认是 `web`）；
- `dsh web` 已成功启动；
- 查看 `%LOCALAPPDATA%\dsh-7d-tray-win\plugin-debug.log` 与 `tray-agent.log` 排查错误。
**Q: 桌面快捷方式没有生成？**
A: 检查 `%LOCALAPPDATA%\dsh-7d-tray-win\plugin-debug.log` 中是否有 `csc.exe not found` 或 `launcher compile failed` 日志。首次运行需要系统自带 .NET Framework 4。
**Q: 如何卸载？**
A: 运行：
```powershell
dsh plugin --profile web remove @7dgroup/dsh-7d-tray-win
```
然后可手动删除 `%LOCALAPPDATA%\dsh-7d-tray-win\` 与桌面 `DSH.lnk`。
**Q: 可以在非 win32 平台安装吗？**
A: 可以安装，但插件会自动跳过，不会创建托盘或快捷方式。
**Q: 升级 DSH 官方版本会影响本插件吗？**
A: 不会。本插件是纯 Cordis 组合层插件，仅向 profile 的 `cordis.patch.yml` 添加一行；不覆盖、不修改 DSH 官方包内的任何文件。只要 Cordis 生命周期保持兼容，官方版本升级后本插件继续生效。
## 📄 许可证
[MIT](LICENSE) · Copyright (c) 2026 7DGroup