提示音提醒 minti2/dsh-sound-alerts

dsh-sound-alerts

为 DeepSeek Harness Web UI 提供可听见的提示音。当一轮对话结束、harness 阻塞等待你批准或回答、或者某一轮出错时，浏览器里会播放声音——这样你在长时间运行时可以走开，仍然知道它什么时候需要你。

这是一个 Cordis 打包，一半是 Host 端，负责检测提醒；一半是浏览器端，负责播放声音。

安装

dsh plugin --profile <name> add github:minti2/dsh-sound-alerts

安装就这一步。dsh plugin 会转发给 pnpm，并把打包追加到配置档的 dsh.profile.bundles，不需要手动改任何东西。

这个包是纯 JavaScript，没有构建步骤，这对 git 安装很重要：git 拉取的是源码而不是构建产物，所以 TypeScript 插件需要 prepare 脚本，再加一个 pnpm-workspace.yaml 构建白名单，授权它在安装时于你机器上执行代码。这里没有构建，所以没有白名单，也没有安装时执行代码。

装进智能体自己的配置档要用插件管理器：

plugin_manager action: install_bundle
target: /path/to/dsh-sound-alerts

什么会触发声音

| 提醒 | Harness 事件 | 何时播放 |
| attention | approval/request、user-questions/request | harness 阻塞，等你批准某个操作或回答某个问题。 |
| turnEnd | agent/turn-stopping | 这一轮即将结束，模型不再需要继续回应。 |
| error | agent/error | 某一步或某一轮出错。 |

attention 是值得你抬头看一眼的提醒，它覆盖 harness 请求的每一次批准——包括工具试图往工作区外写入时弹出的沙箱升级提示。packages/sandbox/sandbox/src/escalation.ts 把这些都走 ctx.approval.request(...)，而这正是本插件监听的事件。

三种声音

每种提醒用不同的乐器，而不是同一个哔声换三个音高。三种声音都在浏览器里用振荡器合成，所以不下载任何东西，也不调用操作系统的音频工具。

| 提醒 | 音色 | 音型 |
| turnEnd | 温暖的加法分音 | 上行纯五度，B3 → F#4 |
| attention | 非谐波钟声分音 | 上行琶音，E4 → G#4 → B4 |
| error | 失谐奇次谐波，拍频 | 下行音型，E3 → C3 → G2 |

连 turnEnd 和 attention 都不共用分音结构：attention 用的是让钟声鸣响的非谐波比例，而 error 让两个声部彼此失谐，声音产生拍频，听起来就不对劲。

配置

Config 是一个 Schemastery schema，浏览器端提供对应的表单，所以下面每个字段都能改，不用碰文件：Settings → Plugins → dsh-sound-alerts → sound-alerts 那一行的 configure 控件。它每条提醒配一个开关，子代理静默配一个开关，音量配一个滑块。
编辑会持久化，走的正是手动编辑会用的那层配置档补丁。

这些控件需要三样东西，缺任何一样都会在某个不同的地方悄无声息地失效。schema 是 Host 校验的依据。每个字段上的 .volatile() 才让它进入设置文档：服务只投影 volatile 字段，并丢弃 volatile 投影为空的条目，所以普通字段永远到不了 UI。行的 plugins.row.config 贡献才把它画出来。插件可以报告 status: "schema"，却仍然在任何地方都不显示控件。

编辑在下一次提醒时生效，而不是等到下次重启：volatile 字段解析为访问器，所以插件每次发布时读取它们的当前值，而不是在激活时做快照。

同样的字段也可以直接在配置档的 cordis.patch.yml 里设置：

- id: sound-alerts
name: dsh-sound-alerts
config:
alerts:
turnEnd: true # chime when a turn finishes
attention: true # chime when the harness waits on you
error: true # chime when a turn errors
quietSubagents: true # silence turnEnd and error from subagent sessions
volume: 0.25 # peak gain of every chime, 0..1

注意：

- volume 是控制音量的唯一旋钮。 它随每个提醒帧一起传输，在浏览器里应用，所以调它不需要动提示音。
- quietSubagents 只覆盖 turnEnd 和 error。关注提醒始终会响：请求被阻塞就需要人来处理，无论哪个智能体发起的。
- 在线改配置会重连你的标签页。 应用新配置会销毁并重新注册提醒路由；销毁器会结束已打开的流，所以浏览器会重新打开它们，而不是抱着一条死流。
- 无效值会在激活时失败，并指出出错的路径，所以拼写错误绝不会悄悄禁用某条提醒。

