前言¶

用 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 会播报两类需要用户注意的事件：

1. agent 发出的审批请求。
2. 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 如果想用自然语音，需要：

1. 安装 NaturalVoiceSAPIAdapter。
2. 使用其 VoiceDownloader 下载自然语音包。
3. 通过 NaturalVoiceSAPIAdapter 注册语音。

例如可以注册 Xiaoxiao。

如果没有自然语音，dsh-speak 会回退到普通 stock voice，例如 Huihui。

macOS¶

macOS 端使用内置 say 命令。

需要注意两个点：

1. Siri 声音和系统朗读声音是两套独立设置。
2. 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 插件目录实际收录页为准。