dsh-speak

dsh plugin --profile web add dsh-speak

dsh-speak 🔊 — 为 AI 编程 harness 提供语音播报

中文 · [English](README.md)



让 Agent 在长任务完成时开口告诉你——不用再盯着屏幕等。

dsh-speak 通过系统语音合成把 Agent 的最终回复朗读出来，用的是操作系统当前的嗓音——

Windows 上即默认 SAPI 嗓音（Windows 11 自带自然语音包，或 Windows 10 上经

[NaturalVoiceSAPIAdapter] 注册），macOS 上即系统朗读嗓音（say，可含 Siri 音色）。

本项目为 DeepSeek Harness 而生，但结构上

任何 harness 都能接入。

特性

• 全自动：DSH web 插件监听会话事件流，自动播报最终回复

（跳过 reasoning/工具调用旁白，合并同一回复的多步消息）。

• 提醒你：审批请求（Agent 等你操作时会播"需要你的审批"）和 Agent 通过

ask_user_question 提出的问题都会播报。

• 最终回复重播（1.7.0）：每条最终回复（回合尾部）操作栏有 🔊 按钮——点击

重播该条回复、再点停止、点另一条切换。语音执行完全由 DSH host 拥有（浏览器

关掉也继续读）。

• host 语音队列（1.7.0）：同一时间只运行一个语音进程，队列自动串行；

WebSocket 实时同步"正在读哪条、队列长度"到 UI。

• 多事件可选播报（1.6.0）：回合结束、命令完成、目标变更、工具出错、

待办更新等事件都可选播报，各自独立开/关（默认关）。

• 可视化配置（1.7.0）：设置 → dsh-speak 设置独立设置页，所有配置项（总开关、

自动朗读、Markdown 清洗、代码块、事件开关、固定提示语…）直接改，无需手写

YAML。

• 总开关（1.6.0）：一键静音所有播报。
• Bundle 自动注册（1.3.0）：把包声明进 dsh.profile.bundles，插件通过包内

自带的 cordis.patch.yml 自动注册，无需手动写 patch 条目。

• 尽力而为：绝不抛错、绝不阻塞 harness、绝不破坏会话。
• 跟随系统嗓音：引擎不挑、也不覆盖嗓音，直接用系统默认——Windows 是默认

SAPI 嗓音（控制面板「语音」或 设置 → 时间和语言 → 语音 里换），macOS 是系统朗读

嗓音（系统设置 → 辅助功能 → 朗读内容 → 系统嗓音，可含 Siri）。换嗓音请改系统设置。

• 健壮的文本清洗：去掉会让语音合成静默失败的 markdown/URL/emoji，

并守卫适配器单次朗读的字数上限。

• 引擎可移植：任意进程一行即可朗读：

Windows powershell -File speak.ps1 -Text "你好" / macOS ./speak.sh -t "你好"。

工作原理

harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
      │
      ▼  adapters/…  （harness 专属触发器：过滤、节流、取消）
      ▼  engine/speak.ps1 / speak.sh  （与 harness 无关：清洗文本 → SAPI5 / say）
      ▼  🔊 你听到最终回复

适配器负责把 harness 专属事件转成引擎调用；引擎负责清洗文本并朗读，

与 harness 完全解耦。完整设计见 [docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)。

前置条件

Windows

• Windows 10 或 11，任意较新的 PowerShell。
• 引擎使用 Windows 默认 SAPI 嗓音。换嗓音在「控制面板 → 语音」（或 设置 →

时间和语言 → 语音）里改；插件不会覆盖系统设置。

• 想听自然语音：Windows 11（21H2–23H2）已内置语音包；Windows 11 24H2/25H2 与

Windows 10 需先装

NaturalVoiceSAPIAdapter，

用它的 VoiceDownloader 下载语音包，再把该嗓音设为系统默认。系统默认是机械音，

听到的就是机械音。

macOS 要求

