@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/lib/topic-decision.js

@@ -0,0 +1,860 @@
+/**
+ * topic-decision.js —— topic_decision_<date>.md 的标记解析、备份与恢复
+ *
+ * ## 为什么需要这个模块
+ *
+ * topic_decision_<date>.md 是**多个平台共用的一个文件**：番茄扫一次追加一段，
+ * 起点扫一次再追加一段。写这个文件的是 LLM（插件把提示词投递给 LLM，
+ * LLM 自己落盘），插件侧并没有代码在写它。
+ *
+ * 这么设计有个硬伤：**"追加"这个语义被委托给了 LLM，而 LLM 的写文件工具
+ * （write）是覆盖语义**。实测（2026-10-27，tt5 项目）：
+ *
+ *   turn 4（起点）：write(topic_decision, "") → cat >> 追加起点分析   ✅
+ *   turn 5（番茄）：write(topic_decision, "") → cat >> 追加番茄分析   ❌
+ *
+ * 第二轮的 write("") 把第一轮的起点分析整个清空了 —— 最终文件里只剩番茄，
+ * 起点的分析**无声无息地丢了**，全程没有任何报错。成因是提示词里那句
+ * "新建一个空文件"：模型为了"新建"就去调 write 工具，而 write 空内容
+ * 等于清空文件。
+ *
+ * 光靠提示词约束模型守规矩是不够的 —— 同一个文件被覆盖两次，内容就没了。
+ * 所以这里做三件事：
+ *   1. parseMarkerBlocks —— 解析文件里的 start/end 标记块；
+ *   2. backupTopicDecision —— 写入前备份（覆盖后还能救回来）；
+ *   3. repairTopicDecision —— 消费前校验，把被覆盖掉的块自动补回。
+ *
+ * ## 为什么标记解析单独放这里
+ *
+ * fancy-topic 自己有一套切块逻辑（splitDecisionSections），那套**刻意容忍**
+ * LLM 漏写 -end 标记（配对切块会一路吞到下一个 -end，把别的平台的分析
+ * 一起带走）。但校验"某个平台的段落还在不在"需要**严格**认标记对，
+ * 两套语义不一样，所以这里另起一套，不去动 fancy-topic 那套。
+ */
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { randomBytes } from 'crypto';
+import { atomicWriteFile as atomicWriteFileShared } from '#atomic-write';
+import { missingDirectionLabels } from '#direction-labels';
+
+const REVISIONS_DIR = '.revisions';
+
+/**
+ * 原子写文件：先写同目录的临时文件，再 rename 覆盖。
+ *
+ * 直接 writeFileSync 覆盖写，进程写到一半被杀（OOM / 磁盘满 / 用户 Ctrl-C）
+ * 会把文件截断 —— 对 topic_decision 来说就是**整份分析报告没了**，
+ * 而且这种损坏往往发生在用户最不想丢数据的时候。
+ *
+ * rename 在同一文件系统内是原子的：要么还是旧内容，要么已经是新内容，
+ * 不会出现"半个文件"。
+ *
+ * @param {string} file
+ * @param {string} content
+ */
+function atomicWriteFile(file, content) {
+  // 具体实现（随机临时名 + wx + rename + fsync）在 lib/atomic-write.js；
+  // 这里保留同名包装，避免外部调用点和测试切片漂移。
+  atomicWriteFileShared(file, content);
+}
+
+/** 标题行（markdown 标题，1~6 级） */
+const TITLE_RE = /^[ \t]*#{1,6}[ \t]*(.+?)[ \t]*$/;
+/**
+ * -start / -end 后缀（允许全角/半角连字符与空格）。
+ *
+ * **分隔符是必需的**（2026-10-29 审计）：
+ * 原来的 `[-—–\s]*start\s*$` 里 `[-—–\s]*` 能匹配**零个字符**，
+ * 于是任何以 "start" 结尾的标题都会被当成标记行 ——
+ * `### Restart`、`## Trend` 这类正常标题会凭空变成一个 key 为 "Re" / "T"
+ * 的块，把文件结构搅乱。
+ *
+ * 现在要求 start/end 前面是行首或一个分隔符（连字符 / 破折号 / 空白）。
+ */
+const START_SUFFIX_RE = /(?:^|[-—–\s])start\s*$/i;
+const END_SUFFIX_RE = /(?:^|[-—–\s])end\s*$/i;
+
+/**
+ * 解析 topic_decision 文件里的标记块。
+ *
+ * 一个"块"从 `-start` 标题行开始，到 `-end` 标题行结束。
+ * 缺 -end 的块也会返回（closed: false）—— 那是 LLM 漏标记，
+ * 但内容还在，不能当成丢了。
+ *
+ * @param {string} content 文件内容
+ * @returns {Array<{key: string, startTitle: string, endTitle: string|null,
+ *                  closed: boolean, text: string}>}
+ */
+export function parseMarkerBlocks(content) {
+  const lines = String(content || '').split('\n');
+  const blocks = [];
+  let cur = null;
+
+  for (const line of lines) {
+    const m = line.match(TITLE_RE);
+    if (!m) {
+      if (cur) cur.lines.push(line);
+      continue;
+    }
+    const title = m[1].trim();
+
+    if (START_SUFFIX_RE.test(title)) {
+      // 上一个块没闭合就又来一个 start —— 先收尾，别把两段混成一块
+      if (cur) blocks.push(cur);
+      cur = {
+        key: title.replace(START_SUFFIX_RE, '').trim(),
+        startTitle: title,
+        endTitle: null,
+        closed: false,
+        lines: [line],
+      };
+      continue;
+    }
+
+    if (END_SUFFIX_RE.test(title)) {
+      const endKey = title.replace(END_SUFFIX_RE, '').trim();
+      // **end 的 key 必须和 start 的 key 一样**（2026-10-29 审计）。
+      // 之前不校验，于是 `# 番茄-…-end` 能把 `# 起点-…-start` 开的块闭合掉 ——
+      // 起点那块变成"已闭合"，番茄那块凭空出现，文件结构全错。
+      // key 对不上时，这一行按**正文**处理（当前块不闭合）。
+      if (cur && endKey === cur.key) {
+        cur.endTitle = title;
+        cur.closed = true;
+        cur.lines.push(line);
+        blocks.push(cur);
+        cur = null;
+      } else if (cur) {
+        cur.lines.push(line);
+      }
+      // 没有对应 start 的 end 标记：忽略（不构成一个块）
+      continue;
+    }
+
+    if (cur) cur.lines.push(line);
+  }
+  if (cur) blocks.push(cur);
+
+  return blocks.map(b => ({
+    key: b.key,
+    startTitle: b.startTitle,
+    endTitle: b.endTitle,
+    closed: b.closed,
+    text: b.lines.join('\n'),
+  }));
+}
+
+/**
+ * 文件里已有的标记块清单（去重，按出现顺序）。
+ *
+ * @param {string} content
+ * @returns {Array<{key: string, startTitle: string, endTitle: string|null, closed: boolean}>}
+ */
+export function listMarkerBlocks(content) {
+  const seen = new Set();
+  const out = [];
+  for (const b of parseMarkerBlocks(content)) {
+    if (seen.has(b.key)) continue;
+    seen.add(b.key);
+    out.push({
+      key: b.key,
+      startTitle: b.startTitle,
+      endTitle: b.endTitle,
+      closed: b.closed,
+    });
+  }
+  return out;
+}
+
+/**
+ * 把 topic_decision 里**同一个 key 的重复块**收敛成一个：保留最后一个，删掉前面的。
+ *
+ * ## 为什么留最后一个
+ *
+ * 与 topic 侧的去冗余规则同向（`selectNonRedundantBlocks`：**后出现的覆盖先出现的**）——
+ * 插件在别处已经按这个规则取内容了，文件这边收敛成同一个结果，
+ * 不会出现"文件里留的是 A、插件读的是 B"的分裂。
+ *
+ * ## 什么时候会重复
+ *
+ * 实测（2026-10-28 tt5）：heredoc 缺结束符 `FANCY_SCAN_EOF`，
+ * shell 把后面的校验命令也当成正文；模型发现后用 edit 清理，**又重写了一遍** ——
+ * 文件里同一个平台于是有了两份报告。
+ *
+ * 模型看不见自己写进去的东西，所以只能插件来收敛。
+ *
+ * ## 只动闭合的块
+ *
+ * 没闭合的块（只有 start 没有 end）本身就是坏的，自动删它有可能把
+ * 别的内容一起带走 —— 那部分只报告，不动。
+ *
+ * @param {string} topicFile
+ * @returns {{ok: boolean, removed: Array<{key: string, lines: string}>,
+ *            kept: number, reason: string|null}}
+ */
+export function dedupeMarkerBlocks(topicFile) {
+  const empty = { ok: true, removed: [], kept: 0, reason: null };
+  if (!topicFile || !existsSync(topicFile)) return { ...empty, reason: '文件不存在' };
+
+  let content;
+  try {
+    content = readFileSync(topicFile, 'utf-8');
+  } catch (e) {
+    return { ...empty, reason: '读文件失败：' + (e && e.message ? e.message : String(e)) };
+  }
+
+  const lines = content.split('\n');
+  const blocks = [];
+  let cur = null;
+  lines.forEach((line, i) => {
+    const m = line.match(TITLE_RE);
+    if (!m) return;
+    const title = m[1].trim();
+    if (START_SUFFIX_RE.test(title)) {
+      if (cur) blocks.push(cur);
+      cur = {
+        key: title.replace(START_SUFFIX_RE, '').trim(),
+        start: i, end: null, closed: false,
+      };
+      return;
+    }
+    if (END_SUFFIX_RE.test(title)) {
+      // end 的 key 必须和 start 一样，否则不闭合（见 parseMarkerBlocks）
+      const endKey = title.replace(END_SUFFIX_RE, '').trim();
+      if (cur && endKey === cur.key) {
+        cur.end = i;
+        cur.closed = true;
+        blocks.push(cur);
+        cur = null;
+      }
+    }
+  });
+  if (cur) blocks.push(cur);
+  // 未闭合的块：算出它实际到哪一行（到下一个块之前 / 文件末尾）
+  for (let i = 0; i < blocks.length; i++) {
+    if (blocks[i].closed) continue;
+    blocks[i].end = blocks[i + 1] ? blocks[i + 1].start - 1 : lines.length - 1;
+  }
+
+  const byKey = new Map();
+  for (const b of blocks) {
+    if (!byKey.has(b.key)) byKey.set(b.key, []);
+    byKey.get(b.key).push(b);
+  }
+
+  const drop = new Set();
+  const removed = [];
+  for (const [key, list] of byKey) {
+    if (list.length < 2) continue;
+    // 保留策略（2026-10-29 审计）：**优先保留闭合的块**。
+    // 之前固定取最后一个 —— 如果最后一个只有 start 没有 end，
+    // 前面的**完整闭合块反而被删掉**，文件里留下的是截断内容。
+    const closed = list.filter(b => b.closed);
+    // 一个都没闭合 → 不动（可能是有意留的半成品，宁可报告也不删）
+    if (!closed.length) continue;
+    const keep = closed[closed.length - 1];
+    for (const b of list) {
+      if (b === keep) continue;
+      for (let i = b.start; i <= b.end; i++) drop.add(i);
+      removed.push({ key, lines: `${b.start + 1}-${b.end + 1}` });
+    }
+  }
+  if (!removed.length) return { ...empty, kept: byKey.size };
+
+  const kept = lines.filter((_, i) => !drop.has(i)).join('\n');
+  try {
+    atomicWriteFile(topicFile, kept);
+  } catch (e) {
+    return { ...empty, reason: '写回失败：' + (e && e.message ? e.message : String(e)) };
+  }
+  return { ok: true, removed, kept: byKey.size, reason: null };
+}
+
+/**
+ * 查 topic_decision 里的"脏"痕迹。
+ *
+ * 这三种都是**模型自己写文件写歪了**的症状，插件必须能自己发现 ——
+ * 模型看不见自己写进去的东西，它只会"照着提示词再来一次"。
+ *
+ *   1. **同一个 key 出现多个块** —— 追加写重了。
+ *      实测（2026-10-28 tt5）：heredoc 少了结束符 `FANCY_SCAN_EOF`，
+ *      shell 把后面的校验命令也当成正文；模型发现后用 edit 清理，
+ *      又重写了一遍 —— 文件里于是有了两份同一个平台的报告。
+ *   2. **块里混进了命令** —— 模型把校验命令（`grep -c` / `cat >>`）
+ *      当成正文写了进去。
+ *   3. **块没闭合** —— 只有 `-start` 没有 `-end`。
+ *      实测（2026-10-28 tt5）：正文里出现了单独一行 `FANCY_SCAN_EOF`，
+ *      heredoc 被提前终止，shell 只把 start 行和第一段正文写了进去，
+ *      `-end` 标记**根本没写进文件**（`start=1 / end=0`）。
+ *      这种块的内容是**被截断的**，而且它会让下一次同平台的计数 N ≥ 1，
+ *      把重扫挡在门外 —— 用户不处理就再也扫不了这个平台了。
+ *
+ * ## 为什么第 3 种只报告、不自动补 end 标记
+ *
+ * 自动补一行 `-end` 看起来无害，实际上会把**被截断的内容伪装成完整的** ——
+ * 用户以为那段分析写完了，其实正文只写了一半。
+ * 截断这件事必须让用户看见，所以只报告。
+ *
+ * @param {string} content 文件内容
+ * @returns {{duplicateKeys: Array<{key: string, count: number}>,
+ *            commandLines: Array<{key: string, line: number, text: string}>,
+ *            unclosedBlocks: Array<{key: string, startTitle: string}>}}
+ */
+export function inspectTopicDecision(content) {
+  const blocks = parseMarkerBlocks(content);
+  const countByKey = new Map();
+  for (const b of blocks) {
+    countByKey.set(b.key, (countByKey.get(b.key) || 0) + 1);
+  }
+  const duplicateKeys = [...countByKey.entries()]
+    .filter(([, n]) => n > 1)
+    .map(([key, count]) => ({ key, count }));
+
+  // 没闭合的块：只有 start 标记、没有 end 标记。
+  // 提示词里的 5.3 校验（start=1 但 end≠1）管的是"本次写入"，
+  // 这里管的是**文件里已经存在的**坏块 —— 模型自己看不见，只能插件查。
+  const unclosedBlocks = blocks
+    .filter(b => !b.closed)
+    .map(b => ({ key: b.key, startTitle: b.startTitle }));
+
+  // 命令痕迹：只认足够特异的命令形式，别把正文里的普通词误伤
+  const CMD_RE = [
+    /^\s*grep\s+-c\s+\S/,          // grep -c '...' "..."
+    /^\s*cat\s+>>?\s+\S/,          // cat >> "..." / cat > "..."
+    /^\s*FANCY_SCAN_(?:BODY_)?EOF\s*$/, // heredoc 结束符漏到正文里
+    /^\s*node\s+references\/\S/,   // node references/xxx.js
+    /^\s*set\s+-e\s*$/,            // set -e
+    /^\s*FILE\s*=\s*\S/,           // FILE="..."
+    /^\s*```(?:bash|sh)?\s*$/,     // 代码块围栏漏进正文
+  ];
+  // 扫**全文**，不只扫块内 ——
+  // 实测（2026-10-28 tt5）：heredoc 缺结束符时，shell 把后面的校验命令
+  // 当成正文，而那些命令落在 end 标记**之后**，根本不在任何块里。
+  const commandLines = [];
+  const lines = String(content || '').split('\n');
+  const blockOf = new Map();
+  blocks.forEach((b) => {
+    for (const l of String(b.text || '').split('\n')) blockOf.set(l, b.key);
+  });
+  let currentKey = null;
+  lines.forEach((line, li) => {
+    const m = line.match(TITLE_RE);
+    if (m) {
+      const title = m[1].trim();
+      if (START_SUFFIX_RE.test(title)) currentKey = title.replace(START_SUFFIX_RE, '').trim();
+      else if (END_SUFFIX_RE.test(title)) currentKey = null;
+      return; // 标记行本身不算命令痕迹
+    }
+    if (CMD_RE.some((re) => re.test(line))) {
+      commandLines.push({ key: currentKey, line: li + 1, text: line.trim() });
+    }
+  });
+
+  return { duplicateKeys, commandLines, unclosedBlocks };
+}
+
+/**
+ * 检查一个内容块的正文**是不是真的写进去了**。
+ *
+ * ## 为什么需要这个
+ *
+ * start/end 标记只能证明"块在文件里"，不能证明"块里有分析"。
+ * 实测（2026-10-28）：模型把 5.2 的 heredoc 命令原样跑了一遍 ——
+ * `<本次正文>` 这个占位符**原封不动地进了文件**，而 start/end 两个标记
+ * 都写对了。于是：
+ *
+ *   - scan 侧的校验读到 start = 1 且 end = 1 → 判定"写入成功"；
+ *   - topic 侧也不检查正文 → 这段占位文字被原样发给 LLM 做选题；
+ *   - 选题结论建立在"字都没写"的块上，最后一路流进整个小说项目。
+ *
+ * 模型**看不见自己写进去的东西**，它只会说"我写好了"。
+ * 所以这个判定必须由插件来做 —— 而且插件完全算得出来。
+ *
+ * ## 判据分两档
+ *
+ * **确凿的失败（blocks 判定，会拦住派发）**：
+ *   1. 正文里还留着 `<本次正文>` 占位符 —— 内容没替换进去；
+ *   2. 正文去掉标记行后是空的 —— 只写了标记没写内容；
+ *   3. 正文只剩命令痕迹（grep / cat >> / 围栏）—— 写进去的是命令不是分析。
+ *
+ * **可疑但不确凿（warnings 判定，只提示不拦）**：
+ *   · 正文偏短（< 200 字）；
+ *   · 没有"一、二、三…"这样的结构标题。
+ *
+ * 后两条**不拦**：报告本来就可能短、结构标题写法也可能因平台而异。
+ * 把"我觉得这不合格"当成"这是坏的"，会误伤正常内容 —— 所以只提示。
+ *
+ * @param {string} body 块的正文（不含 start/end 标记行）
+ * @returns {{ok: boolean, reasons: string[], warnings: string[]}}
+ */
+export function inspectBlockBody(body) {
+  const text = String(body || '');
+  const reasons = [];
+  const warnings = [];
+
+  if (/<本次正文>/.test(text)) {
+    reasons.push('正文里还留着 `<本次正文>` 占位符 —— 内容没替换进去');
+  }
+
+  // 去掉标记行、代码围栏与空白后，看还剩多少实质内容
+  const stripped = text
+    .split('\n')
+    .filter(l => !/^\s*#\s*[^\n]*-(start|end)\s*$/i.test(l))
+    .filter(l => !/^\s*(```|~~~)/.test(l))
+    .join('')
+    .replace(/\s+/g, '');
+
+  if (!stripped) {
+    reasons.push('正文是空的 —— 只写了标记行，没有内容');
+  } else {
+    // 只剩命令痕迹 = 写进去的是命令，不是分析
+    const cmdOnly = text
+      .split('\n')
+      .filter(l => l.trim())
+      .filter(l => !/^\s*#\s*[^\n]*-(start|end)\s*$/i.test(l))
+      .every(l => /^\s*(grep\s+-c|cat\s+>>?|FANCY_SCAN_(?:BODY_)?EOF|```|node\s+references\/)/.test(l));
+    if (cmdOnly) {
+      reasons.push('正文里只剩命令痕迹（grep / cat >> 之类）—— 写进去的是命令，不是分析');
+    }
+  }
+
+  // 方向标题格式是**固定**的（`### 方向 N：名称`），所以数不出来就是确凿的问题，
+  // 不像"结构标题"那样还能只是格式差异。
+  const dirCount = (text.match(/^###\s*方向\s*[0-9]+\s*[:：]/gm) || []).length;
+  if (stripped && dirCount > 0 && dirCount < 3) {
+    reasons.push(`正文里只有 ${dirCount} 个方向标题（要求至少 3 个）—— 报告没写全`);
+  }
+
+  if (stripped.length < 200) {
+    warnings.push(`正文只有 ${stripped.length} 个字（不到 200 字），内容可能偏薄`);
+  }
+
+  // 11 项设计标签是**固定**的（见 #direction-labels）——
+  // 缺标签的方向是"空壳方向"，下游 story-builder 拿到的是残缺输入。
+  // 提示词里已经要求写全，插件这边再查一遍是**兜底**（提示词是请求，检查才是保证）。
+  // 只告警、不判块失败：格式差异不该把一整块报告判死。
+  if (dirCount > 0) {
+    const missing = missingDirectionLabels(text);
+    if (missing.length) {
+      warnings.push(
+        `有 ${missing.length} 个方向缺 11 项设计标签（${missing.join('；')}）`
+        + ' —— 标签要写成 `- **定位**：…` 这种形式，11 项都要齐'
+      );
+    }
+  }
+
+  if (stripped && !/^#{1,6}\s*[一二三四五六七]、/m.test(text)) {
+    warnings.push('正文里没有"一、二、三…"这样的结构标题，报告可能不完整');
+  }
+
+  return { ok: reasons.length === 0, reasons, warnings };
+}
+
+/**
+ * 检查文件里**每个块**的正文是否有效。
+ *
+ * @param {string} content 文件内容
+ * @returns {{key: string, startTitle: string, reasons: string[], warnings: string[]}[]}
+ *          只返回有问题的块
+ */
+export function inspectBlockBodies(content) {
+  const out = [];
+  for (const b of parseMarkerBlocks(content)) {
+    // 去掉 start/end 标记行，只留正文
+    const body = b.text
+      .split('\n')
+      .filter(l => !/^\s*#\s*[^\n]*-(start|end)\s*$/i.test(l))
+      .join('\n');
+    const res = inspectBlockBody(body);
+    if (!res.ok || res.warnings.length) {
+      out.push({
+        key: b.key,
+        startTitle: b.startTitle,
+        reasons: res.reasons,
+        warnings: res.warnings,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 确保 topic_decision 文件以换行结尾。
+ *
+ * ## 为什么需要这个
+ *
+ * `cat >> file` 是**裸追加** —— 它不会在前面补换行。
+ * 所以文件末尾如果没有换行符，新追加的内容会**粘在旧行尾**：
+ *
+ *   文件末尾：  …正文最后一行        （没有换行）
+ *   追加内容：  # 番茄-男频阅读榜-20261028-start\n…
+ *   结果：      …正文最后一行# 番茄-男频阅读榜-20261028-start\n…
+ *
+ * 后果不是"看着别扭"，而是**功能性的坏**：
+ * `grep -c '^# 番茄-男频阅读榜-20261028-start$'` 匹配不到（标记行不在行首），
+ * 于是 5.3 的校验读到 start = 0 → 模型以为"标记没写进去" → **再执行一次写入**
+ * → 同一个平台两个 start 标记 → 写重了。
+ *
+ * 也就是说，"文件末尾缺一个换行"会**引爆「写重了」事故链**。
+ * 这件事模型没法自己知道（它看不见文件末尾有没有换行），
+ * 而且插件能自己算出来 —— 所以由插件在派发前补上。
+ *
+ * 只在**确实缺换行**时才写文件；文件不存在或已经以换行结尾时什么都不做。
+ *
+ * @param {string} topicFile topic_decision_<date>.md 的绝对路径
+ * @returns {{ok: boolean, fixed: boolean, reason: string|null}}
+ */
+export function ensureTrailingNewline(topicFile) {
+  const empty = { ok: true, fixed: false, reason: null };
+  if (!topicFile || !existsSync(topicFile)) return { ...empty, reason: '文件不存在' };
+
+  let content;
+  try {
+    content = readFileSync(topicFile, 'utf-8');
+  } catch (e) {
+    return { ...empty, reason: '读文件失败：' + (e && e.message ? e.message : String(e)) };
+  }
+
+  if (!content) return { ...empty, reason: '文件是空的' };
+  if (content.endsWith('\n')) return { ...empty, reason: null };
+
+  try {
+    atomicWriteFile(topicFile, content + '\n');
+  } catch (e) {
+    return { ...empty, reason: '写回失败：' + (e && e.message ? e.message : String(e)) };
+  }
+  return { ok: true, fixed: true, reason: null };
+}
+
+/**
+ * 解析块标题里的"榜单范围"与"日期"。
+ *
+ * 标记行的格式是 `# 平台-榜单列表-日期-start`：
+ *
+ *   # 起点-全选-20261027-start
+ *   # 起点-新书榜、新人作者榜-20261027-start
+ *
+ * 平台名和榜单列表都不含 '-'，日期是 8 位数字，所以按 '-' 分三段即可。
+ *
+ * 解析不出来（LLM 没写标准标记、标题是散文、日期不是 8 位数字……）时
+ * 返回 null —— 调用方据此**保守地保留**该块，不做冗余判断。
+ * 宁可多发一块给 LLM，也不要凭空吞掉用户的数据。
+ *
+ * @param {string} title - 块的首个标题（可带 '# ' 前缀与 -start/-end 后缀）
+ * @returns {{lists: string[], date: string, isAll: boolean}|null}
+ */
+export function parseBlockMeta(title) {
+  const raw = String(title || '')
+    .trim()
+    .replace(/^#+\s*/, '')
+    .replace(/[-—–\s]*start\s*$/i, '')
+    .replace(/[-—–\s]*end\s*$/i, '')
+    .trim();
+  if (!raw) return null;
+
+  const parts = raw.split('-');
+  if (parts.length < 3) return null;
+
+  const date = parts[parts.length - 1];
+  if (!/^\d{8}$/.test(date)) return null;
+
+  const lists = parts[parts.length - 2]
+    .split('、')
+    .map(s => s.trim())
+    .filter(Boolean);
+  if (!lists.length) return null;
+
+  return { lists, date, isAll: lists.length === 1 && lists[0] === '全选' };
+}
+
+/**
+ * 榜单集合的包含关系：outer 的榜单范围是否**覆盖** inner。
+ *
+ * "全选"是该平台的**全部**榜单，所以覆盖任何子集；
+ * 反过来，窄的范围覆盖不了"全选"。
+ *
+ * @param {{lists: string[], isAll: boolean}} outer
+ * @param {{lists: string[], isAll: boolean}} inner
+ * @returns {boolean}
+ */
+function scopeCovers(outer, inner) {
+  if (!outer || !inner) return false;
+  if (outer.isAll) return true;
+  if (inner.isAll) return false;
+  return inner.lists.every(l => outer.lists.includes(l));
+}
+
+/**
+ * 从同平台的若干块里，挑出**该发给 LLM 的那些**（去掉冗余块）。
+ *
+ * ## 问题
+ *
+ * 同一个平台一天里可能被扫多次，每次追加一个标记块：
+ *
+ *   # 起点-新书榜、新人作者榜-20261027-start   ← 先扫了 2 个榜单
+ *   # 起点-全选-20261027-start                 ← 后来扫了全部榜单
+ *
+ * 两块都留在文件里（数据不丢，这是对的），但 /fancy-topic 选"起点"时
+ * 会把两块**一起**发给 LLM —— 后一次扫描重新采集了同样的榜单文件
+ * （起点新书榜_20261027.md 被覆盖成新的一份），前一块的分析既陈旧
+ * 又被完全覆盖，同一批数据会被统计两遍。
+ *
+ * ## 去冗余规则（**按文件里的先后顺序**）
+ *
+ * 后出现的块覆盖先出现的块时，先出现的块冗余：
+ *
+ *   先 起点-新书榜、新人作者榜  后 起点-全选   → 丢前块（全选重采过新书榜）
+ *   先 起点-全选              后 起点-签约榜   → 两块都留
+ *
+ * 第二种情况**不能**丢：后扫的"签约榜"是另一次独立采集（榜单快照、
+ * 采集时间都不同），不是"全选"的子集 —— 早先那次全选里对签约榜的
+ * 分析用的还是旧数据，而且全选还包含签约榜之外的其它榜单，两块都有价值。
+ * 不看顺序、只看"范围包含"的规则会把它误删，打破了"同平台多块都要
+ * 发给 LLM"这条用户报过的需求。
+ *
+ * 同 key 重复（同平台 + 同榜单 + 同日期）也由这条规则覆盖：
+ * 后一次扫描重采了同样的文件，前一块同样陈旧。
+ *
+ * ## 保守边界
+ *
+ *   · 日期不同 → 不是冗余（数据来自不同天的榜单文件），两块都留；
+ *   · 榜单集合互不包含 → 不是冗余，两块都留；
+ *   · 解析不出标题元信息 → 保留（宁可多发，不可凭猜删数据）。
+ *
+ * @param {Array} items - 待筛选的块
+ * @param {(item:any)=>string} [getTitle] - 取块标题的函数。
+ *        不传时按块自身的两种常见形态取：
+ *        `startTitle`（lib 里的标记块）或 `headers[0]`（fancy-topic 的切段结果）。
+ * @returns {{kept: Array, dropped: Array<{item:any, title:string, reason:string}>}}
+ */
+export function selectNonRedundantBlocks(items, getTitle) {
+  const list = Array.isArray(items) ? items : [];
+  const titleOf = typeof getTitle === 'function'
+    ? getTitle
+    : (it) => {
+        if (!it) return '';
+        if (it.startTitle) return it.startTitle;
+        if (Array.isArray(it.headers) && it.headers.length) return it.headers[0];
+        return '';
+      };
+
+  const metas = list.map((it, i) => {
+    const title = String(titleOf(it) || '');
+    return { i, it, title, meta: parseBlockMeta(title) };
+  });
+
+  /** index → 去冗余理由 */
+  const dropReason = new Map();
+
+  // 后出现的块覆盖先出现的块时，先出现的那块冗余 ——
+  //
+  // "覆盖"指后一次扫描**重新采集了同样的榜单文件**
+  // （起点新书榜_20261027.md 被覆盖成新的一份），所以先扫的那块分析
+  // 用的数据已经陈旧，而且结论被完全覆盖 —— 同一批数据会被统计两遍。
+  //
+  // 顺序是关键：不看顺序、只看"范围包含"会误删。
+  //   先 起点-新书榜、新人作者榜  后 起点-全选  → 丢前块（全选重采过新书榜）
+  //   先 起点-全选              后 起点-签约榜  → 两块都留
+  // 第二种不能丢：后扫的"签约榜"是另一次独立采集（榜单快照、采集时间
+  // 都不同），不是"全选"的子集；而且全选里对签约榜的分析用的是旧数据，
+  // 还包含签约榜之外的其它榜单 —— 两块都有价值。
+  //
+  // 同 key 重复（同平台+同榜单+同日期）也由这条规则覆盖。
+  for (const early of metas) {
+    if (!early.meta || dropReason.has(early.i)) continue;
+    for (const late of metas) {
+      if (late.i <= early.i || !late.meta) continue;
+      if (early.meta.date !== late.meta.date) continue;
+      if (!scopeCovers(late.meta, early.meta)) continue;
+      dropReason.set(
+        early.i,
+        `后扫的「${late.title}」重新采集了同样的榜单，覆盖了前面这块`
+      );
+      break;
+    }
+  }
+
+  const kept = [];
+  const dropped = [];
+  for (const m of metas) {
+    const reason = dropReason.get(m.i);
+    if (reason) {
+      dropped.push({ item: m.it, title: m.title, reason });
+    } else {
+      kept.push(m.it);
+    }
+  }
+  return { kept, dropped };
+}
+
+/**
+ * 备份 topic_decision 文件。
+ *
+ * 备份放在 `<扫榜结果>/.revisions/topic_decision_<日期>-<时间戳>.md`。
+ * 目录名以 `.` 开头，且备份文件名不匹配 `topic_decision_\d{8}.md`，
+ * 所以既不会被 fancy-topic 当成可选的决策文件，也不会被扫榜产物识别
+ * 当成平台文件。
+ *
+ * 文件不存在时不备份（第一次扫，没有可丢的东西）。
+ *
+ * @param {string} topicFile topic_decision_<date>.md 的绝对路径
+ * @returns {{backupPath: string|null, bytes: number}}
+ */
+export function backupTopicDecision(topicFile) {
+  if (!topicFile || !existsSync(topicFile)) return { backupPath: null, bytes: 0 };
+  let content;
+  try {
+    content = readFileSync(topicFile, 'utf-8');
+  } catch {
+    return { backupPath: null, bytes: 0 };
+  }
+  if (!content.trim()) return { backupPath: null, bytes: 0 };
+
+  const dir = join(dirname(topicFile), REVISIONS_DIR);
+  try {
+    // `.revisions` 是项目根下的可写目录：如果它是指向项目外的符号链接，
+    // 备份会把整份报告写到外面去。拒绝符号链接，宁可不备份（调用方会
+    // 因为 backupPath=null 而跳过自动去重）。
+    try {
+      const st = lstatSync(dir);
+      if (st.isSymbolicLink()) return { backupPath: null, bytes: 0 };
+      if (!st.isDirectory()) return { backupPath: null, bytes: 0 };
+    } catch { /* 目录不存在，下面 mkdir */ }
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return { backupPath: null, bytes: 0 };
+  }
+
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..*$/, '').replace('T', '-');
+  const name = basename(topicFile).replace(/\.md$/, '');
+  // 同一秒内可能连续备份两次（修复前 / 去重前）；加随机后缀避免互相覆盖。
+  const backupPath = join(dir, `${name}-${stamp}-${randomBytes(3).toString('hex')}.md`);
+  try {
+    atomicWriteFile(backupPath, content);
+  } catch {
+    return { backupPath: null, bytes: 0 };
+  }
+  return { backupPath, bytes: Buffer.byteLength(content, 'utf-8') };
+}
+
+/**
+ * 列出 topic_decision 的备份，按时间从新到旧。
+ *
+ * @param {string} topicFile
+ * @returns {string[]}
+ */
+export function listBackups(topicFile) {
+  const dir = join(dirname(topicFile || ''), REVISIONS_DIR);
+  if (!topicFile || !existsSync(dir)) return [];
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const prefix = basename(topicFile).replace(/\.md$/, '') + '-';
+  return names
+    .filter(n => n.startsWith(prefix) && n.endsWith('.md'))
+    .map(n => join(dir, n))
+    .filter(p => {
+      try {
+        return statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    })
+    .sort()
+    .reverse();
+}
+
+/**
+ * 校验并修复 topic_decision 文件。
+ *
+ * 逻辑：拿最新的备份和当前文件比 —— 备份里有、当前文件里没有的标记块，
+ * 说明那段内容被后来的写入**覆盖**掉了（模型用 write 清空重写），
+ * 自动把丢失的块补回文件末尾。
+ *
+ * @param {string} topicFile topic_decision_<date>.md 的绝对路径
+ * @returns {{ok: boolean, repaired: string[], missingNow: string[],
+ *            fromBackup: string|null, reason: string|null}}
+ */
+export function repairTopicDecision(topicFile) {
+  const empty = { ok: true, repaired: [], missingNow: [], fromBackup: null, reason: null };
+  if (!topicFile || !existsSync(topicFile)) return { ...empty, reason: '文件不存在' };
+
+  let current;
+  try {
+    current = readFileSync(topicFile, 'utf-8');
+  } catch (e) {
+    return { ...empty, reason: '读文件失败：' + (e && e.message ? e.message : String(e)) };
+  }
+
+  const backups = listBackups(topicFile);
+  if (backups.length === 0) {
+    return { ...empty, reason: '没有备份可比对（第一次扫，或备份已清理）' };
+  }
+
+  let backupContent = null;
+  let usedBackup = null;
+  for (const b of backups) {
+    try {
+      const c = readFileSync(b, 'utf-8');
+      if (!c.trim()) continue;
+      backupContent = c;
+      usedBackup = b;
+      break;
+    } catch {
+      continue;
+    }
+  }
+  if (!backupContent) return { ...empty, reason: '备份都读不出来' };
+
+  // 按**块级**判断丢了什么（2026-10-29 审计）。
+  //
+  // 之前只看 key 在不在：同一个 key 的块被**截断**（只剩标题和两行）时，
+  // key 仍然存在 → 不算 lost → 不会从备份恢复。
+  // 现在同 key 也要比大小：当前块明显比备份块小 → 判定为被截断，一并补回。
+  //
+  // 补回后会出现两个同 key 的块 —— 那没关系，
+  // 下游的 dedupeMarkerBlocks 会收敛（保留闭合的那个）。
+  const currentBlocks = parseMarkerBlocks(current);
+  const currentByKey = new Map();
+  for (const b of currentBlocks) {
+    if (!currentByKey.has(b.key)) currentByKey.set(b.key, []);
+    currentByKey.get(b.key).push(b);
+  }
+  const backupBlocks = parseMarkerBlocks(backupContent);
+  const lost = backupBlocks.filter(b => {
+    const cur = (currentByKey.get(b.key) || [])[0];
+    if (!cur) return true;                       // 整个块没了
+    if (!b.text) return false;
+    // 当前块不到备份块的一半 → 被截断
+    return cur.text.length < b.text.length * 0.5;
+  });
+
+  if (lost.length === 0) {
+    return { ok: true, repaired: [], missingNow: [], fromBackup: usedBackup, reason: null };
+  }
+
+  // 把丢失的块补回文件末尾
+  const addition = '\n\n' + lost.map(b => b.text).join('\n\n') + '\n';
+  try {
+    atomicWriteFile(topicFile, current.replace(/\s*$/, '') + addition);
+  } catch (e) {
+    return {
+      ok: false,
+      repaired: [],
+      missingNow: lost.map(b => b.key),
+      fromBackup: usedBackup,
+      reason: '补写失败：' + (e && e.message ? e.message : String(e)),
+    };
+  }
+
+  return {
+    ok: true,
+    repaired: lost.map(b => b.key),
+    missingNow: lost.map(b => b.key),
+    fromBackup: usedBackup,
+    reason: null,
+  };
+}