离线语音输入 moazzamak/dsh-voice-input

dsh-voice-input

为 DeepSeek Harness 输入框提供离线本地语音转文字。

聊天输入框里会出现一个麦克风按钮。点一下，说话，再点一下，识别出的文字就追加到草稿里——你可以改掉听错的词，然后自己按 Enter。全程不上传：音频在浏览器里录制，发到你自己机器上的 harness 进程，在那里用跑在 CPU 上的 faster-whisper 解码。

环境要求

- 装了 Web GUI 的 DSH（web 配置档）。
- PATH 里有 Python 3.9+，用于一次性安装引擎（Windows 上是 python，其他平台是 python3）。
- uv 可选；有就用它，没有就退回 pip。
- 支持麦克风录制的 Chromium 系浏览器或 Firefox。

安装

1. Install the bundle into your profile.
dsh plugin --profile web add github:moazzamak/dsh-voice-input

2. Build the local engine once. It lives inside the installed package, which
creates a venv there and pre-downloads the default model.
python "$HOME/.dsh/profiles/web/node_modules/dsh-voice-input/python/setup.py"

Windows（PowerShell）：

dsh plugin --profile web add github:moazzamak/dsh-voice-input
python "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-voice-input\python\setup.py"

然后重启 DSH。注意 dsh web 是 web 配置档的固定别名——不存在 dsh web --profile other，而且 dsh plugin 指定的配置档必须和你实际启动的那个一致。

git 安装之外的几种方式

git 安装会拉取源码，pnpm ≥10 在你允许之前会拒绝运行包的 prepare 脚本。这个包发布的是纯 JavaScript，没有构建步骤，所以没什么要运行的，也没什么要允许的。

- Tarball： 在本目录执行 pnpm pack，然后 dsh plugin --profile web add ./dsh-voice-input-0.1.0.tgz。
- 本地检出： dsh plugin --profile web add /path/to/dsh-voice-input。
- npm： dsh plugin --profile web add dsh-voice-input（如果已发布）。

使用

在 Web GUI 里

麦克风按钮在输入框的工具行里，模型选择器左边。

| 状态 | 你会看到 |
| 空闲 | 灰色麦克风 |
| 录音中 | 红色停止方块、实时电平表，以及走动的 m:ss 计时 |
| 没有声音输入 | 电平表一直平着，并显示 no sound — check your microphone |
| 转写中 | 红色麦克风，transcribing… |
| 失败 | 按钮旁边出现红色提示（权限被拒、没听到语音、引擎出错） |

电平表才是重点，不是装饰：一个永远不动的录音指示，跟静音的麦克风根本分不出来。十四根竖条跟踪输入电平，采样自同一条流，走的是 AnalyserNode，所以你在停止之前就能看到自己的声音进来了。
分析器刻意从不连接到音频输出——否则会通过你的扬声器产生回授。

如果输入持续静音约 1.5 秒，电平表会变暗并显示提示。这覆盖了电平表单独无法处理的情况：静音的麦克风和暂停的扬声器看起来都是平的，提示会告诉你该检查哪一个。

转写文本会追加到草稿已有内容之后，用一个空格分隔。它绝不会替你发送。

清理环节

语音里会有填充词、口误，偶尔还有听错。识别完成后，转写文本会经过本次部署已经选定的模型，由它去掉填充词（um、uh、犹豫的「like」），合并结巴，加上标点，修正明显的听错——同时被明确禁止改变含义、翻译，或触碰标识符与技术术语。

实操示例，用一段刻意堆满填充词的录音：

| 阶段 | 文本 |
| Whisper | Umm, so, uhh, like, can you please, you know, refactor the parser and then, umm, run the tests. |
| 清理后 | Can you please refactor the parser and then run the tests? |

之后按钮旁边会出现一个小标记 cleaned up，让你知道跑过一轮清理。

清理是尽力而为，绝不会让你丢掉转写文本。 以下任一情况都会保留识别器自己的文本，并把原因写进宿主日志：

- 清理调用报错、超时，或什么都没返回；
- 改写后长度变化小于一半或大于 1.8×——这是模型在回答请求而不是在清理的特征；
- 无法解析出任何模型路由。

用 polish: off 关掉它，或用 polishProvider + polishModel 把它固定到某个特定（小、便宜）的路由，这样清理就不会占用智能体正在用的大模型。voice_transcribe 工具支持每次调用传 polish: false。

