DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

liceses /

liceses/dsh-ds-tts

Verified

用 DeepSeek 官方朗读音色朗读 / 导出 / 接口化

★ 2 Stars0 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@26c799bb

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 Plugin Platform Node

在 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 字待朗读的状态。 ⚠️ 这张*只拍到了面板：本机 浏览器未连通（专用浏览器没起来），所以没有合成出音频、也没拍到播放器。朗读流程的可信证据仍是下面的终端实录。*

目录

想了解 看这里
30 秒搞懂它为什么这么绕 它是怎么工作的
亲手跑一次（含终端实测输出） 快速开始 · 本次复核
有哪些接口 / 参数怎么传 HTTP 接口 · 命令行 · 模型工具
会不会泄露凭证 安全约定
有哪些开关 配置
出问题了怎么看 排障
它把东西放哪 数据落点
凭什么说"实测有效" 已验证（作者记录） · 本次复核
有什么坑 已知限制
想改代码 依赖 · 开发 · 代码地图
能不能装在我这版 DSH 上 兼容性

快速开始

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

  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) 在 $DSH_HOME/profiles/web/package.json 的 dsh.profile.bundles 里加上 "ds-tts"
#    { "dsh": { "profile": { "bundles": [ "…", "ds-tts" ] } } }

# 4) 重启并刷新
dsh web

注册方式在 0.2.x 变成了 bundle 列表驱动。 早期版本是在 cordis.patch.yml 里 - insert: [{id: ds-tts, name: ds-tts}]；现在不要再往 patch 里 insert —— 同一个 entry id 出现两次会被 cordis 拒绝。

装配行的 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 指纹三道关。 这三道关我们一道都不碰 —— 交给一个真实的浏览器去做（页面自己就会算、就有指纹）。

于是整件事被切成两半：

谁 干什么 为什么是它
真浏览器（CDP 驱动） 把文字投递成一条 DS 消息 PoW / cf_clearance / TLS 指纹它全都有，我们零逆向
ds-tts 宿主进程（Node 直连） 取票 + wss 收 PCM + 拼成 WAV + 缓存 实测 Cloudflare 不拦非浏览器客户端，所以合成不必过浏览器
DSH Web GUI 播放 / 下载 / 存盘 就是你要的"网页端读"

一句话：用真浏览器解决"进不去"的问题，用 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 会话里的一条消息 真实浏览器（CDP 驱动） 需要调 POST /api/v0/chat/completion，那要 DeepSeekHashV1 的 WASM PoW + Cloudflare cf_clearance + 浏览器 TLS 指纹。交给真浏览器，这三样全部由页面自己完成，我们一行都不碰
取票 + wss 合成 + PCM→WAV ds-tts 宿主进程（Node 直连） 实测 Cloudflare 不拦非浏览器客户端（GET /chat/tts/voices 从 Node 返回干净的 {"code":40003,"msg":"INVALID_TOKEN"}，无 cf-mitigated），所以合成不必经浏览器
播放 / 下载 / 存盘 DSH Web GUI 就是你要的「网页端读」

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

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 账号、能写你的工作区，所以边界必须写在明面上。

约定 具体是什么 在代码里
userToken 不落盘 只在页面上下文里读出来当次使用，宿主不写进配置、不打日志 覆盖层文件刻意不含任何凭据字段（src/config.ts 顶部注释）
仅回环 + 同源 每条路由先过 isLoopbackRequest()：remoteAddress 必须是 127.0.0.1/::1、Host 必须是回环主机名、sec-fetch-site 不能是 cross-site、带 Origin 时必须同源 src/routes.ts:86-106，8 条路由全部走 guard()
不对 LAN 暴露 本插件会驱动本机浏览器、能写工作区，绝不能对局域网开口子 同上；护栏照搬 dsh-text-drop 的成熟做法
不逆向、不伪装 不实现 PoW / cf_clearance / TLS 指纹伪装，用的是真浏览器真行为 src/browser/（CDP 驱动页面，不算哈希、不改指纹）
不引 playwright / puppeteer CDP 由 ws 直连；ws 是唯一非 SDK 运行时依赖，构建时内联进 bundle package.json dependencies + src/browser/cdp.ts
导出文件名净化 去分隔符与非法字符，并且纵深防御地抹掉任何 .. 序列（即使分隔符已被替换也不允许出现） src/routes.ts:147-155 sanitizeName()
同源 音频、导出、配置读写都只服务本机页面；别的机器打不到 同护栏

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

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

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

