@pls-compile-owo/fisheye 0.3.0 → 0.4.2

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
@@ -48,8 +50,8 @@ export const clean = (v) => String(v).replace(/[!'()*]/g, '')
 
 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,8 +61,8 @@ 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')
@@ -68,10 +70,9 @@ export async function getOfficialSubs(bvid, cid, range = null) {
     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, {
+    const r = await fetchWithRetry(url, {
       headers: { 'user-agent': UA, referer: `https://www.bilibili.com/video/${bvid}/` },
-      signal: AbortSignal.timeout(20000),
-    })
+    }, { timeoutMs: 20000 })
     if (!r.ok) return null
     let body = (JSON.parse(await r.text()).body ?? [])
     if (!body.length) return null
@@ -79,7 +80,8 @@ export async function getOfficialSubs(bvid, cid, range = null) {
     if (range) body = body.filter((l) => Number(l.from) >= range.from && Number(l.from) <= range.to)
     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')
@@ -122,6 +124,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 +135,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 +163,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/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 }