前言¶

在 dsh web 里跑任务时，有几种状态会等你回来：需要审批、需要你回答提问、或者一个回合已经跑完。如果你没有一直盯着标签页，这些状态很容易错过。

dsh-audio-alert 做的事情比较具体：在上述“需要你注意”的事件发生时，让浏览器播放一段提示音。它不改变任务执行逻辑，只是把等待、提问和完成状态变成可听见的事件。

这是什么¶

ellelkktrraaa/dsh-audio-alert 是一个 DSH 插件，包名为 @deepseek-ai/dsh-client-audio-alert，许可证为 MIT。

它面向 dsh web 的浏览器端，在以下三类事件上提供声音提醒：

• approval request
• ask-user question
• finished turn

提示音可以通过 audio-alert 设置项按事件类型分别配置；如果某个声音字段留空，则使用内置合成音。

核心功能¶

下面介绍它能提供哪些已核实的配置项和能力。

1、按事件类型播放提示音

插件可以针对三类事件分别设置声音：

• approvalSound
• questionSound
• doneSound

2、通过 audio-alert 设置项配置

可用的配置字段包括：

• enabled
• volume
• approvalSound
• questionSound
• doneSound
• debug

3、声音字段支持多种来源

声音字段可以接受：

• data URI
• http(s) / blob URL
• root-relative URL
• local filesystem path

如果某个声音字段为空，则使用内置合成音。

4、本地路径由 dsh web 所在机器读取

本地路径文件由运行 dsh web 的机器上的 node 端读取，并通过：

/audio-alert/audio/<kind>

提供给浏览器。也就是说，浏览器不是直接读取本地文件系统。

5、调试模式

设置：

debug: true

后，插件会把 resolved config 和每次播放事件记录到浏览器控制台和服务器日志中。

安装与启用¶

先确认你的环境满足以下条件：

• 一个 dsh web deployment
• Node ^22.19 || >=24
• pnpm

安装插件时，使用仓库提供的安装命令：

dsh plugin --profile web add https://github.com/ellelkktrraaa/dsh-audio-alert.git

如果你已经有本地 checkout，也可以安装本地路径：

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 中创建一个 audio-alert 配置段，例如：

audio-alert:
  enabled: true
  volume: 0.8
  approvalSound: "C:/sounds/approval.mp3"
  questionSound: "C:/sounds/question.mp3"
  doneSound: "C:/sounds/done.mp3"
  debug: true

各字段含义如下：

• enabled：是否启用提示音
• volume：音量
• approvalSound：approval request 对应的声音
• questionSound：ask-user question 对应的声音
• doneSound：finished turn 对应的声音
• debug：是否输出调试日志

声音字段留空时，会使用内置合成音。

注意：以 / 开头的值会被当作 root-relative URL，而不是本地文件路径。

修改配置后，需要重启 dsh web：

# 重启你当前用于访问 dsh web 的服务进程
# 例如重新启动 dsh web 所在进程

典型用法¶

下面是一个适合先跑通的验证流程。

1、开启调试日志

在 settings.yaml 中设置：

audio-alert:
  debug: true

2、重启 dsh web

3、触发一次 approval request、ask-user question 或 finished turn

4、打开浏览器控制台，查看是否出现 [audio-alert] 日志

正常时，控制台里可以看到类似：

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

然后你就可以在同一事件发生时听一下浏览器是否播放了对应声音。

适用场景与注意¶

这个插件适合使用 dsh web、希望任务进入“需要你回来”状态时收到声音提醒的人。它比较轻量，主要价值是把三类等待状态从界面上拉出来，变成一次可感知的音频事件。

使用前请注意以下边界。

1、它是 DSH 插件，安装前建议检查源码与许可证

dsh-audio-alert 会作为 DSH 插件安装到 web profile 中。由于它会运行在当前 DSH 环境中，安装前建议先检查源码、依赖和许可证。该插件的许可证是 MIT。

2、自定义声音需要宿主 API proxy 允许 audio-alert 命名空间

自定义声音要求 host API proxy allowlist 暴露 audio-alert 命名空间。如果没有暴露，浏览器可能无法读取自定义声音，此时插件仍可能播放内置音。

3、本地声音文件必须在 dsh web 所在机器上可读

本地路径必须存在于运行 dsh web 的机器上，并且可读。它不可直接移植到另一台机器。

4、done 事件不区分结束原因

done 触发条件是某个 session 的 running 状态从 true 变为 false。它不区分 completed、error 或 aborted turn，只表示这一轮结束了。

5、首次声音可能被浏览器的 autoplay 策略阻止

第一次播放可能被浏览器 autoplay policy 拦截，直到页面上发生过一次用户手势。你只需要点击一次页面，让浏览器允许播放。

6、加载时已经 pending 或 idle 的 session 不会补播

如果某个 session 在插件加载时已经处于 pending 或 idle 状态，它不会重新播放之前错过的提醒。

7、看不到 [audio-alert] 日志时，先怀疑缓存

如果浏览器控制台没有 [audio-alert] 日志，可能是浏览器仍在使用旧的 client.js。可以尝试强制刷新，或者打开一个新标签页。

结尾¶

dsh-audio-alert 的价值很直接：把 dsh web 中需要人回看的 approval request、ask-user question 和 finished turn 变成浏览器提示音。它通过 audio-alert 设置项配置，可以按事件选择声音，也支持本地文件、URL 和内置音。

GitHub 仓库：

https://github.com/ellelkktrraaa/dsh-audio-alert