dsh-asr-voice

dsh-asr-voice — 语音输入（Voice Input）

开口即成文，落键即送达。
Speak, and the words are already written.

关于 About

说话，然后文字已经写好。— Say it; the words are already written.

dsh-asr-voice 是 DeepSeek Harness 的语音输入之翼：以云端之耳倾听，以优化之手成文， 让每一次开口都直接落为可用的提示词。对着麦克风说出想法，插件把口语转成干净、可直接发送的提示词， 体验如 Codex 语音输入般顺滑。

A voice-input companion for DeepSeek Harness: it listens with cloud ears and drafts with a polishing hand, turning every utterance into a clean, send-ready prompt — as fluid as Codex voice input.

特色 Highlights

• 混合识别，进退自如 — Hybrid ASR, always a way out 浏览器 Web Speech 优先（免费、免 key、Chrome/Edge 双平台）；不可用或被网络屏蔽时 自动回落到已配置的云端。云端支持多供应商：小米 MiMo / OpenAI / Groq / 硅基流动 / 通义 Qwen-ASR 可同存并蓄。设置页是一张三步向导：选方式 → 点服务商 → 看密钥状态， 点「测试连接」即自检并把该端点真实可用的模型灌进模型下拉。 Web Speech first, with automatic fallback to your cloud ASR. Multiple providers (MiMo, OpenAI, Groq, SiliconFlow, Qwen-ASR) can coexist. Settings is a three-step wizard: pick the engine, click a provider, check the key — “Test connection” self-checks and lists real models.

• 开口即对话 — Talk to the agent, not at a text box 开启实时对话后：边说边上字幕，停顿即发起回合，agent 回复按句朗读，念完自动把麦克风还回来 听下一句。半双工——朗读期间不收音，按钮 / 快捷键 / 提示条 × 三处都能打断；零 key 零配置。 Speak, see live captions, and a pause sends the turn; the reply is read back sentence by sentence, then the mic comes back. Half-duplex — capture is gated while it speaks, and three affordances interrupt. No key, no setup.

• 优化润于无声 — Polished without interrupting 停止录音，约一秒即把清洗版填入草稿；LLM 优化在后台润色，完成自动替换，不覆盖你的编辑。 Stop recording and the cleaned draft lands in about a second, while LLM polish happens in the background and replaces it only when done — your edits are never overwritten.

