dsh-voice-typing
lunnlew/dsh-voice-typing
语音输入与对话朗读：点一下或按快捷键切换语音模式，边说边出字，离线本地识别（SenseVoice + Silero VAD），支持自定义词表、热词提示与多模型档位；回复可用 Edge 在线 / 本地神经模型 / 系统语音三种引擎朗读。
Installazione
dsh plugin --profile web add github:lunnlew/dsh-voice-typingREADME
dsh-voice-typing 使用说明
DeepSeek Harness 的语音输入与对话朗读插件。
点一下麦克风按钮（或按 Alt+V）就开始听你说话，文字自动进输入框；助手的回复可以念给你听。
识别默认在本地完成，不需要 API Key，断网也能用。
这份文档只讲怎么用。想知其所以然，或者要维护这个插件，看文末更深入的资料。
目录
1. 能做什么
一句话：说话代替打字，回复念给你听。
四件事各自独立，用哪件开哪件：
| 能力 | 做什么 | 什么时候用 |
|---|---|---|
| 语音输入 | 你说话，文字自动进输入框，也可以说完自动发送 | 不想打字、手在忙、想说快点 |
| 对话朗读 | 助手的回复自动念出来 | 不想盯着屏幕 |
| 全局语音 | 页面上常驻一个小麦克风，说话直接进当前会话，不经过输入框 | 在设置页、插件页这些没有输入框的地方也想开口 |
| 让 AI 操作界面 | 你开口说一句，助手替你切换会话、打开页面、点按钮、填输入框 | 「帮我把侧栏收起来」「打开插件页」「点一下设置里那个开关」 |
几件值得先知道的事：
- 麦克风按钮是开关，点一下开、再点一下关，不是「按住说话」。
- 默认本地识别，用的是 DSH 已经装好的那份模型，零下载、零密钥、断网可用。
- 边说边出字，说话时文字实时进输入框，不用等说完。
- 念回复有四种方式：微软在线语音（音质最好，要联网）、本地神经模型（离线，音质接近在线）、 系统自带语音（最快）、以及你自己跑的 GPT-SoVITS 服务。
- 全局语音可以喊唤醒词：默认「小鱼」，先说唤醒词再说命令，平时麦克风在待机， 环境里的闲聊不会被发进会话。
- 让 AI 操作界面默认关闭，需要你在设置里明确打开；切会话、发消息这类会改动内容的操作 会先弹一条确认，你可以点按钮，也可以直接说「允许」或「拒绝」。
2. 安装
前置条件：已经装好并运行过 DeepSeek Harness 桌面应用。
-
安装插件。在 DSH 的终端里执行：
dsh plugin --profile desktop add dsh-voice-typing -
重启 DSH。装完必须重启才会生效。
-
启用组合包。打开「设置 → 插件」，把
dsh-voice-typing加进启用列表并勾选。 -
确认聊天输入框旁边出现麦克风图标。看到它，安装就成功了。
看不到麦克风图标时，先检查第 3 步有没有勾上，再重启一次；还不行看 遇到问题怎么办。
关于 macOS 和 Linux：只有「窗口不在前台也能按快捷键」这一项需要额外的可选组件，
安装插件时会自动尝试装上。装不上也不会影响说话和朗读这些主要功能，
只是那一项快捷键不可用。更新插件后可以在插件目录执行一次 pnpm install，然后重启 DSH。
3. 第一次使用
按顺序做一遍，每一步都写明会看到什么。
打开语音模式。 点一下麦克风按钮，或按 Alt+V。按钮变高亮，旁边的状态显示「聆听中」。
开始说话。 说一句完整的话，比如「今天天气怎么样」。文字一边说一边出现在输入框里。
停下来。 默认静音 1.5 秒算「说完一句」，说完自动发给助手，助手开始回复。 想改成「说完不自动发，我自己按回车」，就把设置里的「识别后自动发送」关掉。
听回复。 勾上「朗读回复」后，助手的回复会自动念出来。念的时候麦克风旁边出现 「停止朗读」，点它就不念了。想打断朗读自己接话，直接开口说就行，朗读会停，你说的话会发出去。
关掉。 再点一下麦克风按钮，或按 Alt+V，或右键点麦克风。状态回到「已停止」。
「朗读回复」不需要开着语音模式，勾上就生效；反过来也一样，只听不念、只念不听都行。
4. 平时怎么用
| 想做什么 | 怎么操作 |
|---|---|
| 开关语音模式 | 点一下麦克风按钮，或按 Alt+V |
| 说完一句并发送 | 说完停顿 1.5 秒（默认） |
| 说完就退出语音模式 | 设置里把「交互模式」改成「说完就关」 |
| 这一轮不再念了 | 点「停止朗读」 |
| 打断朗读、自己说话 | 直接开口说 |
| 临时不自动发送 | 关掉「识别后自动发送」，说完自己按回车 |
| 只念回复、不发言 | 只勾「朗读回复」，不点麦克风 |
| 在没有输入框的页面说话 | 打开「全局语音浮层」，按 Ctrl+Alt+V 或点右下角小麦克风 |
| 不按键、喊一声就说话 | 打开「全局语音浮层」，先说唤醒词（默认「小鱼」）再说命令 |
| 窗口不在前台也能按快捷键 | 打开「系统级全局热键」，Windows 直接可用，macOS 还要授权辅助功能 |
| 让 AI 帮忙操作界面 | 「允许 AI 操控界面」和「全局语音浮层」两个开关都打开 |
| 让 AI 打开插件页、收起侧栏 | 直接说「打开插件页」「把侧栏收起来」 |
| 让 AI 点某个按钮、往某个框里填字 | 先说「看看当前页面有什么」，再照着它报回来的名字说要点哪个、填什么 |
麦克风按钮的两个手势：点一下和右键都是开关语音模式。关掉时只是停止聆听， 已经在念的那一轮会念完。
快捷键必须带至少一个修饰键（Ctrl、Alt、Shift、Windows/Cmd）。如果主键是单个字母，
必须配 Ctrl、Alt 或 Windows/Cmd，只配 Shift 不算——那样正常打字会被误触发。
另外别用 Ctrl+Shift+V（浏览器的「粘贴为纯文本」）和 Ctrl+Space（输入法占用）。
打开「全局语音浮层」后，输入框上的麦克风会隐藏，Alt+V 改为切换浮层的麦克风，
界面上只留一个语音入口；关掉浮层就恢复原来的样子。
5. 设置逐项说明
打开「设置 → 语音输入」。所有设置分成六个可以折叠的分区： 语音识别、语音交互、文本处理、语音合成、模型与下载、高级与诊断。 前五个默认展开，最后一个默认收起。改完记得点保存。
先记住两个总开关，它们互相独立：
| 开关 | 管什么 | 默认 |
|---|---|---|
| 语音模式（麦克风按钮） | 是否听你说话 | 关 |
| 朗读回复（设置里） | 是否念出助手的回复 | 关 |
5.1 语音识别
| 设置 | 做什么 | 怎么调 |
|---|---|---|
| 识别模型 | 用哪个模型认字 | 默认 SenseVoice，不用下载，中文效果好，会自动加标点和整理数字。想换看第 6 节 |
| 识别语言 | 提醒模型你说的是哪个语种 | 只有 SenseVoice 认这个设置，换别的模型时界面会说明。选「自动」就好，也可以固定成中文、英文、粤语、日文、韩文 |
| 实时字方式 | 说话时实时出字用哪种办法 | 「整段重识别」最准，句子长了会慢；「流式解码」快，稍不准，需要提前下载 Zipformer2 那一档；拿不准就选「自动」。说完之后的定稿始终用当前模型，不受这项影响 |
5.2 语音交互
| 设置 | 做什么 | 怎么调 |
|---|---|---|
| 交互模式 | 说完一段之后怎么办 | 「连续对话」：说完接着听，麦克风不关。「说完就关」：说完退出语音模式，这项要开着自动发送才有意义，关了自动发送时界面会禁用它 |
| 静音断句 | 静音多久算说完一句 | 默认 1500 毫秒。太短会把长句切段，太长回复来得慢 |
| 识别后自动发送 | 说完是否自动发出 | 开：停顿后自动发。关：文字只留在输入框，你自己按回车 |
| 发送前等待 | 说完后再等一会儿才发 | 默认 1200 毫秒，用来把连着说的短句并成一条、避免抢话。只在开了自动发送时生效 |
| 语音模式快捷键 | 开关语音模式的快捷键 | 默认 Alt+V，改完立刻生效；组合键不合法时不让保存，并会告诉你在哪不对 |
| 全局语音浮层 | 任意页面右下角常驻一个小麦克风，说话直接进当前会话，不经过输入框 | 默认关。打开后自动进入聆听或待机：设了唤醒词就要先喊唤醒词，没设就直接听。此时输入框的麦克风隐藏，Alt+V 也改成切换浮层 |
| 全局语音快捷键 | 在窗口里任意页面切换全局语音 | 默认 Ctrl+Alt+V，在 macOS 上 Cmd+Option+V 也能按 |
| 语音文本注入方式 | 说出来的字怎么送进会话 | 「排到下一轮」：助手空闲时就是发一条新消息。「插入下一步」：助手正在生成时插进当前这一步 |
| 唤醒词 | 待机时先说哪个词再接命令 | 默认「小鱼」，留空就是关掉唤醒词，回到「说话直接发送」。可以用竖线或逗号写几个别名，比如「小鱼|小渔|你好小鱼」。建议两到四个字：两个字的按同音字认（说成「小渔」也算唤醒），三个字以上允许一个字听不准 |
关于全局语音和唤醒词，还有几点要提前知道：
- 麦克风在待机时是常开的，系统会一直显示在录音，更耗电，也可能被误唤醒；不想这样就把唤醒词留空。
- 待机时听到的闲聊不会被发进会话，界面最多每 30 秒提示一次「听到了什么」。
- 唤醒之后 60 秒没再说话就自动回到待机，再说一次唤醒词即可。
- 唤醒词只管右下角的浮层，输入框的麦克风不受影响。
- 窗口被最小化或藏在后面时，语音不如前台稳定，这是浏览器的限制，不是坏了。
5.3 文本处理
| 设置 | 做什么 | 怎么调 |
|---|---|---|
| 清理语气词 | 去掉「嗯」「啊」「那个」这类口头禅 | 勾上就生效，只清理识别出来的字，不改你说的话 |
| 自定义词表 | 纠错词和热词 | 一行一条，写法见第 7 节 |
5.4 语音合成
这一区最上面会显示「当前朗读方式」，也就是正在用哪种引擎、哪个音色或模型。
| 设置 | 做什么 | 怎么调 |
|---|---|---|
| 朗读回复 | 总开关 | 勾上就念，不需要开语音模式。关掉时下面的设置仍然可以保存，只是不生效，方便先把参数配好 |
| 朗读追赶最新 | 助手生成得比念得快时，允许声音落后屏幕多少秒 | 默认 7.5 秒。超过就整段跳过旧内容，从最新的第三段接着念，不会从一段话中间开始。填 0 表示一段都不跳，长回复会越念越滞后 |
| 语音引擎 | 用哪种方式念 | 在线音质最好但要联网；本地神经模型离线且接近在线效果，需要下载约 170MB；系统语音最快但机器感重；GPT-SoVITS 用你自己跑的服务 |
| 朗读音色 | 哪个发音人 | 在线用微软的音色，系统语音用本机装的发音人，神经模型选说话人（只有一个说话人时这项会隐藏） |
| 朗读语速 | 快慢 | 默认快 10%，四种方式都能用 |
| 朗读音调 | 高低 | 只有在线方式支持 |
| 朗读音量 | 大小 | 在线和系统语音支持 |
| 音频格式 | 在线方式的音质档位 | 只有在线方式支持，默认的 24kHz/48kbps 够用，想要更好听选 96kbps |
| GPT-SoVITS 服务地址等几项 | 只在选了 GPT-SoVITS 时才用 | 见下面那段说明 |
用在线方式时，如果那一句话合成失败，会自动改用本机系统语音顶上，保证总有声音， 并在界面上提示一次这次是回退了。
关于 GPT-SoVITS：插件里没有内置这个引擎，也不做声音克隆。要用它，得你自己把
GPT-SoVITS 官方的接口服务跑起来，默认地址是 http://127.0.0.1:9880，
然后在这里填上服务端那台机器能读到的参考音频路径、参考音频里说的内容和语言。
插件只负责把每一句文字交给你的服务、把返回的声音放出来。它失败时不会偷偷改用别的引擎——
你选它就是想要自己的声音和自己的机器。
5.5 模型与下载
| 设置 | 做什么 | 怎么调 |
|---|---|---|
| 启用后预加载模型 | 选了模型就先在后台加载好 | 建议开着，第一次说话就不用干等。加载要多久跟模型大小和磁盘有关，界面不会承诺具体秒数。这项只管你当前用的识别模型和朗读模型，不管实时字用的那一个 |
| 空闲释放 | 模型闲置多久后从内存里放掉 | 默认 10 分钟，也可以选永不释放或 5、30、60 分钟。正在用的模型不会被释放 |
| 运行环境自检 | 检查这台机器上各种方式能不能用 | 点「重新检查」，看每一行的对错说明 |
模型会常驻内存（识别的 Zipformer2 约 160MB，神经朗读模型约 170MB）， 闲置释放是为了把内存还给系统。下面的模型列表负责下载和删除， 只有下载过的才会出现在「识别模型」的下拉里。
5.6 高级与诊断
这一区默认收起，放三个开关和一行状态，平时不用动。
| 设置 | 做什么 | 怎么调 |
|---|---|---|
| 允许 AI 操控界面 | 允许助手替你操作界面 | 默认关。必须同时打开「全局语音浮层」，因为动作由浮层执行 |
| 危险 UI 动作需要确认 | 会改动内容的操作先问你一下 | 默认开。切换会话、新建会话、执行命令、发消息、停止生成、替你点按钮或填字都会先弹确认；只看信息的不弹。你可以点「允许」「拒绝」，也可以直接说这两个词 |
| 系统级全局热键 | 窗口不在前台也能按快捷键唤起语音 | 默认关，同样要开着「全局语音浮层」。Windows 自带实现；macOS 要在「系统设置 → 隐私与安全性 → 辅助功能」里给 DSH 授权；Linux 要用 X11 桌面，Wayland 下一般不行 |
三个开关下面那行「系统级热键状态」只是告诉你现在到底是什么情况 （未开启、等待注册、已启用、失败以及失败原因），不需要也不能设置它。
让 AI 操作界面这件事的几条边界，值得知道：
- 它只能操作这个应用里面的界面。要跳到外部网页、打开文件选择框的点击会被拒绝， 密码框永远不让它代填。
- 它先要「看一眼」当前页面有哪些可以点、可以填的东西，再照着报回来的名字操作。 页面变了、隔太久再操作会失败，让它重新看一次就好。
- 同时开着好几个 DSH 窗口时，只有一个窗口会执行，不会把同一句话发出去两遍。
- 助手等一条操作结果是有时限的。等你按下「允许」时如果已经超时，这次就不执行了， 界面会告诉你动作已超时。
- 升级插件后需要重启一次 DSH，界面操作才会按新的方式生效。
6. 模型怎么选怎么下载
6.1 识别用的模型
| 模型 | 大小 | 中文效果 | 特点 | 适合谁 |
|---|---|---|---|---|
| SenseVoice | 已内置，需要时自动下载约 230MB | 好 | 带标点、会整理数字，零下载 | 大多数人 |
| Zipformer2 中文 | 160MB | 一般 | 反应最快，长句子不变慢，实时字用它 | 要说长句、要快 |
| Whisper tiny | 99MB | 差 | 最小 | 先跑通再说 |
| Whisper base | 153MB | 一般 | 轻量 | 中文勉强够用 |
| Whisper small | 358MB | 好 | 明显比 base 准 | 想均衡 |
| Whisper medium | 902MB | 很好 | 更准 | 重准确率 |
| Whisper large-v3-turbo | 989MB | 很好 | 接近最大档，体积小一半 | 综合最优 |
| Whisper large-v3 | 1.7GB | 最好 | 准确率天花板，也最慢 | 只要准 |
选择建议：默认那个 SenseVoice 就够，不用下载、中文好、带标点。 要实时出字更快选 Zipformer2，要更准就往上挑 Whisper 的大档，代价是体积和耗时。
6.2 朗读用的模型
本地神经模型只有一档：MeloTTS 中英，约 170MB，多说话人，完全离线，音质接近在线。
6.3 怎么下载
- 打开「设置 → 语音输入 → 模型与下载」。
- 在识别模型或合成模型列表里找到想要的，点下载。
- 看着进度走完，出现「已就绪」。
- 回到「语音识别」或「语音合成」，把它选成当前用的模型。
下载失败通常是网络访问不到模型源，国内会走镜像站。进度卡在 100% 不动一般是校验没过， 重试一次或者换个模型。
7. 自定义词表
用来处理同音字和专业名词，两种写法作用完全不同：
| 写法 | 作用 | 例子 |
|---|---|---|
正确=错误 | 替换：识别出「错误」时改成「正确」 | 深度求索=深度球搜 |
只写 正确 | 提示：不改文字，只让识别器更倾向认出这个词 | 专业术语 |
用法：打开「设置 → 语音输入 → 文本处理」，在「自定义词表」里一行写一条，保存。
注意：
- 中文按原字匹配；英文不分大小写，替换后保持原来的大小写样子。
- 「只写正确词」这种提示只有 Zipformer2 有效。用 SenseVoice 或 Whisper 时这类条目不起作用，
想改错字请用
=的写法。 - 最多 200 条，每条不超过 100 个字，空行会被忽略。
8. 遇到问题怎么办
按症状找对策。
8.1 看不到麦克风按钮
- 在终端执行
dsh plugin --profile desktop list，看列表里有没有这个插件。 - 到「设置 → 插件」确认启用列表里勾上了它。
- 重启 DSH。插件必须重启才会加载，刷新页面没用。
8.2 点麦克风没反应，或者提示麦克风被阻止
- 检查系统或浏览器有没有给 DSH 麦克风权限。
- 确认没有别的程序（会议软件之类）占着麦克风。
- 重试一次，还不行就重启 DSH。
8.3 能说话，但文字出不来，或者显示「没听清」
- 确认麦克风没静音、离得近、说得够清楚。
- 提示「加载模型…」时，等第一次加载完成再说。
- 到「模型与下载」确认当前选的那个模型是已就绪状态，没下载的先下载。
- 如果正在说的字突然整段消失，一般是识别模型被换掉或释放了，再说一次即可。 反复出现就照 8.6 看诊断。
8.4 字出来了，但同音字、专有名词错
8.5 没有声音，念得断断续续，或者把代码念出来了
没有声音，按这个顺序查：
- 「朗读回复」有没有勾上。
- 用的是哪种引擎：在线的要联网；系统语音要看本机有没有；本地神经模型要先下载。
- 到「模型与下载」点「运行环境自检」，看哪一行是红的以及它写的理由。
- 显示「朗读中」却完全没声，多半是自动回退到了在线方式而机器没联网。
念得断续、念到一半又回头念前面的情况：正常朗读是按自然段落一段一段往下走的， 遇到助手生成得特别快时会追赶最新内容，也就是整段跳过旧内容，这是设置里 「朗读追赶最新」在起作用，不是坏了。想一段都不跳就把它设成 0，代价是长回复越念越滞后。
代码块不会被念出来，列表前的「1. 2.」这类编号也不会单独念成「一、二」，这是有意设计的。
8.6 快捷键按了没反应
- 到设置里确认组合键写法（比如
Alt+V），看有没有被判定为不合法。 - 换一个组合键试试，有些被浏览器、输入法或别的程序占用了。
- 单个字母必须配 Ctrl、Alt 或 Windows/Cmd，只配 Shift 不算。
- 窗口不在前台时要生效，得打开「系统级全局热键」。打开后到「高级与诊断」里看 「系统级热键状态」那一行写的是什么：等待注册、已启用、还是失败以及失败的原因。 常见的失败原因是这个组合键已经被别的程序占了、macOS 没给辅助功能权限、 Linux 跑在 Wayland 上、或者安全软件拦下了插件启动的小助手进程。
8.7 全局语音没反应、唤醒词不灵
- 确认「全局语音浮层」是开着的并且保存过。关着时右下角的小麦克风根本不出现。
- 窗口里按键不灵：确认「全局语音快捷键」的组合，注意正在设置面板里录快捷键时不会触发。
- 界面显示「待机 · 说『小鱼』唤醒」时，必须先喊唤醒词再说命令。 唤醒词留空才是「说话直接发」。
- 喊了不醒：注意两个字的唤醒词是同音字都要对上（「小渔」算「小鱼」）， 三个字以上才允许一个字听不准。多备几个别名（用竖线分开）会明显提高命中率。
- 说了话但没送进会话：看浮层上有没有「没有当前会话」「发送失败」这类提示。 窗口藏在后面时识别不稳定是已知限制。
8.8 AI 不帮忙操作界面
- 「允许 AI 操控界面」默认是关的，打开并保存；同时要把「全局语音浮层」也打开， 两个开关缺一不可。
- 会改动内容的操作要先确认：没点「允许」（也没说「允许」）就不会执行。
- 让它点某个按钮或填某个框，要先让它看一眼当前页面；隔太久或页面已经变了会失败， 让它重新看一次。
- 想让它点页面外的东西、代填密码，这些是被拒绝的，不是故障。
- 升级插件后要重启一次 DSH。
9. 更深入的资料
这个仓库的文档分工是这样的：
| 文档 | 讲什么 | 给谁看 |
|---|---|---|
| 本文 | 怎么装、怎么用、每个设置怎么选 | 使用者 |
| docs/reference.md | 插件和 DSH 之间怎么通话：接口清单、消息格式、识别与朗读的完整过程、代码结构、配置之间的配合关系 | 要看接口和内部行为的人 |
| docs/maintainer-notes.md | 改这个插件要守的规矩、反复踩过的坑、改完怎么验证、怎么发布 | 维护者 |
| docs/architecture-modernization.md | 一轮一轮的架构改造记录，每批改了什么、为什么、怎么验的 | 想知道为什么长成现在这样 |
| docs/global-voice-ui-control.md | 全局语音与界面操控当初的可行性设计与落地过程 | 设计参考 |
| docs/highlight-read-aloud.md | 「正在念的那句怎么高亮」的调研与实现 | 设计参考 |
| docs/architecture-optimization.md · docs/environment-injection-design.md | 两份早期探索，多数结论已被后续改造取代，留着是为了别重新踩一遍 | 历史资料 |
许可：MIT。
Plugin correlati
dsh-web-ui (dsh-tool-describe-image)
zhu1090093659/dsh-web-ui
modlens
liustack/modlens
ipollowork
devin-axis/ipollowork
dsh-vision-router
ysr666/dsh-vision-router