dsh-tingdong 0.5.0 → 0.5.2

package/README.md

@@ -1,17 +1,36 @@
 # 听懂 · dsh-tingdong
 
-把英文有声读物（MP3）变成听力课，练到**听到英文就知道是什么意思**。
+[![npm version](https://img.shields.io/npm/v/dsh-tingdong.svg?style=flat-square)](https://www.npmjs.com/package/dsh-tingdong)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-tingdong.svg?style=flat-square)](https://www.npmjs.com/package/dsh-tingdong)
+[![license](https://img.shields.io/npm/l/dsh-tingdong.svg?style=flat-square)](LICENSE)
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/aicivilization/dsh-tingdong)
+
+把英文有声读物（MP3）或英文文档变成听力课，练到**听到英文就知道是什么意思**。
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）插件，也能脱离 DSH 单独用。
 
+## 安装
+
+```bash
+dsh plugin --profile desktop add dsh-tingdong    # 装进 DSH（把 desktop 换成你的 profile 名，先完全退出 DSH）
+npm i -g dsh-tingdong                            # 命令行版：不开 DSH 也能用
+dsh plugin --profile desktop add github:AIcivilization/dsh-tingdong   # 源码安装
+```
+
+- **能力分类**：工具与能力（英语听力学习）
+- **运行要求**：Node.js ≥ 20；DSH web / desktop profile；解码 MP3 需要 [ffmpeg](https://ffmpeg.org)（Mac：`brew install ffmpeg`）
+- **许可证**：[MIT](LICENSE)
+- **数据边界**：课程和学习进度都在本机 `~/.dsh/dsh-tingdong/`；识别用 DSH 自带语音输入模型（音频不上传）；讲解和朗读用你在 DSH 里选的大模型；Edge 语音组件需联网（文字会发到微软服务器，详见下方导出说明）
+
 ## 它做什么
 
-首页有两个入口：**导入音频**（有声书、讲座、引导音频）和**导入文档**（文章、手册、书）。
+首页有两个入口：**导入音频**（有声书、讲座、引导音频）和**文档转音频**（文章、手册、书）。
 
-**导入文档**：直接选文件（或拖进来）——PDF、Word（.docx）、EPUB 电子书、网页（.html）、TXT、Markdown；没有文件也可以粘贴英文。
+**文档转音频**：直接选文件（或拖进来）——PDF、Word（.docx）、EPUB 电子书、网页（.html）、TXT、Markdown；没有文件也可以粘贴英文。
 
 1. 插件先取出文字，给你一张**确认卡片**：读到了多少词，预计分几课、朗读多长、处理要多久、大约用多少模型 token，并说明「会用 AI 整理文字」。
 2. 你点确定后，在后台：**AI 整理**（去掉页眉页码目录、修好断行、分好章节，原文一个字都不改、不翻译；长文分段、几段同时整理，逐段核对单词数，模型删多了就重来或改用原文）→ **存档**（原文件、取出的原始文字、整理后的文字都留在 `~/.dsh/dsh-tingdong/docs/`，课程概览里能下载）→ **分课**（每个大标题一课，太长的按段落拆开）→ **朗读**（默认微软 Edge，14 种美式 / 英式男女声，可选离线 Kokoro）→ **逐句翻译讲解**。
 3. 做好一课就能先学一课，之后和音频课一样：精听、复习、磨耳朵、连续听、导出。
+4. **下载音频**：文档课的概览页可以下载这一课的 MP3；分成好几课的文档还能「整篇合成一个 MP3」（章间停 1.5 秒），首页文档那一组旁边也有「下载整篇音频」。
 
 **大小和耗时**：文件最大 100 MB；文字最多约 6 万个英文单词（40 万字符，相当于 7 小时左右的朗读），再长请拆开导入。真正花时间和 token 的是 AI 整理和翻译：1 万词大约整理 4 万字符、朗读 1 小时多，处理约十几分钟（看模型速度）。扫描版 PDF（每页是图片）读不出文字，要先用 OCR 或 AI 转成文字。
 在 DSH 对话里也可以把 PDF 发给 AI，说「整理后导入听懂」（AI 工具 `tingdong_import_text`）。
@@ -70,7 +89,7 @@
 装进 DSH（把 `desktop` 换成你的 profile 名；先完全退出 DSH）：
 
 ```bash
-dsh plugin --profile desktop add /path/to/dsh-go
+dsh plugin --profile desktop add dsh-tingdong
 ```
 
 重新打开 DSH，在对话页打开右侧栏，选「听懂 · 英文听力」。设置里的「听懂」分区会显示 ffmpeg、识别模型、翻译模型是否就绪。
@@ -138,3 +157,14 @@ npm test
 - `lib/drill.js` 磨耳朵音频；`lib/lookup.js` 点词查意思、重新讲解；`lib/vps.js` 经 SSH 发送到 VPS
 - `plugin/` DSH 宿主端（路由、AI 工具）和界面入口（右侧栏、设置）；路由先过 DSH 的 `connection.requestRejection()` 登录校验
 - `web/` 学习面板（原生 JS 模块，无构建）：`panel.js` 路由和首页 · `study.js` 精听、复习、今日学习 · `listen.js` 连续听、磨耳朵、词汇 · `edit.js` 改句子、查词 · `core.js` 播放器和公共状态
+
+## 许可
+
+[MIT](LICENSE) · Copyright © 2026 AIcivilization
+
+## 收录渠道
+
+- [DSH Plugin Hub（dsh-plugin.org 社区插件市场）](https://dsh-plugin.org/plugins/aicivilization/dsh-tingdong)
+- [awesome-dsh-plugin 精选列表](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+- dsh-plugin-shop 插件商店（每日自动收录）
+- 52DSH / tuofangzhe 插件目录（证据分级收录）

package/lib/docaudio.js

@@ -0,0 +1,74 @@
+// lib/docaudio.js — 文档转音频：把一份文档分出来的几课朗读，按顺序接成一个 MP3 下载
+//
+// 各课的朗读都是同一个编码器出的（24 kHz 单声道 64 kbps MP3），参数一样，直接拼接、不重新编码：
+// 几个小时的书也是一眨眼。章与章之间插一段 1.5 秒静音。拼好的缓存在 docs/<docId>/audio.mp3，
+// 哪一课的朗读比它新就重拼。
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { dataRoot, findFfmpeg, FFMPEG_HINT } from './paths.js'
+import { audioPath, getLesson, listLessons } from './store.js'
+
+const GAP = 1.5
+
+function run(ffmpeg, args) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(ffmpeg, ['-hide_banner', '-nostdin', '-y', ...args], { stdio: ['ignore', 'ignore', 'pipe'] })
+    let err = ''
+    p.stderr.on('data', d => { err = (err + d).slice(-2000) })
+    p.on('error', reject)
+    p.on('close', code => (code === 0 ? resolve() : reject(new Error(`拼接音频失败：${err.trim().split('\n').slice(-2).join(' ')}`))))
+  })
+}
+
+/** 这份文档的几课（按原文顺序），以及它们的朗读文件 */
+export async function docLessons(docId) {
+  const metas = (await listLessons()).filter(l => l.docId === docId).sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  return metas
+}
+
+/**
+ * 整篇文档的音频
+ * @returns {Promise<{file:string, title:string, voiceLabel:string, lessons:number}>}
+ */
+export async function wholeDocAudio(docId, o = {}) {
+  if (!/^[a-f0-9]{12}$/.test(String(docId))) throw Object.assign(new Error('文档编号不对'), { status: 400 })
+  const ffmpeg = findFfmpeg(o.ffmpeg)
+  if (!ffmpeg) throw Object.assign(new Error(FFMPEG_HINT), { status: 500 })
+  const lessons = await docLessons(docId)
+  if (!lessons.length) throw Object.assign(new Error('没有这份文档的课'), { status: 404 })
+  const missing = lessons.filter(l => !existsSync(audioPath(l.id)))
+  if (missing.length) throw Object.assign(new Error(`还有 ${missing.length} 课没朗读完，等做好了再下载`), { status: 409 })
+  const first = await getLesson(lessons[0].id)
+  const dir = join(dataRoot(), 'docs', docId)
+  await mkdir(dir, { recursive: true })
+  let title = first.group || first.title
+  try { title = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf8')).title || title } catch { /* 没有存档信息就用组名 */ }
+  const out = join(dir, 'audio.mp3')
+  const info = { file: out, title, voiceLabel: first.voiceLabel || '', lessons: lessons.length }
+  if (lessons.length === 1) return { ...info, file: audioPath(lessons[0].id) }
+
+  // 缓存还新就直接用
+  if (existsSync(out)) {
+    const built = (await stat(out)).mtimeMs
+    const newest = Math.max(...await Promise.all(lessons.map(async l => (await stat(audioPath(l.id))).mtimeMs)))
+    if (built >= newest) return info
+  }
+  const gap = join(dir, 'gap.mp3')
+  if (!existsSync(gap)) await run(ffmpeg, ['-f', 'lavfi', '-i', `anullsrc=r=24000:cl=mono`, '-t', String(GAP), '-c:a', 'libmp3lame', '-b:a', '64k', gap])
+  const q = p => `file '${p.replace(/'/g, "'\\''")}'`
+  const list = lessons.flatMap((l, k) => (k ? [q(gap), q(audioPath(l.id))] : [q(audioPath(l.id))])).join('\n')
+  const listFile = join(dir, 'concat.txt')
+  await writeFile(listFile, list + '\n')
+  const part = join(dir, 'audio.part.mp3')
+  try {
+    await run(ffmpeg, ['-f', 'concat', '-safe', '0', '-i', listFile, '-c', 'copy', '-metadata', `title=${title}`, '-metadata', 'artist=听懂 dsh-tingdong', part])
+    await rename(part, out)
+  } finally {
+    await rm(part, { force: true })
+    await rm(listFile, { force: true })
+  }
+  return info
+}

package/lib/importer.js

@@ -168,6 +168,16 @@ export class Importer {
   async importDoc(text, o = {}) {
     const doc = parseDoc(text, { title: o.title || '' })
     const hash = createHash('sha1').update(text).digest('hex').slice(0, 6)
+    // 没经过「选文件 → 确认」的（对话里的 AI 工具、命令行粘贴）也建一份存档：整篇下载音频要靠它把几课归到一起
+    if (!o.docId) {
+      o = { ...o, docId: createHash('sha1').update(text).digest('hex').slice(0, 12) }
+      const dir = join(dataRoot(), 'docs', o.docId)
+      await mkdir(dir, { recursive: true })
+      await writeFile(join(dir, 'clean.md'), text)
+      if (!existsSync(join(dir, 'meta.json'))) {
+        await writeFile(join(dir, 'meta.json'), JSON.stringify({ docId: o.docId, name: doc.title, title: o.title || doc.title, type: '文字', ext: '.md', needsCleanup: false, confirmedAt: Date.now() }, null, 1))
+      }
+    }
     const slug = t => String(t).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'doc'
     const out = []
     for (const [k, c] of doc.chapters.entries()) {

package/lib/server.js

@@ -14,6 +14,7 @@
 //   POST <prefix>/doc/text {text, title?}        粘贴的文字，同上
 //   POST <prefix>/doc/confirm {docId, title?, engine?, voice?, speed?}   确定：AI 整理 → 分课朗读翻译
 //   POST <prefix>/doc/cancel {docId} · GET /doc/file?id=&which=clean|raw|original   存档
+//   GET  <prefix>/doc/audio?id=                  文档转音频：整篇文档（几课按顺序接起来）下载成一个 MP3
 //   POST <prefix>/upload?name=                   上传音频（请求体就是文件）
 //   POST <prefix>/grade    {id, i, g}            给一句评分（0 没懂 / 1 半懂 / 2 懂了）
 //   POST <prefix>/resume | retranslate | reset | delete  {id}
@@ -48,6 +49,7 @@ import { exportText, FORMATS } from './export.js'
 import { EDGE_EN_VOICES, EDGE_ZH_VOICES, edgeStatus, installEdge } from './edge.js'
 import { MAX_CHARS, PREP_PROMPT } from './doc.js'
 import { DOC_EXT } from './extract.js'
+import { wholeDocAudio } from './docaudio.js'
 import { detect, getVpsConfig, panelUrl, saveVpsConfig, sshHosts } from './vps.js'
 import { KOKORO_VOICES, kokoroReady, kokoroZhReady, SAY_HINT, sayVoices, ZH_VOICES } from './voices.js'
 import { checkId, deleteLesson, editSentence, getLesson, getProgress, gradeSentence, listLessons, mergeWithNext, resetProgress, setProgressFields, setStar, splitSentence, summary } from './store.js'
@@ -160,7 +162,9 @@ export function createHandler(o) {
           if (q.get('download')) {
             const l = await getLesson(id)
             const meta = TRACKS[track] ? (await listTracks(id))[track] : null
-            const label = TRACKS[track] ? TRACKS[track].label + (meta && meta.voiceLabel ? `（${meta.voiceLabel}）` : '') : '磨耳朵'
+            // 文档课的「原声」其实是朗读
+            const label = track === 'full' && l && l.kind === 'doc' ? `朗读（${l.voiceLabel || 'AI'}）`
+              : TRACKS[track] ? TRACKS[track].label + (meta && meta.voiceLabel ? `（${meta.voiceLabel}）` : '') : '磨耳朵'
             filename = `${(l && (l.titleZh || l.title)) || id} - ${label}.${flac ? 'flac' : 'mp3'}`.replace(/[\\/:*?"<>|]/g, '_')
           }
           if (flac) return serveAudio(req, res, trackFlac(id, track), filename, 'audio/flac')
@@ -191,6 +195,11 @@ export function createHandler(o) {
         }
         if (path === '/formats') return send(res, 200, { formats: FORMATS })
         if (path === '/doc-help') return send(res, 200, { prompt: PREP_PROMPT, maxChars: MAX_CHARS, maxUpload: MAX_DOC_UPLOAD, ext: DOC_EXT })
+        if (path === '/doc/audio') {
+          const a = await wholeDocAudio(String(q.get('id') || ''), { ffmpeg: opts().ffmpeg })
+          const name = `${a.title}${a.voiceLabel ? `（朗读：${a.voiceLabel}）` : ''}.mp3`.replace(/[\\/:*?"<>|]/g, '_')
+          return serveAudio(req, res, a.file, name)
+        }
         if (path === '/doc/file') {
           const id = q.get('id')
           if (!DOC_ID.test(String(id))) return send(res, 400, { error: '文档编号不对' })

package/lib/store.js

@@ -216,6 +216,7 @@ export function summary(l, p) {
   return {
     id: l.id,
     kind: l.kind || 'audio',
+    docId: (l.source && l.source.docId) || '',
     voiceLabel: l.voiceLabel || '',
     title: l.title,
     titleZh: l.titleZh || '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tingdong",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "听懂：把英文有声读物（MP3）或英文文档变成听力课。本地识别 / AI 朗读每一句英文、AI 翻译讲解，再用盲听、精听、间隔复习把它练到「一听就懂」。DeepSeek Harness (dsh) 插件。",
   "keywords": [
     "dsh-plugin",

package/plugin/manage.js

@@ -54,7 +54,8 @@ const ALREADY = '这个版本的 DSH 不能在运行中升级已装的插件。
 export function createManager(o) {
   let running = ''
   const readPkg = async () => { try { return JSON.parse(await readFile(join(o.pkgRoot, 'package.json'), 'utf8')) } catch { return {} } }
-  readPkg().then(p => { running = p.version || '' })
+  // 初始包信息读取：info()/update() 开先 await 它，避免 running 还没读到就比版本
+  const pkgReady = readPkg().then(p => { running = p.version || '' })
 
   let cache = null
   async function latest(force) {
@@ -79,6 +80,7 @@ export function createManager(o) {
   return {
     /** 版本信息：正在运行的、磁盘上装好的、npm 上最新的 */
     async info(force) {
+      await pkgReady
       const [pkg, newest] = await Promise.all([readPkg(), latest(force)])
       const installed = pkg.version || ''
       const current = compareVersions(installed, running) > 0 ? installed : running
@@ -96,6 +98,7 @@ export function createManager(o) {
       }
     },
     async update() {
+      await pkgReady
       const newest = await latest(true)
       const cmd = command(`add ${PACKAGE}@${newest || 'latest'}`)
       if (!newest) return { ok: false, message: '查不到 npm 上的最新版本，检查网络后再试', command: cmd }

package/web/panel.js

@@ -155,16 +155,16 @@ function renderLibrary() {
           <span class="faint">有声书、讲座、引导音频……MP3 / M4A / WAV / FLAC。本机识别出每一句英文，AI 翻译讲解。</span>
         </button>
         <button class="new-card ${type === 'doc' ? 'on' : ''}" data-new="doc">
-          <span class="new-ico">📄</span><b>导入文档</b>
+          <span class="new-ico">📄</span><b>文档转音频</b>
           <span class="faint">文章、手册、书……整理好的英文文字（粘贴或 TXT / Markdown）。AI 朗读成音频，再翻译讲解。</span>
         </button>
       </div>
       <div id="newPanel"></div>
       <div id="jobs"></div>` : `<div class="card small muted">这里只用来学习：在电脑上导入、做好课，再用电脑上的「发送到 VPS」发过来。<div id="jobs"></div></div>`}
     <div class="section-title">我的课程</div>
-    ${S.lessons.length ? '' : `<div class="empty">还没有课。上面选一种：导入英文音频，或导入英文文档。</div>`}
+    ${S.lessons.length ? '' : `<div class="empty">还没有课。上面选一种：导入英文音频，或把英文文档转成音频。</div>`}
     ${[...groups].map(([g, ls]) => `
-      ${g ? `<div class="group-title">${esc(g)}</div>` : (groups.size > 1 ? '<div class="group-title">其他</div>' : '')}
+      ${g ? `<div class="group-title row"><span class="grow">${esc(g)}</span>${docDownload(ls)}</div>` : (groups.size > 1 ? '<div class="group-title">其他</div>' : '')}
       ${ls.map(lessonCard).join('')}`).join('')}
     <div id="vpsCard"></div>
   `
@@ -238,7 +238,7 @@ let pendingDoc = null // 已经读出文字、等确认的文档
 function newDocPanel(box) {
   if (pendingDoc) return docConfirm(box, pendingDoc)
   box.innerHTML = `<div class="card">
-    <h3>导入英文文档</h3>
+    <h3>文档转音频</h3>
     <div class="drop" id="docDrop">
       <div class="new-ico">📄</div>
       <div><b>把文档拖到这里</b>，或 <a href="#" class="link" id="docPick">选择文件</a></div>
@@ -372,6 +372,15 @@ async function docConfirm(box, doc) {
   }
 }
 
+/** 文档那一组：整篇音频下载（几课合成一个 MP3）；还有课没做好就先不给 */
+function docDownload(ls) {
+  const ids = [...new Set(ls.map(l => l.docId).filter(Boolean))]
+  if (ls.some(l => l.kind !== 'doc') || ids.length !== 1) return ''
+  const waiting = ls.filter(l => !l.hasAudio).length
+  if (waiting) return `<span class="faint">还有 ${waiting} 课在转音频</span>`
+  return `<a class="link" href="doc/audio?id=${ids[0]}" download title="整篇文档的朗读，合成一个 MP3">⬇ 下载整篇音频</a>`
+}
+
 // —— 今日学习卡片 ——
 async function loadToday() {
   try {
@@ -618,6 +627,7 @@ function paneOverview(pane, l, st) {
       ${l.note ? `<div class="small" style="color:var(--mid)">${esc(l.note)}</div>` : ''}
       ${l.status === 'error' ? `<div class="small" style="color:var(--bad)">${esc(l.error)}</div>` : ''}
     </div>
+    ${l.kind === 'doc' && S.cur.lesson.sentences.length ? docAudioCard(l) : ''}
     <div class="card">
       <div class="stat-grid">
         <div><b>${st.fresh}</b><span>没学过</span></div>
@@ -659,6 +669,22 @@ function paneOverview(pane, l, st) {
   bindManage(pane, l)
 }
 
+/** 文档课：下载朗读音频（这一课 / 整篇） */
+function docAudioCard(l) {
+  const same = S.lessons.filter(x => x.docId && l.source && x.docId === l.source.docId)
+  const waiting = same.filter(x => !x.hasAudio).length
+  return `<div class="card">
+    <h3>下载音频</h3>
+    <div class="faint">把文档转成的音频下载成 MP3，放到手机或播放器上听（朗读：${esc(l.voiceLabel || 'AI')}）。</div>
+    <div class="row" style="margin-top:8px">
+      <a class="btn primary" href="audio?id=${encodeURIComponent(l.id)}&track=full&download=1" download>这一课 MP3（${fmt(l.duration)}）</a>
+      ${same.length > 1 ? (waiting
+        ? `<span class="faint">整篇 ${same.length} 课，还有 ${waiting} 课在转音频，做好后可以合成一个下载</span>`
+        : `<a class="btn" href="doc/audio?id=${l.source.docId}" download>整篇 ${same.length} 课合成一个 MP3</a>`) : ''}
+    </div>
+  </div>`
+}
+
 // —— 概览里的「声音」卡片：每种声音一行：状态、选用、试听、生成、下载 ——
 const TRACK_NOTES = {
   full: '原始音频，含背景音乐和长空白',
@@ -693,7 +719,7 @@ function voicesCard(l) {
     return `<div class="track ${name === t ? 'on' : ''}">
       <div class="row"><b class="grow">${esc(trackLabel(name))}</b>
         ${meta ? `<span class="faint">${fmt(meta.duration)}${meta.voice ? ' · ' + esc(meta.voice) : ''}</span>` : '<span class="faint">未生成</span>'}</div>
-      <div class="faint">${name === 'full' && isDoc() ? '导入文档时 AI 朗读生成的音频' : TRACK_NOTES[name]}${name === 'kokoro' && v.kokoro && !v.kokoro.ready && canMake ? '；第一次生成会下载约 103 MB 语音模型' : ''}</div>
+      <div class="faint">${name === 'full' && isDoc() ? '文档转音频时 AI 朗读生成的音频' : TRACK_NOTES[name]}${name === 'kokoro' && v.kokoro && !v.kokoro.ready && canMake ? '；第一次生成会下载约 103 MB 语音模型' : ''}</div>
       ${stale ? '<div class="small" style="color:var(--mid)">句子改过了，这条声音对不上了，建议重新生成</div>' : ''}
       ${job ? `<div class="small muted" style="margin-top:4px">${job.state === 'queued' ? '排队中' : esc(job.stage)}${job.total ? ` ${job.done}/${job.total}` : ''}…</div>` : `
       <div class="row" style="margin-top:6px">