dsh-voice-wake（语音唤醒）

给 DSH 用的本地语音唤醒插件：叫醒 → 请讲。先说唤醒词，听到「叮-咚」后说内容，停一下就自动发送到会话。

给 agent 的速览

• 解决什么：手被占用、不想打字、或不方便操作电脑时，用语音把指令发进 DSH 会话。
• 怎么用：单独说唤醒词（默认「鲸鱼」，不要带内容）→ 听到提示音 → 说指令 → 停顿后自动发送。
• 前置：DSH 提供 speechToText（本机 SenseVoice），并允许麦克风；音频只在本机识别、不落盘。
• 包名/安装：dsh-voice-wake / npm i dsh-voice-wake
• 配置：wakeWords / wakeSensitivity / silenceMs / followActive
• 扩展：beforeSend / onTranscript / onStateChange / hud.js
• 详细：ARCHITECTURE.md

这是什么

• 本地识别：复用 DSH 自带的 SenseVoice，音频不落盘、不出本机、不消耗 token；
• 两句提示音：唤醒确认「叮-咚」，发送完成「嗒」，不看屏幕也知道进行到哪；
• HUD 卡片：右下角显示「聆听中 / 已唤醒」和音量，可拖动、可折叠、可关闭；
• 一个入口：所有设置都在「设置 → 语音唤醒」，改完立即生效。

装之前

• DSH 里已经能正常用语音输入（设置 → 语音输入，确认识别模型就绪）；
• 没装官方语音输入插件也能装上，但设置页会提示「识别还不能用」，并告诉你缺什么；
• 首次启动后等约 5 秒，模型加载完再试唤醒。

安装

• 在 DSH 市场的「插件」里搜索 语音唤醒 安装；
• 或让包管理器安装：npm install dsh-voice-wake（版本 1.0.x）。

怎么用

1. 打开「设置 → 语音唤醒」，启用；
2. 只喊唤醒词（默认「鲸鱼」，建议 2–3 个字），不要接内容；
3. 听到「叮-咚」、HUD 变「已唤醒」后，5 秒内说你要做的事；
4. 说完停一下，自动发送，并响一声「嗒」。

「鲸鱼，今天几号」这种唤醒词+内容连说不会触发——这是故意的，用来减少误唤醒。

权限与隐私

• 会听麦克风：只在插件启用时；识别在本机完成，音频不落盘、不上传；
• 会往会话发消息：效果等于你手动打字，不会执行额外操作；
• 会读配置：config.json 与浏览器 localStorage（HUD 位置 / 折叠状态）；
• 不会：不联网、不读其它文件、不操作电脑。

特性

• 唤醒词宽容匹配：同音字、前后鼻音（jing/jin）、平翘舌（zh/z）、1 个音节偏差都能命中； 默认还会把「鲸鱼」的同音「金鱼」当成别名；
• 灵敏度 1–10 档，带「校准」按环境底噪自动选档；
• 单句最长 1 / 2 / 5 分钟或「不限」；
• 设置页单页平铺，改完立即生效，没有「保存」按钮；
• HUD 是独立文件 hud.js（纯展示组件），可以整体搬进独立置顶窗口；
• 发送到「当前会话」或固定「语音唤醒会话」，可切换。

设置页

一页到底、没有折叠菜单、没有「保存」按钮。

区	内容
基本	启用语音唤醒、麦克风、唤醒词、灵敏度、说完后静音、单句最长、提示音音量、显示 HUD 卡片（含「归位」）
更多设置	要求唤醒词在段首、快速唤醒探测、发到当前会话
调试	麦克风测试（音量条 + 测试识别）、诊断信息（复制 / 导出 / 链路自检）

改完立即生效；只有失败时顶部才会出现错误条。

工作方式：叫醒 → 请讲

1. 只喊唤醒词（默认「鲸鱼」）——必须独占一句，前后不要带内容；
2. 句首的快速探测会先把这一段按 0.6 秒静音切出来，完整识别确认“只有唤醒词”后， 响「叮-咚」并把 HUD 切到「已唤醒」；
3. 听到「叮-咚」后 5 秒内说你要做的事；一旦检测到有效说话，5 秒倒计时就取消， 改成“说完静音就发送”；
4. 发送完成响一声「嗒」，回到「聆听中」；
5. 5 秒内没说话（或只有杂音、识别为空）→ 视为误触发，自动收回「聆听中」；
6. 唤醒词后面直接带内容（例如「鲸鱼，今天几号」）不算唤醒，不响也不发；
7. 连续说话按「单句最长」（maxSegmentMs）切段：默认 1 分钟，可选 2 / 5 分钟或「不限」。

