dsh-tingdong 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIcivilization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# 听懂 · dsh-tingdong
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把英文有声读物（MP3）变成听力课，练到**听到英文就知道是什么意思**。
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）插件，也能脱离 DSH 单独用。
+
+## 它做什么
+
+1. **导入**：选一个 MP3（或整个文件夹），本机识别出每一句英文和它的起止时间。
+   识别用的是 DSH 自带语音输入的同一套模型（SenseVoice + Silero VAD），音频不上传；用过 DSH 语音输入就不用再下载。
+2. **讲解**：用你在 DSH 里选的大模型逐句校对英文（修正识别错误，如 "resna tuning" → "resonant tuning"）、
+   翻成口语化中文、挑出生词（带音标）、写一句「听音提示」（哪里连读、弱读、吞音），再写全篇概述和关键术语表。
+3. **练习**（右侧栏「听懂」页签，或手机浏览器直接打开）：
+
+| 模式 | 做法 |
+| --- | --- |
+| 今日学习 | 首页一个按钮：所有课里该复习的句子 + 每天 10 句新句子串成一组；显示连续学习天数、今天学了几句、约几分钟、最近 7 天 |
+| 精听 | 每句先**只听不看**猜意思 → 看英文找出没听出来的词（**点任意一个词看意思**）→ 看中文和生词 → 再听一遍 → 自评「没听懂 / 半懂 / 听懂了」 |
+| 复习 | 间隔重复，三种考法：**自评**、**选意思**（只听声音，三选一）、**听写**（打出来，逐词标出没听出来的）。没听懂的一分钟后再来，听懂的隔 10 分钟、1 天、3 天、7 天…再考；7 天后还能听懂算掌握。可以只练「收藏」或「难句」 |
+| 磨耳朵 | 不用动手：每句放 1–4 遍，停几秒让你想意思，再接下一句；字幕可以逐步显示（第 1 遍不看字 → 第 2 遍英文 → 想的时候中文）。做成一段真正的音频，**锁屏也能一直放**，耳机线控切句，也能下载 |
+| 连续听 | 一句接一句不停地播，英文 / 中文字幕分别开关；最后关掉字幕整篇听 |
+| 词汇 | 全篇关键术语、每句的生词、你查过的词，点一下听原句 |
+
+**导出**（每课的「导出」页签）：
+
+- **中文配音（音频）**：可以下载 **MP3** 或无损 **FLAC**（44.1 kHz / 16 位，和合成出来的原始音频同源，不是 MP3 转的）。把英文换成中文配音，只有中文、没有背景音，每句中文从对应英文开始的时刻开始说，总长和原音频一样（也可以对齐「原声·去空白」）。比空档长的句子自动读快一点（最快 1.6 倍），不会挤到下一句。两种语音可选：
+  - **本地 Kokoro**：离线，55 个普通话女声、45 个普通话男声，每个都能先试听；第一次用时下载约 147 MB 模型
+  - **微软 Edge**：晓晓、云希、云扬等 14 种（含台湾、粤语、方言），要联网。插件调用开源工具 [edge-tts](https://github.com/rany2/edge-tts)，点「安装 Edge 语音组件」会装进插件自己的 Python 虚拟环境（需要电脑上有 Python 3）。文字会发到微软的服务器；这不是微软公开的正式接口，可能失效
+- **文字**：双语 / 英文 / 中文字幕（SRT）、双语歌词 LRC（Walkman 等播放器滚动显示）、**录音稿**（每句的开始时间、英文时长、可用时长和中英对照，照着自己录中文配音）、表格 CSV。时间可按原音频或「原声·去空白」
+
+卡片右上角 ☆ 收藏，复习和磨耳朵里可以只练收藏的
+- **改句子**：识别偶尔认错字、切错句，卡片右上角 ✎ 可以改英文 / 中文、和下一句合并、拆成两句、重新讲解、标为非讲话
+- **换设备接着学**：学到第几句、选的哪种声音、复习进度都存在服务器上
+- **手机**：按钮加大，左右滑动换句，评分按钮固定在底部，锁屏界面和耳机线控可以播放 / 暂停 / 换句
+
+**声音**：同一课可以换声音听，在课程页上方切换，每种都能下载成 MP3 放到手机上：
+
+| 声音 | 说明 |
+| --- | --- |
+| 原声（完整） | 原始音频，含背景音乐和长空白 |
+| 原声·去空白 | 只留讲话，句间停 0.7 秒。34 分钟的引导冥想剩 11 分 40 秒 |
+| 原声·压背景 | 同上，再滤掉低沉的双耳节拍和高频噪声 |
+| 系统朗读 | macOS 自带语音读校对后的英文；在系统设置里下载「高级 / 增强」英文语音后会自动用上 |
+| Kokoro 朗读 | 离线神经网络语音（11 种美式 / 英式男女声，可调语速），第一次用时下载约 103 MB 模型 |
+
+新导入的课会自动生成两条原声轨，朗读的声音在「概览 → 声音」里点「生成」。
+
+电脑快捷键：空格 重听 · 回车 下一步 · 1/2/3 评分 · ←/→ 上一句/下一句 · S 变速（1× / 0.85× / 0.7×）· L 单句循环
+
+在 DSH 对话里也可以直接说：「把 /Volumes/…/CD4 导入听懂」「我这课哪些句子总听不懂？给我讲讲」——插件给 AI 注册了 `tingdong_import`、`tingdong_lessons`、`tingdong_sentences` 三个工具。
+
+**更新 / 卸载**：首页标题旁显示版本号，打开时自动查 npm 上有没有新版本；有就出现「更新到 vX」，点一下由 DSH 的插件管理器装好（和插件市场同一套机制），重启 DSH 生效。「卸载」只移除插件，课程和学习进度留在 `~/.dsh/dsh-tingdong`。
+
+## 安装
+
+需要 [ffmpeg](https://ffmpeg.org)（解码 MP3）：Mac 上 `brew install ffmpeg`。
+
+装进 DSH（把 `desktop` 换成你的 profile 名；先完全退出 DSH）：
+
+```bash
+dsh plugin --profile desktop add /path/to/dsh-go
+```
+
+重新打开 DSH，在对话页打开右侧栏，选「听懂 · 英文听力」。设置里的「听懂」分区会显示 ffmpeg、识别模型、翻译模型是否就绪。
+
+### 可选配置
+
+在 profile 的 `cordis.patch.yml` 里：
+
+```yaml
+- id: dsh-tingdong
+  config:
+    provider: dsh-model-workbuddy-ai   # 翻译用的模型；不填就用 DSH 的默认模型
+    model: workbuddy-ai/deepseek-v4.1-flash-sg
+    ffmpeg: /opt/homebrew/bin/ffmpeg   # 找不到 ffmpeg 时填
+    threads: 2                         # 识别线程数
+```
+
+## 用手机学（VPS）
+
+在电脑上做课（识别、翻译、生成声音都很吃 CPU），发到 VPS 上的 DSH，手机浏览器打开学习：
+
+1. VPS 上装好 DSH（比如用 [dsh-vps](https://github.com/AIcivilization/dsh-vps)），也装上本插件：
+   `dsh plugin --profile web add dsh-tingdong`（以运行 DSH 的用户执行，再重启 DSH）。VPS 上不需要 ffmpeg。
+2. 电脑上的「听懂」首页底部「手机学习（VPS）」：选 SSH 主机（`~/.ssh/config` 里的，要能用钥匙免密码登录）→「查找 VPS 上的 DSH」→ 选一个。
+3. 点「全部发送到 VPS」，或在每课「管理」里单独发送。只发课程内容和声音，**不会覆盖 VPS 上的学习进度**。
+4. 手机打开 `https://<你的域名>/api-dsh-tingdong/panel`（首页会显示这个地址），可以「添加到主屏幕」当 App 用。
+
+发送走 SSH（tar 流解到 VPS 上 DSH 用户的 `~/.dsh/dsh-tingdong/lessons/`），不经过网页登录门。
+
+## 不开 DSH 也能用
+
+```bash
+node bin/dsh-tingdong.js import "/Volumes/kuozhan/门罗/CD4"     # 整个文件夹，每个音频一课
+node bin/dsh-tingdong.js serve                                   # 打开 http://127.0.0.1:4810
+node bin/dsh-tingdong.js list
+node bin/dsh-tingdong.js voices all --track kokoro --voice am_michael   # 批量生成声音轨
+```
+
+命令行版的模型：`--base-url / --api-key / --model`，或环境变量 `TINGDONG_BASE_URL / TINGDONG_API_KEY / TINGDONG_MODEL`（任何 OpenAI 兼容接口）；都没给就用本机的 dsh-model 网关。
+
+## 数据
+
+都在 `~/.dsh/dsh-tingdong/lessons/<课程>/`：`lesson.json`（句子、翻译、讲解、查过的词）、`progress.json`（复习进度、学到第几句、选的声音、收藏）、`audio.mp3`（压缩成 64 kbps 单声道，原文件所在的移动硬盘拔掉也能听）、`tracks/`（各种声音和它们的时间表）。
+模型在 `~/.dsh/dsh-tingdong/models/`（Kokoro 英文、Kokoro 中文）；Edge 语音组件在 `~/.dsh/dsh-tingdong/edge-tts/`；识别模型优先复用 DSH 语音输入下好的。
+DSH 插件和命令行版共用这份数据。
+
+## 实测
+
+Hemi-Sync Gateway Wave IV「Adventure 1 (One Year Patterning)」，34 分钟 MP3（大段音乐 + 引导语）：
+识别 16 秒（M 系列 Mac，4 线程），切出 96 句，模型判出 6 处音乐里的杂音并跳过；DeepSeek 翻译讲解约 1 分钟。
+
+## 开发
+
+```bash
+npm install
+npm test
+```
+
+- `lib/asr-worker.js` 识别子进程（sherpa-onnx 是同步推理，放在 DSH 主进程里会卡界面）
+- `lib/translate.js` 校对 + 翻译 + 生词 + 听音提示；缺句自动缩小批次重试，失败的留空，之后可「补全翻译」
+- `lib/tracks.js` 声音轨：原声按句截取拼接；朗读交给 `lib/tts-worker.js` 子进程（Kokoro / macOS say），`lib/pcm.js` 统一拼接编码并出时间表
+- `lib/srs.js` 间隔复习；`lib/store.js` 原子写入的 JSON 存储；`lib/today.js` 今日学习（按用户时区算日期）
+- `lib/export.js` 文字导出；`lib/edge.js` Edge 语音组件（edge-tts）的安装和调用
+- `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` 播放器和公共状态

package/bin/dsh-tingdong.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// bin/dsh-tingdong.js — 不开 DSH 也能用：导入音频、打开学习面板
+//
+//   dsh-tingdong import <文件或文件夹> [--title 标题]   识别 + 翻译，做成课
+//   dsh-tingdong serve [--port 4810]                    在浏览器里打开学习面板
+//   dsh-tingdong list                                   看有哪些课
+//   dsh-tingdong voices <课程id|all> [--track clean,cleannr,say,kokoro] [--voice 名字] [--speed 0.9]
+//                                                       生成声音轨（去空白原声 / 压背景 / 系统朗读 / Kokoro）
+//
+// 模型：--base-url / --api-key / --model，或环境变量 TINGDONG_BASE_URL / TINGDONG_API_KEY / TINGDONG_MODEL；
+// 都没有就用本机的 dsh-model 网关。
+
+import { createServer } from 'node:http'
+import { fileURLToPath } from 'node:url'
+import { cliLlm } from '../lib/cli-llm.js'
+import { Importer } from '../lib/importer.js'
+import { createHandler } from '../lib/server.js'
+import { listLessons } from '../lib/store.js'
+
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url))
+const PREFIX = '/api-dsh-tingdong'
+
+function parse(argv) {
+  const flags = {}
+  const rest = []
+  for (let k = 0; k < argv.length; k++) {
+    const a = argv[k]
+    if (a.startsWith('--')) {
+      const [key, val] = a.slice(2).split('=', 2)
+      if (val !== undefined) flags[key] = val
+      else if (argv[k + 1] && !argv[k + 1].startsWith('--')) flags[key] = argv[++k]
+      else flags[key] = true
+    } else rest.push(a)
+  }
+  return { flags, rest }
+}
+
+const fmtTime = s => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`
+
+async function main() {
+  const { flags, rest } = parse(process.argv.slice(2))
+  const cmd = rest.shift()
+  const options = () => ({ ffmpeg: flags.ffmpeg, threads: Number(flags.threads) || 4 })
+
+  if (cmd === 'list') {
+    for (const l of await listLessons()) {
+      const s = l.stats
+      console.log(`${l.id}  ${l.titleZh || l.title}  [${l.status}]  ${fmtTime(l.duration)}  ${l.sentences} 句  掌握 ${s.mastered}/${s.total}  待复习 ${s.due}`)
+    }
+    return
+  }
+
+  if (cmd === 'voices') {
+    const which = rest[0]
+    if (!which) throw new Error('用法：dsh-tingdong voices <课程id|all> [--track clean,cleannr,say,kokoro]')
+    const ids = which === 'all' ? (await listLessons()).filter(l => l.sentences).map(l => l.id) : [which]
+    const tracks = String(typeof flags.track === 'string' ? flags.track : 'clean,cleannr,say,kokoro').split(',').map(x => x.trim()).filter(Boolean)
+    const importer = new Importer({ llm: () => null, options, log: m => console.error(m) })
+    let last = ''
+    importer.onChange(() => {
+      for (const j of importer.list()) {
+        if (j.state !== 'running') continue
+        const key = `${j.id}|${j.stage}|${j.total ? Math.floor(j.done / j.total * 4) : 0}`
+        if (key !== last) { last = key; console.log(`${j.title}：${j.stage}${j.total ? ` ${j.done}/${j.total}` : ''}`) }
+      }
+    })
+    for (const id of ids) for (const t of tracks) {
+      await importer.makeTrack(id, t, { voice: typeof flags.voice === 'string' ? flags.voice : undefined, speed: flags.speed ? Number(flags.speed) : undefined })
+    }
+    await new Promise(resolve => {
+      const check = () => { if (!importer.running && !importer.jobs.some(j => j.state === 'queued')) resolve() }
+      importer.onChange(() => setImmediate(check))
+      check()
+    })
+    for (const j of importer.list()) console.log(`${j.state === 'done' ? '✓' : '✗'} ${j.title}${j.error ? '：' + j.error : ''}`)
+    return
+  }
+
+  if (cmd === 'import') {
+    if (!rest[0]) throw new Error('用法：dsh-tingdong import <文件或文件夹>')
+    const llm = await cliLlm(flags)
+    console.log(llm ? `翻译模型：${llm.label()}（${llm.via}）` : '没有可用的大模型：只做英文识别，之后用 serve 打开面板点「补全翻译」')
+    const importer = new Importer({ llm: () => llm, options, log: m => console.error(m) })
+    // 只在换阶段、或进度每过 20% 时打一行
+    let last = ''
+    importer.onChange(() => {
+      for (const j of importer.list()) {
+        if (j.state !== 'running') continue
+        const step = j.total ? Math.floor(j.done / j.total * 5) : 0
+        const key = `${j.id}|${j.stage}|${step}`
+        if (key === last) continue
+        last = key
+        console.log(`${j.title}：${j.stage}${j.total ? ` ${j.done}/${j.total} ${j.message || ''}` : ''}`)
+      }
+    })
+    const items = await importer.importPath(rest[0], { title: typeof flags.title === 'string' ? flags.title : '' })
+    for (const it of items) if (it.existed) console.log(`已经导入过：${it.title}（${it.lessonId}）`)
+    await new Promise(resolve => {
+      const check = () => { if (!importer.running && !importer.jobs.some(j => j.state === 'queued')) resolve() }
+      importer.onChange(() => setImmediate(check))
+      check()
+    })
+    for (const j of importer.list()) console.log(`${j.state === 'done' ? '✓' : '✗'} ${j.title}${j.error ? '：' + j.error : ''}`)
+    for (const l of await listLessons()) if (items.some(it => it.lessonId === l.id)) {
+      console.log(`  ${l.titleZh || l.title}：${l.sentences} 句，已翻译 ${l.translated}${l.note ? '；' + l.note : ''}`)
+    }
+    return
+  }
+
+  if (cmd === 'serve') {
+    const llm = await cliLlm(flags)
+    const importer = new Importer({ llm: () => llm, options, log: m => console.error(m) })
+    const handle = createHandler({
+      prefix: PREFIX, pkgRoot: PKG_ROOT, importer, options,
+      status: () => ({ host: 'cli', llm: llm ? llm.label() : '' }),
+    })
+    const port = Number(flags.port) || 4810
+    const server = createServer((req, res) => {
+      if (req.url === '/' || req.url === '') { res.writeHead(302, { location: PREFIX + '/panel' }); return res.end() }
+      if (!String(req.url).startsWith(PREFIX)) { res.writeHead(404); return res.end() }
+      handle(req, res)
+    })
+    server.listen(port, '127.0.0.1', () => {
+      console.log(`学习面板：http://127.0.0.1:${port}${PREFIX}/panel`)
+      console.log(llm ? `翻译模型：${llm.label()}（${llm.via}）` : '没有可用的大模型：导入后只有英文')
+    })
+    return
+  }
+
+  console.log(`听懂 dsh-tingdong — 把英文有声读物变成听力课
+
+  dsh-tingdong import <文件或文件夹> [--title 标题]
+  dsh-tingdong serve [--port 4810]
+  dsh-tingdong list
+  dsh-tingdong voices <课程id|all> [--track clean,cleannr,say,kokoro] [--voice 名字] [--speed 0.9]
+
+  模型：--base-url URL --api-key KEY --model ID（或 TINGDONG_BASE_URL / TINGDONG_API_KEY / TINGDONG_MODEL）
+  其他：--ffmpeg <ffmpeg 路径>  --threads <识别线程数，默认 4>`)
+}
+
+main().catch(e => { console.error(e.message || e); process.exit(1) })

