蓝牙耳机语音键

把蓝牙耳机可被 Windows 看到的按键变成桌面级 语音输入 和 回删 快捷键，用于浏览器、聊天窗口、AI 客户端和 AI Agent 程序，替代手工键盘输入。

• 左侧耳机三击（发送音量减）→ 发送 Win+H，启动 Windows 语音输入，把话输入到当前获得焦点的输入框。
• 右侧耳机三击（发送音量加）→ 发送 Backspace，删除光标前的字符。
• 长按的“嘟”声不能作为触发条件：它只是耳机内部提示音，不会作为按键发送给 Windows。
• 可在 DSH 设置页 蓝牙耳机语音键 中手动选择左右耳按键、测试、调整每次回删的字符数，并查看最近一次耳机按键。

为什么适合 AI / Agent

对着 AI 说话比敲一大段提示词快得多，尤其是这些场景：

场景	怎么说
让 Agent 改代码	“把登录页的报错提示改成中文，并补一个单元测试”
让 AI 总结 / 翻译	“把这段英文邮件总结成三点，再用中文回复”
让 Agent 查资料	“查一下这个库最新版本，比较它和现在用的版本有什么破坏性变更”
长任务追加约束	“先不要改数据库，只改接口层，做完告诉我改了哪些文件”
聊天 / 客服 / 写作	直接口述，右耳回删修正，不用离开输入框

它工作在系统键盘层，不绑定某一个 AI：焦点在哪个输入框，语音文字就进入哪里。 所以 DeepSeek Harness、ChatGPT / Claude 桌面端、浏览器里的 AI 网页、Cursor / VS Code、聊天窗口都能用。配合 DSH Agent 时，语音就是 Agent 的“任务输入口”：说完，Agent 执行；说错，右耳删掉重说。

安装

插件市场收录后，搜索 Bluetooth earbud keys / 蓝牙耳机语音键 安装。

手动安装（GitHub 仓库为 glowwan/dsh-bluetooth-earbuds）：

dsh plugin --profile desktop add github:glowwan/dsh-bluetooth-earbuds

要求 Windows 10/11 和 DSH 桌面版；首次启动会用 Windows 自带的 csc.exe 编译助手，不需要安装 .NET SDK。插件不录音、不联网、不上传音频；语音识别由 Windows 完成。

English: README.en.md

测试耳机的行为（示例）

本项目实测的一副 TWS 耳机：

• 左侧三击 → Windows 收到“音量减”，弹出音量条。
• 右侧三击 → Windows 收到“音量加”，弹出音量条。
• 长按 → 耳机内“嘟”一声，但 Windows 收不到任何按键；因此软件无法把长按当作快捷键。
• 单次轻触很可能两侧都发送“播放/暂停”，Windows 无法区分左右耳。

插件因此把左侧音量减映射为语音、右侧音量加映射为回删。触发时 Windows 音量条可能短暂出现，插件随后会把音量还原，不会让音量越按越小/越大。

注意：键盘上的音量加/减键也会被当作同样的手势。如果不想让键盘音量键触发语音/回删，请在设置页关闭“启用快捷键”。

插件依赖 DSH 运行：关闭 DSH 后后台按键助手会停止，耳机快捷键也随之失效。

重要限制：Windows 只能看到按键，不知道是左耳还是右耳

蓝牙耳机通过 AVRCP/HID 向电脑发送“播放/暂停”“音量加/减”等命令，不会告诉 Windows 是左耳还是右耳在触摸。因此：

• 只有两侧发送不同的键时，插件才能区分左右耳。
• 如果两侧发送同一个键（例如都发送播放/暂停），任何软件都无法区分。
• 部分耳机把触摸用于唤醒手机助手，或只通过蓝牙 HFP 发送私有事件；这类操作不会进入 Windows，插件也收不到。

设置页会在两侧选到同一个键时拒绝保存并提示。

首次使用

1. 安装插件后打开 设置 → 蓝牙耳机语音键，确认状态为“监听中”。
2. 让 Win+H 可以转写：
   • 在任意输入框按一次 Win+H，对麦克风说一句话。
   • 如果只弹出语音条但没有文字，打开 Windows 设置 → 隐私和安全性 → 语音，开启 在线语音识别。本机实测开启后 Win+H 才能正常转写。
   • 确认默认麦克风没有被静音；耳机麦克风（Hands-Free）或 Realtek 麦克风都可以。
3. 在左右耳卡片中手动选择：
   • 左耳：音量减键
   • 右耳：音量加键 也可以点“学习按键”，然后按对应手势（学习需要真的触发一次音量/媒体键）。
4. 点 测试。左耳测试会在 2.5 秒后发送 Win+H，请先点进要输入文字的文本框；右耳测试会发送一次 Backspace。

映射保存在：

%USERPROFILE%\.dsh\plugin-data\bluetooth-earbuds.json

卸载插件不会自动删除该文件；需要恢复默认映射时可在设置页重新选择，或删除这个文件后重启 DSH。

行为选项

• 启用快捷键：关闭后音量/媒体键恢复正常，不必卸载插件。
• 拦截原始媒体键：对普通媒体键生效；音量键手势由音量变化检测触发，系统音量条仍可能短暂出现。
• 每次回删字符数：右耳每触发一次发送的 Backspace 次数，可选 1–10。

工作原理

• Host 半启动 helper/EarbudHelper.exe。该程序由 helper/EarbudHelper.cs 用 Windows 自带的 C# 编译器编译，不需要安装 .NET SDK。
• 助手同时使用多条检测路径：
  • 低级键盘钩子、Raw Input、GetAsyncKeyState 轮询，用于普通媒体键；
  • Core Audio 音量变化检测，用于这副耳机只发送音量增减的情况。检测到一次手势后等音量稳定，再执行动作并把音量还原。
• 左耳触发 SendInput 注入 Win+H，右耳注入 Backspace。
• 插件不录音、不联网、不上传音频。语音识别由 Windows 语音输入完成；开启“在线语音识别”后，语音会按 Microsoft 的隐私政策发送到 Microsoft。

排错

现象	处理
状态显示“未运行”	点“重新启动助手”。若仍失败，查看设置页显示的错误。
三击没有反应	确认左右耳分别选的是“音量减键”/“音量加键”，并且状态为“监听中”。音量已经在最大/最小时可能无法检测。
Win+H 只弹窗、不出字	打开 设置 → 隐私和安全性 → 语音 → 在线语音识别；检查默认麦克风没有被静音。
左耳触发了语音，但没有文字	先在记事本手动按 Win+H 确认能转写，再试耳机。
右耳没有回删	先把光标点进一个有文字的文本框；Backspace 只删除光标前的内容。
长按没有反应	长按只产生耳机内部提示音，不发送按键，无法被软件检测。
音量条每次都会闪	这是 Windows 对音量键的系统提示；插件会还原音量，但无法完全隐藏系统音量条。
对某些程序无效	Windows 不允许普通权限程序向管理员权限窗口注入按键；以相同权限运行目标程序，或不要以管理员身份运行目标程序。

文件

• index.js — Host：助手生命周期、状态文件、设置页 API、Agent 工具。
• client.js — DSH 设置页。
• helper/EarbudHelper.cs — Windows 助手源码。
• helper/EarbudHelper.exe — 已编译助手；源码更新时 Host 会自动重编译。
• cordis.patch.yml — Bundle 的插件行。