@cloud411716/fancy-webnovel 0.1.18 → 0.1.20

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

@@ -0,0 +1,453 @@
+#!/usr/bin/env node
+/**
+ * fancy-scan run-scan.js — 采集编排层
+ *
+ * 职责：
+ * 1. 检查 .fancy-deployed
+ * 2. 调用平台采集脚本
+ * 3. 生成扫榜报告
+ * 4. 生成/追加 topic_decision
+ *
+ * 调用方式：
+ *   node run-scan.js --project-root <abs> --platform qidian --length long
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+// ---------------------------------------------------------------------------
+// 平台配置
+// ---------------------------------------------------------------------------
+
+const VALID_PLATFORMS = ['qidian', 'fanqie', 'jinjiang', 'zhihu', 'dianzhong', 'qimao'];
+const VALID_LENGTHS = ['long', 'short'];
+
+const PLATFORM_SUPPORTED_LENGTHS = {
+  qidian:   ['long'],
+  fanqie:   ['long'],
+  jinjiang: ['long'],
+  zhihu:    ['long', 'short'],
+  dianzhong:['short'],
+  qimao:    ['long', 'short'],
+};
+
+const PLATFORM_CN = {
+  qidian:   '起点',
+  fanqie:   '番茄',
+  jinjiang: '晋江',
+  zhihu:    '知乎',
+  dianzhong:'点众',
+  qimao:    '七猫',
+};
+
+// ---------------------------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------------------------
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function todayStr() {
+  const d = new Date();
+  return `${d.getFullYear()}${String(d.getMonth()+1).padStart(2,'0')}${String(d.getDate()).padStart(2,'0')}`;
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP 采集 — 起点 mobile SSR
+// ---------------------------------------------------------------------------
+
+async function scrapeQidian(outDir) {
+  const MOBILE_BASE = 'https://m.qidian.com';
+  const RANK_TYPES = [
+    { id: 'hotsales',  label: '畅销榜',   path: '/rank/hotsales/' },
+    { id: 'yuepiao',   label: '月票榜',   path: '/rank/yuepiao/' },
+    { id: 'signnewbook',label: '签约作者新书榜', path: '/rank/sign/' },
+    { id: 'pubnewbook', label: '公众作者新书榜', path: '/rank/newbook/' },
+    { id: 'newauthor', label: '新人作者新书榜', path: '/rank/newauthor/' },
+  ];
+
+  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 results = [];
+
+  for (const rt of RANK_TYPES) {
+    const url = `${MOBILE_BASE}${rt.path}`;
+    let html = '';
+    try {
+      html = await fetch(url, { headers: MOBILE_HEADERS, signal: AbortSignal.timeout(15000) }).then(r => r.text());
+    } catch (e) {
+      console.error(`  ⚠ ${rt.label} 请求失败: ${e.message}`);
+      continue;
+    }
+
+    // 提取 pageContext JSON
+    const m = html.match(/<script[^>]+id=["']vite-plugin-ssr_pageContext["'][^>]*>([\s\S]*?)<\/script>/i);
+    if (!m) {
+      console.error(`  ⚠ ${rt.label} 未找到 pageContext`);
+      continue;
+    }
+
+    let pageContext;
+    try {
+      pageContext = JSON.parse(m[1]);
+    } catch (e) {
+      console.error(`  ⚠ ${rt.label} JSON 解析失败`);
+      continue;
+    }
+
+    const records = pageContext?.pageContext?.pageProps?.pageData?.records || [];
+    if (!records.length) {
+      console.error(`  ⚠ ${rt.label} 无书籍数据`);
+      continue;
+    }
+
+    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 || '',
+    }));
+
+    const today = todayStr();
+    const outFile = join(outDir, `${PLATFORM_CN.qidian}${rt.label}_${today}.md`);
+    const md = renderQidianMarkdown(rt.label, url, books);
+    writeFileSync(outFile, md, 'utf-8');
+    console.log(`  ✅ ${rt.label}: ${books.length} 本 → ${outFile}`);
+    results.push({ label: rt.label, count: books.length, file: outFile });
+  }
+
+  return results;
+}
+
+function renderQidianMarkdown(rankLabel, url, books) {
+  const now = nowIso();
+  const lines = [
+    `# 起点 · ${rankLabel}`,
+    '',
+    `- 来源：${url}`,
+    `- 抓取方式：mobile-ssr`,
+    `- 抓取时间：${now}`,
+    `- 条目数：${books.length}`,
+    '',
+    '---',
+    '',
+  ];
+
+  for (const b of books) {
+    lines.push(`## #${b.rank} ${b.title}`);
+    const meta = [b.author, b.genre, b.status].filter(Boolean).join(' · ');
+    if (meta) lines.push(`*${meta}*`);
+    const req = (v) => (v === undefined || v === null || v === '') ? '[待补]' : String(v);
+    lines.push(`**字数：** ${req(b.words)}`);
+    if (b.rankValue) lines.push(`**榜单值：** ${b.rankValue}`);
+    lines.push(`**总推荐：** ${req(b.totalRecommend)}`);
+    lines.push(`**签约：** ${req(b.signStatus)}`);
+    lines.push(`**收费：** ${req(b.vipStatus)}`);
+    if (b.url) lines.push(`[作品页](${b.url})`);
+    lines.push('', '---', '');
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// 占位符采集 — 浏览器平台
+// ---------------------------------------------------------------------------
+
+function scrapeBrowserStub(platform, length, outDir) {
+  // 这些平台需要 browser_* 工具，由 LLM 调用
+  // 这里生成指令文件，供 LLM 读取执行
+  const today = todayStr();
+  const pcn = PLATFORM_CN[platform] || platform;
+  const lenStr = length === 'long' ? '长篇' : '短篇';
+  const instrFile = join(outDir, `_browser_instructions_${platform}_${length}_${today}.json`);
+  const instructions = getBrowserInstructions(platform, length);
+
+  writeFileSync(instrFile, JSON.stringify(instructions, null, 2), 'utf-8');
+  console.log(`  ℹ ${pcn}（${lenStr}）需要 browser_* 工具，已生成指令文件：${instrFile}`);
+  console.log(`  ℹ 请让 LLM 读取并执行该指令文件中的 browser 操作`);
+  return { file: instrFile, instructions };
+}
+
+function getBrowserInstructions(platform, length) {
+  // 返回给 LLM 的操作指令
+  const today = todayStr();
+  const pcn = PLATFORM_CN[platform] || platform;
+  const lenStr = length === 'long' ? '长篇' : '短篇';
+
+  if (platform === 'fanqie') {
+    return {
+      platform, length, pcn, lenStr, date: today,
+      action: 'scrape_fanqie',
+      steps: [
+        { tool: 'browser_navigate', url: 'https://fanqienovel.com/rankings?channel=1&type=2', label: '番茄男频阅读榜' },
+        { tool: 'sleep', seconds: 3 },
+        { tool: 'scroll', times: 3 },
+        { tool: 'extract', description: '提取页面书籍列表：排名、书名、作者、在读数、题材' },
+      ],
+      outputFile: `扫榜结果/番茄男频阅读榜_${today}.md`,
+      format: '见 scan-output-format.md',
+    };
+  }
+
+  if (platform === 'jinjiang') {
+    return {
+      platform, length, pcn, lenStr, date: today,
+      action: 'scrape_jinjiang',
+      steps: [
+        { tool: 'browser_navigate', url: 'https://www.jjwxc.net/topten.php?orderstr=12&t=0', label: '晋江金榜' },
+        { tool: 'sleep', seconds: 3 },
+        { tool: 'extract', description: '提取页面书籍列表：排名、书名、作者、收藏数' },
+      ],
+      outputFile: `扫榜结果/晋江金榜_${today}.md`,
+      format: '见 scan-output-format.md',
+    };
+  }
+
+  if (platform === 'zhihu') {
+    const subType = length === 'short' ? '短篇4榜' : '长篇榜';
+    return {
+      platform, length, pcn, lenStr, date: today,
+      action: 'scrape_zhihu',
+      steps: [
+        { tool: 'browser_navigate', url: 'https://www.zhihu.com/fiore/h5/vip-web', label: `知乎${subType}` },
+        { tool: 'sleep', seconds: 3 },
+        { tool: 'extract', description: '提取页面书籍列表' },
+      ],
+      outputFile: `扫榜结果/知乎${subType}_${today}.md`,
+      format: '见 scan-output-format.md',
+    };
+  }
+
+  if (platform === 'dianzhong') {
+    return {
+      platform, length, pcn, lenStr, date: today,
+      action: 'scrape_dianzhong',
+      steps: [
+        { tool: 'browser_navigate', url: 'https://www.tiyi.cn/', label: '点众短篇榜' },
+        { tool: 'sleep', seconds: 3 },
+        { tool: 'extract', description: '提取页面书籍列表' },
+      ],
+      outputFile: `扫榜结果/点众短篇榜_${today}.md`,
+      format: '见 scan-output-format.md',
+    };
+  }
+
+  if (platform === 'qimao') {
+    const gender = length === 'long' ? '男频' : '女频';
+    return {
+      platform, length, pcn, lenStr, date: today,
+      action: 'scrape_qimao',
+      steps: [
+        { tool: 'browser_navigate', url: 'https://www.qimao.com/paihang', label: `七猫${gender}大热榜` },
+        { tool: 'sleep', seconds: 3 },
+        { tool: 'extract', description: '提取页面书籍列表：排名、书名、作者、热度' },
+      ],
+      outputFile: `扫榜结果/七猫${gender}大热榜_${today}.md`,
+      format: '见 scan-output-format.md',
+    };
+  }
+
+  return { error: `未知平台: ${platform}` };
+}
+
+// ---------------------------------------------------------------------------
+// 扫榜报告生成
+// ---------------------------------------------------------------------------
+
+function generateReport(platform, length, scanFiles, outDir) {
+  const today = todayStr();
+  const pcn = PLATFORM_CN[platform] || platform;
+  const lenStr = length === 'long' ? '长篇' : '短篇';
+
+  // 读取原始数据文件
+  const books = [];
+  for (const f of scanFiles) {
+    if (!existsSync(f)) continue;
+    const content = readFileSync(f, 'utf-8');
+    // 简单解析 Markdown 中的 ## #N 书名 格式
+    const matches = [...content.matchAll(/^## #(\d+) (.+)$/gm)];
+    for (const m of matches) {
+      books.push({ rank: parseInt(m[1]), title: m[2].trim() });
+    }
+  }
+
+  const report = [
+    `# ${pcn}${lenStr}扫榜报告：${today}`,
+    '',
+    '## 市场概况',
+    `- 扫榜时间：${today}`,
+    `- 核心发现：${books.length > 0 ? `共采集 ${books.length} 本上榜作品` : '（数据采集中）'}`,
+    '',
+    '## 题材热度排行',
+    '- （从原始数据分析提取）',
+    '',
+    '## 新题材信号',
+    '- （从原始数据分析提取）',
+    '',
+    '## 关键数据洞察',
+    `- 字数区间：（待分析）`,
+    `- 书名特征：（待分析）`,
+    '',
+    '## 值得关注的方向',
+    '1. （待从榜单提取后填入）',
+    '',
+    '## 一句话',
+    '（待分析后填入）',
+  ].join('\n');
+
+  const reportFile = join(outDir, `${pcn}${lenStr}扫榜报告_${today}.md`);
+  writeFileSync(reportFile, report, 'utf-8');
+  console.log(`  ✅ 扫榜报告 → ${reportFile}`);
+  return reportFile;
+}
+
+// ---------------------------------------------------------------------------
+// topic_decision 追加
+// ---------------------------------------------------------------------------
+
+function appendTopicDecision(platform, length, reportFile, outDir) {
+  const today = todayStr();
+  const pcn = PLATFORM_CN[platform] || platform;
+  const lenStr = length === 'long' ? '长篇' : '短篇';
+
+  const section = [
+    `## ${pcn}（${lenStr}）推荐选题`,
+    `- 扫榜日期：${today}`,
+    `- 数据来源：${reportFile}`,
+    '',
+    '### 选题 1：（待从报告提取）',
+    '- 题材组合：（待填入）',
+    '- 目标读者：（待填入）',
+    '- 核心卖点：（待填入）',
+    '- 能爆的原因：（待填入）',
+    '- 差异化定位：（待填入）',
+    '- 可行性：高/中/低 — （待评估）',
+    '- 失败风险：（待评估）',
+    '- 验证动作：（待填入）',
+    '- 篇幅/平台：（待填入）',
+  ].join('\n');
+
+  const decisionFile = join(outDir, `topic_decision_${today}.md`);
+  const sep = existsSync(decisionFile) ? '\n\n---\n\n' : '';
+
+  if (existsSync(decisionFile)) {
+    writeFileSync(decisionFile, readFileSync(decisionFile, 'utf-8') + sep + section + '\n', 'utf-8');
+  } else {
+    const header = `# 选题决策：${today}\n\n---\n\n`;
+    writeFileSync(decisionFile, header + section + '\n', 'utf-8');
+  }
+  console.log(`  ✅ topic_decision 追加 → ${decisionFile}`);
+  return decisionFile;
+}
+
+// ---------------------------------------------------------------------------
+// 主流程
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = process.argv.slice(2);
+  let projectRoot = '', platform = '', length = '';
+
+  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] === '--length') length = args[i + 1] || '';
+  }
+
+  if (!projectRoot || !platform || !length) {
+    console.error('缺少必要参数: --project-root --platform --length');
+    process.exit(1);
+  }
+
+  // 检查 .fancy-deployed
+  if (!existsSync(join(projectRoot, '.fancy-deployed'))) {
+    console.error('项目未初始化：.fancy-deployed 不存在');
+    process.exit(1);
+  }
+
+  // 验证平台×篇幅
+  if (!VALID_PLATFORMS.includes(platform)) {
+    console.error(`不支持的平台: ${platform}`);
+    process.exit(1);
+  }
+  if (!VALID_LENGTHS.includes(length)) {
+    console.error(`不支持的篇幅: ${length}`);
+    process.exit(1);
+  }
+  if (!PLATFORM_SUPPORTED_LENGTHS[platform].includes(length)) {
+    console.error(`${platform} 不支持 ${length}`);
+    process.exit(1);
+  }
+
+  const today = todayStr();
+  const scanDir = join(projectRoot, '扫榜结果');
+  ensureDir(scanDir);
+
+  let scanFiles = [];
+  let scrapeFiles = [];
+
+  if (platform === 'qidian') {
+    // 起点：HTTP mobile SSR
+    console.log('→ 采集 起点（mobile SSR）...');
+    scrapeFiles = await scrapeQidian(scanDir);
+    if (!scrapeFiles.length) {
+      console.error('  ❌ 起点采集失败');
+      process.exit(1);
+    }
+    scanFiles = scrapeFiles.map(f => f.file);
+  } else {
+    // 其他平台：browser_* 工具（LLM 读取指令文件后执行）
+    console.log(`→ ${PLATFORM_CN[platform]}（browser_* 工具）...`);
+    const { file, instructions } = scrapeBrowserStub(platform, length, scanDir);
+    scrapeFiles.push({ file });
+    scanFiles.push(file);
+
+    // 输出指令供 LLM 读取
+    console.log('\n=== 浏览器采集指令 ===');
+    console.log(JSON.stringify(instructions, null, 2));
+    console.log('=== 浏览器采集指令 END ===\n');
+  }
+
+  // 生成扫榜报告
+  const mdFiles = scanFiles.filter(f => f.endsWith('.md') && !f.includes('扫榜报告') && !f.includes('topic_decision'));
+  const reportFile = generateReport(platform, length, mdFiles, scanDir);
+  appendTopicDecision(platform, length, reportFile, scanDir);
+
+  const receipt = {
+    ok: true,
+    operation: 'scan',
+    platform,
+    length,
+    date: today,
+    scan_files: scanFiles,
+    report_file: reportFile,
+    topic_decision: join(scanDir, `topic_decision_${today}.md`),
+    summary: `${PLATFORM_CN[platform]}（${length}）采集完成，共 ${scanFiles.length} 个文件`,
+  };
+
+  console.log('\n=== RECEIPT ===');
+  console.log(JSON.stringify(receipt, null, 2));
+}
+
+main().catch(e => {
+  console.error('Fatal:', e);
+  process.exit(1);
+});

package/plugins/fancy-scan/scripts/scan-output-format.md

@@ -0,0 +1,207 @@
+# 扫榜数据采集格式规范
+定义起点/番茄/七猫/晋江的采集字段、输出模板和清洗规则。
+
+---
+
+## 起点
+
+### 起点采集说明
+
+榜单清单与 URL 见 SKILL.md「起点采集目标」表。
+
+优先使用 `scripts/qidian-rank-scraper.js` 的默认 `--mode auto`。脚本先读取 `https://m.qidian.com` 移动端 SSR pageContext JSON，规避 PC 站风控页；移动端不可用时才回退到 CDP/PC 页面。输出头部会标注 `抓取方式：mobile-ssr` 或 `cdp-pc`。
+
+
+### 字段
+
+排名 | 书名 | 作者 | 题材 | 状态 | 签约 | 收费模式 | 字数(万字) | 总推荐 | 标签(详情页) | 最新更新(详情页) | 作品页链接 | 简介(详情页，截断100字)
+
+### 输出模板
+
+```markdown
+# qidian · {榜单名称}
+- 来源：{榜单URL}
+- 抓取时间：{ISO 8601}
+- 条目数：{N}
+
+---
+
+## #{排名} {书名}
+*{作者} · {题材} · {状态} · {签约} · {免费/VIP} · {字数}万字 · {推荐数}总推荐*
+**标签：** {标签}
+**最新更新：** {YYYY-MM-DD HH:MM:SS} · {章节标题}
+
+[作品页]({URL})
+
+**简介**
+{简介原文}
+```
+
+### 采集要点
+
+榜单页含：排名/书名/作者/题材/字数/推荐/签约/免费VIP。详情页需：标签/最新更新/简介。三江按周分组。
+
+---
+
+## 番茄小说
+
+榜单 URL 格式与参数说明见 SKILL.md「番茄采集目标」表。
+
+### 题材cat_id
+
+男频19个：西方奇幻(1141) / 东方仙侠(1140) / 科幻末世(8) / 都市日常(261) / 都市修真(124) / 都市高武(1014) / 历史古代(273) / 战神赘婿(27) / 都市种田(263) / 传统玄幻(258) / 历史脑洞(272) / 悬疑脑洞(539) / 都市脑洞(262) / 玄幻脑洞(257) / 悬疑灵异(751) / 抗战谍战(504) / 游戏体育(746) / 动漫衍生(718) / 男频衍生(1016)
+
+女频18个：古风世情(1139) / 科幻末世(8) / 游戏体育(746) / 女频衍生(1015) / 玄幻言情(248) / 种田(23) / 年代(79) / 现言脑洞(267) / 宫斗宅斗(246) / 悬疑脑洞(539) / 古言脑洞(253) / 快穿(24) / 青春甜宠(749) / 星光璀璨(745) / 女频悬疑(747) / 职场婚恋(750) / 豪门总裁(748) / 民国言情(1017)
+
+### 字段
+
+排名 | 书名(需详情页解码) | 作者(需详情页解码) | 题材(详情页 categoryV2) | 状态 | 在读(核心指标) | 字数 | 标签(简介内【】) | 最新更新 | bookId | 作品页链接 | 简介(截断100字)
+
+> 番茄 SSR 详情页**没有数字评分**，故不输出评分。题材取详情页 `categoryV2`（转义 JSON 的首个 `Name`，如「西方奇幻」）；标签取简介开头的 `【tag+tag+...】`（如「种田、慢热、西幻」），是题材细分的真实信号。
+
+### 输出模板
+
+```markdown
+# 番茄 · {频道}{榜单名} · 全 {N} 题材
+- 频道参数：channel={0女频/1男频}，type={1新书榜/2阅读榜}
+- 抓取时间：{ISO 8601}
+- 标题解析：成功 {X} / 共 {Y}
+- 数据质量：[OK / 标题解析异常 / 无数据]
+- 每题材上限 ≈ {N}（cap≈20）
+
+---
+
+## {题材名称} — {N} 本
+
+### #{排名} {书名}
+*{作者} · {题材} · {状态} · {在读数} 在读 · {字数}字*
+**标签：** {标签1、标签2}
+**最新更新：** {章节}
+**bookId：** {bookId}
+
+[作品页]({URL})
+
+**简介**
+{简介原文}
+```
+
+> 标题/作者/题材/标签/简介均为可选字段：详情页拿到才输出。书名解码失败时书名显示 `（标题待解析）`，但 bookId 与作品页链接始终保留，便于人工回查。
+
+### 采集要点
+
+字体反爬：列表页 innerText 被自定义字体混淆，`scripts/fanqie-rank-scraper.js` 改从详情页 HTML（内嵌 JSON `bookName`/`author`/`abstract`/`categoryV2` + `<title>` + og:meta）多策略解码明文，规避字体反爬。流程：访问品类页 → 提取品类链接 → 逐品类取 `__INITIAL_STATE__` 列表 → 分批（每 5 本）请求详情页解码。单页上限约 20 本需滚动加载；`--top N` 可调每题材上限。
+
+**故障排查（书名全是 `bookId:xxx` / `（标题待解析）`）**：
+- 看文件头 `数据质量`：标 `[标题解析异常]` 说明详情页解码失败率高。
+- 多为详情页结构变动或被登录/验证页拦截。在已登录的 Chrome 里手动打开任一 `https://fanqienovel.com/page/{bookId}` 确认页面正常、非验证页。
+- 控制台若报 `CDP 无响应`，说明 Chrome/CDP 没起来或端口不对，按 browser-cdp skill 重新启动。确认正常后重采。
+
+---
+
+## 七猫
+
+### 榜单
+
+入口：qimao.com/paihang，男生榜/女生榜tab切换。类型：大热榜(日/月) / 新书榜 / 完结榜 / 收藏榜 / 更新榜
+
+### 字段
+
+排名 | 书名 | 作者 | 题材 | 分类标签 | 状态 | 字数(万字) | 热度(核心指标) | 最新更新 | 作品页链接 | 简介(截断100字)
+
+### 输出模板
+
+```markdown
+# 七猫 · {男/女}频 · {榜单名称}
+- 来源：qimao.com/paihang
+- 抓取时间：{ISO 8601}
+- 条目数：{N}
+
+---
+
+### #{排名} {书名}
+*{作者} · {题材} · {分类标签} · {状态} · {字数}万字 · {热度}万热度*
+**最新更新：** {时间} · {章节}
+
+[作品页]({URL})
+
+**简介**
+{简介原文}
+```
+
+### 采集要点
+
+无明显反爬需滚动加载。男生榜/女生榜tab切换，大热榜有日/月切换。
+
+---
+
+## 晋江
+
+### 榜单URL
+
+`jjwxc.net/topten.php?orderstr={榜单ID}&t={频道ID}`（t=0全站，各频道ID从页面获取）
+
+| 榜单 | orderstr |
+|------|----------|
+| 收入金榜 | 12 |
+| 月榜 | 7 |
+| 季度榜 | 8 |
+| 完结金榜 | 14 |
+| 新手金榜 | 15 |
+| 千字金榜 | 17 |
+
+### 字段
+
+频道 | 排名 | 书名 | 作者 | novelid | 收藏数(核心) | 营养液 | 积分 | 字数 | 状态 | 作品页链接
+
+### 输出模板
+
+```markdown
+# 晋江 · {榜单名}
+- 来源：{topten URL}
+- 抓取时间：{ISO 8601}
+- 频道数：{N} / 总条目数：{M}
+- 详情采集：{命中收藏数} / {计划数}（每频道前 {top}，上限 {limit}）
+- 数据质量：[OK / 详情解析异常·登录态缺失 / 仅列表-无核心指标]
+
+---
+
+## {频道名} — {N} 本
+
+### #{排名} {书名}
+*{作者} · 收藏 {X} · 营养液 {Y} · 积分 {Z} · 字数 {W}字 · {状态}*
+[作品页](https://www.jjwxc.net/onebook.php?novelid={id})
+```
+
+### 采集要点
+
+两步：① 列表页 `topten.php` 取频道分组 + 书名/作者，从书名 anchor 取 `novelid`（排除"X向《书名》投了Y"霸王票记录）；② 进 `onebook.php?novelid=` 详情页补采核心指标。
+- **编码**：晋江是 gb18030，详情页必须 `fetch+arrayBuffer+TextDecoder('gb18030')` 解码（同步 XHR 的 responseText 按 UTF-8 解码会乱码）。
+- **字段来源**：详情页 `itemprop` 微数据——`collectedCount`(收藏)/`nutritionCount`(营养液)/`scoreCount`(积分)/`wordCount`(字数)/`updataStatus`(状态)。这些是公开指标，**无需登录**。
+- **控量**：列表全量保留，仅每频道前 `--top` 本（受 `--detail-limit` 总量约束）补详情，避免对全站数百本逐一请求。
+
+---
+
+## 数据清洗
+
+通用：移除平台模板文本→简介超100字在句号处截断加`...`→空值标`[待补]`
+
+| 平台 | 额外必填 |
+|------|----------|
+| 起点 | 题材、字数、总推荐 |
+| 番茄 | 在读数 |
+| 七猫 | 热度 |
+| 晋江 | 收藏数、营养液(或积分)、字数 |
+
+最低采集量：主流平台15条，小平台10条。低于底线标`[数据稀疏]`。
+
+---
+
+## 批量采集
+
+| 平台 | 默认组合 |
+|------|----------|
+| 起点 | 新人签约新书榜+签约作者新书榜前20+月票榜前20+畅销榜前20 |
+| 番茄 | 男频阅读榜全题材+女频阅读榜全题材 |
+| 七猫 | 男频大热榜日榜+女频大热榜日榜 |
+| 晋江 | 收入金榜+月榜 |
+| 全平台 | 起点+番茄+七猫默认组合 |