音频提醒插件ellelkktrraaa/dsh-audio-alert

@deepseek-ai/dsh-client-audio-alert

用声音提醒会话中断、向你提问与回合完成——当会话需要你时，播放提示音提醒你回来查看，不用一直盯着界面。node 半注册 audio-alert settings 命名空间；浏览器半订阅会话列表，在三个注意力边界播放声音：审批请求（pendingInteraction 变为 approval 或 plan-review）、ask-user 提问（pendingInteraction 变为 question），以及回合结束（会话的 running 位由 true 翻转为 false）。

声音可通过 audio-alert settings 命名空间逐触发配置（设置 → 插件配置，或 settings.yaml 文档）。每个字段都可选：enabled（默认 true）、volume（默认 0.8，区间 [0, 1]）、approvalSound / questionSound / doneSound，以及 debug（默认 false）。声音字段接受 data URI、http(s)/blob URL、根相对 URL（以 / 开头）或本地文件路径。空字段选择该触发内置的合成音。debug: true 会把解析后的配置与每次播放记录到浏览器控制台与服务端日志。

本地路径（例如 C:/sounds/alert.mp3、~/sounds/alert.mp3 或 ./alert.mp3）由 node 半在运行 dsh web 的机器上读取，并通过 /audio-alert/audio/ 提供给浏览器，因此浏览器自身不接触文件系统。写路径时不要带 data: 或 file: 前缀。

安装教程

前置条件 —— 一个 dsh web 部署（DeepSeek Harness；web 配置文件在首次使用时自动创建）、Node ^22.19 || >=24 和 pnpm。插件会从配置文件自己的 node_modules 解析 @deepseek-ai/* 的 peer 依赖，无需额外安装。

安装 —— dsh plugin 会把参数转发给配置文件目录里的 pnpm：

从 GitHub 安装（推荐；安装时会自动构建）
dsh plugin --profile web add https://github.com/ellelkktrraaa/dsh-audio-alert.git

或从本地目录安装
dsh plugin --profile web add C:\path\to\dsh-audio-alert

卸载（按包名）
dsh plugin --profile web remove @deepseek-ai/dsh-client-audio-alert

配置 —— 在 $DSH_HOME/settings.yaml（默认 C:\Users\\.dsh\settings.yaml）里加一段 audio-alert:：

audio-alert:
enabled: true
volume: 0.8
approvalSound: "C:/sounds/approval.mp3"   # 空 = 内置提示音；或填 data:/http(s) URL
questionSound: "C:/sounds/question.mp3"
doneSound: "C:/sounds/done.mp3"
debug: true

然后重启 dsh web。

验证 —— debug: true 时，浏览器控制台（F12）会打印解析后的配置和每次提醒：

[audio-alert] browser half mounted
[audio-alert] scope changed: {"status":"ready","writable":true,"value":{"enabled":true,"volume":0.8,...}}
[audio-alert] alert kind: approval

触发一次审批、提问或回合结束，听一下声音。

自定义声音的宿主要求 —— 浏览器通过宿主 API 代理读取 audio-alert settings 命名空间，而代理只服务显式白名单里的命名空间。在当前的 DeepSeek Harness 检出中，需要把 'audio-alert' 加进 packages/host/apiproxy/src/api-proxy.ts 的 WEB_SETTINGS_NAMESPACES（不在白名单的命名空间会返回 settings-not-exposed）。没加之前，插件仍会以默认音量播放内置提示音，但自定义声音不会被浏览器读取。

故障排查

- 控制台里完全没有 [audio-alert] 输出 → 浏览器还在用缓存的 client.js；硬刷新（Ctrl+Shift+R）或开一个无痕新标签页。
- scope 卡在 "unavailable" → 宿主没有暴露 audio-alert 命名空间（见上面的宿主要求）。
- 内置提示音会响、但配置的文件不响 → 文件路径必须在运行 dsh web 的机器上存在且可读；服务端日志（debug: true）会打印 [audio-alert] serving approval from ... 或失败原因。
- 第一次声音没响 → 浏览器自动播放策略要求页面先有一次用户手势，先随便点一下页面。

兼容性证据

参照 dsh-plugin-radar 的证据阶梯，本仓库在每一层都提供了对应证据：

| 层级 | 检查 | 状态 |
|---|---|---|
| L0 发现 | topic、可见性、元数据 | 已设置 dsh-plugin topic；仓库公开；package.json 含 keywords / homepage / repository |
| L1 清单 | package.json、名称、入口字段 | @deepseek-ai/dsh-client-audio-alert；main → lib/index.js，exports["./client"] → lib/client.js |
| L2 静态兼容 | 补丁、seam、依赖范围 | seam：audio-alert settings 命名空间（installSettingsSection）、/audio-alert/audio Web 服务路由、浏览器 sessions.list / settingsScope 服务；peer 依赖锁定在 0.1.0-rc.x dsh 家族 |
| L3 编译实验 | 在 workspace 中执行类型/语法检查 | Node 22/24 下 pnpm typecheck（tsc -b）与 pnpm build（tsc -b && tsdown）均通过 |
| L4 运行实测 | 安装、加载、最小任务 | 通过 dsh plugin add 安装（见上方教程）；37 个单元测试通过；debug: true 时浏览器控制台打印 [audio-alert] scope changed: {"status":"ready",...} 及每次提醒 |

已知边界 —— radar 的免责同样适用于本仓库：mainline 与插件都在快速变化，旧结论容易失效；静态通过不代表运行一定成功；编译失败可能来自环境或缺失依赖，而非真正的 API 漂移；上面的运行检查只覆盖此处描述的最小路径。

Model Experience

None, as the plugin only plays a browser sound on live session-list attention edges; nothing here reaches a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

- Done fires on the running edge — a turn ending for any reason (completed, error, aborted) announces once; the sound does not distinguish the reason.
- Autoplay policy — the first sound can be suppressed until the browser has registered a user gesture on the page; playback rejection is contained, never retried.
- First observation is silent — sessions already pending or idle at load do not replay their attention, matching the session list's own reminder semantics.
- Local files are read on the server — the node half reads the file on the machine running dsh web, whole into memory, per request; a path is not portable to another machine.
- Leading-slash paths are URLs — a /-prefixed value is a root-relative URL, never a local file, so a POSIX absolute path must be written ~-relative or cwd-relative instead.