@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

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

@@ -0,0 +1,372 @@
+/**
+ * platforms.js —— 平台/榜单/热度指标/数据形态的**单一事实来源**
+ *
+ * 这些表同时被三处使用：
+ *   1. 提示词渲染（templates.js）：平台名、榜单名、指标名、数据形态；
+ *   2. 采集编排（index.js / run-scan.js）：榜单 id 与 path；
+ *   3. 报告校验（templates/report-schema.js）：题材来源、表头口径。
+ *
+ * 以前它们散在 templates.js 里，提示词和脚本各写一份时必然漂移。
+ * 现在只定义一次，所有地方从这里取。
+ */
+import { SCAN_MODE_API, SCAN_MODE_OCR } from '#scraper-utils';
+
+export const PLATFORM_TABLE = [
+  ['1', 'qidian',  '起点'],
+  ['2', 'fanqie',  '番茄'],
+  ['3', 'jinjiang','晋江'],
+  ['4', 'qimao',   '七猫'],
+];
+
+/**
+ * 各平台的**热度指标**（2026-10-28）
+ *
+ * ## 为什么要按平台区分
+ *
+ * 每个平台衡量"这本书有多火"用的**指标根本不同**，数值之间不可比：
+ *
+ *   · 起点 —— **月票**（`monthTicket`，精确整数，实测 130343）
+ *   · 番茄 —— **在读**（`60.2万`）
+ *   · 晋江 —— **积分**（`1053978496`，采集文件里不带千分位逗号）
+ *   · 七猫 —— **热度**（`3853.8万`）
+ *
+ * 之前提示词里写死"在读"，那么起点/晋江/七猫的数据就**没法算需求规模**
+ * —— 起点压根没有"在读"这个字段（起点此前连热度指标都没有，
+ * 2026-10-28 才补上月票）。
+ *
+ * ## 量纲也要说清
+ *
+ * 四个指标的数量级差几个数量级（月票 13 万 vs 晋江积分 10 亿），
+ * **只能在本平台内部横向比较**，不能跨平台比大小。
+ * 所以计算口径一律是"本平台内各题材的占比/均值/中位数"。
+ *
+ * ## 主指标 vs 辅助指标
+ *
+ * 每个平台有一个**主指标**（`label`）—— 需求规模/需求份额/头部集中度
+ * 三项公式都用它。起点额外有**辅助指标**（`aux`）：
+ * 总推荐 / 周推荐 / 打赏。
+ *
+ * 辅助指标**只作交叉验证，不进那三项公式** —— 它们的口径和量级都不同：
+ * 总推荐是开书至今的**历史累计**（老书天然占优），周推荐是**周增量**，
+ * 打赏是**次数不是金额**。实测对照（2026-10-28 月票榜）：
+ *
+ *   · 夜无疆   月票 123406 / 总推荐 12531500 / 周推荐 41826 / 打赏 今日 19
+ *     → 老书盘子大，但本周打赏很淡
+ *   · 武道！   月票 96884 / 总推荐 162880 / 周推荐 4765 / 打赏 今日 3
+ *     → 新书起量（月票高、总推荐还很小）
+ *   · 玄鉴仙族 月票 132564 / 总推荐 7059484 / 周推荐 34655 / 打赏 今日 352
+ *     → 打赏远高于同榜其它书，付费黏性明显
+ *
+ * 把它们相加或互相代入占比，得出的数没有任何意义。
+ */
+export const HEAT_METRIC = {
+  qidian: {
+    field: '月票',
+    label: '月票',
+    unit: '张',
+    note: '精确整数，取自作品详情页的 monthTicket',
+    sample: '月票：130343',
+    sampleValue: '130343 张',
+    sampleLine: '- **月票：** 130343',
+    precise: true,
+    precisionNote:
+      '**原样记下精确整数**，不要四舍五入（130343 不要写成"约 13 万张"）',
+    // 主指标在分析里的角色
+    role: '读者当月投出的月票数',
+    caveat: '精确整数，跨书可比',
+    // 辅助指标（只有起点有）
+    aux: [
+      {
+        label: '总推荐',
+        unit: '票',
+        sampleLine: '- **总推荐：** 12531500',
+        meaning: '开书至今累计获得的推荐票数',
+        caveat: '**历史累计** —— 老书天然占优，不代表当前热度',
+        usage: '**总推荐 vs 周推荐**：总推荐远大于周推荐 = 老书的累计盘子（体量/资历大）；两者量级接近 = 新书起量',
+      },
+      {
+        label: '周推荐',
+        unit: '票',
+        sampleLine: '- **周推荐：** 41826',
+        meaning: '最近一周获得的推荐票数',
+        caveat: '单点值 —— 只能横向比，**不能据此判断趋势**',
+        usage: '**周推荐 vs 月票**：同题材里周推荐更高 = 最近一周推荐热度更高；月票高而周推荐低 = 热度主要来自本月前段',
+      },
+      {
+        label: '打赏',
+        unit: '人次',
+        sampleLine: '- **打赏：** 今日 19 / 本周 52',
+        meaning: '今日/本周的**打赏次数**',
+        caveat: '**是次数不是金额** —— 页面不公开打赏金额，别写成"打赏 XX 元"',
+        usage: '**打赏 vs 月票**：打赏与月票同向 = 铁粉付费黏性强；月票高而打赏低 = 可能是订阅或活动拉动，不是长期铁粉盘',
+      },
+    ],
+  },
+  fanqie: {
+    field: '在读',
+    label: '在读',
+    unit: '人',
+    note: '精确人数，取自番茄明文接口的 readCount',
+    sample: '在读：597999',
+    sampleValue: '597999',
+    sampleLine: '- **在读：** 597999',
+    precise: false,
+    precisionNote:
+      '**原样记下文件里的数值**，不要换算成"约 60 万"',
+    role: '平台给出的当前在读人数',
+    caveat: '精确人数；榜页显示的"59.8万"是它的舍入形式 —— **原样记录，不要换算**',
+    aux: [],
+  },
+  jinjiang: {
+    field: '积分',
+    label: '积分',
+    unit: '分',
+    note: '形如 1053978496，纯整数不带千分位逗号',
+    sample: '积分：1053978496',
+    sampleValue: '1053978496 分',
+    sampleLine: '- **积分：** 1053978496',
+    precise: true,
+    precisionNote:
+      '**原样记下精确整数**，不要四舍五入（1053978496 不要写成"约 10 亿分"）',
+    role: '作品累计获得的积分',
+    caveat: '精确整数，跨书可比',
+    aux: [],
+  },
+  qimao: {
+    field: '热度',
+    label: '热度',
+    unit: '万',
+    note: '形如 3853.8万',
+    sample: '热度：3853.8万',
+    sampleValue: '3853.8万',
+    sampleLine: '- **热度：** 3853.8万',
+    precise: false,
+    precisionNote:
+      '**原样记下文件里的数值**，不要二次换算或取整（3853.8万 不要写成"约 3854 万"）',
+    role: '平台给出的作品热度值',
+    caveat: '平台给出的数值，原样记录',
+    aux: [],
+  },
+};
+
+/**
+ * 取某平台的热度指标描述；未知平台给通用兜底。
+ * @param {string} platform
+ * @returns {{field: string, label: string, unit: string, note: string,
+ *            sample: string, sampleValue: string, sampleLine: string,
+ *            precise: boolean, precisionNote: string, role: string, caveat: string,
+ *            aux: Array<{label: string, unit: string, sampleLine: string,
+ *                         meaning: string, caveat: string, usage: string}>}}
+ */
+export function heatMetric(platform) {
+  return HEAT_METRIC[platform] || {
+    field: '热度',
+    label: '热度',
+    unit: '',
+    note: '以数据文件里给出的热度指标为准',
+    sample: '热度：…',
+    sampleValue: '…',
+    sampleLine: '- **热度：** …',
+    precise: false,
+    precisionNote: '**原样记下文件里的数值**，不要二次换算或取整',
+    role: '平台给出的热度值',
+    caveat: '以数据文件里给出的热度指标为准',
+    aux: [],
+  };
+}
+
+/**
+ * 选题方向的 11 项设计标签 —— **单一事实来源**见 `lib/direction-labels.js`。
+ *
+ * 这 11 个标签同时出现在：方向模板、写入后校验、fancy-topic 的 11 个
+ * 平级字段、story-builder 的任务输入快照。之前每处各写一遍，已经漂移过一次 ——
+ * 提示词写 `- 定位：`，实际报告写 `- **定位**：`，而 5.3 根本不查标签，
+ * 模型于是自己"适配"了一轮格式（把校验正则改成加粗形式）。
+ *
+ * **标签一律加粗**（`**定位**：`）—— 实际产物已经是这个形式，
+ * 顺势定为规范比强行改回不加粗更省事；校验也按加粗形式查。
+ */
+
+/**
+ * 各平台的**数据文件形态**（2026-10-29 提示词评审 P0-1）
+ *
+ * ## 为什么要有这个（提示词里最严重的一条错）
+ *
+ * 提示词原来对**四个平台统一**描述成：
+ *
+ *   "文件里每个 `## 某题材 — N 本` 是一个题材组，每组取该题材的前 N 本（通常是 10 本）"
+ *   "题材以数据文件里的官方分组为准（`## 都市日常 — 10 本` 的二级标题就是题材）"
+ *
+ * 但那是**番茄/晋江**的格式。起点和七猫是**平铺**的：
+ *
+ *   - 起点（2026-10-29 实测 9 个文件 180 条）：`## #1 玄鉴仙族` ——
+ *     `##` 下面是**书名**，文件里**一个** `## 某题材 — N 本` 都没有；
+ *   - 七猫：`### #1 书名` —— 同上。
+ *
+ * 按原文执行，模型在起点/七猫上找不到任何题材组：
+ * 要么卡住，要么把 `## #1 玄鉴仙族` 当成题材名 —— 整份报告失真。
+ *
+ * 所以数据形态必须**按平台说**，不能一句话套四个平台。
+ *
+ * ## 形态差异一览
+ *
+ * | 平台 | 分组标题 | 书目标题 | 题材来源 | `**标签：**` | `**排名变动：**` |
+ * | --- | --- | --- | --- | --- | --- |
+ * | 番茄 | `## 题材 — N 本` | `### #N 书名` | 分组标题 | 有 | 有 |
+ * | 晋江 | `## 频道 — N 本` | `### #N 书名` | `**题材：**` 字段（频道名不是题材） | 有 | 无 |
+ * | 起点 | **无** | `## #N 书名` | `**题材：**` 字段（大类·子类） | **无** | **无** |
+ * | 七猫 | **无** | `### #N 书名` | `**题材：**` + `**子分类：**` | **无** | **无** |
+ */
+export const DATA_SHAPE = {
+  qidian: {
+    grouped: false,
+    stratified: false,
+    groupTitle: null,
+    bookHeading: '## #N 书名',
+    genreFrom: 'field',
+    genreField: '**题材：** 大类·子类',
+    genreExample: '仙侠·修真文明',
+    hasTags: false,
+    hasRankChange: false,
+  },
+  fanqie: {
+    grouped: true,
+    stratified: true,
+    groupTitle: '## 题材名 — N 本',
+    bookHeading: '### #N 书名',
+    genreFrom: 'group',
+    genreField: null,
+    genreExample: '都市异能',
+    hasTags: true,
+    hasRankChange: true,
+  },
+  jinjiang: {
+    grouped: true,
+    stratified: false,
+    groupTitle: '## 频道名 — N 本',
+    bookHeading: '### #N 书名',
+    // 晋江的 ## 是**频道**（全站），不是题材；题材在每本书的 **题材：** 字段里。
+    genreFrom: 'field',
+    genreField: '**题材：**',
+    genreExample: '原创-言情-架空历史-爱情',
+    hasTags: true,
+    hasRankChange: false,
+  },
+  qimao: {
+    grouped: false,
+    stratified: false,
+    groupTitle: null,
+    bookHeading: '### #N 书名',
+    genreFrom: 'field',
+    genreField: '**题材：** / **子分类：**',
+    genreExample: '都市 / 都市异能',
+    hasTags: false,
+    hasRankChange: false,
+  },
+};
+
+/** 取某平台的数据形态；未知平台按"平铺 + 题材字段"兜底（更保守）。 */
+export function dataShape(platform) {
+  return DATA_SHAPE[platform] || {
+    grouped: false,
+    stratified: false,
+    groupTitle: null,
+    bookHeading: '#N 书名',
+    genreFrom: 'field',
+    genreField: '**题材：**',
+    genreExample: '（文件里的题材值）',
+    hasTags: false,
+    hasRankChange: false,
+  };
+}
+
+// 各平台的榜单配置（与 /home/cloud/dsh-fancy-webnovel/commands/scan/platforms/ 保持一致）
+export const RANK_LISTS = {
+  qidian: [
+    { id: 'hotsales',   label: '畅销榜' },
+    { id: 'yuepiao',   label: '月票榜' },
+    { id: 'readindex', label: '阅读榜' },
+    { id: 'newfans',   label: '书友榜' },
+    { id: 'rec',       label: '推荐榜' },
+    { id: 'update',    label: '更新榜' },
+    { id: 'sign',      label: '签约榜' },
+    { id: 'newbook',   label: '新书榜' },
+    { id: 'newauthor', label: '新人作者榜' },
+  ],
+  fanqie: [
+    { id: '1_2', label: '男频阅读榜' },
+    { id: '1_1', label: '男频新书榜' },
+    { id: '0_2', label: '女频阅读榜' },
+    { id: '0_1', label: '女频新书榜' },
+  ],
+  jinjiang: [
+    { id: '5',  label: '月榜' },
+    { id: '7',  label: '总分榜' },
+    { id: '4',  label: '季度榜' },
+    { id: '3',  label: '新晋作者榜' },
+  ],
+  qimao: [
+    { id: 'boy/hot/month',  label: '男生大热月榜' },
+    { id: 'boy/new/month',  label: '男生新书月榜' },
+    { id: 'girl/hot/month', label: '女生大热月榜' },
+    { id: 'girl/new/month', label: '女生新书月榜' },
+  ],
+};
+
+export function platformLabel(platform) {
+  const row = PLATFORM_TABLE.find(r => r[1] === platform);
+  return row ? row[2] : platform;
+}
+
+/**
+ * 各平台的扫描方式选项（UI 层）。
+ *
+ * 目前只有番茄有两条取数路径：
+ *   api —— 走番茄自家明文接口 /api/book/info 拿书名/作者/简介；
+ *   ocr —— 渲染后截图 + tesseract 识别。
+ *
+ * 两条路径的利弊直接写进 description：用户在提问面板上就能看到
+ * "精度/耗时" 与 "是否依赖番茄内部接口" 的取舍，不必先跑一次才知道。
+ */
+export const SCAN_MODE_OPTIONS = {
+  fanqie: [
+    {
+      id: SCAN_MODE_API,
+      label: 'API扫描（默认）',
+      description:
+        '优势：书名/作者/简介取自番茄明文接口，零识别误差、精度 100%，整榜耗时约为 OCR 扫描的 1/5；' +
+        '劣势：依赖番茄 /api/book/info 接口，该接口若变更或临时不可用时，简介会缺失',
+    },
+    {
+      id: SCAN_MODE_OCR,
+      label: 'OCR扫描',
+      description:
+        '优势：渲染后截图识别，不依赖番茄内部接口，接口失效也能采到；' +
+        '劣势：每本约 0.5 秒且存在认字误差（实测简介字符错误率 8%~17%），整榜耗时约为 API 扫描的 5 倍',
+    },
+  ],
+};
+
+/**
+ * 扫描方式 id → 展示用名称（去掉"（默认）"后缀，只在结果回执里展示）。
+ */
+export function scanModeLabel(mode) {
+  const hit = (SCAN_MODE_OPTIONS.fanqie || []).find(m => m.id === mode);
+  return hit ? hit.label.replace(/（默认）$/, '') : String(mode || '');
+}
+
+/**
+ * 把 DSH 回传的 label 解析成扫描方式 id。
+ *
+ * DSH 的 selected 回传的是 label 字符串（options.value 会被运行时静默忽略），
+ * 所以只能按 label 的字母前缀判断 —— 不能依赖 label 里带 id。
+ * 解析不出合法 id 时返回 null，由调用方按"无效选择"处理。
+ */
+export function parseScanMode(selected) {
+  const s = String(selected == null ? '' : selected).trim();
+  if (!s) return null;
+  const upper = s.toUpperCase();
+  if (upper.startsWith('API')) return SCAN_MODE_API;
+  if (upper.startsWith('OCR')) return SCAN_MODE_OCR;
+  return null;
+}

