@pls-compile-owo/fisheye 0.4.2 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范与 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.7.1] - 2026-11-14
+
+### Added
+
+- `auto --resume`：断点续跑完整版——manifest 与计划一致且拼图齐全时**跳过抽帧**，直接复用已有拼图继续后续阶段（`--force` 强制重跑）。
+
+## [0.7.0] - 2026-11-14
+
+### Added
+
+- `batch <清单文件|条目...> [--concurrency N]` 子命令：一次处理多个 BV/本地文件/URL（`lib/batch.mjs`）。
+- 字幕翻译：外文视频的官方字幕会同时读取 B站 翻译轨（`translated` 字段，落盘 `<BV>-official-subs-translated.txt`）。
+- 断点续跑基础（`lib/resume.mjs`）：manifest 记录计划/阶段，重跑时提示可复用产物（`--force` 强重跑）。
+- 进度辅助（`lib/progress.mjs`）：分段抽帧进度、阶段计时。
+- MCP server 入包（`mcp-video-server.js`，可选组件，需自装 @modelcontextprotocol/sdk / zod）+ 中英 README + CONFIG 文档。
+
+## [0.6.0] - 2026-11-14
+
+### Added
+
+- OCR 画面文字识别：`ocr <图片路径>` 子命令（tesseract，可选）；selftest 显示 OCR 可用性（`lib/ocr.mjs`）。
+- 任意平台视频：`url <视频链接>` 子命令（yt-dlp，可选，下载后走本地视频流程）（`lib/ytdlp.mjs`）。
+- `clean [--target cache|out|all] [--yes]` 子命令：清理缓存/产物（dry-run 默认，--yes 才删）。
+- `auto --audio`：无官方字幕时自动用 whisper 转写台词，跳过烧录字幕带。
+
+### Changed
+
+- selftest 增加 OCR / yt-dlp 检查项。
+
+## [0.5.0] - 2026-11-14
+
+### Added
+
+- `transcribe <BV> [--lang zh]` 子命令：用 whisper.cpp 转写音频，文本落 `out/<BV>-audio-transcript.txt`。
+- `lib/audio.mjs` 自动探测 whisper.cpp 官方 Windows 包解压结构（`whisper/Release/`）。
+- 单元测试覆盖扩展到全部模块：retry / budget / i18n / frame / env / audio / bili（共 46 个用例）。
+- 外部自检脚本增加「模块导入冒烟」（10 个 lib 模块全部可加载）。
+
 ## [0.4.2] - 2026-11-14
 
 ### Fixed

package/README.md

@@ -159,6 +159,15 @@ node fisheye.mjs grab BV1ziWP6qENy 82.5,145.0
        00:27  弹幕热区  —— 弹幕热区 19 条
 ```
 
+## 断点续跑
+
+长视频处理中断后，重新跑同样的命令会提示可复用产物：
+
+```bash
+node fisheye.mjs auto BV1xxx --budget 20000 --resume   # 跳过已抽帧阶段，复用拼图
+node fisheye.mjs auto BV1xxx --budget 20000 --force    # 强制全部重跑
+```
+
 ## 命令
 
 | 命令 | 作用 |
@@ -205,6 +214,46 @@ node fisheye.mjs local <视频文件> [--grid 3x3] [--from 30] [--to 90]
 不依赖 B站 登录与字幕：ffmpeg 解析时长 → 按 grid 等间隔抽帧拼图 → 输出 `SHEET: <拼图路径>`。
 把拼图路径交给模型 `read_image` 即可"看"本地视频。适合 mp4/mkv/avi/mov/webm。
 
+## 音频转写
+
+装了 whisper.cpp 后，可以给无字幕视频做语音转写：
+
+```bash
+node fisheye.mjs transcribe BV1xxx [--lang zh]
+```
+
+自动探测顺序：`FISHEYE_WHISPER` 环境变量 → PATH → 常见安装路径（含 `~/.dsh/surfcore/whisper/Release/`）。
+模型放 `~/.dsh/surfcore/whisper/`（`ggml-*.bin`）或用 `FISHEYE_WHISPER_MODEL` 指定。
+转写文本落 `out/<BV>-audio-transcript.txt`。
+
+## OCR（图片文字识别）
+
+装了 tesseract 后可以识别图片/画面里的文字：
+
+```bash
+node fisheye.mjs ocr screenshot.png [--lang chi_sim+eng]
+```
+
+自动探测 `FISHEYE_TESSERACT` → PATH → 常见安装路径；语言包缺 `chi_sim` 时自动降级到 `eng`。
+识别结果落 `out/<图片名>.ocr.txt`。
+
+## 任意平台视频（yt-dlp）
+
+装了 yt-dlp 后可以直接给任意平台（YouTube/抖音/Twitter…）的链接：
+
+```bash
+node fisheye.mjs url "https://www.youtube.com/watch?v=xxx"
+```
+
+下载（yt-dlp）→ 自动走本地视频抽帧流程。探测顺序：`FISHEYE_YTDLP` → PATH → 常见安装路径。
+
+## 清理
+
+```bash
+node fisheye.mjs clean                    # 预览将清理的缓存/产物（dry-run）
+node fisheye.mjs clean --target out --yes # 实际删除 out/
+```
+
 ## 它怎么工作
 
 ```
