@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

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

@@ -18,10 +18,11 @@
  */
 
 import fs from 'fs';
+import { atomicWriteFile } from '#atomic-write';
 import path from 'path';
 import { pathToFileURL } from 'url';
 import { chromium } from 'playwright-core';
-import { getArg, localDateStamp, runCli } from '#scraper-utils';
+import { getArg, localDateStamp, runCli, renderIntroLines, sanitizeBookFields, stripThousands } from '#scraper-utils';
 
 const BASE_URL = "https://www.jjwxc.net/topten.php";
 
@@ -33,9 +34,66 @@ const RANK_TYPES = [
 ];
 
 const DETAIL_CHUNK = 6;
-const DETAIL_LIMIT = 100;
+const DETAIL_LIMIT = 300;
 const TOP = 10;
 
+// ---------------------------------------------------------------------------
+// 详情页解析（Node 侧纯函数，可被单元测试直接调用）
+// ---------------------------------------------------------------------------
+
+/**
+ * HTML 片段 → 纯文本。
+ *
+ * 晋江的"文案"是多段的，段间是 `<br>`（不是 `<p>`），要转成换行才能读。
+ * 页面里还有 `&nbsp;`（晋江排版大量用它），不清掉会到处是空白。
+ */
+export function htmlToText(html) {
+  return String(html || '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * 从详情页 HTML 里解析**简介**和**内容标签**。
+ *
+ * 简介：`<div id="novelintro" itemprop="description">…</div>`
+ *   文案有多段，段间是 `<br>`（见 htmlToText）。
+ *
+ * 内容标签：`<a href="//www.jjwxc.net/bookbase.php?bq=32">宫廷侯爵</a>`
+ *   —— 整页里只有这些链接指向 bookbase。实测 12/12 本，
+ *   **bq 链接数 == 标签数**（3~6 个/本），不会混进别的东西。
+ *
+ * 标签是**平台官方内容标签**，题材与元素套路混在一起
+ * （如 都市 / 破镜重圆 / 天之骄子 / 高岭之花 / 暗恋），
+ * 且**没有"主分类"概念** —— 这点与番茄不同（番茄第一个标签是主分类）。
+ */
+export function parseNovelDetail(html) {
+  const out = { intro: '', tags: [] };
+  const m = String(html || '').match(/<div[^>]*id="novelintro"[^>]*>([\s\S]*?)<\/div>/i);
+  if (m) out.intro = htmlToText(m[1]);
+
+  const tags = [];
+  const re = /<a[^>]*href=["'][^"']*bookbase\.php\?bq=\d+[^"']*["'][^>]*>([^<]{1,30})<\/a>/gi;
+  let t;
+  while ((t = re.exec(String(html || ''))) !== null) {
+    const name = htmlToText(t[1]);
+    if (name && !tags.includes(name)) tags.push(name);
+  }
+  out.tags = tags;
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // 命令行参数解析
 // ---------------------------------------------------------------------------
@@ -76,14 +134,18 @@ async function extractRankData(page) {
         var typeCell = cells[3];
         var statusCell = cells[4];
         var wordsCell = cells[5];
-        var scoreCell = cells[6];
+        var scoreCell = cells[6] || null;
 
         var author = (authorCell.innerText || '').trim();
         var title = (titleCell.innerText || '').trim();
         var type = (typeCell.innerText || '').trim();
         var status = (statusCell.innerText || '').trim();
         var words = (wordsCell.innerText || '').trim();
-        var score = (scoreCell.innerText || '').trim();
+        // 积分列（第 7 列）可能整列缺失 —— 榜单页偶尔只有 6 列。
+        // 之前直接取 cells[6].innerText 会抛 TypeError，
+        // page.evaluate 整体 reject → 整榜不落盘。
+        // 缺积分的书照样收，积分留空。
+        var score = scoreCell ? (scoreCell.innerText || '').trim() : '';
 
         // 排除标题行
         if (author === '作者' || title === '作品') continue;
@@ -112,49 +174,72 @@ async function extractRankData(page) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// 单本书的字段渲染（纯函数，可被单元测试直接调用）
+// ---------------------------------------------------------------------------
+
+/**
+ * 一本书 → markdown 字段行（不含 `### #N 书名` 标题行）。
+ *
+ * 抽出来是为了能单测这两条格式规则 —— 它们原本埋在 scrapeRank 的
+ * async 函数里，测不到：
+ *
+ *   1. **积分不带千分位逗号**：晋江榜单页写的是 "1,099,899,136"，
+ *      存成纯数字，下游才好比较/求和，模型抄数字时也不会把逗号抄进去
+ *      （"327,650,784" 和 "327650784" 在模型的算术里不是一回事）；
+ *   2. **简介是 `- ` 列表项**：单换行用硬换行保留，空行才是段落分隔；
+ *      每段首尾无空白，作品页也单独作为一个列表项。
+ *
+ * @param {object} b - 一本书
+ * @returns {string[]} markdown 行
+ */
+export function renderBookLines(raw) {
+  const b = sanitizeBookFields(raw);
+  const lines = [];
+  if (b.author) lines.push(`- **作者：** ${b.author}`);
+  if (b.type) lines.push(`- **题材：** ${b.type}`);
+  if (b.status) lines.push(`- **状态：** ${b.status}`);
+  if (b.words) lines.push(`- **字数：** ${stripThousands(b.words)}`);
+  // 积分是 10 亿级的，榜单页必带千分位逗号 —— 写盘前去掉。
+  if (b.score) lines.push(`- **积分：** ${stripThousands(b.score)}`);
+  if (b.tags && b.tags.length) lines.push(`- **标签：** ${b.tags.join('、')}`);
+  // 简介和其他字段一样是 `- ` 列表项；单换行用硬换行，空行才是段落分隔。
+  // 之前是「空行 + `**简介**` + 简介整块」—— 没有冒号，且和上下文粘成一段，
+  // 而且简介首尾的空白字符原样留在文件里。
+  lines.push(...renderIntroLines(b.intro || ''));
+  if (b.novelid) lines.push(`- [作品页](https://www.jjwxc.net/onebook.php?novelid=${b.novelid})`);
+  return lines;
+}
+
 // ---------------------------------------------------------------------------
 // 详情页提取（gb18030 + itemprop 微数据）
 // ---------------------------------------------------------------------------
 
 async function fetchDetails(page, ids) {
-  // 使用 Playwright 的 page.evaluate 来执行详情页抓取
-  const details = await page.evaluate(async (ids) => {
-    const results = [];
-    for (const id of ids) {
-      try {
-        // redirect: 'error' 防止 onebook.php 重定向到外站造成 SSRF
-        const response = await fetch(`/onebook.php?novelid=${id}`, { redirect: 'error' });
-        const buffer = await response.arrayBuffer();
-        const decoder = new TextDecoder('gb18030');
-        const html = decoder.decode(buffer);
-
-        function prop(name) {
-          const m = html.match(new RegExp(`itemprop="${name}"[^>]*>([^<]*) <`));
-          return m ? m[1].trim() : '';
+  // 分块抓：一次把 200 本的 HTML 全带过 evaluate 边界会有几十 MB 的
+  // 序列化开销，分块后每块才 1MB 上下。
+  const map = {};
+  for (let i = 0; i < ids.length; i += DETAIL_CHUNK) {
+    const chunk = ids.slice(i, i + DETAIL_CHUNK);
+    // 浏览器侧只负责"把解码后的原始 HTML 拿回来"，
+    // **解析放在 Node 侧**（parseNovelDetail）—— 这样解析逻辑能被单元测试直接调用。
+    const details = await page.evaluate(async (list) => {
+      const results = [];
+      for (const id of list) {
+        try {
+          // redirect: 'error' 防止 onebook.php 重定向到外站造成 SSRF
+          const response = await fetch(`/onebook.php?novelid=${id}`, { redirect: 'error' });
+          const buffer = await response.arrayBuffer();
+          results.push({ id: id, html: new TextDecoder('gb18030').decode(buffer) });
+        } catch (e) {
+          results.push({ id: id, err: String(e) });
         }
-
-        const statusMatch = html.match(/itemprop="updataStatus"[^>]*>\s*([^\s<]{1,6})/) || [];
-        const status = statusMatch[1] || (html.includes('连载中') ? '连载中' : html.includes('已完结') ? '已完结' : '');
-
-        results.push({
-          id: id,
-          collect: prop('collectedCount'),
-          nutrition: prop('nutritionCount'),
-          score: prop('scoreCount'),
-          review: prop('reviewCount'),
-          words: prop('wordCount'),
-          status: status
-        });
-      } catch (e) {
-        results.push({ id: id, err: String(e) });
       }
+      return results;
+    }, chunk);
+    for (const d of details) {
+      map[d.id] = d.err ? { err: d.err } : parseNovelDetail(d.html);
     }
-    return results;
-  }, ids);
-
-  const map = {};
-  for (const d of details) {
-    map[d.id] = d;
   }
   return map;
 }
@@ -174,6 +259,7 @@ async function scrapeRank(browser, rankTypeId, channelId) {
   const chLabel = channelId === "0" ? "全站" : `频道${channelId}`;
 
   const page = await browser.newPage();
+  const partialReasons = [];
 
   try {
     await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
@@ -193,6 +279,36 @@ async function scrapeRank(browser, rankTypeId, channelId) {
       }
     });
     console.error(`  ✓ 列表：${data.channels.length} 个频道，共 ${totalBooks} 本`);
+    // 解析到 0 本 = 页面结构变了 / 选择器失效 / 没加载出来。
+    // extractRankData 永远至少返回一个 `{ name: '全站', books: [] }`，
+    // 所以上面的 `!data.channels.length` 守卫**永远不触发** ——
+    // 结果是写出一个只有 "## 全站 — 0 本" 的空文件，
+    // 上层 `ok: scanFiles.length > 0` 还判定成功，用户拿到空报告。
+    if (totalBooks === 0) {
+      console.error(`❌ 晋江-${rt.label}（${chLabel}）采集失败：页面解析到 0 本书（选择器可能失效或页面未加载）。请人工打开 ${url} 确认。`);
+      return null;
+    }
+
+    // 逐本进详情页补**简介**和**内容标签**（列表页没有这两个字段）。
+    // 此前 fetchDetails 写好了却从没被调用 —— 晋江产出的 md 里因此一直没有
+    // 简介和标签，提示词里"提取简介标签""简介标签"全是空的。
+    const detailIds = [];
+    for (const ch of data.channels) {
+      for (const b of ch.books) {
+        if (b.novelid && !detailIds.includes(b.novelid)) detailIds.push(b.novelid);
+      }
+    }
+    const detailIdsToFetch = detailIds.slice(0, DETAIL_LIMIT);
+    if (detailIds.length > DETAIL_LIMIT) {
+      console.error(`  ⚠ 详情页只采前 ${DETAIL_LIMIT} 本（共 ${detailIds.length} 本），其余没有简介和标签`);
+    }
+    let detailMap = {};
+    if (!LIST_ONLY && detailIdsToFetch.length) {
+      console.error(`  → 采详情页 ${detailIdsToFetch.length} 本（简介 + 内容标签）`);
+      detailMap = await fetchDetails(page, detailIdsToFetch);
+      const okCount = detailIdsToFetch.filter((id) => detailMap[id] && !detailMap[id].err).length;
+      console.error(`  ✓ 详情页：${okCount}/${detailIdsToFetch.length} 本取到`);
+    }
 
     // 构建输出内容
     const now = new Date().toISOString();
@@ -203,22 +319,28 @@ async function scrapeRank(browser, rankTypeId, channelId) {
       `- 抓取时间：${now}`,
       `- 频道数：${data.channels.length}`,
       `- 总条目数：${totalBooks}`,
+      ...(detailIds.length > DETAIL_LIMIT
+        ? [`- 详情覆盖：${DETAIL_LIMIT} / ${detailIds.length}（其余条目没有简介与标签）`]
+        : []),
       "",
       "---",
       "",
     ];
 
+
     for (const ch of data.channels) {
       lines.push(`## ${ch.name} — ${ch.books.length} 本`, "");
       for (let i = 0; i < ch.books.length; i++) {
         const b = ch.books[i];
+        const d = b.novelid ? detailMap[b.novelid] : null;
+        if (d && !d.err) {
+          b.intro = d.intro;
+          b.tags = d.tags;
+        } else if (d && d.err) {
+          partialReasons.push(`详情页取数失败 ${b.novelid}: ${d.err}`);
+        }
         lines.push(`### #${i + 1} ${b.title}`);
-        if (b.author) lines.push(`**作者：** ${b.author}`);
-        if (b.type) lines.push(`**题材：** ${b.type}`);
-        if (b.status) lines.push(`**状态：** ${b.status}`);
-        if (b.words) lines.push(`**字数：** ${b.words}`);
-        if (b.score) lines.push(`**积分：** ${b.score}`);
-        if (b.novelid) lines.push(`[作品页](https://www.jjwxc.net/onebook.php?novelid=${b.novelid})`);
+        lines.push(...renderBookLines(b));
         lines.push("");
       }
       lines.push("---", "");
@@ -226,7 +348,8 @@ async function scrapeRank(browser, rankTypeId, channelId) {
 
     return {
       content: lines.join("\n"),
-      partial: false,
+      partial: partialReasons.length > 0,
+      partialReasons,
     };
   } finally {
     await page.close();
@@ -283,24 +406,31 @@ async function main() {
     for (const rt of rankTypes) {
       for (const ch of channels) {
         try {
+          // rtInfo 必须在**读它的所有地方之前**声明。
+          // 之前它声明在 partialReasons 那个 if 的后面，
+          // 而上面的 if 会先读 rtInfo → TDZ ReferenceError
+          // → 整榜已经采好的 content 被 catch 吞掉、整榜不落盘。
+          // 只要有一本详情页失败就触发，等于"详情页偶发失败 = 整个榜单没了"。
+          const rtInfo = RANK_TYPES.find((r) => r.id === rt);
           const result = await scrapeRank(browser, rt, ch);
           if (!result) {
             failed++;
-            const rtInfo = RANK_TYPES.find((r) => r.id === rt);
             partialReasons.push(`${rtInfo ? rtInfo.label : rt}: no usable data`);
             continue;
           }
           if (result.partial) {
             partial = true;
           }
+          if (result.partialReasons && result.partialReasons.length) {
+            for (const r of result.partialReasons) partialReasons.push(`${rtInfo ? rtInfo.label : rt}: ${r}`);
+          }
 
-          const rtInfo = RANK_TYPES.find((r) => r.id === rt);
           const date = localDateStamp();
           const chLabel = ch === "0" ? "全站" : `频道${ch}`;
           const filename = `晋江${rtInfo.label}_${chLabel}_${date}.md`;
           fs.mkdirSync(OUTDIR, { recursive: true });
           const filepath = path.join(OUTDIR, filename);
-          fs.writeFileSync(filepath, result.content, "utf-8");
+          atomicWriteFile(filepath, result.content);
           written++;
           files.push(filepath);
           console.error(`  ✓ 已保存: ${filepath}`);

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

@@ -14,10 +14,11 @@
  */
 
 import fs from 'fs';
+import { atomicWriteFile } from '#atomic-write';
 import path from 'path';
 import { pathToFileURL } from 'url';
 import { chromium } from 'playwright-core';
-import { getArg, localDateStamp, runCli } from '#scraper-utils';
+import { getArg, localDateStamp, runCli, renderIntroLines, sanitizeBookFields, sanitizeMarkdownInline } from '#scraper-utils';
 
 const RANK_URL = "https://www.qimao.com/paihang";
 
@@ -395,25 +396,22 @@ function renderMarkdown(ch, rt, period, url, books, rawCount, now = new Date().t
     "",
   ];
 
-  for (const b of books) {
+  for (const raw of books) {
+    const b = sanitizeBookFields(raw);
     try {
       lines.push(`### #${b.rank} ${b.title}`);
-      if (b.author) lines.push(`**作者：** ${b.author}`);
-      if (b.genre) lines.push(`**题材：** ${b.genre}`);
-      if (b.subGenre) lines.push(`**子分类：** ${b.subGenre}`);
-      if (b.status) lines.push(`**状态：** ${b.status}`);
-      if (b.words) lines.push(`**字数：** ${b.words}`);
-      if (b.heat) lines.push(`**热度：** ${b.heat}`);
-      if (b.url) lines.push(`[作品页](${b.url})`);
-      const desc = cleanDesc(b.desc);
-      if (desc) {
-        lines.push("");
-        lines.push(`**简介**`);
-        // 详情页的简介是分段的（单换行分隔），markdown 里要空行才算分段
-        const paras = desc.split(/\n+/).map((p) => p.trim()).filter(Boolean);
-        lines.push(paras[0]);
-        for (const p of paras.slice(1)) lines.push("", p);
-      }
+      if (b.author) lines.push(`- **作者：** ${b.author}`);
+      if (b.genre) lines.push(`- **题材：** ${b.genre}`);
+      if (b.subGenre) lines.push(`- **子分类：** ${b.subGenre}`);
+      if (b.status) lines.push(`- **状态：** ${b.status}`);
+      if (b.words) lines.push(`- **字数：** ${b.words}`);
+      if (b.heat) lines.push(`- **热度：** ${b.heat}`);
+      // 简介和其他字段一样是 `- ` 列表项；单换行用硬换行，空行才是段落分隔。
+      // 之前是「空行 + `**简介**` + 分段」—— 没有冒号、前后多一个空行，
+      // 而且段首尾的空白字符原样留在文件里。
+      lines.push(...renderIntroLines(cleanDesc(b.desc)));
+      // 作品页链接放在简介之后，与起点/番茄/晋江产物保持同一字段顺序。
+      if (b.url) lines.push(`- [作品页](${b.url})`);
       lines.push("", "---", "");
     } catch (bookErr) {
       lines.push("", "---", "");
@@ -567,7 +565,27 @@ async function main() {
   }
   try {
     for (const target of targets) {
-      const result = await scrapeRank(browser, target.channel, target.rankType, target.period);
+      // 每个 target 单独兜住异常（2026-10-29 审计）。
+      //
+      // scrapeRank 的主体被自己的 try/catch 包着，普通失败会返回 null；
+      // 但 browser.newPage() / page.close() / fetchDetailIntros 这些在
+      // try 之外，抛出来会**跳出整个 for 循环** ——
+      // 后面所有 target 都不再采集，而用户只看到"采集失败"。
+      let result = null;
+      try {
+        result = await scrapeRank(browser, target.channel, target.rankType, target.period);
+      } catch (e) {
+        const msg = e && e.message ? e.message : String(e);
+        console.error(`  ✗ 七猫-${target.channel}/${target.rankType} 采集异常：${msg}`);
+        partialReasons.push(`${target.channel}/${target.rankType} 采集异常：${msg}`);
+        failed++;
+        // 浏览器已经死了就别再试后面的 target —— 每个都会立刻失败、白烧时间
+        if (browser.isConnected && !browser.isConnected()) {
+          console.error('  ✗ 浏览器已断开，停止剩余榜单的采集');
+          break;
+        }
+        continue;
+      }
       if (!result) {
         failed++;
         continue;
@@ -577,7 +595,7 @@ async function main() {
       const filename = outputFilename(target.channel, target.rankType, target.period, date);
       fs.mkdirSync(OUTDIR, { recursive: true });
       const filepath = path.join(OUTDIR, filename);
-      fs.writeFileSync(filepath, result.content, "utf-8");
+      atomicWriteFile(filepath, result.content);
       written++;
       files.push(filepath);
       // 详情页没取到简介的书：原因进 partialReasons，一路带到插件层的失败清单

package/plugins/fancy-scan/templates/blocks.js

@@ -0,0 +1,155 @@
+/**
+ * blocks.js —— 按平台生成的提示词**动态段落**
+ *
+ * 这些段落依赖平台的数据形态（平铺 / 分组）、热度指标与标签来源，
+ * 不能写死在静态提示词里。它们只负责**拼文本**，不做任何校验 ——
+ * 校验在 scripts/report-validate.js 与 scripts/append-block.js 里。
+ *
+ * 静态的任务契约在 prompts/01-analysis-prompt.md；
+ * 本文件生成的内容通过 `${...}` 占位符注入。
+ */
+
+/**
+ * 3.2 的「数据形态」段 —— **按平台说**（评审 P0-1）。
+ *
+ * 以前四个平台统一写成"题材组"，起点/七猫实际是平铺的。
+ */
+export function dataShapeBlock(ds) {
+  if (ds.grouped && ds.genreFrom === 'group') {
+    return [
+      `- **数据形态**：文件按**题材分组** —— 每个 \`${ds.groupTitle}\` 是一个题材组，`,
+      `  组里每本书一个 \`${ds.bookHeading}\`。`,
+      `  **这是分层样本，不是全市场随机样本**：每组本数相同。`,
+    ];
+  }
+  if (ds.grouped) {
+    return [
+      `- **数据形态**：文件按**频道分组**（${ds.groupTitle}）—— 频道是榜单范围，**不是题材**。`,
+      `  每个 \`${ds.bookHeading}\` 是一本书；题材取自每本书自己的 \`${ds.genreField}\` 字段。`,
+      `  这是**完整频道榜**，不是"每题材前 N 本"的分层样本；各题材样本量可能不均。`,
+    ];
+  }
+  return [
+    `- **数据形态**：文件是**平铺的书目列表** —— 每个 \`${ds.bookHeading}\` 就是**一本书**，`,
+    `  **不是题材组**。文件里**没有** \`## 某题材 — N 本\` 这样的分组标题。`,
+    `  **书名永远不是题材名** —— \`#1 玄鉴仙族\` 里的"玄鉴仙族"是书名。`,
+  ];
+}
+
+/**
+ * 3.3 的「题材口径」段 —— 分组平台 vs 字段平台。
+ */
+export function genreRuleBlock(ds, multiList = false) {
+  if (ds.genreFrom === 'group') {
+    return [
+      `- **题材以数据文件里的官方分组为准**（${ds.groupTitle} 里的题材名就是平台给的题材），`,
+      `  **不要另造题材分类** —— 自造分类与采集端的分组不一致，题材频次会失真。`,
+      `  统计题材频次时**只算具体的题材组、跳过"全部"**，否则同一本书会被数两遍、占比加起来超过 100%。`,
+      `  同一本书只归入它所在的**那一个**官方题材。`,
+    ];
+  }
+  return [
+    `- **题材取自每本书自己的 \`${ds.genreField}\` 字段**（如 \`${ds.genreExample}\`），`,
+    `  **不是**从标题推断的 —— 标题里只有书名。`,
+    ...(ds.grouped ? [
+      `  **频道/分组标题只是榜单范围，不是题材** —— 不要把"全站"之类当题材。`,
+    ] : []),
+    `  **不要另造题材分类**：自造分类与采集端给的题材值不一致，题材频次会失真。`,
+    ...(multiList ? [
+      `  同一本书在多个榜单里出现时，**它的题材字段应当一致**；若发现不一致，`,
+      `  在"一、数据与方法"里写明你采信了哪一个、为什么。`,
+    ] : []),
+    `  **子分类只作细分**，主表按大类聚合（细分可能有几十个、每个只有 1-2 本）。`,
+  ];
+}
+
+/**
+ * 3.2 的「标签」规则 —— 没有官方标签字段的平台**不做标签频次**（评审 P0-4）。
+ *
+ * 实测（起点 2026-10-29）：9 个文件 0 个 `**标签：**`，
+ * 简介里的 `【…】` 有出版说明（`【本作品简体实体书由次元书馆出版】`）、
+ * 营销语（`【均订2万，放心追看！】`），分隔符也不是 `+` 而是 `、`。
+ * 照旧规则统计，会把"均订2万"算成标签。
+ */
+export function tagRuleBlock(ds) {
+  if (ds.hasTags) {
+    return [
+      `  - **标签**：用 \`**标签：**\` 行（平台官方分类，比从简介猜准）；`,
+      `    那一行没有就记"无标签"，**不要根据书名猜标签**`,
+    ];
+  }
+  return [
+    `  - **标签**：本平台的数据文件里**没有** \`**标签：**\` 字段 ——`,
+    `    **不要做标签频次分析**（没有数据源）。`,
+    `    如果确实要用简介里的 \`【…】\`，那只算**推断**，且必须：`,
+    `    - 只认**用 \`、\` 或 \`，\` 分隔**的标签串（多个 \`【】\` 要逐个看）；`,
+    `    - \`【本作品简体实体书由…出版】\`、\`【均订2万，放心追看！】\` 这类是**说明/营销语**，不是标签；`,
+    `    - **标注"推断"**并报出覆盖率（如"X/N 本出现可识别的标签串"）；`,
+    `    - 覆盖率太低就**直接删掉标签这一项分析**，不要硬凑`,
+  ];
+}
+
+/**
+ * 3.3 的「竞争度指标」段 —— 样本形态 + 指标口径 + 高/中/低阈值。
+ *
+ * - P0-2：平铺数据的样本量极不均匀，"前 3 ÷ 总量"在 1-3 本的题材上恒为 1.000；
+ * - P1-3：高/中/低必须有阈值，否则不同日期的报告不可比；
+ * - P1-4：同质化必须"与众数比"，两两比会恒为 100%。
+ */
+export function competitionBlock(ds, h, multiList = false) {
+  const sampleNote = ds.stratified
+    ? [
+        `  这份数据是"每题材前 N 本"的分层样本，**每组本数相同**，`,
+        `  因此"书目数占比"和"头部集中度（前 N ÷ N）"在这种数据上**恒等于常数、没有区分度**：`,
+        `  **不要拿它们当指标**（这类表在所有题材上并列，得不出差异）。`,
+      ]
+    : [
+        `  这份数据是**榜单样本**，**各题材的样本量极不均匀**`,
+        `  （同一次扫榜里，有的题材有 20 本，有的只有 1 本）。`,
+        `  **样本量不均的直接后果**：`,
+        `  - 只有 1-3 本的题材，"前 3 名 ÷ 总量"恒等于 1.000、"中位数"就是那一本的值 —— **没有区分度**；`,
+        ...(multiList ? [
+          `  - 某题材出现在**越多榜单**里，它的书目数与${h.label}总量就机械性越大 ——`,
+          `    这是**榜单选择偏差**，不是市场需求，**不能**读成"某题材需求是另一个的 N 倍"。`,
+        ] : []),
+      ];
+  const shareName = ds.grouped ? '需求份额' : '样本内份额';
+  const shareFormula = ds.grouped
+    ? `  - **${shareName}** = 该题材${h.label}总量 ÷ 全部题材${h.label}总量（给出百分比）`
+    : `  - **${shareName}** = 该题材${h.label}总量 ÷ **样本内**全部题材${h.label}总量（给出百分比）；`;
+  return [
+    `- **竞争度指标（5 项）—— 按下面的口径算，不要凭感觉打分**：`,
+    ...sampleNote,
+    `  **每个指标都要带样本量**，并按样本量分档：`,
+    `  - **样本量 ≥5 本** → 正常打分（高/中/低）；`,
+    `  - **3-4 本** → 头部集中度 / 同质化程度可写数值或“只描述”，差异化空间写“只描述”；上述三项都不打高/中/低；`,
+    `  - **<3 本** → 头部集中度 / 同质化程度 / 差异化空间三项标“样本不足”，这三项不参与排序；`,
+    `  - **份额列不受样本量分档影响**：始终按总量算百分比（可带高/中/低档），样本不足只影响其余三项打分。`,
+    `  **改用${h.label}数据**：`,
+    `  - **需求规模** = 该题材**有${h.label}值的书**的总量，并给出**均值**、**中位数**与**样本量**`,
+    ...(ds.grouped
+      ? [shareFormula]
+      : [shareFormula,
+         `    **这是榜单样本内部的份额，不是市场份额** —— 报告里要写"样本内份额"，不许简写成"份额"`]),
+    `  - **头部集中度** = 该题材**前 3 名**${h.label}之和 ÷ 该题材${h.label}总量`,
+    `  - **同质化程度** = 该题材里，与**该题材众数组合**在`,
+    `    "金手指 / 主角身份 / **简介核心冲突**"三项中**至少两项一致**的书目数 ÷ N`,
+    `    （只一致一项或零项 → 计 0）。`,
+    `    **是"与众数比"，不是"两两比"** —— 两两比的话几乎每本都能找到同类，结果恒为 100%。`,
+    `    **先定编码规则再统计**：同一维度里机制相近的归一类（如"系统/签到/模拟器/游戏面板"算一类），`,
+    `    差别大的分开算；在"一、数据与方法"里把你用的类别列出来，并写出**众数组合**与**匹配本数**`,
+    `    （"简介核心冲突"的类别自定，但要在方法节写清，如 复仇/生存/争霸/日常经营/探案规则/恋爱/其他）`,
+    `  - **差异化空间** = 该题材**还没被满足**的读者需求。`,
+    `    **数据里没有评论，也没有第一章** —— 只能从**简介标签、核心卖点、同题材书目的空白处**推断，`,
+    `    **必须标注"推断"**；不许声称知道评论里说什么`,
+    `  **高/中/低必须用统一阈值**（每次凭感觉的话，不同日期的报告没法比）：`,
+    `  - **${shareName} / 需求规模**：用**本次快照内的分位数** —— 前 ⌊n/3⌋ 个为高、后 ⌊n/3⌋ 个为低、其余为中`,
+    `    （n 是题材数；n<3 时不分档。份额列**必须写百分比**，不能写成"3 本仅描述"）`,
+    `  - **头部集中度**：≥0.8 高 / 0.5-0.8 中 / <0.5 低；**<3 本的题材标"样本不足"，3-4 本只描述、不打分**。`,
+    `    表里写 **0–1 的小数**（0.56、0.4286），不要写百分比`,
+    `  - **同质化程度**：≥0.7 高 / 0.4-0.7 中 / <0.4 低（前提是先定好编码类别）；同样写 0–1 的小数`,
+    `  - **差异化空间**：3 级 rubric —— **高** = 题材内 ≥3 本共享同一组合、且至少 2 个合理组合缺席；`,
+    `    **中** = 有主导组合但仍有可见变体空间；**低** = 头部书已覆盖多种组合；`,
+    `    3-4 本只描述、不打分；<3 本标“样本不足”`,
+  ];
+}