桌面语音模式 NutshellLee/dsh-voice-mode-desktop

dsh-voice-mode-desktop

为 DeepSeek Harness 0.2 桌面版提供的全双工语音模式：说话时文字实时流入草稿，停顿后自动发送，回复按句朗读，朗读期间再次开口会立刻打断。附带一个应用内设置页，可调朗读语速、录音方式与字幕显示。

本项目是 dsh-voice-mode 0.7.15 的适配分叉（它又源自 haoku123/dsh-voice）。三者均为 MIT 许可，见 LICENSE。

这个分叉做了什么： 让上述插件能在 DSH 0.2 桌面版上运行——适配它依赖的客户端接口、补一个应用内设置页、把云端朗读的第三方依赖换成仓库内自带的实现。识别、打断、本地朗读这些引擎都是上游原样代码，未作改动。

- 上游声明的兼容范围到 DSH 0.1.7-rc.1，代码按 0.1 的客户端接口编写。
- 本分叉面向 DSH 0.2.0-rc.2（DSH NEXT 桌面版 2.0.17-next 随附的版本）：该版本移除了客户端服务 settingsScope，插件配置表单也只渲染标了 volatile 的字段。
- 已在 Windows、DSH NEXT 桌面版 2.0.17-next、@deepseek-ai/* 0.2.0-rc.2 上验证。其他版本未测。

能做什么

- 语音输入：按住说话或持续聆听，识别结果实时进入可编辑的草稿，停顿后自动发送。
- 语音输出：按句朗读（默认走 Edge 云端合成，可选本地 VITS / Kokoro），带实时字幕。
- 全双工：朗读期间开口即打断播放并取消当前回合。
- 设置页：朗读语速（0.5–2.0）、录音方式（按住说话 / 持续聆听）、字幕显隐，以及一键试听自检。入口在侧栏「插件」页里的「语音模式」一项。自检特意把合成与播放分开，听不到声音时能判断是引擎的问题还是输出设备的问题。

与上游 dsh-voice-mode 0.7.15 的差异

| 方面 | 改动 | 原因 |
| 客户端半体 | inject 不再声明 settingsScope，对该服务的访问用 try/catch 兜住 | settingsScope 已从 DSH 客户端接口移除；宿主把"有 entry 未激活"当作致命错误，桌面版会直接进恢复模式 |
| 配置 schema | rate 与 mode 标为 volatile，并在所有读取点解包 | DSH 0.2 的插件表单只渲染 volatile 字段；把包装对象直接交给合成引擎会让朗读静默失败 |
| 设置界面 | 新增应用内设置页（侧栏插件 → 语音模式）与宿主接口 POST /voice-mode/settings；排版对齐宿主官方设置页，颜色使用宿主主题变量 | 上游的设置卡片依赖已移除的客户端接口；渲染插件配置表单的宿主页面在这个桌面部署里没有挂载 |
| 字幕 | 增加显示 / 隐藏开关，字幕最大宽度收紧（默认档 420 像素） | 字幕是可选项，原先的默认宽度会占满大半个窗口 |
| 状态条 | 宽度按内容收缩、居中、上限 480 像素 | 原先会铺满整个输入区 |
| 诊断 | 当模型流因语音会话不匹配而被跳过时输出一行日志 | 让"没有朗读"这类静默问题可以从日志复现 |
| 打包 | 重命名包；挂载补丁用包内相对路径引用本包 | 让适配变成一个可安装的包，而不是一堆本地改动；同时绕开宿主对 profile 级第三方插件的裸包名解析 |
| 云端合成 | 用仓库内的 Edge 朗读客户端（lib/edge-tts.js）替代 msedge-tts 依赖 | msedge-tts 里的 require("buffer/index") 在 DSH 桌面宿主上解析失败，导致插件整体无法加载。自带这个约一百八十行的客户端后，安装是一步到位，不需要再给依赖打补丁 |

其余部分——识别、合成引擎、打断、唤醒词、让位语义、模型校验——都是上游代码，未改。

改动范围

基线：npm 上的 dsh-voice-mode@0.7.15（其本身源自 haoku123/dsh-voice）。本分叉触及的文件：

| 文件 | 改动性质 |
| lib/index.js | 宿主半体：schema 的 volatile 字段、POST /voice-mode/settings、一行诊断日志；Edge 引擎改为调用仓库内的客户端 |
| lib/client.js | 客户端半体：inject 列表、settingsScope 守卫、设置页、字幕显隐与宽度、状态条宽度 |
| lib/edge-tts.js | 本分叉新增 |
| cordis.patch.yml、package.json | 挂载点与打包信息（重命名包、不含安装脚本） |
| scripts/verify-compat.mjs、scripts/check-tts.mjs | 本分叉新增 |

lib/sense-worker.mjs 与 lib/tts-vits-worker.cjs 为上游文件，逐字节一致。上游项目保有自己的提交历史、测试与构建流程；本仓库是兼容适配，不是重写。

安装

这是一个 DSH bundle，装进某个 profile：

从 npm 仓库安装
dsh plugin add @nutshelllee/dsh-voice-mode-desktop

或从本地检出安装
dsh plugin add link:/path/to/dsh-voice-mode-desktop

或不经过包仓库，直接用仓库地址： dependency: "@nutshelllee/dsh-voice-mode-desktop": "git+https://github.com/NutshellLee/dsh-voice-mode-desktop.git"

然后在 profile 清单（dsh.profile.bundles）里启用它，需要的话在 profile 补丁里覆盖默认值：

- id: voice-mode
config:
enabled: true
voice: zh-CN-XiaoxiaoNeural
rate: 1.1
mode: hold # hold = 按住说话，toggle = 持续聆听 ttsEngine: edge # edge | vits | kokoro bargeInMode: detect silenceMs: 1500 autoSend: true spokenFormat: true

首次安装后重启应用，然后打开「插件 → 语音模式」调整设置，或在一段对话里按 Ctrl+Shift+V。

云端朗读

Edge 引擎由 lib/edge-tts.js 直接与微软的朗读接口通信（WebSocket 握手、SSML 请求、接收 MP3 分片），不涉及任何第三方合成封装，因此安装不需要安装脚本，也不需要给依赖打补丁。想确认这台机器上是否可用：

node scripts/check-tts.mjs

自检

node scripts/verify-compat.mjs [DSH 应用目录]

检查本分叉依赖的几项契约：DSH 应用存在、九个客户端注入目标齐全、宿主不再提供 settingsScope、插件客户端半体没有声明缺失的服务、rate/mode 能作为可编辑字段投影出来。退出码为 0 表示全部通过。

模型

仓库内不含模型文件。插件在第一次用到某项能力时自行下载，之后复用本地副本。

| 能力 | 何时下载 | 来源仓库 |
| 流式识别（默认） | 首次语音输入 | csukuangfj/sherpa-onnx-streaming-zipformer-zh-int8-2025-06-30（encoder / decoder / joiner / tokens） |
| 静音检测 | 首次语音输入 | Silero VAD（silero_vad.onnx） |
| SenseVoice 识别（senseVoice: true） | 首次语音输入 | SenseVoice int8（model.int8.onnx 与词表） |
| 本地 VITS 朗读（ttsEngine: vits） | 首次用该引擎朗读 | csukuangfj/sherpa-onnx-vits-zh-ll |
| 本地 Kokoro 朗读（ttsEngine: kokoro） | 首次用该引擎朗读 | Kokoro int8 模型集 |

- 下载源：优先 huggingface.co，失败时用 hf-mirror.com。除非在 profile 补丁里设置 allowCustomHost: true，否则只接受这两个域名（含 hf.co）。可以用 modelHost 固定某个镜像。
- 缓存目录：Windows 上是 %LOCALAPPDATA%\dsh-voice-mode\models，其他系统是 ~/.cache/dsh-voice-mode/models。
- 校验：每个文件在使用前都会比对固定的 SHA-256；未完成的下载先写成临时文件，校验通过后才改名。
- 进度：下载与加载进度显示在语音状态条上；失败会在对话里提示，而不是静默忽略。
- 离线：识别需要模型文件，ttsEngine: edge 每次朗读都需要联网。要完全离线，请预先填充缓存目录并改用 vits / kokoro。

已知限制

- 编译产物：lib/ 是上游的构建输出加本分叉的改动，并非从源码重新构建；请对照 dsh-voice-mode@0.7.15 看差异，不要期待可读的源码结构。
- 默认使用云端合成：ttsEngine: edge 会把朗读文本发送给微软。需要完全本地合成请改用 vits 或 kokoro。
- 外放时的打断依赖浏览器的回声消除；在 Windows 上，按住说话或戴耳机最可靠。
- 设置持久化只覆盖 rate 与 mode 这两个 volatile 字段；其他选项在启动时从 profile 补丁读取。
- 诊断会写本机日志：为了定位"说过的话整段丢失"，插件把每段识别结果（最多 400 字）和一组链路事件写进 DSH 的应用日志（desktop-next.log）。日志只落在本机，诊断接口只监听回环地址（POST /voice-mode/diag，同时校验同源）；但它记录的就是你的口述原文，介意的话请定期清理日志，也别把它装在共享账号的机器上。
- 语音纠错词表是本地文件：词条保存在 ~/.dsh/voice-dict.json（可用环境变量 DSH_VOICE_DICT 覆盖），不随本包发布；仓库里只有匹配逻辑，不含任何人的词条。

兼容矩阵

| DSH（@deepseek-ai/*） | 桌面壳 | 状态 |
| 0.2.0-rc.2 | DSH NEXT 2.0.17-next（Windows） | 已验证（加载、设置、合成、识别） |
| 0.1.7-rc.1 及更早 | — | 请用上游 dsh-voice-mode |
| 其他 | — | 未测 |

许可与归属

MIT。上游项目的版权声明保留在 LICENSE 中。本分叉为非官方适配，未获上游作者背书；包名与上游不同是刻意为之。

完整的适配记录——按顺序记录了什么失败、每次改动如何验证——见 docs/CHANGELOG.md。