# dsh-session-notification

[![npm version](https://img.shields.io/npm/v/@dingyi222666/dsh-session-notification.svg)](https://www.npmjs.com/package/@dingyi222666/dsh-session-notification)

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

一个给 dsh Web GUI 的通知插件：会话跑完、出错、想问你问题、或需要你授权时，都有提示音提醒；离开当前标签页时，还会弹一条系统通知，让你不用一直盯着。

## 截图

| 设置面板——侧边栏里的「**通知**」入口与栏目内容 | 每种类型的音效选择器（官方下拉菜单） |
| --- | --- |
| ![通知设置栏目](screenshots/01-notifications-section.png) | ![音效选择器](screenshots/02-sound-menu-open.png) |

## 安装

```sh
# 从 npm 安装（需要 dsh >= 0.2.1-rc.2）
dsh plugin --profile web add @dingyi222666/dsh-session-notification
# 重启 dsh web 后生效
dsh web
```

一切都在插件自身实现——不依赖 harness（宿主）的任何改动：

- 设置栏目通过客户端 slot 系统（`settings.section`）注册，与官方栏目做法一致。
- 偏好存在浏览器本地（localStorage）并跨标签页同步；不需要宿主设置命名空间或任何其他宿主包改动。（dsh 0.1.7 的插件配置表单直接由 Loader 条目派生，Node 半区已无命名空间可保留，保持惰性。）
- 设置外壳只给它自己认识的栏目 id 配导航图标，所以「通知」导航行显示的是外壳默认的齿轮。

## 四种通知类型

| 类型 | 触发时机 | 默认音效 |
| --- | --- | --- |
| 会话完成 | 一轮会话正常结束（`turn/end` completed） | 叮咚 |
| 会话失败 | 一轮会话出错中断，或宿主上报 agent 错误 | 低鸣 |
| 问问题 | Agent 正在等你回答（`question/requested`） | 轻响 |
| 权限请求 | Agent 请求执行需要授权的操作（`approval/requested`） | 警示 |

每种类型都可以单独开关，也可以把提示音换成四种内置音效中的任意一种（或静音）。四种音效全部用 Web Audio 实时合成——不携带任何音频文件——整体音量用官方风格的滑块调节（0–100%）。播放链路带固定响度增益（约 +6 dB）和软限幅器，所有声音都明显更响且不失真；自定义音频走同一条链路。播放结束后共享 AudioContext 会立即挂起、下次响铃再恢复，闲置通知不会一直占着系统音频流（以及 macOS 的防睡眠断言）。

## 自定义音频

除了四种内置音效，每种类型还可以**上传你自己的音频文件**（mp3/ogg/wav，最大 1 MB）：在对应类型那一行点「自定义音频」上传，之后该类型就用它代替内置音效——支持「更换」和移除，并显示「已使用自定义音频」标签。自定义音频存在浏览器本地（音频属于设备资源，不放进共享偏好）。

## 浏览器通知与「不打扰」默认

浏览器（系统级）通知**默认关闭**；打开开关时会先向浏览器申请授权（需要一次点击手势）。授权后，当事件所属的会话不是当前正在读的会话、或标签页在后台时，才会弹系统通知。**通知使用网页自身的图标**（harness 提供的 favicon）。**完成的会话，通知正文会带上它的最终回复文本**（最后一条 assistant 消息）；**点击通知**会聚焦页面并打开对应会话（Web 与桌面端一致）；「测试通知」按钮可以在授权后立即验证系统通知通道。

**当前会话默认不打扰**——你确实在看它时不会打断你。通过「**当前会话提醒时机**」下拉菜单可以放宽这一层级：

| 你正在读的会话，而你…… | 仅后台或最小化（默认） | 切到其他应用时 | 始终提醒 |
| :--- | :---: | :---: | :---: |
| DSH 在前台、正看着它 | 🔕 静默 | 🔕 静默 | ✅ 提醒 |
| 切到了其他 App（DSH 仍露在屏幕上） | 🔕 静默 | ✅ **提醒** | ✅ 提醒 |
| 标签页切后台 / 窗口最小化 | ✅ 提醒 | ✅ 提醒 | ✅ 提醒 |

**「通知范围」**三选一（默认 **主会话 + 等子会话**）：*全部会话* 连子会话一起提醒；*只主会话* 主会话一结束就提醒；*主会话 + 等子会话* 则等它派生的所有子会话都跑完再提醒一次，中间的空档不会提前打断你（失败仍然立即提醒）。

## 桌面端（Desktop）

插件在 dsh 桌面应用（Electron 外壳）里原样运行——外壳加载的是同一套 Web 客户端与插件图。桌面通知走**系统原生通知**：外壳默认授予通知权限，因此打开「浏览器通知」开关即可，不会再弹授权框。通知使用**应用图标**（网页端用页面 favicon；`dsh-app://` 下会跳过页面图标，让打包后的应用图标生效），并在系统层标记为**静音**——插件的 Web Audio 是唯一音源，系统通知音不会和提示音叠加；点击通知会经外壳的应用激活恢复并聚焦窗口、并打开该会话的对话——关闭窗口只是隐藏、不会退出。

desktop profile（`$DSH_HOME/profiles/desktop`）由桌面应用独占，CLI 会拒绝管理，因此请从桌面应用的 **设置 → 插件（Plugins）** 页面安装本插件，而不是 `dsh plugin --profile desktop`。偏好存在该渲染进程本地，与 Web profile 相互独立。

## 通知设置栏

插件在设置面板注册了一个「**通知**」栏目（设置 ⚙ → 通知）：

- **浏览器通知**总开关（含授权状态与「授权」按钮），
- **当前会话提醒时机**下拉菜单（仅后台或最小化 / 切到其他应用时 / 始终提醒），
- **通知范围**选择（全部会话 / 只主会话 / 主会话 + 等子会话），
- **提示音**总开关，
- **音量**滑块（0–100%），
- 每种通知类型一行：启用开关、自定义音频上传、音效选择（官方下拉菜单）、以及「试听」按钮，
- 浏览器通知行上的「测试通知」按钮（授权后一键验证系统通知通道）。

偏好保存在**浏览器本地**（localStorage）的 `dsh-session-notification` 键下——无需宿主放行任何设置命名空间——跨会话持久化、跨标签页同步，完全不依赖宿主改动。

## 工作原理

浏览器端监听会话列表快照和每个会话的对话快照——无需轮询、无需新增链路：

- 会话 `running` 由 true→false 表示一轮运行结束；运行期间若出现了新的 `turn-error` 节点或宿主 `agent-error`，判定为**失败**，否则为**完成**（被重试挽回的失败按完成处理）。
- 当宿主还持有会自动开启下一轮的工作（排队中的后续输入，或驱动器仍要跑的 goal 轮次）时，「完成」不触发：这个空闲边沿只是暂停，由续跑自身结束后的边沿通知。完成 / 失败通知的标题取本轮最后一条用户消息，没有时才回落到会话标题。
- 待交互边沿出现 `question` / `approval` 时，触发问问题 / 权限请求通知，正文带问题文本或工具名+原因。
- 插件加载时已经空闲（或已经在等待交互）的会话不会触发任何通知。

## 开发

- `yarn run build` —— 构建浏览器包（`lib/client.js`）与 Node 半区（`lib/index.js`）。
- `src/client/notification-service.ts` —— 引擎（事件判定）与分发器（开关/音效/通知门控）；`src/client/settings-store.ts` —— 设置栏桥接；`src/client/NotificationsSection.tsx` —— 设置栏 UI；`src/client/sounds.ts` 与 `src/client/custom-audio.ts` —— 内置与自定义音效。
- `yarn test` —— 行为测试；`yarn run typecheck` —— 类型门禁。
- dsh 0.2.1-rc.2：`@deepseek-ai/dsh-*` 类型作为 devDependencies（`^0.2.1-rc.2`；`@deepseek-ai/cordis` ^4.0.5、`@deepseek-ai/schemastery` ^3.18.5，已转为正式版，与 dsh 包的 peer 依赖一致）从 npm 安装，不再需要检出路径映射；0.2.1 这一线（自 alpha.1 起）移除了运行时 invariant 插件机制，因此原来的 `./invariant` 伴生模块已删除。
- Node 半区改动需要重启 `dsh web`；浏览器包改动重新 `yarn run build` 即可（`--dev` 模式会自动热更新）。

## 已知限制

- 失败判定读取会话的对话快照，而客户端只为「打开过」的会话维护快照；从未打开过的会话若运行失败，会按「完成」通知。
- 浏览器通知需要授权，声音播放需要页面获得用户激活（浏览器自动播放策略）——浏览器应用的常态，用户与界面交互一次即可解决。
- 自定义音频存在浏览器本地（localStorage），不会跨浏览器或跨 profile 同步。
- 浏览器端是基于会话列表快照的事件驱动，不直接读原始事件流；理论上两次快照之间开始又结束的运行可能漏报（宿主对每个边沿都会下发状态帧，实际不会发生）。
- goal 的激活状态（activation）是进程内的，不上线：`active` 但未激活的 goal（例如进程重启后）会被当成仍会续跑，它的空闲边沿不会通知，直到 goal 变化或被重新恢复。
- 后台任务的列表只会为你正在查看的会话加载，因此「任务结束后唤醒空闲会话」在那一刻对客户端不可见；这种唤醒仍可能提前产生一次完成通知。

## 模型体验

无。插件是纯客户端观察者，只读已记录的会话状态，不会进入任何模型请求。

#### KV Cache 影响

无；本包既不组装也不发送 provider 请求。