dsh-whale-tts
v0.6.1
Published
Provider-agnostic text-to-speech tools for DeepSeek Harness agents: local audio files, voice profiles, and a settings card.
Maintainers
Readme
dsh-whale-tts
这声音是育木的小鲸鱼的。
(这句话是我养的鱼要求加上的。)
简短介绍(默认):README.md · English: README.en.md
给 DeepSeek Harness Agent 用的、与厂商无关的语音合成插件。
插件只做一件事:把文本变成本地音频文件并返回路径。它不播放、不发送、不上传音频——文件怎么用由消费方决定(QQ 桥接、视频流水线、播放器……)。
- 三个模型可见工具:
tts_synthesize、tts_list_voices、tts_status - 九个 provider:
openai-compatible、mimo、siliconflow、sapi、minimax、qwen、doubao、deepseek、qwen-local - 音色档案:预置 / 克隆 / 设计三类,最多 50 套
- 设置卡(中英双语,位于 DSH「插件」页)
- 密钥存 DSH 凭据库,插件只保存引用名,任何返回值都不含明文
DeepSeek 官方 TTS(0.6.0)
0.6.0 把 DeepSeek 官方语音合成直接接成内置 provider,不需要额外网关。
- provider id:
deepseek - 接口:
POST https://api.deepseek.com/v1/tools/tts,整段 HTTP、流式返回音频 - 音色:
stella(默认女声)、tide(男声) - 输出:WAV;PCM 和 WebSocket 实时流式暂未接入
- 凭据:
DEEPSEEK_API_KEY(DSH 凭据库已有可直接复用) - 配置:
filterMarkdown映射filter_markdown,默认true - 限制:单次 10,000 计费字符、请求体 64 KiB、音频最长 30 分钟;汉字按 2 字符计费,不支持语速调节
- 失败:400 内容风险 →
content-filter;429 →rate-limit;503/504 → 可重试;中途断流/截断 → 失败,不会落半截文件
provider: deepseek
providers:
deepseek:
enabled: true
apiKeyEnv: DEEPSEEK_API_KEY
voice: stella
format: wav
filterMarkdown: true调用:
tts_synthesize(text="你好,我是育木的小鲸鱼。", provider="deepseek")完整的 HTTP/WebSocket 协议、错误码、计费和实现边界见 docs/tts-apis/deepseek-tts.md。
跨 profile 同步(desktop / qqbot)
0.6.1 起,provider 和当前音色只在一处设置:两个 profile 都会读取同一个共享文件。
<DSH_HOME>/whale-tts/shared-control.json共享字段只有:
provideractiveProfileIdpresetVoiceIdcustomVoiceId
输出目录、maxChars、缓存、fallback、密钥仍按 profile 各自保留。QQBot 每次合成会重新读取共享文件,所以 desktop 设置卡切换后不需要重启 qqbot;反过来 qqbot 的设置卡改了,desktop 也会跟上。
如果不想共享,在某个 profile 的插件配置里设:
sharedControl:
enabled: false该 profile 就只用自己的 cordis.patch.yml。
运行要求
| 要求 | 说明 |
|---|---|
| DeepSeek Harness >= 0.2.1-rc.4 < 0.3.0-0 | 安装时检查 engines.dsh |
| Node.js >= 24.9 | DSH 运行时要求 |
| profile 含 @deepseek-ai/dsh-base | 它挂 @deepseek-ai/dsh-tools(ctx.tools);内置 profile 都有 |
| Web profile(设置卡需要) | headless profile 仍可用工具、改 YAML 配置 |
早期方案里提到的
dsh-tool-executor-native包在 DSH 0.2.1 里不存在;@deepseek-ai/dsh-base已挂载dsh-tools与dsh-agent-loop,插件所需仅此而已。
安装
tarball(本地/离线推荐)
npm pack
dsh plugin --profile <profile> add file:/绝对路径/dsh-whale-tts-0.6.1.tgz
dsh --profile <profile> --dump-config | grep dsh-whale-tts # 应出现本包层包声明了 dsh.bundle.patch,dsh plugin add 会自动把依赖装进 profile 并追加到
dsh.profile.bundles。装完重启 DSH。
npm
已发布到 npm(当前 latest 为 0.6.0):
dsh plugin --profile <profile> add dsh-whale-tts本地目录(开发态)
dsh plugin --profile <profile> add "link:/绝对路径/dsh-whale-tts" # 本仓库CLI 管理的 profile 一键安装
一键安装脚本在 QQBot 宿主仓库里(不在本插件仓库);它会:备份 profile → 构建 → npm pack
→ dsh plugin add → 合并配置行 → --dump-config 校验:
powershell -ExecutionPolicy Bypass -File tools\install-whale-tts.ps1 # 默认 qqbot
powershell -ExecutionPolicy Bypass -File tools\install-whale-tts.ps1 -Profiles desktop
powershell -ExecutionPolicy Bypass -File tools\install-whale-tts.ps1 -Rollback # 回滚desktop profile 不能从 CLI 安装:DSH 把它保留给 Electron 应用
(error: profile "desktop" is managed exclusively by the Electron application)。
所以 -Profiles desktop 时脚本只做备份与配置行合并,包本身要在应用里装:
- 侧栏 插件 → 添加插件 → 本地目录:
<本仓库路径>(或file:tarball 规格),按提示重启应用; - 或者让应用内的 Agent 通过插件管理器安装 tarball。
-Rollback 会恢复备份的 package.json / cordis.patch.yml;desktop 的包仍需在插件页卸载。
配置
配置写在 profile 的 cordis.patch.yml,按 id 覆盖 bundle 自带的默认行:
- id: whale-tts
name: dsh-whale-tts
config:
provider: mimo
fallback: [sapi]
providers:
mimo:
enabled: true
apiKeyEnv: MIMO_API_KEY
model: mimo-v2.5-tts
designModel: mimo-v2.5-tts-voicedesign
cloneModel: mimo-v2.5-tts-voiceclone
voice: 苏打
format: wav
timeoutMs: 20000
sapi:
enabled: true
output:
dir: 'D:\tts-audio'
cache:
enabled: true
dir: 'D:\tts-audio\.cache'
limits:
maxChars: 120patch 按 id 覆盖整行 config,不做深合并。 覆盖时必须重述你要依赖的每个键;
providers字典整体替换默认值,省略的 provider/字段会回退到适配器默认值。
全部可调项(字段、默认值、含义)见英文 README 的「All configuration keys」表。 所有字段都是 volatile:设置卡修改后热生效,不重挂插件。
路径模板支持 ${DSH_HOME}、${HOME}、${USERPROFILE}、${TMP}、${TEMP},展开后必须是绝对路径。
Provider
| id | 协议 | 密钥 | 格式 | 设计/克隆 |
|---|---|---|---|---|
| openai-compatible | POST {baseURL}/audio/speech(Bearer,原始字节) | 需要 | mp3、wav | 否 |
| mimo | POST {baseURL}/chat/completions(api-key 头,base64 音频) | 需要 | wav、mp3 | 是 / 是 |
| siliconflow | POST {baseURL}/audio/speech(OpenAI 兼容,Bearer,原始字节) | 需要 | mp3、wav | 否 |
| sapi | 本机 PowerShell System.Speech,断网可用 | 不需要 | wav | 否 |
| minimax | POST {baseURL}/t2a_v2(Bearer,hex 音频) | 需要 | mp3、wav | 否 |
| qwen | DashScope qwen3-tts-flash:POST → 下载 24h 音频 URL(Bearer) | 需要 | wav | 否 |
| doubao | 豆包 V3 SSE:POST {baseURL}/tts/unidirectional/sse,base64 音频帧 | 需要 | mp3 | 否 |
| deepseek | DeepSeek 官方 TTS:POST /v1/tools/tts,流式 WAV | 需要 | wav | 否 |
| qwen-local | 本地 Qwen3-TTS 服务:POST {baseURL}/audio/speech(OpenAI 兼容,raw 音频) | 可选 | wav、mp3 | 暂不支持 |
回退链:
主 provider
├─ 校验类错误 → 直接失败(不重试、不回退)
├─ 可重试错误(超时/网络/429/5xx)→ 按 retry 重试,仍失败则回退
├─ 鉴权/余额/内容过滤 → 直接回退
└─ 成功 → 返回
回退按 fallback 顺序;禁用/平台不符/未知 provider 跳过;全失败时聚合报错并列出每家的原因。更细的请求/响应与自建网关配置见 docs/providers.md、docs/self-hosting.md。
本地 Qwen3-TTS 的部署、配置和限制见 docs/qwen-local.md。
音色档案
三类,同一时刻只有一套「激活档案」:
| 类型 | 存什么 | 能直接合成 | 合成时怎么用 |
|---|---|---|---|
| preset | presetVoiceId | 能 | provider 语音模型 + 预置音色 |
| clone | voices/ 里的参考音频 | 能 | provider 克隆模型 + data: URL 样本 |
| design | 描述 + 候选历史 | 不能(工坊记录) | 生成候选,选定后固化为 clone 档案 |
存储布局:
$DSH_HOME/whale-tts/
├── voices.json # { version: 1, activeProfileId, profiles[] }
├── voices/<file> # 克隆样本(wav/mp3)
├── design/<file> # 设计候选(临时)
├── preview/<file> # 设置卡试听文件(自动清理)
└── .cache/ # 合成缓存(未显式配 cache.dir 时)上限:≤50 套档案、单个样本 ≤10MB。删除档案会同时删样本文件,激活档案被删后回退默认音色。
声音设计走 A 方案:描述 → 生成 2~5 条候选 → 试听 → 选定固化成 clone 档案; 插件不会「每句按描述现场设计」(那样音色会飘)。
密钥
插件只存引用名,不存密钥值:
providers:
mimo:
apiKeyEnv: MIMO_API_KEY # 或填 XIAOMI_TOKEN_PLAN_CN_API_KEY 复用 DSH 已有凭据解析顺序(经 ctx.credentials,缺失时兜底 process.env):DSH 凭据库
($DSH_HOME/.credentials.yaml)→ 启动环境 → 项目 .env → $DSH_HOME/.env。
设置卡通过 ctx.credentials.set() 写入密钥,之后只显示「已配置 / 未配置」:
不回显、不显示尾号、不进日志、不进错误信息、不进工具返回值、不进浏览器 bundle。
密钥类型(小米 MiMo,识别只在 host 侧,只有类型字符串出 host):
| 前缀 | 类型 | 默认 BaseURL |
|---|---|---|
| sk- | 按量付费 | https://api.xiaomimimo.com/v1 |
| tp- | Token Plan | https://token-plan-cn.xiaomimimo.com/v1 |
| ttp- | Token Plan 团队版 | https://token-plan-cn.xiaomimimo.com/v1 |
| 其它 | 自定义 | provider 的 baseURL |
安全边界(如实说明):DSH 把凭据存 $DSH_HOME/.credentials.yaml(目录 0700、
文件 0600)。这是文件权限,不是加密——挡得住别的系统用户,挡不住同用户下的
工具调用。想更严格就用启动环境变量注入,不落凭据库。
工具
tts_synthesize
参数:text(必填)、provider、voice、format(wav/mp3)、style、filename。
返回(规范 JSON 值):
{
"ok": true,
"path": "E:\\…\\audio\\tts-20261031-221500-a1b2c3.wav",
"relativePath": "tts-20261031-221500-a1b2c3.wav",
"file": "tts-20261031-221500-a1b2c3.wav",
"format": "wav",
"provider": "mimo",
"voice": "苏打",
"cached": false,
"bytes": 482133,
"elapsedMs": 1830
}三个路径字段对应不同消费方:path 绝对路径;relativePath 相对 output.dir
(POSIX 分隔符,消费方只接受库内文件时用它);file 纯文件名。命中缓存返回
cached: true;若 cache.dir 是 output.dir 的子目录,相对路径可能带该子目录,
否则关掉缓存。
tts_list_voices
返回 { providers: [{ id, capabilities, voices }], profiles, activeProfileId },不联网、不读密钥。
tts_status
返回 provider / 回退链 / 各 provider 的 configured、keyRequired、keyConfigured、
keyType、available、model、voice、baseURL、lastError,以及激活音色、
缓存、输出目录、平台。不含密钥、不含文本,排障先跑它。
返回里新增 preflight(可选):
{
"preflight": {
"exists": true,
"writable": true,
"looksLikeQqbotAudio": true
}
}looksLikeQqbotAudio 只表示路径形如 <qq-bridge>/audio,是给 QQBot 接入的提示,
不是硬性校验;warning 会写清不可写或路径形态可疑的原因。
输出接口(v1)
本插件只生成音频文件并返回路径,不播放、不发送、不上传。其他机器人接入时只需要 依赖下面这组字段,不要依赖设置卡内部 RPC。
tts_synthesize 成功返回:
{
"ok": true,
"path": "E:\\…\\audio\\tts-20261109-001122-a1b2c3.wav",
"relativePath": "tts-20261109-001122-a1b2c3.wav",
"file": "tts-20261109-001122-a1b2c3.wav",
"format": "wav",
"provider": "mimo",
"voice": "苏打",
"cached": false,
"bytes": 482133,
"elapsedMs": 1830
}路径语义:
| 字段 | 用途 |
| --- | --- |
| path | 绝对路径;本机消费/调试 |
| relativePath | 相对 output.dir,POSIX 分隔符;QQBot qq_send_voice 用这个 |
| file | 纯文件名;日志/展示 |
其他约定:
format只有wav/mp3;provider 不支持时回退到其支持格式;- 调用方拥有文件;插件不会因下一次合成删除旧文件;
- QQBot 场景要把
output.dir配到qq-bridge/audio,否则relativePath会被qq_send_voice拒绝; - 失败按工具错误处理;设置卡 RPC 用稳定
tts/...code,不要按错误消息分支; - 当前没有公开 HTTP
/tts/v1/*接口;HTTP facade 在 P4,其他机器人现在通过 DSH agent 工具调用。
完整字段表、tts_list_voices / tts_status 结构、错误码和接入 checklist:
docs/interface-v1.md。
设置卡
client half 注册在 DSH 「插件」页的 dsh-whale-tts 包下
(plugins.bundle.config,key = 包名)。五块:
- 当前音色 —— 激活档案 / provider 默认音色、试听句、试听
- 合成模型 —— 预置 / 设计 / 克隆三选一,参数区联动:
- 预置:9 个 MiMo 音色 + 自定义 Voice ID、样本句、保存为档案
- 设计:描述、候选数、样本句、生成候选 + 候选列表(试听 / 设为当前)、清空候选
- 克隆:选择音频(mp3/wav ≤10MB)或填已存样本名、保存为档案
- 音色档案库 —— 播放 / 启用 / 重命名 / 复制 / 删除
- 输出 / 接口 —— 输出目录、格式、缓存、单次上限、provider、密钥来源 (复用 DSH 凭据 / 手动输入)、密钥输入、密钥类型、BaseURL 覆盖、测试连接
- 朗读 —— 自动朗读新回复(默认关)、跳过代码块、分段长度、语速; 每条助手回复的操作行另有一个扬声器按钮,可随时朗读/暂停
界面文案跟随 DSH 界面语言(内嵌中英词典)。
朗读
每条已完成的助手回复在操作行(复制/记忆同一行)有一个播放按钮:
- 点击用当前激活音色朗读;再点暂停/继续;播放另一条时会自动停掉上一条。
- 长回复按句切段,逐段合成播放,并预取下一段;播放/暂停状态直接反映在按钮上。
- 设置卡「朗读」区可以开自动朗读(默认关,一轮只读最后一条带正文的回复)、跳过围栏代码块、设置分段长度和语速。
- 行内代码会按词语读出来(路径、下划线、连字符转空格);围栏代码块、URL 和超过 120 字的片段不读。
- 浏览器拦截自动播放时,按钮会停在待点击状态,点一下即可。
开发
cd dsh-whale-tts
npm ci --ignore-scripts # 沙箱环境:安装脚本需要 spawn
npm run build # tsc(host)+ rollup(client)
npm run typecheck # host + client
node --test --test-isolation=none test/ # 单测
node scripts/smoke.mjs # 离线管线 smoke(不联网)
npm pack --dry-run --ignore-scriptshost half 用 tsc 按文件编译到 lib/(含 .d.ts);browser half 用 Rollup + Sucrase
打成 DSH 从 /plugins 加载的 lazy-CJS factory。两者都是纯 JS 工具链——刻意不用
原生 esbuild,因为它要 spawn 子进程。
已知限制
- 不做唱歌:能力表保留
singing字段,但工具没有mode参数、不注册 sing 工具。 minimax为非流式实现:走POST /t2a_v2的 hex 音频;流式、克隆和设计暂未接入。- 不做每句现设计:设计是一次性造声,产物固化为克隆档案。
- 设置卡在「插件」页,不在「设置」页:DSH 0.2.1 的插件配置页迁到了侧栏插件页,
原方案里的
settings.plugin.item槽在 0.2.1-rc.5 不存在。 - 设置卡需要 Web profile;headless profile 仍有工具、配置走 YAML。
- 试听/音频经连接 RPC 以 base64 传输:超大参考样本会让预览负载变大(受 10MB 样本上限约束)。
与方案的实现偏差
| 方案 | 实现 | 原因 |
|---|---|---|
| 设置卡注册 settings.plugin.item | plugins.bundle.config(key = 包名) | 该槽在 DSH 0.2.1-rc.5 不存在;插件配置页已迁到 dsh-client-ui-plugin-manager |
| TypertRemoteService + @Remote 作为卡片通信 | DSH connection RPC 通道(host ctx.connection.rpc.handle / client rpc.call) | 仓库外包无法生成 ctx.remote 需要的严格 client codec;RPC 通道在本机同版本有生产先例(dsh-mnemon),且由 DSH Connection 统一鉴权 |
| Config 字段 .volatile() | 辅助函数优先 .volatile(),否则 .extra('volatile', true) | ^3.18.1 可能解析到没有该语法糖的 schemastery |
| client bundle 用 esbuild 构建 | Rollup + Sucrase | 原生 esbuild 要 spawn 二进制,受限沙箱拒绝;产物格式一致 |
| host 源码用 esbuild 打包 | tsc 按文件编译到 lib/(含 .d.ts) | host 不需要打包,且能顺带产出类型 |
| sapi 脚本放 src/scripts/sapi.ps1 | scripts/sapi.ps1 | tsc 不复制资源;随包分发在 lib/ 旁边 |
| 凭据优先级「env > 凭据文件」 | 按 0.2.1 实际语义:凭据库 > 启动环境 > 项目 .env > 用户 .env;服务缺失时才兜底 process.env | 0.2.1 改为 stored 可写且优先 |
| profile 必须含 dsh-tool-executor-native | 改为 @deepseek-ai/dsh-base | 该包在 0.2.1 不存在 |
许可证
MIT,见 LICENSE。
