dsh-breeze-tts

dsh-breeze-tts

BreezeBlue 语音，住进 DSH。 把文字合成为中文语音，在 DSH 里直接播放或导出； 再打开会话头左上角的小喇叭，助手每轮回复结束后就会自动念出来——默认用「大肥鱼（迷糊版）」的声音。

纯 JavaScript、零运行时依赖，宿主半侧 + Web 客户端半侧都由一个包提供； 通过 dsh-super-injector 注入，注入即生效，卸载即净。

---

功能一览

能力	说明
🔊 自动朗读	助手每轮回复完成（turn/end completed）后自动合成并播放，只念最终文本，不念思考/工具输出
🎚️ 会话头开关	顶部栏最左侧（会话标题左边）一个喇叭按钮，点一下开/关；新建会话、未发消息时也显示，不浮在内容上
🧠 朗读前处理	自动去掉代码块、图片、链接、Markdown、表格、HTML 后再念；超长按句末截断，默认上限 1000 字
⚡ 长轮询推送	开关打开后客户端阻塞等待服务端推送，合成一完成就播放，没有轮询间隔
🛠️ 三个工具	breeze_say 合成、breeze_voices 查音色、breeze_status 查 Key 与用量
🌐 HTTP 接口	/breeze-tts/audio、/synthesize、/preview、/pending、/wait、/auto，方便外部桥（如 QQ）接入
🎭 两款音色	迷糊版 voc_8yud7hz7c9q2（默认）、机灵版 voc_u3nxkd5578wc
💾 状态持久化	开关状态写入 ~/.dsh/breeze-tts/auto.json，重启 DSH 后保持

快速开始

1. 配置 API Key（三选一，推荐文件方式）：
   • 文件：把 brz_...（一行）写进 ~/.dsh/breeze-tts.key；
   • 环境变量：BREEZE_API_KEY；
   • DSH 凭据：在「设置 → 凭据」新建 BREEZE_API_KEY。
2. 确认连通：对助手说「用 breeze_status 检查一下语音服务」，应返回 keyStatus: active。
3. 注入并启用：dev_inject_plugin D:\ZD\HH\dsh-breeze-tts，或在插件管理器里启用（client 端会自动挂载）。
4. 刷新网页（Ctrl+R），会话头左上角会出现喇叭。
5. 开关：点一下开启（变浅蓝 + 脉冲），此后回复自动朗读；再点一下关闭并立即停止播放。

工具

breeze_say

把一段文字合成为语音，返回可播放 URL 与本地文件。

参数	必填	说明
text	✅	待合成文本，≤ 1000 字
voice		音色 ID 或别名：mihu/迷糊/迷糊版、jiling/机灵/机灵版
language		ISO 语言码，省略时按文本自动判断（中文 zh）
instructions		风格/情绪提示（BreezeBlue 支持时生效）
speed		语速 0.5–2，默认 1

返回含：ok、url（/breeze-tts/audio?id=...）、file（工作区副本路径）、cachedFile、bytes、format、mediaType、voiceId、language、chars、billableChars、credits、costUsd、elapsedMs、keySource。

breeze_voices

列出可用音色。参数 refresh（强制刷新，默认 false）、query（关键词过滤）。

breeze_status

查配置与连通性。参数 verify（是否调用 GET /v1/api-keys/current，默认 false）。 返回 Key 状态、剩余 credits、默认音色、音频目录、autoSpeak 开关状态与最近一次错误。

配置项

注入时可通过 loader 配置覆盖（均为可选）：

键	默认	说明
apiKeyRef	BREEZE_API_KEY	DSH 凭据引用名 / 环境变量名
apiKey	空	直接写 Key（不推荐，优先文件/凭据）
keyFile	~/.dsh/breeze-tts.key	自定义 Key 文件路径
baseUrl	https://api.breeze.blue	API 端点
voice	voc_8yud7hz7c9q2	默认音色（迷糊版）
format	mp3	输出格式：mp3/wav/flac/pcm/aac/opus 及 _24000 变体
modelId	空	显式指定模型；留空由服务端按语言选择
outputDir	assets/audio	工作区音频目录（相对当前工作目录）
organizeBySession	true	按会话分子目录
cacheDir	~/.dsh/breeze-tts/cache	音频缓存目录
autoSpeak	true	自动朗读总开关（客户端开关会覆盖）
autoSpeakMaxChars	1000	自动朗读文本上限（20–1000）
autoSpeakVoice	空	自动朗读单独音色；留空沿用 voice

