- Home
- Plugin
- Visione, voce e multimodale
- dsh-pet-extend
dsh-pet-extend
wang-yudong/dsh-pet-extend
Adds offline Chinese wake-word detection with speaker verification to dsh-pet, plus right-click chat access and wake reactions. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.
Installazione
dsh plugin --profile web add github:wang-yudong/dsh-pet-extendREADME
dsh-pet-extend
dsh-pet 的扩展插件。
这不是一个「语音唤醒插件」——语音唤醒只是当前已落地的第一个能力模块。这个仓库的定位是给 dsh-pet 持续加能力的扩展层:右键菜单、对话联动、唤醒反馈,以及后续还会继续扩展的其他能力,都以模块形式加在这里。所有功能都以插件方式挂在 dsh-pet 上,不改 dsh-pet 源码,也不改 DSH 内核。
本项目扩展的是 PC2005-cloud/dsh-pet。
能力模块
| 模块 | 状态 | 说明 |
|---|---|---|
| 语音唤醒 | 已实现 | 完全离线的中文唤醒词 + 声纹校验,默认「大肥鱼」,可自定义 |
| 右键菜单 | 已实现 | 桌宠右键「更多」直接打开对话,不弹独立窗口 |
| 唤醒联动 | 已实现 | 唤醒后打开 pet-chat + 桌宠动画 + 气泡 + 朗读(音色跟随 dsh-pet) |
| 语音任务 | 已实现 | 唤醒后接着说一句命令,用 DSH 官方 SenseVoice 转成文字,写进 DSH 会话(草稿或直接发送) |
| 后续扩展 | 规划中 | 新的交互与自动化能力会继续加到这个扩展里,不限于语音 |
语音唤醒模块的能力
| 能力 | 说明 |
|---|---|
| 离线语音唤醒 | 默认唤醒词「大肥鱼」,可自定义任意中文词 |
| 声纹二次校验 | 最多 3 条声纹模板,逐条比对取最高分,别人喊不醒 |
| 并行多档灵敏度 | 同一句词同时用 3~4 档关键词加成解码,覆盖不同语速/节奏/音量 |
| 声纹逐条回放 | 每次录入单独存一份原始录音,可逐条播放对比 |
| 按住录音测试 | 走与正式监听完全相同的解码 + 声纹链路,但不真的打开对话 |
| 唤醒反应 | 打开对话 + 桌宠联动动画 + 气泡 + 朗读(音色跟随 dsh-pet 设置) |
| 诊断面板 | 检测/触发/拒绝/解码/未命中、音频峰值、有效语音占比、并行档位、最近跳过原因 |
| 不做的事 | 不自动调节麦克风音量、不做 AGC、不缩放音频幅度、不上传音频 |
识别与声纹推理全部在本机跑(sherpa-onnx),不上传任何音频。
- 唤醒引擎:sherpa-onnx 中文 KWS(
sherpa-onnx-kws-zipformer-wenetspeech-3.3M) - 声纹模型:3D-Speaker CAM++(
campplus_sv_zh-cn_16k-common) - 宿主:dsh-pet + DSH
环境要求
- 已安装 DSH,并且 dsh-pet 桌宠可正常使用
- Node.js >= 22.12.0
- 语音任务需要 DSH 里启用官方语音输入插件
(
@deepseek-ai/dsh-experimental-voice-input-bundle,含 SenseVoice 模型);只用唤醒不需要 - 可用的麦克风
- Windows / macOS / Linux(依赖
sherpa-onnx-node的预编译包)
安装
1. 作为 DSH 插件安装
方式 A:从 npm 安装(推荐,发布后即可)
# <profile> 换成你的 DSH profile 名;desktop 是桌面端 DSH 的默认 profile
dsh plugin --profile desktop add dsh-pet-extend
无需克隆仓库、无需手动装依赖与模型——dsh-pet-extend 发布到 npm 后,DSH 直接从 registry 拉取,
包内已附带模型,可选依赖由 DSH 自动安装。在此之前(未发布时)请用方式 B。
方式 B:从本地源码安装(开发 / 改代码用)
# <profile> 换成你的 DSH profile 名;路径用本目录的绝对路径
dsh plugin --profile <profile> add file:/absolute/path/to/dsh-pet-extend
Windows 示例:
dsh plugin --profile default add file:E:\path\to\dsh-pet-extend
2. 安装依赖
cd dsh-pet-extend
npm install
# 若 DSH 没有自动装可选依赖,再执行一次:
npm run install:deps
package.json 里 sherpa-onnx-node 与 pinyin-pro 是 optionalDependencies:
前者负责 KWS 与声纹推理,后者提供全量汉字拼音(缺失时退回内置常用字表)。
3. 模型
仓库内的 models/ 已附带模型(约 32 MB):
models/kws/ encoder / decoder / joiner (.int8.onnx) + tokens.txt
models/speaker/ 3dspeaker_speech_campplus_sv_zh-cn_16k-common.onnx
若缺失或损坏:
npm run install:models # 补装
npm run install:models -- --force # 强制重下
4. 重启 DSH
插件代码在 DSH 启动时加载,改完代码或首次安装都必须重启 DSH(dsh web 就重启 dsh web)。设置页上的「重新初始化引擎」只会重建 native 语音引擎,不会重载插件 JS。
首次使用
- 打开设置页:DSH 设置 → 桌宠扩展设置,或直接访问
http://127.0.0.1:<DSH端口>/dsh-pet-extend/settings - 点「申请麦克风权限」,允许授权
- 点「开始录入(3 秒)」,等提示「麦克风已就绪」后连续清晰地念 3 秒唤醒词;建议录 2~3 次
- 在「唤醒词」里填写(默认「大肥鱼」),点保存
- 打开「语音唤醒」开关
- 正常喊唤醒词即可
未录入声纹时开关不可用。数据保存在
~/.dsh/dsh-pet-extend/。
语音任务(唤醒后直接说命令)
开启后交互变成「小爱」模式:
喊「大肥鱼」
→ 唤醒反应:桌宠动画 + 气泡「我在」+ 朗读(和以前完全一样)
→ 语音播放一结束,气泡立刻换成「我在听」并开始录音(不预录,不在命令里混入之前的尾音)
→ 说一句命令,例如「把 README 里的标题改一下」
· 一直没开口:2 秒后静默放弃,等下一次唤醒(不朗读、不留提示)
· 说完后连续静音 2 秒:判定说完,立刻截断去识别
→ SenseVoice 转成文字,剥掉开头录进去的「我在」和唤醒词尾巴(「大肥鱼」/「肥鱼」)
· 写到当前会话(默认)+ 先填草稿:插到当前输入框光标处,你按回车才开始跑
· 写到新会话 + 先填草稿:新建会话并填好草稿
· 直接发送:整条替换 / 新建后立即发出去,agent 马上开跑
流程就是最朴素的「唤醒词 → 念完「我在」→ 我在听 + 录音」,不做任何预录——命令只在反应播放 完毕后才开始录,所以唤醒词之前说的「あれ?」之类不会带进命令。
为什么不是「点击官方语音输入插件」:那个插件只是一个挂在输入框旁的 React 组件,
没有对外服务、没有快捷键,外部无法触发它。本扩展直接调用它背后的同一个宿主服务
ctx.speechToText(SenseVoice 本机推理),所以识别结果、模型、语言都与官方一致,
但流程由我们自己控制。
几个刻意的取舍:
- 复用唤醒那条已经开着的麦克风流。命令录音不需要再
getUserMedia一次, 既不会和「语音输入」按钮抢设备(Windows 上两路同时打开多半报Could not start audio source),也不会多一次权限弹窗。 - 流程就是「唤醒词 → 念完「我在」→ 我在听 + 录音」:反应(
dsh-pet的 Edge TTS)播完, 气泡立刻切「我在听」并开始收音。合成音频尾部常带几百毫秒~1 秒静音,直接等<audio>.onended气泡会多停 1 秒——所以客户端decodeAudioData算出「语音真正结束」的时刻,到那一刻就切气泡, 尾静音仍由<audio>在后台静默放完(不截断、不丢字)。代价是朗读会被麦克风录进去,收官用stripReactionText()/stripWakeWordPrefix()剥掉开头那句回应与唤醒词尾巴。 - 不预录:录音从「我在」播放完毕那一刻才开始,所以唤醒词之前说的尾音(「あれ?」之类) 不会混进命令。预录环仅用来给端点检测器喂最近几块的 RMS 做底噪估计(不进命令音频), 让底噪阈值秒级收敛。
- 停嘴判定是「相对峰值」而非「绝对安静」:端点检测记录本次说话的峰值,只要能量掉到峰值的 65% 以下就累计静音——嘈杂环境里底噪不低、噪声偶尔起伏也不会把静音计数清零,不要求房间安静, 只要用户停嘴即可;起音判定仍用相对底噪的阈值,避免把底噪当语音。
- 不复述识别结果、不需要说「开始」。结果只用气泡显示,避免二次确认的噪声。
- 不做任何增益:端点检测用的是和 KWS 完全相同的原始 PCM 与电平口径。
前置条件:DSH 里启用了官方语音输入插件(@deepseek-ai/dsh-experimental-voice-input-bundle,
默认 provider sensevoice-local)。没启用时本功能自动降级——只打开桌宠对话,并在设置页
「语音任务」卡片里写明原因。
设置项
| 项目 | 默认 | 说明 |
|---|---|---|
| 唤醒词 | 大肥鱼 | 中文即可,多个词用逗号/换行分隔;会转成模型需要的拼音 token |
唤醒加成 keywordsScore | 3.0 | 数值越高越灵敏,但过高会让流式解码过早重建,反而漏检 |
触发阈值 keywordsThreshold | 0.15 | 越低越容易触发 |
声纹阈值 speakerThreshold | 0.5 | 越高越严格;0.3 明显更松,误触也会变多 |
唤醒冷却 cooldownMs | 1500 | 两次唤醒的最小间隔,低于它会被「冷却」挡掉 |
| 语音唤醒 | 关闭 | 总开关;关闭后会真正释放麦克风 |
| 语音任务 | 关闭 | 唤醒后继续听一句命令;开启后不再打开桌宠对话 |
| 命令写到 | 当前会话 | current 写进当前会话的草稿/直接提交;new 新建会话 |
| 识别完成后 | 先填草稿 | draft 只填草稿等回车;auto 直接发送并跳转到该会话 |
说完判定 silenceMs | 2000 | 说过的最后一句之后连续静音多久算说完 |
没开口放弃 noSpeechMs | 2000 | 开始听之后多久没开口就静默放弃 |
安全上限 maxMs | 60000 | 单条命令的最长收音时间 |
| 识别语言 | auto | SenseVoice 支持 auto / zh / en / yue / ja / ko |
| 黑名单 | 删除,重置,… | auto 模式下命中即降级成草稿,必须人工确认 |
并行档位:引擎实际会同时跑 1.5 / 2 / 2.5 三档(把加成设成 3 时再加一档 3),
同一块音频喂给所有档位,任一档吐词就触发。原因是三字词的最优加成会随语速漂移——
单档参数一定会在某些语速下漏检。
诊断与排错
设置页「诊断」会显示:
引擎 ready · 并行档位 1.5 / 2 / 2.5
检测 12 / 触发 11 / 拒绝 1
解码 3109 段 · 未命中 3096 段 · 最近跳过 冷却中
音频 3113 段 · 峰值 0.088/1.000 · 有效语音 99%
| 现象 | 含义 | 处理 |
|---|---|---|
解码 不涨 | 引擎没在跑 | 看引擎状态与「重新初始化引擎」 |
解码 在涨但 检测 0 | 引擎没识别出唤醒词 | 换成四字/叠词、放慢、加大音量;或看「按住录音测试」的归因 |
检测 在涨但 触发 0 | 识别到了但没通过 | 看「最近跳过」:冷却中 / 声纹未通过 / 分数低于阈值 |
| 有效语音占比很低 | 采集端把声音吃掉了 | 检查系统「音频增强/降噪」;靠近麦克风 |
| 峰值接近 1.000 | 电平过高已削波 | 调低系统麦克风音量 |
Could not start audio source | NotReadableError:麦克风启动不了 | 多为设备被占用:先关掉「语音唤醒」开关、等 5 秒再申请;再查 Windows 隐私里的「允许桌面应用访问麦克风」 |
「按住录音测试」会在没检出时给出归因:
- 放大后能检出 → 电平问题,提示调高系统麦克风音量
- 放大也检不出 → 发音/语速与词表不匹配
- 换个加成能检出 → 直接告诉你「把加成改成 X 再试」
还可以点「回放刚才的录音」听引擎实际收到的声音,点「回放最近监听」对比正式监听收到的声音。
工作原理
麦克风 ──getUserMedia(关闭降噪/回声消除/AGC)──► AudioContext
└─ 127 抽头 Blackman 窗 FIR 抗混叠低通 ──► 16 kHz Int16 PCM
└─ 每 100 ms 一块 ──► POST /api/kws/audio(串行队列,带超时与合并)
└─ KeywordSpotter × 3~4 档(并行)──► 命中
└─ 按唤醒词对齐截取 ──► 声纹余弦相似度 ──► 触发
几个关键取舍:
- 不做任何自动增益。
getUserMedia各档都显式autoGainControl: false,编码只做 Float32→Int16 的数值限幅,KWS 与声纹、录入与监听四条路径电平完全一致。 - 首选
{ exact: false }强制关闭降噪与回声消除。WebRTC 里这三项默认就是true, 写false只是 ideal,设备可以忽略;Windows 驱动一旦开启会把持续人声压到底噪。 - 命中后重建流而不是
reset。实测reset连续 8 轮只中 5/8,每次createStream是 8/8。 - 流在第一次收到音频时才创建。sherpa-onnx 的 KeywordStream 需要「创建后立刻
acceptWaveform」,先建流再等音频会让isReady恒为 false。 - AudioWorklet 内部攒到 4096 帧再发给主线程。每 128 帧发一次(约 375 次/秒)会把主线程淹没。
常见问题
为什么一定要录声纹? 插件是「唤醒词 + 声纹」双重校验,避免别人或电视里的一句话把桌宠叫出来。未录入声纹时开关不可用。
换唤醒词后不灵敏? 模型自带词表全是 4 字/叠词,2~3 字短词对语速和发音很敏感。可以:
- 把「唤醒加成」在 1.5~3 之间微调(或看按住测试给出的建议值);
- 换成四字词(如模型自带的「小爱同学」);
- 放慢、字间稍分开,说完停 0.2~0.3 秒再松手。
多条声纹有什么好处? 最多保留 3 条模板,比对时取最高分。3 次录入的音色/音量差异很大,只比均值会把分数稀释 (实测同一段录音均值 0.292、逐条最高 0.622)。
模型 32 MB 会一直占内存吗? KWS 是 3.3M 的小模型,常驻内存很小;声纹模型只在录入/校验时用。并行多档实测每 100 ms 音频约 6 ms CPU。
朗读用的是什么音色?插件自己做 TTS 吗?
不做。所有朗读都委托给 dsh-pet 的 POST /voice/speak,音色与音量直接读它 /config 里的
main.voiceName / main.voiceVolume——也就是说完全跟随 dsh-pet 的设置,本插件没有任何本地 TTS。
dsh-pet 0.4.x 把音色改成了「限定 id」(provider/voice,默认 edge/zh-CN-XiaoyiNeural)。
旧配置里如果还留着裸名(zh-CN-XiaoyiNeural),/voice/speak 会直接 bad-request,
表现为有动画、有气泡,但没声音。本插件会用 dsh-pet 的 /voice/voices 目录把裸名补全成限定 id,
但它自己那条链路仍然读的是坏配置——所以建议打开 dsh-pet 设置重新选一次音色。
如果选的是需要凭据的云端音色(例如 deepseek/stella),而 DEEPSEEK_API_KEY 没配,
/voice/speak 会立刻失败(dsh-pet 日志里是 reason=DEEPSEEK_API_KEY is not configured,
连它自己的碎碎念也一起哑掉)。本插件遇到这种情况会自动改用目录里的 edge 默认音色重试一次,
并把失败原因写进设置页「语音任务」的诊断行,不会让整条唤醒反应没声音。
顺带说明识别侧:dsh-pet 0.4.9 里的 dsh 识别实现,接的就是 DSH 的 speechToText(SenseVoice),
与本插件语音任务用的是同一个引擎,只是各自走各自的入口。
说完判定/没开口放弃要等很久,一直卡在「正在听命令」?
端点检测的阈值必须相对底噪,不能写死一个绝对值。实测这台机器的底噪 RMS 就有
0.0230.033,说话也才 0.0480.072;旧实现把绝对下限写成 0.02(比底噪还低),
于是每一块都被判成「有声」、静音计数永远是 0,只能等到 60 秒上限——录音 60 秒、
识别 1.7 秒,就是你看到的那种「卡很久,最后又执行了」。
现在的规则:
- 底噪用预录段(或头 500ms)的中位数估;
- 有声阈值 = 底噪 × 1.55 + 0.006,静音判定就是「低于有声阈值」;
- 底噪跟随是非对称的(往下快、往上只在贴着底噪的窄带里极慢上调), 避免把说话的中等电平块当成静音、反过来抬高低噪,形成正反馈死循环;
- 另加
maxSpeechMs = 20s兜底,真的一直说不停也不会拖到 60 秒。
想自己核对电平:~/.dsh/dsh-pet-extend/last-listen.wav 就是引擎最近听到的 6 秒原始音频。
状态一直停在「正在听命令…」?
它只是设置页的状态提示。正常情况下收音结束会立刻转成「识别中… Ns」,识别完就消失。
如果它一直不消失,说明「听命令」窗口没有被解除——旧版本里这个窗口最长挂 60 秒,
现在收音一结束就主动解除(POST /api/voice/transcribing),并且窗口本身封顶 20 秒、
识别与落地各有超时(25s / 8s),任何异常都会立刻收场并记进诊断。
语音任务喊完没反应? 先在设置页「语音任务」卡片看第一行状态:
- 「识别不可用」→ DSH 里没启用官方语音输入插件,本功能只会退化成打开桌宠对话;
- 「识别就绪」但计数里「进入」不涨 → 唤醒没触发(看上面的唤醒诊断);
- 「进入」在涨、「识别」不涨 → 命令没被识别:确认说完后停了 2 秒再等结果, 或者把「没开口放弃」调大一点。
为什么说完要等 2 秒?
插件靠「持续静音」判断你说完了,默认 2 秒(voiceTaskSilenceMs)。想更快可以调到
1000~1500 ms,但太短容易把句中停顿当成结束。
「直接发送」会不会乱改代码?
auto 只对不命中黑名单的命令生效,其余一律退回草稿等你按回车;即便如此,
它也只是把话发给 agent,改文件的每一步仍然受 DSH 自己的权限确认约束。
这个模式没有「撤销」,需要中断请用会话里的停止按钮。
支持哪些平台?
取决于 sherpa-onnx-node 的预编译包。Windows x64 已验证;macOS / Linux 理论上可用,未逐一实测。
开发
npm test # 烟雾 + 回归测试(含假推理模块,不需要真模型)
lib/
index.js 服务端:HTTP 路由、设置、声纹、模型装配
client.js DSH 客户端:菜单、麦克风采集、上传、唤醒反应
kws.js KWS 引擎:并行多档、会话、诊断统计
speech.js 官方 SenseVoice 转写桥(PCM→WAV→transcribe,可选依赖)
voiceprint.js 声纹录入与校验
settings.js 设置持久化、唤醒词 → 拼音 token
models.js 模型路径与下载地址
pages/settings.html 设置页(原生 JS,无框架)
scripts/install-models.mjs
test/smoke.mjs
常用调试接口(同源):
| 接口 | 用途 |
|---|---|
GET /api/kws/status | 引擎/客户端/诊断计数 |
POST /api/kws/retry | 重建引擎(等真正结束再返回) |
POST /api/kws/test | 按住录音测试(body 为 16 kHz Int16LE PCM) |
GET /api/kws/test/audio | 回放刚才的测试录音 |
GET /api/kws/listen-audio | 回放正式监听最近 6 秒 |
GET /api/kws/voiceprint/audio?index=N | 逐条回放声纹录音 |
GET /api/kws/level | 麦克风电平/有效语音占比 |
GET /api/voice/status | 官方转写服务/provider 就绪状态 + 语音任务计数与最近一次结果 |
POST /api/voice/prepare | 预热识别模型(模型懒加载时先叫醒,省掉几百毫秒) |
POST /api/voice/command | 手动喂 16 kHz Int16LE PCM,返回识别文本与耗时(排查用) |
数据与隐私
所有数据都在本机 ~/.dsh/dsh-pet-extend/:
settings.json 设置
keywords.txt 当前唤醒词 token
voiceprint.json 声纹特征向量
voiceprint-*.wav 每次录入的原始录音(用于回放)
voiceprint-audio.json 录音索引
音频不离开本机,也不写入插件目录之外的任何位置。
语音任务的识别同样在本机完成(DSH 官方 SenseVoice provider,模型在
~/.dsh/speech-to-text/),命令音频只经过本机 HTTP 传给宿主进程,不落盘、不上传。
插件只记录「最近一次识别出的文字」用于设置页诊断,保存在内存里,重启即清空。
许可证
Apache License 2.0,Copyright 2026 dsh-pet-extend contributors。
Apache 2.0 允许商用、修改与再分发,条件是分发时保留本许可证与版权声明、标注你修改过的文件,并且它自带显式的专利授权。
本项目是 PC2005-cloud/dsh-pet 的扩展,dsh-pet 自身的许可证以其仓库为准,本项目不改变它。
模型来自 sherpa-onnx / 3D-Speaker 社区发布,遵循其各自的许可证;仓库内仅为方便安装而附带。
Plugin correlati
dsh-web-ui (dsh-tool-describe-image)
zhu1090093659/dsh-web-ui
modlens
liustack/modlens
ipollowork
devin-axis/ipollowork
dsh-image-gen
shanliuling/dsh-image-gen