@pls-compile-owo/fisheye 0.3.0 → 0.7.1

package/lib/i18n.mjs

@@ -0,0 +1,147 @@
+// 国际化：CLI 文案按语言取用。语言来自环境变量 FISHEYE_LANG
+// 'zh'（默认）/ 'en'；也接受 zh-CN、en-US 这类写法（取第一段）。
+// 零依赖：只读 process.env，不引任何模块。
+
+const DEFAULT_LANG = 'zh'
+const SUPPORTED = new Set(['zh', 'en'])
+
+/** 当前语言：FISHEYE_LANG 不合法或没设时回落到中文 */
+export function getLang() {
+  const raw = String(process.env.FISHEYE_LANG ?? '').trim().toLowerCase()
+  if (!raw) return DEFAULT_LANG
+  const base = raw.split(/[-_]/)[0]
+  return SUPPORTED.has(base) ? base : DEFAULT_LANG
+}
+
+// 文案表。占位符写法 {name}，由 t() 的 vars 替换；
+// 找不到当前语言的 key 时回落到中文，再找不到就原样返回 key（方便发现漏翻）。
+const MESSAGES = {
+  zh: {
+    // —— 用法帮助 ——
+    usage: `用法:
+  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）
+  node fisheye.mjs grid <BV> [--chunk 60] [--grid 3x3]
+  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/缓存/磁盘）`,
+
+    // —— 依赖缺失 ——
+    'err.ffmpeg.missing': `找不到 ffmpeg。
+
+安装方式（任选其一）：
+  1. 装到 PATH：https://ffmpeg.org/download.html （Windows 用 gyan.dev 的 build）
+  2. 放项目里：把 ffmpeg 可执行文件放到 {binDir}/
+  3. 设环境变量：FFMPEG=<ffmpeg 完整路径>
+  4. 写配置：{cfgFile} 里加 {"ffmpeg": "<完整路径>"}`,
+
+    'err.cred.missing': `找不到 B站登录态文件。
+
+创建 {credPath}，内容：
+  {
+    "sessdata": "<B站 SESSDATA>",
+    "bili_jct": "<bili_jct>",
+    "buvid3": "<buvid3>"
+  }
+获取方法：浏览器登录 B站 → F12 → Application → Cookies → bilibili.com，
+复制这三个值。或用环境变量 BILI_CRED=<文件路径> 指向已有文件。
+
+（也可以只跑 selftest 先看环境是否就绪：node fisheye.mjs selftest）`,
+
+    // —— 命令 / 参数错误 ——
+    '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}',
+
+    // —— util 参数校验 ——
+    'err.argPrefix': '参数错误：',
+    'err.num.notNumber': '--{name} 需要数字，收到：{value}',
+    'err.num.min': '--{name} 不能小于 {min}（收到 {n}）',
+    'err.num.max': '--{name} 不能大于 {max}（收到 {n}）',
+    'err.grid.format': '--grid 格式应为 NxM（如 3x3，行列 1~9），收到：{value}',
+    'err.time.format': '--{name} 时间格式应为 330 / 5:30 / 1:05:30，收到：{value}',
+    'err.time.invalid': '--{name} 时间格式非法：{value}',
+    'err.page.range': '--p 分P序号应为 1~200 的整数，收到：{value}'
+  },
+
+  en: {
+    usage: `Usage:
+  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)
+  node fisheye.mjs grid <BV> [--chunk 60] [--grid 3x3]
+  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.
+
+Install it in one of these ways:
+  1. Put it on PATH: https://ffmpeg.org/download.html (on Windows use a gyan.dev build)
+  2. Drop it into the project: place the ffmpeg executable in {binDir}/
+  3. Set an env var: FFMPEG=<full path to ffmpeg>
+  4. Use the config file: add {"ffmpeg": "<full path>"} to {cfgFile}`,
+
+    'err.cred.missing': `Bilibili credentials not found.
+
+Create {credPath} containing:
+  {
+    "sessdata": "<Bilibili SESSDATA>",
+    "bili_jct": "<bili_jct>",
+    "buvid3": "<buvid3>"
+  }
+How to get them: log in to Bilibili in your browser → F12 → Application → Cookies → bilibili.com,
+then copy those three values. Or set BILI_CRED=<file path> to point at an existing file.
+
+(You can also run selftest first to check whether the environment is ready: node fisheye.mjs selftest)`,
+
+    '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}',
+
+    'err.argPrefix': 'Argument error: ',
+    'err.num.notNumber': '--{name} must be a number, got: {value}',
+    'err.num.min': '--{name} must be >= {min} (got {n})',
+    'err.num.max': '--{name} must be <= {max} (got {n})',
+    'err.grid.format': '--grid must be NxM (e.g. 3x3, rows/cols 1-9), got: {value}',
+    'err.time.format': '--{name} must be a time like 330 / 5:30 / 1:05:30, got: {value}',
+    'err.time.invalid': '--{name} invalid time: {value}',
+    'err.page.range': '--p (page number) must be an integer from 1 to 200, got: {value}'
+  }
+}
+
+/**
+ * 取当前语言的一条文案，替换 {name} 占位符。
+ * 未提供的占位符保持原样，未知 key 返回 key 本身。
+ */
+export function t(key, vars = {}) {
+  const entry = MESSAGES[getLang()]?.[key] ?? MESSAGES[DEFAULT_LANG][key]
+  if (entry === undefined) return key
+  return entry.replace(/\{(\w+)\}/g, (match, name) =>
+    Object.prototype.hasOwnProperty.call(vars, name) ? String(vars[name]) : match)
+}

