语音对话练习 astr0mfly/dsh-voice-by-edge

🎙 dsh-voice-by-edge

npm version
npm downloads
license
stars

Awesome DSH Plugin

语音交流练习插件 · Voice practice mode for the DSH web app 中英文语言输出 + 对话中英文朗读（TTS）+ 语音输入（STT）

一个为 DSH Web 页面设计的插件：在对话框新增「语音交流」模式选项。开启后，模型会用目标语言以适合朗读的短句口语化回复，浏览器自动朗读对话内容（中英文分段选择对应语音），并支持麦克风语音输入直接发送——专为锻炼英文（或中文）听说能力设计。

A plugin for the DSH web page that adds a Voice Practice mode toggle to the composer. When enabled, the model replies in the target language with short, spoken-style sentences; the browser reads the conversation aloud (auto-detecting Chinese vs English segments and picking matching voices); and you can dictate replies with the microphone. Built for practicing English (or Chinese) speaking and listening.

✨ 功能 / Features

| 功能 | 说明 |
| 🎤 语音交流模式开关 | 输入栏工具行左侧的 🎤 按钮，按会话开启/关闭（conversation.input.left 插槽） |
| 🗣 控制条 | 开启后出现在输入框下方（conversation.composer.dock 插槽）：练习语言（English / 中文 / 自动）、麦克风、自动朗读、跟读回放、自动发送、语速、停止 |
| 🔊 逐条朗读 | 每条助手回复右侧的 🔊 按钮，点击即朗读该条（conversation.chat.assistant-actions 插槽） |
| 🌐 双语分段朗读 | 朗读时按句子自动识别中英文，分别用对应语音朗读（如英文回复 + 【译文】中文段落） |
| 🎙 语音输入（STT） | 浏览器 Web Speech API（Chrome / Edge），识别结果实时填入输入框，可自动发送；错误会分类提示（权限被拒 / 服务不可用 / 浏览器不支持） |
| 🧠 服务端提示词注入 | 开启模式的会话，系统提示词追加「语音练习模式」引导：用目标语言、短句口语化、无 markdown 表格/代码块、附【译文】与【提示】纠错 |

🔊 朗读引擎（TTS）

- 主引擎：Microsoft Edge 神经语音（edge-tts）。服务端通过 msedge-tts 连接 Edge Read-Aloud 服务合成 MP3（/voice-by-edge/api/tts），浏览器直接播放。英文默认 en-US-AriaNeural，中文默认 zh-CN-XiaoxiaoNeural，合成结果磁盘缓存于 ~/.dsh/cache/voice-by-edge/。
- 回退引擎：浏览器本地 speechSynthesis。Edge 服务不可达（断网/服务变更）时自动回退，保证朗读功能不失效。
- 语速 0.75×–1.5× 可调。

📦 安装 / Install

方式一：从 GitHub 安装（推荐，给其他用户）

钉住 commit 保证可复现（当前最新为 c2b51e1）：
dsh plugin --profile web add "github:astr0mfly/dsh-voice-by-edge#c2b51e1bc643687b4cbf53d4cc258a211ecf5f1b"
或打 tarball：
pnpm pack && dsh plugin --profile web add ./dsh-voice-by-edge-.tgz

首次安装需确认构建脚本：pnpm 11 默认拦截依赖的构建脚本，dsh plugin add 会在 ~/.dsh/profiles/web/pnpm-workspace.yaml 自动写入占位配置
allowBuilds: { msedge-tts: set this to true or false }——把它改成 true 后重新执行上面的 add 命令即可。
若安装报 ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: msedge-tts@2.0.7，就是这个步骤没完成。

方式二：本地链接安装（开发调试）

dsh plugin --profile web add H:\dsh_space\plugins\dsh-voice-by-edge
或者手工方式：把 "dsh-voice-by-edge": "link:H:\\dsh_space\\plugins\\dsh-voice-by-edge" 加入 ~/.dsh/profiles/web/package.json 的 dependencies，并在 dsh.profile.bundles 中加入 "dsh-voice-by-edge"，然后：markdown
cd ~/.dsh/profiles/web && pnpm install

