@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

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

@@ -0,0 +1,667 @@
+#!/usr/bin/env node
+/**
+ * fancy-scan run-scan.js — 采集编排层
+ *
+ * 职责：
+ * 1. 检查 .fancy-deployed
+ * 2. 调用平台采集脚本（qidian HTTP；其他平台通过 playwright-core）
+ * 3. 解析 scraper 的结构化 JSON receipt
+ * 4. 生成汇总 receipt 输出到 stdout
+ *
+ * 调用方式：
+ *   node run-scan.js --project-root <abs> --platform fanqie --rank 1_2
+ */
+
+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 { 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 的超时预算。
+//
+// 插件层给 run-scan.js 的预算是 30 分钟（fancy-scan/index.js 的 spawnScript），
+// 这里必须留出余量：**内层要早于外层触发**，否则外层会先掐死本进程，
+// 而 scraper 是被 detached 出去、独立成组的 —— 外层的 process.kill(-pid)
+// 够不到它；本进程一死，本层的定时器随之消失，scraper 就永远收不到
+// SIGTERM，会带着 chromium 一路跑到自然结束。
+//
+// 实测（外层 8s / 内层 60s 的真实番茄链路）：外层超时后 11.5 秒，
+// scraper 进程仍在，headless chrome 从 7 涨到 13 —— 确认是孤儿。
+// 本层 25 分钟 < 外层 30 分钟后，超时先由本层处理：
+// 杀进程组 → scraper 收到 SIGTERM → 它自己关掉浏览器 → 干净退出。
+const SCRAPER_TIMEOUT_MS = 25 * 60 * 1000;
+
+// 字符串消息 → EC 码映射，用于把 main() 里 throw new Error(msg) 转成结构化错误
+const MSG_TO_EC = {
+  '缺少必要参数: --project-root --platform --rank': EC.EC042_MISSING_REQUIRED,
+  '项目未初始化：.fancy-deployed 不存在': EC.EC124_PROJECT_NOT_INITIALIZED,
+  '不支持的平台': EC.EC029_INVALID_PLATFORM_SCAN,
+};
+
+// EC027_NO_OUTPUT_FILES 用前缀匹配（runScraper 返回的错误带平台名前缀）
+function lookupEC(msg) {
+  if (MSG_TO_EC[msg]) return MSG_TO_EC[msg];
+  if (msg.includes('未找到输出文件')) return EC.EC027_NO_OUTPUT_FILES;
+  if (msg.startsWith('不支持的平台')) return EC.EC029_INVALID_PLATFORM_SCAN;
+  if (msg.includes('JSON')) return EC.EC123_JSON_PARSE_FAIL;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 平台配置
+// ---------------------------------------------------------------------------
+
+const VALID_PLATFORMS = ['qidian', 'fanqie', 'jinjiang', 'qimao'];
+
+const PLATFORM_CN = {
+  qidian:   '起点',
+  fanqie:   '番茄',
+  jinjiang: '晋江',
+  qimao:    '七猫',
+};
+
+// ---------------------------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------------------------
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/** 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 顺序（从早到晚），用于判定"只进不退"
+
+// 把 .fancy-deployed 的 phase 推进到指定值；只能向前推进或保持
+// 不会从 analyzed 退回到 scanned
+function advancePhase(projectRoot, nextPhase) {
+  const deployedPath = join(projectRoot, '.fancy-deployed');
+  // 用共享体检读状态：missing / corrupt / no_phase / unknown_phase 四种情况
+  // 在这里被统一区分开，不再靠 JSON.parse 抛异常来表达"文件坏了"。
+  const state = readDeployedState(projectRoot);
+  if (state.status === DEPLOYED_STATUS.MISSING) {
+    return { updated: false, reason: 'project_not_initialized' };
+  }
+  if (state.status === DEPLOYED_STATUS.CORRUPT) {
+    return { updated: false, reason: 'corrupt', message: state.error };
+  }
+  if (state.status === DEPLOYED_STATUS.NO_PHASE) {
+    return { updated: false, reason: 'unknown_phase', currentPhase: null, requestedPhase: nextPhase };
+  }
+  if (state.status === DEPLOYED_STATUS.UNKNOWN_PHASE) {
+    return { updated: false, reason: 'unknown_phase', currentPhase: state.phase, requestedPhase: nextPhase };
+  }
+  const data = state.config;
+  const currentRank = PHASE_ORDER.indexOf(data.phase);
+  const nextRank = PHASE_ORDER.indexOf(nextPhase);
+  if (currentRank === -1 || nextRank === -1) {
+    return { updated: false, reason: 'unknown_phase', currentPhase: data.phase, requestedPhase: nextPhase };
+  }
+  if (currentRank >= nextRank) {
+    return { updated: false, reason: currentRank === nextRank ? 'already_at_phase' : 'already_advanced', currentPhase: data.phase, requestedPhase: nextPhase };
+  }
+  const previousPhase = data.phase;
+  data.phase = nextPhase;
+  try {
+    atomicWriteJSON(deployedPath, data, { mode: 0o600 });
+  } catch (e) {
+    return { updated: false, reason: 'write_failed', message: e.message };
+  }
+  return { updated: true, previousPhase, currentPhase: nextPhase };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP 采集 — 起点 mobile SSR
+// ---------------------------------------------------------------------------
+
+// 起点榜单（移动端 m.qidian.com）。
+// 路径与页面中文名均取自 m.qidian.com 各榜单页的实测结果：
+//   readindex → 阅读榜 / newfans → 书友榜（不是"新粉榜"）
+// PC 端 www.qidian.com 同一路径有瑞数 WAF + 腾讯滑块验证码，纯 HTTP 拿不到数据，
+// 故固定走移动端；移动端没有 /rank/recom/（404），推荐榜的移动端路径是 /rank/rec/。
+const QIDIAN_RANK_TYPES = [
+  { id: 'hotsales',   label: '畅销榜',     path: '/rank/hotsales/' },
+  { id: 'yuepiao',   label: '月票榜',     path: '/rank/yuepiao/' },
+  { id: 'readindex', label: '阅读榜',     path: '/rank/readindex/' },
+  { id: 'newfans',   label: '书友榜',     path: '/rank/newfans/' },
+  { id: 'rec',       label: '推荐榜',     path: '/rank/rec/' },
+  { id: 'update',    label: '更新榜',     path: '/rank/update/' },
+  { id: 'sign',      label: '签约榜',     path: '/rank/sign/' },
+  { id: 'newbook',   label: '新书榜',     path: '/rank/newbook/' },
+  { id: 'newauthor', label: '新人作者榜', path: '/rank/newauthor/' },
+];
+
+/**
+ * 抓取单本作品的详情（移动端详情页 SSR）。
+ *
+ * 榜单页 records 里也有 desc，但它比详情页短：实测新书榜 20 本，
+ * 详情 desc 100% 更长（中位 +8 字符，最大 +56），其中 2 本榜单 desc
+ * 尾部带省略号。详情 desc 才是完整版，代价是每本多一次请求。
+ *
+ * 详情页还补上了 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 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),
+  };
+}
+
+async function scrapeQidianRank(rankId, outDir) {
+  const MOBILE_BASE = 'https://m.qidian.com';
+  const RANK_TYPE = QIDIAN_RANK_TYPES.find(r => r.id === rankId);
+  if (!RANK_TYPE) {
+    return { ok: false, error: `未知榜单 ID: ${rankId}` };
+  }
+
+  const MOBILE_HEADERS = {
+    'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+    'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+    'Accept-Encoding': 'identity',
+  };
+
+  const url = `${MOBILE_BASE}${RANK_TYPE.path}`;
+  let html = '';
+  try {
+    html = await fetch(url, { headers: MOBILE_HEADERS, signal: AbortSignal.timeout(15000) }).then(r => r.text());
+  } catch (e) {
+    return { ok: false, error: `${RANK_TYPE.label} 请求失败: ${e.message}` };
+  }
+
+  const m = html.match(/<script[^>]+id=["']vite-plugin-ssr_pageContext["'][^>]*>([\s\S]*?)<\/script>/i);
+  if (!m) {
+    return { ok: false, error: `${RANK_TYPE.label} 未找到 pageContext` };
+  }
+
+  let pageContext;
+  try {
+    pageContext = JSON.parse(m[1]);
+  } catch (e) {
+    return { ok: false, error: `${RANK_TYPE.label} JSON 解析失败` };
+  }
+
+  const records = pageContext?.pageContext?.pageProps?.pageData?.records || [];
+  if (!records.length) {
+    return { ok: false, error: `${RANK_TYPE.label} 无书籍数据` };
+  }
+
+  const books = records.map((r, i) => ({
+    rank:    r.rankNum || i + 1,
+    title:   r.bName || r.bookName || '',
+    url:     r.bid ? `${MOBILE_BASE}/book/${r.bid}/` : '',
+    author:  r.bAuth || r.author || '',
+    genre:   [r.cat, r.subCat].filter(Boolean).join('·'),
+    status:  r.status || '',
+    words:   r.cnt || r.wordCount || '',
+    rankValue: r.rankCnt || '',
+    totalRecommend: r.totalRecommend || '',
+    signStatus: r.signStatus || '',
+    vipStatus: r.vipStatus || '',
+  }));
+
+  // 逐本访问详情页补简介。
+  // 串行而非并发：起点有瑞数 WAF（当前靠移动端规避），并发易触发风控。
+  // 单本失败不中断整个榜单 —— 失败原因记入 partialReasons，
+  // 由 run-scan.js 的 receipt 一路带到插件层显示在失败清单里。
+  const partialReasons = [];
+  for (const b of books) {
+    if (!b.url) continue;
+    try {
+      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);
+  atomicWriteFile(outFile, md);
+
+  return {
+    ok: true,
+    writtenFiles: [outFile],
+    failed: partialReasons.length,
+    partialReasons,
+  };
+}
+
+function renderQidianMarkdown(rankLabel, url, books) {
+  const now = nowIso();
+  const lines = [
+    `# 起点 · ${rankLabel}`,
+    '',
+    `- 来源：${url}`,
+    `- 抓取方式：mobile-ssr`,
+    `- 抓取时间：${now}`,
+    `- 条目数：${books.length}`,
+    '',
+    '---',
+    '',
+  ];
+
+  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}`);
+    // 缺失就不写这一行。写 [待补] 会让下游把它当成真实字数/占位符。
+    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) {
+      // 格式与其它字段保持一致：首段紧跟标签，其余段落各自成段。
+      // 起点简介里的换行有两种语义（<br> → 行分隔、段落标签 → 段分隔），
+      // 所以按空行分段，不按单换行。
+      lines.push(...renderIntroLines(b.intro));
+    }
+    if (b.url) lines.push(`- [作品页](${b.url})`);
+    lines.push('', '---', '');
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// scraper 参数构造（platform → 调哪个 scraper）
+// ---------------------------------------------------------------------------
+
+function scraperArgs(platform, rank, scanMode) {
+  switch (platform) {
+    case 'fanqie': {
+      const [channel, type] = rank.split('_');
+      return {
+        script: 'fanqie-rank-scraper.js',
+        // --scan-mode 决定番茄用明文接口还是截图 OCR 取书名/作者/简介。
+        // 非法值在 normalizeScanMode 里已回落到默认，不会透传给 scraper。
+        extra: ['--channel', channel, '--type', type, '--top', '10',
+                '--scan-mode', normalizeScanMode(scanMode)],
+      };
+    }
+    case 'jinjiang':
+      return {
+        script: 'jjwxc-rank-scraper.js',
+        extra: ['--type', rank],
+      };
+    case 'qimao': {
+      const parts = rank.split('/');
+      const channel = parts[0];
+      const type = parts[1];
+      const period = parts[2] || 'day';
+      return {
+        script: 'qimao-rank-scraper.js',
+        extra: ['--channel', channel, '--type', type, '--period', period],
+      };
+    }
+    default:
+      return { script: null, extra: [] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 调用 scraper（统一用 infra.js spawnScript）
+// ---------------------------------------------------------------------------
+
+/**
+ * 把 spawnScript 的原始错误转成人话。
+ *
+ * "timeout after 1500000ms" 是内部实现细节，会原样出现在给用户看的
+ * 失败清单里；这里转成"采集超时（超过 25 分钟未完成）"。
+ */
+function humanizeSpawnError(raw) {
+  const text = String(raw ?? '');
+  const t = /^timeout after (\d+)ms$/.exec(text);
+  if (!t) return text;
+  return `采集超时（超过 ${Math.round(Number(t[1]) / 60000)} 分钟未完成）`;
+}
+
+async function runScraper(platform, rank, outDir, scanMode) {
+  const args = scraperArgs(platform, rank, scanMode);
+  if (!args.script) {
+    return { ok: false, error: `平台 ${platform} 暂不支持采集` };
+  }
+
+  // scraper 脚本路径（相对 run-scan.js）
+  // 必须用 fileURLToPath：URL.pathname 会把空格/中文百分号编码
+  // （/tmp/普通 目录 → /tmp/%E6%99%AE%E9%80%9A%20%E7%9B%AE%E5%BD%95），
+  // 拼出来的路径不存在，采集必然失败。
+  const scraperPath = join(fileURLToPath(new URL('.', import.meta.url)), 'scrapers', args.script);
+  const fullArgs = ['--outdir', outDir, ...args.extra];
+
+  // 不传 NODE_PATH：tesseract.js 由 scraper 脚本按 node_modules 向上查找解析
+  // （scraper 位于 <repo>/plugins/fancy-scan/scripts/scrapers/ 下，
+  //  能找到 <repo>/node_modules/tesseract.js），实测未设 NODE_PATH 时 OCR 正常。
+  // 此前硬编码的 /home/cloud/.npm-global/lib/node_modules 下并没有 tesseract.js，
+  // 覆盖用户自带的 NODE_PATH 只会带来副作用。
+  const result = await spawnScript('node', [scraperPath, ...fullArgs], {
+    timeout: SCRAPER_TIMEOUT_MS,
+    onSpawn: (proc) => {
+      // 本进程被 SIGTERM（上游超时或用户中断）时，scraper 因为 detached
+      // 独立成组、不在本进程组里，必须显式转发 —— 否则它会带着 chromium
+      // 继续跑完整流程。转发后不立刻退出：让 scraper 自己收尾（关浏览器），
+      // 本进程随后会拿到失败 receipt 正常退出。
+      process.on('SIGTERM', () => {
+        killProcessTree(proc, 'SIGTERM');
+        // 兜底：scraper 若迟迟不退，10 秒后强制结束本进程。
+        setTimeout(() => process.exit(143), 10000).unref();
+      });
+    },
+  });
+
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: humanizeSpawnError(result.error || `exit ${result.code}`),
+      stderr: result.stderr,
+    };
+  }
+
+  // 解析结构化 receipt（fanqie/jinjiang/qimao 都用此协议）
+  let receipt;
+  try {
+    receipt = JSON.parse(result.output);
+  } catch (_) {
+    // 优先用 stderr 作为错误信息（stdout 经常被进度日志污染）
+    const stderrTail = (result.stderr || '').trim().slice(-300);
+    const stdoutTail = (result.output || '').trim().slice(-200);
+    return {
+      ok: false,
+      error: stderrTail
+        ? `scraper 输出非 JSON；stderr: ${stderrTail}`
+        : `scraper 输出非 JSON；stdout: ${stdoutTail}`,
+      stderr: result.stderr,
+    };
+  }
+
+  if (receipt.ok === false) {
+    // receipt.error 可能为 undefined（scraper 没设置），fallback 到 stderr
+    const stderrTail = (result.stderr || '').trim().slice(-300);
+    return {
+      ok: false,
+      error: receipt.error || stderrTail || 'scraper 报告失败（无错误详情）',
+      stderr: result.stderr,
+    };
+  }
+
+  const writtenFiles = receipt.files || receipt.written || receipt.scan_files || [];
+  if (!Array.isArray(writtenFiles) || writtenFiles.length === 0) {
+    return {
+      ok: false,
+      error: `${PLATFORM_CN[platform]}（${rank}）采集失败：未找到输出文件`,
+      stderr: result.stderr,
+    };
+  }
+
+  return {
+    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 || [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 主流程
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = process.argv.slice(2);
+  let projectRoot = '', platform = '', rank = '';
+  // 扫描方式（取数路径）。仅番茄使用；其他平台忽略。
+  // 缺失或非法一律按默认（api）处理，绝不把未知值透传给 scraper。
+  let scanMode = DEFAULT_SCAN_MODE;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project-root') projectRoot = args[i + 1] || '';
+    if (args[i] === '--platform') platform = args[i + 1] || '';
+    if (args[i] === '--rank') rank = args[i + 1] || '';
+    if (args[i] === '--scan-mode') scanMode = args[i + 1] || '';
+  }
+
+  if (!projectRoot || !platform || !rank) {
+    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 = [];
+  let failed = 0;
+  const partialReasons = [];
+
+  // 调用 scraper
+  const r = platform === 'qidian'
+    ? await scrapeQidianRank(rank, scanDir)
+    : await runScraper(platform, rank, scanDir, scanMode);
+
+  if (!r.ok) {
+    throw new Error(r.error);
+  }
+
+  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);
+
+  // 扫榜成功 → 把 .fancy-deployed 的 phase 推进到 'scanned'
+  // 部分失败（failed>0）也算成功推进，因为已有产出文件
+  // 注：fancy-topic 启动时会再检查 topic_decision_<date>.md 是否存在，
+  //     并要求 phase === '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 —— 正常（重扫），不是问题
+  //   corrupt / unknown_phase / write_failed —— phase 推不动，流程走不下去
+  // 后者以前只写进 stderr，receipt 里看不出来，插件层于是照报"采集完成"，
+  // 用户接着跑 /fancy-topic 报"状态文件读不了"，完全不知道问题出在这儿。
+  const phaseBlocked = !phaseResult.updated
+    && !['already_at_phase', 'already_advanced'].includes(phaseResult.reason);
+
+  // 输出结构化 receipt
+  const receipt = {
+    ok: scanFiles.length > 0,
+    operation: 'scan',
+    platform,
+    rank,
+    date: today,
+    scan_files: scanFiles,
+    topic_decision: join(scanDir, `topic_decision_${today}.md`),
+    written: scanFiles.length,
+    failed,
+    partial: failed > 0,
+    partialReasons,
+    phase_advance: phaseResult,
+    phase_blocked: phaseBlocked,
+    summary: `${PLATFORM_CN[platform]}（${rank}）采集完成，共 ${scanFiles.length} 个文件`,
+  };
+
+  console.log(JSON.stringify(receipt));
+}
+
+main().catch(e => {
+  const msg = e.message || String(e);
+  // 尝试把已知消息映射到 EC 码
+  const ec = lookupEC(msg);
+  const errObj = ec
+    ? errorResponse(ec, { message: msg })
+    : { ok: false, error: { code: 1, code_name: 'EC001', message: msg } };
+  process.stdout.write(JSON.stringify(errObj) + '\n');
+  process.exit(ec ? ec.code : 1);
+});