@pls-compile-owo/fisheye 0.3.0 → 0.7.1

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

@@ -6,6 +6,8 @@ import crypto from 'node:crypto'
 import { execFileSync, spawnSync } from 'node:child_process'
 import { FFMPEG, CACHE, WS, CRED, OUT } from './env.mjs'
 import { fmt } from './util.mjs'
+// 所有 B站请求都走 fetchWithRetry：网络抖动 / 429 / 5xx 时自动重试（指数退避），幂等 GET 才重试
+import { fetchWithRetry } from './retry.mjs'
 
 export const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36'
 
@@ -26,8 +28,8 @@ export const H = {
 // 时长格式化：超过 1 小时显示 01:05:30，否则 MM:SS
 
 export async function getView(bvid) {
-  const r = await fetch(`https://api.bilibili.com/x/web-interface/view?bvid=${bvid}`,
-    { headers: H, signal: AbortSignal.timeout(15000) })
+  const r = await fetchWithRetry(`https://api.bilibili.com/x/web-interface/view?bvid=${bvid}`,
+    { headers: H }, { timeoutMs: 15000 })
   const v = await r.json()
   if (v.code !== 0) throw new Error(`view code=${v.code} ${v.message}`)
   return v.data
@@ -46,10 +48,38 @@ 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 fetch('https://api.bilibili.com/x/web-interface/nav',
-      { headers: H, signal: AbortSignal.timeout(15000) })).json()
+    const nav = await (await fetchWithRetry('https://api.bilibili.com/x/web-interface/nav',
+      { headers: H }, { timeoutMs: 15000 })).json()
     const raw = keyOf(nav.data?.wbi_img?.img_url ?? '') + keyOf(nav.data?.wbi_img?.sub_url ?? '')
     if (raw.length < 64) return null
     const mixin = MIXIN_TAB.map((i) => raw[i]).join('').slice(0, 32)
@@ -59,31 +89,56 @@ export async function getOfficialSubs(bvid, cid, range = null) {
         .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(clean(k === 'wts' ? wts : params[k]))}`).join('&')
       return `${q}&w_rid=${crypto.createHash('md5').update(q + mixin).digest('hex')}`
     }
-    const p = await (await fetch(`https://api.bilibili.com/x/player/wbi/v2?${wbi({ bvid, cid })}`,
-      { headers: H, signal: AbortSignal.timeout(15000) })).json()
+    const p = await (await fetchWithRetry(`https://api.bilibili.com/x/player/wbi/v2?${wbi({ bvid, cid })}`,
+      { 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 fetch(url, {
-      headers: { 'user-agent': UA, referer: `https://www.bilibili.com/video/${bvid}/` },
-      signal: AbortSignal.timeout(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
 
-    const txt = path.join(OUT, `${bvid}-official-subs.txt`)
+    fs.mkdirSync(OUT, { recursive: true })
+  const txt = path.join(OUT, `${bvid}-official-subs.txt`)
     const plain = path.join(OUT, `${bvid}-official-subs-plain.txt`)
     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)
@@ -93,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)}`)
@@ -122,6 +179,7 @@ export function looksLikeMp4(p) {
 }
 
 export async function ensureMp4(bvid, pageNo = 1) {
+  fs.mkdirSync(CACHE, { recursive: true })
   const p = path.join(CACHE, pageNo > 1 ? `${bvid}-p${pageNo}.mp4` : `${bvid}.mp4`)
   if (looksLikeMp4(p)) return p
 
@@ -132,18 +190,17 @@ export async function ensureMp4(bvid, pageNo = 1) {
   const duration = page.duration ?? data.duration
   const title = page.part && data.pages.length > 1 ? `${data.title} · P${pageNo} ${page.part}` : data.title
 
-  const pu = await (await fetch(
+  const pu = await (await fetchWithRetry(
     `https://api.bilibili.com/x/player/playurl?bvid=${bvid}&cid=${cid}&qn=80&fnval=1&platform=pc&high_quality=1`,
-    { headers: H, signal: AbortSignal.timeout(15000) })).json()
+    { headers: H }, { timeoutMs: 15000 })).json()
   const url = pu.data?.durl?.[0]?.url
   if (!url) throw new Error(`没拿到直链 code=${pu.code}`)
 
   // 下载到 .part 再 rename：网络中断时只会留下 .part，不会把半个 mp4 伪装成缓存
   // （旧实现直接写最终路径，中断后下次运行会拿着残缺文件当缓存用）