为什么由 Host 检测、由浏览器播放

两边都无法同时做这两件事。

检测必须在 Host 上。 approval/request 和 user-questions/request 是瀑布事件。Harness 应用为两者都注册了自己的监听器，它把请求转发给已连接的 UI 并返回你的回答；当 UI 回答时，那个监听器会 resolve，不调用 next()，于是链上其余部分被跳过。Host 这一半用 prepend: true 注册，因此在应答监听器运行之前就观察到请求。浏览器这一半没有对应能力：ctx.remote.$on 不接受任何选项，而内置的审批面板和提问面板总是先注册，所以浏览器侧的观察者永远到不了。

播放必须在浏览器里。 它能到达你实际坐着的机器，在 Host 远程运行或跑在容器里时也能用，而且不需要 afplay/paplay/PowerShell 播放器。

两半通过一条 Server-Sent Events 路由 /sound-alerts/events 连接，浏览器那一半用 EventSource 订阅它。

验证

pnpm install # supplies the dev dependency the check imports
node scripts/self-check.mjs

检查默认值能否解析、非法值是否被拒绝，检查 Config 是不是原生 Schemastery 图、每个字段是不是 volatile（丢掉任意一项都会悄悄移除设置控件），检查路由和四个监听器是否注册，检查告警流能否打开、是否拒绝非 GET 请求、能否在流写到一半挂掉时存活，检查子代理回合是否保持安静而 attention 仍然触发，检查两个 waterfall 监听器是否都用 next() 继续往下传，检查销毁是否结束打开的流，以及每个已发布的告警类型是否都有对应的浏览器声音。

这个检查会导入 @deepseek-ai/schemastery。运行时由 Host 通过配置档解析层提供，检查本身则由 devDependencies 提供。没有安装这一步，模块就解析不了。

已知限制

- 仅限 Web UI。 插件需要 Host 的 web 服务器，所以在无头配置档里保持不激活。没有终端告警。
- 低音需要能还原它的扬声器。 error 最低到 98 Hz，turnEnd 最低到 247 Hz。笔记本扬声器大约在 150 Hz 以下就开始衰减，所以最低的基频靠泛音承载，而不是直接还原；如果低音告警听起来单薄，就在 client.js 里把音高调高。
- 用户取消的回合仍会响。 回合因任何原因关闭时 agent/turn-stopping 都会触发，包括你主动发起的取消。
- 前置依赖应用的转发事件监听器自己不做前置。 如果它做了前置，两者仍然都会运行，但将来若有改动把它排到本插件前面，attention 提示音就会哑掉，而回合结束和错误告警照常工作。自检会断言这个前置，好让这类回归无法悄悄落地。
- 告警路由没有鉴权。 /sound-alerts/events 由 Host 的 web 服务器提供，不做凭证检查，与随附的 /plugins/events 路由一致。它是只收通道——没法通过它注入任何东西，也没法让它发声——但能连到端口的客户端可以订阅，从而得知有审批或提问在等待。那是元数据，不是内容。只有当 Host 绑定超出 loopback 时才有影响；默认 loopback 绑定下，可达集合就是本机，而本机本来就能读配置档的文件。
- view: 'summary' 时设置卡片什么都不渲染。 页面会退回自己的一行式展示。这是对插槽约定的预期解读，但也是这里唯一只对着运行中的 UI 验证、而非由自检断言的行为。

开发

改 index.js 或 client.js 需要重启 Harness。 配置档会为配置启用 dsh-hmr，但它的 root 默认是 []，所以模块根目录 —— JavaScript 本身 —— 不会被监听。只有 cordis.patch.yml 的改动会实时生效。

想不重启就迭代，把这个包加进配置档 dsh-hmr 配置的模块监听根目录：

- id: hmr
config:
root:
- /path/to/dsh-sound-alerts

重新加载前先跑 node scripts/self-check.mjs；监听器的接线和 schema 结构一旦静默失败，本来会被它藏住，这个脚本能覆盖到。