dsh-agent-alert

Readme

# dsh-agent-alert

> DeepSeek Harness 任务状态提醒插件：当智能体任务完成、出错或等待审批时，弹出 Windows 浏览器通知并播放提示音。
> Desktop alert plugin for DeepSeek Harness: pops a Windows browser notification and plays a sound when the agent finishes a task, errors out, or awaits approval.

**中文** | [English](README.en.md)

---

## 这是什么

dsh-agent-alert 是 DeepSeek Harness（DSH）的桌面提醒插件：它监听智能体运行状态，在以下三种时刻提醒你回到页面：

| 状态 | 通知标题 | 说明 |
| --- | --- | --- |
| 回答完成 | DeepSeek 回答完成 | 一次回答已完成，可以回来继续操作 |
| 出错 | DeepSeek 出错 | 任务异常（附加错误信息） |
| 等待审批 | DeepSeek 等待审批 | 有操作需要你在页面确认 |

## 提醒方式

1. **浏览器通知**：Windows 系统通知（`Notification`），点击可聚焦回页面；
2. **标题闪烁**：标签页标题短暂加上 "BELL …" 前缀；
3. **页面提示音**：Web Audio 双音哔声（可选）；
4. **PowerShell 提示音**：Node 端通过子进程静默播放（`[console]::beep` 双音，或系统 WAV 文件）。

同类提醒 1 秒内只触发一次，避免刷屏。

## 安装

```bash
npm exec -- dsh plugin --profile web add dsh-agent-alert
```

或者直接从 GitHub 仓库安装：

```bash
npm exec -- dsh plugin --profile web add github:DeepVite/dsh-alert
```

也可以作为本地工作区包放入 web profile，并在 `cordis.patch.yml` 中插入：

```yaml
- insert:
    - id: dsh-agent-alert
      name: 'dsh-agent-alert'
```

安装完成后重启 dsh web 并刷新页面。

## 配置

`config.json`（包根目录）所有字段均可省略，缺省值如下：

| 字段 | 缺省 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 总开关 |
| `states.done` | `true` | 完成时提醒 |
| `states.error` | `true` | 出错时提醒 |
| `states.approval` | `true` | 等待审批时提醒 |
| `sound.enabled` | `true` | 声音开关 |
| `sound.kind` | `"beep"` | `beep` 或 `wav` |
| `sound.beepFreq` | `880` | beep 基频（Hz） |
| `sound.beepDurationMs` | `300` | beep 时长（ms） |
| `sound.wavPath` | `C:\Windows\Media\Windows Notify.wav` | wav 模式播放的文件 |
| `browserNotify` | `true` | 浏览器通知开关 |
| `pollIntervalMs` | `1000` | 浏览器端轮询间隔（ms） |
| `queueCap` | `50` | 通知队列上限 |

## 通知权限

浏览器通知需要用户授权：页面首次点击时插件会自动请求 `Notification` 权限；也可以到 **设置 → 常规** 的 dsh-agent-alert 状态行点击"测试"按钮验证（会同时播放声音并闪烁标题）。

## 工作原理

- **Node 端**（`lib/index.js`）：监听 Agent 状态事件，通过子进程播放 PowerShell 声音，并把提醒事件写入 `/dsh-alert/state` 队列；
- **浏览器端**（`lib/client.js`）：轮询 `/dsh-alert/state`，弹出系统通知、闪烁标题、播放页面提示音。

## 版本与许可

- [CHANGELOG.md](CHANGELOG.md)
- [Apache-2.0](LICENSE)

欢迎通过 [Issues](https://github.com/DeepVite/dsh-alert/issues) 反馈与贡献。