-  const r = await fetch(url, {
+  const r = await fetchWithRetry(url, {
     headers: { 'user-agent': UA, referer: 'https://www.bilibili.com/', range: 'bytes=0-' },
-    signal: AbortSignal.timeout(300000),
-  })
+  }, { timeoutMs: 300000 })
   if (!r.ok) throw new Error(`下载失败 HTTP ${r.status}`)
   const buf = Buffer.from(await r.arrayBuffer())
   if (buf.length < 1024) throw new Error('下载内容过短，可能被中断（.part 已丢弃）')
@@ -161,10 +218,9 @@ export async function ensureMp4(bvid, pageNo = 1) {
 
 export async function getDanmaku(cid, range = null) {
   try {
-    const r = await fetch(`https://comment.bilibili.com/${cid}.xml`, {
+    const r = await fetchWithRetry(`https://comment.bilibili.com/${cid}.xml`, {
       headers: { 'user-agent': UA, referer: 'https://www.bilibili.com/' },
-      signal: AbortSignal.timeout(20000),
-    })
+    }, { timeoutMs: 20000 })
     if (!r.ok) return null
     const xml = await r.text()
     const list = []

package/lib/budget.mjs

@@ -0,0 +1,117 @@
+// lib/budget.mjs —— token 预算估算（零依赖，Node ≥18）
+//
+// 为什么单独拆一个模块：
+//   fisheye 的整个「抽多少帧 / 拼几张图」决策都建立在「一张图 ≈ 多少 token」上。
+//   旧版把这个值写死在 stages.mjs（COST = { grid: 1200, subs: 1000, fine: 1300 }），
+//   但不同模型的图像 tokenizer 差异很大——同一张 1920x1080 拼图，
+//   Gemini 对单图按固定档位计（约 258 token 起），GPT-4o high detail 按 512px 瓦片计（约 1.1k~2.1k），
+//   Qwen-VL 系列走动态分辨率（28px patch，token 更多）。固定系数会系统性高估或低估 20~30%，
+//   直接让「预算只够几张」算错，最后要么超支、要么白白变稀。
+//
+// 估算公式：
+//   estimateTokens(kind, count) = round(tokensPerUnit(kind) * count)
+//   tokensPerUnit(kind)         = round(基准(kind) * 模型系数)      // 单张/单帧成本
+//
+// 基准值（环境变量可覆盖，单位 token；覆盖值须为正数，非法值忽略并告警一次）：
+//   grid = 1200  FISHEYE_TOKENS_PER_GRID
+//       3x3 拼图（9 格 × 640px，约 1920x1080）。stageAuto 还会按实际画面面积再修正，
+//       所以这里只是 16:9 的基准值。
+//   subs = 1000  FISHEYE_TOKENS_PER_SUBS
+//       烧录字幕带（1xN 行，只裁画面里的字幕条，信息密度高但仍是图）。
+//   fine = 1300  FISHEYE_TOKENS_PER_FINE
+//       精读用单帧原图（不压成 640 格，通常比拼图里的单格更贵一点）。
+//
+// 模型系数（FISHEYE_TOKEN_MODEL，默认 1.0 = 基准，保持向后兼容）：
+//   gpt     1.0    GPT-4o / 4.1 一类按 512px 瓦片计费的基准
+//   qwen    1.35   Qwen2-VL / 2.5-VL 动态分辨率，同图 token 明显更多（保守取 1.35）
+//   gemini  0.8    Gemini 单图固定档位计费，token 更少；取 0.8 作为保守下限（不按 258 的极端值算）
+//   也可直接写数字（如 1.2），会被收敛到 [0.25, 4] 区间
+//
+// 兼容性：三个环境变量都不设、FISHEYE_TOKEN_MODEL 也不设时，
+//   estimateTokens('grid'|'subs'|'fine', n) 与旧版 COST.* × n 完全一致。
+
+// 默认单张成本（token）。导出 COST 是为了兼容旧代码里 `import { COST } from './stages.mjs'` 的用法。
+const DEFAULTS = Object.freeze({ grid: 1200, subs: 1000, fine: 1300 })
+
+export const COST = DEFAULTS
+
+// 模型系数表：只描述「相对基准模型，同一张图的 token 大致贵/便宜多少」。
+// 数值来自公开的计费规则量级（图像 500~4000 token/图），不是精确 tokenizer 复刻；
+// 目的是把 20~30% 的系统性偏差收窄，而不是追求逐像素精确。
+export const MODEL_FACTORS = Object.freeze({
+  gpt: 1,
+  qwen: 1.35,
+  gemini: 0.8,
+})
+
+const ENV_PER_UNIT = Object.freeze({
+  grid: 'FISHEYE_TOKENS_PER_GRID',
+  subs: 'FISHEYE_TOKENS_PER_SUBS',
+  fine: 'FISHEYE_TOKENS_PER_FINE',
+})
+
+const FACTOR_MIN = 0.25
+const FACTOR_MAX = 4
+
+// 同一个错误只提示一次，避免在每个拼图的日志里刷屏
+const warned = new Set()
+function warnOnce(key, message) {
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(`[预算] ${message}`)
+}
+
+function toPositiveNumber(raw) {
+  if (raw === undefined || raw === null) return null
+  const text = String(raw).trim()
+  if (!text) return null
+  const n = Number(text)
+  return Number.isFinite(n) && n > 0 ? n : null
+}
+
+/** 解析模型系数；无法识别/非法时回退 1.0（并告警一次），保证环境变量写错不会瘫痪 CLI */
+export function modelFactor(raw = process.env.FISHEYE_TOKEN_MODEL) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return 1
+  const key = String(raw).trim().toLowerCase()
+  if (Object.prototype.hasOwnProperty.call(MODEL_FACTORS, key)) return MODEL_FACTORS[key]
+  const n = toPositiveNumber(key)
+  if (n !== null) {
+    const clamped = Math.min(FACTOR_MAX, Math.max(FACTOR_MIN, n))
+    if (clamped !== n) warnOnce(`factor:${n}`, `FISHEYE_TOKEN_MODEL=${raw} 超出合理范围，已收敛为 ×${clamped}`)
+    return clamped
+  }
+  warnOnce(`model:${key}`, `FISHEYE_TOKEN_MODEL=${raw} 不认识（可用 gpt / qwen / gemini，或 0.5~2 的数字），按 ×1 估算`)
+  return 1
+}
+
+/** 单张（单帧）成本：基准 × 模型系数，四舍五入到整数 token */
+export function tokensPerUnit(kind) {
+  const base = DEFAULTS[kind]
+  if (base === undefined) {
+    throw new Error(`tokensPerUnit：未知 kind「${kind}」（支持 ${Object.keys(DEFAULTS).join(' / ')}）`)
+  }
+  const envVar = ENV_PER_UNIT[kind]
+  const raw = process.env[envVar]
+  let unit = base
+  if (raw !== undefined && String(raw).trim() !== '') {
+    const n = toPositiveNumber(raw)
+    if (n === null) warnOnce(`env:${envVar}`, `${envVar}=${raw} 不是正数，忽略，仍用默认 ${base}`)
+    else unit = n
+  }
+  return Math.round(unit * modelFactor())
+}
+
+/**
+ * 估算 count 个单位的 token 消耗。
+ * @param {'grid'|'subs'|'fine'} kind 单位类型：拼图 / 烧录字幕带 / 精读单帧
+ * @param {number} [count=1] 数量；非有限数或 ≤0 视为 0（空列表不花钱）
+ * @returns {number} 整数 token
+ */
+export function estimateTokens(kind, count = 1) {
+  if (DEFAULTS[kind] === undefined) {
+    throw new Error(`estimateTokens：未知 kind「${kind}」（支持 ${Object.keys(DEFAULTS).join(' / ')}）`)
+  }
+  const n = count === undefined || count === null ? 1 : Number(count)
+  if (!Number.isFinite(n) || n <= 0) return 0
+  return Math.round(tokensPerUnit(kind) * n)
+}

package/lib/env.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
 
 export const PKG_DIR = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
 export const WS = process.env.FISHEYE_HOME || PKG_DIR

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 + 时间戳：两个视频并发跑时不会互相覆盖