package/lib/ocr.mjs

@@ -0,0 +1,386 @@
+// OCR（可选）：tesseract 命令行识别画面里的文字（截图标题、PPT、烧进画面的字幕条）
+//
+// 定位：fisheye 的信息源是「官方字幕 → 画面/字幕带 → 弹幕 → 音频」。画面里的文字
+// （弹幕截图、PPT、标题条、烧进画面的字幕）模型只能"看图猜"，OCR 能直接给出原文，
+// 让模型对照文本而不是辨认像素。
+// 它是**可选能力**：找不到 tesseract / 语言包一律返回 null，绝不让整个看片流程失败。
+//
+// 设计约束（和项目其他模块一致）：
+// · 零 npm 依赖，Node ≥18
+// · 所有子进程用 spawnSync；stdout / stderr 分别重定向到临时文件（沙箱禁管道捕获），
+//   分开落盘是为了不让 stderr 的 "Estimating resolution as ..." 混进正文
+// · Windows 路径全部 path.join，可执行文件补 .exe
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { PKG_DIR } from './env.mjs'
+
+const IS_WIN = process.platform === 'win32'
+const EXE = (name) => (IS_WIN ? `${name}.exe` : name)
+
+// tesseract --version 每次探测都跑一遍太浪费，按 cmd 缓存
+const versionCache = new Map()
+
+const stripQuotes = (s) => String(s ?? '').trim().replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1')
+
+function readText(file, limit = 65536) {
+  try { return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '').slice(0, limit) } catch { return '' }
+}
+
+function tmpFile(tag) {
+  return path.join(os.tmpdir(), `fisheye-ocr-${tag}-${process.pid}-${crypto.randomUUID().slice(0, 8)}.txt`)
+}
+
+/**
+ * 跑一个短命令，把 stdout / stderr 分别落到两个临时文件。
+ * 沙箱里不能捕获管道，所以不能用 spawnSync 的 'pipe' —— 只能 fd 重定向。
+ */
+function capture(cmd, args, timeoutMs = 8000) {
+  const outFile = tmpFile('out')
+  const errFile = tmpFile('err')
+  let fdOut = null
+  let fdErr = null
+  try {
+    fdOut = fs.openSync(outFile, 'w')
+    fdErr = fs.openSync(errFile, 'w')
+    const r = spawnSync(cmd, args, {
+      stdio: ['ignore', fdOut, fdErr],
+      timeout: timeoutMs,
+      windowsHide: true,
+    })
+    return {
+      ok: r.status === 0,
+      status: r.status,
+      error: r.error,
+      out: readText(outFile),
+      err: readText(errFile),
+    }
+  } catch (e) {
+    return { ok: false, status: null, error: e, out: '', err: '' }
+  } finally {
+    if (fdOut !== null) try { fs.closeSync(fdOut) } catch {}
+    if (fdErr !== null) try { fs.closeSync(fdErr) } catch {}
+    try { fs.unlinkSync(outFile) } catch {}
+    try { fs.unlinkSync(errFile) } catch {}
+  }
+}
+
+// where.exe / which 的全部命中行（没有命中返回 []）
+function whereAll(name) {
+  const r = capture(IS_WIN ? 'where.exe' : 'which', [name], 5000)
+  if (r.status !== 0) return []
+  return r.out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)
+}
+
+/**
+ * 判断一个 where 命中项是否值得 spawn。
+ * Windows 上 `where tesseract` 一般命中真 exe；但 PATHEXT 里还有 .cpl/.bat 之类，
+ * 直接 spawn 会 ENOENT 或弹控制面板，所以先按扩展名筛掉。
+ */
+function spawnable(p) {
+  if (!p) return false
+  const ext = path.extname(p).toLowerCase()
+  if (IS_WIN && ['.cpl', '.dll', '.msi', '.sys', '.scr', '.bat', '.cmd', '.ps1', '.vbs', '.js'].includes(ext)) return false
+  const looksPath = p.includes('/') || p.includes('\\')
+  if (looksPath && !fs.existsSync(p)) return false
+  try {
+    if (fs.existsSync(p)) {
+      const st = fs.statSync(p)
+      if (!st.isFile() || st.size === 0) return false
+    }
+  } catch { return false }
+  return true
+}
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory() } catch { return false }
+}
+
+/** tessdata 目录：TESSDATA_PREFIX → exe 同级 tessdata → 标准 share 布局 */
+function tessdataDir(cmd, env = process.env) {
+  const cands = []
+  const explicit = stripQuotes(env.TESSDATA_PREFIX)
+  if (explicit) {
+    if (isDir(explicit)) cands.push(explicit)
+    // 少数分发把 TESSDATA_PREFIX 指到 "tessdata 的父目录"
+    if (isDir(path.join(explicit, 'tessdata'))) cands.push(path.join(explicit, 'tessdata'))
+  }
+  if (cmd && (cmd.includes('/') || cmd.includes('\\'))) {
+    const binDir = path.dirname(cmd)
+    cands.push(
+      path.join(binDir, 'tessdata'),
+      path.join(binDir, '..', 'share', 'tesseract-ocr', 'tessdata'),
+      path.join(binDir, '..', 'share', 'tessdata'),
+      path.join(binDir, '..', 'tessdata'),
+    )
+  }
+  for (const d of cands) if (isDir(d)) return path.resolve(d)
+  return null
+}
+
+/** tessdata 里的语言包（* .traineddata 的文件名，去掉扩展名） */
+function listLangs(dir) {
+  if (!dir) return []
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.traineddata'))
+      .map((e) => e.name.slice(0, -'.traineddata'.length))
+      .sort((a, b) => a.localeCompare(b))
+  } catch { return [] }
+}
+
+/** 常见安装路径（不含 PATH）；顺序按需求固定：surfcore → LOCALAPPDATA → Program Files → 项目 bin */
+function commonTesseractPaths(env = process.env) {
+  const home = os.homedir()
+  const localApp = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local')
+  return [
+    path.join(home, '.dsh', 'surfcore', 'tesseract', EXE('tesseract')),
+    path.join(home, '.dsh', 'surfcore', 'tesseract', 'bin', EXE('tesseract')),
+    path.join(localApp, 'Programs', 'Tesseract-OCR', EXE('tesseract')),
+    path.join(localApp, 'Tesseract-OCR', EXE('tesseract')),
+    'C:\\Program Files\\Tesseract-OCR\\tesseract.exe',
+    'C:\\Program Files (x86)\\Tesseract-OCR\\tesseract.exe',
+    path.join(PKG_DIR, 'bin', EXE('tesseract')),
+  ]
+}
+
+// FISHEYE_TESSERACT 可能是 exe 路径 / 安装目录 / PATH 上的命令名
+function resolveEnvCommand(raw, env, notes) {
+  const v = stripQuotes(raw)
+  if (!v) return null
+  if (isDir(v)) {
+    const p = path.join(v, EXE('tesseract'))
+    if (fs.existsSync(p) && spawnable(p)) return path.resolve(p)
+    notes.push(`FISHEYE_TESSERACT=${v} 是目录，但里面没有 ${EXE('tesseract')}`)
+    return null
+  }
+  if (fs.existsSync(v)) {
+    if (!spawnable(v)) { notes.push(`FISHEYE_TESSERACT=${v} 不是可执行文件`); return null }
+    return path.resolve(v)
+  }
+  if (path.isAbsolute(v) || v.includes('/') || v.includes('\\')) {
+    notes.push(`FISHEYE_TESSERACT 指向的文件不存在：${v}`)
+    return null
+  }
+  const hits = whereAll(v).filter(spawnable)
+  if (hits.length) return hits[0]
+  notes.push(`FISHEYE_TESSERACT=${v} 在 PATH 上找不到`)
+  return null
+}
+
+function describe(cmd, source, env) {
+  const abs = path.resolve(cmd)
+  return {
+    cmd: fs.existsSync(abs) ? abs : cmd,
+    binDir: path.dirname(fs.existsSync(abs) ? abs : cmd),
+    tessdata: tessdataDir(abs, env),
+    source,
+  }
+}
+
+function findTesseractDetailed({ env = process.env } = {}) {
+  const e = env ?? {}
+  const notes = []
+
+  // 1) 环境变量：显式指定优先级最高
+  if (e.FISHEYE_TESSERACT) {
+    const cmd = resolveEnvCommand(e.FISHEYE_TESSERACT, e, notes)
+    if (cmd) return { tesseract: describe(cmd, '环境变量 FISHEYE_TESSERACT', e), notes }
+  }
+
+  // 2) PATH 上所有 tesseract 命中项
+  for (const cmd of whereAll('tesseract').filter(spawnable)) {
+    return { tesseract: describe(cmd, 'PATH', e), notes }
+  }
+
+  // 3) 常见安装路径（用户手动解压时它通常不在 PATH 里）
+  for (const cmd of commonTesseractPaths(e)) {
+    if (!fs.existsSync(cmd) || !spawnable(cmd)) continue
+    return { tesseract: describe(cmd, '常见安装路径', e), notes }
+  }
+
+  return { tesseract: null, notes }
+}
+
+/**
+ * 探测可用的 tesseract。
+ * 探测顺序：FISHEYE_TESSERACT → PATH 上 tesseract → 常见安装路径（~/.dsh/surfcore/tesseract、
+ * %LOCALAPPDATA%\Programs\Tesseract-OCR、C:\Program Files\Tesseract-OCR、项目 bin/）。
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ * @returns {{ cmd: string, binDir: string, tessdata: string|null } | null}
+ */
+export function findTesseract({ env } = {}) {
+  const r = findTesseractDetailed({ env: env ?? process.env })
+  if (!r.tesseract) return null
+  const { cmd, binDir, tessdata } = r.tesseract
+  return { cmd, binDir, tessdata }
+}
+
+// --version 输出形如 "tesseract v5.4.0.20240606" / "tesseract 4.1.1"
+function tesseractVersion(cmd) {
+  const key = String(cmd).toLowerCase()
+  if (versionCache.has(key)) return versionCache.get(key)
+  const r = capture(cmd, ['--version'], 8000)
+  const m = `${r.out}\n${r.err}`.match(/tesseract\s+v?([0-9][\w.-]*)/i)
+  const v = m ? m[1] : null
+  versionCache.set(key, v)
+  return v
+}
+
+// 请求的语言里有的语言包没有时降级到交集；一个都没有返回 null
+function resolveLang(requested, langs) {
+  // osd 只做方向检测，不是识别语言，混进 -l 会让 tesseract 输出空页
+  const want = String(requested ?? '').split('+').map((s) => s.trim()).filter(Boolean)
+    .filter((l) => l.toLowerCase() !== 'osd')
+  if (!want.length) return null
+  if (!langs.length) return want.join('+') // 语言包目录没探到，交给 tesseract 自己找
+  const have = new Set(langs.map((l) => l.toLowerCase()))
+  const kept = want.filter((l) => have.has(l.toLowerCase()))
+  return kept.length ? kept.join('+') : null
+}
+
+// chi_sim 会在每个汉字之间插一个空格（"你 好 世 界"），合并回"你好世界"；
+// 只处理「汉字 + 空格 + 汉字」这一种相邻关系，不会动英文单词之间和中文与数字之间的空格
+const CJK = '\\u3400-\\u4dbf\\u4e00-\\u9fff\\u3005-\\u303f\\uff00-\\uffef'
+const CJK_GAP = new RegExp(`([${CJK}])[ \\t]+(?=[${CJK}])`, 'g')
+
+function normalizeText(raw) {
+  return String(raw ?? '')
+    .replace(/\u000c/g, '\n') // tesseract 每页结尾的 form feed
+    .replace(/^\uFEFF/, '')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .join('\n')
+    .replace(CJK_GAP, '$1')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/**
+ * 能力描述（给 CLI / selftest 打印用）。
+ * available 为 true 才表示「现在真的能做 OCR」：tesseract + 至少一个语言包。
+ * @param {{ env?: NodeJS.ProcessEnv, tesseract?: object }} [options]
+ * @returns {{ available: boolean, reason: string, summary: string, hint: string|null,
+ *             cmd: string|null, binDir: string|null, langs: string[],
+ *             tessdata: string|null, version: string|null, notes: string[] }}
+ */
+export function ocrCaps(options = {}) {
+  const env = options.env ?? process.env
+  try {
+    const detail = options.tesseract
+      ? { tesseract: { ...options.tesseract, source: 'opts.tesseract' }, notes: [] }
+      : findTesseractDetailed({ env })
+    const t = detail.tesseract
+    const langs = t ? listLangs(t.tessdata) : []
+    const hasLang = langs.some((l) => l.toLowerCase() !== 'osd')
+    const version = t ? tesseractVersion(t.cmd) : null
+    const caps = {
+      available: false,
+      reason: '',
+      summary: '',
+      hint: null,
+      cmd: t?.cmd ?? null,
+      binDir: t?.binDir ?? null,
+      langs,
+      tessdata: t?.tessdata ?? null,
+      version,
+      notes: detail.notes ?? [],
+    }
+
+    if (!t) {
+      caps.reason = '未找到 tesseract 可执行文件（已试 FISHEYE_TESSERACT / PATH / 常见安装路径）'
+      caps.hint = '装 tesseract 到 ~/.dsh/surfcore/tesseract，或把 tesseract.exe 放进 PATH；'
+        + '中文识别还需要 tessdata/chi_sim.traineddata'
+    } else if (!hasLang) {
+      caps.reason = `找到 ${path.basename(t.cmd)}，但 tessdata 里没有可用的语言包（只有 osd 不算）`
+      caps.hint = '把 eng.traineddata / chi_sim.traineddata 放进 tessdata 目录（或用 TESSDATA_PREFIX 指定）'
+    } else {
+      caps.available = true
+      const bits = [
+        `tesseract ${version ? `v${version}` : path.basename(t.cmd)}`,
+        `语言包 ${langs.join('/')}`,
+      ]
+      if (t.source) bits.push(t.source)
+      caps.reason = bits.join('，')
+      if (!langs.some((l) => l.toLowerCase() === 'chi_sim')) {
+        caps.hint = '没有 chi_sim 语言包，中文画面只能识别英文/数字；把 chi_sim.traineddata 放进 tessdata'
+      }
+    }
+
+    caps.summary = `OCR：${caps.available ? '可用' : '不可用'} —— ${caps.reason}`
+    return caps
+  } catch (e) {
+    return {
+      available: false,
+      reason: `能力探测异常：${String(e?.message ?? e).slice(0, 120)}`,
+      summary: 'OCR：不可用 —— 能力探测异常',
+      hint: null,
+      cmd: null,
+      binDir: null,
+      langs: [],
+      tessdata: null,
+      version: null,
+      notes: [],
+    }
+  }
+}
+
+/**
+ * 识别一张图片里的文字（可选能力，失败不抛异常）。
+ *
+ * @param {string} imagePath 图片路径（png/jpg/bmp/tiff/webp 等，tesseract 支持的格式）
+ * @param {{ lang?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv,
+ *           tesseract?: object, quiet?: boolean }} [options]
+ * @returns {{ text: string, cmd: string, lang: string } | null}
+ */
+export function ocrImage(imagePath, { lang = 'chi_sim+eng', timeoutMs = 30000, env = process.env, tesseract, quiet = false } = {}) {
+  const warn = (msg) => { if (!quiet) console.warn(`[OCR] ${msg}`) }
+
+  try {
+    const file = imagePath ? path.resolve(String(imagePath)) : ''
+    if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      warn(`找不到图片：${imagePath ?? '(空)'}`)
+      return null
+    }
+
+    const t = tesseract ?? findTesseract({ env })
+    if (!t) {
+      warn('没有可用的 tesseract，跳过 OCR（装 tesseract 或设 FISHEYE_TESSERACT）')
+      return null
+    }
+
+    const langs = listLangs(t.tessdata)
+    const useLang = resolveLang(lang, langs)
+    if (!useLang) {
+      warn(`tessdata 里没有 ${lang} 对应的语言包（现有：${langs.join('/') || '无'}）`)
+      return null
+    }
+    if (useLang !== lang) warn(`语言包不全：${lang} → 改用 ${useLang}`)
+
+    // tesseract <img> stdout [--tessdata-dir <dir>] -l <lang>
+    const args = [file, 'stdout']
+    const tessdata = t.tessdata ? path.resolve(t.tessdata) : null
+    if (tessdata) args.push('--tessdata-dir', tessdata)
+    args.push('-l', useLang)
+
+    const r = capture(t.cmd, args, timeoutMs)
+    if (!r.ok) {
+      const why = r.error?.code === 'ETIMEDOUT' ? '超时' : (r.error?.code ?? `退出码 ${r.status}`)
+      const detail = (r.err || r.out).trim().split(/\r?\n/)[0]?.slice(0, 160) ?? ''
+      warn(`tesseract 执行失败（${why}）${detail ? `：${detail}` : ''}`)
+      return null
+    }
+
+    const text = normalizeText(r.out)
+    if (!text) {
+      warn('识别结果为空（画面里可能没有可读文字）')
+      return null
+    }
+    return { text, cmd: t.cmd, lang: useLang }
+  } catch (e) {
+    warn(`OCR 异常：${String(e?.message ?? e).split('\n')[0].slice(0, 120)}`)
+    return null
+  }
+}