在任何界面上，作为工具使用

同一个引擎也是面向模型的工具，所以命令行、SDK 或 ACP 会话都能转写音频文件，无需浏览器参与：

dsh --profile headless "transcribe /path/to/meeting.m4a and save the transcript next to it"

工具是 voice_transcribe：

| 参数 | 必填 | 含义 |
| path | 是 | 要转写的音频文件；相对路径按会话工作目录解析 |
| language | 否 | 语言代码，或 auto；默认用配置的语言 |
| polish | 否 | false 返回识别器的文本，不做清理环节 |

它返回转写文本，或一条说明失败原因的消息。接受的容器是 ffmpeg 能解码的任何格式——wav、mp3、m4a、webm/opus、ogg、flac。浏览器路由和工具共用一个引擎、一份缓存、一套配置。

因为工具在每个界面上都存在，而路由只在浏览器能到达的地方存在，插件声明对 webServer 没有硬依赖：headless 或 SDK 配置档会加载它、注册工具，并跳过路由。

配置

每个选项都有可用的默认值，所以配置是可选的。要修改某一项，覆盖 $DSH_HOME/profiles/web/cordis.patch.yml 里对应的行即可——补丁会替换该行的整个 config，所以你想保留的键都要重新写一遍：

- id: voice-input
name: dsh-voice-input
config:
model: small.en
language: en
computeType: int8
timeoutMs: 300000

| 键 | 默认值 | 含义 |
| model | base.en | Whisper 模型大小或名称 |
| language | en | 口语语言，或设为 auto 自动检测 |
| computeType | int8 | CTranslate2 计算类型 |
| timeoutMs | 300000 | 单次转写的截止时间 |
| polish | conservative | 用模型清理转写文本；off 返回原始文本 |
| polishTimeoutMs | 15000 | 仅清理调用的截止时间 |
| polishProvider / polishModel | 当前选择 | 把清理固定到特定路由 |
| pythonPath | 包内 .venv | 带 faster-whisper 的解释器 |
| scriptPath | 内置命令行 | 转写脚本 |
| cacheDir | $DSH_HOME/cache/voice-models | 模型权重缓存 |

清理使用部署已经选定的模型，所以不需要第二份凭据，也不需要额外配置。它就是一次普通的 ctx.llm.stream 调用——和智能体用的是同一条路由——以 temperature: 0 运行，并有自己的截止时间。

选择模型

| 模型 | 大小 | 说明 |
| tiny.en | ~75 MB | 最快，准确度最低 |
| base.en | ~150 MB | 默认；大约每 5 秒语音消耗 1 秒 CPU |
| small.en | ~500 MB | 明显更好，计算量约为 3 倍 |

多语言模型去掉 .en 后缀（base、small），并搭配 language: auto。未缓存的模型会在首次使用时下载，需要联网一次。

如果 huggingface.co 被屏蔽，启动 DSH 前把 DSH_VOICE_HF_ENDPOINT 设为镜像地址，例如 https://hf-mirror.com。

隐私

- 音频由浏览器录制，并发送到 harness 自己的回环 HTTP 服务器。
- 转写在本地子进程里运行。音频、文本、模型请求都不会离开本机；唯一的网络访问是一次性的模型下载。
- 挂载了 composition 的 connection 信任围栏时，路由由它守护（Host/Origin 检查，可挡住 DNS 重绑定和跨站提交）；否则由服务器的回环绑定守护。
- 录音暂存在操作系统临时目录下，不会自动清理；想回收空间时，清空 %TEMP%\dsh-voice-input（Windows）或 /tmp/dsh-voice-input。

工作原理

两半，一个 npm 包：

- 宿主半边（index.mjs）在 tools 上注册面向模型的 voice_transcribe 工具，并在 composition 的 webServer 上注册一条精确的 POST 路由 /voice-input/transcribe。它把音频暂存到临时文件，并通过 shell 服务运行内置命令行（lib/engine.mjs）。
- 浏览器半边（client.cjs）在 conversation.input.left 插槽，用 MediaRecorder 录音，用 AnalyserNode 对同一路流做电平检测，把字节发出去，再用结果调用 inputActions.setDraft()。

有五个细节是关键，而且每一个都是测出来的，不是读出来的：

