ejie-dsh-notify-plugin

Readme

# dsh-email-notify

**DeepSeek Harness 通知插件。** 当工具需要审批、DSH 向你提问、或一个轮次完成时，本插件会以**两种独立方式**通知你：通过 [Resend](https://resend.com) 邮件 API 向你配置的邮箱发送邮件（即使你关掉浏览器、或人在手机上也能收到）；以及当你正在浏览其他标签页时，弹出**浏览器系统通知**——不同事件使用不同的提示音和通知。

## 特性

- **审批** → 发邮件（`approval/asked`）和/或桌面通知
- **提问** → 发邮件（`ask_user_question` 工具）和/或桌面通知
- **轮次完成** → 发邮件（`turn/end`）和/或桌面通知
- **邮件**随 DSH 主机进程服务端运行，无需浏览器；**系统通知**在浏览器内运行（两者各有独立开关）
- **不同提示音 + 通知栏**：审批、提问、轮次完成分别触发不同的系统通知提示音，并使用不同标记的通知
- **设置页**：独立的 **设置 → 通知设置** 页面，可开关邮件通知、填写收件邮箱/发件邮箱/API Key，并**单独**配置系统通知（事件勾选 + 浏览器权限请求）
- **测试按钮**：先发一封测试邮件验证可用
- **至多一次**：每个事件只发一封邮件、一条通知（重连 / 回放不会重复）
- **自动重试不打扰**：因临时限流（HTTP 429 / `RATE_LIMIT`）结束的轮次不会当作「轮次完成」通知——DSH 自身的重试/退避会自动处理，无需你介入；只有真正完成的轮次，或停下来需要你处理的轮次才会通知。

## 安装

本插件是一个 DSH **bundle**，通过标准 `dsh plugin` 机制安装到 `web` profile（无需改动 DSH 源码）：

```sh
dsh plugin --profile web add ejie-dsh-notify-plugin
```

安装完成后**重启 Web UI** 并刷新浏览器页面即可生效。

> 本地开发安装方式：
> ```sh
> dsh plugin --profile web add /path/to/dsh-email-notify
> ```

### 升级

```sh
dsh plugin --profile web update ejie-dsh-notify-plugin
```

### 卸载

```sh
dsh plugin --profile web remove ejie-dsh-notify-plugin
```

## 配置

重启后打开 **设置 → 通知设置**：

**邮件事件：**
1. 打开「启用邮件通知」
2. 填写**收件邮箱**
3. 填写**发件邮箱**（必须是你在 Resend 里验证过的域名下的地址）
4. 粘贴你的 **Resend API Key**（在 https://resend.com/api-keys 创建）
5. 选择要邮件通知的事件（审批 / 提问 / 轮次完成）
6. 点「发送测试邮件」验证能否收到

**系统通知（与邮件独立）：**
7. 打开「启用系统通知」，选择要通知的事件，然后点「开启系统通知权限」（浏览器会请求一次授权，必须由用户点击触发）

最后点「保存」。你的邮箱、API Key 和两个开关都保存在本机 `<dshHome>/email-notify.json` 中；邮件字段仅供主机进程发信使用，除发送通知或测试邮件时发给 Resend API 外不会离开你的机器，系统通知则完全在你的浏览器内处理。

## 开发与验证

```sh
DSH_CHECKOUT=/path/to/dsh node scripts/build.mjs   # tsc + tsdown -> lib/
DSH_CHECKOUT=/path/to/dsh npx vitest run             # node + client 测试
```

`lib/` 已提交，消费者无需构建即可安装。测试覆盖设置归一化、事件路由与去重、以及 Settings 行（jsdom）。

## 社区

如有可复现的问题、功能建议或使用疑问，请在承载本包的仓库提交 issue；安全漏洞请私下联系维护者。

## License

BSD-3-Clause