@@ -252,7 +301,7 @@ B 站的弹幕密度本身就是内容信号。实测一条 40 分钟视频：
 ## 开发
 
 ```bash
-node --test test/                # 单元测试（参数解析 / 弹幕分析）
+node --test test/                # 单元测试（全部模块：46 个用例）
 node test-danmaku-filter.js      # 弹幕过滤规则测试（51 条用例）
 node fisheye.mjs selftest --deep # 含抽帧/字幕带实测的自检
 ```

package/fisheye.mjs

@@ -15,23 +15,29 @@
 // · 拼图每格顺序固定，manifest 按「从左到右、从上到下」记录时间，供 agent 对照
 // · 拼图与精读用同一种 seek，保证同一时间戳取到同一帧
 // · 所有子进程用 stdio:'ignore'（沙箱禁管道捕获），数据走临时文件
+import fs from 'node:fs'
 import path from 'node:path'
 import { PKG_DIR, WS, CFG_FILE, FFMPEG, CRED } from './lib/env.mjs'
 import { parseTime, num, pageNum } from './lib/util.mjs'
 import { t } from './lib/i18n.mjs'
-import { stageAuto, stageGrid, stageSubs, stageSelftest, stageRefine, stageGrab, stageLocal } from './lib/stages.mjs'
+import { stageAuto, stageGrid, stageSubs, stageSelftest, stageRefine, stageGrab, stageLocal, stageTranscribe, stageClean, stageOcr, stageUrl, stageBatch } from './lib/stages.mjs'
 
 const IS_SELFTEST = process.argv[2] === 'selftest'
 
 // local 处理本地文件，不需要 B站 登录态（但仍然需要 ffmpeg）
 const IS_LOCAL = process.argv[2] === 'local'
+// clean / ocr 只动本地文件，不需要 ffmpeg 与 B站 凭证
+const IS_CLEAN = process.argv[2] === 'clean'
+const IS_OCR = process.argv[2] === 'ocr'
+// url 需要 yt-dlp + ffmpeg，但不需要 B站 凭证
+const IS_URL = process.argv[2] === 'url'
 