• 隐私自守 — Privacy by design API key 只落在 DSH 凭据服务（与 LLM 共用同一份凭据体系），既不进插件 settings、也不进 浏览器 DOM，设置页只显示「已配置 / 未配置」。录音在本地完成格式转换后再上传，浏览器仅经 /api/asr-voice/* 私有 JSON 代理而行。 API keys live in the DSH credential store only — never in the plugin's settings document nor the browser DOM (the UI shows “configured / not configured”, nothing more). Audio is converted locally before upload, and the browser talks through a private local proxy.

• 处处顺手 — Thoughtful touches 结果一键复制剪贴板（默认开）、完整替换或末尾追加、快捷键与按住说话、用量统计一目了然。 One-tap clipboard, replace-or-append insertion, hotkey & hold-to-talk, and a glanceable usage stats.

• 独立干净 — Zero third-party runtime 运行时只依赖官方 @deepseek-ai/* peer 包，可单独用、可组合用。 Runs on official @deepseek-ai/ peers only — usable alone or alongside other plugins.*

功能 Features

• 输入框工具行麦克风按钮（conversation.input.right）：点击开始/结束（默认手动关麦， 点停止即整段去识别；可选静音自动停止），可选按住说话
• 默认快捷键 Ctrl+Shift+Space（可配置，支持 macOS 的 Cmd 兼容）
• 识别后填入草稿待确认；可选「识别后自动发送」（push-to-talk 风格）
• 语音对话（默认开，realtime.enabled）：与麦克风同一个按钮——点 = 录音转写， 长按约 450ms = 进入语音对话（对话中再点 = 打断播报 / 结束对话）；关 realtime.enabled 即回到纯整段模式，按钮只剩「点 = 转写」。边说边上字幕 → 停顿即发起 agent 回合 → 回复按句朗读 → 念完自动回到聆听，半双工、点按可打断
• 设置卡片：「设置 → 插件 → 配置 → 语音输入」= 三步向导 + 默认折叠的「高级」（BaseURL / 模型 / 通道 / 多服务商 / 语言 / 优化 / 快捷键 / 用量）；改动先进本地草稿，点「保存」才写回， 写回后按段读回校验

快速开始 Quick start

三步，多数情况下一个 key 都不用填：

1. ① 识别方式 选「云端」（只想用浏览器识别的选「仅浏览器」，后面两步直接跳过）。
2. ② 服务商 点一个 chip（OpenAI / Groq / 硅基流动 / 小米 MiMo / 阿里云百炼 / 自定义）， BaseURL、模型、调用通道自动填好。
3. ③ 密钥与自检 看这一行的状态：
   • 显示 ✓ 已使用 DSH 凭据 OPENAI_API_KEY → 已经复用了你在 DSH 里配过的同名 LLM 凭据，无需任何输入。
   • 显示未配置 → 把 key 粘进输入框点「保存密钥」；key 只写入 DSH 凭据，不回显、不进配置文件。
   • 点「测试连接」自检（列一次该端点的模型：一次验掉 key + BaseURL + 网络，且不用麦克风）。
4. 点「保存」→ 刷新页面确认仍在，即可对着输入框旁的麦克风开说。

自定义服务商的凭据引用名为 ASR_VOICE_<显示名>_API_KEY（显示名参与派生，改名等于换一把 key）。 Your existing DSH LLM credential for the same provider is reused automatically — most users never type a key. “Test connection” verifies key + base URL + network in one click without the mic.

效果 Preview

安装 Install

dsh plugin --profile <profile> add <本插件路径或 GitHub 仓库>

浏览器端依赖官方 client 包（由 DSH 提供），无需额外安装。 The browser side relies on official DSH client packages — nothing extra to install.

设置项 Settings（namespace dsh-asr-voice）

API key 不在上表里。 它存于 DSH 凭据服务，按引用名读取：预置供应商直接用 <PRESET>_API_KEY（OPENAI_API_KEY / GROQ_API_KEY / SILICONFLOW_API_KEY / MIMO_API_KEY / DASHSCOPE_API_KEY）——与官方 LLM 凭据同名，因此配过该服务商 LLM 的人 零输入即可用；自定义供应商用 ASR_VOICE_<显示名>_API_KEY。解析顺序：过渡期 settings 里的 残留明文 → credentials.resolve(ref) → 环境变量 ref。

实时对话演示 Realtime demo

一句话闭环：开口 → 字幕逐字上屏 → 停顿即自动发起回合 → 回复按句朗读 → 念完麦克风自动回来听下一句。

怎么用好它（三步）：

1. 开口即出字，说话而不是打字：长按输入行的麦克风按钮（约 450ms）或按 realtime.hotkey， 说的时候字幕逐字上屏——不用等把话说完：停顿约一秒即判定「说完了」，草稿自动填入并发送。 你在对 agent 说话。
2. 回复朗读，随后自动还麦：回复按句朗读（浏览器语音，或云端 TTS），念完麦克风自动回来听 下一句。半双工保证扬声器里机器自己的声音不会被当成你说的话，回声不会触发奇怪的回合。
3. 三处打断，随时收放：再点一次麦克风按钮（对话中点击 = 打断/结束）/ 再按一次快捷键 / 点提示条上的 ×，立刻止读、取消在途回合、回到聆听。开启「语音插话」 （realtime.bargeIn，仅按句切段引擎）后更可以直接开口打断朗读——人声持续超过回声门才 生效，键盘和机器自己的声音不会误触。

引擎怎么选：browser 零配置零配额，但依赖浏览器语音服务（部分地区被网络屏蔽，遇 network 错误会自动降级到 segmented——提示「已自动改用云端识别」后照常说即可，不用手动切引擎）；segmented 每句走你已配好的云端 ASR，天然适配国内网络；cloud 上传 PCM 到 host 实时通道、服务端判回合， 出字延迟最低——已实现，需把 realtime.provider 选到 dashscope-realtime（真云端 qwen3-asr-flash-realtime，凭据复用 DASHSCOPE_API_KEY），保持默认 builtin 则走 host 端 假 provider（开发态，不花配额）。

实时语音对话 Realtime voice chat

realtime.enabled 打开后，麦克风按钮长按约 450ms 即进入语音对话（也可用快捷键 realtime.hotkey）；按钮不随开关增删，关掉开关只是长按与对话快捷键不再动作。一轮闭环：

说 → 字幕逐字上屏 → 静默 turn.settleMs（再宽限 turn.tailMs）判定说完 → 填入草稿并直接 发送 → agent 回复按句朗读 → 念完自动把麦克风还回来听下一句。

• 停顿即发起回合：实时模式恒等于「自动发送」，与 behavior.autoSend 无关——那一次点击 换成了每句的静默判定，草稿框里的内容会真的被提交执行。behavior.textMode 仍然生效： append 保留你已敲的文字，replace 覆盖草稿。
• 三种引擎，回合判据同源：browser 用浏览器 Web Speech 连续识别，逐字上屏，不新增任何本机 host 请求、不需要云商 key（识别由浏览器自己的语音服务完成，音频出机方式见下节披露，因此同样受 Firefox 无 Web Speech 的限制）。segmented 用本地能量 VAD 把连续麦克风切成句，每句走一次已有的 云端整段转写：要先配好 ASR 服务商，出字节奏是「说完 vad.silenceMs + 一个往返」而非逐字， 换来的是不依赖浏览器语音服务、且电平表由真实麦克风电平驱动。 browser/segmented 共用同一套 realtime.turn.* 静默判定，切换只改段边界的来源，不改 「什么时候算说完」。segmented 连续三次转写失败即判死并结束会话；转写慢过说话时丢最旧的段并 提示字幕断裂，而不是让字幕越拖越长。 cloud 走 host 实时通道：16k PCM 帧量化后逐帧上行，SSE 下行事件驱动字幕与回合， 回合边界由服务端 VAD 判定（realtime.provider = builtin 假 provider，或 dashscope-realtime 真云端 qwen3-asr-flash-realtime），本地不再文字静默判定——逐字延迟 更低，代价是需要一条 host 实时通道。
• 半双工（默认）与语音插话（可选）：默认朗读期间不收音，回声不会被当成你说的话—— 虚拟设备上实测 Chromium AEC 消除率仅 0.42 dB（echoCancellation 基本无效），因此真机 回环复测通过前不冒然默认全双工。打断三入口——再按一次按钮、再按一次快捷键、点提示条 ×——任一都立刻止住朗读、取消在途回合、回到聆听。开启 realtime.bargeIn 后（仅 engine=segmented）：播报期间继续收音，TTS 回声被能量门当背景学习，人声持续 350ms 且显著超过回声门才打断；键盘/关门等瞬态与 3dB 量级的弱声不会误断。
• 不做提示词优化：对话要的是即时，转写文本原样上屏；optimize.* 只作用于整段录音模式。
• 到点自己收：realtime.maxSessionMs 上限到即结束会话并释放麦克风，麦克风不会无人值守常开。
• 实时通道与真云端 provider 均已实现：host 会话注册表（sid 由 host 铸造）+ SSE 下行带 背压 + RealtimeProvider 接缝 + 假 provider（含 undici WebSocket 带 Authorization 的真实 socket 上线证据）；realtime.engine = cloud 时浏览器把采集帧上行到该通道、SSE 下行驱动字幕/ 回合；真云端 provider 也已落地（src/realtime-dashscope.ts，阿里云百炼 qwen3-asr-flash-realtime，服务端 VAD 判回合），把 realtime.provider 选到 dashscope-realtime 即启用，凭据复用 DSH 的 DASHSCOPE_API_KEY；云端 TTS 同理 （realtime.tts = cloud）。两者都在 Node 22+ 上运行（依赖全局 WebSocket）。

云端 ASR 预置 Presets

两条调用通道（设置项 asr.cloud.mode，默认 auto）：

• whisper 式 transcriptions：multipart 上传到 /audio/transcriptions（OpenAI / Groq / 硅基流动 / 本地部署）。
• chat + input_audio chat：base64 data URI 走 /chat/completions——小米 MiMo-V2.5-ASR、通义 Qwen-ASR 等音频大模型的 OpenAI 兼容姿势。
• auto：按模型名自动判定（模型名含 asr/audio/omni/sensevoice 走 chat，否则 whisper 式）。

自定义端点兼容任何 OpenAI-compatible 服务（按模型选对应通道）。 Any OpenAI-compatible endpoint works — pick the channel to match your model.

外部依赖 External Dependencies

• Node ≥ 22（host 半区）：云端实时转写与云端 TTS 依赖 Node 内置全局 WebSocket （undici，Node 22 起稳定）。Node 18/20 上这两条通道不可用——表现为路由 502 「云端通道不可用」，而不是可读的版本错误，因此 package.json 声明 engines.node >= 22， scripts/build.sh 也会先挑一个 ≥22 的 node。其余功能（整段识别 / 优化 / browser、 segmented 实时引擎）不受影响。
• 浏览器：Web Speech API（Chrome/Edge；Safari 部分支持）、getUserMedia + MediaRecorder； realtime.engine = segmented 另需 AudioWorklet（16k PCM 采集，Chrome/Edge/Safari 交集内）
• 云端 ASR / LLM：你配置的 OpenAI-compatible 服务（网络请求由本机 host 发起）
• 运行时不依赖任何第三方 DSH 插件（与 dsh-ui-tweaks 等完全独立，可单独用、可组合用）

生命周期脚本 Lifecycle Scripts

无 preinstall / install / postinstall / prepare 等安装期脚本； build / build:client / bundle / typecheck / pretest / test 仅开发者构建与验证用， 不参与安装（pretest 是 npm 的测试前置钩子，只在本地 npm test 时触发，不是安装脚本）。

权限与已知风险 Permissions & Known Issues（保守披露）

已知风险：

• 若见「未检测到声音」之语，请将浏览器地址栏站点设置中的输入设备选为「内置麦克风」—— 远程控制/直播软件安装的虚拟音频设备常被误选，徒留静音寂寂；插件静音守卫会拦截此类录音并明言相告， 不向云端虚报。 If you see "no sound detected", pick the built-in microphone as the input device in the browser's site settings — virtual audio devices are often selected by mistake and record silence. The silence guard blocks such recordings and tells you plainly instead of wasting a cloud call.
• 浏览器 Web Speech 在 Firefox 不可用（提示改用云端）；识别质量取决于浏览器/服务商。 Web Speech is unavailable on Firefox (it will prompt you to use cloud ASR); recognition quality varies by browser and provider.
• 云端转写会把你的语音上传到所配置的服务商，请确认其隐私政策。 Audio is uploaded to your configured provider for transcription — review their privacy policy.
• 实时对话会在你没有再点击的情况下发起回合。 每句的静默判定就是提交点，草稿里的内容 直接进 agent；若该会话配了工具或审批，你说出的每一句都可能真的触发执行。共享终端上、 或开着高权限工具时，不要把 realtime.enabled 打开。 Realtime chat starts agent turns without another click — the pause is the send. Keep it off on shared machines or when high-privilege tools are armed.
• engine=browser（默认）：实时对话期间麦克风持续流经浏览器自己的在线语音识别服务 （Chrome / Edge / Safari 各自的后端，非本插件的服务器），比整段模式的占用时长长得多。 本插件不经手、不落盘这段音频。 While a browser-engine session is open, audio streams continuously to the browser's own speech service — not to this plugin's servers, which neither handle nor store it.
• engine=segmented：每说完一句，该句音频就作为一次独立转写请求上传到你配置的云端 ASR （与整段模式同一服务商、同一凭据），并按句消耗其配额；一次对话 = N 次请求，而不是 1 次。 VAD 只认响度，安静环境里的呼吸、键盘声若超过 vad.rms 也会照发一次（调高它即可，趋零的段 由静音守卫当场拦下、不上游）。 With the segmented engine, every utterance becomes one upload to your configured cloud ASR and consumes quota per sentence; raise vad.rms if breaths or keystrokes are being billed.
• 语音插话需真机复测：浏览器回声消除在假设备管路线上实测不生效（消除率 0.42 dB）， 因此 realtime.bargeIn 默认关。打开后打断走软件回声门（纯能量，不依赖 AEC）；真机 （真实扬声器 + 麦克风回环）复测脚本就位后在真实声学下确认误断率，再考虑翻转默认。 Barge-in is off by default: Chromium's AEC measured 0.42 dB on virtual devices, so acoustic interruption uses a software echo gate. Turn it on to try; a real-device retest will decide whether the default flips.
• 播报音色与断句取决于操作系统装了什么语音，长句可能出现机械停顿；不接受就 realtime.tts = off， 字幕与自动提交照常。云端实时（PCM 流 + 服务端轮次判定）已由 engine=cloud 接入：host 实时 通道（会话注册表 + SSE 下行 + RealtimeProvider 接缝 + 假 provider）+ client 侧 cloud 引擎 （采集帧上行 + SSE 下行驱动字幕/回合）均已实现；真云端 provider 也已实现 （src/realtime-dashscope.ts，阿里云百炼 qwen3-asr-flash-realtime），把 realtime.provider 选到 dashscope-realtime 即走真云端，凭据复用 DASHSCOPE_API_KEY（需 Node 22+）。 Voice quality depends on installed system voices; set realtime.tts = off for captions only. The host realtime channel (session registry + SSE downlink + RealtimeProvider seam + fake provider) and the browser half's engine=cloud consumer are both implemented, and so is the real cloud provider (src/realtime-dashscope.ts, Alibaba Bailian qwen3-asr-flash-realtime): point realtime.provider at dashscope-realtime to use it (credential DASHSCOPE_API_KEY, Node 22+).
• API key 存于 DSH 凭据服务（落盘位置与格式由 host 的凭据策略决定），仅本机回环可访问代理路由 （信任围栏防 CSRF：同源判定含端口，本机其它端口上的页面借不了道）。 Keys live in the DSH credential store (where and how they are persisted is the host's policy); proxy routes are loopback-only (trusted-origin fence against CSRF; the same-origin check includes the port, so pages on other local ports cannot borrow it).
• 升级自 v0.1/v0.2 的注意：旧版本的 apiKey 是写在 settings 里的明文字段，且曾随 settings.describe 过线到浏览器。本版本首次加载会自动把这些明文迁进凭据并抹掉 settings 里的值； 若你想立刻处理，可自己删 ~/.dsh/settings.yaml 中的 apiKey 字段。迁移前已经过线的那把 key 建议轮换一次（如果你在意的话）。若 credentials.set 被拒（例如该引用名被只读来源遮蔽），迁移会 整批放弃并保留 settings 原值——识别照旧可用，只是 host 日志里会有一条 warn，而卡片第 ③ 步会显示 该引用名「尚未配置」；自己按提示填一次即可。 Upgrading from v0.1/v0.2: apiKey used to be plaintext in the settings document and did cross the settings wire to the browser. On first load this version moves those keys into credentials and clears the settings copy; delete apiKey from ~/.dsh/settings.yaml by hand if you want it gone now, and consider rotating a key you care about. If the credential write is refused, the migration aborts and leaves the plaintext in place — transcription keeps working, the host logs one warning, and the card shows that ref as “no key yet”.
• 动效为自研 GSAP 风格轻量动画模块（离线构建环境无 gsap 包可装），API 对齐 GSAP （to/fromTo/timeline），后续可一行替换为真 GSAP——不影响组件调用点。

开发 Development

• 构建：bash scripts/build.sh（自动选用 Node ≥22；依赖树经 junction 链接到已装兄弟插件 或 DSH_CHECKOUT，仅为构建期便利，与运行时无关）。脚本会先 type-check client 半区 （tsc -p tsconfig.client.json --noEmit）再跑 tsdown——tsdown 不做类型检查，漏掉这一步 就会把带类型错误的 lib/client.js 提交出去；npm run build 同款。
• 类型检查：npm run typecheck（host + client 两个半区；npm test 前会自动先编译 host， 避免测试跑在过期的 lib/ 上）
• lib/ 入库且是发布内容：改了 src/ 必须重跑构建并把 lib/ 一起提交；发布工作流 （.github/workflows/publish.yml）会在 npm publish 前重跑构建并用 git diff --exit-code -- lib 校验产物与源码一致，不一致即中止发布。
• 契约：本仓库 AGENTS.md 指向伞仓库 dsh-plugins/AGENTS.md（单一来源）

License

MIT