全双工语音 houzi5940/dsh-voice

dsh-voice

DeepSeek Harness（dsh）的全双工语音插件：说话 → 语音识别 → 模型流式回答 → 语音朗读，并且支持开口即打断（barge-in）。

说话 ──▶ SenseVoice 识别 ──▶ composer 草稿 / 提交 ──▶ 模型流式输出 │ ◀── 浏览器 SSE 播放（MP3 + 字幕）◀── 分句 + Edge TTS 合成

特性

- 三种说话方式：点按连续听写、长按发送键说话、长按快捷键说话。
- 实时字幕：长按期间浮层里持续显示"已说的内容"预览，松手后显示识别中状态，直到最终文本落地。
- 真正的语音打断：检测到用户开口的瞬间，本地播放停止、host 合成队列清空（连正在合成的那一句一起丢弃）、正在运行的轮次被取消；被打断的轮次不会补读半句话。
- 回声消除：使用页面自身的 TTS 播放作为参考信号，运行 NLMS 自适应回声消除器，避免外放时把助手自己的声音误判成用户开口。浏览器原生 echoCancellation 仅在没有参考信号时兜底。
- 中文原生 ASR：host 端使用 sherpa-onnx（Apache-2.0）运行 SenseVoice，原生输出简体中文，自带标点、ITN（数字/符号规范化）与 50+ 语种自动识别。
- 不阻塞模型流：对 llm/stream 是无损 tap，每个 chunk 原样透传，分句与合成完全旁路进行。
- 模型缓存与断点续传：模型文件通过 host 端缓存代理下载并落盘，支持 Range 与 .part 续传，也支持 HuggingFace 镜像。

环境要求

- Node.js ≥ 22.19 或 ≥ 24（依赖 node:zlib 的 zstd API）
- dsh 0.1.0-rc.6 或 0.2.x（插件的 @deepseek-ai/dsh-web peer 范围已覆盖两者）
- 一个可用的 dsh web profile
- 浏览器麦克风权限

安装

dsh plugin --profile web add <repo-url-or-path>
dsh --profile web

首次使用时，host 会按需下载 SenseVoice 模型（数百 MB）到本地缓存；也可以提前预热：

npm run prefetch # 默认访问 http://127.0.0.1:3080，需 dsh 正在运行

使用

| 操作 | 行为 |
| 点按麦克风 | 连续听写，VAD（RMS 能量）在尾部静音处自动断句 |

朗读策略（tts.mode）在设置页选择：first 只播首句、paragraph 朗读首段（到第一个空行，流式判定）、all 整篇朗读、off 静音；仅影响播报，会话中的显示始终完整。
| 长按发送键（或麦克风） | 按住即录音，松开发送，上滑取消 |
| 长按 Ctrl（可配置 asr.hotkey） | 不离开键盘直接说话，松开 Ctrl 发送，Esc 取消 |

长按期间输入框上方会出现波形浮层：

- 波形来自麦克风实时电平（每 ~64ms 一帧）。
- 实时字幕是预览，不是最终结果；它不会写入草稿，松手后迟到的预览会被直接丢弃。
- 松手后浮层进入"识别中…"，直到最终识别结果返回才关闭；空结果或失败也会自动收尾，不会一直转圈。
- 上滑超过 80px 进入取消态，松手即丢弃本次录音。

键盘方式有额外的安全设计：长按阈值 600ms（指针是 260ms），并且按住期间按下任何其他键都会作废本次录音，保证慢速 Ctrl+C 不会被当成语音；切换窗口（blur）也会取消，避免麦克风一直开着。

工作原理

输入: 麦克风 ──RMS 端点检测──▶ POST /asr（原始 f32 PCM） │ 文本（SenseVoice，host 端） ▼ composer 草稿 ──提交──▶ 模型流 ──llm/stream tap──▶ SentenceSegmenter │ 浏览器 ◀── SSE /dsh-voice-api/stream ── TtsQueue（msedge-tts）◀──┘ （base64 MP3 帧 + 字幕文本）

打断: 语音前沿 ──▶ engine.skip() + POST /cancel（epoch +1）
+ session.cancel()（仅当该会话有运行中的轮次）

几个关键设计：

