dsh-voice-by-edge

Readme

# 🎙 dsh-voice-by-edge

<!-- npm badges light up once the package is published to npm; until then they
     show "not found" — GitHub stars/license badges work immediately. -->
![npm version](https://img.shields.io/npm/v/dsh-voice-by-edge?label=npm&color=blue)
![npm downloads](https://img.shields.io/npm/dm/dsh-voice-by-edge)
![license](https://img.shields.io/github/license/astr0mfly/dsh-voice-by-edge)
![stars](https://img.shields.io/github/stars/astr0mfly/dsh-voice-by-edge?style=social)

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

> 语音交流练习插件 · 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 安装（推荐，给其他用户）**

```sh
# 钉住 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-<version>.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`，就是这个步骤没完成。

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

```sh
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"，然后：
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