# @dingyi222666/dsh-session-notification 中文文档 规范地址：https://npmcn.com/package/%40dingyi222666/dsh-session-notification/ 版本：0\.2\.8 npm 元数据更新时间：2026-11-11T01:34:56.929Z 中文译文更新时间：2026-11-12T10:12:46.721Z 软件包许可：BSD-3-Clause 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dingyi222666/dsh-session-notification 原文对照：https://npmcn.com/package/%40dingyi222666/dsh-session-notification/?lang=original 项目主页：https://github.com/dingyi222666/dsh-session-notification#readme 源码仓库：https://github.com/dingyi222666/dsh-session-notification ## 关键信息（来自 npm 元数据） - 包体积（解压后）：155 kB，20 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2026-08-13T13:42:12.032Z - 最新版本发布：2026-11-11T01:34:56.709Z - 近 30 天下载量：3134（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：20（近 12 个月 20 个） ## 中文简介 Dsh 网络 GUI 的会话状态通知插件: 会话完成/ 失败, 询问, 和权限请求的提醒, 带有可配置的内置或自定义声音和浏览器通知, 以及通知设置部分 ## 安装 ```sh npm install @dingyi222666/dsh-session-notification ``` 也可以使用：`pnpm add @dingyi222666/dsh-session-notification`、`yarn add @dingyi222666/dsh-session-notification`、`bun add @dingyi222666/dsh-session-notification` ## README # 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](https://npmcn.com/package/%40dingyi222666/dsh-session-notification/README.md) 一个给 dsh Web GUI 的通知插件：会话跑完、出错、想问你问题、或需要你授权时，都有提示音提醒；离开当前标签页时，还会弹一条系统通知，让你不用一直盯着。 ## 截图 | 设置面板——侧边栏里的「**通知**」入口与栏目内容 | 每种类型的音效选择器（官方下拉菜单） | | :-- | :-: | | ![通知设置栏目](https://npmcn.com/package/%40dingyi222666/dsh-session-notification/screenshots/01-notifications-section.png) | ![音效选择器](https://npmcn.com/package/%40dingyi222666/dsh-session-notification/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 请求。 ## 常见问题 ### @dingyi222666/dsh-session-notification 是什么？ Dsh 网络 GUI 的会话状态通知插件: 会话完成/ 失败, 询问, 和权限请求的提醒, 带有可配置的内置或自定义声音和浏览器通知, 以及通知设置部分 ### 如何安装 @dingyi222666/dsh-session-notification？ 在项目目录运行 npm install @dingyi222666/dsh-session-notification，或使用 pnpm add / yarn add / bun add。 ### @dingyi222666/dsh-session-notification 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dingyi222666/dsh-session-notification 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @dingyi222666/dsh-session-notification 可以商用吗？ @dingyi222666/dsh-session-notification 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。 ### @dingyi222666/dsh-session-notification 的下载量有多少？ 根据 npm 官方下载统计，@dingyi222666/dsh-session-notification 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,134 次，日均约 104 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dingyi222666/dsh-session-notification 还在维护吗？ 最新版本 0\.2\.8 发布于 2026/11/11（1 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/08/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。