@pls-compile-owo/fisheye 0.2.1 → 0.4.2

package/lib/bili.mjs

@@ -0,0 +1,195 @@
+// B站 API：视频信息 / WBI 签名 / 官方字幕 / 播放地址 / 弹幕
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+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'
+
+export let cred = {}
+try {
+  // 去 BOM：README 让用户「复制模板为 credentials.json」，而模板/记事本/PowerShell 写的
+  // UTF-8 常带 BOM。不剥的话 JSON.parse 抛错 → cred 为空 → 匿名拿不到 AI 字幕、
+  // 部分播放地址 403，但正式运行不报错，只有 selftest 报「缺字段」。
+  cred = JSON.parse(fs.readFileSync(CRED, 'utf8').replace(/^\uFEFF/, '')) || {}
+} catch { /* 自检会报 */ }
+
+export const H = {
+  'user-agent': UA,
+  referer: 'https://www.bilibili.com/',
+  cookie: `SESSDATA=${cred.sessdata ?? ''}; bili_jct=${cred.bili_jct ?? ''}; buvid3=${cred.buvid3 ?? ''}`,
+}
+
+// 时长格式化：超过 1 小时显示 01:05:30，否则 MM:SS
+
+export async function getView(bvid) {
+  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
+}
+
+// 官方字幕（看视频最省的一条腿）
+// 有官方/AI 字幕时，台词信息用文本拿（几百 token），比抽字幕带图（1000 token + OCR 误差）又快又准。
+// 关键（踩过的坑，见 subtitles.mjs）
+// ① 必须走 WBI 签名的 /x/player/wbi/v2，旧端点拿到的 subtitle_url 缺 auth_key → CDN 403
+// ② auth_key 分钟级过期，拿到就得马上下载
+// ③ 匿名拿不到 AI 字幕，必须带登录 cookie
+
+export const MIXIN_TAB = [46,47,18,2,53,8,23,32,15,50,10,31,58,3,45,35,27,43,5,49,33,9,42,19,29,28,14,39,12,38,41,13,37,48,7,16,24,55,40,61,26,17,0,1,60,51,30,4,22,25,54,21,56,59,6,63,57,62,11,36,20,34,44,52]
+
+export const keyOf = (u) => u.slice(u.lastIndexOf('/') + 1, u.lastIndexOf('.'))
+
+export const clean = (v) => String(v).replace(/[!'()*]/g, '')
+
+export async function getOfficialSubs(bvid, cid, range = null) {
+  try {
+    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)
+    const wbi = (params) => {
+      const wts = Math.round(Date.now() / 1000)
+      const q = Object.keys({ ...params, wts }).sort()
+        .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 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 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)
+    if (!body.length) return null
+
+    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')
+
+    // 质量判断：B 站 AI 字幕在纯音乐/音效为主的视频里会输出大量「 歌词」噪声或无意义碎片，
+    // 这种字幕不能用（拿它当台词理解视频会全错），应该降级为看图
+    const effChars = body.map((l) => String(l.content ?? '').replace(/[♪\s]/g, '').length)
+    const avgEff = effChars.reduce((a, b) => a + b, 0) / body.length
+    const uniqueRatio = new Set(body.map((l) => String(l.content ?? '').replace(/[♪\s]/g, ''))).size / body.length
+    const chars = effChars.reduce((a, b) => a + b, 0)
+    const quality = avgEff < 2 || uniqueRatio < 0.4 ? 'noisy' : 'ok'
+
+    return {
+      lan: pick.lan, lanDoc: pick.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}`),
+    }
+  } catch (e) {
+    console.warn(`[官方字幕] 获取失败（按无官方字幕处理）：${String(e.message).split('\n')[0].slice(0, 60)}`)
+    return null
+  }
+}
+
+// 下载（一次，复用；分P 分开缓存）
+/**
+ * 缓存视频是否有效。
+ * 只校验文件大小会把「下载中断的残缺文件 / 拷坏的 mp4」当有效缓存复用，
+ * 之后抽帧静默失败，极难排查。mp4 头 12 字节里一定有 ftyp box。
+ */
+
+export function looksLikeMp4(p) {
+  try {
+    if (!fs.existsSync(p) || fs.statSync(p).size <= 1024) return false
+    const fd = fs.openSync(p, 'r')
+    const buf = Buffer.alloc(12)
+    fs.readSync(fd, buf, 0, 12, 0)
+    fs.closeSync(fd)
+    return buf.includes(Buffer.from('ftyp'))
+  } catch { return false }
+}
+
+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
+
+  const data = await getView(bvid)
+  const page = data.pages?.[pageNo - 1]
+  if (!page) throw new Error(`没有第 ${pageNo} 个分P（这条视频共 ${data.pages?.length ?? 1} 个）`)
+  const { cid } = page
+  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 fetchWithRetry(
+    `https://api.bilibili.com/x/player/playurl?bvid=${bvid}&cid=${cid}&qn=80&fnval=1&platform=pc&high_quality=1`,
+    { 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 fetchWithRetry(url, {
+    headers: { 'user-agent': UA, referer: 'https://www.bilibili.com/', range: 'bytes=0-' },
+  }, { 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 已丢弃）')
+  const part = p + '.part'
+  fs.writeFileSync(part, buf)
+  fs.renameSync(part, p)
+  console.log(`[下载] ${title}  ${duration}s  →  ${(fs.statSync(p).size / 1048576).toFixed(2)} MB`)
+  return p
+}
+
+// 画面变化点：一次解码，把带分数的候选全部拿出来
+// 旧做法是每个阈值各跑一遍 ffmpeg（0.3 / 0.15 / 0.08 三遍全片解码），慢且浪费。
+// 现在只解码一遍（阈值放最低 0.05），把每处的 scene_score 一起记下，阈值阶梯在内存里做，零重复成本。
+// 注意：沙箱下 child_process 的 stdout 管道被禁（EPERM），只能用「ffmpeg 写临时文件」的方式取输出。
+
+export async function getDanmaku(cid, range = null) {
+  try {
+    const r = await fetchWithRetry(`https://comment.bilibili.com/${cid}.xml`, {
+      headers: { 'user-agent': UA, referer: 'https://www.bilibili.com/' },
+    }, { timeoutMs: 20000 })
+    if (!r.ok) return null
+    const xml = await r.text()
+    const list = []
+    for (const m of xml.matchAll(/<d p="([^"]*)">([^<]*)<\/d>/g)) {
+      const t = Number(String(m[1]).split(',')[0])
+      const text = String(m[2] ?? '').trim()
+      if (!Number.isFinite(t) || !text) continue
+      if (range && (t < range.from || t > range.to)) continue
+      list.push({ t, text })
+    }
+    return list
+  } catch (e) {
+    console.warn(`[弹幕] 获取失败（忽略，不影响其余流程）：${String(e.message).split('\n')[0].slice(0, 60)}`)
+    return null
+  }
+}
+
+// 弹幕过滤逻辑在 danmaku-filter.mjs（与测试共用同一份实现，避免测试测副本）
+
+// 广告段检测（视频内广告，不是弹幕文本广告）
+// 判断依据来自案例 BV1i4W86zEUS（小约翰可汗 40 分钟视频，
+// 用户指认 04:35-06:49 是鱼油广告）
+// · 广告段弹幕密度只有全片的 31%（观众跳过 / 不互动）
+// · 「感谢金主爸爸」这类关键词会在广告段附近出现
+// 只用密度会误报（纯画面段、BGM 段也是低谷），所以分两级
+// high = 密度低谷 且 附近有关键词命中（可直接标注为广告）
+// low = 只有密度低谷（标成「低互动段」，不当广告）

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/danmaku.mjs

@@ -0,0 +1,75 @@
+// 弹幕分析：广告段检测 / 热区摘要（过滤规则在 danmaku-filter.mjs）
+import { fmt } from './util.mjs'
+
+
+export const AD_SEGMENT_SIGNAL = /金主|恰饭|商单|硬广|软广|赞助|推广|接广|带货|下单|同款|优惠码/i;
+
+export function detectAdSegments(danmaku, duration, bucketSec = 30, stepSec = 10) {
+  if (!danmaku?.length || duration < 120) return []
+  const dens = []
+  for (let s = 0; s + bucketSec <= duration; s += stepSec) {
+    let n = 0
+    for (const d of danmaku) if (d.t >= s && d.t < s + bucketSec) n++
+    dens.push({ s, n })
+  }
+  if (!dens.length) return []
+  const nums = dens.map((d) => d.n).sort((a, b) => a - b)
+  const median = nums[Math.floor(nums.length / 2)] || 1
+  // 低密度：低于中位数的 45%
+  const spans = []
+  for (const d of dens) {
+    if (d.n >= median * 0.45) continue
+    const last = spans[spans.length - 1]
+    if (last && d.s - last.to <= stepSec * 2) last.to = d.s + bucketSec
+    else spans.push({ from: d.s, to: d.s + bucketSec, count: 0 })
+  }
+  const long = spans.filter((x) => x.to - x.from >= 60)
+  if (!long.length) return []
+
+  const hits = danmaku.filter((d) => AD_SEGMENT_SIGNAL.test(d.text))
+  return long.map((sp) => {
+    const near = hits.filter((h) => h.t >= sp.from - 20 && h.t <= sp.to + 20)
+    // dens 是「30s 窗、10s 步长」的滑窗，同一条弹幕会被相邻 3 个桶各计一次。
+    // 分母必须用「实际桶数」而不是 (时长/bucketSec)，否则 ratio 虚高约 3 倍
+    // （出现 lowDensity = -25% 的负值，因为 ratio > 1）
+    const segBuckets = dens.filter((d) => d.s >= sp.from && d.s < sp.to)
+    const total = segBuckets.reduce((s, d) => s + d.n, 0)
+    const ratio = total / Math.max(1, segBuckets.length) / median
+    return {
+      from: sp.from,
+      to: sp.to,
+      dur: sp.to - sp.from,
+      ts: `${fmt(sp.from)}-${fmt(sp.to)}`,
+      lowDensity: Number((1 - ratio).toFixed(2)),
+      confidence: near.length ? 'high' : 'low',
+      keywords: near.slice(0, 3).map((h) => h.text),
+    }
+  })
+}
+
+// 按时间桶聚合，找「观众最激动」的时段。
+// 高频重复的弹幕最能代表那里在刷什么（梗 / 共鸣），所以每个热区取前 3 条并标出现次数。
+
+export function summarizeDanmaku(list, bucketSec = 5, topN = 6) {
+  if (!list?.length) return null
+  const buckets = new Map()
+  for (const d of list) {
+    const k = Math.floor(d.t / bucketSec) * bucketSec
+    if (!buckets.has(k)) buckets.set(k, [])
+    buckets.get(k).push(d.text)
+  }
+  return [...buckets.entries()]
+    .map(([start, texts]) => ({ start, texts }))
+    .sort((a, b) => b.texts.length - a.texts.length)   // 先按密度挑出最热的 N 个桶
+    .slice(0, topN)
+    .sort((a, b) => a.start - b.start)                  // 再按时间顺序展示
+    .map(({ start, texts }) => {
+      const freq = new Map()
+      for (const t of texts) freq.set(t, (freq.get(t) ?? 0) + 1)
+      const samples = [...freq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([t, n]) => (n > 1 ? `${t}×${n}` : t))
+      return { start, end: start + bucketSec, ts: fmt(start), count: texts.length, samples }
+    })
+}

package/lib/env.mjs

@@ -0,0 +1,61 @@
+// 路径与依赖解析：不写死绝对路径，解析顺序：环境变量 → ~/.config/fisheye/config.json → 项目内 bin/ → PATH
+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
+export const CACHE = path.join(WS, 'cache')
+export const OUT = path.join(WS, 'out')
+export const CFG_FILE = path.join(os.homedir(), '.config', 'fisheye', 'config.json')
+export let LOCAL_CFG = {}
+try {
+  LOCAL_CFG = JSON.parse(fs.readFileSync(CFG_FILE, 'utf8').replace(/^\uFEFF/, '')) || {}
+} catch { LOCAL_CFG = {} }
+
+export function onPath(cmd) {
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { stdio: 'ignore', timeout: 5000 })
+    return true
+  } catch { return false }
+}
+
+/** 按 环境变量 → 配置文件 → 项目内 bin → PATH 的顺序找工具；找不到返回 null */
+
+export function resolveTool(envVar, cfgKey, localCandidates, cmdName) {
+  if (process.env[envVar]) return { cmd: process.env[envVar], from: `环境变量 ${envVar}` }
+  if (LOCAL_CFG[cfgKey] && fs.existsSync(LOCAL_CFG[cfgKey])) return { cmd: LOCAL_CFG[cfgKey], from: CFG_FILE }
+  for (const c of localCandidates) if (fs.existsSync(c)) return { cmd: c, from: '项目内 bin/' }
+  if (onPath(cmdName)) return { cmd: cmdName, from: 'PATH' }
+  return null
+}
+
+export const FFMPEG_RES = resolveTool('FFMPEG', 'ffmpeg', [
+  path.join(PKG_DIR, 'bin', 'ffmpeg.exe'), path.join(PKG_DIR, 'bin', 'ffmpeg'),
+], 'ffmpeg')
+
+export const PYTHON_RES = resolveTool('PYTHON', 'python', [
+  path.join(PKG_DIR, '.venv', 'Scripts', 'python.exe'), path.join(PKG_DIR, '.venv', 'bin', 'python'),
+], process.platform === 'win32' ? 'python' : 'python3')
+
+export const FFMPEG = FFMPEG_RES?.cmd ?? null
+
+export const PYTHON = PYTHON_RES?.cmd ?? null
+
+/** B站登录态：环境变量 → config.json → 数据目录 → ~/.config/fisheye/ */
+
+export function resolveCred() {
+  if (process.env.BILI_CRED) return process.env.BILI_CRED
+  if (LOCAL_CFG.credentials && fs.existsSync(LOCAL_CFG.credentials)) return LOCAL_CFG.credentials
+  for (const c of [
+    path.join(WS, 'credentials.json'),
+    path.join(os.homedir(), '.config', 'fisheye', 'credentials.json'),
+  ]) if (fs.existsSync(c)) return c
+  return null
+}
+
+export const CRED = resolveCred()
+
+// 自检要能诊断「依赖缺失」本身，所以 selftest 时不在下面硬退出

package/lib/frame.mjs

@@ -0,0 +1,192 @@
+// 抽帧与时间点选择：场景检测 / 广告剔除 / 取帧计划 / 字幕带定位 / 单帧截取 / 子进程封装
+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'
+
+export function detectScenes(file) {
+  // 文件名带 pid + 时间戳：两个视频并发跑时不会互相覆盖
+  const name = `.scenes-${process.pid}-${Date.now()}.txt`
+  const abs = path.join(OUT, name)
+  try {
+    if (fs.existsSync(abs)) fs.rmSync(abs, { force: true })
+    execFileSync(FFMPEG, ['-hide_banner', '-i', file, '-vf',
+      `scale=320:-2,select='gt(scene,0.05)',metadata=print:file=${name}`, '-an', '-f', 'null', '-'],
+      { stdio: 'ignore', cwd: OUT })
+    if (!fs.existsSync(abs)) return []
+    const out = fs.readFileSync(abs, 'utf8')
+    fs.rmSync(abs, { force: true })
+    // 输出是两行一组： "…pts_time:4.1" 紧跟 "lavfi.scene_score=0.42"
+    const ents = []
+    let cur = null
+    for (const line of out.split('\n')) {
+      const t = line.match(/pts_time:\s*([0-9.]+)/)
+      if (t) { cur = { t: Number(t[1]), score: 0 }; continue }
+      const s = line.match(/scene_score=([0-9.]+)/)
+      if (s && cur) { cur.score = Number(s[1]); ents.push(cur); cur = null }
+    }
+    return ents.filter((e) => e.t > 0.2)
+  } catch { return [] }
+}
+
+// 段内取帧：等间隔骨架 + 吸附变化点（阈值阶梯 + 去重）
+// 基准点 ((i+0.5)*dur/n) 让每格的吸附窗口 [base±dur/2n] 恰好铺满整段、且不越界。
+// 从 [from,to] 里减掉广告段，返回剩余连续区间（用于「广告不占帧」）
+
+export function subtractAds(from, to, adSegs) {
+  let segs = [{ a: from, b: to }]
+  for (const ad of adSegs) {
+    const next = []
+    for (const s of segs) {
+      if (ad.to <= s.a || ad.from >= s.b) { next.push(s); continue }
+      if (ad.from > s.a) next.push({ a: s.a, b: ad.from })
+      if (ad.to < s.b) next.push({ a: ad.to, b: s.b })
+    }
+    segs = next
+  }
+  return segs.filter((s) => s.b - s.a > 0.5)
+}
+
+export function pickTimes(from, to, n, scenes, adSegs = []) {
+  const dur = to - from
+  const inAd = (t) => adSegs.some((ad) => t >= ad.from && t <= ad.to)
+
+  // 广告段时间从时间轴上「压缩掉」：在剩余有效时间里等间隔取基准点。
+  // 效果 = 帧数不变、广告不占帧、多出来的时长自动分给内容（密度提升）。
+  const segs = adSegs.length ? subtractAds(from, to, adSegs) : [{ a: from, b: to }]
+  if (!segs.length) return null                      // 整段都是广告 → 调用方跳过这张图
+  const totalEff = segs.reduce((s, x) => s + (x.b - x.a), 0)
+  const base = []
+  for (let i = 0; i < n; i++) {
+    let rem = ((i + 0.5) / n) * totalEff
+    let t = segs[segs.length - 1].b
+    for (const s of segs) {
+      const d = s.b - s.a
+      if (rem <= d) { t = s.a + rem; break }
+      rem -= d
+    }
+    base.push(t)
+  }
+
+  // 吸附窗口/去重下限按「有效时长」算，而不是原始段长。
+  // 段里有广告时，内容被压缩得更密，用原始 dur 会让窗口过大 → 多帧吸到同一点后被去重退回
+  // （40 分钟视频图2：跳过 118s 广告后 9 帧里有 5 帧被退回）
+  const timingBase = totalEff > 0 ? totalEff : dur
+  const half = timingBase / n / 2
+  const minGap = (timingBase / n) * 0.4 // 去重下限：相邻两帧至少隔这么多
+
+  const tryThreshold = (th) => {
+    // 吸附候选也排除广告段：不然帧会被吸到广告里的高变化点（片头/转场）
+    const cands = scenes.filter((s) => s.score >= th && !inAd(s.t))
+    const raw = base.map((b) => {
+      const near = cands.filter((s) => Math.abs(s.t - b) <= half)
+      if (!near.length) return b
+      // 窗口内可能挤着多个变化点：取「最剧烈」的而不是「最近」的——
+      // 时间代表性靠窗口保证（都在 ±half 内），视觉显著性决定落在哪一刻
+      return near.reduce((x, s) => (s.score > x.score ? s : x)).t
+    })
+    // snapped 统计的是「吸附能力」，必须在去重前算 —— 否则被去重退回的帧会被误记成「没吸到」
+    const snapped = raw.filter((t, i) => Math.abs(t - base[i]) > 1e-6).length
+
+    // 去重：吸附后若相邻两帧挤得比 minGap 还近，把后一个退回它自己的等间隔基准点
+    // （基准点之间间距 = dur/n，永远不会违反 minGap，所以退回一定安全）
+    const times = raw.slice()
+    for (let i = 1; i < times.length; i++) {
+      if (Math.abs(times[i] - times[i - 1]) < minGap) times[i] = base[i]
+    }
+    let dedup = 0
+    for (let i = 1; i < times.length; i++) {
+      if (Math.abs(raw[i] - times[i]) > 1e-6) dedup++
+    }
+    return { times, th, snapped, dedup, base }
+  }
+
+  // 阈值阶梯：从严格到宽松，取第一个「≥75% 帧都吸附成功」的档位
+  // （段变短后吸附窗口 half 会变小，过半门槛太松，容易留下大量没吸到的帧）
+  let fallback = null
+  for (const th of [0.3, 0.15, 0.08]) {
+    const r = tryThreshold(th)
+    if (!fallback) fallback = r
+    if (r.snapped >= Math.ceil(n * 0.75)) return r
+  }
+  return fallback
+}
+
+// 字幕行取帧：等间隔骨架 + 吸附变化点（字幕通常在镜头切换时更新，纯等间隔会取到
+// 「还没出字幕」的过渡帧——第一条字幕带的行 1 经常是空的）
+
+export function snapSubsTimes(span, count, scenes, start = 0) {
+  const base = Array.from({ length: count }, (_, i) => start + ((i + 0.5) * span) / count)
+  const cands = scenes.filter((s) => s.score >= 0.15 && s.t >= start && s.t <= start + span)
+  if (!cands.length) return base
+  const half = span / count / 2
+  const minGap = (span / count) * 0.4
+  const times = base.map((b) => {
+    const near = cands.filter((s) => Math.abs(s.t - b) <= half)
+    if (!near.length) return b
+    return near.reduce((x, s) => (s.score > x.score ? s : x)).t
+  })
+  for (let i = 1; i < times.length; i++) {
+    if (Math.abs(times[i] - times[i - 1]) < minGap) times[i] = base[i]
+  }
+  return times
+}
+
+// 弹幕：独立于画面和字幕的第三个信息源
+// 为什么值得拉：弹幕密集的时段 = 观众真正觉得精彩的地方，可以直接指导精读选点；
+// 而且它能看到画面和字幕里都没有的东西——大家在哪一秒笑、在刷什么梗。
+// 数据源：https://comment.bilibili.com/<cid>.xml
+// 每条 <d p="相对秒,模式,字号,颜色,...,>内容</d>，只取第一段（相对时间）和文本
+
+export function detectBand(mp4, duration) {
+  const probe = path.join(OUT, `.probe-${Date.now()}`)
+  try {
+    fs.mkdirSync(probe, { recursive: true })
+    // 逐帧快速 seek 抽 24 帧：fps 滤镜虽然只输出 24 帧，但必须全片解码，长视频下慢一个数量级
+    // 注意：这里**必须跨全片采样**，不能只看 --from/--to 区间 —— 字幕位置是视频级属性，
+    // 只在区间内采样时，区间里若恰好多帧无字幕，峰值会被画面边缘抢走（82%-90% 跑偏成 55%-83%）
+    for (let i = 0; i < 24; i++) {
+      const t = ((i + 0.5) * Math.max(duration, 1)) / 24
+      grabFrame(mp4, t, path.join(probe, `f${String(i).padStart(2, '0')}.jpg`))
+    }
+    const jsonPath = path.join(probe, 'subs.json')
+    execFileSync(PYTHON, [path.join(PKG_DIR, 'analyze_subs.py'), probe, jsonPath], { stdio: 'ignore' })
+    const r = JSON.parse(fs.readFileSync(jsonPath, 'utf8'))
+    return r.ok ? r : null
+  } catch (e) {
+    // Python 缺失、分析脚本报错、抽帧失败 —— 一律降级为「没有字幕」，不能让整个流程崩掉
+    console.warn(`[字幕] 检测失败（将按无字幕处理）：${String(e.message).split('\n')[0].slice(0, 80)}`)
+    return null
+  } finally {
+    try { fs.rmSync(probe, { recursive: true, force: true }) } catch {}
+  }
+}
+
+// 抽一帧；失败返回 false 而不是抛异常（t 越界、解码失败都可能发生）
+
+export function grabFrame(mp4, t, outFile, quality = 3) {
+  try {
+    execFileSync(FFMPEG, ['-y', '-loglevel', 'error', '-ss', t.toFixed(3), '-i', mp4,
+      '-an', '-frames:v', '1', '-q:v', String(quality), outFile], { stdio: 'ignore' })
+    return fs.existsSync(outFile)
+  } catch {
+    return false
+  }
+}
+
+export function runCapture(cmd, args, timeoutMs = 15000) {
+  const tmp = path.join(WS, `.selftest-${process.pid}-${crypto.randomUUID().slice(0, 8)}.txt`)
+  let fd = null
+  try {
+    fd = fs.openSync(tmp, 'w')
+    // 沙箱禁管道捕获 stdout，所以写到文件再读（和 detectScenes 同样的做法）
+    execFileSync(cmd, args, { stdio: ['ignore', fd, 'ignore'], timeout: timeoutMs })
+    return { ok: true, out: fs.readFileSync(tmp, 'utf8') }
+  } catch (e) {
+    return { ok: false, out: '', err: String(e?.message ?? e).split('\n')[0] }
+  } finally {
+    if (fd !== null) try { fs.closeSync(fd) } catch {}
+    try { fs.unlinkSync(tmp) } catch {}
+  }
+}