dsh-voice
English | 简体中文
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-webpeer 范围已覆盖两者） - 一个可用的 dsh
webprofile - 浏览器麦克风权限
安装
dsh plugin --profile web add
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 在线合成）