package/lib/asr-worker.js

@@ -0,0 +1,111 @@
+// lib/asr-worker.js — 识别子进程：ffmpeg 解码 → Silero VAD 切句 → SenseVoice 识别
+//
+// sherpa-onnx 的推理是同步的，放在 DSH 主进程里会卡住整个界面，所以单独起一个进程
+// （和 DSH 自带语音输入的做法一样：process.execPath + ELECTRON_RUN_AS_NODE=1）。
+// 音频边解码边处理，内存占用和音频长短无关。
+//
+// 输入：argv[2] 是 JSON 参数。输出：stdout 每行一个 JSON 事件：
+//   {type:'duration', seconds}  {type:'progress', seconds}  {type:'segment', start, end, text}
+//   {type:'done', segments, inferenceSeconds}  {type:'error', message}
+
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+
+const RATE = 16000
+const WINDOW = 512
+
+const emit = obj => process.stdout.write(JSON.stringify(obj) + '\n')
+
+function main() {
+  const opt = JSON.parse(process.argv[2] || '{}')
+  const sherpa = createRequire(import.meta.url)('sherpa-onnx-node')
+  const threads = opt.threads || 2
+
+  const recognizer = new sherpa.OfflineRecognizer({
+    featConfig: { sampleRate: RATE, featureDim: 80 },
+    modelConfig: {
+      senseVoice: { model: opt.models.model, language: opt.language || 'en', useInverseTextNormalization: 1 },
+      tokens: opt.models.tokens, numThreads: threads, provider: 'cpu', debug: 0,
+    },
+  })
+  const maxSpeech = opt.maxSpeechSeconds || 20
+  const minSilence = opt.minSilenceSeconds || 0.6
+  const vad = new sherpa.Vad({
+    sileroVad: {
+      model: opt.models.vad, threshold: opt.vadThreshold || 0.5, minSilenceDuration: minSilence,
+      minSpeechDuration: 0.25, maxSpeechDuration: maxSpeech, windowSize: WINDOW,
+    },
+    sampleRate: RATE, numThreads: 1, provider: 'cpu', debug: 0,
+  }, maxSpeech + minSilence + 5)
+
+  let count = 0
+  let inference = 0
+  const drain = () => {
+    while (!vad.isEmpty()) {
+      const seg = vad.front(false)
+      const t0 = performance.now()
+      const stream = recognizer.createStream()
+      stream.acceptWaveform({ sampleRate: RATE, samples: seg.samples })
+      recognizer.decode(stream)
+      const text = recognizer.getResult(stream).text.trim()
+      inference += performance.now() - t0
+      if (text) {
+        count++
+        emit({ type: 'segment', start: seg.start / RATE, end: (seg.start + seg.samples.length) / RATE, text })
+      }
+      vad.pop()
+    }
+  }
+
+  const ff = spawn(opt.ffmpeg, ['-hide_banner', '-nostdin', '-i', opt.file, '-vn', '-ac', '1', '-ar', String(RATE), '-f', 'f32le', 'pipe:1'],
+    { stdio: ['ignore', 'pipe', 'pipe'] })
+  let stderr = ''
+  ff.stderr.on('data', d => {
+    stderr = (stderr + d.toString('utf8')).slice(-8000)
+    const m = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(stderr)
+    if (m && !main.sentDuration) { main.sentDuration = true; emit({ type: 'duration', seconds: +m[1] * 3600 + +m[2] * 60 + +m[3] }) }
+  })
+
+  let carry = Buffer.alloc(0)
+  let fed = 0
+  let lastReport = 0
+  let pending = new Float32Array(0)
+  ff.stdout.on('data', chunk => {
+    const buf = carry.length ? Buffer.concat([carry, chunk]) : chunk
+    const usable = buf.length - (buf.length % 4)
+    carry = buf.subarray(usable)
+    // 复制一份：Electron 的 V8 内存笼不允许直接把 Node Buffer 交给原生代码
+    const fresh = new Float32Array(usable / 4)
+    new Uint8Array(fresh.buffer).set(buf.subarray(0, usable))
+    let samples = fresh
+    if (pending.length) { samples = new Float32Array(pending.length + fresh.length); samples.set(pending); samples.set(fresh, pending.length) }
+    let i = 0
+    for (; i + WINDOW <= samples.length; i += WINDOW) {
+      vad.acceptWaveform(samples.subarray(i, i + WINDOW))
+      drain()
+    }
+    pending = samples.slice(i)
+    fed += usable / 4
+    if (fed - lastReport > RATE * 10) { lastReport = fed; emit({ type: 'progress', seconds: fed / RATE }) }
+  })
+  ff.on('error', e => { emit({ type: 'error', message: `ffmpeg 启动失败：${e.message}` }); process.exit(1) })
+  ff.on('close', code => {
+    if (code !== 0) {
+      emit({ type: 'error', message: `ffmpeg 解码失败（${code}）：${stderr.trim().split('\n').slice(-2).join(' ')}` })
+      process.exit(1)
+    }
+    if (pending.length) vad.acceptWaveform(pending)
+    vad.flush()
+    drain()
+    emit({ type: 'progress', seconds: fed / RATE })
+    emit({ type: 'done', segments: count, inferenceSeconds: inference / 1000 })
+    process.exit(0)
+  })
+}
+
+try {
+  main()
+} catch (e) {
+  emit({ type: 'error', message: e && e.message ? e.message : String(e) })
+  process.exit(1)
+}