package/plugins/fancy-scan/templates/report-schema.js

@@ -0,0 +1,90 @@
+/**
+ * report-schema.js —— 扫榜报告的**结构契约**（提示词与校验脚本同源）
+ *
+ * ## 为什么要有这个文件
+ *
+ * 评审 F14 指出：提示词里写一份、校验脚本里写一份，**口径必然漂**。
+ * 提示词说"3 张表"，脚本查的是另一种表头；提示词说"11 项标签"，
+ * 脚本数的是另一个清单 —— 校验通过了，报告其实不合格。
+ *
+ * 现在**只定义一次**：
+ *   - 提示词从这儿取章节标题、取表头、取数字要求；
+ *   - `scripts/append-block.js` 也从这儿取。
+ *
+ * 改一处，两边同时变。
+ *
+ * ## 这不是"内容质量"契约
+ *
+ * 这里定义的全是**可机械判定**的东西：章节标题在不在、表头对不对、
+ * 方向几个、标签齐不齐、字数够不够。
+ * "选得好不好""洞察深不深"不在这里 —— 那是模型的事，脚本管不了，
+ * 也不该管（管了就成了"为了过校验而写废话"）。
+ */
+import { DIRECTION_LABELS } from '#direction-labels';
+
+/** 报告的七个章节 —— 标题**逐字**固定，顺序也固定 */
+export const SECTION_TITLES = [
+  '一、数据与方法',
+  '二、市场结构（单日快照）',
+  '三、热门题材分析',
+  '四、用户画像',
+  '五、竞争度评估',
+  '六、选题方向建议',
+  '七、风险与验证',
+];
+
+/**
+ * 机械判定阈值 —— 提示词与脚本共用。
+ *
+ * 数字都取"能被脚本精确验证"的值：
+ *   - 字数用**汉字数**而不是字符数（标点、表格符号、markdown 标记不算）；
+ *   - 表格数用**分隔行**数（`| --- | --- |` 那种），不是"看起来像表格的行"；
+ *   - 标签要求"加粗 + 全角冒号 + 正文 ≥20 汉字"，避免"写个标题充数"。
+ */
+export const REPORT_RULES = {
+  /** 方向个数 */
+  minDirections: 3,
+  maxDirections: 4,
+  /** 每个方向的 11 项设计标签 */
+  minTagsPerDirection: DIRECTION_LABELS.length,
+  /** 每个标签后面的正文汉字数下限（防止"写个标签名充数"） */
+  minTagChars: 20,
+  /** 全文汉字数区间 */
+  minCjkTotal: 4000,
+  maxCjkTotal: 15000,
+  /** 纯正文汉字数下限（排除表格行、标题行、标签行之后的正文量） */
+  minPureCjk: 3000,
+  /** 表格张数 */
+  minTables: 3,
+  /** 至少几处"《书名》…月票 N 张"式的引用 */
+  minCitations: 2,
+  /** 至少几处"推断"标记 */
+  minInferMarks: 3,
+};
+
+/**
+ * 三张表的表头 —— **按平台**给（"需求份额"在平铺平台要叫"样本内份额"）。
+ *
+ * @param {string} metricLabel 热度指标名（如"月票"、"在读"）
+ * @param {boolean} grouped 数据是否按题材分组（番茄/晋江）
+ * @returns {{topic: string, competition: string, choice: string}}
+ */
+export function tableHeaders(metricLabel, grouped) {
+  const share = grouped ? '需求份额' : '样本内份额';
+  return {
+    topic: `题材 | 书目数 | ${metricLabel}总量 | 均值 | 中位数 | ${share}`,
+    competition: `题材 | ${share} | 头部集中度 | 同质化程度 | 差异化空间 | 判断`,
+    choice: '方向 | 题材 | 金手指 | 情绪价值 | 差异化 | 风险 | 优先级',
+  };
+}
+
+/** 表名 → 表头（脚本按顺序校验三张表） */
+export const TABLE_ORDER = ['topic', 'competition', 'choice'];
+
+/** 表格分隔行（`| --- | --- |` 那种） */
+export const TABLE_SEP_RE = /^\s*\|(?:\s*:?-{2,}:?\s*\|)+\s*$/;
+
+/** 方向标题 */
+export const DIRECTION_RE = /^###\s*方向\s*(\d+)\s*[:：]/;
+
+export { DIRECTION_LABELS };