dsh-ds-tts

ds-tts · 用 DeepSeek 官方朗读音色朗读 / 导出 / 接口化

English: A DSH plugin that reads assistant messages aloud with DeepSeek's official TTS voices, exports audio files, and exposes a text-in/audio-out HTTP API.

在 DSH Web GUI 里用 DeepSeek 官方朗读音色朗读对话、导出音频，并提供「文本进、音频出」的接口与工具。

• 🔊 每条助手消息可一键朗读（DS 官方音色：贝壳 mira / 白浪 echo / 海星 stella / 暗潮 tide）
• ⟳ 每条消息可重新生成：DS 每次合成的声音可能不同，缓存会让同文本秒回同一版，所以需要显式再要一版
• ⤓ 导出为音频文件下载，或存进当前会话工作区 .dsh/tts/
• 输入框旁的朗读入口：粘贴任意文本即可播放 / 重新生成 / 下载 / 存盘
• HTTP 接口 POST /api/ds-tts/synthesize：文本进、音频 URL 与文件出（命令行示例见 scripts/tts-call.mjs）
• 三个模型可见工具：tts_speak / tts_voices / tts_status

它和「本地 TTS 引擎」不是一回事：声音是 DS 账号里的，所以要有 DS 账号；代价是文本得先在 DS 那边走一趟（见下面 30 秒说明）。换来的是不用装模型、不占显存、不调参的官方音色。

效果实拍：输入框旁的朗读入口 —— 粘贴任意文本 → 选音色 / 投递模式 → 朗读 / 重新生成 / 下载 / 存到工作区。图里是填好 42 字待朗读的状态。 ⚠️ 这张只拍到了面板：本机 浏览器未连通（专用浏览器没起来），所以没有合成出音频、也没拍到播放器。朗读流程的可信证据仍是下面的终端实录。

---

目录

---

快速开始

前置条件（缺一个就跑不起来，先说清楚）：

1. 一个能用的 DSH 安装（本插件是 DSH 插件，不是独立程序）；
2. 一个 chat.deepseek.com 账号 —— 朗读音色是 DS 账号级功能，没账号没有音色；
3. 本机有 Edge 或 Chrome（src/browser/page.ts 会自动探测，探测的是 Windows 路径）。

# 1) 生成本包不提交的构建产物 lib/（.gitignore 忽略了 node_modules/ 与 lib/）
pnpm install && npm run link-sdk && npm run build

# 2) 把本包链接进你的 profile（dsh plugin 会把参数转交给 profile 目录里的 pnpm）
dsh plugin --profile web add link:/abs/path/to/dsh-ds-tts

# 3) 在 profile 的 cordis.patch.yml 追加一行（与其它第三方插件同款）
#    - insert:
#        - id: ds-tts
#          name: ds-tts

# 4) 重启并刷新
dsh web

第 2 步之后 cordis.patch.yml 通常已被自动并入，但手写 profile 时需要自己补那一行—— 装配行的 id 必须等于包名（ds-tts），这是客户端 bundle 的加载契约。

跑起来之后：

1. 重启 dsh web（宿主半与客户端 bundle 都只在启动时装载），刷新页面；
2. 第一次朗读会自动拉起一个专用浏览器（$DSH_HOME/ds-tts/browser，端口 9222）—— 在这个窗口里登录一次 chat.deepseek.com（之后全自动）；
3. 点任意助手消息下的 🔊。首次要等投递 + 合成（数秒到数十秒），相同文本第二次秒回（内容寻址缓存）。

不想点界面？直接打接口（下一节）。

---

它是怎么工作的（以及为什么必须这样）

30 秒版（人话）

DS 官方的朗读接口不接正文。它只认一个 message_id —— 也就是"读你自己 DS 会话里的哪条消息"。

所以"我想读这段文字"这句话，在 DS 那边没有直接的表达方式。ds-tts 的绕法只有一条： 先想办法把这段文字变成 DS 会话里的一条消息，再让官方接口去读那条消息。

"把文字变成一条消息"需要调 DS 的对话接口，而那要过 PoW 计算 + Cloudflare + 浏览器 TLS 指纹三道关。 这三道关我们一道都不碰 —— 交给一个真实的浏览器去做（页面自己就会算、就有指纹）。

