dsh-funasr-voice

Readme

# dsh-funasr-voice

DeepSeek Harness (DSH) Web GUI 的**本地离线语音输入**插件。浏览器采集麦克风 → host 半自动拉起本地 **FunASR + SenseVoiceSmall** 识别 → 文字实时填入输入框。全程离线、不联网、不上传。

> ⚠️ **macOS 用户注意**：DSH Desktop 2.0.2 存在麦克风权限 Bug，会拿到静音流、表现为
> 「录音了但识别不出、输入框没反应」（静默失败）。使用前需先给 DSH Desktop 打补丁，
> 详见下方「已知 Bug 与修复」。

## 特性

- **点一下开始、再点一下停止**：点按切换连续听写，VAD 自动断句，边说边出字。
- **一键安装**：设置页点「安装」即自动创建 venv、安装 funasr + torch、下载 SenseVoiceSmall 模型（约 2~3 GB），全程无需手动敲命令。
- **录音计时**：录音时按钮旁实时显示已录时长（`0:05`）。
- **完全离线**：ASR 在本地 CPU 上跑（SenseVoice RTF ~0.07，约 10x 实时）。
- **自动填 / 自动发**：识别文字自动填入草稿，可选「识别后自动发送」。
- 句首/句尾的 SenseVoice 事件/情绪 emoji（👏🎼😊 等）会被自动剥掉。

## 截图

**语音输入**（点话筒 → 说话 → 文字进输入框，按钮旁带计时）：

![语音输入](voice.png)

**配置**（设置 → 通用 → 语音输入，支持自动检测 / 手动填路径）：

![配置](config.png)

## 原理

```
浏览器麦克风 ──AudioWorklet 采集──▶ VAD 断句 ──POST /funasr-voice/asr（原始 f32 PCM @16kHz）
                                           │ host 半代理
                                           ▼
                              本地 FunASR Python 服务（SenseVoiceSmall）
                                           │
              输入框 ◀── 识别文字 ──────────┘
```

- 浏览器只做采集 + 端点检测，ASR 全部在 host 侧本地 Python 进程里跑。
- host 半**懒加载**拉起 FunASR 服务（首次识别约 2~3 秒加载模型，之后常驻复用）。
- 客户端用 **AudioWorklet** 采音（不是已废弃的 ScriptProcessorNode）。

## 环境要求

| 依赖 | 说明 |
|------|------|
| DeepSeek Harness Desktop | **2.0.2**（本插件的开发/测试版本） |
| Python venv + FunASR 1.4.x + torch | 本地 ASR 引擎 |
| SenseVoiceSmall 模型 | 本地离线加载 |
| Node ≥ 20 | 插件 host 半 |

> ⚠️ **DSH Desktop 2.0.2 存在麦克风权限 Bug**，直接使用会拿到静音流、无法识别。
> 详见下方「已知 Bug 与修复」，需要先给 DSH Desktop 打一个补丁。

## 一键安装（推荐）

打开 DSH 设置 → 通用 → 语音输入，点「**安装**」即可。插件会自动：

1. 探测本机 `python` / `python3` 及版本，挑一个可用的做 venv 基座；
2. 在安装目录（默认 `~/.dsh/funasr-voice`）创建独立 venv，安装 torch + funasr；
3. 下载 SenseVoiceSmall 模型到 `~/.dsh/funasr-voice/models/SenseVoiceSmall`（约 1 GB）。

全程有进度和日志显示，装完自动填入路径。桌面端点「安装」会先弹原生目录选择器让你选安装目录；Web 端则手填目录。

## 备选：手动安装 FunASR 环境

如果你已有 FunASR 环境、或想自己控制安装位置，以 macOS 为例：

```bash
# 1. 创建独立 venv
python3 -m venv ~/Documents/ASR/funasr/.venv
source ~/Documents/ASR/funasr/.venv/bin/activate

# 2. 安装 FunASR（会自动带上 torch、modelscope 等依赖，约数 GB 磁盘空间）
pip install --upgrade pip
pip install funasr

# 3. 下载 SenseVoiceSmall 模型（约 1 GB，二选一）
mkdir -p ~/Documents/ASR/funasr/models
cd ~/Documents/ASR/funasr/models

#    方式 A：ModelScope（国内更快）
python -c "from modelscope import snapshot_download; snapshot_download('iic/SenseVoiceSmall', local_dir='SenseVoiceSmall')"

#    方式 B：HuggingFace
pip install huggingface_hub
python -c "from huggingface_hub import snapshot_download; snapshot_download('FunAudioLLM/SenseVoiceSmall', local_dir='SenseVoiceSmall')"
```

装完后：