• macOS（Apple Silicon / Intel 均可），系统自带 say 命令，无需安装任何软件。
• 中文音色与 Siri 音色的选择入口/坑见 [macOS](#macos) 一节。

DSH 版本

• 已在 DSH 0.2.1-rc.4 上验证。0.1.1 之后有两轮 host/客户端 API 变更，本插件均已适配：
• 0.1.7 把 settings provider API 换成了 Config 投影：settings 服务改为读取每个

已激活 Loader 条目自己导出的 Config schema，把其中的 volatile 字段投影成设置

界面（宿主侧 ctx.settings.describe()，浏览器侧 ctx.configForms）。1.6.0–1.8.x

使用的 settings.register(namespace, schema, { base }) 已删除，浏览器服务

settingsScope 也被 configForms 取代。因此本插件把 schema 作为 Config 导出，

而设置 namespace 就是它的条目 id（dsh-speak；1.8.x 遗留的 speech-hook

条目 id 依然可以绑定，见下）。

• 0.1.2 起 Session snapshot 不再携带会话视图（Conversation target）数据——

🔊 按钮改为通过 Chat 目标的 hook useChat 取被点击消息的文本；同一版本还删除了

@deepseek-ai/dsh-settings 的 installSettingsSection / settingsNamespace。

• 0.2.x（已实测到 0.2.1-rc.4）没有插件 API 破坏性变更，插件仍只依赖上面这些接口

和 engines.dsh。

• 宿主要求声明在 dsh-market 实际读取的位置：package.json 的 engines.dsh

（>=0.1.7-rc.2）。市场卡片与「适配当前 DSH」筛选读的正是这个字段，因此只有在

某个宿主版本上实测通过后，这个下限才会移动。

• dsh-speak 1.8.2+ 依赖 0.1.7 引入的设置模型：在更老的宿主上浏览器半侧会一直等待

configForms 服务。DSH ≤ 0.1.6 请用 1.8.1。

安装与快速开始

DSH — 方式 A：npm 插件（推荐）

# 1. 把插件装进你的 web profile（会写入 ~/.dsh/profiles/web/package.json 的
#    dependencies **和** dsh.profile.bundles）
dsh plugin --profile web add dsh-speak

# 2. 到此为止——包自带 bundle patch，条目（id: dsh-speak）由它注册。
#    不要再手写一行 insert：同一个条目注册两次会让 id 不唯一，DSH 的 config-editor
#    随后会拒绝每一次设置写入：
#      settings/rejected: Configuration for "dsh-speak" is overridden by a home patch or command-line overlay
#    （语音照常工作，只有设置页静默弹回——所以特别难查。）
#
#    如果仍想在 YAML 里固定选项，只加这一行**顶层行**（设置页就地改写它；
#    config 放顶层行才是编辑器支持的形状，见「DSH 插件配置」）：
#    - id: dsh-speak
#      name: 'dsh-speak'
#      config: {}
#
#    0.1.7 起条目 id 就是设置 namespace：你的选项会以这个 key 存在同一个文件里。
#    1.8.x 遗留的 id（speech-hook）继续可用——浏览器半侧两个 id 都认。

# 3. 重启 DSH web 应用 — 之后回复会被自动播报

在应用内插件市场安装是同一条路径（会把包加进 dsh.profile.bundles）；

只有下面两种手动安装才需要手写行。一个 profile 只能有一种注册方式，绝不能两种都有。

没有 pnpm？ dsh plugin 内部转发给 pnpm，并非所有机器都装了。可以用 npm

直接完成同样的安装：

```powershell

npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak

```

macOS（bash）：

```bash

npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak

```

单纯 npm install 不会注册插件：要么把包名加进

~/.dsh/profiles/web/package.json 的 dsh.profile.bundles，要么用文件安装那两行

——不要两者都做。

引擎随包分发（node_modules/dsh-speak/engine/），无需额外拷贝。

想让 Agent 帮你装？ 把本仓库地址（https://github.com/Alan2Z/dsh-speak）

丢给你的 DSH 会话，让它照着这份 README 安装即可——它读的就是你正在看的这份文档。

只需要同意它对 ~/.dsh（工作区外）的写入审批。

DSH — 方式 B：文件安装（不需要 npm）

# 1. 克隆
git clone https://github.com/Alan2Z/dsh-speak.git
cd dsh-speak

# 2. 一键安装：拷贝引擎 + 插件，并注册到 cordis.patch.yml
powershell.exe -NoProfile -ExecutionPolicy Bypass -File adapters\dsh\install.ps1

# 3. 验证引擎能出声
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\hooks\speak.ps1" -Text "你好，语音播报已就绪。"

# 4. 重启 DSH web 应用 — 之后回复会被自动播报

文件安装脚本做了这些事：

文件 · 目标位置

engine/*.ps1 · %USERPROFILE%\.dsh\hooks\

adapters/dsh/speech-hook.js · %USERPROFILE%\.dsh\profiles\web\plugins\

注册条目 · 追加到 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml（先备份）

macOS

同一套适配层原生支持 macOS——插件自动检测平台，改调 engine/speak.sh

（系统自带的 say 命令）而不是 speak.ps1。**自 1.2.0 起 macOS 引擎随 npm 包

正式分发**，无需安装任何额外软件。

# 1. 装进你的 web profile（没有 pnpm 也能装——dsh plugin 才依赖 pnpm）
npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak


…(truncated)