- host / client 分工：识别在本机 host 完成，浏览器只负责采集、端点检测和 POST 原始 little-endian f32 PCM（16 kHz 单声道）。浏览器端不加载任何模型。
- 分句：SentenceSegmenter 剥离 Markdown 后按中英文终止标点切句，遇到没有标点的长文本有安全阀；每个 chunk 仍然原样传给下游。
- 合成队列：TtsQueue 按会话串行合成，cancel() 通过 epoch 机制同时丢弃排队中和正在合成的内容。
- 增量预览：每次预览只上传"上次之后新增的音频"（用 x-dsh-session 关联），host 对每个会话只解码固定长度的滑动窗口（8s），所以长按再久，预览开销也不增长。超过 12s 停止预览。
- 长按绕过 VAD：按住本身就是明确意图，所以按下到松开之间的所有音频都会保留；只有短于 250ms 的采集会被当作误触丢弃（时长在补尾垫之前测量）。

隐私边界：语音识别全部在本机 host 完成，音频不会上传到第三方；朗读使用微软 Edge TTS 在线合成（文本会发送到微软服务）。

配置

在 dsh 的 bundle patch 中配置：

- id: voice
name: '@haoku123/dsh-voice'
config:
basePath: /dsh-voice-api # HTTP 路由前缀（/dsh-voice-api/config 始终可作为引导路径） enabled: true # 关闭后不再挂接 llm/stream voice: zh-CN-XiaoxiaoNeural # Edge TTS 音色 cacheDir: ~/.cache/dsh-voice/models # 模型磁盘缓存目录 asr: model: csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17 modelHost: https://huggingface.co # 国内可改为 https://hf-mirror.com language: auto # auto | zh | en | ja | ko | yue useItn: true # 数字/符号规范化 autoSend: false # 点按模式下识别完是否自动提交 mode: toggle # toggle | hold hotkey: Control # 键盘长按说话键；'' 表示禁用

hotkey 取 KeyboardEvent.key 的值，例如 Control、Alt、Meta、Shift、Space 或单个字母。

HTTP API

| 路由 | 用途 |
| GET /dsh-voice-api/stream | SSE；event: audio，帧格式 {sessionId, seq, text, audio(base64 MP3)} |
| POST /dsh-voice-api/asr | 请求体为原始 little-endian f32 PCM；返回 {text}。带 x-dsh-session 时为增量预览 |
| POST /dsh-voice-api/cancel | {sessionId}，清空该会话排队中与合成中的语音（epoch +1） |
| GET /dsh-voice-api/config | 返回前端所需的运行时配置 {asr, basePath}；该路径固定，自定义 basePath 时客户端仍能靠它发现真实前缀 |
| GET /dsh-voice-api/hf/ | HuggingFace 模型缓存代理（落盘到 cacheDir，支持 Range / 续传） |
| GET /dsh-voice-api/ | 连通性探测：{ok, name, enabled} |

模型缓存

模型下载统一走 /dsh-voice-api/hf 缓存代理：

- 首次请求时从 asr.modelHost 拉取，同时镜像到 cacheDir（按 HF 仓库路径布局）。
- 支持 HTTP Range；中断后从 .part 文件续传。
- 之后的每次启动都直接读本地磁盘，不再联网。
- 国内网络把 modelHost 改成 https://hf-mirror.com 即可。

开发

npm install # sherpa-onnx 是运行时依赖，必须安装
npm run build # esbuild：lib/index.js（host）+ lib/client.js（浏览器）
npm test # host 测试 + client 组件测试
npm run test:host # segmenter / bargein / bargein-semantics / integration
npm run test:client # vitest + jsdom
node verify-client.mjs # 校验 client bundle 的注册、exports、slots

改完源码后记得重新 npm run build：host 测试直接 import lib/*.js。

常见问题

麦克风没反应？ 界面会区分"权限被拒绝 / 找不到设备 / 被其他程序占用"。权限问题请在浏览器地址栏的站点权限里放行麦克风。

识别很慢？ 首次使用需要下载并加载模型，之后会明显变快。建议先 npm run prefetch，并确认 cacheDir 可写。

外放时助手会打断自己？ 插件已经用 TTS 播放作为参考信号做 NLMS 回声消除。若仍有误触发，可降低系统音量，或关闭 noiseSuppression / autoGainControl 不友好的音频驱动；耳机效果最好。

Ctrl 热键与编辑器快捷键冲突？ 把 asr.hotkey 改成 Alt、Space 等其他键，或设为 '' 关闭键盘模式，只保留发送键长按。

模型下载失败？ 切换 asr.modelHost 为镜像源后重启 dsh；已下载的部分会从 .part 继续。

许可

MIT

第三方组件：

- sherpa-onnx（Apache-2.0）与 SenseVoice 模型
- msedge-tts（Edge TTS 在线合成）