@pls-compile-owo/fisheye 0.2.1 → 0.4.2

package/lib/i18n.mjs

@@ -0,0 +1,131 @@
+// 国际化：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]      ← 推荐：自动规划并铺网
+  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 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.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]      # recommended: auto-plan and build grids
+  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 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.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/retry.mjs

@@ -0,0 +1,209 @@
+// 带「重试 + 指数退避」的 fetch 封装（零依赖，只用 Node >= 18 内置能力）
+//
+// 背景：lib/bili.mjs 里的 B站请求都是幂等 GET，但原来是裸 fetch——网络抖动 / 429 限流 /
+// 网关 5xx 一次失败就让整条命令直接挂掉（getView 抛错、ensureMp4 失败、字幕静默降级）。
+// 这里统一加一层重试，调用点只把 fetch 换成 fetchWithRetry，不改各函数的签名和返回值。
+//
+// 策略：
+// · 只重试可安全重复的失败：网络错误 / 超时 / HTTP 5xx / 429。
+// · 其余 4xx（鉴权失效、参数错、资源不存在）是确定性失败，重试没有意义，直接把 Response 交给调用方。
+// · 退避 delay = baseDelayMs * 2^attempt + 随机 jitter；429/503 若带 Retry-After 头则优先听它的
+//   （仍受 MAX_BACKOFF_MS 上限约束，避免被服务端要求等几小时）。
+// · 每次尝试都新建独立的超时 signal：AbortSignal.timeout() 触发后不可复用，跨 attempt 复用会让
+//   第二次重试瞬间失败。外部 AbortController 的 signal 则跨 attempt 保持生效（用于用户主动取消）。
+// · 返回原生 Response，调用方照常 .json() / .text() / .arrayBuffer() 消费。
+
+const DEFAULT_RETRIES = 2
+const DEFAULT_BASE_DELAY_MS = 500
+const MAX_BACKOFF_MS = 30_000
+
+// undici 的网络错误会包一层 TypeError('fetch failed')，真正的 code 在 err.cause 里
+const NETWORK_ERROR_RE = /fetch failed|network error|ECONNRESET|ECONNREFUSED|ECONNABORTED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EPIPE|UND_ERR|socket hang up|terminated|other side closed|connection (?:reset|closed|refused)|getaddrinfo/i
+
+/** 5xx 和 429 可以重试；其余状态码（含 3xx/4xx）不重试 */
+export function isRetryableStatus(status) {
+  return status === 429 || (status >= 500 && status <= 599)
+}
+
+/** 判断 signal 是否因「超时」而 abort（AbortSignal.timeout 的 reason 是 TimeoutError） */
+function isTimeoutAbort(signal) {
+  const reason = signal?.reason
+  if (!reason) return false
+  return reason.name === 'TimeoutError' || reason.code === 23 || /timeout/i.test(String(reason.message ?? ''))
+}
+
+/** 判断错误是否为可重试的瞬时网络错误（超时单独由 signal 判定，这里也兼容直接抛出的 TimeoutError） */
+export function isTransientNetworkError(err) {
+  if (!err) return false
+  const name = String(err.name ?? '')
+  if (name === 'TimeoutError') return true
+  if (name === 'AbortError') return false // 外部取消由调用方判定，这里不盲目重试
+  const msg = [
+    err.message,
+    err.cause?.message,
+    err.cause?.code,
+    err.code,
+  ].filter(Boolean).join(' ')
+  return NETWORK_ERROR_RE.test(msg)
+}
+
+/** 组合外部取消信号与本次尝试的超时信号（Node 18.17+ 用 AbortSignal.any，更早版本手动转发） */
+function combineSignals(external, timeoutSignal) {
+  if (!external) return timeoutSignal
+  if (!timeoutSignal) return external
+  if (typeof AbortSignal.any === 'function') {
+    try { return AbortSignal.any([external, timeoutSignal]) } catch { /* 参数异常时走下面的回退 */ }
+  }
+  const ctrl = new AbortController()
+  const forward = (src) => () => {
+    cleanup()
+    ctrl.abort(src.reason ?? new DOMException('This operation was aborted', 'AbortError'))
+  }
+  const onExternal = forward(external)
+  const onTimeout = forward(timeoutSignal)
+  function cleanup() {
+    external.removeEventListener('abort', onExternal)
+    timeoutSignal.removeEventListener('abort', onTimeout)
+  }
+  if (external.aborted) { onExternal(); return ctrl.signal }
+  if (timeoutSignal.aborted) { onTimeout(); return ctrl.signal }
+  external.addEventListener('abort', onExternal, { once: true })
+  timeoutSignal.addEventListener('abort', onTimeout, { once: true })
+  return ctrl.signal
+}
+
+/** 可被外部 signal 打断的 sleep（重试等待期间用户取消要立刻退出） */
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const abortReason = () => signal?.reason instanceof Error
+      ? signal.reason
+      : Object.assign(new Error('The operation was aborted'), { name: 'AbortError' })
+    if (signal?.aborted) { reject(abortReason()); return }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    function onAbort() {
+      clearTimeout(timer)
+      reject(abortReason())
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** 解析 Retry-After（秒数或 HTTP 日期），拿不到返回 null */
+function retryAfterMs(res) {
+  try {
+    const raw = res?.headers?.get?.('retry-after')
+    if (!raw) return null
+    const secs = Number(raw)
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1000)
+    const at = Date.parse(raw)
+    if (Number.isFinite(at)) return Math.max(0, at - Date.now())
+  } catch { /* 头不可读就当没有 */ }
+  return null
+}
+
+/** 指数退避：base * 2^attempt + 随机 jitter；有 Retry-After 时取更大值但封顶 MAX_BACKOFF_MS */
+function backoffDelay(attempt, baseDelayMs, hintMs) {
+  const exp = baseDelayMs * 2 ** attempt
+  const jitter = Math.random() * baseDelayMs
+  let delay = Math.round(exp + jitter)
+  if (hintMs != null) delay = Math.max(delay, Math.round(hintMs))
+  return Math.min(delay, MAX_BACKOFF_MS)
+}
+
+function shortUrl(url) {
+  try {
+    const u = new URL(url)
+    return `${u.host}${u.pathname}`.slice(0, 72)
+  } catch {
+    return String(url).slice(0, 72)
+  }
+}
+
+function defaultOnRetry(info) {
+  console.warn(`[重试] ${info.label} ${info.reason}，${info.delay}ms 后重试（${info.attempt + 1}/${info.maxRetries}）`)
+}
+
+/**
+ * 带重试与指数退避的 fetch。
+ *
+ * @param {string | URL} url 请求地址
+ * @param {RequestInit} [options] 原生 fetch 选项；options.signal 会被视为「外部取消信号」（跨重试复用）
+ * @param {object} [retryOptions]
+ * @param {number} [retryOptions.retries=2] 额外重试次数（总尝试 = retries + 1）
+ * @param {number} [retryOptions.baseDelayMs=500] 指数退避基数（第 n 次重试等待 base*2^n + jitter）
+ * @param {number} [retryOptions.timeoutMs=0] 单次尝试超时（毫秒）；>0 时每次尝试新建 AbortSignal.timeout
+ * @param {boolean} [retryOptions.quiet=false] 为 true 时不打印重试日志
+ * @param {Function | null} [retryOptions.onRetry] 自定义重试回调（传 null 关闭日志）
+ * @returns {Promise<Response>} 原生 Response；最后一次尝试即使是 5xx/429 也原样返回，交给调用方处理
+ */
+export async function fetchWithRetry(url, options = {}, {
+  retries = DEFAULT_RETRIES,
+  baseDelayMs = DEFAULT_BASE_DELAY_MS,
+  timeoutMs = 0,
+  quiet = false,
+  onRetry,
+} = {}) {
+  const maxRetries = Math.max(0, Math.floor(Number(retries) || 0))
+  const base = Math.max(0, Number(baseDelayMs) || 0)
+  const notify = onRetry !== undefined ? onRetry : (quiet ? null : defaultOnRetry)
+  const label = shortUrl(url)
+
+  // 调用方可能传 AbortSignal.timeout()（一次性）或 AbortController.signal（可持续取消）
+  let externalSignal = options.signal ?? null
+  let attemptTimeoutMs = Math.max(0, Number(timeoutMs) || 0)
+
+  if (externalSignal?.aborted) {
+    // 已经取消的请求没必要再发；若它同时是超时信号，也不该浪费一次尝试
+    throw externalSignal.reason instanceof Error
+      ? externalSignal.reason
+      : Object.assign(new Error('The operation was aborted'), { name: 'AbortError' })
+  }
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const startedAt = Date.now()
+    const timeoutSignal = attemptTimeoutMs > 0 ? AbortSignal.timeout(attemptTimeoutMs) : null
+    const signal = combineSignals(externalSignal, timeoutSignal)
+
+    try {
+      const res = await fetch(url, signal ? { ...options, signal } : options)
+
+      if (!isRetryableStatus(res.status) || attempt >= maxRetries) return res
+
+      // 丢弃 5xx/429 的响应体，避免连接/流泄漏后再发下一次
+      try { await res.body?.cancel?.() } catch { /* 忽略 */ }
+      const hint = res.status === 429 || res.status === 503 ? retryAfterMs(res) : null
+      const delay = backoffDelay(attempt, base, hint)
+      notify?.({ url, label, attempt, maxRetries, status: res.status, reason: `HTTP ${res.status}`, delay })
+      await sleep(delay, externalSignal)
+      continue
+    } catch (err) {
+      const cancelledExternally = externalSignal?.aborted === true
+      const timedOutByCaller = cancelledExternally && isTimeoutAbort(externalSignal)
+
+      // 用户/上层主动取消：立即结束，不重试
+      if (cancelledExternally && !timedOutByCaller) throw err
+
+      // 调用方传的是 AbortSignal.timeout()：它已经触发且不可复用，记录实际耗时作为后续尝试的超时
+      if (timedOutByCaller) {
+        if (!attemptTimeoutMs) attemptTimeoutMs = Math.max(1, Date.now() - startedAt)
+        externalSignal = null
+      }
+
+      const timedOut = timedOutByCaller || timeoutSignal?.aborted === true
+      const transient = timedOut || isTransientNetworkError(err)
+      if (attempt >= maxRetries || !transient) throw err
+
+      const delay = backoffDelay(attempt, base)
+      notify?.({ url, label, attempt, maxRetries, status: null, reason: timedOut ? '请求超时' : `网络错误：${String(err.message).slice(0, 60)}`, delay })
+      await sleep(delay, externalSignal)
+    }
+  }
+
+  // 逻辑上不可达（循环内要么 return 要么 throw）
+  throw new Error(`fetchWithRetry: ${label} 重试耗尽`)
+}
+
+export { DEFAULT_RETRIES, DEFAULT_BASE_DELAY_MS, MAX_BACKOFF_MS }