haoku123/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-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 能量）在尾部静音处自动断句
长按发送键（或麦克风）	按住即录音，松开发送，上滑取消
长按 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 在线合成）