@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

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 本标“样本不足”`,
+  ];
+}

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 };