前言¶
DeepSeek Harness (DSH) 采用插件化架构，允许通过 Web 界面进行智能体开发与交互。在 Web composer 场景下，频繁切换输入法或手动打字会影响交互效率。dsh-dictation-hotkey 旨在解决这一问题，提供一种基于快捷键的语音输入方式，复用本地 SenseVoice 引擎，无需额外下载模型或调用云端 API。
插件概述¶
该插件为 DSH Web composer 提供“按住说话”功能。它不引入独立的识别进程，而是直接驱动 DSH 官方 Web composer 内置的语音 Remote（SenseVoice），通过官方 API 将转写结果插入编辑器。
核心功能¶
- 模式控制：支持“按住说话”或“切换模式”。
- 发送策略：支持将转写内容“填充”到编辑器供检查，或“立即发送”。
- 原生集成：复用官方语音输入 bundle，不引入独立的识别器进程。
- 原生插入：通过官方 API 将文本插入编辑器，保留光标位置和附件。
- 配置管理：快捷键、模式、行为、提示音等配置存储在浏览器本地。
- 多场景支持：在新建对话页面也可工作（需有焦点编辑器）。
- 诊断日志：提供音量、时长、推理时间等诊断信息。
安装与启用¶
插件依赖 DSH 的官方语音输入 bundle，安装前需确保环境满足要求。
前置条件
* DSH 版本：0.2.0-rc.2 或兼容版本。
* 插件管理器中启用“语音输入” bundle。
安装步骤
1. 打开终端，执行安装命令：
dsh plugin --profile web add github:AndyYang12345/dsh-dictation-hotkey
- 重载 DSH Web UI。
使用方法¶
安装后，在 composer 下方的工具栏会出现一个“🎙 Dictation” pill。
基本操作
* 按住 Ctrl+Shift+Space，开始说话，松开后文本插入编辑器。
* 点击 pill 图标可配置快捷键、发送行为（填充/发送）、模式（按住/切换）、提示音和诊断开关。
常用配置项
配置存储在浏览器 localStorage 的 dsh-dictation-hotkey.settings 键下。
| 配置项 | 默认值 | 说明 |
|---|---|---|
hotkey |
Ctrl+Shift+Space |
快捷键组合，支持 + 分隔。 |
mode |
hold |
hold (按住录音) / toggle (点击开始/停止)。 |
autoSend |
false |
是否在插入文本后自动发送。 |
beep |
true |
是否播放提示音。 |
language |
(空) | 识别语言提示，空则跟随 DSH 设置。 |
providerId |
(空) | 语音提供者 ID。 |
minRecordMs |
150 |
最小录音时长（毫秒），过短会被拒绝。 |
tailMs |
180 |
松开按键后保留的音频时长（毫秒）。 |
maxRecordSeconds |
60 |
最大录音时长（秒）。 |
debug |
false |
是否开启诊断日志。 |
诊断与调试¶
在 pill 配置界面开启“诊断日志”后，每次按键操作都会记录一条结构化日志。
日志事件类型
* start: 麦克风启动，记录触发按键。
* stop: 松开按键，记录录音时长。
* ok: 识别成功，记录音频时长、推理时间、字符数、音量峰值。
* empty-transcript: 返回空文本，记录音量峰值。
* skip: 被阈值拒绝（如录音过短、无音频、语音 Remote 未挂载）。
* transcribe-failed / mic-failed / insert-conflict / finish-threw: 对应的失败事件。
限制与注意事项¶
- 快捷键范围：快捷键仅在 DSH 页面获得焦点时有效，不支持系统级全局快捷键。
- 麦克风权限：麦克风权限仅授予 DSH 域，首次使用可能需要点击官方麦克风按钮授权。
- 录音时长：受
maxRecordSeconds（默认 60s）及 Remote 音频限制。 - 开发环境：本地开发需要 Node.js 版本
^22.19.0或>=24.0.0。
结语¶
该插件通过复用官方 SenseVoice 引擎和 Web composer API，降低了语音输入的门槛，适合需要频繁进行语音交互的开发场景。
