前言¶
在 DSH Web 界面里写长提示、改 slash 命令，键盘仍是主路径；若希望「点一下说话、把文字填进输入框」，或让助手回复用本地 TTS 读出来，通常要接云端 ASR/TTS，或自己写浏览器录音与后端转写。DeepSeek Harness 社区插件 dsh-voice（维护者 MathieuPortmann，GitHub 仓库 MathieuPortmann/dsh-voice）把听写、口语化命令和朗读收进同一套离线工具链：页面侧点按开麦，主机侧用 faster-whisper 与 Piper，运行时不再访问外网。下面介绍它做什么、如何安装，以及使用时需要注意的点。
这是什么¶
dsh-voice 是面向 DSH Web profile 的插件（分类：模型推理）。它在聊天页 Send 旁增加麦克风按钮，在每条回答下方增加 Read 按钮；录音转文字后只写入消息框，不会自动发送。无唤醒词、无常开麦克风：仅在用户两次点击麦克风之间向浏览器申请麦克风，录完即释放。界面随 DSH 语言在英文与法文间切换（client.js 顶部 en / fr 表）。维护状态为 best-effort，Issue 可能无人回复，欢迎 fork。
核心功能¶
听写（Dictation）¶
- 点击麦克风开始录音，再次点击结束（单次最长约 10 分钟，受
maxAudioMB等配置约束）。 - 页面用
MediaRecorder录制，再转为 16 kHz 单声道 WAV。 - 主机用 faster-whisper（默认
small，CPU、int8）转写，自动识别法语或英语，文本追加到输入框。
口语命令（Spoken commands）¶
以 command … 或 commande … 开头的听写，会映射为当前会话里已有的 slash 命令或 skill 名称，例如：
command web on→/web oncommand science reading …→/science-reading …
未知名称保留为普通文本并给出提示。映射逻辑在 lib/commands.js，与 DSH 原生实现对照过大量生成用例。
朗读（Read aloud）¶
每条回答下的 Read 按钮调用本地 Piper 合成语音；根据文本猜测法语或英语音色。代码块会被跳过。
安装与启用¶
环境要求（来自 README Compatibility）：Node.js ^22.19.0 || >=24.0.0；DSH >=0.2.0-rc.2 <0.3.0；Linux 上已测试；浏览器需支持 MediaRecorder 与 Web Audio（当前 Chromium、Firefox）。Python 工具在资料中于 Python 3.12、faster-whisper 1.2.1、piper-tts 1.8.0 下验证。
1. 安装插件¶
在 Web profile 下执行官方命令：
dsh plugin --profile web add github:MathieuPortmann/dsh-voice
包上架 npm 后，也可使用：
dsh plugin --profile web add dsh-voice
2. 一次性准备语音工具¶
默认目录为 ~/.dsh/tools/voice（即 <DSH_HOME>/tools/voice）。需要 Python 3.10 及以上；含模型约占用 1 GB 磁盘。下列命令会从 Hugging Face 下载模型，仅此阶段需要网络；之后 worker 离线运行。
python3 -m venv ~/.dsh/tools/voice
~/.dsh/tools/voice/bin/pip install faster-whisper piper-tts
~/.dsh/tools/voice/bin/python -m piper.download_voices --download-dir ~/.dsh/tools/voice/models/piper fr_FR-siwis-medium en_US-lessac-medium
~/.dsh/tools/voice/bin/python -c "from faster_whisper import WhisperModel; WhisperModel('small', device='cpu', compute_type='int8', download_root='$HOME/.dsh/tools/voice/models/whisper')"
3. 重启 profile¶
重启 DSH Web profile 后，首次听写时浏览器会请求麦克风权限。
配置¶
在 profile 的 voice 行可改选项；均有默认值。听写与朗读仅支持法语和英语。
| 选项 | 默认值 | 含义 |
|---|---|---|
python |
<DSH_HOME>/tools/voice/bin/python |
语音虚拟环境中的 Python |
modelsDir |
<DSH_HOME>/tools/voice/models |
含 whisper/ 与 piper/ 的目录 |
whisperModel |
small |
faster-whisper 模型规模（多语言可用 base、small、medium 等） |
voiceFr, voiceEn |
fr_FR-siwis-medium, en_US-lessac-medium |
Piper 音色（<modelsDir>/piper/<voice>.onnx） |
hotwords |
commande command DeepSeek DSH Ollama Piper Whisper |
转写时优先拼对的词 |
threads |
min(6, CPU threads) |
worker CPU 线程数 |
idleMinutes |
10 |
空闲多久停止 worker（约释放 1～2 GB 内存） |
maxAudioMB |
20 |
接受的最大录音体积（约 10 分钟） |
maxReadChars |
8000 |
单次朗读最长字符数 |
典型用法¶
- 打开 DSH Web 聊天页，在 Send 旁点麦克风，口述内容后再次点击结束；确认转写出现在输入框，按需编辑再发送。
- 需要切换会话能力时，可说「command web on」等形式，让文本变为对应
/web on等命令后再发送。 - 阅读长回答时，点该条下的 Read，本地 Piper 朗读正文（跳过代码块）。
架构与权限（简要）¶
- client.js：绘制按钮、录音、WAV 转换、播放 TTS 音频。
- index.js：注册
POST /voice-api/<stt|tts|to-command|warm>，经ctx.connection.admit()校验；启动长期 Python worker（Whisper 只加载一次），空闲idleMinutes后退出。 - worker/voice_worker.py：按行读 JSON 请求、按行回 JSON（转写或合成）；运行时设
HF_HUB_OFFLINE=1，不访问网络。
插件不新增模型侧 tool，也不会替用户发消息。子进程、临时 WAV、模型文件读写均在当前 DSH 进程权限下进行；安装前建议阅读仓库源码与 MIT 许可证。麦克风被拒时页面提示 “microphone blocked or missing”；Python 或模型缺失时听写/朗读会返回错误（如 “voice tools are not installed”）。按钮位置依赖 Send、Copy 的英/法标签，Web UI 改版后可能需要插件更新。
适用场景与注意¶
适合希望在本机离线完成听写与朗读、且主要使用 DSH Web 界面、内容以英法为主的开发者。不适合需要唤醒词、常开麦克风或运行时云端语音 API 的场景。
插件以 best-effort 维护；社区目录 skillhub.cn 上的 dsh-voice 页 与 GitHub 均为社区信息来源，与 DeepSeek / 幻方无官方从属关系。DSH 生态强调「一切皆插件」，安装第三方插件前请自行评估权限与依赖。
结尾¶
经过上面的步骤，你可以在 DSH Web 里用点击式听写填框、用口语前缀触发已有命令，并用 Piper 本地朗读回复——全程数据留在本机，运行时无出站网络。详情与 Issue 见 GitHub：MathieuPortmann/dsh-voice，目录入口见 SkillHub 插件页。
