# DSH Windows 通知

简体中文 | [English](README.md)

为 DeepSeek Harness Web 提供 Windows 系统通知、可选提示音和 DSH 风格页面通知卡片。只要 DSH 标签页保持打开，即使正在使用其他软件，也能收到任务结果或待处理事项提醒。

![DSH 通知设置、页面通知卡片与 Windows 系统通知](https://raw.githubusercontent.com/lsq-dsh-plugins/dsh-windows-notifications/main/assets/notification-settings.png)

## 通知规则

默认情况下，同一个事件只会显示 Windows 通知或页面通知，不会两者同时出现。提示音独立于显示方式，可以与其中任意一种通知同时播放。

| DSH 状态 | 默认显示方式 |
| --- | --- |
| 标签页可见且浏览器窗口拥有焦点 | DSH 页面通知 |
| DSH 显示在另一块屏幕，但焦点在其他软件 | Windows 通知 |
| 正在浏览其他标签页或浏览器已最小化 | Windows 通知 |
| Windows 通知不可用或投递失败 | 已启用时回退为页面通知 |

判断依据是浏览器可见性和焦点，而不是显示器数量。如果关闭“仅在 DSH 不活跃时弹系统通知”，DSH 获得焦点时也可能显示 Windows 通知；只要 Windows 通知投递成功，同一事件的页面通知仍会被抑制。

## 通知事件

- 任务正常完成。
- 任务报错、中止、阻塞、异常中断或达到输出上限。
- DSH 正在等待审批、计划确认或问题回答。
- 可选的子智能体完成与失败事件。

点击 Windows 通知会聚焦 DSH 并打开对应会话。插件读取 Harness 持久化的 `turn/end` 结果，不会从短暂的运行状态猜测任务是否完成。首次加载、刷新和重连只建立静默基线，不会把旧事件重新当作新通知。

## 设置

在 DSH Web 中打开**设置 → 通知**。

| 设置 | 默认值 | 作用 |
| --- | --- | --- |
| 启用通知 | 开 | 任务通知总开关 |
| Windows 系统通知 | 开 | 使用浏览器 Notification API |
| 仅在 DSH 不活跃时弹系统通知 | 开 | 正在查看 DSH 时避免系统弹窗 |
| 页面内提示 | 开 | 未投递 Windows 通知时显示 DSH 风格卡片 |
| 提示音 | 开 | 播放 Web Audio 合成提示音 |
| 音量 | 55% | 设置提示音音量 |
| 任务完成 | 开 | 提醒成功完成的任务 |
| 失败与中断 | 开 | 提醒所有非正常结束 |
| 等待你的操作 | 开 | 提醒审批、计划确认和问题 |
| 子任务通知 | 关 | 包含子智能体完成与失败事件 |

Windows 通知、页面通知和声音分别提供独立测试按钮。连续触发 Windows 或页面测试时，新测试会覆盖尚未结束的同类测试，不会不断排队；真实任务通知仍按到达顺序展示。

## 安装

将公开包安装到 DSH Web 配置：

```sh
dsh plugin --profile web add @lsq64737/dsh-windows-notifications
```

如果 DSH Web 正在运行，请在安装后重启。再次执行相同的 add 命令即可更新。

卸载命令：

```sh
dsh plugin --profile web remove @lsq64737/dsh-windows-notifications
```

## 首次启用

1. 打开 DSH Web，进入**设置 → 通知**。
2. 点击**授权通知**。
3. 在浏览器权限提示中选择允许。
4. 分别运行**测试 Windows 通知**、**测试页面通知**和**测试声音**。

浏览器要求通过用户手势申请通知权限，因此插件不会在页面加载时自动弹出权限框。如果此前选择了拒绝，请先在浏览器的站点权限中恢复通知权限，再重新测试。

## 浏览器与 Windows 要求

- DSH 标签页必须保持打开；关闭标签页或浏览器后，通知处理会停止。
- Windows 通知要求浏览器和页面来源能够在受允许的安全上下文中使用 Notification API。
- Chrome 或 Edge 的站点权限以及 Windows“勿扰”设置具有最终控制权，插件无法绕过。
- Windows 决定系统通知的外框、位置和持续时间；插件只提供 DSH 图标、标题、正文和点击操作。
- 浏览器可能限制或冻结长时间未使用的后台标签页，即使 DSH 连接看似仍然活跃，通知也可能延迟。

## 隐私与可靠性

- 插件不使用第三方通知服务。事件只在 DSH Web、浏览器 Notification API、Web Audio 和 Windows 之间处理。
- 通知正文可能包含 DSH 会话标题，因此会按照 Windows 通知设置显示在系统界面或锁屏上。
- 提示音由 Web Audio 合成，不下载音频文件。
- 桌面通知投递失败时，如果页面通知已启用，会回退为页面错误提示或任务卡片。
- 关键路径和异常使用 `windows-notifications:` 前缀写入 Harness 日志或浏览器控制台，包括权限、投递、设置和音频失败，不记录凭据。

## 开发

需要 Node.js 24 或更高版本，以及兼容的 DSH 开发工作区。

```sh
npm ci
npm run typecheck
npm test
npm run build
```

## 许可证

[MIT](LICENSE)