@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-scan/scripts/scrapers/fanqie-rank-scraper.js

@@ -0,0 +1,923 @@
+#!/usr/bin/env node
+/**
+ * 番茄小说排行榜采集脚本
+ *
+ * 流程：
+ * 1. 使用 playwright-core 打开榜单首页
+ * 2. 从页面 DOM 动态提取子题材分类链接
+ * 3. 把"全部"（首页本身）也加入品类列表
+ * 4. 对每个分类：新建独立 browser context（避免 OOM/状态污染）
+ *    → 等待前 TOP 名渲染完毕
+ *    → DOM 提取 rank/readerCount/url（明文）
+ *    → 截图 title/author/status/desc 区域
+ *    → tesseract.js OCR 识别截图
+ * 5. 失败时写结构化诊断到 stderr（即便进程被 OOM 杀，前面阶段的进度也能保留）
+ * 6. 完成后输出 JSON receipt 到 stdout（被 run-scan.js 解析）
+ *
+ * 关键决策：
+ * - 每 category 用全新 browser context：避免共享 chromium 时的内存累积
+ * - 截图用 jpeg quality 95 + deviceScaleFactor 2 提高 OCR 准确率
+ * - OCR 后清理 Tesseract 在中文间插入的空格
+ */
+
+import fs from 'fs';
+import { atomicWriteFile } from '#atomic-write';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { chromium } from 'playwright-core';
+import Tesseract from 'tesseract.js';
+import { getArg, localDateStamp, runCli, normalizeScanMode, SCAN_MODE_API, renderIntroLines, sanitizeBookFields, sanitizeMarkdownInline } from '#scraper-utils';
+
+// 捕获未处理的 promise 错误——只写 stderr，让上层重试逻辑处理，不要直接退出
+process.on('unhandledRejection', (reason) => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(`[unhandledRejection] ${msg}\n`);
+});
+
+// ---------------------------------------------------------------------------
+// CLI 参数
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const OUTDIR = getArg(args, "--outdir") || ".";
+const CHANNEL = getArg(args, "--channel") || "1";
+const TYPE = getArg(args, "--type") || "2";
+const TOP = parseInt(getArg(args, "--top") || "10", 10);
+
+// 扫描方式（取数路径）：
+//   api —— 书名/作者/简介走番茄明文接口 /api/book/info（零 OCR 误差）
+//   ocr —— 渲染后截图 + tesseract 识别（原流程）
+// 非法值/缺失一律按默认（api）处理：绝不能出现"既不截图也不取接口"的空采集。
+const SCAN_MODE = normalizeScanMode(getArg(args, "--scan-mode"));
+
+// 兜底退出：任何情况都尝试释放 OCR worker
+process.on('exit', () => {
+  if (_ocrWorker) {
+    try { _ocrWorker.terminate(); } catch (_) {}
+    _ocrWorker = null;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------------------------
+
+function channelLabel(ch) {
+  return ch === "1" ? "男频" : "女频";
+}
+
+function typeLabel(t) {
+  return t === "2" ? "阅读榜" : "新书榜";
+}
+
+/**
+ * 等待排名前 N 名渲染完毕（最多等 60 秒）
+ */
+async function waitForRankN(page, n) {
+  let lastCount = -1;
+  let stableRounds = 0;
+  for (let attempt = 0; attempt < 30; attempt++) {
+    const count = await page.locator('.rank-book-item').count();
+    if (count >= n) {
+      const h1Text = await page.locator('.rank-book-item').nth(n - 1).locator('.book-item-index h1').textContent().catch(() => '');
+      if (h1Text && h1Text.trim() !== '') return true;
+    } else if (count > 0 && count === lastCount) {
+      // 数量连续两轮不变 → 渲染已经稳定，就是这个品类本来本数少
+      stableRounds++;
+      if (stableRounds >= 2) return true;
+    } else {
+      stableRounds = 0;
+    }
+    lastCount = count;
+    await page.waitForTimeout(2000);
+  }
+  return false;
+}
+
+async function screenshotToFile(locator, filepath) {
+  const buf = await locator.screenshot({ type: 'jpeg', quality: 95 });
+  fs.mkdirSync(path.dirname(filepath), { recursive: true });
+  atomicWriteFile(filepath, buf);
+  return filepath;
+}
+
+/**
+ * 把页面文本规整成安全的单层目录名。
+ *
+ * 题材名与排名都直接取自 DOM 文本，可能含 '/'、'..' 或控制字符；
+ * 直接拼进路径会导致 mkdir 失败，或写到目标目录之外。
+ */
+export function safePathSegment(raw, fallback) {
+  const s = String(raw == null ? '' : raw)
+    .replace(/[\x00-\x1f\x7f]/g, '')   // 控制字符
+    .replace(/[/\\]/g, '_')            // 路径分隔符
+    .replace(/^\.+/, '_')              // 开头的点串（"."、".."、"..."）
+    .trim();
+  return s || fallback;
+}
+
+/**
+ * 单例 OCR worker：tesseract.js v7 用 createWorker 初始化，避免每张图都重建 worker
+ * 进程退出时 dispose
+ *
+ * 语言模型只装 chi_sim，不装 eng+chi_sim。
+ *
+ * tesseract 是**按行/按块**判定语言的，不是逐字混合。番茄的简介开头常是
+ * "【种田+慢热+西幻+多种族+无系统+争霸】" 这种符号密集的标签块，
+ * 混合模型会把**整行**判成英文，于是该行的中文被读成拉丁字母：
+ *   "穿越中世纪，成为一名叫"菲尔德"的贵族" → "FEPHE,AAS FRENRE SAXMR,ABHNERE"
+ * 同一行的后半段若以中文开头又是对的 —— 这正是"按行判定"的症状。
+ *
+ * 实测（20 本，详情页明文作真值，编辑距离相似度）：
+ *   字段    eng+chi_sim   chi_sim
+ *   title      93.0%      94.2%
+ *   author     83.3%      93.6%
+ *   desc       84.0%      92.9%
+ * desc 里 20 本有 18 本被 eng 判成拉丁行，chi_sim 只有 4 本。
+ */
+let _ocrWorker = null;
+let _ocrInitPromise = null;
+
+// OCR 各环节的超时上限。
+// tesseract.js 的 recognize() 没有取消接口，也没有超时参数（实测其源码中
+// 搜不到任何 timeout 机制），worker 又是单线程串行处理任务的 ——
+// 一次 recognize 卡死，会把后续所有 OCR 一起拖死，只能靠外层 25 分钟
+// 的进程超时兜底，代价是整榜数据作废。
+const OCR_INIT_TIMEOUT_MS = 120000;   // worker 初始化（含语言包加载/下载）
+const OCR_TIMEOUT_MS = 30000;        // 单张图识别
+const OCR_TERMINATE_TIMEOUT_MS = 5000; // 换掉卡死 worker 时终止自身的上限
+
+/**
+ * 给 promise 加超时兜底。
+ *
+ * 超时后原始 promise 仍在跑（无法取消），但 race 已经结算，
+ * 调用方不再等待；原始 promise 后续的 reject 由 race 吸收，不会变成
+ * unhandledRejection。
+ */
+function withTimeout(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label}超时（${ms}ms）`)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** 终止并丢弃当前 worker（卡死时用；worker 为空则什么都不做） */
+async function resetOcrWorker() {
+  const w = _ocrWorker;
+  _ocrWorker = null;
+  _ocrInitPromise = null;
+  if (!w) return;
+  try {
+    await Promise.race([
+      w.terminate(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('terminate timeout')), OCR_TERMINATE_TIMEOUT_MS)),
+    ]);
+  } catch (_) {}
+}
+
+async function getOcrWorker() {
+  if (_ocrWorker) return _ocrWorker;
+  if (_ocrInitPromise) return _ocrInitPromise;
+  const init = Tesseract.createWorker('chi_sim');
+  _ocrInitPromise = (async () => {
+    try {
+      const w = await withTimeout(init, OCR_INIT_TIMEOUT_MS, 'OCR worker 初始化');
+      _ocrWorker = w;
+      return w;
+    } catch (e) {
+      // 失败/超时后必须清掉缓存的 promise：否则后续每次调用都拿到同一个
+      // rejected promise，OCR 永远不可用（实测此前 disposeOcrWorker 在
+      // _ocrWorker 为空时也不会清 _ocrInitPromise）。
+      _ocrInitPromise = null;
+      // init 可能日后仍会成功，兜底终止它，避免泄漏一个 worker
+      init.then(w => w.terminate().catch(() => {})).catch(() => {});
+      throw e;
+    }
+  })();
+  return _ocrInitPromise;
+}
+
+async function disposeOcrWorker() {
+  await resetOcrWorker();
+}
+
+/**
+ * OCR 识别截图（清理多余空格，保留中文可读性）
+ */
+/**
+ * 规整 OCR 文本中的多余空白。
+ *
+ * tesseract 识别中文时是"逐字插空格"（"百 岁 修仙"），这些空格必须去掉；
+ * 但拉丁字母/数字构成的多词短语（"Hello World"）的词间空格要保留。
+ *
+ * 此前实现先 replace(/\s+/g,'') 把所有空白删光，导致：
+ *   1) 英文短语被粘连成 "HelloWorld"；
+ *   2) 后面"只删 CJK 之间空格"的分支永远匹配不到东西（死代码），
+ *      且该分支的注释与实际行为不符。
+ *
+ * 规则：只保留"拉丁字母/数字 ↔ 拉丁字母/数字"之间的空白，其余一律删除。
+ * 用占位符保住需要保留的空格，避免与后续的全量删除互相抵消。
+ */
+export function normalizeOcrText(raw) {
+  const MARK = '\u0000';
+  return String(raw == null ? '' : raw)
+    .trim()
+    .replace(/([A-Za-z0-9])[\s]+(?=[A-Za-z0-9])/g, `$1${MARK}`)
+    .replace(/\s+/g, '')
+    .split(MARK).join(' ');
+}
+
+async function ocrFile(imagePath) {
+  const worker = await getOcrWorker();
+  try {
+    const { data: { text } } = await withTimeout(
+      worker.recognize(imagePath),
+      OCR_TIMEOUT_MS,
+      'OCR 识别'
+    );
+    return normalizeOcrText(text);
+  } catch (e) {
+    // recognize 卡死时无法取消，而 worker 单线程串行处理任务 ——
+    // 一个卡死会把后续所有 OCR 一起拖死。只能把 worker 换掉，
+    // 让 ocrWithRetry 的下一次重试拿到全新的 worker。
+    await resetOcrWorker();
+    throw e;
+  }
+}
+
+async function screenshotWithRetry(locator, filepath, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await screenshotToFile(locator, filepath);
+    } catch (e) {
+      if (i === retries - 1) throw e;
+      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
+    }
+  }
+}
+
+async function ocrWithRetry(imagePath, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await ocrFile(imagePath);
+    } catch (e) {
+      if (i === retries - 1) throw e;
+      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API 模式：番茄明文接口
+// ---------------------------------------------------------------------------
+
+/**
+ * 番茄的榜单页把书名/作者/简介用 awesome-font 做了 PUA 字体混淆
+ * （DOM 文本是 U+E000–U+F8FF 私用区码位），所以"渲染后识别"只是取回真文本
+ * 的一种手段，精度天然受限于 OCR。
+ *
+ * 番茄自家在用的 /api/book/info 返回的是同名同内容的**明文**字段
+ * （bookName / author / abstract），无需浏览器、无需 cookie、无需 a_bogus 签名。
+ *
+ * 三条独立证据链确认它与榜单页是同一份文本：
+ *   1) 榜页 DOM(PUA) --码表--> 明文 vs 接口明文：title 10/10 一致、
+ *      author 10/10 一致、desc 长度 10/10 严格相等；
+ *   2) 生产 OCR 产物 200 本 vs 接口明文：desc 字符相似度 92.26%，
+ *      差异全部是 OCR 认字错误（登项→登顶、社瘟→社畜），长度逐本对齐；
+ *   3) DOM「在读：70.3万」vs 接口 readCount：200/200 误差 <2%。
+ */
+const BOOK_INFO_URL = 'https://fanqienovel.com/api/book/info?bookId=';
+
+/**
+ * 明文接口的 UA。
+ *
+ * 实测桌面 Chrome UA 直连即可（HTTP 200），不需要 cookie。
+ * 同窗口 A/B 对照与高并发交错对照都证明带不带 cookie 对成功率没有影响
+ * （两组各 200/200 全绿）—— 此前观察到的 444 是突发请求后的限流时间窗，
+ * 与 cookie 无关。
+ * 这里仍然不带 cookie：浏览器会话 cookie 对本进程本就无意义，
+ * 真被限流时少一个变量也好排查。
+ */
+const API_UA = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+const API_TIMEOUT_MS = 20000;   // 实测 p95 延迟 463ms，留足余量
+const API_CONCURRENCY = 8;      // 实测 8 并发 24 QPS 零失败；40 并发 70 QPS 也零失败，
+                                // 但曾观测到突发后的一次 444 限流窗口，保守取 8
+const API_RETRY = 3;            // 失败重试次数（总尝试 = API_RETRY + 1）
+const API_RETRY_DELAY_MS = 1500;
+
+/**
+ * 取一本书的明文信息。
+ *
+ * 失败判定不能只看 HTTP 状态码：查无此书时接口仍返回 HTTP 200，
+ * 响应体是 {"data":{},"code":-1,"message":"查无此书"} ——
+ * 只看状态码会把"这本书取不到"误判成"取到了空简介"。
+ */
+async function fetchBookInfo(bookId) {
+  const res = await fetch(BOOK_INFO_URL + encodeURIComponent(bookId), {
+    headers: { 'User-Agent': API_UA, 'Accept': 'application/json, text/plain, */*' },
+    signal: AbortSignal.timeout(API_TIMEOUT_MS),
+  });
+  if (res.status !== 200) throw new Error(`HTTP ${res.status}`);
+  const body = await res.text();
+  let json;
+  try { json = JSON.parse(body); } catch (_) { throw new Error('响应非 JSON'); }
+  if (!json || json.code !== 0) {
+    throw new Error(json && json.message ? String(json.message) : `接口返回 code=${json && json.code}`);
+  }
+  const data = json.data;
+  // 缺**书名**才是整本失败；缺简介不算（2026-10-29 审计）。
+  //
+  // 之前是 `!data.abstract` → throw。API 模式下书名/作者/精确在读/字数/
+  // 官方标签**全都来自这个接口**（DOM 里的书名是 PUA 混淆字形），
+  // 所以"只因没有 abstract"就把整本书判失败，丢的远不止简介。
+  // 真的没简介的书，书名作者还在，照样能收（简介留空）。
+  if (!data || !data.bookName) throw new Error('接口未返回书名');
+  return data;
+}
+
+/**
+ * 把 fetch 的 `TypeError: fetch failed` 展开成可排查的原因。
+ *
+ * Node/undici 把真正的网络错误藏在 `err.cause` 里（code / hostname /
+ * address / AggregateError），只记 message 时日志里永远只有 "fetch failed"，
+ * 无法判断是 DNS、连接重置、超时还是限流。
+ */
+function describeBookInfoError(err) {
+  if (!err) return '未知错误';
+  const cause = err.cause || {};
+  const first = (cause.errors && cause.errors[0]) || cause;
+  const code = first.code || cause.code || '';
+  const host = first.hostname || cause.hostname || first.address || cause.address || '';
+  const detail = [err.message || String(err)];
+  if (code) detail.push(code);
+  if (host) detail.push(host);
+  return detail.join(' / ');
+}
+
+/** 这些错误重试没有意义（书不存在/接口契约错误），直接缓存失败。 */
+function isNonRetryableBookInfoError(err) {
+  const message = String((err && err.message) || '');
+  return /查无此书|接口未返回书名|响应非 JSON|code=-?\d+/.test(message);
+}
+
+/**
+ * bookId → { ok, data } 的缓存。
+ *
+ * 同一个 bookId 会出现在多个题材榜单里（实测 200 条记录只有 190 个唯一 id），
+ * 缓存后同一本书只请求一次。
+ */
+const _bookInfoCache = new Map();
+
+/**
+ * 带重试的单本取数。缓存的是**结果**而不是 promise 之外的中间态，
+ * 失败也缓存 —— 同一本书在别的题材再次出现时不必再撞一次接口。
+ */
+async function loadBookInfo(bookId) {
+  if (_bookInfoCache.has(bookId)) return _bookInfoCache.get(bookId);
+  let lastError = null;
+  for (let attempt = 0; attempt <= API_RETRY; attempt++) {
+    try {
+      const data = await fetchBookInfo(bookId);
+      const result = { ok: true, data };
+      _bookInfoCache.set(bookId, result);
+      return result;
+    } catch (e) {
+      lastError = e;
+      if (isNonRetryableBookInfoError(e)) break;
+      if (attempt < API_RETRY) {
+        await new Promise(r => setTimeout(r, API_RETRY_DELAY_MS * (attempt + 1)));
+      }
+    }
+  }
+  const reason = describeBookInfoError(lastError);
+  process.stderr.write(`[api-fail] 番茄/${bookId}: ${reason}\n`);
+  const result = { ok: false, error: reason };
+  _bookInfoCache.set(bookId, result);
+  return result;
+}
+
+/**
+ * 限并发批量取明文。
+ *
+ * 并发上限是硬约束：番茄接口在高并发突发后会进入限流窗口（实测出现过
+ * 一次 HTTP 444 / Access Denied），所以这里固定 8 并发，不做自适应放大。
+ */
+async function loadAllBookInfo(bookIds) {
+  const out = new Map();
+  if (!bookIds.length) return out;
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(API_CONCURRENCY, bookIds.length) }, async () => {
+    while (true) {
+      const i = cursor++;
+      if (i >= bookIds.length) break;
+      const id = bookIds[i];
+      out.set(id, await loadBookInfo(id));
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+/**
+ * 从页面提取品类列表（DOM 中所有匹配 prefix 的 anchor）
+ */
+async function extractCategories(page, channel, type) {
+  const prefix = `/rank/${channel}_${type}_`;
+  return await page.evaluate((pref) => {
+    const out = [], seen = new Set();
+    for (const a of document.querySelectorAll('a')) {
+      const href = a.getAttribute('href') || '';
+      if (!href.includes(pref)) continue;
+      const name = (a.innerText || a.textContent || '').trim();
+      if (!name || seen.has(href)) continue;
+      seen.add(href);
+      out.push({ name, href });
+    }
+    return out;
+  }, prefix);
+}
+
+/**
+ * 把榜单卡片里的文本调整成适合 OCR 的样子。
+ *
+ * 番茄的 title/author/desc 用 awesome-font 做了 PUA 字体混淆（DOM 里的
+ * 文本是 U+E000–U+F8FF 私用区码位），只能靠"渲染后识别"（截图 + OCR）
+ * 拿回真文本。页面的默认样式对 OCR 有两处不利：
+ *
+ *   1) desc 被 `-webkit-line-clamp:2` 截成两行（榜单页规则
+ *      `.muye-rank-book-list .book-item-text .abstract`：
+ *      line-height:23px + overflow:hidden + -webkit-box，
+ *      实测 clientHeight=46px / scrollHeight=92~184px）。
+ *      DOM 里的文本其实是完整的（实测榜单页 desc 与详情页 abstract 等长），
+ *      截断只是视觉的 —— 白丢三分之二内容，而且最后一行是半截字形，
+ *      识别出来是垃圾（实测尾部出现 "…满是贫穷和怪.，1"）。
+ *   2) desc 颜色是 rgba(0,0,0,.4)、author 同样是 rgba(0,0,0,.4) ——
+ *      浅灰低对比度，tesseract 的识别率明显下降（改纯黑后命中率 +0.2pp）。
+ *      （title 本来就是 rgb(0,0,0)，一起设成 #000 只是兜底，无副作用。）
+ *
+ * 这里解除行数限制并把颜色改成纯黑。元素是逐个渲染出来的，
+ * 所以要在榜单渲染完成之后（waitForRankN 之后）再统一处理。
+ */
+async function prepareOcrFriendlyStyles(page) {
+  await page.evaluate(() => {
+    for (const el of document.querySelectorAll('.book-item-text .desc')) {
+      el.style.setProperty('-webkit-line-clamp', 'unset', 'important');
+      el.style.setProperty('height', 'auto', 'important');
+      el.style.setProperty('max-height', 'none', 'important');
+      el.style.setProperty('overflow', 'visible', 'important');
+      el.style.setProperty('display', 'block', 'important');
+    }
+    for (const el of document.querySelectorAll(
+      '.book-item-text .desc, .book-item-text .author, .book-item-text .title'
+    )) {
+      el.style.setProperty('color', '#000', 'important');
+    }
+  });
+}
+
+/**
+ * 采集一个品类（10 本书的 rank/title/author/status/desc/readerCount）
+ *
+ * 两种取数路径：
+ *   api —— 排名/状态/在读/bookId 走 DOM 直读（本来就是明文），
+ *          书名/作者/简介走番茄明文接口；不截图、不 OCR。
+ *   ocr —— 原流程：四个字段全部截图 + tesseract 识别。
+ *
+ * 返回 { books, failures }：failures 是取不到明文的书，向上汇总到
+ * partialReasons，让用户看得见"哪本没取到"，而不是只看到空简介。
+ */
+/**
+ * 读榜页给出的**名次变动**。
+ *
+ * DOM：`<p><span class="up">1</span></p>` / `<span class="down">2</span>` / `<p>-</p>`。
+ * 方向只在 span 的 class 上，textContent 分不出升降（实测 up/down 都出现过，
+ * 只取数字会把"下降 1 名"判成"上升 1 名"）。
+ *
+ * 返回：
+ *   '上升 N' / '下降 N' / '持平'  —— 有值
+ *   null                         —— 这个元素压根不存在（不是"没变化"）
+ */
+export async function readRankChange(item) {
+  const p = item.locator('.book-item-index p').first();
+  if ((await p.count().catch(() => 0)) === 0) return null;
+  const text = (await p.innerText().catch(() => '')).trim();
+  if (!text || text === '-') return '持平';
+  const cls = (await p.locator('span').first().getAttribute('class').catch(() => '')) || '';
+  if (/up/i.test(cls)) return `上升 ${text}`;
+  if (/down/i.test(cls)) return `下降 ${text}`;
+  return text;
+}
+
+/**
+ * 解析接口里的 `categoryV2` —— 平台**官方标签**。
+ *
+ * 形如 `[{"Name":"西方奇幻","MainCategory":true,...},{"Name":"系统",...}]`，
+ * 每个标签还带官方描述（ExternalDesc）和维度号（Dim）。
+ *
+ * 实测 25/25 本都有，平均 5.8 个/本，范围 3~11 个。第一个是主分类
+ * （MainCategory=true，与采集端的题材组一致），其余是次级标签 ——
+ * 次级标签里**题材细分和元素套路混在一起**（如"都市/东方玄幻"与
+ * "无限流/单女主/无脑爽"），不能按 Dim 硬分。
+ *
+ * 主分类排到最前（不依赖数组顺序），其余保持原序。
+ */
+export function parseTags(categoryV2) {
+  if (!categoryV2) return [];
+  let arr;
+  try {
+    arr = JSON.parse(categoryV2);
+  } catch (_) {
+    return [];
+  }
+  if (!Array.isArray(arr)) return [];
+  const nameOf = (t) => (t && t.Name ? String(t.Name).trim() : '');
+  const main = arr.filter((t) => t && t.MainCategory);
+  const rest = arr.filter((t) => t && !t.MainCategory);
+  return [...main, ...rest].map(nameOf).filter(Boolean);
+}
+
+async function scrapeCategory(page, catHref, catName, ch, type, screenshotBase) {
+  await page.goto('https://fanqienovel.com' + catHref, { waitUntil: 'commit', timeout: 60000 });
+  await page.waitForTimeout(3000);
+
+  const ready = await waitForRankN(page, TOP);
+  if (!ready) throw new Error('等待渲染超时');
+
+  // 解除 desc 的两行截断、把文字改成纯黑，再截图 OCR
+  // （只有 OCR 路径需要：API 路径不截图，改样式没有意义）
+  if (SCAN_MODE !== SCAN_MODE_API) {
+    await prepareOcrFriendlyStyles(page);
+  }
+
+  // 一次性拿所有书籍 DOM 引用，避免后续循环索引错位
+  const items = await page.locator('.rank-book-item').all();
+  const actualTop = Math.min(items.length, TOP);
+  const books = [];
+
+  for (let i = 0; i < actualTop; i++) {
+    const item = items[i];
+
+    const rankRaw = await item.locator('.book-item-index h1').first().textContent().catch(() => '');
+    const rank = (rankRaw || '').trim() || String(i + 1);
+
+    const readerText = await item.locator('.book-item-count').first().textContent().catch(() => '');
+    const readerCount = (readerText || '').replace('在读：', '').trim();
+
+    // 排名变动：`<p><span class="up">1</span></p>` / `down` / `-`（无变化）。
+    // 方向在 span 的 class 里，光取 textContent 分不出上升还是下降 ——
+    // 实测 19 个分类 380 本里 up/down 都有，只看数字会全判错。
+    const rankChange = await readRankChange(item);
+
+    const url = await item.locator('.book-item-text .title a').first().getAttribute('href').catch(() => '') || '';
+    const bookIdMatch = url.match(/\/page\/(\d+)/);
+    const bookId = (bookIdMatch && bookIdMatch[1]) || `unknown_${i}`;
+
+    if (SCAN_MODE === SCAN_MODE_API) {
+      // 状态在 DOM 里本来就是明文（实测 PUA=0，"连载中"/"已完结"），
+      // 原流程却把它也送去 OCR —— 这里直接读，省掉每本一次识别。
+      const statusRaw = await item.locator('.book-item-footer .book-item-footer-status')
+        .first().textContent().catch(() => '');
+      books.push({
+        rank, bookId, url,
+        title: '', author: '',
+        status: (statusRaw || '').trim() || '未知',
+        desc: '',
+        readerCount: readerCount || '未知',
+        rankChange,
+      });
+      continue;
+    }
+
+    const bd = path.join(screenshotBase, safePathSegment(rank, String(i + 1)));
+    fs.mkdirSync(bd, { recursive: true });
+
+    const ocr = {};
+    for (const [field, sel] of [
+      ['title',  '.book-item-text .title'],
+      ['author', '.book-item-text .author'],
+      ['status', '.book-item-footer .book-item-footer-status'],
+      ['desc',   '.book-item-text .desc'],
+    ]) {
+      const fp = path.join(bd, `${bookId}_${field}.jpg`);
+      try {
+        await screenshotWithRetry(item.locator(sel), fp, 3);
+        ocr[field] = await ocrWithRetry(fp, 3);
+      } catch (e) {
+        // 单字段 OCR 失败不影响其他字段——降级为空字符串
+        process.stderr.write(`[ocr-fail] ${catName}/${bookId}/${field}: ${e.message}\n`);
+        ocr[field] = '';
+      }
+    }
+
+    books.push({
+      rank, bookId, url,
+      title: ocr.title || `（bookId: ${bookId}）`,
+      author: ocr.author || '未知',
+      status: ocr.status || '未知',
+      desc: ocr.desc || '',
+      readerCount: readerCount || '未知',
+      rankChange,
+    });
+  }
+
+  // API 路径：批量补书名/作者/简介
+  const failures = [];
+  if (SCAN_MODE === SCAN_MODE_API) {
+    const ids = [...new Set(books.map(b => b.bookId).filter(id => /^\d+$/.test(id)))];
+    const infoMap = await loadAllBookInfo(ids);
+    for (const b of books) {
+      const r = infoMap.get(b.bookId);
+      if (r && r.ok) {
+        b.title = r.data.bookName || b.title;
+        b.author = r.data.author || b.author;
+        b.desc = r.data.abstract || '';
+        // 精确在读：榜页只给"59.8万"这种舍入值，接口给的是准确人数
+        // （实测同书 597999 ↔ 榜页 59.8万）。份额/中位数用它更准。
+        if (r.data.readCount) b.readCount = String(r.data.readCount);
+        // 字数：番茄此前完全没有字数（其它三个平台都有）
+        if (r.data.wordNumber) b.wordCount = String(r.data.wordNumber);
+        // 平台官方标签
+        b.tags = parseTags(r.data.categoryV2);
+        continue;
+      }
+      // 两种失败要分开说：一种是没从 DOM 拿到 bookId（压根没法查接口），
+      // 另一种是接口本身没返回。都归成"取不到"会让排查无从下手。
+      const reason = /^\d+$/.test(b.bookId)
+        ? ((r && r.error) || '未知原因')
+        : '未取到 bookId';
+      process.stderr.write(`[api-fail] ${catName}/${b.bookId}: ${reason}\n`);
+      b.title = b.title || `（bookId: ${b.bookId}）`;
+      b.author = b.author || '未知';
+      failures.push(`${catName}/${b.bookId} 明文获取失败: ${reason}`);
+    }
+  }
+
+  return { books, failures };
+}
+
+function buildMarkdown(catName, books) {
+  const lines = [];
+  lines.push(`## ${sanitizeMarkdownInline(catName)} — ${books.length} 本`, '');
+  for (const raw of books) {
+    const b = sanitizeBookFields(raw);
+    lines.push(`### #${b.rank} ${b.title}`);
+    lines.push(`- **作者：** ${b.author}`);
+    if (b.status) lines.push(`- **状态：** ${b.status}`);
+    // 精确在读优先（接口给的准确人数），没有才用榜页的舍入值
+    const readers = b.readCount || b.readerCount;
+    if (readers) lines.push(`- **在读：** ${readers}`);
+    if (b.wordCount) lines.push(`- **字数：** ${b.wordCount}`);
+    if (b.tags && b.tags.length) lines.push(`- **标签：** ${b.tags.join('、')}`);
+    if (b.rankChange) lines.push(`- **排名变动：** ${b.rankChange}`);
+    // 简介和其他字段一样是 `- ` 列表项；单换行用硬换行，空行才是段落分隔。
+    // 之前是「空行 + `**简介**` + 简介整块」—— 没有冒号，且和上下文粘成一段，
+    // 而且简介首尾的空白字符原样留在文件里。
+    lines.push(...renderIntroLines(b.desc || ''));
+    if (b.url) lines.push(`- [作品页](https://fanqienovel.com${b.url})`);
+    lines.push('');
+  }
+  lines.push('---', '');
+  return lines.join('\n');
+}
+
+/**
+ * 确保 browser 有效；旧实例已死则关闭并启动新的（避免孤儿进程）
+ */
+async function ensureBrowser(browserRef) {
+  if (browserRef.current) {
+    // isConnected() 返回 boolean，不是 Promise
+    let alive = false;
+    try { alive = browserRef.current.isConnected(); } catch (_) { alive = false; }
+    if (alive) return browserRef.current;
+    try { await browserRef.current.close(); } catch (_) {}
+    browserRef.current = null;
+  }
+  browserRef.current = await chromium.launch({ headless: true, timeout: 60000 });
+  return browserRef.current;
+}
+
+/**
+ * 采集一个 channel+type，browserRef 是 { current: Browser } 包装对象
+ */
+async function scrapeChannel(browserRef, ch, type) {
+  const chLabel = channelLabel(ch), tyLabel = typeLabel(type);
+  const listUrl = `https://fanqienovel.com/rank/${ch}_${type}/`;
+
+  // 1. 获取品类列表
+  let categories = [];
+  const listPage = await browserRef.current.newPage();
+  try {
+    await listPage.goto(listUrl, { waitUntil: 'commit', timeout: 60000 });
+    // 轮询直到拿到品类列表（动态渲染，最多等 20 秒）
+    for (let attempt = 0; attempt < 20; attempt++) {
+      categories = await extractCategories(listPage, ch, type);
+      if (categories.length > 0) break;
+      await listPage.waitForTimeout(1000);
+    }
+  } catch (e) {
+    process.stderr.write(`[stage] extract-categories failed: ${e.message}\n`);
+  } finally {
+    await listPage.close();
+  }
+
+  // 2. fallback：拿不到任何分类时使用全部 init catId
+  if (!categories.length) {
+    const initCatId = ch === "1" ? "1141" : "1139";
+    categories.push({ name: "全部", href: `/rank/${ch}_${type}_${initCatId}` });
+  } else {
+    // 把首页（全部）放到第一个，确保也被采集
+    categories.unshift({ name: '全部', href: `/rank/${ch}_${type}/` });
+  }
+
+  // 3. 准备 markdown 容器
+  const now = new Date().toISOString();
+  const allLines = [
+    `# 番茄 · ${chLabel}${tyLabel} · 全 ${categories.length} 题材`,
+    '',
+    `- 频道参数：channel=${ch}，type=${type}`,
+    `- 抓取时间：${now}`,
+    `- 每题材前${TOP}本`,
+    '',
+    '---',
+    ''
+  ];
+
+  const screenshotBasePrefix = path.join(OUTDIR, 'screenshots', `${chLabel}${tyLabel}_${Date.now()}`);
+  const writtenFiles = [];
+  const partialReasons = [];
+  let failedCategories = 0;
+  // 单本取数失败与"品类采集失败"是两种不同粒度的失败，单位不能混：
+  // 前者计本数，后者计题材数。两者都要进 partialReasons 让用户看见。
+  let failedBooks = 0;
+  // 成功采集到的品类数（2026-10-29 审计）。
+  // 之前只看"写了几个文件" —— 而**所有品类都失败时文件照样写出来**
+  // （里面全是 `## <品类> — 采集失败` 段落），上层 `ok: scanFiles.length > 0`
+  // 于是判成功，项目被推进到 phase=scanned，用户拿到一份空报告。
+  let okCategories = 0;
+
+  // 4. 逐个分类采集（每个 category 用独立 browser context）
+  for (let ci = 0; ci < categories.length; ci++) {
+    const cat = categories[ci];
+    const screenshotBase = path.join(screenshotBasePrefix, safePathSegment(cat.name, '未分类'));
+
+    let ok = false;
+    for (let retry = 0; retry < 2 && !ok; retry++) {
+      let ctx = null;
+      try {
+        const browser = await ensureBrowser(browserRef);
+        ctx = await browser.newContext({
+          viewport: { width: 1280, height: 800, deviceScaleFactor: 2 },
+        });
+        const page = await ctx.newPage();
+
+        const { books, failures } = await scrapeCategory(page, cat.href, cat.name, ch, type, screenshotBase);
+        allLines.push(buildMarkdown(cat.name, books));
+        // 单本明文取不到不算"品类失败"，但必须让用户看见：
+        // 否则产物里就是一条只有排名的空简介，看不出是接口挂了还是本来就没简介。
+        if (failures.length) {
+          partialReasons.push(...failures);
+          failedBooks += failures.length;
+        }
+        ok = true;
+        okCategories++;
+      } catch (e) {
+        const diag = { stage: 'category', cat: cat.name, href: cat.href, msg: e.message };
+        process.stderr.write(`[diag] ${JSON.stringify(diag)}\n`);
+        // browser 可能已死，主动 invalidate，下次 ensureBrowser 会重建
+        if (browserRef.current) {
+          const stillAlive = (() => { try { return browserRef.current.isConnected(); } catch (_) { return false; } })();
+          if (!stillAlive) {
+            process.stderr.write(`[diag] browser dead, invalidating\n`);
+            browserRef.current = null;
+          }
+        }
+        if (retry === 0) {
+          await new Promise(r => setTimeout(r, 2000));
+        } else {
+          failedCategories++;
+          partialReasons.push(`${cat.name}: ${e.message}`);
+          allLines.push(`## ${cat.name} — 采集失败`, '', '---', '');
+        }
+      } finally {
+        if (ctx) {
+          try { await ctx.close(); } catch (_) {}
+        }
+      }
+    }
+
+    await new Promise(r => setTimeout(r, 500));
+  }
+
+  // 5. 写 markdown 文件
+  const date = localDateStamp();
+  const filename = `番茄${channelLabel(ch)}${typeLabel(type)}_${date}.md`;
+  fs.mkdirSync(OUTDIR, { recursive: true });
+  const filepath = path.join(OUTDIR, filename);
+  atomicWriteFile(filepath, allLines.join('\n'));
+  writtenFiles.push(filepath);
+
+  return {
+    writtenFiles,
+    failed: failedCategories + failedBooks,
+    okCategories,
+    partialReasons,
+  };
+}
+
+async function main() {
+  if (!["0", "1", "all"].includes(CHANNEL)) throw new Error(`未知 --channel: ${CHANNEL}`);
+  if (!["1", "2", "all"].includes(TYPE)) throw new Error(`未知 --type: ${TYPE}`);
+  const channels = CHANNEL === "all" ? ["1", "0"] : [CHANNEL];
+  const types = TYPE === "all" ? ["2", "1"] : [TYPE];
+
+  const browserRef = { current: null };
+  // 被 SIGTERM 杀时（上游超时或中断）主动关掉浏览器，
+  // 否则 chromium 会留在系统里继续占 CPU/内存。
+  // close 必须带超时兜底：浏览器正在导航时 close() 可能挂住，
+  // 无超时的话进程会卡住不退出（实测过）。
+  process.on('SIGTERM', async () => {
+    try {
+      if (browserRef.current) {
+        await Promise.race([
+          browserRef.current.close(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('close timeout')), 5000)),
+        ]);
+      }
+    } catch (_) {}
+    process.exit(143);
+  });
+  const planned = channels.length * types.length;
+  const writtenFiles = [];
+  const partialReasons = [];
+  let failedCount = 0;
+  let okCategories = 0;
+
+  // 首次启动 browser（失败时尝试一次 fallback 重试）
+  try {
+    await ensureBrowser(browserRef);
+  } catch (launchErr) {
+    process.stderr.write(`[fatal] browser launch failed: ${launchErr.message}\n`);
+    // 重新抛出让 runCli 捕获
+    throw new Error(`浏览器启动失败：${launchErr.message}`);
+  }
+
+  try {
+    for (const ch of channels) {
+      for (const ty of types) {
+        try {
+          const r = await scrapeChannel(browserRef, ch, ty);
+          writtenFiles.push(...r.writtenFiles);
+          failedCount += r.failed;
+          okCategories += r.okCategories || 0;
+          partialReasons.push(...r.partialReasons);
+        } catch (chErr) {
+          failedCount++;
+          partialReasons.push(`${channelLabel(ch)}${typeLabel(ty)}: ${chErr.message}`);
+        }
+      }
+    }
+  } finally {
+    // 关闭 browser（兜底超时 5s）
+    if (browserRef.current) {
+      try {
+        await Promise.race([
+          browserRef.current.close(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('close timeout')), 5000)),
+        ]);
+      } catch (e) {
+        process.stderr.write(`[cleanup] browser close warning: ${e.message}\n`);
+        // 强制 SIGTERM
+        try { browserRef.current.process()?.kill('SIGTERM'); } catch (_) {}
+      }
+    }
+  }
+
+  const written = writtenFiles.length;
+  return {
+    planned,
+    written,
+    failed: failedCount,
+    // 成功采集到的品类数 —— 上层用它判断"是不是一个都没成功"
+    okCategories,
+    partial: failedCount > 0 || written < planned,
+    partialReasons,
+    files: writtenFiles,
+  };
+}
+
+// import.meta.main 需要 Node >= 22.19（package.json 声明支持 node >=18.0.0）。
+// 旧版本上它是 undefined，必须回落到 argv[1] 比对 —— 否则整个脚本静默空跑：
+// exit 0、无 stdout、没有任何采集文件，调用方只看到"采集失败"。
+const isMain = import.meta.main ??
+  (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href);
+
+if (isMain) {
+  // 把 dispose 包装成 hook，确保 OCR worker 在退出前 dispose（避免热加载残留）
+  runCli(main(), "番茄采集", {
+    beforeExit: disposeOcrWorker,
+  });
+}