dsh-voice：DeepSeek Harness 的本地语音输入插件

前言¶

DeepSeek Harness (DSH) 是用于调试和开发智能体的工具。在智能体开发中，语音输入是一个常见需求，但通常需要依赖外部 API 或复杂的本地服务部署。dsh-voice 是一个插件，它为 DSH 引入了本地、私密的语音转文本能力，无需外部二进制文件即可运行。

插件介绍¶

dsh-voice 是一个单面插件，旨在为 DeepSeek Harness 提供 Web UI 和 TUI 的语音输入功能。

维护者：wencharmwang
许可证：MIT
核心价值：Host 端提供基于 ONNX 的本地 Whisper 服务，浏览器端集成麦克风按钮。

安装与启用¶

该插件以 Bundle 形式添加到 DSH Profile 中。

从 NPM 安装：

    dsh plugin --profile web add dsh-voice

或直接从 GitHub 安装：

    dsh plugin --profile web add github:wencharmwang/dsh-voice

注意：在使用 pnpm >= 10 从 Git 安装时，如果 prepare 脚本报错，需要在 Profile 的 pnpm-workspace.yaml 中配置 allowBuilds。

安装完成后，插件会自动激活 voice Row。也可以手动在 ~/.dsh/profiles/web/cordis.patch.yml 中声明 Row。

配置¶

所有配置均为可选，可通过 Patch 文件修改。配置项包括模型、语言、数据类型和缓存目录。

- id: voice
  config:
    model: onnx-community/whisper-medium  # Hugging Face Whisper ONNX ID 或本地目录
    language: auto                       # 'auto' | 'zh' | 'en' | ...
    dtype: q8                            # 'q8' | 'fp32' | 'q4'
    dir: ''                              # 模型缓存及录音目录，留空则使用默认路径

模型层级的优先级为：配置文件优先于 Schema 默认值。

功能与使用¶

Host 端服务 (ctx.stt)¶

插件在 Host 端暴露了 ctx.stt 服务，提供以下接口：

status()：检查就绪状态及当前模型，不加载/下载模型。
ensureModel(onProgress)：确保模型已下载并加载。
transcribe(input, options)：将音频输入转换为文本。支持 Float32Array (16kHz mono)、Buffer (PCM/WAV) 或文件路径。
startRecording() (TUI)：开始录音，返回 WAV 文件路径及停止/取消方法。

Web UI 交互¶

在 Web 界面的 Composer 中集成了麦克风按钮。录音在浏览器本地完成，解码为 16kHz 单声道 PCM 后，通过 HTTP 请求发送到 Host 端。

HTTP 路由¶

Web 模式下暴露了以下路由：

POST /voice/transcribe：接收音频数据，返回转录文本。支持查询参数 ?lang=<iso> 指定语言。
GET /voice/status：检查模型加载状态。

模型支持¶

插件支持从 Hugging Face Hub 下载的多种 Whisper ONNX 模型，模型缓存于 ~/.dsh/voice/models。

onnx-community/whisper-medium (约 0.8 GB，默认)
onnx-community/whisper-small (约 250 MB)
onnx-community/whisper-large-v3 (约 1.6 GB)

注意事项¶

TUI 录音依赖：TUI 模式下的麦克风录音功能需要系统级的录制工具（如 ffmpeg、sox 或 arecord）。
模型缓存：首次使用会自动下载模型，后续缓存于指定目录。
生态定位：本插件由社区开发者维护，与 DeepSeek 官方无直接隶属关系。使用前请检查源码与许可证。