前言¶

在 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