打断：上一轮还在干活时，再次喊唤醒词、等「叮」、再说新指令，新消息会打断上一轮； 部署不支持打断时自动退回排队，保证消息不丢。

发到哪个会话：

• 关闭（默认）：语音消息固定发到「语音唤醒会话」，首次创建/使用时主窗口会自动跳过去；
• 开启：跟着你当前打开的会话走；如果当前不在聊天页（工作区 / 插件 / 自动化任务等）， 拿不到当前会话，会自动落回「语音唤醒会话」。

声音反馈

听到什么	含义
叮-咚（988→1319 Hz，轻）	完整识别确认「这句只有唤醒词」后响，表示可以开始说正文了
嗒（660 Hz，低、短）	正文识别完并成功发进会话
没有声音	没叫醒 / 不是干净唤醒 / 片段太短 / 纯噪声——没有回应本身就是信号

快速探测命中时，从说完唤醒词到「叮」约 1–1.5 秒；探测没命中时会慢一些（要等普通 2 秒静音）。

防误触

• 唤醒词必须独占一句：识别文本去掉标点后必须完全等于唤醒词，多一个字都不算；
• wakeAtStart：默认开，唤醒词必须在识别文本开头，前面最多 1 个语气词；
• 唤醒侧宽松、正文侧严格：唤醒词做同音/平翘舌容错；确认后的正文原样发送，不做改写。

常见问题

• 没有「叮」：先确认设置页显示「识别还不能用」；没有就检查麦克风权限和唤醒词是否说完整；
• 第一次特别慢：启动后模型要加载约 5 秒，等一会儿再试；
• 消息跑到「语音唤醒会话」：这是默认行为；想跟着当前会话走，打开「发到当前会话」；
• HUD 找不到：设置页点「归位」，会回到右下角并置顶；
• 怎么换提示音：见 ARCHITECTURE.md 的「扩展配方」。

配置项

字段全部在 lib/config.js 的 CONFIG_SCHEMA 里定义；默认值、迁移、范围校验都由这张表生成。

字段	类型	默认值	取值范围	影响
enabled	布尔	false	true / false	总开关。关掉就不常听麦克风
deviceId	字符串	''（系统默认）	浏览器给的设备 id	用哪支麦克风；设备失效自动退回默认
wakeWords	字符串	鲸鱼	英文逗号分隔多个说法	唤醒词
wakeAtStart	布尔	true	true / false	是否要求唤醒词在段首（前面最多 1 个语气词）
language	枚举	zh	auto zh en yue ja ko	传给识别引擎的语言提示
wakeSensitivity	整数	5	1–10	唤醒灵敏度档位：1 最灵敏，10 最保守
silenceMs	数字	2000	400–8000（取整）	说完后静音多久算一句（毫秒）
maxSegmentMs	数字	60000	0–3600000（取整）	单句最长；0 表示不限
chimeVolume	整数	32	0–100	提示音音量；0 为静音
probeEnabled	布尔	true	true / false	快速唤醒探测（更快，但吃 CPU）
followActive	布尔	false	true / false	发到当前会话；关闭时固定发到「语音唤醒会话」
hudEnabled	布尔	true	true / false	是否显示 HUD 卡片
hudPosition	坐标/空	null	null 或 {x,y}	HUD 初值坐标
hudCollapsed	布尔	false	true / false	HUD 初值：是否折叠成小圆点
hudOpacity	数字	1	0.2–1	HUD 不透明度
hudZIndex	整数	2147483000	0–2147483647	HUD 层叠高度
sessionId	字符串	''	由插件写入	专用语音会话 id
sessionPreset	字符串	standard	任意 agent preset id	语音会话用哪个 preset

配置版本 16。旧配置会自动迁移；已删除的 vadThreshold 等旧字段会被丢弃。

更多文档

• ARCHITECTURE.md：数据流、文件职责、扩展配方（改 HUD / 换识别器 / 换提示音 / 独立窗口）；
• CHANGELOG.md：版本变更；
• LICENSE：MIT；
• GitHub 仓库：源码与 issue。