-if (!IS_SELFTEST) {
+if (!IS_SELFTEST && !IS_CLEAN && !IS_OCR) {
   if (!FFMPEG) {
     console.error(t('err.ffmpeg.missing', { binDir: path.join(PKG_DIR, 'bin'), cfgFile: CFG_FILE }))
     process.exit(2)
   }
-  if (!IS_LOCAL && !CRED) {
+  if (!IS_LOCAL && !IS_CLEAN && !IS_OCR && !IS_URL && !CRED) {
     console.error(t('err.cred.missing', { credPath: path.join(WS, 'credentials.json') }))
     process.exit(2)
   }
@@ -70,7 +76,68 @@ if (stage === 'local') {
   }
   process.exit(0)
 }
-if (!stage || (stage !== 'selftest' && !bvid)) {
+
+if (stage === 'ocr') {
+  const img = argv[1]
+  if (!img || img.startsWith('--')) {
+    console.error(t('err.ocr.usage'))
+    process.exit(2)
+  }
+  try {
+    await stageOcr(img, { lang: opt('lang', null) })
+  } catch (error) {
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
+    process.exit(1)
+  }
+  process.exit(0)
+}
+if (stage === 'url') {
+  const link = argv[1]
+  if (!link || link.startsWith('--')) {
+    console.error(t('err.url.usage'))
+    process.exit(2)
+  }
+  try {
+    await stageUrl(link, {
+      grid: opt('grid', '3x3'),
+      from: parseTime(opt('from', null), 'from'),
+      to: parseTime(opt('to', null), 'to')
+    })
+  } catch (error) {
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+
+if (stage === 'batch') {
+  const arg = argv[1]
+  const listText = (arg && !arg.startsWith('--') && fs.existsSync(arg))
+    ? fs.readFileSync(arg, 'utf8')
+    : argv.slice(1).filter((a) => !a.startsWith('--')).join('\n')
+  if (!listText.trim()) {
+    console.error(t('err.batch.usage'))
+    process.exit(2)
+  }
+  try {
+    await stageBatch(listText, {
+      concurrency: num(opt('concurrency', 1), 'concurrency', { min: 1, max: 8 }),
+      budget: opt('budget', null) ? num(opt('budget'), 'budget', { min: 2000, max: 200000 }) : 20000,
+      grid: opt('grid', '3x3'),
+      audio: argv.includes('--audio'),
+      lang: opt('lang', null),
+      from: parseTime(opt('from', null), 'from'),
+      to: parseTime(opt('to', null), 'to')
+    })
+  } catch (error) {
+    console.error(t('err.local.failed', { message: error?.message ?? error }))
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+if (!stage || (stage !== 'selftest' && stage !== 'clean' && stage !== 'ocr' && stage !== 'url' && stage !== 'batch' && !bvid)) {
   if (rawBvid && stage !== 'selftest') {
     console.error(`${t('err.bvFormat', { raw: rawBvid })}\n`)
   }
@@ -94,7 +161,9 @@ try {
     await stageAuto(bvid,
       num(opt('budget', 20000), 'budget', { min: 2000, max: 200000 }),
       { density: d === null ? null : num(d, 'density', { min: 0.5, max: 60 }), page, from, to,
-        useDanmakuFrames: !argv.includes('--no-danmaku-frames') })
+        useDanmakuFrames: !argv.includes('--no-danmaku-frames'),
+        audio: argv.includes('--audio'), audioLang: opt('lang', null),
+        resume: argv.includes('--resume'), force: argv.includes('--force') })
   } else if (stage === 'refine') {
     await stageRefine(bvid, { template: argv.includes('--template'), decisions: opt('decisions', null) })
   } else if (stage === 'grid') {
@@ -108,6 +177,11 @@ try {
       opt('band', 'auto'),
       { page, range })
   } else if (stage === 'grab') await stageGrab(bvid, argv[2] ?? '', { page })
+  else if (stage === 'clean') {
+    // 清理缓存/产物：本地操作，不需要 BV 号
+    await stageClean({ target: opt('target', 'all'), yes: argv.includes('--yes') })
+  }
+  else if (stage === 'transcribe') await stageTranscribe(bvid, { page, lang: opt('lang', null) })
   else { console.error(t('err.unknownStage', { stage })); process.exit(2) }
 } catch (e) {
   console.error(t('err.fatal', { message: e.message }))

package/lib/audio.mjs

@@ -145,6 +145,7 @@ function commonWhisperPaths(env = process.env) {
     path.join(home, '.dsh', 'surfcore', 'whisper', 'bin'),
     path.join(home, '.dsh', 'surfcore', 'whisper', 'build', 'bin'),
     path.join(home, '.dsh', 'surfcore', 'whisper', 'build', 'bin', 'Release'),
+  path.join(home, '.dsh', 'surfcore', 'whisper', 'Release'),
     // 本机实际布局：ffmpeg 和 B站下载器放在 bili/bin，whisper 也可能被丢在同一处
     path.join(home, '.dsh', 'surfcore', 'bili', 'bin'),
     path.join(home, '.dsh', 'surfcore', 'bin'),

package/lib/batch.mjs

@@ -0,0 +1,191 @@
+// 批量处理核心：把多条 BV / 本地文件 / URL 交给同一个 runner 跑。
+// 纯逻辑：不读文件系统、不起子进程、不碰网络、零第三方依赖。
+// 文件是否存在、视频能不能解析，统一交给调用方传入的 runner 判断——
+// 这样 parseBatchList 是可测的纯函数，批量流程也能在单测里跑完。
+//
+// 典型接法（后续 batch 子命令）：
+//   const { items, errors } = parseBatchList(text)
+//   // errors 先报给用户，items 再进 runBatch
+//   const summary = await runBatch(items, (item) => runOne(item, opts), {
+//     concurrency: 2,
+//     onItem: (item, i) => console.log(`[${i + 1}/${items.length}] ${item.value}`)
+//   })
+//   console.log(formatBatchReport(summary))
+
+// BV 号：BV + 10 位字母数字（与 fisheye.mjs 入口校验保持一致）
+const BV_RE = /^BV[0-9A-Za-z]{10}$/
+const URL_RE = /^https?:\/\//i
+// Windows 盘符：C:\ / C:/ / 裸 C:
+const DRIVE_RE = /^[A-Za-z]:(?:[\\/]|$)/
+// 常见视频扩展名（URL 已在前面单独判定，这里只看裸文件名）
+const VIDEO_EXT_RE = /\.(mp4|mkv|avi|mov|webm)$/i
+
+// 路径形态判断（纯字符串，不看磁盘）
+function looksLikeFile(s) {
+  if (DRIVE_RE.test(s)) return true
+  if (s.startsWith('\\\\') || s.startsWith('//')) return true // UNC \\server\share
+  if (s.startsWith('./') || s.startsWith('.\\') || s.startsWith('../') || s.startsWith('..\\')) return true
+  if (s.startsWith('/')) return true
+  if (VIDEO_EXT_RE.test(s)) return true // 裸文件名：video.mp4
+  if (/[\\/]/.test(s)) return true // 含路径分隔符
+  return false
+}
+
+function classify(value) {
+  if (BV_RE.test(value)) return 'bv'
+  if (URL_RE.test(value)) return 'url'
+  if (looksLikeFile(value)) return 'file'
+  return null
+}
+
+// 统一成「物理行」数组：字符串直接按行拆；数组每项再按行拆（一项多行也认）
+function toLines(input) {
+  if (typeof input === 'string') return input.split(/\r?\n/)
+  if (!Array.isArray(input)) return null
+  const out = []
+  for (const entry of input) {
+    if (entry === null || entry === undefined) continue
+    out.push(...String(entry).split(/\r?\n/))
+  }
+  return out
+}
+
+/**
+ * 解析批量输入。
+ * 每行 trim 后：空行 / `#` 开头的注释行跳过；BV 号 → bv；http(s):// → url；
+ * 像文件路径（盘符/UNC/相对路径/含分隔符/视频扩展名）→ file；其余进 errors。
+ * @param {string|string[]} input 多行文本，或每项一行的数组
+ * @returns {{ items: Array<{kind:'bv'|'file'|'url', value:string}>,
+ *             errors: Array<{line:number, raw:string, reason:string}> }}
+ */
+export function parseBatchList(input) {
+  const lines = toLines(input)
+  // 类型不对时也走 errors，不要抛异常——CLI 层还要把错误列给用户看
+  if (lines === null) {
+    return {
+      items: [],
+      errors: [{ line: 0, raw: String(input ?? ''), reason: '批量清单必须是字符串或数组' }]
+    }
+  }
+  const items = []
+  const errors = []
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]
+    const value = raw.trim()
+    if (value === '' || value.startsWith('#')) continue
+    const kind = classify(value)
+    if (kind) items.push({ kind, value })
+    else errors.push({ line: i + 1, raw: value, reason: '无法识别：既不是 BV 号、URL，也不是视频文件路径' })
+  }
+  return { items, errors }
+}
+
+const nowMs = () => performance.now()
+
+function errorText(error) {
+  if (error instanceof Error) return error.message || error.name || '未知错误'
+  if (typeof error === 'string') return error
+  if (error === null || error === undefined) return '未知错误'
+  try {
+    const s = JSON.stringify(error)
+    return s === undefined ? String(error) : s
+  } catch {
+    return String(error) // 循环引用、BigInt 之类
+  }
+}
+
+async function runOne(item, runner) {
+  const started = nowMs()
+  try {
+    const result = await runner(item)
+    return { item, ok: true, result, ms: Math.round(nowMs() - started) }
+  } catch (error) {
+    return { item, ok: false, error: errorText(error), ms: Math.round(nowMs() - started) }
+  }
+}
+
+function normalizeConcurrency(value, total) {
+  const n = Math.floor(Number(value))
+  if (!Number.isFinite(n) || n < 1) return 1
+  return Math.min(n, total)
+}
+
+/**
+ * 批量执行：串行或简单并发池；单项失败只记录，不中断整体。
+ * 结果顺序始终与 items 一致（并发完成顺序不回写结果顺序）。
+ * onItem 在每项 runner 之前调用，抛错会中断整批（进度回调不该抛错）。
+ * @param {Array} items parseBatchList().items 或任意可迭代项
+ * @param {(item:any, index:number)=>Promise<any>} runner 单条处理逻辑
+ * @param {{concurrency?:number, onItem?:null|((item:any, index:number)=>any)}} [options]
+ * @returns {Promise<{results: Array<{item:any, ok:boolean, result?:any, error?:string, ms:number}>,
+ *                    total:number, ok:number, failed:number}>}
+ */
+export async function runBatch(items, runner, { concurrency = 1, onItem = null } = {}) {
+  if (!Array.isArray(items)) throw new TypeError('runBatch: items 必须是数组')
+  if (typeof runner !== 'function') throw new TypeError('runBatch: runner 必须是函数')
+  if (onItem !== null && typeof onItem !== 'function') throw new TypeError('runBatch: onItem 必须是函数或 null')
+
+  const total = items.length
+  if (total === 0) return { results: [], total: 0, ok: 0, failed: 0 }
+
+  const limit = normalizeConcurrency(concurrency, total)
+  const results = new Array(total)
+  let next = 0
+
+  // 简单并发池：limit 个 worker 抢同一个游标，谁空谁取下一个
+  async function worker() {
+    for (;;) {
+      const index = next++
+      if (index >= total) return
+      const item = items[index]
+      if (onItem) await onItem(item, index)
+      results[index] = await runOne(item, runner)
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, () => worker()))
+
+  const ok = results.reduce((n, r) => n + (r.ok ? 1 : 0), 0)
+  return { results, total, ok, failed: total - ok }
+}
+
+// 报告里的耗时：按 ms 展示，超过 1 秒给一位小数，超过 1 分钟给 XmYs
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return '0ms'
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  if (ms < 60000) {
+    const s = Math.round(ms / 100) / 10
+    return s >= 60 ? '1m0s' : `${s.toFixed(1)}s`
+  }
+  const m = Math.floor(ms / 60000)
+  const s = Math.round((ms % 60000) / 1000)
+  return s === 60 ? `${m + 1}m0s` : `${m}m${s}s`
+}
+
+function describeItem(item) {
+  if (!item || typeof item !== 'object') return String(item)
+  const value = item.value ?? ''
+  return item.kind ? `[${item.kind}] ${value}` : String(value)
+}
+
+/**
+ * 生成人类可读的汇总文本（不含尾随换行，方便 console.log 直接用）。
+ * 耗时取 results 里各条 ms 之和（并发时是累计值，不是墙钟时间）。
+ * @param {object} summary runBatch() 的返回值
+ * @returns {string}
+ */
+export function formatBatchReport(summary) {
+  const results = Array.isArray(summary?.results) ? summary.results : []
+  const total = Number.isFinite(summary?.total) ? summary.total : results.length
+  const ok = Number.isFinite(summary?.ok) ? summary.ok : results.filter((r) => r?.ok).length
+  const failed = Number.isFinite(summary?.failed) ? summary.failed : Math.max(0, total - ok)
+  const spent = results.reduce((sum, r) => sum + (Number.isFinite(r?.ms) ? r.ms : 0), 0)
+
+  const lines = [`批量处理：共 ${total} 条，成功 ${ok} 条，失败 ${failed} 条，耗时合计 ${formatDuration(spent)}`]
+  if (failed > 0) {
+    lines.push('失败明细：')
+    const failures = results.filter((r) => r && !r.ok)
+    if (failures.length === 0) lines.push('  （没有明细）')
+    else failures.forEach((r, i) => lines.push(`  ${i + 1}. ${describeItem(r.item)} —— ${r.error ?? '未知错误'}`))
+  }
+  return lines.join('\n')
+}

package/lib/bili.mjs

@@ -48,6 +48,34 @@ export const keyOf = (u) => u.slice(u.lastIndexOf('/') + 1, u.lastIndexOf('.'))
 
 export const clean = (v) => String(v).replace(/[!'()*]/g, '')
 
+/**
+ * 从 B站 subtitle.subtitles 列表里挑「主轨（原文）」和「翻译轨（中文）」。
+ * 外文视频（英文/日文…）的 AI 字幕除了原文轨还会带一条中文机器翻译轨（l2，lan 含 zh），
+ * 只取原文就成了「只转写不翻译」——所以这里把两条轨分开，交给 getOfficialSubs 分别下载。
+ *
+ * 语义：
+ * · 有外文轨 + 中文轨：main = 第一条外文轨（保留原话），translate = 中文轨
+ * · 只有中文轨：main = 中文轨，translate = null（原有行为，不产生「中文翻译中文」）
+ * · 只有外文轨：main = 外文轨，translate = null
+ * · 空 / 无有效 lan：null
+ * · preferZh=false：不做翻译，中文轨直接当主轨（只要中文文本的调用方）
+ * 中文轨优先级沿用旧逻辑：ai-zh → zh-CN → 其它 zh*（B站 AI 中文覆盖最全）。
+ * 纯函数，不发请求，便于单测。
+ */
+export function pickSubtitleTracks(subs, preferZh = true) {
+  const list = (Array.isArray(subs) ? subs : []).filter((s) => s && typeof s.lan === 'string' && s.lan)
+  if (!list.length) return null
+  const isZh = (s) => /zh/i.test(s.lan)
+  const zh = list.find((s) => s.lan === 'ai-zh') ?? list.find((s) => s.lan === 'zh-CN')
+    ?? list.find(isZh) ?? null
+  const foreign = list.find((s) => !isZh(s)) ?? null
+  // 只要中文：中文轨当主轨，不再单列翻译
+  if (!preferZh) return { main: zh ?? foreign, translate: null }
+  // 没有外文轨（中文原声视频 / 只有单条中文字幕）：保持旧行为
+  if (!foreign) return { main: zh, translate: null }
+  return { main: foreign, translate: zh }
+}
+
 export async function getOfficialSubs(bvid, cid, range = null) {
   try {
     const nav = await (await fetchWithRetry('https://api.bilibili.com/x/web-interface/nav',
@@ -65,19 +93,25 @@ export async function getOfficialSubs(bvid, cid, range = null) {
       { headers: H }, { timeoutMs: 15000 })).json()
     const subs = p?.data?.subtitle?.subtitles ?? []
     if (!subs.length) return null
-    const pick = subs.find((s) => s.lan === 'ai-zh') ?? subs.find((s) => s.lan === 'zh-CN')
-      ?? subs.find((s) => String(s.lan).startsWith('zh')) ?? subs[0]
-    if (!pick?.subtitle_url) return null
-
-    const url = String(pick.subtitle_url).startsWith('http') ? pick.subtitle_url : 'https:' + pick.subtitle_url
-    const r = await fetchWithRetry(url, {
-      headers: { 'user-agent': UA, referer: `https://www.bilibili.com/video/${bvid}/` },
-    }, { timeoutMs: 20000 })
-    if (!r.ok) return null
-    let body = (JSON.parse(await r.text()).body ?? [])
-    if (!body.length) return null
-    // 只保留所处理区间内的字幕行（--from/--to）
-    if (range) body = body.filter((l) => Number(l.from) >= range.from && Number(l.from) <= range.to)
+    const tracks = pickSubtitleTracks(subs)
+    if (!tracks?.main?.subtitle_url) return null
+
+    const subHeaders = { 'user-agent': UA, referer: `https://www.bilibili.com/video/${bvid}/` }
+    const subUrl = (u) => (String(u).startsWith('http') ? String(u) : 'https:' + String(u))
+    // 下载一条字幕轨并按 --from/--to 过滤。翻译轨失败只丢翻译，不能让整条字幕失败。
+    const fetchBody = async (u) => {
+      const r = await fetchWithRetry(subUrl(u), { headers: subHeaders }, { timeoutMs: 20000 })
+      if (!r.ok) return []
+      const raw = JSON.parse(await r.text()).body ?? []
+      if (!range) return raw
+      return raw.filter((l) => Number(l.from) >= range.from && Number(l.from) <= range.to)
+    }
+    // 主轨 + 翻译轨并行下载：auth_key 分钟级过期，串行两次请求更容易踩到期
+    const translateTrack = tracks.translate?.subtitle_url ? tracks.translate : null
+    const [body, transBody] = await Promise.all([
+      fetchBody(tracks.main.subtitle_url),
+      translateTrack ? fetchBody(translateTrack.subtitle_url).catch(() => []) : Promise.resolve([]),
+    ])
     if (!body.length) return null
 
     fs.mkdirSync(OUT, { recursive: true })
@@ -86,6 +120,25 @@ export async function getOfficialSubs(bvid, cid, range = null) {
     fs.writeFileSync(txt, body.map((l) => `[${fmt(l.from)}] ${l.content}`).join('\n'), 'utf8')
     fs.writeFileSync(plain, body.map((l) => l.content).join('\n'), 'utf8')
 
+    // 翻译轨：中文机器翻译（外文视频才有）。chars 用与原文相同的「去 ♪/空白」算法，
+    // 避免译文里的空格让字数虚高；全空的翻译轨按「没有翻译」处理。
+    let translated = null
+    if (transBody?.length) {
+      const tChars = transBody.reduce(
+        (a, l) => a + String(l.content ?? '').replace(/[♪\s]/g, '').length, 0)
+      if (tChars > 0) {
+        const file = path.join(OUT, `${bvid}-official-subs-translated.txt`)
+        fs.writeFileSync(file, transBody.map((l) => `[${fmt(l.from)}] ${l.content}`).join('\n'), 'utf8')
+        translated = {
+          lan: translateTrack.lan,
+          lines: transBody.length,
+          chars: tChars,
+          txt: transBody.map((l) => String(l.content ?? '')).join('\n'),
+          file,
+        }
+      }
+    }
+
     // 质量判断：B 站 AI 字幕在纯音乐/音效为主的视频里会输出大量「 歌词」噪声或无意义碎片，
     // 这种字幕不能用（拿它当台词理解视频会全错），应该降级为看图
     const effChars = body.map((l) => String(l.content ?? '').replace(/[♪\s]/g, '').length)
@@ -95,9 +148,11 @@ export async function getOfficialSubs(bvid, cid, range = null) {
     const quality = avgEff < 2 || uniqueRatio < 0.4 ? 'noisy' : 'ok'
 
     return {
-      lan: pick.lan, lanDoc: pick.lan_doc, lines: body.length, txt, plain,
+      lan: tracks.main.lan, lanDoc: tracks.main.lan_doc, lines: body.length, txt, plain,
       chars, quality, avgEff: Number(avgEff.toFixed(1)), uniqueRatio: Number(uniqueRatio.toFixed(2)),
       head: body.slice(0, 5).map((l) => `[${fmt(l.from)}] ${l.content}`),
+      // 中文翻译轨（没有时为 null）：原文 lines/txt 不变，翻译单独给，调用方自己决定怎么用
+      translated,
     }
   } catch (e) {
     console.warn(`[官方字幕] 获取失败（按无官方字幕处理）：${String(e.message).split('\n')[0].slice(0, 60)}`)

package/lib/frame.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { execFileSync, spawnSync } from 'node:child_process'
-import { FFMPEG, PYTHON, WS, OUT } from './env.mjs'
+import { FFMPEG, PYTHON, WS, OUT, PKG_DIR } from './env.mjs'
 
 export function detectScenes(file) {
   // 文件名带 pid + 时间戳：两个视频并发跑时不会互相覆盖

package/lib/i18n.mjs

@@ -19,7 +19,7 @@ const MESSAGES = {
   zh: {
     // —— 用法帮助 ——
     usage: `用法:
-  node fisheye.mjs auto <BV> [--budget 20000] [--density 6]      ← 推荐：自动规划并铺网
+  node fisheye.mjs auto <BV> [--budget 20000] [--density 6] [--audio]  ← 推荐：自动规划并铺网（--audio 无字幕转写 / --resume 断点续跑）
   node fisheye.mjs refine <BV> --template                         ← 生成精读决策模板
   node fisheye.mjs refine <BV> --decisions <file.json>            ← 按模型判断精读
   node fisheye.mjs refine <BV>                                    ← 几何兜底（零 token）
@@ -27,6 +27,11 @@ const MESSAGES = {
   node fisheye.mjs subs <BV> [--count 12] [--band auto|0.22]
   node fisheye.mjs grab <BV> <t1,t2,t3>                           ← 手动指定时间点
   node fisheye.mjs local <视频文件> [--grid 3x3] [--from t] [--to t]  ← 看本地视频（mp4/mkv/...）
+  node fisheye.mjs transcribe <BV> [--lang zh]                     ← 音频转写（需 whisper.cpp）
+  node fisheye.mjs ocr <图片路径> [--lang chi_sim+eng]             ← OCR 识别图片文字（需 tesseract）
+  node fisheye.mjs url <视频链接> [--grid 3x3]                     ← 任意平台视频（需 yt-dlp）
+  node fisheye.mjs clean [--target cache|out|all] [--yes]          ← 清理缓存/产物
+  node fisheye.mjs batch <清单文件|条目...> [--concurrency 2]       ← 批量处理（每行一个 BV/路径/URL）
   node fisheye.mjs selftest [--deep]                              ← 自检（依赖/凭证/API/缓存/磁盘）`,
 
     // —— 依赖缺失 ——
@@ -55,6 +60,9 @@ const MESSAGES = {
     'err.unknownStage': '未知阶段: {stage}',
     'err.bvFormat': '[错误] BV 号格式不对：{raw}（应为 BV + 10 位字母数字，如 BV1ziWP6qENy）',
     'err.local.usage': '用法: node fisheye.mjs local <视频文件> [--grid 3x3] [--from t] [--to t]',
+    'err.ocr.usage': '用法: node fisheye.mjs ocr <图片路径> [--lang chi_sim+eng]',
+    'err.url.usage': '用法: node fisheye.mjs url <视频链接> [--grid 3x3] [--from t] [--to t]',
+    'err.batch.usage': '用法: node fisheye.mjs batch <清单文件|条目...> [--concurrency 2]',
     'err.fatal': '\n错误：{message}',
     'err.local.failed': '[错误] {message}',
 
@@ -71,7 +79,7 @@ const MESSAGES = {
 
   en: {
     usage: `Usage:
-  node fisheye.mjs auto <BV> [--budget 20000] [--density 6]      # recommended: auto-plan and build grids
+  node fisheye.mjs auto <BV> [--budget 20000] [--density 6] [--audio]  # recommended: auto-plan and build grids (--audio transcribe / --resume resume)
   node fisheye.mjs refine <BV> --template                         # generate a refine decision template
   node fisheye.mjs refine <BV> --decisions <file.json>            # refine using model decisions
   node fisheye.mjs refine <BV>                                    # geometric fallback (zero tokens)
@@ -79,6 +87,11 @@ const MESSAGES = {
   node fisheye.mjs subs <BV> [--count 12] [--band auto|0.22]
   node fisheye.mjs grab <BV> <t1,t2,t3>                           # pick timestamps manually
   node fisheye.mjs local <video file> [--grid 3x3] [--from t] [--to t]  # analyze a local video (mp4/mkv/...)
+  node fisheye.mjs transcribe <BV> [--lang zh]                     # transcribe audio (requires whisper.cpp)
+  node fisheye.mjs ocr <image path> [--lang chi_sim+eng]           # OCR text from an image (requires tesseract)
+  node fisheye.mjs url <video link> [--grid 3x3]                   # any platform video (requires yt-dlp)
+  node fisheye.mjs clean [--target cache|out|all] [--yes]          # clean cache/out artifacts
+  node fisheye.mjs batch <list file|items...> [--concurrency 2]    # batch process (one BV/path/URL per line)
   node fisheye.mjs selftest [--deep]                              # self-check (deps/credentials/API/cache/disk)`,
 
     'err.ffmpeg.missing': `ffmpeg not found.
@@ -105,6 +118,9 @@ then copy those three values. Or set BILI_CRED=<file path> to point at an existi
     'err.unknownStage': 'Unknown stage: {stage}',
     'err.bvFormat': '[error] Invalid BV id: {raw} (expected BV + 10 alphanumeric chars, e.g. BV1ziWP6qENy)',
     'err.local.usage': 'Usage: node fisheye.mjs local <video file> [--grid 3x3] [--from t] [--to t]',
+    'err.ocr.usage': 'Usage: node fisheye.mjs ocr <image path> [--lang chi_sim+eng]',
+    'err.url.usage': 'Usage: node fisheye.mjs url <video link> [--grid 3x3] [--from t] [--to t]',
+    'err.batch.usage': 'Usage: node fisheye.mjs batch <list file|items...> [--concurrency 2]',
     'err.fatal': '\nError: {message}',
     'err.local.failed': '[error] {message}',