@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-scan/templates.js

@@ -1,111 +1,144 @@
 /**
- * scan 模板 — 仅 fancy-scan 使用
+ * scan 模板渲染层 —— 组装提示词 + 提供运行时 API
+ *
+ * ## 分层（与 fancy-story-builder 同构）
+ *
+ *   prompts/01-analysis-prompt.md   提示词层：静态任务契约、报告结构、校验口径。
+ *                                   只描述"要什么"和"脚本退出码代表什么"，
+ *                                   不包含任何直接写目标文件的命令。
+ *   templates/platforms.js          模板层：平台/榜单/指标/数据形态的单一事实来源。
+ *   templates/blocks.js             模板层：按平台生成的提示词动态段落。
+ *   templates/report-schema.js      模板层：报告章节/阈值/表头契约（与校验脚本同源）。
+ *   scripts/append-block.js         脚本层：预检 + 校验 + 写入 + 回滚（部署到工作区内）。
+ *   scripts/report-validate.js      脚本层：正文机械校验（提示词与插件共用）。
+ *
+ * **LLM 只能通过部署到 `.fancy-tools/fancy-scan/` 的脚本写目标文件**；
+ * 提示词里的 3.1 预检与 5.2 写入都只调用脚本，由退出码与 JSON 决定下一步。
  */
 
-import { SCAN_MODE_API, SCAN_MODE_OCR } from '#scraper-utils';
-
-// ---------------------------------------------------------------------------
-// 共享常量
-// ---------------------------------------------------------------------------
+import { shellSingleQuote } from '#path-guard';
+import {
+  DIRECTION_LABELS,
+  DIRECTION_LABEL_RE,
+  directionTemplateBlock,
+} from '#direction-labels';
+// 报告的结构契约 —— **提示词与校验脚本同源**（report-schema.js）。
+// 阈值、章节标题、表头只定义一次，改一处两边同时变。
+import {
+  SECTION_TITLES,
+  REPORT_RULES,
+  tableHeaders,
+} from './templates/report-schema.js';
+import {
+  PLATFORM_TABLE,
+  HEAT_METRIC,
+  heatMetric,
+  DATA_SHAPE,
+  dataShape,
+  RANK_LISTS,
+  platformLabel,
+  parseScanMode,
+  SCAN_MODE_OPTIONS,
+  scanModeLabel,
+} from './templates/platforms.js';
+import {
+  dataShapeBlock,
+  genreRuleBlock,
+  tagRuleBlock,
+  competitionBlock,
+} from './templates/blocks.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
 
-export const PLATFORM_TABLE = [
-  ['1', 'qidian',  '起点'],
-  ['2', 'fanqie',  '番茄'],
-  ['3', 'jinjiang','晋江'],
-  ['4', 'qimao',   '七猫'],
-];
-
-// 各平台的榜单配置（与 /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: '女生新书月榜' },
-  ],
+// 兼容旧入口：外部（index.js / 测试）一直从 templates.js 取这些表。
+export {
+  PLATFORM_TABLE,
+  HEAT_METRIC,
+  heatMetric,
+  DATA_SHAPE,
+  dataShape,
+  RANK_LISTS,
+  platformLabel,
+  parseScanMode,
+  SCAN_MODE_OPTIONS,
+  scanModeLabel,
 };
 