环节 证据
账号放行 GET /chat/tts/voices → code 0，4 个音色；/auth/ticket → code 0，ticket 600s
TTS 只接受助手消息 同一会话：助手消息 code 0（627 帧 / 3,009,162 B / 62.69s）；用户消息 code 6 / no_content
端到端朗读 + 缓存 缓存元数据 mode:echo、voice:mira、seconds:172.54、bytes:8,282,136、serverFormat:pcm，带 DS 侧 audioId/traceId，且 echoVerify 通过 —— 即「CDP 投递 → 模型回显 → ticket+wss → PCM→WAV → 落盘」整条链路真的跑通过
登录检测 曾误判"未登录"：新标签页还在 about:blank 时读 localStorage（竞态）。修法是 waitForOrigin 等页面落在 DS 源且 readyState=complete；修后 status 报 pageFound:true / loggedIn:true

本次复核（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）。

端点

名称 参数 说明
POST /synthesize {text, voice?, format?, mode?, regenerate?, sessionId?} 文本进、音频出。返回 {ok, id, url, version, regenerated, ext, bytes, ms, cached, voice, mode, seconds, text, truncated}。text 空 → 400；超长（maxChars 的 8 倍）→ 413 TOO_LONG
GET /audio/<id>.<ext> 路径参数 id（16 位 hex）、ext ∈ wav/mp3/opus；?v=<版本> 取音频字节。?v= 只用于缓存击穿，路由忽略它；响应带 immutable 长缓存。id/ext 不合法 → 400；文件不在缓存（可能被清理）→ 404
POST /export {id, ext, sessionId, fileName?} 把缓存里的音频写到该会话工作区的 <cwd>/.dsh/tts/，返回绝对路径。重名自动加 -1…（上限 1000 次尝试）。缺参 → 400；音频不在缓存 → 404
GET /voices ?force=1 跳过 1 小时缓存 DS 官方音色列表（含公开 CDN 试听地址）与账号当前音色
POST /voice {voiceId} 切账号级音色（会改你 DS 账号里的设置）。voiceId 空 → 400
GET /status ?probe=1 顺带真探测一次放行 浏览器 / 登录 / 放行 / 队列 / 缓存自查。不会触发浏览器自启
GET/PUT/POST /config PUT/POST 的 body 是配置补丁 读 / 写生效配置。补丁字段走白名单（9 个 string + 4 个 number + 3 个 boolean），不认识 → 400
POST /cancel {id?} 取消排队 / 进行中的合成；不带 id = 取消当前

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

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

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

名称 参数 说明
node scripts/tts-call.mjs <文字> [选项] 合成并打印 URL 与元数据；ok / ext / KB / 秒数 / 新合成|缓存命中|重新生成
--voice <id> 音色：mira（贝壳，默认）/ echo（白浪）/ stella（海星）/ tide（暗潮）
--mode <m> 投递模式：echo（默认）/ auto / user
--regen / --regenerate — 强制重新生成一版（跳过缓存）
--out / -o <路径> 把音频写到该文件；以分隔符结尾或没有扩展名则当目录
--json — 只吐原始 JSON（不配 --out 时生效），方便脚本接
--base <url> 宿主地址，默认 http://127.0.0.1:3080
--status — 查浏览器 / 登录 / 缓存状态后退出
--help / -h — 打印用法

等价的手写请求：

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 只读助手消息，文本必须先投递进会话）；命中缓存时两者都不需要。

模型可见工具

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

名称 参数 说明
tts_speak text（必填）、voice?、format?（pcm/opus）、out?、regenerate?、play? 合成并落成真实文件，返回绝对路径（可直接 present）。默认写 $DSH_HOME/ds-tts/out/。失败返回 ok:false + 中文 error，不抛错（一次 TTS 失败不该结束整个回合）
tts_voices refresh? 列音色 + 账号当前音色（refresh:true 跳缓存）
tts_status 无 诊断：浏览器连通 / 是否登录 / 是否放行 / 队列 / 缓存。tts_speak 报错时先调它

接口清单与验证方式

层 接口 怎么确认它在
插件 synthesize / audio/<id>.<ext> / export / voices / voice / status / config / cancel 装配测试断言 8/8 注册；另用无副作用调用逐条实测：status 200、config 200、synthesize 空文本 400（不触发合成）、cancel 200、export 缺参 400、audio 坏 id 400、audio 真 id 200 + audio/wav + RIFF 头
DS 官方 GET /api/v0/chat/tts/voices、POST /api/v0/auth/ticket、wss /api/v0/chat/tts/ 实测：code 0 / 4 个音色 / ticket 600s / 助手消息 627 帧 3,009,162 字节
不存在 「读任意文本」的接口；「读用户消息」的接口 用户消息实测 code 6 / no_content；官方 API Change Log 无 TTS 条目

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

配置

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

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

