dsh-voice-assistant

Readme

# 🎙️ dsh-voice-assistant

> **dsh web 免手语音助手** —— 关键词唤醒 · 语音听写 · 口述编辑 · 中文朗读

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Version](https://img.shields.io/badge/version-0.5.9-00e5ff.svg)
![Platform](https://img.shields.io/badge/platform-dsh%20web-6f42c1.svg)
![ASR](https://img.shields.io/badge/ASR-sherpa--onnx%20WASM%20%E7%A6%BB%E7%BA%BF-0ea5e9.svg)

在 dsh web 输入框旁提供麦克风按钮与科幻风状态条，让你**彻底解放双手**：说「小鲸」唤醒，口述指令自动入框，回复自动朗读——全程不离键盘，不碰鼠标。

**识别引擎默认使用 sherpa-onnx WASM 在浏览器本地运行**：模型跑在浏览器里，**离线可用、不依赖 Google 服务**，国内网络无需任何代理。仅在本地资源加载失败时自动回退浏览器 Web Speech API。

---

## ✨ 功能特性

| 能力 | 说明 |
| --- | --- |
| 🎤 **关键词唤醒** | 说「小鲸」（或任意自定义词）唤醒。**同音/近音容错自动生效**：同音字直接唤醒；近音字需 3s 内二次确认（防误唤醒，可关） |
| ⚡ **实时响应** | 利用流式中间结果**不等整句说完**：唤醒词一出口立即唤醒，口述命令（执行发送/执行清空等）边说边执行，无需等待静默判定 |
| 🗣️ **语音听写** | 唤醒后连续口述，逐句自动填入输入框，30s 无语音自动回待命 |
| ✏️ **口述编辑命令** | 所有命令以「执行」开头（如「执行删除上一句」「执行发送」），正文中的「发送/清空/删除」等词**永不误触**；含**同音字容错**（如「直行发宋」→执行发送），直接操作草稿 |
| 📖 **中文朗读** | 模型回复自动以中文女声朗读，可随时语音打断（barge-in） |
| 🤖 **本地离线识别** | sherpa-onnx WASM + 流式 Zipformer 模型，浏览器本地推理，隐私不上云 |
| 🧩 **一键安装更新** | 设置页内置「检查更新」，跟随 GitHub 最新版一键升级 |
| ⚙️ **热配置** | 唤醒词 / 前置 skill / 问候语 / 识别引擎等全部即时生效 |

## 🚀 快速开始

```bash
# 方式一：npm registry（稳定版，需已安装 dsh web）
npm i -g dsh-voice-assistant

# 方式二：GitHub 开发版（含尚未发布的改动）
dsh plugin --profile web add github:supersyh-sss/dsh-voice-assistant

# 重启
dsh web
```

打开 dsh web（默认 127.0.0.1:3080），插件加载后自动进入待命监听，说「小鲸」即可开始使用。

> npm 全局安装后，dsh 通过 profile 的 bundles 加载插件：确认 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 中包含 `dsh-voice-assistant`，或使用 `dsh plugin --profile web add dsh-voice-assistant` 登记，然后重启 dsh web。

**更新插件**（设置页 → 语音助手 → 检查更新，或终端执行）：

```bash
# npm 安装（跟随 registry 最新版）
npm i -g dsh-voice-assistant@latest

# GitHub 安装（跟随 GitHub 最新提交）
dsh plugin --profile web update dsh-voice-assistant
```

## 🧠 识别引擎

插件内置两种识别引擎，可在设置页热切换：

| 引擎 | 说明 |
| --- | --- |
| `auto`（默认） | 优先本地 sherpa 识别，加载失败自动回退浏览器识别 |
| `sherpa` | 强制本地识别，离线可用、不依赖 Google；加载失败则明确报错 |
| `web-speech` | 始终使用浏览器自带识别 |

**响应速度**：识别为流式解码，中间结果每约 0.3s 刷新一次。插件利用中间结果**即时响应**——唤醒词与短命令不等「说完话 + 静默判定」即可触发；句尾判定静默窗口已收紧（有内容句 1.0s、静默清理 1.6s），整句听写结果也比默认更快返回。

**唤醒准确度**：唤醒词采用「L1 同音强命中 + L2 近音弱命中」两层判定——同音字（如 ASR 把「小鲸」识别成「小京/小金」）直接唤醒；近音字（如「秀经/小姐」）在严格模式下需再说一遍确认，普通说话不误唤醒。容错基于通用拼音引擎，**对任意自定义唤醒词自动生效**，无需维护词表；pinyin 库加载失败时自动降级为纯字面匹配，不影响监听。

**热词增强**：唤醒词与全部「执行」命令词会注入 sherpa 识别器热词表（hotwords），识别器对关键短语加权——唤醒与命令的命中率显著提升，且不影响普通口述内容的正常识别。

识别为提升不同麦克风/距离下的准确率做了 4 层音频处理：采集时显式开启浏览器底层的自动增益 / 降噪 / 回声消除；音频链插入 **80Hz 高通滤波**，滤除风扇、空调等低频环境噪声；软件层做**自动增益（AGC）**——语音块自动放大到目标电平（小声也能稳定识别），并叠加设置页「输入音量」（1~4 倍）微调，`tanh` 软限幅防削波；**静音块（RMS 低于约 -50dBFS）直接丢弃**，避免环境底噪被识别成「嗯/啊」等干扰词。注意软件增益仅对本地 sherpa 引擎生效（web-speech 音频不经插件）。

本地识别资源托管在 GitHub（`assets/`），启动时自动按顺序探测可用源：

1. **jsDelivr CDN**（默认主源，国内可达）
2. **Gitee 镜像**（可选，导入后自动优先）
3. ghproxy 代理
4. GitHub raw（兜底）

> 手动指定资源地址：设置页「资源服务器地址」直接填写，或在控制台执行
> `window.DSH_VOICE_BASE = "https://…"` 后刷新页面，优先级高于自动探测。

## ⚙️ 设置页

在 dsh web「设置 → 语音助手」中调整（即时生效）：

- **唤醒词**：逗号分隔多个，热切换；同音/近音容错自动生效（自定义词同样支持）
- **严格唤醒**：开启时近音唤醒词需 3s 内再说一遍确认才生效，防误唤醒；关闭则近音也立即唤醒
- **前置 skill**：作为系统提示注入模型上下文，不显示在输入框、不随语音发出；**留空使用内置缺省值**（语音助理定位：简洁、行动导向、先做后说），填入后覆盖缺省
- **唤醒问候 / 问候语模板**：支持 `{时段}` 占位符
- **自动朗读回复**：回复完成后自动朗读
- **空闲超时**：唤醒后无语音自动回待命
- **识别引擎**：auto / sherpa / web-speech
- **输入音量**：麦克风声音太小时调大（1~4 倍），仅本地 sherpa 识别生效；静音时自动不放大
- **资源服务器地址**：本地识别资源下载源（以 `/` 结尾），留空自动探测；修改后重启 dsh web 生效
- **版本与更新**：显示当前版本，一键「检查更新」，发现新版本可直达 GitHub 发布页 / 复制更新命令

## 🎛️ 口述命令

唤醒后说出以下命令即可执行，命令本身**不会**进入输入框：

| 命令 | 别名 |
| --- | --- |
| 执行删除上一句 | 执行删掉上一句 / 执行删除最后一句 / 执行删掉 |
| 执行清空 | 执行清空草稿 |
| 执行换行 | 执行另起一行 |
| 执行发送 | 执行发送消息 |
| 执行停止朗读 | 执行别读了 |
| 执行朗读 | 执行读一下 / 执行念一遍 |
| 执行停止监听 | 执行关闭监听 |
| 执行终止回答 | 执行停止回答 |
| 执行新开会话 | 执行新建会话 / 执行新对话 |

所有命令统一以「执行」开头，这是**防误触的核心设计**：正文口述中常见的「发送」「清空」「删除」「换行」等词本身**永远不会触发命令**，只有整句以「执行」开头的命令短语才生效（如「执行发送」「执行清空」）。「执行」前缀带同音字容错（「直行」→执行、「执刑」→执行等），误触概率趋近于零。

「执行终止回答」相当于按下**停止生成**按钮：取消当前正在进行的回答（排队中的内容保留、取消后继续执行）；「执行新开会话」相当于点击**新会话**：创建空白会话并切换到它（保留当前工作目录），切换后自动恢复监听，直接开讲。

命令词支持**同音字容错**（覆盖 ASR 常见同音混淆，如「执行发宋」→执行发送、「执行清孔」→执行清空、「执行删除上遗句」→执行删除上一句），且同音匹配**仅从句子开头对齐、尾部只允许语气后缀**（「执行发送给张三」「执行发送一下」不会误触）。命令不可逆，因此**不做近音容错**——宁漏勿错，保证准确。口述命令在流式中间结果阶段即可触发，说完立即执行。

## ⌨️ 快捷键

| 快捷键 | 作用 |
| --- | --- |
| `Ctrl+Shift+Space` | 切换常开监听 |
| 状态条「按住说话」 | 手动听写（按住说话，松开入框；朗读中可打断） |

## 🧰 开发

```bash
# 单元测试（核心逻辑：唤醒词 / 拼音容错 / 命令解析 / 草稿编辑）
node test/logic.test.mjs

# 修改源码后同步到 dsh profile（Windows）
sync-plugin.cmd
```

```
dsh-voice-assistant/
├── lib/
│   ├── index.js              # 插件宿主端：设置注册 + 前置 skill 注入（内置缺省值）
│   └── client.js             # 浏览器端：识别引擎、状态机、UI、设置页
├── assets/                   # 本地识别资源（CDN 分发）
│   ├── sherpa-onnx-asr.js                # sherpa-onnx C API 封装
│   ├── sherpa-onnx-wasm-main-asr.patched.js  # wasm 胶水（pthread 适配）
│   ├── sherpa-onnx-wasm-main-asr.wasm    # wasm 运行时（12.5 MB）
│   └── models/               # 流式 Zipformer 模型（encoder 走 gzip 分发）
├── cordis.patch.yml          # dsh bundle 补丁清单
├── sync-plugin.cmd           # Windows 开发同步脚本
└── test/logic.test.mjs       # 核心逻辑单元测试
```

## ❓ 常见问题

**识别没反应？** 确认麦克风权限已允许；首次使用本地识别需下载约 38 MB 资源（之后走浏览器缓存），弱网下首启较慢。

**本地识别加载失败？** 检查网络能否访问 jsDelivr / Gitee；也可在设置页手动指定「资源服务器地址」，或查看浏览器控制台 `[dsh-voice]` 日志中的具体原因。

**唤醒偶尔误触发？** 近音容错在「严格唤醒」模式下需要二次确认，若仍觉得灵敏可关闭「严格唤醒」反查——更常见的是开启后待命时误唤醒显著减少。

**口述命令识别不准？** 命令词支持同音字容错（如「发宋」→发送），但不做近音容错以免误删/误发；若某个写法反复识别失败，可反馈补充别名。

**中文朗读音色不满意？** 朗读使用系统 `speechSynthesis` 音色库，Windows 上通常为「Microsoft Huihui」/「Microsoft Yaoyao」，可在系统设置中调整。

## 🗺️ 路线图

- [x] 手动听写（按住说话 + 追加式草稿）
- [x] 常开监听 + 关键词唤醒 + 状态机
- [x] 问候 + 口述编辑命令 + 多轮免手输入
- [x] sherpa-onnx WASM 本地识别（离线、国内可用）+ 多源资源自动探测
- [x] 设置页聚合（唤醒词 / 前置 skill / 问候 / 自动朗读 / 识别引擎 / 资源地址 / 检查更新）
- [x] 唤醒词与口述命令拼音容错（同音 L1 + 近音 L2 二次确认，自定义词通用）
- [x] 流式中间结果实时响应（唤醒 / 短命令零等待，端点判定收紧）
- [x] 前置 skill 内置缺省值（定位清晰、角色清晰）
- [ ] 多轮免手对话（自动分段提交 + 对话衔接）
- [ ] Edge TTS 服务端合成 + barge-in 精细化

## 📄 License

[MIT](LICENSE)