安装后重启 DSH Web（bundle 插件重启生效）。可用 dsh --profile web --dump-config 验证 voice-by-edge 层已生效。

依赖说明：插件唯一的运行时依赖是 msedge-tts（npm registry），dsh plugin add 会自动安装；如手动 clone 开发，先在插件目录 pnpm install。安装过程使用 pnpm（DSH profile 默认），无需构建步骤。

⚙️ 配置 / Config

cordis.patch.yml（bundle 自带，也可在 profile 的 cordis.patch.yml 中按 id 覆盖）：

| Key | 默认 | 含义 |
| defaultTargetLang | en | 练习目标语言：en / zh / auto |
| practiceLevel | beginner | 难度：beginner / intermediate / advanced（影响提示词措辞） |
| includeTranslation | true | 回复后附一段【译文】对照翻译 |
| includeCorrection | true | 用户有语言错误时附一句【提示】温和纠错 |
| maxReplySentences | 3 | 要求模型回复控制在几句话内（1–8） |

客户端偏好（练习语言、语速、自动朗读、跟读回放、自动发送）保存在浏览器 localStorage（voice-by-edge.state），每个会话独立的开关状态也在其中。

🧩 架构 / Architecture

dsh-voice-by-edge/
├── package.json # bundle 清单（dsh.bundle.patch）+ 客户端清单（dsh.client） ├── cordis.patch.yml # 把插件行插入 host（config 可覆盖） ├── lib/index.js # 服务端：/voice-by-edge/api/mode + system-prompt/assemble 注入 └── client/client.js # 客户端（纯 JS 免构建）：TTS / STT / 插槽 UI

- 服务端（Cordis 插件）：维护每会话模式状态（内存）；system-prompt/assemble 瀑布中为开启模式的会话追加 voice-by-edge 提示词段落（order 210）；/voice-by-edge/api/mode 端点使用与 /api 网关相同的回环/受信 Host 校验。
- 客户端（window.__ModuleLoader__.load 注入）：三个插槽注册——conversation.input.left（开关）、conversation.composer.dock（控制条）、conversation.chat.assistant-actions（逐条朗读）；TTS/STT 全部走浏览器 Web Speech API，无外部依赖。

⚠️ 注意事项 / Notes

- 浏览器支持：朗读（edge-tts 不依赖浏览器语音）任何浏览器可用；语音输入（STT）需要 Chrome / Edge（基于 Web Speech API）。浏览器不支持时，麦克风按钮会显示 🚫 提示。
- STT 常见问题：点击麦克风无反应时，控制条会分类提示——① 地址栏🔒处允许麦克风权限；② Chrome 的语音识别依赖 Google 服务，网络受限时建议改用 Edge 浏览器（Azure 语音服务）。
- 语音输入需要用户手势：首次点击麦克风即授权；Chrome 下语音识别需要 HTTPS 或 localhost——DSH Web 默认 localhost 部署，满足条件。
- TTS 依赖网络：edge-tts 合成需要能访问微软 Edge 语音服务；不可达时自动回退浏览器本地语音。合成结果缓存于 ~/.dsh/cache/voice-by-edge/，重复朗读秒回。
- 自动朗读：仅在页面可见（visibilityState === 'visible'）且你未在录音时朗读新消息；开启模式的瞬间不会重读历史消息（有基线）。
- 安全：模式状态仅存于浏览器与服务端内存，不落盘会话日志；提示词注入只影响该会话的模型行为，不修改任何历史记录。TTS 语音白名单校验，防止任意语音/SSML 注入。
- 目前按会话内存记录，重启 DSH 后需重新开启模式（客户端开关状态仍保留，重开后自动同步）。

🛠 开发 / Development

客户端为纯 JS（client/client.js），无需构建；服务端为 ESM（lib/index.js）。改动后刷新页面即可看到客户端变化（HMR 可用时自动生效），服务端改动需重启 web 进程。服务端依赖 msedge-tts（已安装在插件目录 node_modules/，重新安装用 pnpm install）。

📄 License

MIT