-export function platformLabel(platform) {
-  const row = PLATFORM_TABLE.find(r => r[1] === platform);
-  return row ? row[2] : platform;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** 校验/追加脚本的绝对路径（写目标文件的唯一入口） */
+export const APPEND_SCRIPT = join(__dirname, 'scripts', 'append-block.js');
+
+/** 静态提示词契约（**提示词层**；动态段落由 templates/blocks.js 注入） */
+export const ANALYSIS_PROMPT_FILE = join(__dirname, 'prompts', '01-analysis-prompt.md');
+
+/** 块 ID：平台-榜单列表-日期（提示词、预检、写入、复核共用） */
+export function makeBlockId(platform, rankListsStr, date) {
+  return `${platformLabel(platform)}-${rankListsStr}-${date || ''}`;
+}
+
+/** 把块（数组或空）转成带换行的文本，便于注入 Markdown 模板 */
+export function blockToText(block) {
+  if (!block) return '';
+  const lines = Array.isArray(block) ? block : [String(block)];
+  if (!lines.length) return '';
+  return lines.join('\n') + '\n';
 }
 
 /**
- * 各平台的扫描方式选项（UI 层）。
+ * 渲染提示词：静态契约来自 prompts/01-analysis-prompt.md，
+ * 动态段落（按平台的数据形态/指标/竞争度）由调用方传入。
  *
- * 目前只有番茄有两条取数路径：
- *   api —— 走番茄自家明文接口 /api/book/info 拿书名/作者/简介；
- *   ocr —— 渲染后截图 + tesseract 识别。
+ * **提示词层不执行任何校验**；它只描述契约与脚本的退出码。
+ * 校验与写盘在 scripts/append-block.js（部署到项目 `.fancy-tools/`）。
  *
- * 两条路径的利弊直接写进 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 → 展示用名称（去掉"（默认）"后缀，只在结果回执里展示）。
+ * @param {Record<string, string|number>} vars
+ * @returns {string}
  */
-export function scanModeLabel(mode) {
-  const hit = (SCAN_MODE_OPTIONS.fanqie || []).find(m => m.id === mode);
-  return hit ? hit.label.replace(/（默认）$/, '') : String(mode || '');
+export function renderAnalysisPrompt(vars) {
+  let text = readFileSync(ANALYSIS_PROMPT_FILE, 'utf-8');
+  // 维护者元数据（@meta-only 之前）不发给 LLM
+  const meta = text.indexOf('\n@meta-only\n');
+  if (meta !== -1) {
+    text = text.slice(meta + '\n@meta-only\n'.length);
+    text = text.replace(/^\s*---\s*\n/, '');
+  }
+  for (const [key, value] of Object.entries(vars)) {
+    text = text.split('${' + key + '}').join(value === undefined || value === null ? '' : String(value));
+  }
+  // 没有对应变量的占位符替空，避免把 ${...} 原样发给模型
+  text = text.replace(/\$\{[a-z_]+\}/g, '');
+  return text;
 }
 
 /**
- * 把 DSH 回传的 label 解析成扫描方式 id。
+ * 正文临时文件的路径 —— 按块 ID 派生，同一块永远是同一个文件。
  *
- * DSH 的 selected 回传的是 label 字符串（options.value 会被运行时静默忽略），
- * 所以只能按 label 的字母前缀判断 —— 不能依赖 label 里带 id。
- * 解析不出合法 id 时返回 null，由调用方按"无效选择"处理。
+ * 放在 <工作区目录>/.tmp 下：这是 DSH 沙箱允许写、且不会进 `扫榜结果/` 的
+ * 位置；不要用系统 /tmp。
  */
-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;
+export function bodyFilePath(projectRoot, blockId, scope = '') {
+  const safe = String(blockId)
+    .replace(/[^\w一-鿿-]+/g, '_')
+    .slice(0, 60);
+  // 不同项目同平台同日期会得到同一个 blockId；把 topicFile/projectRoot
+  // 的哈希拼进去，避免两个会话共用同一个临时正文文件、互相覆盖。
+  const h = scope
+    ? createHash('sha256').update(String(scope)).digest('hex').slice(0, 10)
+    : '';
+  const tempDir = projectRoot ? join(projectRoot, '.tmp') : '.tmp';
+  return join(tempDir, `fancy_scan_body_${safe}${h ? '_' + h : ''}.md`);
 }
 
+// 11 项标签的**单一事实来源**在 lib/direction-labels.js ——
+// 这里转出去一份，外部引用方不用知道它住在哪个 lib 文件里。
+export { DIRECTION_LABELS, DIRECTION_LABEL_RE };
+
+// ---------------------------------------------------------------------------
+// 共享常量
+// ---------------------------------------------------------------------------
+
 // ---------------------------------------------------------------------------
 // 模板
 // ---------------------------------------------------------------------------
@@ -165,55 +198,163 @@ export const scan = {
     };
   },
 
-  notify({ type, files, topicFile, projectRoot, err, failedRanks, scanMode, detail }) {
+  notify({ type, files, topicFile, projectRoot, err, failedRanks, scanMode, detail, repaired, dirt, platform, rankLabels, date, blockId, closed, dates }) {
     switch (type) {
+      case 'help':
+        return `📊 扫榜 用法
+
+/fancy-scan        交互选择平台与榜单，抓取榜单并生成 <工作区>/扫榜结果/
+/fancy-scan help   显示本帮助
+
+作用：为 fancy-topic 提供扫榜数据。`;
+
       case 'not_initialized':
-        return '⚠️ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+        return '⚠️ 当前目录不属于已初始化的 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。';
 
       case 'invalid_choice':
-        return '❌ 无效选择，请输入 1-4 的编号。';
+        return '❌ 选择无效，请输入 1-4 的编号。';
 
       case 'invalid_scan_mode':
-        return '❌ 无效的扫描方式选择，请重新运行 /fancy-scan。';
+        return '❌ 扫描方式选择无效，请重新运行 /fancy-scan。';
 
       case 'cancelled':
-        return '🚫 已取消';
+        return '🚫 操作已取消。';
 
       case 'no_provider':
-        return '⚠️ 当前环境不支持交互式提问。请在 dsh-tui 中运行此命令，或确保 web UI 已正确加载交互组件。';
+        return '⚠️ 当前运行环境不支持交互式提问。请在 dsh-tui 中运行该命令，或确认 Web UI 已正确加载交互组件。';
 
       case 'no_project_root':
-        return '❌ 无法确定项目目录：' + (err || '会话未提供 cwd') + '。请在项目目录下运行该命令。';
+        return '❌ 无法确定工作区：' + (err || '会话未提供当前工作目录') + '。请在 fancy-webnovel 工作区目录下运行该命令。';
 
       case 'ask_failed':
-        return '❌ 提问失败：' + (err || '未知错误');
+        return '❌ 交互提问失败：' + (err || '未知错误');
 
       case 'cancelled_with_hint':
-        return '⚠️ 已取消。请再次调用 /fancy-scan 继续。';
+        return '⚠️ 操作已取消。请重新运行 /fancy-scan。';
 
       case 'failed':
         return '❌ 采集失败：' + err;
 
       case 'scraper_failed':
-        return '❌ ' + err;
+        return '❌ 榜单采集失败：' + err;
 
       case 'no_rank_selected':
-        return '❌ 未选中任何榜单，无法开始采集。';
+        return '❌ 未选择任何榜单，无法开始采集。';
+
+      case 'scan_date_mixed': {
+        const ds = Array.isArray(dates) ? dates : [];
+        const fs = Array.isArray(files) ? files : [];
+        const rel = fs.map(f => '- ' + String(f).replace((projectRoot || '') + '/', '')).join('\n');
+        return '❌ 本次采集跨过了本地午夜，各榜单落在了不同日期：' + ds.join(' / ') + '。\n'
+          + '为避免把两天的数据写进同一份日报，已停止分析，**没有生成报告**。\n'
+          + (rel ? `\n本批数据文件：\n${rel}\n` : '')
+          + '\n请删除这批数据文件后重新采集，确保本批数据文件使用同一个日期。';
+      }
+
+      case 'already_scanned': {
+        const rel = topicFile
+          ? topicFile.replace((projectRoot || '') + '/', '')
+          : '扫榜结果/topic_decision_<日期>.md';
+        const unclosed = closed === false ? '\n（注意：这个块目前只有 start、缺 end 标记）' : '';
+        return `⏭️ 本次未执行扫榜：${platform || ''} · ${rankLabels || ''} · ${date || ''}。\n`
+          + `目标文件：${rel}\n`
+          + `目标文件中已存在本次标记 \`# ${blockId || ''}-start\`${unclosed}\n`
+          + '为避免重复采集，本次未启动采集脚本，也未改动任何文件。\n'
+          + '如需重新采集，请先删除该内容块，或更换榜单/日期。';
+      }
+
+      case 'existing_block_unreadable': {
+        const rel = topicFile
+          ? topicFile.replace((projectRoot || '') + '/', '')
+          : '扫榜结果/topic_decision_<日期>.md';
+        return `❌ 无法检查 ${rel} 中是否已存在本次内容块：${err || '目标文件无法读取'}。\n`
+          + '为避免重复采集或重复写入，本次未启动采集脚本。\n'
+          + '请确认该文件可读且不是符号链接，然后重试。';
+      }
+
+      case 'dirty_file': {
+        // 模型自己把文件写歪了：同一个平台写了两遍，或者把校验命令写进了正文。
+        // 它自己看不见（写完就交差了），只能插件来说。
+        const d = dirt || {};
+        let out = '⚠️ 目标文件中检测到上次写入异常的内容：\n';
+        if (d.deduped && d.deduped.removed && d.deduped.removed.length) {
+          out += `- 已自动合并 **${d.deduped.removed.length} 个重复块**（同一平台被写入多次，保留最后一份）\n`;
+          for (const r of d.deduped.removed) {
+            out += `  - 「${r.key}」第 ${r.lines} 行的重复块已删除\n`;
+          }
+          out += d.deduped.backupPath
+            ? `- 删除前已备份：\`${d.deduped.backupPath}\`\n`
+            : '- ⚠️ 本次备份失败，已删除内容无法恢复。\n';
+        }
+        if (d.lines && d.lines.length) {
+          out += (d.deduped && d.deduped.removed && d.deduped.removed.length ? '\n以下内容尚未处理：\n' : '') +
+            d.lines.map((l) => '- ' + l).join('\n') + '\n';
+        }
+        out += '\n这些异常通常由模型写入文件时 heredoc 缺少结束符 `FANCY_SCAN_BODY_EOF` 导致。' +
+          '正文中混入的命令片段和未闭合块不会被自动修改，以免误删正文内容。' +
+          '请人工确认后处理。';
+        return out;
+      }
+
+      case 'manifest_failed':
+        return '❌ 生成本次分析运行清单失败，已停止：\n'
+          + (err || '未知错误') + '\n\n'
+          + '未改动任何采集结果。请检查工作区目录与 `.fancy-tools/fancy-scan/` 的写权限后重试。';
+
+      case 'tool_deploy_failed':
+        return '❌ 准备工作区内的校验/写入脚本失败，已停止本次扫榜：\n'
+          + (err || '未知错误') + '\n\n'
+          + '未开始采集，扫榜结果/ 未发生改动。\n'
+          + '请检查工作区目录的写权限，并确认 `.fancy-tools` 是真实目录（不能是符号链接）后重试。';
 
       case 'llm_delivery_failed':
-        return '❌ 采集已完成，但提示词投递给 LLM 失败：' + (err || '未知错误') +
-          '\n已采集的数据保留在 扫榜结果/ 下，请重新运行 /fancy-scan 以触发分析。';
+        return '❌ 采集已完成，但提示词发送给 LLM 失败：' + (err || '未知错误') +
+          '\n已采集数据保留在 扫榜结果/ 下，请重新运行 /fancy-scan 触发分析。';
+
+      case 'write_verify_failed':
+        // 模型回合结束后插件自己查了一遍，发现没写进去 / 写歪了。
+        // 之前这种情况会被当成"写成功了"——用户看到的是一份残缺报告。
+        return '❌ 采集与分析已完成，但分析结果未能正确写入目标文件：\n'
+          + (err || '未知原因') + '\n\n'
+          + '📁 已采集数据保留在 扫榜结果/ 下，目标文件中未损坏的内容仍然保留。\n'
+          + '💡 重新运行 /fancy-scan 可重新执行分析；同一平台同一天的内容块不会重复写入。';
 
       case 'phase_advance_failed':
         // 采集成功但 phase 推不动 = 整个流程卡住：
         // 下游 /fancy-topic 要求 phase === 'scanned'，推不动就永远过不了。
         // 之前这个失败只写进 run-scan.js 的 stderr，用户只看到"采集完成"，
         // 接着跑 /fancy-topic 报"状态文件读不了"，完全不知道问题出在这儿。
-        return '❌ 采集已完成，但 .fancy-deployed 的 phase 没能推进到 scanned，流程走不下去。\n' +
+        return '❌ 采集已完成，但 `.fancy-deployed` 的 phase 未能推进到 `scanned`，后续流程无法继续。\n' +
           `原因：${err || '未知原因'}\n\n` +
-          '📁 已采集的数据保留在 扫榜结果/ 下，修好状态文件后重跑 /fancy-scan 即可。\n\n' +
+          '📁 已采集数据保留在 扫榜结果/ 下。修复状态文件后重新运行 /fancy-scan。\n\n' +
           (detail || '');
 
+      case 'analysis_done': {
+        const failed = (failedRanks || []).length
+          ? '\n⚠️ 以下榜单存在采集问题：'
+            + failedRanks.map(f => f.label + '（' + f.error + '）').join('；')
+          : '';
+        const modeLine = scanMode
+          ? `\n🔍 扫描方式：${scanModeLabel(scanMode)}`
+          : '';
+        const repairedLine = (repaired || []).length
+          ? `\n♻️ 检测到上一次的 topic_decision 被覆盖，已从备份补回 ${repaired.length} 个内容块：${repaired.join('、')}`
+          : '';
+        const fileLines = (files || []).length
+          ? '\n📁 本次采集文件：\n' + files.map(f => '- ' + f.replace((projectRoot || '') + '/', '')).join('\n')
+          : '';
+        const rel = topicFile
+          ? topicFile.replace((projectRoot || '') + '/', '')
+          : '扫榜结果/topic_decision_<日期>.md';
+        return `✅ 采集与分析${failed ? '完成（部分榜单存在异常）' : '完成'}（${platform || ''} · ${rankLabels || ''} · ${date || ''}）`
+          + modeLine
+          + repairedLine
+          + fileLines
+          + `\n📄 分析报告已追加写入：${rel}`
+          + failed
+          + '\n\n💡 下一步：运行 /fancy-topic 进行选题。';
+      }
+
       case 'handover': {
         // 部分榜单失败时必须显式列出：此前直接中断整个命令，
         // 已采集成功的榜单产物被丢弃，用户既不知道采到了什么，也拿不到文件。
@@ -224,12 +365,18 @@ export const scan = {
         const modeLine = scanMode
           ? `\n🔍 扫描方式：${scanModeLabel(scanMode)}`
           : '';
+        // 上一次分析把 topic_decision 覆盖了（LLM 的 write 是覆盖语义），
+        // 这次已从备份补回 —— 必须告诉用户，不然他会以为之前那轮白跑了。
+        const repairedLine = (repaired || []).length
+          ? `\n♻️ 检测到上一次的 topic_decision 被覆盖，已从备份补回 ${repaired.length} 个内容块：${repaired.join('、')}\n`
+          : '';
         return (
-          `📊 采集完成，正在将数据交给 LLM 进行分析...` +
+          `📊 采集完成，正在将数据发送给 LLM 进行分析…` +
           modeLine +
+          repairedLine +
           `\n📁 生成文件：\n${(files || []).map(f => '- ' + f.replace(projectRoot + '/', '')).join('\n')}\n` +
-          `💡 分析报告将写入：${(topicFile || '').replace(projectRoot + '/', '')}\n` +
-          `⏳ LLM 完成后会写入上述 topic_decision 文件，届时可执行 /fancy-topic` +
+          `💡 分析报告将**追加**写入：${(topicFile || '').replace(projectRoot + '/', '')}\n` +
+          `⏳ LLM 完成后会将分析写入上述 topic_decision 文件，届时可执行 /fancy-topic` +
           failed
         );
       }
@@ -239,57 +386,309 @@ export const scan = {
     }
   },
 
-  llmAnalysisPrompt({ platform, rankLists, date, files, topicFile, projectRoot }) {
+  /**
+   * @param {object} args
+   * @param {string} args.platform - 平台 value（fanqie/qidian/…）
+   * @param {string[]} args.rankLists - 榜单中文名列表
+   * @param {string} args.date - 日期戳（YYYYMMDD）
+   * @param {string[]} args.files - 采集产物绝对路径
+   * @param {string} args.topicFile - topic_decision_<date>.md 绝对路径
+   * @param {string} args.projectRoot - 工作区目录
+   * @param {Array<{key: string, startTitle: string, endTitle: string|null, closed: boolean}>} [args.existingBlocks]
+   *        文件里**已有**的标记块（插件读文件得到的）。
+   *        告诉模型"里面已经有什么"，它才知道自己只该追加、不该重写。
+   */
+  llmAnalysisPrompt({ platform, rankLists, date, files, topicFile, projectRoot, existingBlocks, fileWarnings, failedRanks, appendScript: appendScriptArg, manifestPath }) {
     const pLabel = platformLabel(platform);
     const listsStr = rankLists ? rankLists.join('、') : '全选';
+    // 本次是**一个**榜单还是**多个**（含"全选"）—— 措辞必须跟着走。
+    // 之前一律写"本报告只有一个榜单"，而用户选"全选"或多个榜单时，
+    // 那句话和实际数据文件直接矛盾（起点"全选"本身就含新书榜）。
+    //
+    // "全选"要**单独判**：它只有一个元素，但代表的是该平台的**全部**榜单 ——
+    // 只看数组长度会把它当成单榜（实测踩过：选了全选，提示词却说"只有一个榜单"）。
+    const multiList = !rankLists || rankLists.length > 1 || rankLists.includes('全选');
+    const listRule = multiList
+      ? [
+          `- **本报告覆盖多个榜单**（${pLabel}·${listsStr}）—— 它们**都在本次数据文件里**，`,
+          `  可以做它们之间的对比；但**不得引入数据文件之外的榜单**，`,
+          `  不得编造本次没有提供的对比维度。`,
+          `- **"二、市场结构（单日快照）"里必须加一个"榜单间结构"小节**（标题逐字写 \`### 榜单间结构\`），至少包含下面 3 部分：`,
+          `  1. **跨榜重合**：哪些书出现在 ≥2 个榜单里（重合度），各榜全部条目重合多少本；`,
+          `  2. **名次差**：同一本书在不同榜的名次差；名次差大的书要说明原因，原因只能标"推断"；`,
+          `  3. **题材分布差异**：各榜的题材偏好有什么不同，至少举 2 本书佐证。`,
+          `  **不要把多个榜单简单合并成一个总表** —— 合并会造成榜单选择偏差`,
+          `  （某本书在几个榜里出现，它的样本量就机械性变大）。`,
+        ]
+      : [
+          `- **本报告只有一个榜单**（${pLabel}·${listsStr}），**没有第二个榜单可比**：`,
+          `  不得引入"新书榜"等其它榜单，不得编造"阅读榜 vs 新书榜"式的对比。`,
+        ];
+    // 各平台的热度指标不一样（起点月票/番茄在读/晋江积分/七猫热度）——
+    // 提示词里所有"热度"相关的措辞都要跟着平台走。
+    const h = heatMetric(platform);
+    // 单榜报告没有第二个榜单，不能出现"跨榜汇总/某题材在越多榜单里"这类说明；
+    // 只有多榜时才注入这段。
+    const crossListRule = multiList
+      ? [
+          `- **同一本书在多个榜单里的${h.label}可能有微小差异**（抓取时间差）——`,
+          `  **跨榜汇总/表格取抓取时间最新的值**；**正文按具体榜单引用时取该榜文件里的值并注明榜单**；`,
+          `  在"一、数据与方法"里记一句差异量级（两者差通常很小，写清口径即可）`,
+        ]
+      : [];
+    // 数据形态按平台走 —— 起点/七猫是平铺的，番茄/晋江才分组（评审 P0-1）
+    const ds = dataShape(platform);
+    // 单榜报告不写"同一本书在多个榜单里"——它只有一个榜单。
+    const dedupeRule = multiList
+      ? `- **去重键：书名 + 作者**；同一本书在多个${ds.grouped ? '组' : '榜单'}里出现时只算一次，并注明它出现在哪几个`
+      : `- **去重键：书名 + 作者**；同一本书重复出现时只算一次，并注明重复出现的位置`;
+    const genreSelfCheck = ds.grouped && ds.genreFrom === 'group'
+      ? `- 题材用的是数据文件里的官方分组，且跳过了"全部"`
+      : ds.grouped
+        ? `- 题材用的是每本书自己的题材字段（不是标题、不是频道名）`
+        : `- 题材用的是每本书自己的题材字段（不是标题）`;
+    // 契约常量：章节标题、阈值、表头 —— 与校验脚本同源
+    const R = REPORT_RULES;
+    const headers = tableHeaders(h.label, ds.grouped);
+    // 校验/追加脚本（写目标文件的唯一入口）。
+    // 运行时由 index.js 传入**工作区内**部署后的路径；测试/直接调用时
+    // 回退到插件内路径（只用于渲染提示词，不用于真的执行）。
+    const appendScript = appendScriptArg || APPEND_SCRIPT;
     const fileList = (files || [])
       .map(f => '- `' + f.replace(projectRoot + '/', '') + '`')
       .join('\n');
 
-    return [
-      `## 扫榜数据分析任务`,
-      ``,
-      `平台：${pLabel}`,
-      `榜单：${listsStr}`,
-      `时间：${date || ''}`,
+    // 块 ID **只算一次**（评审 11.3）—— 计数命令、写入命令、标记行、校验、
+    // 回复里凡是"平台-榜单-日期"都用这三个常量。之前散在 6 处各拼一次，
+    // 任何一次改格式都会和其它几处对不上。
+    const blockId = makeBlockId(platform, listsStr, date);
+    // 正文临时文件：按块 ID 派生，同一块永远是同一个文件
+    const bodyFile = bodyFilePath(projectRoot, blockId, topicFile || projectRoot || '');
+    // 预检/写入命令：优先用插件生成的 manifest。
+    // manifest 里已经写死目标、工作区目录、块 ID、数据文件、正文路径、指标与开关，
+    // 模型只需要照抄两条短命令 —— 少一个参数就少一个跑偏的机会。
+    const preflightCommand = manifestPath
+      ? `node ${shellSingleQuote(appendScript)} --preflight --manifest ${shellSingleQuote(manifestPath)}`
+      : [
+          `node ${shellSingleQuote(appendScript)} --preflight`,
+          `--target ${shellSingleQuote(topicFile)}`,
+          projectRoot ? `--project-root ${shellSingleQuote(projectRoot)} ` : '',
+          `--block-id ${shellSingleQuote(blockId)}`,
+          ...((files || []).map(f => `--data-file ${shellSingleQuote(f)}`)),
+        ].filter(Boolean).join(' ');
+    const appendCommand = manifestPath
+      ? `node ${shellSingleQuote(appendScript)} --manifest ${shellSingleQuote(manifestPath)}`
+      : [
+          `node ${shellSingleQuote(appendScript)}`,
+          `--target ${shellSingleQuote(topicFile)}`,
+          projectRoot ? `--project-root ${shellSingleQuote(projectRoot)} ` : '',
+          `--block-id ${shellSingleQuote(blockId)}`,
+          `--body ${shellSingleQuote(bodyFile)}`,
+          `--metric-label ${shellSingleQuote(h.label)}`,
+          ds.grouped ? '--grouped' : '--ungrouped',
+          multiList ? '--multi-list' : '--single-list',
+        ].filter(Boolean).join(' ');
+
+    const existing = existingBlocks || [];
+    // 措辞不能依赖"有没有标记块"来推断"文件存不存在" ——
+    // 文件可能有内容但没有标记块（模型没写标记、或内容是别的格式）。
+    // 说成"该文件目前不存在或是空的"会让模型以为可以重建/覆盖，
+    // 与"只能追加"自相矛盾。所以统一讲清追加语义，存在性交给预检去查。
+    const existingText = existing.length
+      ? [
+          `该文件里**已经有**下面这些内容块（**一个字都不许动**）：`,
+          ...existing.map(b => '- `' + b.startTitle + '` … `' + (b.endTitle || '（缺 end 标记）') + '`'),
+          ``,
+          `本次**只追加**，绝不覆盖、截断或重建这个文件。`,
+        ].join('\n')
+      : [
+          `目标文件**可能已存在**（含其它平台的内容）。`,
+          `本次**只追加**，绝不覆盖、截断或重建它 —— 它是否存在、有多大，以 3.1 预检的结果为准。`,
+        ].join('\n');
+
+    // 读数据文件时拼出来的绝对路径示例 —— 拼错路径是常见失败模式，
+    // 给一个具体例子比讲道理管用。
+    const absExample = projectRoot + '/' +
+      ((files && files[0] ? files[0].replace(projectRoot + '/', '') : '扫榜结果/xxx.md'));
+
+    // 采集阶段的部分失败必须让分析模型知道：它拿到的不是“全选完整数据”，
+    // 不能把缺失的榜单当成“没有书”或“热度为 0”。
+    const failed = Array.isArray(failedRanks) ? failedRanks : [];
+    const failedBlock = failed.length
+      ? [
+          `**采集异常（必须写进报告）**`,
+          ``,
+          `以下榜单/条目在采集阶段失败或部分失败。**缺失的部分不在本次文件里**：`,
+          ...failed.map(f => `- ${String(f.label || '').replace(/\s+/g, ' ')}：${String(f.error || '').replace(/\s+/g, ' ')}`),
+          ``,
+          `- 不得假装这些榜单完整；不得把缺失解释成“没有书/热度为 0”。`,
+          `- 在“一、数据与方法”里列出这些异常，并在“七、风险与验证”里说明局限。`,
+        ].join('\n')
+      : '';
+
+    // 文件里有上次写歪的痕迹时，先告诉模型现状（细节见 index.js 的 inspectTopicDecision）。
+    const warningsBlock = (fileWarnings && fileWarnings.length)
+      ? [
+          ``,
+          `⚠️ **这个文件里有上次写歪的痕迹，追加前先看清楚**：`,
+          ...fileWarnings.map(w => `- ${w}`),
+          ``,
+          `- **本次只追加一个块**（一个 start 标记 + 正文 + 一个 end 标记）。`,
+          `- **上面提到的旧块一个字都不许动，也不要试图"修"它们** —— 脏的地方由用户自己决定怎么处理，你只管把本次的内容追加对。`,
+          `- **如果上面提到某个块没闭合**：那说明上次没写完。你**不要替它补 end 标记**，`,
+          `  也不要往它后面再追加 —— 直接把情况报告给用户，让他决定怎么处理。`,
+        ].join('\n') + '\n'
+      : '';
+
+    // 2.3 热度指标说明 —— 主指标 + 辅助指标，各自"代表什么"与"口径注意"。
+    // 只说"有哪些数字"模型会用错，所以每个数字都要说清它的坑。
+    const aux = h.aux || [];
+    const metricRows = [
+      `| **${h.label}**（主指标） | ${h.unit} | \`${h.sampleLine}\` | ${h.role} | ${h.caveat} |`,
+      ...aux.map(a =>
+        `| ${a.label} | ${a.unit} | \`${a.sampleLine}\` | ${a.meaning} | ${a.caveat} |`),
+    ];
+    const scaleNote = aux.length
+      ? `**这 ${metricRows.length} 个数字的量级差极大**（${
+          [h.label, ...aux.map(a => a.label)].join('、')
+        }），**不要把它们相加成一个"热度分"，也不要互相代入占比**。`
+      : `本平台只有这一个热度指标 —— 需求规模、需求份额、头部集中度三项都用它。`;
+    // 参数表里只有"主热度指标"这一行，但 2.3 会列出主指标 + 辅助指标。
+    // 不写清"谁是主、谁只作辅助"，模型会把 4 个数字都当成热度指标。
+    const metricIntro = aux.length
+      ? `本次（${pLabel}）数据文件里的热度指标：**主指标 1 个（${h.label}）+ 辅助指标 ${aux.length} 个（${aux.map(a => a.label).join(' / ')}）**。`
+        + `\n需求规模 / 需求份额 / 头部集中度**只用主指标 ${h.label}**；辅助指标只作交叉验证，不进公式。`
+      : `本次（${pLabel}）数据文件里只有 1 个热度指标（${h.label}），需求规模 / 需求份额 / 头部集中度都用它。`;
+    const heatMetricBlock = [
+      `### 2.3 热度指标说明`,
       ``,
-      `已生成的文件：`,
-      fileList,
+      metricIntro,
       ``,
-      `请执行以下步骤：`,
-      `1. 读取上述生成的**最新**数据文件，**必须**忽略旧文件和对话历史上下文`,
-      `2. 分析爆款书籍的题材、卖点、节奏、人设等特征`,
-      `3. 生成扫榜报告（包含：市场趋势、热门题材分析、用户画像、竞争度评估）`,
-      `4. 给出 3-5 个可行的选题方向建议。为每个方向设计金手指、核心设定、爽点模式、情绪价值曲线、开篇切入点、故事节奏规划、人物设定框架、差异化竞争策略等一系列要素`,
-      `5. 首先检查 \`${topicFile}\` 是否存在。如果该文件不存在则**必须**新建此文件（只新建空文件，不要写内容，也不要写标题）；文件存在后就直接进入第 6 条的四步，把本次分析报告**追加**写入`,
+      `| 指标 | 单位 | 数据文件里的字段 | 代表什么 | 口径注意 |`,
+      `| --- | --- | --- | --- | --- |`,
+      ...metricRows,
       ``,
-      `6. 追加写入的四步，严格按顺序做：`,
+      scaleNote,
+    ].join('\n');
 
-      `- **第一步**：确认 \`${topicFile}\` 这个文件在不在。不在就**先新建一个空文件**（只创建，不要写内容，也不要写标题）`,
-      `- **第二步**：把本次分析报告**追加**到该文件的**末尾**。是追加（append），**不是覆盖**（覆盖会把之前其它平台的分析抹掉）`,
-      `- **第三步**：追加的内容按下面 start/end 标记的格式写`,
-      `- **第四步**：写完后**把文件读回来**确认 start 和 end 标记都写进去了（两个都要有，只写一个会导致平台数据串台）`,
+    // 2.4 其它可用字段 —— 字数 / 标签 / 排名变动。
+    // 这三个字段不是每个平台都有（采集端采到了才会有）。
+    // **按平台列**：起点/七猫压根没有 `**标签：**` 和 `**排名变动：**`，
+    // 把番茄/晋江的坑写给它们看是纯噪声（评审 P1-10）。
+    const otherFieldsBlock = [
+      `### 2.4 其它可用字段`,
       ``,
-      `追加写入时，**必须**用下面这样的 start/end 标记把本次内容与之前的内容隔开（**两个标记都要写**，只写一个会导致平台数据串台）。下面是**格式模板**，请严格照抄标记行的写法：`,
+      `数据文件里**可能**出现下面这些行 —— 本平台的采集端采到了才会有。`,
+      `**出现就记下来，没出现就跳过**（不要因为没有某一行就编一个值）：`,
       ``,
-      `\`\`\``,
-      `# ${pLabel}-${listsStr}-${date || ''}-start`,
-      `（本次分析报告正文，从"一、市场趋势"重新编号）`,
-      `# ${pLabel}-${listsStr}-${date || ''}-end`,
-      `\`\`\``,
-      ``,
-      `标记要求：`,
-      `- 上面代码块只是**格式展示**：写入文件时**只写标记行本身**，不要把代码块的 \`\`\` 围栏一起写进文件`,
-      `- start 与 end 必须**成对出现**，两个标记行都要**独占一行**，行首不要加任何其它文字`,
-      `- 两个标记之间**只放本次平台**的分析内容，不要混入其它平台的内容`,
-      `- 标记里的平台名、榜单名、日期必须与上面写的完全一致（本次是：${pLabel}-${listsStr}-${date || ''}）`,
-      `- 本次追加写入的分析报告内容要**重新开始编号**（从"一、"重新数）`,
-      `- 标记行**不要**加粗、**不要**缩进、**不要**带任何 markdown 装饰符号`,
-      ``,
-      `报告要求：`,
-      `- 客观分析数据，不臆测`,
-      `- 选题建议要有差异化竞争力`,
-      `- 报告语言：中文`,
+      `| 行 | 代表什么 | 怎么用 | 坑 |`,
+      `| --- | --- | --- | --- |`,
+      `| \`**字数：**\` | 作品累计字数 | 反映**体量** —— 老书天然字数大 | **字数不是热度** —— 不可与热度指标相加或代入占比；各平台粒度不同（精确字数 / "647.39万字"），**原样记录** |`,
+      ds.hasTags
+        ? `| \`**标签：**\` | 平台**官方标签** | 统计标签出现频次，可看出题材细分与元素/套路分布 | 番茄：**第一个标签是主分类**（= 文件里的题材组），统计时**跳过它**，否则与题材频次重复计数；晋江：**全是内容标签、没有主分类**。两者的标签都**题材细分与元素套路混在一起**（如"都市/破镜重圆/暗恋"、"无限流/单女主/无脑爽"）—— **原样分组统计，不要自己判断它属于哪类** |`
+        : `| （本平台没有 \`**标签：**\` 行） | — | **不做标签频次分析** —— 没有数据源 | 详见 3.2 的"标签"一条 |`,
+      ds.hasRankChange
+        ? `| \`**排名变动：**\` | 榜页给出的**名次变化**（上升/下降 N 名/持平） | 说明"名次较上次有变动" | **只是一个变化值，不是历史序列** —— 可以说"名次较上次上升 N 位"，**不能推断连续走势** |`
+        : `| （本平台没有 \`**排名变动：**\` 行） | — | **不要写名次变动** —— 没有这个数据源 | — |`,
     ].join('\n');
+
+    // 3.3 里"辅助指标怎么用" —— 只在有辅助指标的平台出现（目前只有起点）。
+    const auxUsageBlock = aux.length
+      ? [
+          `- **辅助指标（${aux.map(a => a.label).join(' / ')}）只作交叉验证，不进上面三项公式** ——`,
+          `  它们的口径和量级都与${h.label}不同（见 2.3），代入占比或相加都得出没有意义的数。用法：`,
+          ...aux.map(a => `  - ${a.usage}`),
+          `  以上都是**同一天、同一批书的横向比较** —— 不能写成"正在上升""持续走高"。`,
+        ]
+      : [];
+
+    // 写前自检里也要有一项：辅助指标没被混用（累计量进份额公式 / 数字相加）。
+    const selfCheckExtra = aux.length
+      ? ` / **${h.label}与辅助指标（${aux.map(a => a.label).join('/')}）没有混用**（累计量没进份额公式、数字没相加）`
+      : '';
+
+    // 3.3 里"排名变动怎么用" —— 只有采集端真的采到 `**排名变动：**` 的平台才写。
+    // 起点/七猫没有这个字段，写给它看只会增加噪声，还会让模型去找不存在的行。
+    const rankChangeRule = ds.hasRankChange
+      ? [
+          `- **数据文件里有 \`**排名变动：**\` 行时**，它说明"名次较上次有变动"（上升/下降 N 名/持平）——`,
+          `  这可以写进结论，但**只能写这一次的变动**："名次较上次上升 N 位"；`,
+          `  **不能**由它推断连续走势（"连续上升""一路走高"）—— 它是单个变化值，不是历史序列。`,
+        ]
+      : [];
+
+    return renderAnalysisPrompt({
+      platform_label: pLabel,
+      rank_lists: listsStr,
+      date: date || '',
+      heat_metric_label: h.label,
+      heat_metric_note: h.note,
+      heat_precision_note: h.precisionNote,
+      heat_sample_value: h.sampleValue,
+      topic_file: topicFile,
+      file_list_block: fileList,
+      project_root: projectRoot,
+      abs_example: absExample,
+      failed_block: failedBlock ? failedBlock + '\n\n' : '',
+      existing_block: existingText,
+      warnings_block: warningsBlock,
+      heat_metric_block: heatMetricBlock,
+      other_fields_block: otherFieldsBlock,
+      preflight_command: preflightCommand,
+      append_command: appendCommand,
+      data_shape_block: blockToText(dataShapeBlock(ds)),
+      dedupe_rule: dedupeRule,
+      tag_rule_block: blockToText(tagRuleBlock(ds)),
+      group_scope: ds.grouped ? '组内' : '榜内',
+      all_group_block: ds.grouped && ds.genreFrom === 'group'
+        ? blockToText([
+            `- **"全部"组是汇总，不是题材** —— 实测它取的是**第一个题材组的前 N 本**，`,
+            `  不是"跨题材的整体前 10"。**不计入题材频次与占比**；`,
+            `  **也不要拿"有多少本进入全部组"当指标** —— 它恒为"某题材 N、其余全 0"，没有区分度`,
+          ])
+        : '',
+      snapshot_scope: multiList ? '、这几个榜单' : '、这一个榜单',
+      list_rule_block: blockToText(listRule),
+      cross_list_block: blockToText(crossListRule),
+      genre_rule_block: blockToText(genreRuleBlock(ds, multiList)),
+      genre_self_check: genreSelfCheck,
+      competition_block: blockToText(competitionBlock(ds, h, multiList)),
+      aux_usage_block: blockToText(auxUsageBlock),
+      rank_change_block: blockToText(rankChangeRule),
+      section_titles_block: SECTION_TITLES.map(t => `- \`## ${t}\``).join('\n'),
+      direction_template_block: directionTemplateBlock(),
+      min_tag_chars: R.minTagChars,
+      min_directions: R.minDirections,
+      max_directions: R.maxDirections,
+      min_cjk_total: R.minCjkTotal.toLocaleString('en-US'),
+      max_cjk_total: R.maxCjkTotal.toLocaleString('en-US'),
+      min_pure_cjk: R.minPureCjk.toLocaleString('en-US'),
+      min_tables: R.minTables,
+      report_headers_block: Object.entries(headers)
+        .map(([k, v]) => `  - **${k === 'topic' ? '题材表' : k === 'competition' ? '竞争度表' : '选题对比表'}**：${v}`)
+        .join('\n'),
+      min_citations: R.minCitations,
+      min_infer_marks: R.minInferMarks,
+      self_check_extra: selfCheckExtra,
+      body_file_quoted: shellSingleQuote(bodyFile),
+      append_script_quoted: shellSingleQuote(appendScript),
+      topic_file_quoted: shellSingleQuote(topicFile),
+      project_root_arg: projectRoot ? `--project-root ${shellSingleQuote(projectRoot)} ` : '',
+      block_id_quoted: shellSingleQuote(blockId),
+      heat_metric_label_quoted: shellSingleQuote(h.label),
+      grouped_flag: ds.grouped ? '--grouped' : '--ungrouped',
+      multi_flag: multiList ? '--multi-list' : '--single-list',
+    });
   },
+
+  // 这些函数在模块顶层定义，index.js 通过 `scan.xxx(...)` 调用。
+  // 之前多次出现“只 export 顶层函数、没挂到 scan 对象上”的问题，
+  // 运行时直接 `TypeError: scan.xxx is not a function`。
+  // 这里统一挂到 scan 对象；测试会扫描 index.js 里所有 `scan.xxx(` 调用，
+  // 逐个断言 typeof === 'function'，防止再漏。
+  dataShape,
+  heatMetric,
+  platformLabel,
+  makeBlockId,
+  bodyFilePath,
 };