@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-scan/scripts/run-scan.js

@@ -12,12 +12,14 @@
  *   node run-scan.js --project-root <abs> --platform fanqie --rank 1_2
  */
 
-import { writeFileSync, existsSync, mkdirSync, renameSync } from 'fs';
-import { join, dirname } from 'path';
+import { existsSync, lstatSync, mkdirSync, realpathSync, statSync } from 'fs';
+import { isAbsolute, join, relative, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnScript, killProcessTree } from '#infra';
 import { EC, errorResponse } from '#error-codes';
-import { localDateStamp, normalizeBookIntro, normalizeScanMode, DEFAULT_SCAN_MODE } from '#scraper-utils';
+import { atomicWriteFile, atomicWriteJSON } from '#atomic-write';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+import { localDateStamp, normalizeBookIntro, normalizeScanMode, DEFAULT_SCAN_MODE, renderIntroLines, sanitizeBookFields } from '#scraper-utils';
 import { readDeployedState, PHASE_ORDER, DEPLOYED_STATUS } from '#deployed-state';
 
 // 调用 scraper 的超时预算。
@@ -75,11 +77,12 @@ function ensureDir(dir) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
-// 原子写 JSON：写到 .tmp 后 rename，避免半截文件污染状态
-function atomicWriteJSON(filepath, data) {
-  const tmpPath = join(dirname(filepath), `.${Date.now()}-${process.pid}.tmp`);
-  writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
-  renameSync(tmpPath, filepath);
+/** child 是否在 parent 目录内（防止 scraper 把文件写到项目外） */
+function isPathInside(parent, child) {
+  const p = resolve(parent);
+  const c = resolve(child);
+  const rel = relative(p, c);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
 }
 
 // phase 顺序（从早到晚），用于判定"只进不退"
@@ -115,7 +118,7 @@ function advancePhase(projectRoot, nextPhase) {
   const previousPhase = data.phase;
   data.phase = nextPhase;
   try {
-    atomicWriteJSON(deployedPath, data);
+    atomicWriteJSON(deployedPath, data, { mode: 0o600 });
   } catch (e) {
     return { updated: false, reason: 'write_failed', message: e.message };
   }
@@ -153,18 +156,69 @@ const QIDIAN_RANK_TYPES = [
  * 详情页还补上了 bookStatus：榜单 records 的键实测为
  * _index/bAuth/bName/bid/cat/catId/cnt/desc/rankNum/subCat/subCatId，
  * 没有任何 status 类字段，20/20 为空 —— 此前产出的 `**状态：**` 行恒为空。
+ *
+ * ## 月票（2026-10-28）
+ *
+ * 起点此前**没有任何热度指标** —— 产出的 md 里只有作者/题材/状态/字数/简介，
+ * 没有能判断一本书热不热的数字。而榜单页的 records 也**不带月票**：
+ * 实测 keys 为 catId/rankCnt/bName/rankNum/cat/cnt/subCatId/bid/subCat/bAuth/desc/_index，
+ * 其中 `rankCnt` **随榜单类型变化**：
+ *   - 月票榜 → "12.81万月票"（有，但精度只到万位）
+ *   - 书友榜 → "3541"（收藏数）
+ *   - 推荐榜 → "4.15万推荐"
+ *   - 畅销榜 / 阅读榜 / 新书榜 → **没有** rankCnt
+ *
+ * 也就是说光靠榜单页拿不到稳定可比的月票数。
+ * 详情页的 `bookInfo.monthTicket` 才是**精确整数**（实测 123271），
+ * 所以月票一律取详情页。
+ *
+ * ## 起点其它热度指标（2026-10-28）
+ *
+ * 起点不止月票，详情页还给了三个同样能判断热度的字段，一并采集：
+ *
+ *   · `bookInfo.recomAll` —— **总推荐票**（开书至今累计，实测 99261 ~ 3739 万）
+ *   · `bookInfo.recomWeek` —— **周推荐票**（最近一周，实测 4031 ~ 41826）
+ *   · `pageData.rewardInfo.todayCnt / weekCnt` —— **打赏**（今日/本周，实测 2 ~ 352）
+ *
+ * 三个都实测过 12/12 本都有值，且区分度够大。但口径完全不同：
+ * `recomAll` 是**历史累计**（老书天然占优），`recomWeek` 是**周增量**，
+ * 打赏是**次数不是金额**（页面不公开打赏金额，`totalprice` 恒为 0）。
+ *
+ * 顺带查了榜单页的 records：`totalRecommend` 这个键**所有榜都是 undefined**
+ * （月票榜/畅销榜/推荐榜/阅读榜各 0/20），所以总推荐只能取详情页。
  */
 async function fetchBookDetail(bookUrl, headers) {
   const html = await fetch(bookUrl, { headers, signal: AbortSignal.timeout(15000) })
     .then(r => r.text());
   const m = html.match(/<script[^>]+id=["']vite-plugin-ssr_pageContext["'][^>]*>([\s\S]*?)<\/script>/i);
   if (!m) throw new Error('未找到 pageContext');
-  const bookInfo = JSON.parse(m[1])?.pageContext?.pageProps?.pageData?.bookInfo;
+  const pageData = JSON.parse(m[1])?.pageContext?.pageProps?.pageData;
+  const bookInfo = pageData?.bookInfo;
   if (!bookInfo) throw new Error('未找到 bookInfo');
+  // 取不到就返回 null（区别于"真的是 0"）—— 渲染时据此决定要不要写这一行。
+  // 注：这个函数被测试用源码切片单独调用，所以辅助函数只能定义在函数体内。
+  const numOrNull = (v) => {
+    if (v === null || v === undefined || v === '') return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  };
+  const reward = pageData.rewardInfo || {};
+  const monthTicket = numOrNull(bookInfo.monthTicket);
   return {
     intro: normalizeBookIntro(bookInfo.desc || ''),
     status: bookInfo.bookStatus || '',
     signStatus: bookInfo.signStatus || '',
+    // 月票：精确整数。别用 noRewardMonthTic（那是"未奖励月票"，恒为 0）。
+    // 额外保留 present：0 张是合法数据，不能和"字段缺失"混为一谈。
+    monthTicket: monthTicket === null ? 0 : monthTicket,
+    monthTicketPresent: monthTicket !== null,
+    // 总推荐票：开书至今累计（bookInfo.recomAll）
+    totalRecommend: numOrNull(bookInfo.recomAll),
+    // 周推荐票：最近一周（bookInfo.recomWeek）
+    weekRecommend: numOrNull(bookInfo.recomWeek),
+    // 打赏：**次数**，不是金额 —— 页面不公开打赏金额（totalprice 恒为 0）
+    rewardToday: numOrNull(reward.todayCnt),
+    rewardWeek: numOrNull(reward.weekCnt),
   };
 }
 
@@ -232,15 +286,34 @@ async function scrapeQidianRank(rankId, outDir) {
       const detail = await fetchBookDetail(b.url, MOBILE_HEADERS);
       b.intro = detail.intro;
       if (!b.status && detail.status) b.status = detail.status;
+      b.monthTicket = detail.monthTicket;
+      b.monthTicketPresent = detail.monthTicketPresent;
+      if (detail.totalRecommend !== null) b.totalRecommend = detail.totalRecommend;
+      if (detail.weekRecommend !== null) b.weekRecommend = detail.weekRecommend;
+      if (detail.rewardToday !== null || detail.rewardWeek !== null) {
+        b.rewardToday = detail.rewardToday;
+        b.rewardWeek = detail.rewardWeek;
+      }
     } catch (e) {
       partialReasons.push(`${b.title} 简介获取失败: ${e.message}`);
     }
   }
 
+  // 全部详情页都失败时，文件里既没有简介也没有热度指标 —— 这不是
+  // “部分失败”，是整榜数据不可用。直接判失败，别让下游在空数据上做分析。
+  const usable = books.filter(b => b.intro || b.monthTicketPresent).length;
+  if (usable === 0) {
+    return {
+      ok: false,
+      error: `${RANK_TYPE.label} 所有书籍详情页获取失败：${partialReasons.slice(0, 3).join('；')}`,
+      partialReasons,
+    };
+  }
+
   const today = localDateStamp();
   const outFile = join(outDir, `${PLATFORM_CN.qidian}${RANK_TYPE.label}_${today}.md`);
   const md = renderQidianMarkdown(RANK_TYPE.label, url, books);
-  writeFileSync(outFile, md, 'utf-8');
+  atomicWriteFile(outFile, md);
 
   return {
     ok: true,
@@ -264,19 +337,38 @@ function renderQidianMarkdown(rankLabel, url, books) {
     '',
   ];
 
-  for (const b of books) {
+  for (const raw of books) {
+    const b = sanitizeBookFields(raw);
     lines.push(`## #${b.rank} ${b.title}`);
-    if (b.author) lines.push(`**作者：** ${b.author}`);
-    if (b.genre) lines.push(`**题材：** ${b.genre}`);
-    if (b.status) lines.push(`**状态：** ${b.status}`);
-    lines.push(`**字数：** ${b.words || '[待补]'}`);
+    if (b.author) lines.push(`- **作者：** ${b.author}`);
+    if (b.genre) lines.push(`- **题材：** ${b.genre}`);
+    if (b.status) lines.push(`- **状态：** ${b.status}`);
+    // 缺失就不写这一行。写 [待补] 会让下游把它当成真实字数/占位符。
+    if (b.words) lines.push(`- **字数：** ${b.words}`);
+    // 热度指标 —— 起点的四个热度数字，口径各不相同，别混用：
+    //   月票（当月，主指标）/ 总推荐（开书至今累计）/ 周推荐（最近一周）/ 打赏（今日·本周人次）
+    // 0 张是合法数据；只有明确“缺失”（monthTicketPresent === false）才不写。
+    const hasMonthTicket = b.monthTicketPresent !== false
+      && typeof b.monthTicket === 'number' && Number.isFinite(b.monthTicket);
+    if (hasMonthTicket) lines.push(`- **月票：** ${b.monthTicket}`);
+    // 注意：字段可能是 null（取不到）、undefined（压根没取）、
+    // 也可能真的是 0。三者必须分开 —— 把"没取到"当成 0 写进文件，
+    // 等于告诉模型"这本书本周没人打赏"，那是编造。
+    const hasNum = (v) => v !== null && v !== undefined;
+    if (hasNum(b.totalRecommend)) lines.push(`- **总推荐：** ${b.totalRecommend}`);
+    if (hasNum(b.weekRecommend)) lines.push(`- **周推荐：** ${b.weekRecommend}`);
+    if (hasNum(b.rewardToday) || hasNum(b.rewardWeek)) {
+      const t = hasNum(b.rewardToday) ? b.rewardToday : 0;
+      const w = hasNum(b.rewardWeek) ? b.rewardWeek : 0;
+      lines.push(`- **打赏：** 今日 ${t} / 本周 ${w}`);
+    }
     if (b.intro) {
-      // 格式与其它字段保持一致：首段紧跟标签，其余段落各自成段
-      const paras = b.intro.split('\n\n');
-      lines.push(`**简介：** ${paras[0]}`);
-      for (const p of paras.slice(1)) lines.push('', p);
+      // 格式与其它字段保持一致：首段紧跟标签，其余段落各自成段。
+      // 起点简介里的换行有两种语义（<br> → 行分隔、段落标签 → 段分隔），
+      // 所以按空行分段，不按单换行。
+      lines.push(...renderIntroLines(b.intro));
     }
-    if (b.url) lines.push(`[作品页](${b.url})`);
+    if (b.url) lines.push(`- [作品页](${b.url})`);
     lines.push('', '---', '');
   }
 
@@ -417,6 +509,10 @@ async function runScraper(platform, rank, outDir, scanMode) {
     ok: true,
     writtenFiles,
     failed: receipt.failed || 0,
+    // 成功采集到的品类数（番茄 receipt 提供）。没有这个字段的平台
+    // （起点/晋江/七猫）返回 undefined —— 调用方按"未知"处理，不拦。
+    okCategories: Number.isInteger(receipt.okCategories) ? receipt.okCategories : undefined,
+    planned: Number.isInteger(receipt.planned) ? receipt.planned : undefined,
     partial: receipt.partial || false,
     partialReasons: receipt.partialReasons || [],
   };
@@ -444,16 +540,46 @@ async function main() {
     throw new Error('缺少必要参数: --project-root --platform --rank');
   }
 
+  if (!isAbsolute(projectRoot)) {
+    throw new Error(`--project-root 必须是绝对路径: ${projectRoot}`);
+  }
+  projectRoot = resolve(projectRoot);
+  if (isSensitiveProjectPath(projectRoot) || !isValidProjectPath(projectRoot)) {
+    throw new Error(`--project-root 路径不合法或属于受保护目录: ${projectRoot}`);
+  }
   if (!existsSync(join(projectRoot, '.fancy-deployed'))) {
     throw new Error('项目未初始化：.fancy-deployed 不存在');
   }
 
+  // 先判“有没有初始化”，再解开符号链接查真实路径：
+  // 目录不存在时应报 EC124（未初始化），而不是把“路径读不了”误报成 EC001。
+  try {
+    projectRoot = realpathSync(projectRoot);
+  } catch (e) {
+    throw new Error(`无法读取 --project-root：${e.message}`);
+  }
+  if (isSensitiveProjectPath(projectRoot) || !isValidProjectPath(projectRoot)) {
+    throw new Error(`--project-root 的真实路径属于受保护目录: ${projectRoot}`);
+  }
+
   if (!VALID_PLATFORMS.includes(platform)) {
     throw new Error(`不支持的平台: ${platform}`);
   }
 
   const today = localDateStamp();
   const scanDir = join(projectRoot, '扫榜结果');
+  // 扫榜结果/ 如果是符号链接，写盘会落到链接指向的项目外。
+  // 这是插件自己管理的产物目录，不允许用链接代替。
+  try {
+    if (existsSync(scanDir)) {
+      const st = lstatSync(scanDir);
+      if (st.isSymbolicLink() || !st.isDirectory()) {
+        throw new Error('扫榜结果/ 不是真实目录，拒绝写入；请换成真实目录');
+      }
+    }
+  } catch (e) {
+    if (e && e.message && e.message.includes('不是真实目录')) throw e;
+  }
   ensureDir(scanDir);
 
   let scanFiles = [];
@@ -470,6 +596,18 @@ async function main() {
   }
 
   scanFiles = r.writtenFiles;
+  // scraper 报告的文件必须在 扫榜结果/ 内且真实存在。
+  // 不能让一个被篡改/写错的 scraper 把任意路径塞进扫描回执，
+  // 后面 LLM 会把它当作数据文件去读。
+  const scanDirReal = realpathSync(scanDir);
+  for (const f of scanFiles) {
+    let realFile = '';
+    try { realFile = realpathSync(f); } catch { /* 不存在 */ }
+    if (!realFile || !isPathInside(scanDirReal, realFile)
+      || !existsSync(realFile) || !statSync(realFile).isFile()) {
+      throw new Error(`scraper 返回了非法输出文件: ${f}`);
+    }
+  }
   failed = r.failed || 0;
   if (Array.isArray(r.partialReasons)) partialReasons.push(...r.partialReasons);
 
@@ -477,7 +615,16 @@ async function main() {
   // 部分失败（failed>0）也算成功推进，因为已有产出文件
   // 注：fancy-topic 启动时会再检查 topic_decision_<date>.md 是否存在，
   //     并要求 phase === 'scanned' 才允许运行
-  const phaseResult = advancePhase(projectRoot, 'scanned');
+  //
+  // **但一个品类都没成功时不推进**（2026-10-29 审计）：
+  // 番茄在所有品类都失败时**照样写文件**（里面全是 `## <品类> — 采集失败`），
+  // 于是 scanFiles.length > 0 → 判成功 → phase 推进到 scanned
+  // → 用户以为扫好了，跑 /fancy-topic 却在空报告上做选题。
+  const nothingSucceeded = r.okCategories === 0
+    && Number.isInteger(r.planned) && r.planned > 0;
+  const phaseResult = nothingSucceeded
+    ? { updated: false, reason: 'no_category_succeeded' }
+    : advancePhase(projectRoot, 'scanned');
   console.error(`  📌 phase: ${phaseResult.updated ? `${phaseResult.previousPhase} → ${phaseResult.currentPhase}` : phaseResult.reason}`);
   // "没推进"有两种含义，必须分开：
   //   already_at_phase / already_advanced —— 正常（重扫），不是问题

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

@@ -21,11 +21,12 @@
  */
 
 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 } from '#scraper-utils';
+import { getArg, localDateStamp, runCli, normalizeScanMode, SCAN_MODE_API, renderIntroLines, sanitizeBookFields, sanitizeMarkdownInline } from '#scraper-utils';
 
 // 捕获未处理的 promise 错误——只写 stderr，让上层重试逻辑处理，不要直接退出
 process.on('unhandledRejection', (reason) => {
@@ -73,11 +74,21 @@ function typeLabel(t) {
  * 等待排名前 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) { await page.waitForTimeout(2000); continue; }
-    const h1Text = await page.locator('.rank-book-item').nth(n - 1).locator('.book-item-index h1').textContent().catch(() => '');
-    if (h1Text && h1Text.trim() !== '') return true;
+    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;
@@ -86,7 +97,7 @@ async function waitForRankN(page, n) {
 async function screenshotToFile(locator, filepath) {
   const buf = await locator.screenshot({ type: 'jpeg', quality: 95 });
   fs.mkdirSync(path.dirname(filepath), { recursive: true });
-  fs.writeFileSync(filepath, buf);
+  atomicWriteFile(filepath, buf);
   return filepath;
 }
 
@@ -295,7 +306,7 @@ const API_UA = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like
 const API_TIMEOUT_MS = 20000;   // 实测 p95 延迟 463ms，留足余量
 const API_CONCURRENCY = 8;      // 实测 8 并发 24 QPS 零失败；40 并发 70 QPS 也零失败，
                                 // 但曾观测到突发后的一次 444 限流窗口，保守取 8
-const API_RETRY = 1;            // 失败重试次数（总尝试 = API_RETRY + 1）
+const API_RETRY = 3;            // 失败重试次数（总尝试 = API_RETRY + 1）
 const API_RETRY_DELAY_MS = 1500;
 
 /**
@@ -318,10 +329,41 @@ async function fetchBookInfo(bookId) {
     throw new Error(json && json.message ? String(json.message) : `接口返回 code=${json && json.code}`);
   }
   const data = json.data;
-  if (!data || !data.abstract) throw new Error('接口未返回简介');
+  // 缺**书名**才是整本失败；缺简介不算（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 } 的缓存。
  *
@@ -345,12 +387,15 @@ async function loadBookInfo(bookId) {
       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 result = { ok: false, error: lastError ? lastError.message : '未知错误' };
+  const reason = describeBookInfoError(lastError);
+  process.stderr.write(`[api-fail] 番茄/${bookId}: ${reason}\n`);
+  const result = { ok: false, error: reason };
   _bookInfoCache.set(bookId, result);
   return result;
 }
@@ -445,6 +490,56 @@ async function prepareOcrFriendlyStyles(page) {
  * 返回 { 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);
@@ -472,6 +567,11 @@ async function scrapeCategory(page, catHref, catName, ch, type, screenshotBase)
     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}`;
@@ -487,6 +587,7 @@ async function scrapeCategory(page, catHref, catName, ch, type, screenshotBase)
         status: (statusRaw || '').trim() || '未知',
         desc: '',
         readerCount: readerCount || '未知',
+        rankChange,
       });
       continue;
     }
@@ -519,6 +620,7 @@ async function scrapeCategory(page, catHref, catName, ch, type, screenshotBase)
       status: ocr.status || '未知',
       desc: ocr.desc || '',
       readerCount: readerCount || '未知',
+      rankChange,
     });
   }
 
@@ -533,6 +635,13 @@ async function scrapeCategory(page, catHref, catName, ch, type, screenshotBase)
         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（压根没法查接口），
@@ -552,14 +661,23 @@ async function scrapeCategory(page, catHref, catName, ch, type, screenshotBase)
 
 function buildMarkdown(catName, books) {
   const lines = [];
-  lines.push(`## ${catName} — ${books.length} 本`, '');
-  for (const b of books) {
+  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}`);
-    if (b.readerCount) lines.push(`**在读：** ${b.readerCount}`);
-    if (b.desc) { lines.push(''); lines.push('**简介**'); lines.push(b.desc); }
-    if (b.url) lines.push(`[作品页](https://fanqienovel.com${b.url})`);
+    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('---', '');
@@ -635,6 +753,11 @@ async function scrapeChannel(browserRef, ch, type) {
   // 单本取数失败与"品类采集失败"是两种不同粒度的失败，单位不能混：
   // 前者计本数，后者计题材数。两者都要进 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++) {
@@ -660,6 +783,7 @@ async function scrapeChannel(browserRef, ch, type) {
           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`);
@@ -693,12 +817,13 @@ async function scrapeChannel(browserRef, ch, type) {
   const filename = `番茄${channelLabel(ch)}${typeLabel(type)}_${date}.md`;
   fs.mkdirSync(OUTDIR, { recursive: true });
   const filepath = path.join(OUTDIR, filename);
-  fs.writeFileSync(filepath, allLines.join('\n'), 'utf-8');
+  atomicWriteFile(filepath, allLines.join('\n'));
   writtenFiles.push(filepath);
 
   return {
     writtenFiles,
     failed: failedCategories + failedBooks,
+    okCategories,
     partialReasons,
   };
 }
@@ -729,6 +854,7 @@ async function main() {
   const writtenFiles = [];
   const partialReasons = [];
   let failedCount = 0;
+  let okCategories = 0;
 
   // 首次启动 browser（失败时尝试一次 fallback 重试）
   try {
@@ -746,6 +872,7 @@ async function main() {
           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++;
@@ -774,6 +901,8 @@ async function main() {
     planned,
     written,
     failed: failedCount,
+    // 成功采集到的品类数 —— 上层用它判断"是不是一个都没成功"
+    okCategories,
     partial: failedCount > 0 || written < planned,
     partialReasons,
     files: writtenFiles,