HTTP 接口

所有路由同源于 DSH Web GUI（例：http://127.0.0.1:50892），默认只监听本机。

方法	路径	说明
GET/HEAD	/breeze-tts/audio?id=<32hex>.<ext>	播放/下载音频，支持 Range（206）
GET	/breeze-tts/auto	开关状态、最近事件、统计
POST	/breeze-tts/auto	{ "enabled": true } 即时生效并持久化
GET	/breeze-tts/pending?session=&since=	取新语音条目；不带 session = 全局
GET	/breeze-tts/wait?session=&since=&timeout=	长轮询，有新条目或超时返回；timeout 1000–30000
GET/POST	/breeze-tts/preview	{ text, sessionId } 立即合成并入队（调试用）
GET/POST	/breeze-tts/synthesize	通用合成接口，详见 QQ-INTEGRATION.md

示例：

# 开关
curl -X POST http://127.0.0.1:50892/breeze-tts/auto -H "content-type: application/json" -d '{"enabled":true}'

# 合成（默认迷糊版音色）
curl -X POST http://127.0.0.1:50892/breeze-tts/synthesize -H "content-type: application/json" \
  -d '{"text":"呜哇，被你发现啦！我在认真思考呢，才没有摸鱼。"}'

计费

按 BreezeBlue 规则：汉字每字计 2 个计费字符，1 credit = 10 计费字符，$3 / 10000 credits（≈ $0.0003/credit）。 一句 23 字的中文约 46 计费字符 ≈ 5 credits ≈ $0.0015。自动朗读只念最终回复，每条回复一次请求。

工作方式

助手回复完成 ──▶ 宿主监听 session/event ──▶ 文本清洗 ──▶ BreezeBlue 合成
                                              │
                                    缓存 ~/.dsh/breeze-tts/cache
                                              │
客户端开关打开 ──▶ GET /breeze-tts/wait ◀─────┘ 合成完成即推送 ──▶ WebAudio 顺序播放

• 自动朗读只在 turn/end 且 reason.kind === "completed" 时触发；同文本 60 秒内去重。
• 带工具调用的中间消息不念，只念最终文本；只写缓存、不往工作区复制音频。
• 开关是「全局」的：一个开关控制所有会话的自动朗读。

排障

现象	处理
缺少 BreezeBlue API Key	按「快速开始」配置 Key；~/.dsh/breeze-tts.key 权限建议 600
401 / 402 / 429	Key 无效、余额不足或被限流；用 breeze_status 核实
会话头没有喇叭	刷新网页（Ctrl+R）；确认插件在插件管理器里已启用
有按钮但不出声	先点一下页面任意处（浏览器要求用户手势解锁音频），再看 /breeze-tts/auto 的 lastError
语音比文字慢几秒	正常：延迟主要是云端合成（约 3 秒），不是轮询

回滚与卸载

• 临时停用：点灭会话头喇叭（立即静音，状态持久化）。
• 停止自动朗读：把配置 autoSpeak 设为 false。
• 彻底卸载：dev_uninject_plugin dsh-breeze-tts，并删除 C:\Users\<你>\.dsh\profiles\desktop\node_modules\@dsh-external\dsh-breeze-tts 这个 junction 即可（缓存目录可留可删）。

开发说明

• 宿主入口 lib/index.js，客户端入口 lib/client.js（window.__ModuleLoader__.load factory 形式，无需构建）。
• package.json 里 dsh.client = { platform: "web", inject: [] } 是 DSH 客户端插件约定。
• 注入器对 client bundle 有骨架校验（KNOWN_SLOTS + register({ name: ... }) 相邻写法）； 注册到不在白名单里的插槽会被判定为坏骨架，需先在注入器里补白名单。
• 注入器目前把 junction 建在 profiles/web，而桌面版宿主跑 profiles/desktop； 若注入后 [no-fiber]，补一条 desktop profile 的 junction 即可（本插件已补）。

许可

BSD-3-Clause。音色与语音服务由 BreezeBlue 提供，使用需遵守其服务条款。