项 默认 说明
voice mira 音色 voice_id
format pcm pcm → 无损 WAV；opus → 体积小（带 Ogg 容器且有 ffmpeg 时转 MP3）
mode echo 投递模式 echo（默认）/user/auto —— 见上文实测结论
maxChars 2000 归一化后上限；超出在句末截断并回 truncated:true；离谱超长（8×）回 413 TOO_LONG
cdpUrl / cdpPort '' / 9222 CDP 端点（cdpUrl 非空则完全用它，不再自启）
browserPath / userDataDir '' 留空自动探测 Edge/Chrome 与 $DSH_HOME/ds-tts/browser
autoLaunch true 没端点时是否自启专用浏览器
chatSessionId '' ds-tts 专用 DS 会话（首次投递时创建并记住）
echoPrompt / echoVerify 见 schema echo 模式指令模板与回显校验
timeoutMs 120000 单次合成总超时
cacheEnabled / cacheKeepDays true / 30 内容寻址缓存与保留期
ffplayPath '' 工具 play:true 时用的 ffplay

它把东西放在哪

$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。它刻意不含任何凭据字段（见「安全约定」）。

兼容性（DSH 版本）

npm run check:dsh     # 用 dsh 自己的闸门函数判定本插件还能不能被加载
dsh 版本 结果
0.1.7-rc.2 ✅ 兼容
0.2.0-rc.1 ✅ 兼容
0.2.1-rc.5 ✅ 兼容（实测运行，见下）
0.2.9 ✅ 兼容
0.3.0-rc.1 ❌ 拒绝（需重新评估）

peerDependencies 里 @deepseek-ai/dsh-* 一律写显式区间 >=0.1.7-rc.1 <0.3。

为什么用显式区间而不是 ^

DSH 启动期会调 evaluatePluginCompatibility()，拿 peerDependencies 的版本范围与运行时版本比对， 不满足就拒绝加载（dsh: skipping profile bundle "…": Plugin … is incompatible with dsh …）。两个坑：

  1. engines.dsh 不参与判定 —— 真正被比的是 peerDependencies 里的 @deepseek-ai/dsh-*。
  2. caret + 预发布版会踩上界：^0.1.7-rc.1 的语义是 >=0.1.7-rc.1 <0.2.0。 用真实闸门实测，运行时 0.2.1-rc.5 下 ^0.1.7-rc.1 被拒、^0.2.1-rc.1 通过 —— 老写法会在每次次版本升级时失效。跨小版本必须写 >=A <B。

0.2.1 的实测证据

检查 方法 结果
装配期闸门 dsh 0.2.1-rc.5 的 evaluatePluginCompatibility ✅ 不再被拒
类型 tsc --noEmit 对着 0.2.1-rc.5 类型 ✅ 0 错误
单测 npm test ✅ 114/114
客户端登记 隔离实例读首页 __DSH_BOOT__ 预载清单 ✅ 含 ds-tts/client.js
客户端执行 真浏览器查 style[data-plugin="ds-tts"] ✅ 存在（factory 与 apply() 都跑了）
宿主路由 GET /api/ds-tts/status ✅ 200

0.2.x 相对 0.1.x 的结构性变化（已适配）：dsh-client-runtime 整包消失，继任者是 dsh-client-ui-renderer（/client）与 dsh-client-store；dsh-client-ui-primitives / -slots / -store 不是 dsh 的依赖（壳当平台模块提供），所以 dsh.client.inject 只列真实客户端插件边 （ui-chat / ui-conversation），不列平台模块。

依赖

运行期的 @deepseek-ai/* SDK 由 dsh 提供（profile 的 node_modules 里就是 dsh 安装的 junction），所以它们不会进入 dependencies：

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

所以它们只作为 peerDependencies 元数据存在于 package.json（pnpm install 不会去装）， committed 的配置里没有任何本机路径。真正起作用的运行期契约是 dsh.client.inject 与源码里的 import （plugin 行由 profile 装配，SDK 由宿主解析）。类型来源见 开发。

开发

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 check:dsh     # 用真实运行时闸门判定兼容性
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（114 个用例，默认不联网、不需要浏览器）
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 所在目录。

⚠️ 它有一条安全护栏：如果 node_modules/@deepseek-ai 本身已经是一条目录链接（例如整目录指向某个 SDK 镜像）， 脚本会拒绝执行。原因很实在：那样逐条的 rmSync + symlinkSync 会穿透链接去改写镜像本体 —— 实测踩过：一次 run 就删掉了共享镜像里 3 个从 tarball 解包的客户端包，另一次把 226 个条目改指向别处。 这种情况直接跳过本脚本即可（整目录链接本身已能解析类型），或者先去掉那条链接。

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/check-dsh-compat.mjs  用 dsh 自己的闸门函数判定版本兼容性
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 插件精选列表。
—/ 5

No ratings yet

Verified DSH bundle

Commit 26c799bb5f47

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout