前言¶
DeepSeek Harness（DSH）是一个插件化框架，旨在扩展其核心功能。语音输入通常需要切换窗口或复制粘贴文本。dsh-voice-input 插件在 DeepSeek Harness 的 composer 输入框中集成了一个麦克风按钮，并提供了一个 Web 设置页面。它通过浏览器引擎或任何 OpenAI 兼容的 /audio/transcriptions 端点实现语音转文字（ASR）。
核心功能¶
该插件具备以下能力：
- 输入框内集成：在输入框左侧工具栏增加麦克风按钮，支持开始/停止录音快捷键（Alt+M）及取消快捷键（Esc）。
- 实时状态反馈：录音时输入框上方出现状态条，显示电平、计时、实时文字、完成状态及错误信息。
- 双引擎支持：
- 浏览器引擎：零配置，调用浏览器原生语音识别（需 Chrome / Edge）。
- OpenAI 兼容 API 引擎：支持云端服务或本地服务，通过
/audio/transcriptions接口进行转录。
- 本地 ASR 支持：支持本机 Whisper 服务器，提供一键准备脚本。
- 零依赖安装：无构建步骤，无运行时依赖，宿主仅使用 Node 内置
fetch/FormData/Blob。 - 安全凭证管理：API Key 从凭证库读取（默认
VOICE_ASR_API_KEY），不在配置文件中明文存储。 - 自动错误处理：针对 401（认证错误）、404（路径错误）、413（文件过大）、超时等常见错误提供提示。
- 工具诊断：注册了
voice_input_status工具，可直接询问 DeepSeek 当前配置及状态。
安装与启用¶
在安装前，请确保环境满足以下要求：
- DeepSeek Harness
0.1.5-rc.1或更新版本。 - Node.js 22+（宿主端使用
AbortSignal.any、FormData、Blob）。 - 一个现代浏览器（Chrome / Edge 支持
SpeechRecognition；Firefox 不支持）。
执行以下命令进行安装：
# 执行安装
./install.ps1
安装完成后，刷新 Web UI，进入「设置 → 语音输入」即可使用。
若需卸载，请执行：
./install.ps1 -Uninstall
注意：不要与 dsh plugin --profile web add github:owner/repo 命令同时使用。
使用方法¶
基础操作¶
- 在输入框左侧工具栏点击麦克风按钮（或按
Alt+M）开始录音。 - 录音中按
Esc取消且不写入输入框。 - 说话结束后，转写结果会自动填入输入框。
引擎选择¶
- 浏览器引擎（无配置）：刷新页面后直接点击麦克风。若浏览器支持，将使用原生识别引擎。注意：浏览器引擎在中国大陆通常不可用。
- 云端转写接口：在设置页面配置接口地址（如 OpenAI、SiliconFlow、Groq 等）和模型。
- 本地转写：使用
local-asr/文件夹提供的离线 Whisper 服务，或通过设置页面的「本机后端（一键准备）」脚本启动。
Ollama 与本地模型¶
- Ollama：插件支持检测 Ollama 模型，但目前无法使用，因为 Ollama 0.34 版本的官方模型库中没有任何模型具备音频投影（audio/mmproj）能力。
- 本地 Whisper：推荐使用支持 OpenAI 协议的本地服务（如 whisper.cpp 或 faster-whisper-server）。
配置与注意事项¶
API Key 管理¶
插件不会在配置文件中保存 API Key，而是从凭证库按引用读取（VOICE_ASR_API_KEY）。这使得轮换 Key 对下一次录音立即生效，无需修改配置。
模型与浏览器限制¶
- Ollama：若要使用 Ollama 进行转写，模型必须具备音频投影（mmproj）能力。目前 Ollama 官方库中暂无此类模型。
- Firefox：由于不支持
SpeechRecognition，Firefox 无法使用浏览器原生引擎。
本机后端脚本¶
插件提供了 PowerShell 脚本用于管理本地 ASR 服务和 Ollama。安装脚本会自动处理 cordis.patch.yml 的托管行，并在安装完成后校验文件完整性。
