dsh-plugin-voice-dictation

Readme

# 🎙️ dsh-plugin-voice-dictation · 语音听写

> **说话即任务**：点一下 🎤，说出你的任务，自动填入输入框或**直接发送**给 DeepSeek Harness Web GUI 里的 Agent —— 从此不用打字。

[![ci](https://github.com/dytom18/dsh-plugin-voice-dictation/actions/workflows/ci.yml/badge.svg)](https://github.com/dytom18/dsh-plugin-voice-dictation/actions/workflows/ci.yml)
[![license](https://img.shields.io/github/license/dytom18/dsh-plugin-voice-dictation)](LICENSE)
![topic](https://img.shields.io/badge/topic-dsh--plugin-blue)

纯浏览器端实现：使用浏览器内建的 **Web Speech API**（Chrome / Edge 自带在线语音识别，无需任何 API Key、无需联网配置密钥、无需构建）。

---

## 功能

| 能力 | 说明 |
|---|---|
| 🎤 一键听写 | 点击悬浮按钮开始说话，实时显示转写（灰字=临时结果），**再说一次点击**即结束 |
| 自动发送 | 识别结束后按设置自动把任务发送给当前会话（也可改成只填入输入框草稿） |
| 自动续接 | 浏览器静音超时/网络抖动自行断流时**自动续接**，不会把半句话当成说完了发出去 |
| 智能接入 | 优先走 DSH 客户端 API（composer 输入机 `setDraft`+`submit` / `conversation.send`），失败自动降级为 DOM 写入输入框 |
| 草稿保护 | 输入框里已有你手写的内容时**绝不抢发、绝不覆盖**：自动改为追加进草稿并提示 |
| 撤销口令 | 说「取消 / 算了 / 错了 / 重来」等（整句）→ 本条直接丢弃，不发送 |
| 更正口令 | 说「更正 / 上一条作废」→ 自动通知 Agent「上一条任务作废，以下一条为准」 |
| 去重 | 同一句被浏览器拆成两段结果下发时自动合并，绝不出现重复两行 |
| 可拖动按钮 | 按钮位置随意拖动（拖动不会误触发录音），位置持久化（localStorage + Cookie 双写） |
| 可隐藏 | ⚙ 里一键隐藏悬浮按钮；`Ctrl+Shift+M` 随时唤回 |
| 随手可关 | 面板 `×` 或 `Esc` 关闭；面板默认不显示，不占屏幕 |
| 快捷开关 | `Ctrl+Shift+M` 全局开/关听写 |
| 停止后快捷操作 | 识别完成后出现「发送 / 填草稿 / 丢弃」三个按钮，不满意随时重来 |
| 超时保护 | 单次最长听写 90 秒自动结束（自动续接不延长上限），不怕忘关麦克风 |
| 自愈 | 组件被页面框架移除后 10 秒内自动重建 |
| 中英双语 | 界面跟随浏览器语言；识别语言可在设置里选 中文 / English / 跟随浏览器 |
| 安全兜底 | 权限被拒、浏览器不支持、网络错误都有明确提示；插件任何异常都不影响 DSH 页面 |

## 安装

### 方式 A：一行从 GitHub 安装（推荐）

```sh
dsh plugin --profile web add github:dytom18/dsh-plugin-voice-dictation
```

### 方式 B：克隆后本地安装

```sh
git clone https://github.com/dytom18/dsh-plugin-voice-dictation.git
dsh plugin --profile web add ./dsh-plugin-voice-dictation
```

### 方式 C：已在本地（开发调试）

```sh
dsh plugin --profile web add C:\Users\hp\.dsh\plugins\dsh-plugin-voice-dictation
```

> **暂未发布到 npm**（npm 同名包已被他人占用，且新账号受 2FA 限制），目前以 GitHub 为唯一分发渠道。
> Windows 桌面端安装前请**完全退出 DSH Desktop（含托盘图标）**，避免 pnpm 占用报 `EPERM`。

然后**重启 DSH 服务**（已安装 `dsh-setting-restart` 的话：设置 → 通用设置 → 一键重启；或在服务端 `dsh web` 重启），页面按 `Ctrl+Shift+R` 强制刷新一次。

## 使用

1. 页面右下（可拖动）出现紫色圆形 **🎤** 按钮；
2. 点击它 → 打开听写面板，按钮变红开始录音；
3. **说出你的任务**（例如：“帮我写一个 Python 脚本，统计当前目录下所有文件的行数”）；
4. 说完了再点一次 🎤（或等待 90 秒自动结束）；
5. 默认**自动发送**：任务直接发给了 Agent 🚀；若在设置里关闭了自动发送，则文字填入输入框，你按回车发送即可。

**记住：`Ctrl+Shift+M` 也能随时开始/停止听写。**

## 设置

点面板右上角 **⚙**：

| 选项 | 说明 |
|---|---|
| 识别语言 | 中文（普通话）/ English (US) / 跟随浏览器 |
| 自动发送 | 开启=说完即发送给 Agent；关闭=只填入输入框草稿 |
| 发送前确认 | 开启=说完先显示文字，点「发送」才发（重要任务推荐） |
| 显示悬浮按钮 | 关闭=整个插件从屏幕上收起；`Ctrl+Shift+M` 可唤回 |
| 复位按钮位置 | 按钮移丢了？一键回默认位置 |

## 语音口令（整句说即可）

| 你说 | 插件行为 |
|---|---|
| 取消 / 撤消 / 算了 / 错了 / 说错了 / 不对 / 不要 / 等等 / 重来 / 重新说 / 别发 | **本条不发送**，提示重新说 |
| 更正 / 纠正 / 改口 / 上一条作废 / 上一条不算 | 自动给 Agent 发一句「上一条任务作废，以下一条为准」 |
| 其他任何内容 | 按设置发送（或填入草稿）；输入框已有手写内容时改为追加、不发送 |

> 注意：只有**整句**等于这些词才触发（例如「不要用 Python，改用 Go」不会被当成取消）。

## 验证是否加载成功

浏览器按 `F12` 打开控制台，执行：

```js
__VOICE_INPUT_DEBUG__.state()     // 插件状态：supported / sessionsAvailable / send / confirm / visible
__VOICE_INPUT_DEBUG__.ui()        // 界面状态：面板是否可见、按钮是否显示
__VOICE_INPUT_DEBUG__._probe()    // 会话链路自检：scope / conversation / 输入机 / 当前草稿
__VOICE_INPUT_DEBUG__._classify('取消')   // 口令分类：cancel / correct / normal
```

没有麦克风也能完整验证链路：

```js
__VOICE_INPUT_DEBUG__.simulateDispatch('帮我分析今天的行情', true)   // 模拟识别并自动发送
__VOICE_INPUT_DEBUG__.simulateDispatch('帮我看看这个文件夹', false)  // 模拟识别并填入草稿
__VOICE_INPUT_DEBUG__.simulateFinish('帮我统计文件数量')             // 模拟「停止录音」全链路
```

## 工作原理

```
🎤 点击 → Web Speech API 在线识别（zh-CN / en-US）
          ↓ 实时转写
识别结束 → 0) 口令判定：cancel=丢弃 / correct=通知作废 / normal=继续
          1) 草稿保护：输入框已有内容 → 追加进草稿，不发送
          2) 优先：DSH 客户端 API
             · 有 composer 输入机 → setDraft + submit()（等同按回车）
             · 无输入机           → conversation.send()（队列发送）
          ↓ 任一失败
          2) 兜底：原生 setter + input 事件写入 textarea（React 受控输入安全更新）
```

## 环境要求

- DeepSeek Harness `dsh web` profile（本插件为纯客户端插件，`dsh.client.platform: web`）
- Chrome 或 Edge（Firefox 不支持 Web Speech API，插件会给出提示）
- 语音识别需要 **Chrome 在线服务**（Chrome 内置，无需登录/密钥）；首次使用浏览器会请求**麦克风权限**，请允许

## 故障排查

| 现象 | 原因 | 处理 |
|---|---|---|
| 按钮不出现 | 服务未重启 / 页面缓存旧 bundle | 重启 DSH 服务 + `Ctrl+Shift+R` |
| 提示「不支持语音识别」 | Firefox 或内核不支持 | 换 Chrome/Edge |
| 提示权限被拒 | 麦克风权限被拒 | 点地址栏 🔒 → 允许麦克风 → 刷新页面 |
| 提示网络错误 | Chrome 识别服务不可达 | 确认能正常上网后重试 |
| 识别成了英文/错语种 | 语言设置不对 | 设置里选 中文（普通话） |
| 面板关不掉 | 旧版本 bug（已修） | 刷新页面到 v1.1.0+ |
| 消息重复两行 | 旧版本 bug（已修） | 刷新页面到 v1.1.0+ |

## 更新日志

### v1.1.0
- **修复**：面板默认隐藏、`×`/`Esc` 真正可关闭（旧版面板常驻、关不掉）
- **修复**：临时结果升级为定稿后未清空导致「同一句发两行」，并增加规范化去重
- **修复**：发送时整句替换草稿，不再追加出第二行
- **新增**：浏览器自行断流时自动续接，不会提前发送半句话
- **新增**：撤销口令（取消/算了/错了…）与更正口令（更正/上一条作废）
- **新增**：草稿保护——输入框有手写内容时只追加、不覆盖、不抢发
- **新增**：可隐藏悬浮按钮（`Ctrl+Shift+M` 唤回）、面板跟随按钮移动、10 秒自愈重建、拖动不再误触发录音
- **新增**：调试钩子 `_probe()` / `_classify()` / `ui()` / `simulateFinish()` 便于自检

### v1.0.0
- 首个版本：悬浮 🎤 听写、自动发送/填草稿、快捷键、可拖动、位置持久化

## 二次开发

- 全部逻辑集中在 `lib/client.js`（浏览器端，无依赖、无构建），宿主侧 `lib/index.js` 为空壳；
- 改完执行 `node --check lib/client.js` 验证语法；
- 调试钩子：`window.__VOICE_INPUT_DEBUG__`（见上）。

## License

MIT