于是整件事被切成两半：

一句话：用真浏览器解决"进不去"的问题，用 Node 解决"读得到"的问题。

机制细节（作者原文，一字未改）

DS 官方朗读的合成协议是：

POST /api/v0/auth/ticket {scope:"tts"}        → 一次性 ticket（600s，只能用一次）
wss  /api/v0/chat/tts/?chat_session_id=..&message_id=..&ticket=..&mode=manual&format=pcm|opus

请求里没有正文参数 —— 读哪段文字由服务端从你自己 DS 会话的消息里取。所以：

投递方式（实测结论决定了默认值）：

DS 官方 TTS 只接受「助手消息」。 对同一条会话实测：助手消息 code 0 / success（627 帧 / 3,009,162 字节 / pcm / 62.69 秒），用户消息返回 code 6 / no_content（0 帧）。 也就是说 user 模式在当前服务端行为下不可能成功，唯一可行的是 echo。因此 mode 默认是 echo，不是 auto —— 默认 auto 会先试一次 user：白跑一轮，而且那条投递出去的用户消息会永久留在你的会话里。

• echo（默认）：投递一条「请原样输出以下文本，不要添加解释或格式」的用户消息 → DS 模型写回助手回复 → 朗读那条助手回复。这是"任意文本也想用 DS 官方音色"的固有代价：文本要先在 DS 那边被复述一遍（消耗一次网页端模型回复，并留下会话消息）。
• user：只试用户消息（实测返回 no_content），保留给"将来 DS 支持用户消息时"用。
• auto：先试 user 再降级 echo，用于自我发现；已知不可用时直接走 echo。

echoVerify（默认开）会校验取到的正文确实包含原文的首尾；拿不到正文时自动跳过校验，拿到但不一致则失败（宁可报错，也不静默朗读错内容）。长文本更容易在复述时走样 —— 报错信息会建议调小 maxChars 分段。

为什么音频 URL 要带 ?v=

音频路由的响应头是 cache-control: public, max-age=31536000, immutable，而路径是按内容哈希固定的（<textHash>.wav）。重新生成会覆盖同一个文件 —— 如果 URL 不变，浏览器会一直从自己的 HTTP 缓存里给你旧音频，让人以为"重新生成没生效"。

所以版本令牌（DS 侧每次合成唯一的 audio_id，缺失时退到写入时间）进 URL：同一版 URL 稳定（缓存照旧有效），新一版 URL 必变（浏览器必然取新字节）。一个文本一个槽位、永远保留最新一版；想保留历史版本需要改成 hash+nonce 独立文件 + 清理策略（当前刻意没做，避免磁盘随点击次数无界增长）。

---

安全约定

这个插件要驱动你的浏览器、碰你的 DS 账号、能写你的工作区，所以边界必须写在明面上。

两条必须知道的副作用（不是漏洞，是设计）：

1. POST /api/ds-tts/voice 改的是你 DS 账号的音色 —— 官方「朗读音色」是账号级设置， 点「同步到 DS 账号」会同时改写你 DS 账号里的音色。
2. echo 模式会在你的 DS 账号里留下消息 —— 每条待读文本都会投递进专用会话， 并消耗一次网页端模型回复。会话过长时用设置里的「重建朗读会话」。

---

已验证（实测记录，不是"应该能跑"）

本次复核（2026-10-07，README 改写时新跑的 —— 与上表是两批数据）

上表是仓库作者的记录；下面是本次改写 README 时在隔离实例上真跑出来的，两批不要混着读。

环境：lab profile（本机 127.0.0.1:3081，非主实例 3080），插件已装为 ds-tts； D:/developing/DSH-plugin/ds-tts 与本仓库的 src/engine.ts sha256 一致（4BB6B01A…A93D4）， 即打 3081 等于打本仓库这份代码。

① 环境自查 —— node scripts/tts-call.mjs --status --base http://127.0.0.1:3081（节选）：

