语音输入 KotDath/dsh-voice

dsh-voice

DeepSeek Harness Web GUI 的语音输入——作为官方插件包。

麦克风按钮（SVG 图标）位于输入框发送按钮旁边。
点击它会在输入框上方弹出 ChatGPT 风格的录音“胶囊”：

[ ✕ 取消 ] [ 波形 ] [ ⏹ 停止 ] [ ↑ 发送 ]

- ✕ —— 取消录音；
- ⏹ —— 停止、转写并将文本插入输入框（不发送）；
- ↑ —— 停止、转写并立即发送到聊天。

波形是一排竖条：新信号从右侧进入，历史向左淡出，变成一条暗淡的虚线基线（类似 ChatGPT 的语音模式）。

安装

要求

- 一个正在运行的、带 Web GUI 的 DeepSeek Harness（Node.js 快速启动：
npx @deepseek-ai/dsh web，默认 http://127.0.0.1:3080）。
- 在主机上：bash、curl（引擎/模型下载）、ffmpeg（音频转换）。transcribe.cpp 引擎会根据操作系统/架构自动从本仓库的 Releases 下载——或者如果已存在 transcribe-cli 二进制文件，则从 PATH / 同级 .engine/ 目录采用。
- 一个可通过 HTTPS 或 localhost 访问麦克风的浏览器。

安装到某个 profile（所有会话）

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

如果改用本地测试构建：

npm install && npm run build
dsh plugin --profile web add file:/path/to/dsh-voice

然后重启 web 进程（dsh web）——新的插件行会在启动时被加载。
之后该插件在该 profile 的每个会话中都处于活动状态：无需按会话执行 cordis_define，也无需修改源码。

该包声明了 dsh.bundle.patch（→ cordis.patch.yml，一行 id: voice, name: dsh-voice）和 dsh.client（→ 浏览器端 lib/client.js）。dsh plugin 会用 pnpm 将其安装到 profile 中，并自动协调 dsh.profile.bundles。

卸载：

dsh plugin --profile web remove dsh-voice

首次运行流程（面向最终用户）

1. 打开 Settings → Voice —— 引擎要么显示 ✓ installed，要么可通过一键点击下载（“Download engine”，由 CI 构建的 releases）。
2. 从目录中选择一个模型，如果它未标记为 ✓，则按 Download。
3. 使用输入框发送按钮旁边的麦克风按钮。
4. 录音 → ✕ 取消 / ⏹ 插入 / ↑ 发送。

架构

[客户端：浏览器] [主机：Node]
┌─────────────────────────────────┐ fetch ┌────────────────────────────────┐
│ slot conversation.input.right │ ──────────► │ /api/voice/transcribe │
│ • MediaRecorder (webm/opus) │ base64+meta │ • base64 -d → file │
│ • AnalyserNode → waveform │ │ • ffmpeg → 16 kHz mono wav │
│ • timers, states │ ◄─────────── │ • provider: │
│ inputActions.setDraft + submit │ { text } │ tcpp: transcribe-cli │
└─────────────────────────────────┘ │ local: whisper-cli -oj │
│ api：curl 多部分表单 │ │ codex：ChatGPT 后端 │ │ （$CODEX_HOME auth.json） │ │ • 临时文件清理 │ └────────────────────────────────┘

与早期的动态插件版本不同，这两部分不使用 harness.handle/host.call 桥接：Node 部分在 harness webserver 上注册普通的 HTTP 端点（/api/voice/），浏览器部分则通过 fetch 调用它们。这正是其他静态 bundle 插件（例如 dsh-track）所使用的模式。

转录提供方

可在 设置 → 语音 中切换（状态保存在内存中，这符合插件 bundle 的预期行为）。

| 提供方 | 工作方式 | 要求 |
| tcpp（默认） | transcribe.cpp 引擎（与 Handy 内部使用的是同一个）——一个静态的 transcribe-cli 二进制文件（约 5 MB）。包含 67 个模型的目录（GigaAM v3 CTC/RNN-T/E2E、Voxtral Mini 3B/4B/24B、Whisper tiny…large-v3（+turbo）、Qwen3-ASR、Parakeet、Canary、Moonshine、Nemotron、Granite、SenseVoice、Fun-ASR、Cohere、MedASR……）。模型选择下拉框，一键从 Hugging Face 下载并显示进度 | 引擎（在 Win/macOS/Linux 上自行下载） |
| codex | 本地 Codex CLI 登录背后的 ChatGPT 订阅：录音会使用 $CODEX_HOME/auth.json 中的 OAuth 令牌发送到 ChatGPT 后端语音转文本端点 | 主机上已执行 codex login；无需 API 密钥，无需下载模型 |
| local | whisper.cpp（whisper-cli）+ 一个 GGML 模型 | 二进制文件和模型的路径；离线 |
| api | OpenAI 兼容的 POST /v1/audio/transcriptions（多部分表单） | URL、API 密钥、模型名称（gpt-4o-transcribe、whisper-1、Groq、本地 faster-whisper 服务器等） |

Codex / ChatGPT 订阅

如果主机已使用 ChatGPT 套餐登录 Codex CLI，那么该订阅就可以转录语音输入——无需下载任何内容，也无需 API 密钥：

1. 在主机上执行 codex login（一次），然后进入 设置 → 语音 → 转录提供方 → Codex。面板会显示账户、套餐和令牌到期时间，而 测试 会通过真实路径发送一秒静音，一键验证登录、端点和 ffmpeg。
2. 照常录音。整段录音（最多 5 分钟上限）会作为单个 16 kHz WAV 请求发送——与本地模型不同，该端点会在数分钟内保持上下文，因此长听写不再需要 tcpp 所用的 20 秒分块。

