npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

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

共享字段只有:

  • provider
  • activeProfileId
  • presetVoiceId
  • customVoiceId

输出目录、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 时脚本只做备份与配置行合并,包本身要在应用里装:

  1. 侧栏 插件 → 添加插件 → 本地目录: <本仓库路径> (或 file: tarball 规格),按提示重启应用;
  2. 或者让应用内的 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: 120

patch 按 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 = 包名)。五块:

  1. 当前音色 —— 激活档案 / provider 默认音色、试听句、试听
  2. 合成模型 —— 预置 / 设计 / 克隆三选一,参数区联动:
    • 预置:9 个 MiMo 音色 + 自定义 Voice ID、样本句、保存为档案
    • 设计:描述、候选数、样本句、生成候选 + 候选列表(试听 / 设为当前)、清空候选
    • 克隆:选择音频(mp3/wav ≤10MB)或填已存样本名、保存为档案
  3. 音色档案库 —— 播放 / 启用 / 重命名 / 复制 / 删除
  4. 输出 / 接口 —— 输出目录、格式、缓存、单次上限、provider、密钥来源 (复用 DSH 凭据 / 手动输入)、密钥输入、密钥类型、BaseURL 覆盖、测试连接
  5. 朗读 —— 自动朗读新回复(默认关)、跳过代码块、分段长度、语速; 每条助手回复的操作行另有一个扬声器按钮,可随时朗读/暂停

界面文案跟随 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-scripts

host 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。