前言¶
用 DSH 跑長任務時，經常會遇到一個具體痛點：任務結束、agent 等待審批、agent 通過 ask_user_question 提問時，如果你不在屏幕前，很容易錯過。
dsh-speak 針對這個問題：它把 DSH 會話中的最終回覆、審批請求和提問，通過系統語音合成讀出來。下面介紹它的定位、核心能力、安裝方式和一些實際使用注意點。
這是什麼¶
dsh-speak 是一個 DSH web 插件，由 Alan2Z 維護，許可證爲 MIT。
它的主要目標是讓 AI 編碼 harness“說話”：
- 在 Windows 上使用 SAPI5 語音合成。
- 在 macOS 上使用系統
say命令。 - 支持 DSH 以及其他可以接入該 harness 事件流的 AI coding harness。
項目說明裏寫得很直接：這個項目存在的目的，是給用戶提供一個已經驗證過的 harness 語音播報方案；除非出現意外情況，後續不會再繼續更新。
核心功能¶
播報最終回覆¶
DSH web 插件會監聽會話事件流，並播報最終回覆。
它會跳過 reasoning 和 tool-call 過程的中間敘述，並會合並多步消息。簡單說，不是把每一步都念出來，而是儘量把最後給用戶的回覆讀出來。
提醒審批和提問¶
dsh-speak 會播報兩類需要用戶注意的事件：
- agent 發出的審批請求。
- agent 通過
ask_user_question提出的問題。
這類信息適合語音提醒，因爲它們通常意味着任務已經停下來，等待用戶處理。
Bundle 自動註冊¶
1.3.0 開始支持 bundle auto-registration：
- 在
dsh.profile.bundles中聲明該包。 - 插件會通過自帶的
cordis.patch.yml註冊自己。 - 不需要手工追加 patch 條目。
如果不用 bundle 自動註冊，也可以手動向 DSH profile 的 cordis.patch.yml 追加插件條目。
Best-effort 運行¶
dsh-speak 採用 best-effort 策略：
- 不拋異常。
- 不阻塞 harness。
- 不會破壞當前會話。
也就是說，語音播報失敗時，目標是不要影響 DSH 主流程。
自然語音¶
Windows 上優先使用自然語音：
- Windows 11：使用系統內置自然語音包。
- Windows 10：可以通過
NaturalVoiceSAPIAdapter註冊自然語音，例如Xiaoxiao。
macOS 上使用系統朗讀聲音；在較新的 macOS 上，也可以使用 Siri natural voices。
如果當前系統沒有可用自然語音，會回退到任意已安裝語音。
文本清洗¶
語音合成經常會被 Markdown、URL、emoji 等字符影響，甚至可能靜默失敗。
dsh-speak 會對待播報文本做清洗：
- 去掉 Markdown。
- 去掉 URL。
- 去掉 emoji。
- 限制 adapter 的單次 utterance 字符上限。
可移植引擎¶
它提供可獨立調用的語音引擎：
powershell -File speak.ps1 -Text "你好"
./speak.sh -t "你好"
任何進程都可以用這種方式調用語音播報，不一定依賴 DSH。
安裝與啓用¶
環境要求¶
- Node.js
>= 18。 - Windows：Windows 10 或 11，PowerShell。
- macOS：使用系統內置
say，不需要額外軟件。 - 許可證：MIT。
方式一：通過 npm 安裝¶
先安裝到 web profile：
dsh plugin --profile web add dsh-speak
如果機器上沒有 pnpm，也可以用 npm 直接安裝到 web profile：
npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak
macOS 上使用：
npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
然後把插件註冊到 DSH 的 patch 文件。編輯：
~/.dsh/profiles/web/cordis.patch.yml
追加：
- insert:
- id: speech-hook
name: 'dsh-speak'
Windows 上需要重啓 DSH web app。
macOS 上不需要重啓，因爲 patch watcher 會熱加載。
方式二：文件安裝¶
如果不通過 npm 安裝，也可以在 Windows 上使用文件安裝：
git clone https://github.com/Alan2Z/dsh-speak.git
cd dsh-speak
powershell.exe -NoProfile -ExecutionPolicy Bypass -File adapters\dsh\install.ps1
安裝完成後，重啓 DSH web app。
讓 agent 代爲安裝¶
你也可以把倉庫地址交給 DSH 裏的 agent，讓它按 README 安裝插件：
https://github.com/Alan2Z/dsh-speak
由於安裝過程會寫入 workspace 外的 ~/.dsh，需要審批這些 out-of-workspace writes。
典型用法¶
測試 Windows 語音引擎¶
安裝完成後，可以直接測試 PowerShell 語音引擎：
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\hooks\speak.ps1" -Text "你好，語音播報已就緒。"
如果系統能讀出這句話，說明 Windows 端語音鏈路已經可用。
測試 macOS 語音引擎¶
在 macOS 上可以直接下載腳本並測試：
curl -sfL -o ~/speak.sh "https://cdn.jsdelivr.net/gh/Alan2Z/dsh-speak@main/engine/speak.sh"
chmod +x ~/speak.sh
~/speak.sh -t "你好，Mac 版語音播報測試"
如果系統能讀出這句話，說明 macOS 端 say 鏈路已經可用。
在 DSH 中觀察效果¶
安裝並啓用後，DSH web 插件會監聽會話事件流。
當 agent 給出最終回覆時，插件會播報最終回覆。當 agent 請求審批，或通過 ask_user_question 提問時，插件也會進行語音提醒。
聲音配置與注意¶
Windows 10 和 Windows 11¶
Windows 11 的自然語音包是內置的，不需要額外安裝。
Windows 10 如果想用自然語音，需要：
- 安裝
NaturalVoiceSAPIAdapter。 - 使用其 VoiceDownloader 下載自然語音包。
- 通過
NaturalVoiceSAPIAdapter註冊語音。
例如可以註冊 Xiaoxiao。
如果沒有自然語音，dsh-speak 會回退到普通 stock voice，例如 Huihui。
macOS¶
macOS 端使用內置 say 命令。
需要注意兩個點：
- Siri 聲音和系統朗讀聲音是兩套獨立設置。
- Siri voices 不會通過
say -v '?'暴露。
另外，打開 Spoken Content / Siri Voice 設置面板，即使沒有修改任何內容，也可能把系統語音重置爲 婷婷（Tingting）。如果突然發現聲音變了，可以重新選擇系統朗讀聲音。
macOS 上的日誌位置是：
$TMPDIR/dsh-speech-hook.log
注意這是 os.tmpdir()，不是 /tmp。
say 沒有 volume flag，音量跟隨系統輸出音量。
適用場景與注意¶
適合以下場景：
- 長時間跑 DSH 任務，離開屏幕。
- 需要在 agent 等待審批時快速得到提醒。
- 需要在 agent 提問時及時知道任務卡住。
- 想把 DSH 最終回覆變成語音播報，減少盯着屏幕的時間。
使用注意：
dsh-speak作爲 DSH web 插件運行，使用當前 DSH 宿主進程的權限。- 安裝前建議檢查 GitHub 源碼、腳本和 MIT 許可證。
- 如果允許 agent 代爲安裝，需要審批對
~/.dsh的 workspace 外寫入。 - 它是 best-effort 組件，目標是播報失敗時不影響 DSH 主流程。
結尾¶
dsh-speak 做的事情很具體：讓 DSH 在最終回覆、審批請求和 ask_user_question 提問時發出語音，減少漏看屏幕的情況。它的範圍不大，但路徑已經驗證過，適合想給 harness 加一個輕量語音提醒的人。
GitHub 倉庫：
https://github.com/Alan2Z/dsh-speak
社區目錄頁請以你使用的 DSH 插件目錄實際收錄頁爲準。