其行为方式如下：

- 凭据：主机会读取 $CODEX_HOME/auth.json（默认 ~/.codex/auth.json），并通过 DSHVOICE_CODEX_TOKEN 环境变量将访问令牌传递给 curl——绝不出现在 argv 中，令牌也绝不会到达页面（设置中只能看到账户、套餐和过期）。该文件可以在高级中指向其他位置。
- 它永远不会被写入。 插件不会刷新或重写登录信息：ChatGPT 刷新令牌会轮换，而第二个写入者会使 Codex CLI 自身所依赖的登录失效。如果令牌过期，面板会提示——运行任意 codex 命令（或 codex login）即可刷新它。
- 语言：该端点接受具体的语言代码（对于 ru/en/uk/de，会转发 Language 设置）。Auto 在那里不是有效值，会被直接省略，这正是自动检测能够生效的原因。
- 错误会被解码，而不是原样抛出：登录过期会报告 401 以及修复方法，Cloudflare 拦截会报告 403，速率限制会报告 429。
- API 密钥模式下的 auth.json 会按此情况报告——该模式无法使用订阅端点。

在本机实测：一段 5 分钟的俄语听写在一个请求中约 68 秒完成转写，一段 50 秒的约 13 秒完成。

transcribe-cli 引擎：开箱即用，无需 Handy 应用

- 该插件不依赖 Handy 应用程序：ASR 引擎是开源库 handy-computer/transcribe.cpp。
- 该二进制文件通过“Download engine”按钮从本仓库针对当前操作系统/架构的 GitHub Releases 下载（transcribe-cli-{platform}-{arch}，Windows 上为 .exe）。
- 如果 PATH 中或配置的引擎路径旁边已经存在 transcribe-cli，插件会采用它（将其复制到自己的目录中）——无需下载。发现是显式的；不会扫描文件系统。
- 当发布了 .sha256 附属文件时，下载内容会据此校验（尽力而为的完整性检查）。
- 插件数据（引擎、模型、临时文件）位于 DSH 进程启动目录（.engine/、.models/、.tmp/）——沙箱只允许在那里写入。路径会在设置中显示。
- 发布二进制文件由 CI 构建（.github/workflows/build-engine.yml）：Linux x86_64/arm64、macOS arm64/x86_64、Windows x86_64。
- 模型是来自 Hugging Face（handy-computer）的 GGUF 文件；目录内嵌在插件中（大小决定进度条）。Handy 已下载到 HF 缓存中的模型会被自动识别——无需重新下载。
- 长录音：许多模型有约 25 秒的窗口（例如 GigaAM），会静默丢失长录音的其余部分。插件会将超过 22 秒的音频拆分为 20 秒的片段，并在一次批处理运行中转写它们（单次模型加载，全文拼接）。

在本机验证：GigaAM v3 E2E-RNN-T——30 倍实时，Voxtral Mini 4B Realtime——1.7 倍实时（20 秒俄语音频），质量极佳。

API 密钥与 Codex 凭据处理

OpenAI 兼容的 API 密钥是仅限主机端的：它通过自己的端点（POST /api/voice/api-key）设置，绝不会回显到页面（设置中只显示是否已设置密钥），并通过 DSHVOICE_API_KEY 环境变量——绝不出现在 argv 中。

Codex 提供程序对 ChatGPT 登录应用相同的规则：宿主读取 $CODEX_HOME/auth.json，将访问令牌作为 DSHVOICE_CODEX_TOKEN 传递（同样绝不出现在 argv 中），仅向页面暴露账户、套餐和到期时间，并且从不写入该文件。

开发

npm install # dev deps (uses .npm-cache/ if ~/.npm is read-only)
npm run build # gen-catalog → tsc → tsdown (lib/index.js + lib/client.js)
npm test # both Node suites (plain Node, no browser)

npm test 运行 test/run.mjs（bundle/catalog 契约）和 test/codex.mjs
（Codex 提供程序，挂载在伪造的 Cordis 上下文上——默认离线）。
添加 DSH_VOICE_LIVE=1 还可使用本宿主的 Codex 登录驱动真实的 ChatGPT 后端：

DSH_VOICE_LIVE=1 node test/codex.mjs

可安装的产物是位于仓库根目录的 npm 包。完整代理说明（布局、端点、安全规则、故障排除）见 AGENTS.md。

仓库布局

src/plugin/ — Node half (index.ts, HTTP /api/voice/) + browser half (client/: state, recorder, waveform, components, settings, voice.module.css) + generated catalog scripts/gen-catalog.mjs — injects models.json into generated-catalog.ts tsdown.config.ts — node ESM bundle + browser CJS-closure bundle cordis.patch.yml — the bundle's composition patch (one row: id voice) package.json — dsh.bundle.patch + dsh.client declarations models.json — model catalog (source of truth) test/ — Node suites: run.mjs (bundle contract) + codex.mjs (Codex provider; DSH_VOICE_LIVE=1 adds real API calls) .github/workflows/build-engine.yml — CI: plugin tests + 5-platform engine builds AGENTS.md — agent install/update instructions README.md — this document

已发布的版本通过 git 标签固定（v0.4.0、……）。

v1 限制

- 录音使用浏览器的 MediaRecorder（需要 HTTPS 或 localhost）。
- 转录为批处理（录音结束后）；流式部分结果已在计划中。
- 上游 whisper.cpp 不支持 Handy 的 Qwen3-ASR GGUF（需要 transcribe-cpp 引擎）；标准 ggml 模型（tiny…large-v3）可正常工作。