package/lib/progress.mjs

@@ -0,0 +1,140 @@
+// 进度反馈：长视频抽帧/下载动辄几分钟，不给进度就像卡死。
+//
+// 设计约束：
+// · 默认写 stderr —— stdout 留给机器可读结果（MANIFEST/SHEET/JSON），别混在一起
+// · TTY 单行覆盖（\r），非 TTY（重定向到文件/管道）每次换行，否则日志会变成一坨
+// · --quiet 用 enabled:false 整体静默，但 elapsed() 仍然准确（耗时统计不受影响）
+// · stream 可注入：测试用假 stream 收集输出，不用去 patch process.stderr
+
+export const isTTYStream = (stream) => Boolean(stream && stream.isTTY)
+
+/** 毫秒 → 人类可读时长：300ms / 1.5s / 2m3s / 1h2m3s */
+export function humanDuration(ms) {
+  let n = Number(ms)
+  if (!Number.isFinite(n) || n < 0) n = 0
+  if (n < 1000) return `${Math.round(n)}ms`
+  if (n < 60000) return `${(n / 1000).toFixed(1)}s`
+  const totalSec = Math.round(n / 1000)
+  const h = Math.floor(totalSec / 3600)
+  const m = Math.floor((totalSec % 3600) / 60)
+  const s = totalSec % 60
+  return h ? `${h}h${m}m${s}s` : `${m}m${s}s`
+}
+
+/** 安全写入：终端已关闭（EPIPE）不该炸掉整个抽帧流程 */
+function safeWrite(stream, text) {
+  if (typeof stream?.write !== 'function') return
+  try { stream.write(text) } catch { /* 忽略写失败 */ }
+}
+
+/**
+ * 进度条。返回 { tick(n=1), set(done), done(), fail(msg), elapsed() }
+ *
+ * @param {string} label  前缀，如 '抽帧'
+ * @param {number} total  总数；<=0 / 非数字表示「总数未知」，只显示已计数
+ * @param {{stream?: {write: Function, isTTY?: boolean}, enabled?: boolean}} opts
+ */
+export function createProgress(label, total, { stream = process.stderr, enabled = true } = {}) {
+  const t0 = Date.now()
+  const rawTotal = Number(total)
+  const totalN = Number.isFinite(rawTotal) && rawTotal > 0 ? Math.floor(rawTotal) : 0
+  const tty = isTTYStream(stream)
+  let done = 0
+  let dirty = false   // TTY 下屏幕上是否已有一行「没换行」的进度
+  let ended = false
+
+  const clamp = (n) => {
+    const v = Number(n)
+    if (!Number.isFinite(v) || v < 0) return 0
+    return totalN ? Math.min(v, totalN) : v
+  }
+  const text = () => {
+    const base = `[${label}] `
+    if (!totalN) return `${base}${done}`
+    const pct = Math.min(100, Math.floor((done / totalN) * 100))
+    return `${base}${done}/${totalN} (${pct}%)`
+  }
+  const render = () => {
+    if (!enabled) return
+    if (tty) {
+      safeWrite(stream, `\r${text()}`)
+      dirty = true
+    } else {
+      safeWrite(stream, `${text()}\n`)
+      dirty = false
+    }
+  }
+  const closeLine = () => {
+    if (dirty) {
+      safeWrite(stream, '\n')
+      dirty = false
+    }
+  }
+
+  const api = {
+    tick(n = 1) {
+      if (ended) return api
+      const step = Number(n)
+      done = clamp(done + (Number.isFinite(step) ? step : 1))
+      render()
+      return api
+    },
+    set(n) {
+      if (ended) return api
+      done = clamp(n)
+      render()
+      return api
+    },
+    done() {
+      if (!ended) {
+        done = totalN || done
+        if (enabled) {
+          render()
+          closeLine()
+        }
+        ended = true
+      }
+      return api.elapsed()
+    },
+    fail(msg) {
+      if (!ended) {
+        if (enabled) {
+          if (tty && dirty) {
+            // 覆盖当前行，失败原因和停在哪一帧一起显示，方便直接定位
+            safeWrite(stream, `\r${text()} 失败：${msg}\n`)
+            dirty = false
+          } else {
+            closeLine()
+            safeWrite(stream, `[${label}] 失败：${msg}\n`)
+          }
+        }
+        ended = true
+      }
+      return api.elapsed()
+    },
+    elapsed() {
+      return Number(((Date.now() - t0) / 1000).toFixed(1))
+    },
+  }
+  return api
+}
+
+/**
+ * 阶段计时器。stop() 输出 `[label] 用时 3.2s`，返回秒数（重复 stop 只输出一次）。
+ * @param {string} label
+ * @param {{stream?: {write: Function, isTTY?: boolean}, enabled?: boolean}} opts
+ */
+export function stageTimer(label, { stream = process.stderr, enabled = true } = {}) {
+  const t0 = Date.now()
+  let stopped = false
+  return {
+    stop() {
+      const ms = Date.now() - t0
+      if (!stopped) {
+        stopped = true
+        if (enabled) safeWrite(stream, `[${label}] 用时 ${humanDuration(ms)}\n`)
+      }
+      return Number((ms / 1000).toFixed(1))
+    },
+  }
+}