- `python` 路径：`~/Documents/ASR/funasr/.venv/bin/python`
- 模型目录：`~/Documents/ASR/funasr/models/SenseVoiceSmall`（需包含 `model.pt` 和 `config.yaml`）

把这两个填进插件的 `python` / `model` 配置（见下方「配置」）即可，也可以用插件设置里的
「**自动检测 Python 与模型**」自动识别。

## 安装

1. 安装插件：

   ```sh
   dsh plugin --profile <你的profile> add <本插件目录或仓库地址>
   ```

2. 重启 DSH，进 设置 → 通用 → 语音输入，点「**安装**」自动装好 FunASR 环境与模型（或按上面「备选」手动准备）。
3. 点输入框右侧的**话筒图标**开始听写。首次会请求麦克风权限，允许即可。

## 配置

有两种方式配置 `python` / `model`：

**① GUI（推荐）**：DSH 设置 → 通用 → 语音输入，点「**安装**」会自动装好 FunASR 环境与
模型并写入路径；装完点「安装」旁的状态会变成「✓ 已就绪」。配置持久化到
`~/.dsh/dsh-funasr-voice.json`，优先级高于 YAML 配置。

**② YAML**：插件源码不带个人路径（默认 `python: python3`、`model` 为空）。在你**自己
profile 的 `cordis.patch.yml`** 里覆盖：

```yaml
# ~/.dsh/profiles/<你的profile>/cordis.patch.yml
- id: dsh-funasr-voice
  config:
    python: /你的/FunASR/.venv/bin/python
    model: /你的/SenseVoiceSmall/模型目录
```

可配置字段：

| 字段 | 默认 | 说明 |
|------|------|------|
| `enabled` | `true` | 总开关 |
| `basePath` | `/funasr-voice` | HTTP 路由前缀（一般别改） |
| `python` | `python3` | FunASR venv 的 python 解释器（**必配**） |
| `model` | （空） | SenseVoiceSmall 模型目录（**必配**） |
| `port` | `18765` | 本地 ASR 服务端口 |
| `language` | `auto` | `auto` \| `zh` \| `en` \| `ja` \| `ko` \| `yue` |
| `useItn` | `true` | 逆文本正则化 |
| `autoSend` | `false` | 识别后自动发送 |

## 已知 Bug 与修复：DSH Desktop 2.0.2 麦克风权限

**Bug 现象**：DSH Desktop 2.0.2 的 Electron 主进程没有处理 `getUserMedia` 的
`media` 权限。结果是浏览器拿到一条**静音流**，且 macOS 从不弹「想要访问麦克风」
授权框——语音插件表现为「录音了但识别不出、输入框没反应、没有文字」。

**根本原因**：`dsh-plugin-desktop/src/main.ts` 缺少
`session.setPermissionRequestHandler`，也从不调用
`systemPreferences.askForMediaAccess('microphone')` 去触发 macOS 的系统授权弹窗。

**修复方式**：给 DSH Desktop 源码打补丁（`dsh-plugin-desktop/src/main.ts`，在
`app.whenReady()` 之后）：

```ts
import { session, systemPreferences } from 'electron'

session.defaultSession.setPermissionRequestHandler((_wc, permission, callback, details) => {
  if (permission !== 'media') {
    callback(true)
    return
  }
  const mediaTypes = 'mediaTypes' in details ? details.mediaTypes : undefined
  const checks: Promise<boolean>[] = []
  if (!mediaTypes || mediaTypes.includes('audio')) checks.push(systemPreferences.askForMediaAccess('microphone'))
  if (!mediaTypes || mediaTypes.includes('video')) checks.push(systemPreferences.askForMediaAccess('camera'))
  void Promise.all(checks).then(results => callback(results.every(Boolean)))
})
```

重新构建并启动后，点麦克风会弹出系统授权框，允许后即可正常识别。若不想改源码，也可
等官方修复该 Bug 后升级 DSH Desktop。

## 目录结构

```
.
├── lib/index.js       # host 半：拉起/代理 FunASR + HTTP 路由
├── lib/client.js      # client 半：话筒按钮 + VAD + 计时
├── asr_server.py      # FunASR(SenseVoice) HTTP 服务，host 半自动拉起
├── cordis.patch.yml   # 插件树插入补丁（配置）
└── package.json
```

## 排查

- 识别报错「server exited during startup」：`python` / `model` 路径不对，看 DSH 日志里的 stderr。
- 录音但没文字、不弹授权框：见上方「DSH Desktop 的麦克风权限」。
- 首次识别慢：模型加载 + torch 初始化约 2~3 秒，之后常驻。

## License

[MIT](LICENSE)