前言¶

在开发基于大模型的对话应用时，语音交互往往需要多个组件串联：语音识别（ASR）、大模型推理、语音合成（TTS），还要处理用户中途打断（barge-in）等场景。如果这些环节各自实现，通常需要维护多个服务或进程，接口、状态管理都比较复杂。DeepSeek Harness（DSH）采用「一切皆插件」的架构，将这类能力封装成可插拔模块，开发者只需配置即可复用。

这是什么¶

dsh-voice 是 DeepSeek Harness 的语音模式插件，提供全双工语音流：麦克风输入 → 实时 ASR → 大模型流式输出 → 实时 TTS。它支持三种语音输入方式（点击、长按、键盘快捷键），内置实时字幕、中途打断检测、消息重放与运行时配置等能力。该插件 fork 自 haoku123/dsh-voice，由 houzi5940 维护。

核心功能¶

• 全双工语音流：麦克风 → SenseVoice ASR → 大模型流式推理 → TTS，支持实时字幕与语音合成。
• 三种语音输入方式：
  1. 点击麦克风：连续语音输入，VAD 根据尾部静音分段。
  2. 长按发送键（或麦克风）：录制直到释放，上滑可丢弃。
  3. 按下 Ctrl（可配置 asr.hotkey）：不离开键盘即可录音，Esc 丢弃。
• 实时字幕：录音过程中每约 900ms 重新解码并显示 interim 转写，释放后显示加载状态直到最终转写就绪。
• 中途打断（barge-in）：检测到麦克风输入起音后，立即停止播放、丢弃队列中的合成任务、取消当前轮次，并中止未完成的半句。
• ASR 引擎：使用 sherpa-onnx 运行 SenseVoice，支持简体中文、英文、日文、韩文、粤语等多语言自动检测，内置标点与逆文本归一化（ITN）。
• 回声消除：使用 NLMS 语音回声消除器，以页面自身的 TTS 播放为参考消除回声，浏览器级回声消除作为降级方案。
• 缓存代理：模型文件通过 /dsh-voice-api/hf 代理获取，首次下载后镜像到磁盘缓存目录（默认 ~/.cache/dsh-voice/models/），支持断点续传；可通过 npm run prefetch 预热缓存。
• 运行时配置：支持自定义语音合成、模型来源、语言、ITN、自动发送、输入模式与快捷键等。

安装与启用¶

1. 确保已安装 Node.js ≥ 22.19 或 ≥ 24（需要 node:zlib zstd API）。
2. 确保当前 DeepSeek Harness 版本为 0.1.0-rc.6 或 0.2.x（插件依赖 @deepseek-ai/dsh-web）。
3. 在 DSH 命令行中执行：

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

安装完成后，插件会自动注入到 Web 模式下，可通过配置启用语音模式。

典型用法¶

• 启用语音模式：在 bundle patch 配置中添加 voice 模块，并设置 asr.hotkey 为期望的键盘快捷键（如 Control）。

- id: voice
  name: '@haoku123/dsh-voice'
  config:
    voice: zh-CN-XiaoxiaoNeural
    cacheDir: ~/.cache/dsh-voice/models
    asr:
      model: csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17
      modelHost: https://huggingface.co
      language: auto
      useItn: true
      autoSend: false
      mode: toggle
      hotkey: Control

• 预热模型缓存：在 dsh host 运行时执行：

npm run prefetch

• 测试功能：运行测试套件以验证 ASR、TTS 回退、barge-in、集成与客户端注册等：

npm test
npm run test:host
npm run test:client
node test/host.integration.test.mjs
node test/tts-retry.test.mjs

适用场景与注意¶

• 适合需要在大模型对话中集成实时语音交互的开发者，特别是中文场景。
• 插件以当前 DSH 进程的权限运行，安装前建议检查源码与许可证（MIT）。
• 模型文件首次使用时会通过代理下载，网络环境可能影响速度；国内环境可配置 HF 镜像（如 https://hf-mirror.com）。
• 长按录音超过 12 秒时，实时字幕会停止更新；这仅是显示层的限制，不影响最终转写结果。

结尾¶

dsh-voice 将语音识别、大模型流式输出与语音合成串联为统一的语音模式，提供了中途打断、实时字幕与灵活的输入方式，适合需要全双工语音交互的开发场景。更多详情与源码请参考：

• 目录页：https://www.skillhub.cn/plugins/houzi5940/dsh-voice
• GitHub：https://github.com/houzi5940/dsh-voice