{
  "ok": true,
  "browser": {
    "connected": true,
    "cdpUrl": "http://127.0.0.1:9222",
    "browserVersion": "Edg/154.0.4258.53",
    "pageUrl": "https://chat.deepseek.com/",
    "launched": true,
    "lastError": ""
  },
  "ds": {
    "pageFound": true,
    "loggedIn": true,
    "allowed": true,
    "lastProbe": { "code": 0, "msg": "可用，检测到 4 个音色", "at": 1789401649853 },
    "userModeSupported": null,
    "chatSessionId": "ff668a51-c858-4b08-8158-ecf2c4080f7f"
  },
  "queue": { "pending": 0, "active": false },
  "cache": { "files": 39, "bytes": 35212884, "hits": 0, "misses": 0 },
  "config": { "voice": "mira", "format": "pcm", "mode": "echo", "maxChars": 2000,
              "cdpPort": 9222, "autoLaunch": true, "echoVerify": true, "timeoutMs": 120000 }
}

--status 不会触发浏览器自启（它只读状态），所以这条命令可以随时跑。

② 真合成一次（这是"文本进、音频出"的最小验证）：

$ node scripts/tts-call.mjs "README 实测：这是 ds-tts 命令行调用的一次真实合成。" --base http://127.0.0.1:3081
ok  wav  272.0 KB  5.8 秒  新合成
音色 mira  模式 echo  版本 cf94d3a0-f12c-4155-a1bc-a463e3d61cee
url  http://127.0.0.1:3081/api/ds-tts/audio/74f853beeef85471.wav?v=cf94d3a0-f12c-4155-a1bc-a463e3d61cee

③ 同文本再跑一次 → 缓存命中（版本与路径都不变，说明内容寻址缓存真的在生效）：

$ node scripts/tts-call.mjs "README 实测：这是 ds-tts 命令行调用的一次真实合成。" --base http://127.0.0.1:3081
ok  wav  272.0 KB  5.8 秒  缓存命中
音色 mira  模式 echo  版本 cf94d3a0-f12c-4155-a1bc-a463e3d61cee
url  http://127.0.0.1:3081/api/ds-tts/audio/74f853beeef85471.wav?v=cf94d3a0-f12c-4155-a1bc-a463e3d61cee

④ 落盘 + 文件真伪（--out，写到临时目录）：

$ node scripts/tts-call.mjs "缓存命中也应该能落盘。" --out <临时目录>/out.wav --base http://127.0.0.1:3081
ok  wav  111.6 KB  2.4 秒  新合成
音色 mira  模式 echo  版本 b3f7f82e-dc7a-4763-9f90-5b6c85863240
url  http://127.0.0.1:3081/api/ds-tts/audio/1802f64a7c187ab8.wav?v=b3f7f82e-dc7a-4763-9f90-5b6c85863240
写出 <临时目录>\out.wav

文件大小 114266 B
前 12 字节 52 49 46 46 52 BE 01 00 57 41 56 45   → "RIFF" + "WAVE"

⑤ --regen 强制重生成（版本令牌变、路径不变 —— 正是「为什么音频 URL 要带 ?v=」描述的行为）：

$ node scripts/tts-call.mjs "缓存命中也应该能落盘。" --regen --base http://127.0.0.1:3081
ok  wav  111.6 KB  2.4 秒  重新生成
音色 mira  模式 echo  版本 9e0a9ecc-cf99-4b10-ace1-17f76683b36b
url  http://127.0.0.1:3081/api/ds-tts/audio/1802f64a7c187ab8.wav?v=9e0a9ecc-cf99-4b10-ace1-17f76683b36b

⑥ 单测（node --test，113 个用例全过）：

$ node --test
ℹ tests 113
ℹ suites 0
ℹ pass 113
ℹ fail 0
ℹ duration_ms 602.4668

本次没验证到的（如实说，不含糊）：