- 宿主负责落盘，引擎只读。 受限 shell 会拒绝写入会话工作区之外的任何位置——包括平台临时目录根——所以引擎如果自己写一份解码后的副本，就会以 PermissionError 失败。把所有写入都留在宿主进程里，引擎在任何沙箱策略下都能用。
- shell 用自己的解释器解析命令字符串（Windows 上是 pwsh -Command）。因此命令位置上的带引号路径对 PowerShell 来说不是可执行文件，所以 Windows 命令要包在 cmd /c 里。
- 路由是延迟的，不是声明的。 webServer 不能作为硬依赖（headless/SDK/ACP 配置档都没有它），而且它是在这一行的 apply 之后才发布的——所以在那里读一次只会看到 undefined，路由就静默地永远不注册。再开一行去等它同样不对：启动审计只要发现任何条目还处于 pending 就会失败（N entry did not activate）。ctx.inject(['webServer'], …) 才是正确的延迟写法，在任何地方都能保持绿灯。
- 工具 schema 是标准 JSON Schema。 服务商会逐字校验 parameters，所以必填项必须是对象级的 required: [...] 数组。仓库内的 defineTool 辅助函数接受按属性写 required: true 的便捷写法，但这种写法在传输时会被拒绝。
- 插槽名不是服务。 浏览器 Loader 在 apply 运行之前就解析 bundle 的 inject 列表，而客户端启动审计只要发现任何条目还处于 pending 就会让页面失败——所以声明 conversation.input.left 会产生 pending (waiting for service: conversation.input.left)，把整个 Web 启动拖垮。slots.inject(…) 才是等待插槽声明的写法；bundle 只声明 slots。定时器服务出于同一类原因也是探测而不是声明，没有它电平检测会无害地降级。

引擎 venv 位于包根目录（<package>/.venv），从 lib/engine.mjs 解析，所以两个宿主职责找到的是同一个解释器。

故障排查

| 症状 | 原因与修复 |
| 没有麦克风按钮 | bundle 安装到了与启动时不同的配置档。dsh web 永远指 web 配置档。 |
| 启动时出现 pending (waiting for service: webServer) | 旧版本把 webServer 声明为硬依赖，或者声明为单独等待的一行。更新即可；路由现在用 ctx.inject 延迟。 |
| 按钮出现了，但每次录音都因引擎路径错误失败 | 旧版本解析 venv 时相对了错误的模块。更新，然后重新运行 python/setup.py。 |
| Invalid schema for function 'voice_transcribe' | 旧版本用了仓库内按属性写 required: true 的写法。更新即可。 |
| faster-whisper is not installed in this interpreter | 运行 python/setup.py；或者把 pythonPath 指向你实际安装依赖的那个解释器。 |
| ModuleNotFoundError: av / metadata_errors | av 19 删掉了 faster-whisper 传入的一个参数。setup.py 把 av<19 固定住；用它重新安装。 |
| Microphone permission was denied | 在浏览器的站点设置里，为 harness 的来源放行麦克风权限。 |
| no speech was recognized | 录音是静音，或者太短。 |
| the transcription engine exited with code 1 … PermissionError | 旧版本会把待写入的数据先放好，再让子进程去写。更新即可。 |

Development

把检出目录直接安装进一个临时配置档，该配置档基于 web 模板构建：

dsh --profile voicetest --from-default-profile web --dump-config
dsh plugin --profile voicetest add /path/to/dsh-voice-input
dsh --profile voicetest

不启动 harness 也能跑引擎：

python/.venv/Scripts/python.exe python/transcribe.py --audio sample.webm

契约测试（npm test）覆盖宿主与浏览器插件的形态、行拆分、bundle 的注册格式，以及工具的参数字段结构。它们覆盖不到浏览器行为，所以 tools/cdp-check.mjs 通过 DevTools Protocol 驱动真实的 Chrome：加载正在运行的页面，断言客户端入口已生效，点击麦克风，再采样 DOM，确认时钟在走、音量条在动。

Against a harness already listening (its logged URL carries the token):
node tools/cdp-check.mjs "http://127.0.0.1:3080/?token=<token>" 9333

它会自己在单独的调试端口上启动 Chrome，使用 Chrome 的假采集设备，如果启动审计失败、或者音量条与时钟停住不动，就以非零码退出。这正是单元测试够不到的那一半——计时器和注入的缺陷就是它抓出来的。

License

MIT