dingyi222666/dsh-session-notification

中文 | English

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

截图

设置面板——侧边栏里的「通知」入口与栏目内容	每种类型的音效选择器（官方下拉菜单）

安装

# 从 npm 安装（需要 dsh >= 0.2.0-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 与桌面端一致）；「测试通知」按钮可以在授权后立即验证系统通知通道。默认不打扰你正在读的会话——它的动静不会打断你；想要它也有提示的话，打开「当前会话也提醒」开关即可。

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

桌面端（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，判定为失败，否则为完成（被重试挽回的失败按完成处理）。
• 待交互边沿出现 question / approval 时，触发问问题 / 权限请求通知，正文带问题文本或工具名+原因。
• 插件加载时已经空闲（或已经在等待交互）的会话不会触发任何通知。

开发

• yarn run build —— 构建浏览器包（lib/client.js）与 Node 半区（lib/index.js / lib/invariant.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.0-rc.2：@deepseek-ai/dsh-* 类型作为 devDependencies（^0.2.0-rc.2；@deepseek-ai/cordis ~4.0.4、@deepseek-ai/schemastery ~3.18.4，与 dsh 包的 peer 依赖一致）从 npm 安装，不再需要检出路径映射。
• Node 半区改动需要重启 dsh web；浏览器包改动重新 yarn run build 即可（--dev 模式会自动热更新）。

已知限制

• 失败判定读取会话的对话快照，而客户端只为「打开过」的会话维护快照；从未打开过的会话若运行失败，会按「完成」通知。
• 浏览器通知需要授权，声音播放需要页面获得用户激活（浏览器自动播放策略）——浏览器应用的常态，用户与界面交互一次即可解决。
• 自定义音频存在浏览器本地（localStorage），不会跨浏览器或跨 profile 同步。
• 浏览器端是基于会话列表快照的事件驱动，不直接读原始事件流；理论上两次快照之间开始又结束的运行可能漏报（宿主对每个边沿都会下发状态帧，实际不会发生）。

模型体验

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

KV Cache 影响

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