• 完整 npm run build / npm run typecheck 没跑通。两半 bundle 都产出成功 （host bundle written to lib/index.js / client bundle written to lib/client.js (id=ds-tts)）， 但最后一步 tsc -p tsconfig.build.json 报 src/client/index.ts(13,36): error TS2307: Cannot find module '@deepseek-ai/dsh-client-runtime/client' —— 本机所有候选位置都没有这个包的实体副本（profile 里是悬空 junction），离线补不齐。 不是代码问题，是这台机器缺一份 SDK 副本；在有完整 dsh 安装的机器上按「开发」一节跑即可。
• 只有插件页截图，没有朗读界面截图。docs/screenshots/plugin-page.png 是「插件 → 已安装 → 查看 ds-tts」 的实拍（显示组件「运行中」）；设置面板与朗读界面没能取到 —— 本机这个插件页上就没有配置表单， 所以朗读流程的证据仍是上面的终端实录，不造示意图。
• 没有验证非 Windows 平台（自动探测浏览器只写了 Windows 路径）。

---

HTTP 接口

全部挂在 /api/ds-tts 下，仅回环可调（本机脚本可以，别的机器不行），本机调用不需要鉴权 —— 上面那道护栏就是它的边界。默认端口取决于你的 DSH 实例（dsh web 默认 3080；本机 lab 实例是 3081）。

端点

/voices 在 autoLaunch:true 时会顺手把专用浏览器拉起来（有副作用）——诊断请优先用 /status。

命令行（scripts/tts-call.mjs）

不依赖插件内部代码，只打 HTTP —— 这也是「文本进音频出」不经 GUI 的最小示例：

等价的手写请求：

curl -s -X POST http://127.0.0.1:3080/api/ds-tts/synthesize \
  -H 'Content-Type: application/json' \
  -d '{"text":"要朗读的文字","voice":"mira"}'
curl -s 'http://127.0.0.1:3080/api/ds-tts/audio/<id>.wav?v=<version>' -o out.wav

三条必须知道的事：

1. 仅回环可调：路由带 loopback + 同源护栏（它要驱动本机浏览器、能写工作区）。本机脚本可以，别的机器不行。
2. 本机调用不需要鉴权（实测裸 fetch 即 200）—— 上面那条护栏就是它的边界。
3. 合成要求 DS 专用浏览器在跑且已登录（DS 官方 TTS 只读助手消息，文本必须先投递进会话）；命中缓存时两者都不需要。

模型可见工具

三个工具都由宿主注册，模型可以直接调：

接口清单与验证方式

诊断请优先用 GET /api/ds-tts/status：它不会触发浏览器自启。而 /voices 在 autoLaunch:true 时会顺手把专用浏览器拉起来（有副作用）。

---

配置

部署默认值在 cordis.patch.yml 的 config:（Schemastery），用户在 $DSH_HOME/ds-tts/config.json 的覆盖层按 mtime 热读（改完不需要重启）。

设置入口：设置 → 通用 → 「语音朗读（ds-tts）」 —— 改音色/格式/投递模式/上限、看状态自查、重建朗读会话。

---

它把东西放在哪

$DSH_HOME/ds-tts/
  config.json      # 用户覆盖层（config）+ 运行时状态（runtime：lastProbe / voicesCache / chatSessionId）
  cache/           # 内容寻址缓存：<16 位 hex>.wav + 同名 .json 元数据
  browser/         # 专用浏览器 profile（要在这里登录一次 DS）
  out/             # tts_speak 工具的默认产物目录

<会话 cwd>/.dsh/tts/   # /export 路由的落点（带 sessionId，所以能解析会话工作区）

覆盖层按 mtime 热读：改 config.json 不需要重启 DSH。它刻意不含任何凭据字段（见「安全约定」）。

---

依赖