package/lib/asr.js

@@ -0,0 +1,116 @@
+// lib/asr.js — 在子进程里识别一个音频文件，返回带时间的句子；顺手做压缩音频
+//
+// 识别结果先按 VAD 切出来的片段给，再用 mergeSegments() 拼成适合练听力的句子：
+// 太碎的（"First." "Next."）和后一句接上，太长的不拼。
+
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { findFfmpeg, FFMPEG_HINT } from './paths.js'
+
+const WORKER = fileURLToPath(new URL('./asr-worker.js', import.meta.url))
+
+/**
+ * @param {string} file 音频文件（mp3 / m4a / wav / flac……ffmpeg 能读的都行）
+ * @param {object} opt { models, ffmpeg?, threads?, language?, signal?, onEvent? }
+ * @returns {Promise<{duration:number, segments:{start:number,end:number,text:string}[]}>}
+ */
+export function transcribe(file, opt) {
+  const ffmpeg = findFfmpeg(opt.ffmpeg)
+  if (!ffmpeg) return Promise.reject(new Error(FFMPEG_HINT))
+  const args = {
+    file, ffmpeg, models: opt.models, language: opt.language || 'en', threads: opt.threads || 2,
+    vadThreshold: opt.vadThreshold, minSilenceSeconds: opt.minSilenceSeconds, maxSpeechSeconds: opt.maxSpeechSeconds,
+  }
+  return new Promise((resolve, reject) => {
+    // Electron 里 process.execPath 是 App 本体：ELECTRON_RUN_AS_NODE=1 让它当 Node 用
+    const child = spawn(process.execPath, [WORKER, JSON.stringify(args)], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+    })
+    const segments = []
+    let duration = 0
+    let failure = null
+    let buf = ''
+    let stderr = ''
+    const onAbort = () => child.kill('SIGKILL')
+    if (opt.signal) {
+      if (opt.signal.aborted) onAbort()
+      else opt.signal.addEventListener('abort', onAbort, { once: true })
+    }
+    child.stdout.on('data', d => {
+      buf += d.toString('utf8')
+      let nl
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl)
+        buf = buf.slice(nl + 1)
+        let ev
+        try { ev = JSON.parse(line) } catch { continue }
+        if (ev.type === 'segment') segments.push({ start: round(ev.start), end: round(ev.end), text: ev.text })
+        else if (ev.type === 'duration') duration = ev.seconds
+        else if (ev.type === 'error') failure = ev.message
+        if (opt.onEvent) { try { opt.onEvent(ev) } catch { /* 进度回调出错不影响识别 */ } }
+      }
+    })
+    child.stderr.on('data', d => { stderr = (stderr + d).slice(-4000) })
+    child.on('error', reject)
+    child.on('close', code => {
+      if (opt.signal) opt.signal.removeEventListener('abort', onAbort)
+      if (opt.signal && opt.signal.aborted) return reject(new Error('已取消'))
+      if (code !== 0 || failure) return reject(new Error(failure || `识别进程退出（${code}）：${stderr.trim().split('\n').slice(-3).join(' ')}`))
+      resolve({ duration, segments })
+    })
+  })
+}
+
+const round = n => Math.round(n * 100) / 100
+
+const ENDS = /[.!?。！？…"”']$/
+
+/**
+ * 把 VAD 片段拼成句子：前一段很短（<1.6s）或没说完（没有句末标点），且停顿 <1.2s、拼完不超过 14s，就接上
+ */
+export function mergeSegments(segs, { maxGap = 1.2, maxLen = 14, short = 1.6 } = {}) {
+  const out = []
+  for (const s of segs) {
+    const text = String(s.text || '').trim()
+    if (!text) continue
+    const prev = out[out.length - 1]
+    if (prev) {
+      const gap = s.start - prev.end
+      const prevShort = prev.end - prev.start < short
+      const unfinished = !ENDS.test(prev.text)
+      if (gap < maxGap && (prevShort || unfinished) && s.end - prev.start <= maxLen) {
+        prev.end = s.end
+        prev.text = joinText(prev.text, text)
+        continue
+      }
+    }
+    out.push({ start: s.start, end: s.end, text })
+  }
+  return out
+}
+
+/** "First." + "Your energy…" → "First, your energy…" 不改；只是用空格接上，交给翻译那一步去校对 */
+function joinText(a, b) {
+  return `${a} ${b}`.replace(/\s+/g, ' ').trim()
+}
+
+/** 压缩成单声道 64 kbps MP3（固定码率，浏览器跳转到某一秒才准） */
+export function compactAudio(src, dest, opt = {}) {
+  const ffmpeg = findFfmpeg(opt.ffmpeg)
+  if (!ffmpeg) return Promise.reject(new Error(FFMPEG_HINT))
+  return new Promise((resolve, reject) => {
+    const child = spawn(ffmpeg, ['-hide_banner', '-nostdin', '-y', '-i', src, '-vn', '-map_metadata', '-1', '-ac', '1', '-ar', '44100',
+      '-codec:a', 'libmp3lame', '-b:a', '64k', dest], { stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    child.stderr.on('data', d => { stderr = (stderr + d).slice(-4000) })
+    const onAbort = () => child.kill('SIGKILL')
+    if (opt.signal) opt.signal.addEventListener('abort', onAbort, { once: true })
+    child.on('error', reject)
+    child.on('close', code => {
+      if (opt.signal) opt.signal.removeEventListener('abort', onAbort)
+      if (code === 0) resolve(dest)
+      else reject(new Error(`音频压缩失败：${stderr.trim().split('\n').slice(-2).join(' ')}`))
+    })
+  })
+}

package/lib/cli-llm.js

@@ -0,0 +1,54 @@
+// lib/cli-llm.js — 命令行版用哪个模型
+//
+// 顺序：命令行参数 > 环境变量（TINGDONG_BASE_URL / TINGDONG_API_KEY / TINGDONG_MODEL）
+//       > 本机的 dsh-model 网关（~/.dsh-model，同一生态的插件，地址和密钥都在本机）。
+// 没指定模型时，在接口的模型列表里优先挑 deepseek。
+
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { openaiLlm } from './llm.js'
+
+async function dshModelGateway() {
+  const root = join(homedir(), '.dsh-model')
+  try {
+    const cfg = JSON.parse(await readFile(join(root, 'config.json'), 'utf8'))
+    const yaml = await readFile(join(root, 'engine.yaml'), 'utf8')
+    const key = /api-keys:\s*\n\s*-\s*["']?([^"'\n]+)/.exec(yaml)
+    const port = Number(cfg.port) || 8317
+    return { baseURL: `http://127.0.0.1:${port}/v1`, apiKey: key ? key[1].trim() : '' }
+  } catch {
+    return null
+  }
+}
+
+async function pickModel(baseURL, apiKey) {
+  try {
+    const r = await fetch(baseURL.replace(/\/+$/, '') + '/models', {
+      headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+      signal: AbortSignal.timeout(6000),
+    })
+    const ids = ((await r.json()).data || []).map(m => m.id).filter(id => typeof id === 'string')
+    return ids.find(id => /deepseek/i.test(id) && !/embed|bge/i.test(id)) || ids.find(id => !/embed|bge/i.test(id)) || ''
+  } catch {
+    return ''
+  }
+}
+
+/** @returns {Promise<object|null>} complete() 接口；没有可用模型返回 null */
+export async function cliLlm(flags = {}) {
+  let baseURL = flags['base-url'] || process.env.TINGDONG_BASE_URL || ''
+  let apiKey = flags['api-key'] || process.env.TINGDONG_API_KEY || ''
+  let model = flags.model || process.env.TINGDONG_MODEL || ''
+  let via = 'env'
+  if (!baseURL) {
+    const gw = await dshModelGateway()
+    if (gw) { baseURL = gw.baseURL; apiKey = apiKey || gw.apiKey; via = 'dsh-model' }
+  }
+  if (!baseURL) return null
+  if (!model) model = await pickModel(baseURL, apiKey)
+  if (!model) return null
+  const llm = openaiLlm({ baseURL, apiKey, model })
+  llm.via = via
+  return llm
+}