@pls-compile-owo/fisheye 0.4.2 → 0.7.2

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}',
 

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
+  }
+}