运行期的 @deepseek-ai/* SDK 由 dsh 提供（profile 的 node_modules 里就是 dsh 安装的 junction），所以它们刻意不写进任何依赖字段：

• 写进 dependencies 会拉进第二份副本，@deepseek-ai/schemastery 的 schema 身份、SlotMap 增补都可能对不上；
• 写进 peerDependencies 也不行 —— pnpm 会去 registry 解析，而 @deepseek-ai/dsh-* 的 rc 版存在 semver 预发布区间问题：它们的传递依赖写 ^0.1.5，匹配不到 0.1.5-rc.x，直接 ERR_PNPM_NO_MATCHING_VERSION。标 optional: true 也拦不住。

所以：committed 的配置里没有任何本机路径，本地开发用 npm run link-sdk 把本机 dsh 安装里的 SDK 链接进来（见下）。真正起作用的运行期契约是 package.json 的 dsh.client.inject 与源码里的 import（plugin 行由 profile 装配，SDK 由宿主解析）。

口径提醒：.npmrc、scripts/link-sdk.mjs 与 package.json 的 dsh._note 都说这些 SDK 「只声明为 peerDependencies」，但 package.json 里并没有 peerDependencies 字段 —— 实际是一个依赖字段都没进。README 按实际字段叙述，源码未改。

---

开发

pnpm install          # 只装普通依赖（esbuild / typescript / ws / @types / react），不需要访问私有 registry
npm run link-sdk      # ★ 必跑：把本机 dsh 安装里的 @deepseek-ai/* 链进 node_modules（供 tsc/esbuild 解析类型）
npm run typecheck     # tsc --noEmit
npm run build         # esbuild → lib/index.js + lib/client.js（+ lib/testing.js 给测试）；tsc -p tsconfig.build.json → lib/types
npm test              # build + node --test（113 个用例，默认不联网、不需要浏览器）
npm run probe         # Step 0 探针说明 + 宿主侧可达性检查

link-sdk.mjs 会扫描 $DSH_HOME/profiles/node_modules/@deepseek-ai、profiles/web/... 与 npm 全局的 dsh 安装， 把找到的包做成 junction（Windows 免管理员）；它校验 package.json 是否存在，所以会自动跳过本机那些悬空 junction（有目录、无 package.json）。也可用 DSH_SDK_DIR 直接指定 @deepseek-ai 所在目录。

tsconfig.json 开着 preserveSymlinks: true，这是必需的：TS 默认会穿透链接到真实路径，于是 ui-chat / ui-conversation 在自身位置向上解析 @deepseek-ai/dsh-client-ui-slots 时会命中 profile 里那个 悬空 junction，它们对 SlotMap 的 declare module 增补就被静默丢弃（症状：SlotMap 里只剩本插件自己声明的 key）。 开着它，解析停留在本仓库 node_modules（link-sdk 建立的那套），全部命中可用副本 —— 于是 committed 配置里不需要任何绝对路径。

代码地图

src/index.ts          宿主 apply：配置 + 路由 + 工具
src/engine.ts         编排：归一化 → 缓存 → 串行队列 → 浏览器投递 → ticket+wss → WAV/MP3
src/routes.ts         HTTP 层（护栏 / 状态码 / 导出落盘）
src/tools.ts          tts_speak / tts_voices / tts_status
src/config.ts         Schemastery 默认值 ⊕ config.json 热读覆盖层
src/ds/tts.ts         DS 官方通道（voices / voice / ticket / wss 收帧）
src/ds/frames.ts      4 字节大端 seq 帧、信封、业务码→中文
src/ds/history.ts     history_messages 的解释层（字段别名归一化 / 新消息选择 / 诊断）
src/ds/mode.ts        投递模式决策（实测：DS 只接受助手消息 → 为什么默认 echo）
src/ds/text.ts        Markdown → 口播文本归一化
src/browser/cdp.ts    极简 CDP 客户端（/json/list + 页级 WebSocket JSON-RPC）
src/browser/page.ts   页面驱动：就绪等待 / 选页复用 / 登录检测 / 投递 / 取 message_id
src/audio/*           裸 PCM→WAV、内容寻址缓存（含版本令牌）、可选 Ogg/Opus→MP3、ffplay 播放
src/client/*          Web GUI：slot 注册、播放器、弹窗、设置行、动作（朗读/重新生成/下载/存盘）
src/client/icons.tsx  图标：官方 primitives 图标（带存在性检查）+ DS 网页端原版朗读素材
src/client/primitives.d.ts  平台模块的类型 shim（本机没有实体，只有运行时模块表提供）
scripts/build-*.mjs   两半的 esbuild 构建
scripts/link-sdk.mjs  本地开发：把本机 dsh 安装的 @deepseek-ai/* 链进 node_modules
scripts/tts-call.mjs  命令行调 HTTP 接口的示例（不依赖插件内部）
scripts/probe*.mjs    Step 0 探针
docs/probe*.js        4 个**浏览器控制台**探针（F12 → Console 粘贴，不是 node 脚本；只读或合成，不发送消息）
test/*.test.mjs       12 个测试文件（node --test，113 个用例）

关于图标

官方图标来自平台模块 @deepseek-ai/dsh-client-ui-primitives（官方 bundle 里以 _deepseek_ai_dsh_client_ui_primitives.X 引用它）。播放条直接复用官方图标 （IconPlayOutline16 / IconPauseOutline16 / IconStopFill16 / IconLoadingOutline16 / IconCloseOutline16）； 官方图标集里没有声音与下载图标，所以 🔊 / ⤓ / 💾 三个按官方 16px 描边约定自绘 （viewBox="0 0 16 16"、fill="none"、stroke="currentColor"、strokeWidth=1.31831、圆角端点）。

该包在本机是悬空 junction（没有实体可读），所以类型是 shim、并在运行时做 存在性检查：任一图标拿不到就退到内联等价物，绝不让一个图标名把插件搞白屏。

---

排障

报错怎么定位（先看 status 再看 mode）

1. node scripts/tts-call.mjs --status 或 GET /api/ds-tts/status（都不会触发浏览器自启）；
2. 按返回的字段对号入座：

症状	看哪个字段	大概率原因
说浏览器不可用	browser.connected / lastError	专用浏览器没起、或 CDP 端口被别的进程占了
说没登录	ds.pageFound vs ds.loggedIn	页面没打开（pageFound:false）与没登录（pageFound:true 但 loggedIn:false）是两件事
账号没放行	ds.allowed / lastProbe.code	账号没有官方朗读灰度
合成报 DELIVER_FAILED	—	DS 前端改版把投递选择器改了，需要适配
朗读出来的内容不对	echoVerify	复述走样；调小 maxChars 分段
点了"重新生成"没变化	URL 里的 ?v=	浏览器缓存了旧字节 —— 正常路径下版本令牌会变，若没变说明没真的重生成

合成很慢 / 卡住

首次合成要：拉起浏览器 → 等页面 readyState=complete（最多 20s）→ 投递 → 等模型回显 → 取票 → wss 收 PCM。 openPage 超时会返回 PAGE_NOT_READY（可重试），而不是误报"未登录"。timeoutMs 默认 120s。 命中缓存时纯读文件，不需要浏览器 —— 所以同文本第二次会秒回。

---

已知限制

• 官方朗读是灰测/新功能接口，协议随时可能变；前端改版会让投递选择器失效（届时 tts_status 会给出 DELIVER_FAILED）。
• 每次未命中缓存的朗读都需要专用浏览器在运行；命中缓存时纯读文件，不需要浏览器。
• 选页策略是"复用优先"（有专用会话就复用该会话页，否则复用任何已开的 DS 页，都没有才新开），所以不会每失败一次就堆一个标签页；ds-tts 不会关闭任何标签页。
• 冷启动浏览器/首次加载 DS 页面需要时间：openPage 会等页面真正落在 chat.deepseek.com 且 readyState=complete（最多 20s）才去读登录态，超时返回 PAGE_NOT_READY（可重试）而不是误报"未登录"。
• echo 模式每条文本都会在你的 DS 账号里留下会话消息，并消耗一次网页端模型回复；会话过长时可用设置里的「重建朗读会话」。
• 长文本按 maxChars 截断（并在 UI 提示）；不做整段对话拼接成单一长音频。
• 不做词级高亮同步。
• SAPI / Edge 等其它引擎刻意没有：这台机器上要的就是 DS 官方音色。
• 自动探测浏览器是 Windows 形状（src/browser/page.ts 只拼 msedge.exe / chrome.exe 的 Windows 路径， 且没有 process.platform === 'win32' 判断）。非 Windows 上要自己填 browserPath；未在非 Windows 上验证过。
• 一个文本一个缓存槽位、只保留最新一版（想留历史版本要改成 hash+nonce + 清理策略，当前刻意没做）。

---

License

BSD-3-Clause —— 声明见 package.json 的 license 字段。

仓库根目录没有 LICENSE 文件（GitHub 也识别不到许可），所以这里不给徽章、不复制全文。

---

相关

• awesome-dsh-plugin —— DSH 插件精选列表。