dsh-tingdong 0.3.1 → 0.5.0

package/lib/importer.js

@@ -4,13 +4,18 @@
 // 模型不可用时也能出课（只有英文），之后再「补全翻译」。
 
 import { existsSync } from 'node:fs'
-import { readdir, rename, rm, stat } from 'node:fs/promises'
+import { copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { basename, dirname, extname, join, resolve } from 'node:path'
 import { compactAudio, mergeSegments, transcribe } from './asr.js'
 import { ensureModels } from './models.js'
 import { audioPath, getLesson, makeId, saveLesson, titleFromFile } from './store.js'
 import { summarizeLesson, translateSentences } from './translate.js'
-import { buildTrack, TRACKS } from './tracks.js'
+import { buildDocAudio, buildTrack, TRACKS } from './tracks.js'
+import { MAX_CHARS, parseDoc } from './doc.js'
+import { cleanupText, estimate, plainTidy } from './docprep.js'
+import { extractText } from './extract.js'
+import { dataRoot } from './paths.js'
+import { createHash } from 'node:crypto'
 import { getVpsConfig, sendLesson } from './vps.js'
 
 export const AUDIO_EXT = ['.mp3', '.m4a', '.aac', '.wav', '.flac', '.ogg', '.opus', '.wma', '.m4b', '.mp4', '.webm']
@@ -106,12 +111,91 @@ export class Importer {
     return out
   }
 
+  /**
+   * 导入文档第一步：取出文字、存档、预估，等用户确认（不调用 AI）
+   * @param {string} file 上传或本机的文件；text 模式时为 null
+   * @param {{name:string, text?:string, removeSource?:boolean}} o
+   */
+  async prepareDoc(file, o) {
+    const ext = (/\.[a-z0-9]+$/i.exec(o.name || '') || ['.txt'])[0].toLowerCase()
+    const r = file ? await extractText(file, o.name) : { type: '粘贴的文字', text: String(o.text || '') }
+    if (r.scanned) throw Object.assign(new Error('这是扫描版 PDF（每页都是图片），读不出文字。先用手机或电脑的文字识别（OCR）、或让 AI 把它转成文字（.txt），再导入。'), { status: 400 })
+    const text = r.text.trim()
+    if ((text.match(/[A-Za-z]+/g) || []).length < 20) throw Object.assign(new Error('文档里几乎没有英文'), { status: 400 })
+    if (text.length > MAX_CHARS) {
+      throw Object.assign(new Error(`太长了：约 ${Math.round(text.length / 6 / 1000)} 千词。一次最多约 6 万词（${MAX_CHARS / 1000} 千字符，相当于 7 小时左右的朗读），拆成几份导入。`), { status: 400 })
+    }
+    // 已经是「# 章节」格式的 Markdown 不用 AI 再整理
+    const formatted = (ext === '.md' || ext === '.markdown' || !file) && /^#\s+\S/m.test(text)
+    const llm = this.deps.llm()
+    const docId = createHash('sha1').update(text).digest('hex').slice(0, 12)
+    const dir = join(dataRoot(), 'docs', docId)
+    await mkdir(dir, { recursive: true })
+    if (file) await copyFile(file, join(dir, `original${ext}`))
+    if (o.removeSource && file) await rm(file, { force: true })
+    await writeFile(join(dir, 'raw.txt'), text)
+    // 粘贴的文字没有文件名：标题留空，整理后用第一章的标题
+    const title = file ? (o.name || '').replace(/\.[a-z0-9]+$/i, '').replace(/[_]+/g, ' ').trim() : (o.title || '')
+    const meta = {
+      docId, name: o.name || '粘贴的文字', title, type: r.type, ext, pages: r.pages || null,
+      needsCleanup: !formatted, model: llm && llm.label ? llm.label() : '', hasModel: Boolean(llm),
+      estimate: estimate(text, { needsCleanup: !formatted }), createdAt: Date.now(),
+      preview: text.slice(0, 600),
+    }
+    await writeFile(join(dir, 'meta.json'), JSON.stringify(meta, null, 1))
+    return meta
+  }
+
+  /** 导入文档第二步：用户确定后排队——AI 整理 → 存档 → 分课（每课再朗读、翻译） */
+  async confirmDoc(docId, o = {}) {
+    if (!/^[a-f0-9]{12}$/.test(String(docId))) throw Object.assign(new Error('文档编号不对'), { status: 400 })
+    const dir = join(dataRoot(), 'docs', docId)
+    let meta
+    try { meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf8')) } catch { throw Object.assign(new Error('找不到这份文档，重新选一次文件'), { status: 404 }) }
+    meta.title = (o.title || meta.title || '').trim()
+    meta.voice = { engine: o.engine, voice: o.voice, speed: o.speed }
+    meta.confirmedAt = Date.now()
+    await writeFile(join(dir, 'meta.json'), JSON.stringify(meta, null, 1))
+    this.enqueue({ kind: 'docprep', docId, title: `整理文档：${meta.title || meta.name}` })
+    return meta
+  }
+
+  /**
+   * 导入英文文档：一章一课；每课排一个任务：朗读 → 翻译讲解 → 概述
+   * @param {string} text 整理好的纯文本（# 章节标题 分章）
+   * @param {{title?:string, engine?:'edge'|'kokoro', voice?:string, speed?:number}} o
+   */
+  async importDoc(text, o = {}) {
+    const doc = parseDoc(text, { title: o.title || '' })
+    const hash = createHash('sha1').update(text).digest('hex').slice(0, 6)
+    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()) {
+      const id = `${slug(c.title)}-${hash}${doc.chapters.length > 1 ? `-${k + 1}` : ''}`.replace(/^-+/, '')
+      const existing = await getLesson(id)
+      if (existing && existing.status === 'ready') { out.push({ lessonId: id, existed: true, title: existing.title }); continue }
+      const lesson = existing || {
+        id, version: 1, kind: 'doc',
+        title: c.title, group: doc.title || o.group || '文档', order: k,
+        source: { type: 'doc', name: o.docName || doc.title, chars: text.length, ...(o.docId ? { docId: o.docId } : {}) },
+        status: 'queued', createdAt: Date.now(),
+        sentences: c.sentences.map((s, i) => ({ i, start: 0, end: 0, text: s.text, en: s.text, zh: '', words: [], sound: '', skip: false, para: s.para, ...(s.heading ? { heading: true } : {}) })),
+      }
+      if (!existing) await saveLesson(lesson)
+      this.enqueue({ kind: 'doc', lessonId: id, title: lesson.title, engine: o.engine, voice: o.voice, speed: o.speed })
+      out.push({ lessonId: id, existed: false, title: lesson.title, sentences: lesson.sentences.length })
+    }
+    return { title: doc.title, items: out }
+  }
+
   /** 补全翻译（缺翻译的句子、缺概述） */
   async resume(lessonId) {
     const l = await getLesson(lessonId)
     if (!l) throw Object.assign(new Error('没有这节课'), { status: 404 })
     if (this.jobs.some(j => j.lessonId === lessonId && (j.state === 'queued' || j.state === 'running'))) return
-    if (!l.sentences || !l.sentences.length) {
+    if (l.kind === 'doc' && !existsSync(audioPath(lessonId))) {
+      this.enqueue({ kind: 'doc', lessonId, title: l.title, engine: l.engine, voice: l.voice, speed: l.speed })
+    } else if (!l.sentences || !l.sentences.length) {
       const file = l.source && l.source.file
       if (!file || !existsSync(file)) throw Object.assign(new Error('原音频文件不在了，删掉这节课重新导入'), { status: 400 })
       this.enqueue({ kind: 'import', lessonId, title: l.title, file })
@@ -207,6 +291,50 @@ export class Importer {
   async run(job) {
     const signal = job.abort.signal
     const opt = this.opts()
+    if (job.kind === 'docprep') {
+      const dir = join(dataRoot(), 'docs', job.docId)
+      const meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf8'))
+      const raw = await readFile(join(dir, 'raw.txt'), 'utf8')
+      let text = raw
+      let warnings = []
+      if (meta.needsCleanup) {
+        const llm = this.deps.llm()
+        if (llm) {
+          this.stage(job, 'AI 整理文档', 0, Math.max(1, meta.estimate.chunks), '段')
+          const r = await cleanupText(llm, raw, { title: meta.title, signal, concurrency: opt.concurrency || 3, onProgress: (d, t) => this.stage(job, 'AI 整理文档', d, t, '段') })
+          text = r.text
+          warnings = r.warnings
+        } else {
+          text = plainTidy(raw)
+          warnings = ['没有可用的大模型：只简单接了断行，页眉页码可能还在']
+        }
+      }
+      await writeFile(join(dir, 'clean.md'), text)
+      const r = await this.importDoc(text, { title: meta.title, ...meta.voice, docId: job.docId, docName: meta.name })
+      Object.assign(meta, { cleanedAt: Date.now(), warnings, lessons: r.items.map(x => x.lessonId) })
+      await writeFile(join(dir, 'meta.json'), JSON.stringify(meta, null, 1))
+      if (warnings.length) job.message = warnings[0]
+      return
+    }
+
+    if (job.kind === 'doc') {
+      if (!existsSync(audioPath(job.lessonId))) {
+        const l = await getLesson(job.lessonId)
+        l.status = 'transcribing'; l.error = ''
+        await saveLesson(l)
+        const r = await buildDocAudio(l, {
+          ffmpeg: opt.ffmpeg, engine: job.engine, voice: job.voice, speed: job.speed, signal,
+          onStage: (stage, done, total, unit) => this.stage(job, stage, done, total, unit),
+        })
+        const fresh = await getLesson(job.lessonId)
+        for (const s of fresh.sentences) { const t = r.items[s.i]; if (t) { s.start = t[0]; s.end = t[1] } }
+        Object.assign(fresh, { duration: r.duration, engine: r.engine, voice: r.voice, voiceLabel: r.voiceLabel, speed: r.speed, status: 'translating' })
+        await saveLesson(fresh)
+      }
+      await this.translate(job, await getLesson(job.lessonId), signal)
+      return
+    }
+
     if (job.kind === 'send') {
       const cfg = await getVpsConfig()
       for (const [k, id] of job.ids.entries()) {
@@ -298,7 +426,7 @@ export class Importer {
     const total = l.sentences.filter(s => !s.zh && !s.skip).length
     this.stage(job, '翻译讲解', 0, total, '句')
     const res = await translateSentences(llm, l.sentences, {
-      hint, signal, concurrency: this.opts().concurrency || 3,
+      hint, signal, concurrency: this.opts().concurrency || 3, doc: l.kind === 'doc',
       onProgress: (d, t) => this.stage(job, '翻译讲解', d, t, '句'),
       onBatch: () => (signal.aborted ? null : saveLesson(l)),
     })
@@ -321,4 +449,3 @@ export class Importer {
     await saveLesson(l)
   }
 }
-

package/lib/server.js

@@ -8,6 +8,12 @@
 //   GET  <prefix>/voices                         能用的朗读声音（系统语音、Kokoro）
 //   GET  <prefix>/jobs                           导入任务
 //   POST <prefix>/import   {path, title?}        导入本机的文件或文件夹
+//   POST <prefix>/import-doc {text, title?, engine?, voice?, speed?}   导入整理好的英文文档（# 章节 分课），AI 朗读
+//   GET  <prefix>/doc-help                       导入文档的格式要求、给别的 AI 的整理指令
+//   POST <prefix>/doc/upload?name=               上传文档（PDF / Word / EPUB / 网页 / TXT / MD）→ 取出文字、存档、预估，等确认
+//   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   存档
 //   POST <prefix>/upload?name=                   上传音频（请求体就是文件）
 //   POST <prefix>/grade    {id, i, g}            给一句评分（0 没懂 / 1 半懂 / 2 懂了）
 //   POST <prefix>/resume | retranslate | reset | delete  {id}
@@ -32,14 +38,16 @@ import { mkdir, readFile, rm, stat } from 'node:fs/promises'
 import { extname, join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 import { findModels } from './models.js'
-import { findFfmpeg, uploadsDir } from './paths.js'
+import { dataRoot, findFfmpeg, uploadsDir } from './paths.js'
 import { AUDIO_EXT } from './importer.js'
 import { listTracks, trackAudio, trackFlac, TRACKS, zhSample } from './tracks.js'
 import { buildDrill, DRILL_RE } from './drill.js'
 import { explainSentences, lookupWord } from './lookup.js'
 import { today } from './today.js'
 import { exportText, FORMATS } from './export.js'
-import { EDGE_ZH_VOICES, edgeStatus, installEdge } from './edge.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 { 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'
@@ -53,6 +61,8 @@ const STATIC = {
 for (const name of ['panel', 'core', 'study', 'listen', 'edit', 'dict']) STATIC[`/${name}.js`] = [`web/${name}.js`, 'text/javascript; charset=utf-8']
 
 const MAX_UPLOAD = 2 * 1024 * 1024 * 1024
+const MAX_DOC_UPLOAD = 100 * 1024 * 1024
+const DOC_ID = /^[a-f0-9]{12}$/
 
 function send(res, status, body) {
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
@@ -161,7 +171,7 @@ export function createHandler(o) {
             say: await sayVoices(), sayHint: SAY_HINT,
             kokoro: { ready: await kokoroReady(), voices: KOKORO_VOICES },
             zh: { ready: await kokoroZhReady(), voices: ZH_VOICES.map(({ id, label, gender }) => ({ id, label, gender })) },
-            edge: { ...(await edgeStatus()), voices: EDGE_ZH_VOICES },
+            edge: { ...(await edgeStatus()), voices: EDGE_ZH_VOICES, en: EDGE_EN_VOICES },
           })
         }
         if (path === '/export') {
@@ -180,6 +190,26 @@ export function createHandler(o) {
           return res.end(out.text)
         }
         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/file') {
+          const id = q.get('id')
+          if (!DOC_ID.test(String(id))) return send(res, 400, { error: '文档编号不对' })
+          const dir = join(dataRoot(), 'docs', id)
+          let meta
+          try { meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf8')) } catch { return send(res, 404, { error: '没有这份文档' }) }
+          const which = q.get('which') === 'original' ? 'original' : q.get('which') === 'raw' ? 'raw' : 'clean'
+          const file = which === 'original' ? join(dir, `original${meta.ext}`) : join(dir, which === 'raw' ? 'raw.txt' : 'clean.md')
+          const base = (meta.title || meta.name || 'document').replace(/\.[a-z0-9]+$/i, '')
+          const filename = which === 'original' ? meta.name : `${base}${which === 'raw' ? '（原始文字）.txt' : '（整理后）.md'}`
+          let buf
+          try { buf = await readFile(file) } catch { return send(res, 404, { error: which === 'clean' ? '还没整理好' : '没有这个文件' }) }
+          res.writeHead(200, {
+            'content-type': which === 'original' ? 'application/octet-stream' : 'text/plain; charset=utf-8',
+            'content-disposition': `attachment; filename="document${extname(filename)}"; filename*=UTF-8''${encodeURIComponent(filename.replace(/[\\/:*?"<>|]/g, '_'))}`,
+            'cache-control': 'no-store',
+          })
+          return res.end(buf)
+        }
         if (path === '/update') {
           if (!o.manage) return send(res, 200, { managed: false })
           return send(res, 200, { managed: true, ...(await o.manage.info(q.get('force') === '1')) })
@@ -196,6 +226,19 @@ export function createHandler(o) {
 
       if (!safePost(req)) return send(res, 403, { error: '只接受本页面发出的请求' })
 
+      if (path === '/doc/upload') {
+        const name = String(q.get('name') || 'document.txt').replace(/[\\/]/g, '_').slice(0, 200)
+        const ext = extname(name).toLowerCase()
+        if (!DOC_EXT.includes(ext)) return send(res, 400, { error: '不支持这种文件：可以导入 PDF、Word（.docx）、EPUB、网页（.html）、TXT、Markdown' })
+        if (Number(req.headers['content-length'] || 0) > MAX_DOC_UPLOAD) return send(res, 413, { error: '文件太大（最多 100 MB）' })
+        await mkdir(uploadsDir(), { recursive: true })
+        const tmp = join(uploadsDir(), `${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`)
+        try { await pipeline(req, createWriteStream(tmp)) } catch (e) { await rm(tmp, { force: true }); throw e }
+        try {
+          return send(res, 200, { ok: true, doc: await o.importer.prepareDoc(tmp, { name, removeSource: true }) })
+        } finally { await rm(tmp, { force: true }) }
+      }
+
       if (path === '/upload') {
         const name = String(q.get('name') || 'audio.mp3').replace(/[\\/]/g, '_').slice(0, 200)
         const ext = extname(name).toLowerCase()
@@ -213,7 +256,44 @@ export function createHandler(o) {
         return send(res, 200, { ok: true, items })
       }
 
-      const body = await readJson(req)
+      // 导入文档的请求体是整篇文字，放宽到 2 MB；其余都是小参数
+      const body = await readJson(req, path === '/import-doc' ? 2 * 1024 * 1024 : 64 * 1024)
+      if (path === '/doc/text') {
+        if (typeof body.text !== 'string' || !body.text.trim()) return send(res, 400, { error: '没有文字' })
+        const title = typeof body.title === 'string' && body.title.trim() ? body.title.trim().slice(0, 120) : ''
+        return send(res, 200, { ok: true, doc: await o.importer.prepareDoc(null, { name: title || '粘贴的文字', title, text: body.text }) })
+      }
+      if (path === '/doc/confirm') {
+        const speed = Number(body.speed)
+        const meta = await o.importer.confirmDoc(String(body.docId || ''), {
+          title: typeof body.title === 'string' ? body.title.slice(0, 120) : '',
+          engine: body.engine === 'kokoro' ? 'kokoro' : 'edge',
+          voice: typeof body.voice === 'string' ? body.voice.slice(0, 60) : undefined,
+          speed: Number.isFinite(speed) && speed >= 0.6 && speed <= 1.4 ? speed : 1,
+        })
+        return send(res, 200, { ok: true, doc: meta })
+      }
+      if (path === '/doc/cancel') {
+        const id = String(body.docId || '')
+        if (!DOC_ID.test(id)) return send(res, 400, { error: '文档编号不对' })
+        const dir = join(dataRoot(), 'docs', id)
+        try {
+          const meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf8'))
+          if (!meta.confirmedAt) await rm(dir, { recursive: true, force: true }) // 确认过的是存档，不删
+        } catch { /* 本来就没有 */ }
+        return send(res, 200, { ok: true })
+      }
+      if (path === '/import-doc') {
+        if (typeof body.text !== 'string' || !body.text.trim()) return send(res, 400, { error: '没有文字：粘贴进来，或选一个 .txt / .md 文件' })
+        const speed = Number(body.speed)
+        const r = await o.importer.importDoc(body.text, {
+          title: typeof body.title === 'string' ? body.title.slice(0, 120) : '',
+          engine: body.engine === 'kokoro' ? 'kokoro' : 'edge',
+          voice: typeof body.voice === 'string' ? body.voice.slice(0, 60) : undefined,
+          speed: Number.isFinite(speed) && speed >= 0.6 && speed <= 1.4 ? speed : 1,
+        })
+        return send(res, 200, { ok: true, ...r })
+      }
       if (path === '/import') {
         if (typeof body.path !== 'string' || !body.path.trim()) return send(res, 400, { error: '请填音频文件或文件夹的路径' })
         const items = await o.importer.importPath(body.path, { title: typeof body.title === 'string' ? body.title.trim() : '' })

package/lib/store.js

@@ -215,6 +215,8 @@ export function summary(l, p) {
   const translated = (l.sentences || []).filter(s => s.zh || s.skip).length
   return {
     id: l.id,
+    kind: l.kind || 'audio',
+    voiceLabel: l.voiceLabel || '',
     title: l.title,
     titleZh: l.titleZh || '',
     group: l.group || '',

package/lib/tracks.js

@@ -17,7 +17,7 @@ import { fileURLToPath } from 'node:url'
 import { createEncoder, RATE } from './pcm.js'
 import { dataRoot, findFfmpeg, FFMPEG_HINT, lessonDir } from './paths.js'
 import { ensureKokoro, ensureKokoroZh, sayVoices, zhVoice } from './voices.js'
-import { edgeBin, edgeVoice } from './edge.js'
+import { edgeBin, edgeEnVoice, edgeVoice } from './edge.js'
 
 const WORKER = fileURLToPath(new URL('./tts-worker.js', import.meta.url))
 
@@ -218,6 +218,43 @@ async function buildZh(lesson, o) {
   return { flac: true, items: res.items, duration: res.duration, engine, voice: voice.id, voiceLabel: `${engine === 'edge' ? 'Edge ' : ''}${voice.label}`, speed: args.speed, align, squeezed: res.squeezed || 0 }
 }
 
+/**
+ * 文档课：把整课英文念成这一课的主音频（audio.mp3，相当于音频课的「原声」），并得出每句的时间
+ * engine：'edge'（默认，微软在线语音）或 'kokoro'（离线）
+ * @returns {Promise<{items, duration, engine, voice, voiceLabel, speed}>}
+ */
+export async function buildDocAudio(lesson, o = {}) {
+  const ffmpeg = findFfmpeg(o.ffmpeg)
+  if (!ffmpeg) throw new Error(FFMPEG_HINT)
+  const engine = o.engine === 'kokoro' ? 'kokoro' : 'edge'
+  let voice
+  let voiceLabel
+  let kokoroDir
+  if (engine === 'edge') {
+    if (!edgeBin()) throw Object.assign(new Error('还没装 Edge 语音组件：在导入文档的地方点「安装 Edge 语音组件」，或者改用 Kokoro'), { status: 400 })
+    const v = edgeEnVoice(o.voice)
+    voice = v.id
+    voiceLabel = `Edge ${v.label.replace(/（.*）/, '')}`
+  } else {
+    kokoroDir = await ensureKokoro({ signal: o.signal, onProgress: (g, t) => o.onStage && o.onStage('下载 Kokoro 语音模型', Math.round(g / 1048576), Math.round(t / 1048576), 'MB') })
+    voice = o.voice && !/^en-/.test(o.voice) ? o.voice : 'am_michael'
+    voiceLabel = `Kokoro ${voice}`
+  }
+  // 停顿：句与句之间 0.6 秒，换段 1.2 秒，小标题后 1 秒
+  const list = lesson.sentences
+  const sentences = list.map((s, k) => {
+    const prev = list[k - 1]
+    const pause = !prev ? 0 : prev.heading ? 1 : prev.para !== s.para ? 1.2 : 0.6
+    return { i: s.i, text: s.en || s.text, pause }
+  })
+  await mkdir(lessonDir(lesson.id), { recursive: true })
+  const out = join(lessonDir(lesson.id), 'audio.part.mp3')
+  const args = { engine: engine === 'edge' ? 'edge-en' : 'kokoro', mode: 'reading', voice, speed: o.speed || 1, sentences, kokoroDir, ffmpeg, out, threads: o.threads || 2, bitrate: '64k' }
+  const res = await runWorker(args, o, `朗读（${voiceLabel}）`)
+  await rename(out, trackAudio(lesson.id, 'full'))
+  return { items: res.items, duration: res.duration, engine, voice, voiceLabel, speed: args.speed }
+}
+
 /** 试听一个中文音色：同一句话，生成一次缓存起来 */
 const ZH_SAMPLE = '现在进入你的准备流程。首先，用你的能量转换盒，接着做共振调音。'
 export async function zhSample(voiceId, o = {}) {

package/lib/translate.js

@@ -48,9 +48,10 @@ export function cleanItem(raw) {
   }
 }
 
-function batchPrompt(context, items, hint) {
+function batchPrompt(context, items, hint, doc) {
   const lines = []
   if (hint) lines.push(`材料：${hint}`)
+  if (doc) lines.push('注意：这是书面文档（会用 AI 朗读给学生听），英文是准确的原文，不是语音识别：en 照抄原句，不要改；skip 一律 false。')
   if (context.length) {
     lines.push('前文（仅供参考，不用输出）：')
     for (const c of context) lines.push(`- ${c}`)
@@ -61,8 +62,8 @@ function batchPrompt(context, items, hint) {
 }
 
 /** 跑一批；返回 Map<i, item>（可能缺一些） */
-async function runBatch(llm, items, context, hint, signal) {
-  const text = await llm.complete({ system: SYSTEM, user: batchPrompt(context, items, hint), maxTokens: 16000, signal })
+async function runBatch(llm, items, context, hint, signal, doc) {
+  const text = await llm.complete({ system: SYSTEM, user: batchPrompt(context, items, hint, doc), maxTokens: 16000, signal })
   const json = extractJson(text)
   const got = new Map()
   for (const raw of Array.isArray(json.items) ? json.items : []) {
@@ -97,12 +98,13 @@ export async function translateSentences(llm, sentences, opt = {}) {
   const batches = []
   for (let k = 0; k < todo.length; k += size) batches.push(todo.slice(k, k + size))
 
+  // 文档课：英文是准确的书面原文，不让模型改；也没有「非讲话」
   const apply = (s, item) => {
-    s.en = item.en || s.text
+    s.en = opt.doc ? s.text : (item.en || s.text)
     s.zh = item.zh
     s.words = item.words
     s.sound = item.sound
-    s.skip = item.skip
+    s.skip = opt.doc ? false : item.skip
   }
   const contextFor = first => {
     const idx = sentences.indexOf(first)
@@ -118,7 +120,7 @@ export async function translateSentences(llm, sentences, opt = {}) {
       for (const part of parts) {
         if (opt.signal && opt.signal.aborted) throw new Error('已取消')
         try {
-          const got = await runBatch(llm, part, contextFor(part[0]), opt.hint, opt.signal)
+          const got = await runBatch(llm, part, contextFor(part[0]), opt.hint, opt.signal, opt.doc)
           for (const s of part) {
             const item = got.get(s.i)
             if (item && (item.zh || item.skip)) { apply(s, item); done++ } else still.push(s)

package/lib/tts-worker.js

@@ -152,10 +152,35 @@ async function timeline(opt, speak) {
   emit({ type: 'done', ...res, squeezed })
 }
 
+/**
+ * 文档朗读：一句接一句，停顿由每句的 pause（这句之前停几秒）决定——
+ * 句与句之间短、段落之间长，小标题后面也停一下，听起来像人在念书
+ */
+async function reading(opt, speak) {
+  const enc = createEncoder({ ffmpeg: opt.ffmpeg, out: opt.out, gap: 0, bitrate: opt.bitrate })
+  const list = (opt.sentences || []).map(s => ({ ...s, text: tidy(s.text) })).filter(s => s.text)
+  const AHEAD = opt.engine === 'edge-en' ? 4 : 1
+  const pending = []
+  let next = 0
+  const fill = () => { while (next < list.length && pending.length < AHEAD) { const p = speak(list[next++].text); p.catch(() => {}); pending.push(p) } }
+  fill()
+  for (const [k, s] of list.entries()) {
+    const pcm = await pending.shift()
+    fill()
+    if (k) await enc.pad(s.pause ?? 0.6)
+    await enc.write(s.i, pcm)
+    emit({ type: 'progress', done: k + 1, total: list.length })
+  }
+  const res = await enc.finish()
+  emit({ type: 'done', ...res })
+}
+
 async function main() {
   const opt = JSON.parse(process.argv[2] || '{}')
   if (opt.engine === 'kokoro-zh') return timeline(opt, kokoroZhEngine(opt))
   if (opt.engine === 'edge-zh') return timeline(opt, edgeEngine(opt))
+  if (opt.engine === 'edge-en') return reading(opt, edgeEngine(opt))
+  if (opt.mode === 'reading') return reading(opt, kokoroEngine(opt))
   const speak = opt.engine === 'kokoro' ? kokoroEngine(opt) : sayEngine(opt)
   const enc = createEncoder({ ffmpeg: opt.ffmpeg, out: opt.out, gap: opt.gap ?? 0.7 })
   const list = (opt.sentences || []).map(s => ({ i: s.i, text: tidy(s.text) })).filter(s => s.text)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-tingdong",
-  "version": "0.3.1",
-  "description": "听懂：把英文有声读物 MP3 变成听力课。本地识别每一句英文、AI 翻译讲解，再用盲听、精听、间隔复习把它练到「一听就懂」。DeepSeek Harness (dsh) 插件。",
+  "version": "0.5.0",
+  "description": "听懂：把英文有声读物（MP3）或英文文档变成听力课。本地识别 / AI 朗读每一句英文、AI 翻译讲解，再用盲听、精听、间隔复习把它练到「一听就懂」。DeepSeek Harness (dsh) 插件。",
   "keywords": [
     "dsh-plugin",
     "dsh-plugins",
@@ -54,7 +54,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "sherpa-onnx-node": "1.13.8"
+    "sherpa-onnx-node": "1.13.8",
+    "unpdf": "1.9.1"
   },
   "dsh": {
     "bundle": {

package/plugin/client.js

@@ -3,7 +3,7 @@
 //
 // 手写单文件 bundle，没有构建链：由 dsh web 客户端的 ModuleLoader 注入（写法照 dsh-pick）。挂两处：
 //   - 对话页右侧栏的一个页签：整个学习面板（iframe 指向宿主路由 /api-dsh-tingdong/panel）
-//   - 「设置 → 听懂」：状态（ffmpeg、识别模型、翻译模型）和用法
+//   - 「设置 → 听懂」：版本、更新、卸载，状态（ffmpeg、识别模型、翻译模型）和用法
 // 面板本身是独立调好的页面（dsh-tingdong serve 也能直接打开），这里原样复用。
 // 硬约束：界面崩了不能影响 dsh，注册一律包在 try/catch 里。
 
@@ -25,18 +25,115 @@ window.__ModuleLoader__.load({
       border: 'var(--dsw-alias-border-l3, rgba(127,127,127,.25))',
       good: '#1f9d55',
       warn: '#c98a12',
+      accent: 'var(--dsw-alias-link, #2f6bff)',
+      danger: '#c94040',
     }
 
-    function Btn({ onClick, children }) {
+    function Btn({ onClick, disabled, primary, danger, title, children }) {
       return h('button', {
-        type: 'button', onClick,
+        type: 'button', onClick, disabled, title,
         style: {
           appearance: 'none', fontFamily: 'inherit', fontSize: 12, lineHeight: '18px', padding: '2px 10px',
-          borderRadius: 6, cursor: 'pointer', border: '1px solid ' + C.border, background: 'transparent', color: C.text,
+          borderRadius: 6, cursor: disabled ? 'default' : 'pointer', opacity: disabled ? 0.6 : 1, whiteSpace: 'nowrap',
+          border: '1px solid ' + (danger ? C.danger : primary ? C.accent : C.border),
+          background: primary ? C.accent : 'transparent',
+          color: primary ? '#fff' : danger ? C.danger : C.text,
         },
       }, children)
     }
 
+    async function api(path, method = 'GET') {
+      const r = await fetch('/api-dsh-tingdong/' + path, {
+        method, credentials: 'same-origin',
+        headers: method === 'POST' ? { 'content-type': 'application/json', 'x-tingdong': '1' } : undefined,
+        body: method === 'POST' ? '{}' : undefined,
+      })
+      return r.json()
+    }
+
+    /** 给用户自己在终端执行的命令：等宽显示，旁边一个「复制」 */
+    function CommandLine({ command }) {
+      const [copied, setCopied] = useState(false)
+      const copy = async () => {
+        try { await navigator.clipboard.writeText(command) } catch {
+          const ta = document.createElement('textarea')
+          ta.value = command
+          ta.style.position = 'fixed'
+          ta.style.opacity = '0'
+          document.body.appendChild(ta)
+          ta.select()
+          try { document.execCommand('copy') } catch { /* 实在不行用户还能手动选 */ }
+          ta.remove()
+        }
+        setCopied(true)
+        setTimeout(() => setCopied(false), 2000)
+      }
+      return h('div', { style: { display: 'flex', alignItems: 'center', gap: 6, marginTop: 6, flexWrap: 'wrap' } },
+        h('code', { style: { flex: '1 1 auto', minWidth: 0, padding: '4px 8px', borderRadius: 6, fontSize: 12, color: C.text, border: '1px solid ' + C.border, userSelect: 'all', overflowWrap: 'anywhere' } }, command),
+        h(Btn, { onClick: copy }, copied ? '已复制' : '复制'))
+    }
+
+    /**
+     * 标题行：听懂 · 版本号 · 更新 ……（最右）卸载
+     * 打开设置页时自动去 npm 查新版本；更新、卸载交给 DSH 的插件管理器（宿主路由 /update、/uninstall）
+     */
+    function HeaderBar() {
+      const [info, setInfo] = useState(null)
+      const [phase, setPhase] = useState('checking') // checking | idle | updating | updated | removing | removed
+      const [confirm, setConfirm] = useState(false)
+      const [msg, setMsg] = useState(null) // { text, command?, ok? }
+      const check = (force) => {
+        setPhase('checking')
+        api('update' + (force ? '?force=1' : '')).then(j => { setInfo(j); setPhase('idle') }).catch(() => setPhase('idle'))
+      }
+      useEffect(() => { check(false) }, [])
+      const update = async () => {
+        setPhase('updating'); setMsg(null)
+        try {
+          const j = await api('update', 'POST')
+          setMsg({ text: j.message, command: j.command, ok: j.ok })
+          if (j.ok) { setPhase('updated'); return }
+        } catch (e) { setMsg({ text: '更新请求失败：' + e.message }) }
+        setPhase('idle')
+      }
+      const uninstall = async () => {
+        setConfirm(false); setPhase('removing'); setMsg(null)
+        try {
+          const j = await api('uninstall', 'POST')
+          setMsg({ text: j.message, command: j.command, ok: j.ok })
+          setPhase(j.ok ? 'removed' : 'idle')
+        } catch {
+          // 卸下插件时它自己的接口也随之消失，请求多半就是这么断的
+          setPhase('removed')
+        }
+      }
+      let upd
+      if (phase === 'updating') upd = { label: '正在更新…', disabled: true }
+      else if (phase === 'updated') upd = { label: '已更新，重启 DSH 生效', disabled: true }
+      else if (info && info.restartPending) upd = { label: `v${info.restartPending} 已装好，重启 DSH 生效`, disabled: true }
+      else if (info && info.available) upd = { label: `更新到 v${info.latest}`, primary: true, onClick: update }
+      else if (phase === 'checking') upd = { label: '检查更新…', disabled: true }
+      else upd = { label: info && info.latest ? '已是最新' : '检查更新', onClick: () => check(true), title: '点一下重新检查' }
+      const busy = phase === 'updating' || phase === 'removing' || phase === 'removed'
+      const managed = !info || info.managed !== false
+      return h('div', { style: { marginBottom: 8 } },
+        h('div', { style: { display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' } },
+          h('span', { style: { fontSize: 15, fontWeight: 650 } }, '听懂'),
+          info && info.running ? h('span', { style: { fontSize: 12, color: C.sub, fontVariantNumeric: 'tabular-nums' } }, 'v' + info.running) : null,
+          managed ? h(Btn, { onClick: upd.onClick, disabled: upd.disabled || busy, primary: upd.primary, title: upd.title }, upd.label) : null,
+          h('span', { style: { flex: 1 } }),
+          !managed ? null
+            : phase === 'removed' ? h('span', { style: { fontSize: 12, color: C.sub } }, '已卸载，重启 DSH 后彻底移除')
+            : phase === 'removing' ? h('span', { style: { fontSize: 12, color: C.sub } }, '正在卸载…')
+            : confirm ? h('span', { style: { display: 'inline-flex', gap: 6, alignItems: 'center' } },
+                h('span', { style: { fontSize: 12, color: C.sub } }, '确定卸载？课程和进度会保留'),
+                h(Btn, { danger: true, onClick: uninstall }, '确认卸载'),
+                h(Btn, { onClick: () => setConfirm(false) }, '取消'))
+            : h(Btn, { danger: true, disabled: busy, onClick: () => setConfirm(true) }, '卸载')),
+        msg ? h('div', { style: { fontSize: 12, color: msg.ok ? C.sub : C.danger, marginTop: 6, lineHeight: 1.6 } },
+          msg.text, msg.command ? h(CommandLine, { command: msg.command }) : null) : null)
+    }
+
     /** 右侧栏：占满栏高的 iframe */
     function Panel() {
       return h('div', { style: { height: '100%', display: 'flex', flexDirection: 'column', boxSizing: 'border-box' } },
@@ -68,9 +165,7 @@ window.__ModuleLoader__.load({
         catch { setMsg('先回到一个对话，再从右侧栏打开') }
       }
       return h('div', { style: { color: C.text } },
-        h('div', { style: { display: 'flex', alignItems: 'center', gap: 8 } },
-          h('span', { style: { fontSize: 15, fontWeight: 650 } }, '听懂'),
-          st && st.version ? h('span', { style: { fontSize: 12, color: C.sub } }, 'v' + st.version) : null),
+        h(HeaderBar),
         h('div', { style: { fontSize: 12.5, color: C.sub, lineHeight: 1.7, marginTop: 6 } },
           '把英文有声读物（MP3）变成听力课：本机识别每一句英文，AI 翻译讲解，再用盲听、精听、间隔复习练到一听就懂。'),
         h('div', { style: { marginTop: 14 } },