@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-topic/index.js

@@ -0,0 +1,1057 @@
+/**
+ * fancy-topic plugin entry
+ *
+ * 两条路径：
+ *   A 探索模式  /fancy-topic [参数]            trim 后为空 → 选平台/选文件/LLM 评分
+ *   B 敲定模式  /fancy-topic setup             逐项弹框 → 原子写盘 → phase=topic_done
+ *
+ * 不论哪条路径，都先检查 .fancy-deployed 存在且 phase ∈ {scanned, topic_done}。
+ */
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, mkdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { askUserQuestion, llmFollowup, notify, spawnScript } from '#infra';
+import { readDeployedState, deployedStateProblemText, DEPLOYED_STATUS } from '#deployed-state';
+import { repairTopicDecision, selectNonRedundantBlocks, inspectBlockBodies } from '#topic-decision';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+import { normalizeTopicData } from '#topic-schema';
+import { resolveWorkspace } from '#workspace';
+import { topic } from './templates.js';
+import { deployTopicTools } from './tool-deploy.js';
+
+export const inject = ['commands', 'userQuestions'];
+
+/**
+ * select-topic.js 的绝对路径。
+ *
+ * 必须用 fileURLToPath：URL.pathname 会把中文/空格百分号编码
+ * （/tmp/普通 目录 → /tmp/%E6%99%AE%E9%80%9A%20%E7%9B%AE%E5%BD%95），
+ * 拼出来的路径不存在，spawnScript 必然报 MODULE_NOT_FOUND，
+ * 选题根本写不进去。run-scan.js 里同一个坑已经修过。
+ */
+const SELECT_TOPIC_SCRIPT = join(
+  fileURLToPath(new URL('.', import.meta.url)),
+  'scripts',
+  'select-topic.js'
+);
+
+/**
+ * 多选字段的 id 集合。
+ *
+ * 这两个字段必须保持**数组**语义：多选回传 selected 是数组，
+ * 写盘时也是 JSON 数组。首次收集与必填重试轮必须用同一套取值逻辑 ——
+ * 曾经重试轮写成 `ans.selected?.[0]`，把多选塌成字符串且只保留第一项。
+ */
+const MULTISELECT_IDS = new Set(['hard_constraints', 'anti_tropes']);
+
+/**
+ * 从 DSH 的一条 answer 里取值。
+ *
+ * ## custom 与 selected 谁优先（2026-10-29 审计）
+ *
+ * DSH 的契约里两者可以并存：
+ *
+ *   selected: string[]  选中的选项标签
+ *   custom?: string     自由输入的"其他"
+ *
+ * web 端在**单选**时会把 selected 清空（只留 custom），
+ * 但 TUI 端可能两个都传 —— `selected: ['其他']` + `custom: '玄幻'`。
+ * 这时取 `selected[0]` 会拿到"其他"这个标签，
+ * 用户真正输入的题材**被丢掉**。
+ *
+ * 所以：**custom 是用户亲手敲的，比 selected 的标签更具体，优先用它**。
+ * 多选时两者都要保留（custom 是用户在已选项之外额外加的一条）。
+ *
+ * @param {object} ans - DSH 的 AskUserQuestionAnswerItem
+ * @returns {string|string[]|undefined} undefined 表示这条 answer 没有对应字段
+ */
+function collectAnswerValue(ans) {
+  if (!ans || !ans.id) return undefined;
+  const custom = typeof ans.custom === 'string' ? ans.custom.trim() : '';
+  if (MULTISELECT_IDS.has(ans.id)) {
+    const out = Array.isArray(ans.selected) ? ans.selected.slice() : [];
+    if (custom && !out.includes(custom)) out.push(custom);
+    return out;
+  }
+  // 单选或文本：custom（用户亲手输入的）优先，否则取选中的标签
+  if (custom) return custom;
+  return ans.selected?.[0] ?? '';
+}
+
+function getProjectRoot(session) {
+  // Scan/topic/analyze are workspace-level tools. The workspace may be found
+  // from cwd, FANCY_HOME, or the global pointer written by bootstrap.
+  const cwd = session.header?.cwd;
+  if (!cwd) return null;
+  try {
+    return resolveWorkspace({ cwd, required: true });
+  } catch {
+    // Fall back to the session cwd so the caller can report "not initialized"
+    // with the right path instead of "no project root".
+    return cwd;
+  }
+}
+
+/**
+ * 读取项目 phase。
+ *
+ * 必须区分「读不到」和「phase 值不对」：
+ * 之前一律返回 null，调用方只能报"请先运行 /fancy-scan 扫榜" ——
+ * 但 .fancy-deployed 内容损坏时，跑 scan 也没用，错误信息会把用户带偏。
+ *
+ * @returns {{phase: string|null, error: 'missing'|'corrupt'|'no_phase'|null, message?: string}}
+ */
+/**
+ * 平台目录（中文名 + 英文 value），用于判定某行标题归属哪个平台。
+ */
+const PLATFORM_DIR = topic.PLATFORM_OPTIONS.map(p => ({
+  value: p.value,
+  label: p.label,
+  lowerValue: String(p.value).toLowerCase(),
+}));
+
+/**
+ * 判断一行标题归属哪个平台。
+ *
+ * 规则：去掉 start/end 后缀后，标题**以平台名开头**才算该平台的段标题。
+ *   "番茄-男频阅读榜-20261021"  → 番茄
+ *   "番茄男频阅读榜分析"        → 番茄（LLM 漏写标记时也认）
+ *   "参考：起点同类作品"        → 不以平台名开头 → 不归属任何平台
+ * 第二个规则很重要：正文里的 markdown 小标题常带平台名，若一律当段标题，
+ * 就会把别的平台的内容从段落中间切开。
+ */
+function platformOfHeader(text) {
+  const core = String(text || '')
+    .trim()
+    .replace(/[-—–\s]*(start|end)\s*$/i, '')
+    .trim();
+  if (!core) return null;
+  for (const p of PLATFORM_DIR) {
+    if (core.startsWith(p.label)) return p.value;
+    if (core.toLowerCase().startsWith(p.lowerValue)) return p.value;
+  }
+  return null;
+}
+
+/**
+ * 把 topic_decision_<date>.md 按**平台归属**切成块。
+ *
+ * 块边界规则（按优先级）：
+ *   1. **-start 标记行** → 开一个新块（**哪怕前一个块是同平台**）
+ *   2. **-end 标记行** → 关闭当前块（同平台）
+ *   3. 其它以平台名开头的标题行 → 若当前有开着的**同平台**块，
+ *      它只是该块的另一个标题（LLM 常在 -start 后面再写一个报告大标题），
+ *      追加进该块；否则自己开一个新块
+ *
+ * 规则 1 是关键：同一个平台在一次报告里可能有**多个 -start 块**
+ * （例："# 起点-全选-20261021-start" 与 "# 起点-签约榜-20261021-start"），
+ * 它们是两次独立分析，不能合并成一块 —— 合并后用户看到的
+ * "起点只有 1 块" 就是错的。
+ *
+ * 为什么不用 -start/-end 配对切块：LLM 偶尔漏写标记，靠配对会让漏掉 -end
+ * 的那一块一路吞到下一个 -end，把夹在中间的**别的平台**的分析一起带走
+ * —— 实测过：选番茄时起点的分析也一起发给了 LLM，而且全程没有任何报错。
+ * 现在靠"标题行"和"-start 标记"两个信号切块，漏写 -end 也不会串台。
+ *
+ * 返回 [{ platform, headers, body, hasStart, hasEnd }]
+ */
+function splitDecisionSections(content) {
+  const lines = String(content || '').split('\n');
+  const raw = [];
+  let cur = null;
+  const preamble = [];
+
+  for (const line of lines) {
+    // 独占一行的代码围栏（``` / ~~~）是 markdown 装饰，不是正文内容。
+    // 扫榜提示词把 start/end 模板放在代码块里展示，LLM 照抄时会把围栏
+    // 一起写进 topic_decision 文件；这里只丢掉**围栏行本身**，
+    // 围栏里面的正文照旧保留（不"自愈"文件，只在解析时忽略装饰）。
+    if (/^[ \t]*(?:`{3,}|~{3,}).*$/.test(line)) continue;
+
+    const m = line.match(/^[ \t]*#{1,6}[ \t]*(.+?)[ \t]*$/);
+    const title = m ? m[1].trim() : '';
+    const platform = title ? platformOfHeader(title) : null;
+
+    if (platform) {
+      // 分隔符是必需的：`# Restart` 不能被当成 `-start` 标记。
+      const isStartMark = /(?:^|[-—–\s])start\s*$/i.test(title);
+      const isEndMark = /(?:^|[-—–\s])end\s*$/i.test(title);
+      const titleKey = title.replace(/(?:^|[-—–\s])(?:start|end)\s*$/i, '').trim();
+
+      // -end 行：关闭当前块（同平台且同 key），**不开新块**。
+      // 不能只看平台：`# 起点-签约榜-end` 会把 `# 起点-全选-start`
+      // 开的块错误闭合，两块内容随后可能被合并/错切。
+      if (isEndMark && cur && cur.platform === platform && (!cur.key || cur.key === titleKey)) {
+        cur.hasEnd = true;
+        cur.headers.push(`# ${title}`);
+        raw.push(cur);
+        cur = null;
+        continue;
+      }
+      // key 对不上的 end 不关闭当前块；当普通标题保留在块内，
+      // 由 inspectTopicDecision / parseMarkerBlocks 去报告“标记不匹配”。
+      if (isEndMark && cur && cur.platform === platform) {
+        cur.headers.push(`# ${title}`);
+        continue;
+      }
+      // 孤立 end / 别的平台的 end：不要凭空开一个空块。
+      if (isEndMark) {
+        if (cur) cur.bodyLines.push(`# ${title}`);
+        else preamble.push(`# ${title}`);
+        continue;
+      }
+
+      // 块内的另一个标题：同平台、当前块开着、且它不是 -start/-end 标记。
+      // 追加进当前块，不新开块 —— LLM 常在 -start 后面紧跟一个报告大标题。
+      if (cur && cur.platform === platform && !isStartMark && !isEndMark) {
+        cur.headers.push(`# ${title}`);
+        continue;
+      }
+
+      // 其余情况开新块（含 -start 标记行：同平台也必须开新块）
+      if (cur) raw.push(cur);
+      cur = {
+        platform,
+        key: titleKey,
+        headers: [`# ${title}`],
+        bodyLines: [],
+        hasStart: isStartMark,
+        hasEnd: false,
+      };
+      continue;
+    }
+
+    if (cur) cur.bodyLines.push(line);
+    else preamble.push(line);
+  }
+  if (cur) raw.push(cur);
+
+  // 文件前言并入第一块（LLM 有时把本次分析写在任何标题之前）
+  if (preamble.length && raw.length) {
+    raw[0].bodyLines = [...preamble, ...raw[0].bodyLines];
+  }
+
+  return raw.map((s) => ({
+    platform: s.platform,
+    headers: s.headers,
+    body: s.bodyLines.join('\n').trim(),
+    hasStart: s.hasStart,
+    hasEnd: s.hasEnd,
+  }));
+}
+
+/**
+ * 从块里挑出属于指定平台的块。
+ *
+ * 平台名（番茄/起点/晋江/七猫）出现在标题中即认为匹配；
+ * 同时也认英文 value（fanqie/qidian/...）—— LLM 偶尔会写成英文，
+ * 只认中文会让用户看到"没有找到该平台的内容块"。
+ */
+function filterSectionsByPlatform(sections, platformValue) {
+  const val = String(platformValue || '').toLowerCase();
+  if (!val) return [];
+  return sections.filter(s => s.platform === val);
+}
+
+/**
+ * 从 扫榜结果/ 的产物文件名推断扫过哪些平台。
+ *
+ * 产物文件名形如 "番茄男频阅读榜_20261021.md" —— 以平台中文名开头。
+ * 用途：LLM 一次平台标记都没写时，若只扫过一个平台，
+ * 就能确定整份文件都属于那个平台（降级处理，不至于直接失败）。
+ */
+function scannedPlatforms(scanDir) {
+  const found = [];
+  if (!existsSync(scanDir)) return found;
+  let files = [];
+  try { files = readdirSync(scanDir); } catch (_) { return found; }
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    if (/^topic_decision_\d{8}\.md$/.test(f)) continue;
+    for (const p of PLATFORM_DIR) {
+      if (f.startsWith(p.label) && !found.includes(p.value)) found.push(p.value);
+    }
+  }
+  return found;
+}
+
+function platformCn(value) {
+  const m = topic.PLATFORM_OPTIONS.find(p => p.value === value);
+  return m ? m.label : value;
+}
+
+// 把任意形式的 platform（label 或 value）归一化成 value 用于比较
+function platformToValue(p) {
+  if (!p) return '';
+  const direct = topic.PLATFORM_OPTIONS.find(opt => opt.value === p);
+  if (direct) return p;
+  const byLabel = topic.PLATFORM_OPTIONS.find(opt => opt.label === p);
+  return byLabel ? byLabel.value : p;
+}
+
+// 比较两个 platform 值（不论是 label 还是 value，都视为相等）
+function platformEqual(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  return platformToValue(a) === platformToValue(b);
+}
+
+// ---------------------------------------------------------------------------
+// 路径 A：探索模式
+// ---------------------------------------------------------------------------
+
+async function pathExplore(ctx, session, invocation, signal, projectRoot) {
+  // 弹框 1：选平台
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const askedplatformChoice = await askUserQuestion(ctx, invocation, [topic.askPlatform()]);
+  if (!askedplatformChoice.ok) {
+    return notify(session, 'error', topic.notify({
+      type: askedplatformChoice.failure.type,
+      err: askedplatformChoice.failure.message
+    }));
+  }
+  const platformChoice = askedplatformChoice.answer;
+  if (!platformChoice?.answers?.[0]) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const selectedPlatform = platformChoice.answers[0]?.selected?.[0];
+  if (!selectedPlatform) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+
+  // 扫描 扫榜结果/ 目录下的 topic_decision_<date>.md 文件
+  const scanDir = join(projectRoot, '扫榜结果');
+  let decisionFiles = [];
+  if (existsSync(scanDir)) {
+    try {
+      const st = lstatSync(scanDir);
+      if (st.isSymbolicLink() || !st.isDirectory()) {
+        return notify(session, 'error', topic.notify({
+          type: 'read_failed',
+          err: '扫榜结果/ 不是真实目录，已拒绝读取。请将其替换为真实目录后重试。',
+        }));
+      }
+    } catch (e) {
+      return notify(session, 'error', topic.notify({
+        type: 'read_failed',
+        err: `检查扫榜结果目录失败：${e.message}`,
+      }));
+    }
+    try {
+      decisionFiles = readdirSync(scanDir)
+        .filter(f => /^topic_decision_\d{8}\.md$/.test(f))
+        // 不跟随符号链接：决策文件必须在工作区目录内，防止读到项目外的内容。
+        .filter(f => {
+          try {
+            const st = lstatSync(join(scanDir, f));
+            return st.isFile() && !st.isSymbolicLink();
+          } catch { return false; }
+        })
+        .sort()
+        .reverse();  // 最新的在前
+    } catch (e) {
+      return notify(session, 'error', topic.notify({
+        type: 'read_failed',
+        err: `读取扫榜结果目录失败：${e.message}`,
+      }));
+    }
+  }
+
+  if (decisionFiles.length === 0) {
+    return notify(session, 'error', topic.notify({ type: 'no_decision_file' }));
+  }
+
+  // 弹框 2：选 topic_decision 文件
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const askedfileChoice = await askUserQuestion(ctx, invocation, [topic.askDecisionFile(decisionFiles)]);
+  if (!askedfileChoice.ok) {
+    return notify(session, 'error', topic.notify({
+      type: askedfileChoice.failure.type,
+      err: askedfileChoice.failure.message
+    }));
+  }
+  const fileChoice = askedfileChoice.answer;
+  if (!fileChoice?.answers?.[0]) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const selectedFile = fileChoice.answers[0]?.selected?.[0];
+
+  // DSH 回传的是 label（不是 value），此处必须按 label 判断，
+  // 此前用 value:'__rescan__' 判断导致该分支永远不可达。
+  if (selectedFile === topic.RESCAN_LABEL) {
+    return notify(session, 'success', topic.notify({ type: 'path_a_rescan' }));
+  }
+  if (!selectedFile || !decisionFiles.includes(selectedFile)) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+
+  // 读取 topic_decision_<date>.md
+  const decisionPath = join(projectRoot, '扫榜结果', selectedFile);
+  let content;
+
+  // 2026-10-27：读之前先校验一遍有没有被覆盖。
+  //
+  // 写这个文件的是 LLM，write 工具是覆盖语义 —— 实测（tt5 项目）
+  // 第二个平台分析时模型先 write("") 清空文件再 cat >> 追加，
+  // 第一个平台的分析就此消失。fancy-scan 现在投递前会备份，
+  // 这里拿备份比对，把被覆盖掉的段落自动补回来。
+  let repairedKeys = [];
+  try {
+    const repair = repairTopicDecision(decisionPath);
+    if (repair.repaired.length) {
+      repairedKeys = repair.repaired;
+      console.error(`[fancy-topic] topic_decision 缺失 ${repairedKeys.length} 个内容块，已从备份补回：${repairedKeys.join('、')}`);
+    }
+  } catch (e) {
+    console.error('[fancy-topic] 校验 topic_decision 失败：' + (e && e.message ? e.message : String(e)));
+  }
+
+  try {
+    content = readFileSync(decisionPath, 'utf-8');
+  } catch (e) {
+    return notify(session, 'error', topic.notify({
+      type: 'read_failed',
+      err: `读取 ${selectedFile} 失败：${e.message}`,
+    }));
+  }
+
+  // 空文件不能走“只扫过一个平台 → 整份文件都归它”的降级分支：
+  // 那会把空字符串当成数据发给 LLM，产出建立在空白上的选题。
+  // 只有 start/end 标记、没有正文的文件同样算空。
+  const meaningful = String(content)
+    .split('\n')
+    .filter(l => !/^\s*#\s*[^\n]*-(start|end)\s*$/i.test(l))
+    .filter(l => !/^\s*(?:`{3,}|~{3,}).*$/.test(l))
+    .join('')
+    .trim();
+  if (!meaningful) {
+    return notify(session, 'error', topic.notify({
+      type: 'empty_decision_file',
+      decisionFile: selectedFile,
+    }));
+  }
+
+  // 按平台归属切段。段边界由标题行决定，不靠 -start/-end 配对 ——
+  // 靠配对会让漏写 -end 的那段吞掉别的平台的内容（实测串台）。
+  const sections = splitDecisionSections(content);
+  const platformCnName = platformCn(selectedPlatform);
+  const platformValue = platformToValue(selectedPlatform);
+
+  let matchedSections = filterSectionsByPlatform(sections, platformValue);
+  const notes = [];
+
+  // ── 先验正文，再去冗余 ────────────────────────────────────────────
+  //
+  // 顺序反了会丢块（2026-10-29 审计）：
+  //
+  //   1. 先 selectNonRedundantBlocks —— 后出现的"全选"块（范围宽）
+  //      覆盖前面的"单榜"块（范围窄），单榜块被丢弃；
+  //   2. 再 inspectBlockBodies —— 这才发现"全选"块的正文没写进去
+  //      （占位符残留 / 正文为空），把它剔除；
+  //   3. usable 为空 → 报 block_body_invalid。
+  //
+  // 明明"单榜"块是好的，却因为先被去冗余丢掉而报失败。
+  // 正确顺序：**先把没写进去的块剔掉，再在剩下的块里算冗余**。
+  //
+  // 实测（2026-10-28）：模型把 5.2 的 heredoc 命令原样跑了一遍，
+  // `<本次正文>` 占位符原封不动进了文件，而 start/end 两个标记都写对了。
+  // 于是 start=1 且 end=1 被判成"写入成功"，这段占位文字又被原样发给 LLM
+  // 做选题 —— 选题结论建立在"字都没写"的块上。
+  //
+  // 模型看不见自己写进去的东西，所以这个判定必须由插件做（插件算得出来）。
+  // 有问题的块**不发给 LLM**：宁可少发一块，也不能让垃圾进选题。
+  {
+    const bad = inspectBlockBodies(content);
+    // 只看**本次选中平台**的块。文件里别的平台的坏块不应让本次报
+    // “block_body_invalid”，也不应出现在本次的提示里。
+    const relevantBad = bad.filter(b => {
+      if (!b.key) return false;
+      return matchedSections.some(s => String((s.headers && s.headers[0]) || '').includes(b.key));
+    });
+    // 只有**确凿**的失败（占位符残留 / 正文为空 / 只剩命令痕迹）才拦住派发；
+    // "偏短""没有结构标题"只是可疑 —— 报告本来就可能短，
+    // 把"我觉得不合格"当成"这是坏的"会误伤正常内容，所以只提示。
+    const hardBad = relevantBad.filter(b => b.reasons && b.reasons.length);
+    const softBad = relevantBad.filter(b => !b.reasons || !b.reasons.length);
+
+    if (softBad.length) {
+      notes.push(
+        `有 ${softBad.length} 个内容块看起来偏薄（${softBad.map(b => b.warnings.join('；')).join('；')}），` +
+        '已照常使用 —— 如果内容明显不对，可以手动检查一下。'
+      );
+    }
+
+    if (hardBad.length) {
+      const usable = matchedSections.filter(
+        s => !hardBad.some(b => b.key && String(s.headers[0] || '').includes(b.key))
+      );
+      if (usable.length) {
+        notes.push(
+          `有 ${hardBad.length} 个内容块的正文没写进去（${hardBad.map(b => b.reasons.join('；')).join('；')}），` +
+          '已跳过它们，只把能用的块发给 LLM；文件里的原始内容没有删除。'
+        );
+        matchedSections = usable;
+      } else {
+        // 所有块都没内容 —— 直接失败，别拿垃圾去做选题
+        return notify(session, 'error', topic.notify({
+          type: 'block_body_invalid',
+          reasons: hardBad.map(b => `「${b.key}」：${b.reasons.join('；')}`),
+        }));
+      }
+    }
+  }
+
+  // 同平台的块去冗余 ——
+  //
+  // 同一平台一天里可能被扫多次，每次追加一个标记块。文件里两块都留着
+  // （数据不丢），但把两块**一起**发给 LLM 就是冗余：榜单范围窄的那块
+  // 已经被范围宽的那块覆盖，同一批数据会被统计两遍。
+  //
+  // 去冗余只影响"发给 LLM 的内容"，**不删文件里的任何数据**。
+  if (matchedSections.length > 1) {
+    const { kept, dropped } = selectNonRedundantBlocks(
+      matchedSections,
+      (s) => (s.headers && s.headers[0]) || ''
+    );
+    if (dropped.length) {
+      matchedSections = kept;
+      notes.push(
+        `该平台有 ${dropped.length} 个内容块与其它块重复（${dropped.map(d => d.reason).join('；')}），` +
+        '已只发不重复的那部分给 LLM；文件里的原始数据没有删除。'
+      );
+    }
+  }
+
+  // 被覆盖过的段落已从备份补回 —— 必须告诉用户"这份文件刚才丢过东西"
+  if (repairedKeys.length) {
+    notes.push(
+      `检测到该文件曾被覆盖（LLM 写文件时用了覆盖语义），已从备份补回 ${repairedKeys.length} 个内容块：` +
+      repairedKeys.join('、') + '。'
+    );
+  }
+
+  // 一次平台标记都没写：若只扫过一个平台，整份文件都属于它（降级，不直接失败）
+  if (sections.length === 0) {
+    const scanned = scannedPlatforms(scanDir);
+    if (scanned.length === 1 && scanned[0] === platformValue) {
+      matchedSections = [{
+        platform: platformValue,
+        headers: [`（整份文件，LLM 未写平台标记）`],
+        body: content.trim(),
+        hasStart: false,
+        hasEnd: false,
+      }];
+      notes.push('LLM 未在报告里写平台标记；本次只扫过一个平台，已按整份文件处理。');
+    } else {
+      // "文件里一个段都没有" 与 "有段但没有这个平台" 是两回事，
+      // 必须分开报错：前者是 LLM 没按格式写，后者是扫榜没扫这个平台。
+      return notify(session, 'error', topic.notify({
+        type: 'no_decision_block',
+        decisionFile: selectedFile,
+      }));
+    }
+  } else if (matchedSections.length === 0) {
+    return notify(session, 'error', topic.notify({
+      type: 'platform_not_in_decision',
+      platform: platformCnName,
+      decisionFile: selectedFile,
+      available: [...new Set(sections.map(s => s.headers[0]))],
+    }));
+  }
+
+
+  // 诊断：哪些块缺 start/end 标记（LLM 格式不规范，但已按标题隔离，不影响正确性）
+  // 分开统计 -start / -end：只缺 -end 的块被说成"标记缺失"是错的 ——
+  // 那种块明明写着 -start，却出现在告警名单里，用户会以为切错了。
+  const missingStart = matchedSections.filter(s => !s.hasStart);
+  const missingEnd = matchedSections.filter(s => !s.hasEnd);
+  if (missingStart.length || missingEnd.length) {
+    const parts = [];
+    if (missingStart.length) {
+      parts.push(`${missingStart.length} 块缺少 -start 标记（${missingStart.map(s => s.headers[0]).join('；')}）`);
+    }
+    if (missingEnd.length) {
+      parts.push(`${missingEnd.length} 块缺少 -end 标记（${missingEnd.map(s => s.headers[0]).join('；')}）`);
+    }
+    notes.push(`其中 ${parts.join('；')}，已按标题行切分隔离，不影响平台归属。`);
+  }
+
+  // 拼装发给 LLM 的提示。
+  //
+  // 块包装**不用标题层级**（2026-10-29 提示词评审 F1）：
+  // 原来用 `## 块 N`，而块正文里有 `# 平台-榜单-日期-start` 这种 H1 ——
+  // H2 里套 H1 是层级倒置，任务指令 `### 2.1` 与数据里的 `### 3.1`
+  // 也混在同一层，模型只能靠"请执行以下分析"这一句判断边界。
+  //
+  // 现在数据整体被 `<<<FANCY_SCAN_DATA>>>` 哨兵包住（见 explorePrompt），
+  // 块包装改成普通文本行 `【数据块 N】`，不引入任何标题层级。
+  // 块标题已经在 source_summary_block 里逐条列出，这里不再重复 start/end 标记；
+  // 只保留“数据块 N”这个普通文本行，正文从 `## 一、...` 开始。
+  const blocksText = matchedSections.map((s, i) =>
+    `【数据块 ${i + 1}】\n${s.body}`
+  ).join('\n\n');
+
+  // 汇总按平台分组（保持文件里的出现顺序），并给出每个平台的块数。
+  // 之前是"每块一行"，同一个平台会出现多行、总数也和块数对不上；
+  // 术语统一用"块"（与下面的 "【数据块 N】" 标记一致）。
+  const summaryByPlatform = new Map();
+  for (const s of sections) {
+    const name = platformCn(s.platform) || s.platform;
+    if (!summaryByPlatform.has(name)) summaryByPlatform.set(name, []);
+    summaryByPlatform.get(name).push({ headers: s.headers });
+  }
+  const sectionSummary = [...summaryByPlatform.entries()].map(([name, blocks]) => ({
+    platform: name,
+    blocks,
+  }));
+
+  // LLM 只执行工作区内的只读脚本：先把 save-suggestion.js 及其 import 闭包
+  // 部署到 `<工作区目录>/.fancy-tools/fancy-topic/`，再把部署后的路径写进提示词。
+  // 不能把插件目录（node_modules）暴露给模型。
+  const deployed = deployTopicTools(projectRoot);
+  if (!deployed.ok) {
+    return notify(session, 'error', topic.notify({
+      type: 'tool_deploy_failed',
+      err: deployed.problems.join('；'),
+    }));
+  }
+
+  mkdirSync(join(projectRoot, '.tmp'), { recursive: true });
+
+  const prompt = topic.explorePrompt({
+    platform: platformCnName,
+    decisionFile: selectedFile,
+    // 绝对路径：提示词里"参考文件"和 source_decision_file 都用它，
+    // 免得模型拿着裸文件名拼不出它在 扫榜结果/ 下
+    decisionPath: decisionPath,
+    blocks: blocksText,
+    blockCount: matchedSections.length,
+    sectionSummary,
+    notes,
+    projectRoot,
+    saveScriptPath: deployed.saveScript,
+  });
+
+  // 触发 LLM 分析
+  try {
+    const follow = await llmFollowup(invocation, prompt);
+    // llmFollowup 内部已捕获异常并返回 { ok, error }，必须检查返回值，
+    // 否则投递失败也会报"分析已完成"
+    if (!follow || follow.ok !== true) {
+      return notify(session, 'error', topic.notify({
+        type: 'llm_delivery_failed',
+        err: (follow && follow.error) || '提示词投递失败',
+      }));
+    }
+  } catch (err) {
+    // llmFollowup 通常不抛错（它自己 try/catch），但保险起见
+    return notify(session, 'error', topic.notify({
+      type: 'llm_delivery_failed',
+      err: err.message,
+    }));
+  }
+
+  return notify(session, 'success', topic.notify({
+    type: 'path_a_done',
+    platform: platformCnName,
+    decisionFile: selectedFile,
+    blockCount: matchedSections.length,
+    notes,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// 路径 B：敲定模式
+// ---------------------------------------------------------------------------
+
+async function pathSetup(ctx, session, invocation, signal, projectRoot) {
+  // 中间过程提示的收集处（DSH 只有 handler 的返回值会被用户看到）
+  const extraNotes = [];
+  const novelTopicPath = join(projectRoot, '_novel_topic.json');
+
+  // 如果 _novel_topic.json 不存在，创建骨架
+  if (!existsSync(novelTopicPath)) {
+    const skeletonResult = await spawnScript('node', [
+      SELECT_TOPIC_SCRIPT,
+      '--project-root', projectRoot,
+      'skeleton',
+    ], { timeout: 30000 });
+
+    if (!skeletonResult.ok) {
+      const errMsg = skeletonResult.error || '未知错误';
+      return notify(session, 'error', topic.notify({ type: 'write_failed', err: errMsg }));
+    }
+    // 这条信息不能只 notify 出去：DSH 只有 handler 的返回值会经
+    // settleThrown → command/done → channel.notify()，中间调用丢弃 = 用户看不到。
+    // 并入最终返回消息。
+    extraNotes.push(topic.notify({ type: 'create_skeleton' }));
+  }
+
+  // 弹框：选平台（路径 B 也独立选，因为路径 A 不写文件）
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const askedplatformChoice = await askUserQuestion(ctx, invocation, [topic.askPlatform()]);
+  if (!askedplatformChoice.ok) {
+    return notify(session, 'error', topic.notify({
+      type: askedplatformChoice.failure.type,
+      err: askedplatformChoice.failure.message
+    }));
+  }
+  const platformChoice = askedplatformChoice.answer;
+  if (!platformChoice?.answers?.[0]) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const selectedPlatform = platformChoice.answers[0]?.selected?.[0];
+  if (!selectedPlatform) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+
+  // 弹框里展示的两组值，优先级：
+  //   1. "📌 当前值" —— _novel_topic.json 的值（仅当平台一致）
+  //   2. "💡 推荐值" —— _novel_topic_suggestion.json 的值（仅当平台一致）
+  //
+  // 两者都直接写进 question 文本展示。之前还有一段"用推荐值填补上次空字段"
+  // 的逻辑，但它唯一的落点是问题对象上的 default 字段 ——
+  // DSH 的 AskUserQuestionItem 根本没有 default 字段（会被静默忽略），
+  // 那段代码对用户完全不可见，属于死代码，已删除。
+  const suggestionPath = join(projectRoot, '_novel_topic_suggestion.json');
+  let suggestion = null;
+  if (existsSync(suggestionPath) && lstatSync(suggestionPath).isSymbolicLink()) {
+    extraNotes.push(topic.notify({
+      type: 'suggestion_corrupt',
+      file: '_novel_topic_suggestion.json（符号链接，已忽略）',
+    }));
+  } else if (existsSync(suggestionPath)) {
+    try {
+      suggestion = normalizeTopicData(JSON.parse(readFileSync(suggestionPath, 'utf-8')));
+    } catch (e) {
+      // 以前是静默忽略 —— 用户看到的是"没有推荐值"，却不知道推荐值其实存在、
+      // 只是坏了。这跟"文件被写坏"这个事实一起消失，问题无从查起。
+      // 现在明确告诉用户，并给出补救动作。
+      console.error('[fancy-topic] _novel_topic_suggestion.json 解析失败：' + (e && e.message ? e.message : String(e)));
+      extraNotes.push(topic.notify({
+        type: 'suggestion_corrupt',
+        file: '_novel_topic_suggestion.json',
+      }));
+    }
+  }
+
+  // 比较 suggestion 与 selectedPlatform，决定是否应用建议值
+  // 比较 _novel_topic.json 与 selectedPlatform，决定是否显示"当前值"
+  const suggestionPlatformMatches = suggestion ? platformEqual(suggestion.platform, selectedPlatform) : false;
+
+  // 读 _novel_topic.json，仅当其 platform 与 selectedPlatform 一致时作为"当前值"展示
+  const currentValues = (() => {
+    if (!existsSync(novelTopicPath)) return {};
+    if (lstatSync(novelTopicPath).isSymbolicLink()) {
+      extraNotes.push(topic.notify({
+        type: 'current_values_corrupt',
+        file: '_novel_topic.json（符号链接，已忽略）',
+      }));
+      return {};
+    }
+    try {
+      const data = normalizeTopicData(JSON.parse(readFileSync(novelTopicPath, 'utf-8')));
+      if (!data.platform) return data; // 没有 platform 字段就当作一致（兼容旧数据）
+      return platformEqual(data.platform, selectedPlatform) ? data : {};
+    } catch (e) {
+      // 同上：损坏不能静默。_novel_topic.json 存的是**已敲定的设定**，
+      // 它坏了会让后面的阶段读不到已定下来的东西。
+      console.error('[fancy-topic] _novel_topic.json 解析失败：' + (e && e.message ? e.message : String(e)));
+      extraNotes.push(topic.notify({
+        type: 'current_values_corrupt',
+        file: '_novel_topic.json',
+      }));
+      return {};
+    }
+  })();
+
+  // 只有 suggestion 平台匹配时，askFields 才显示"推荐值"
+  const suggestionValuesForDisplay = suggestionPlatformMatches ? suggestion : null;
+
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const askedfieldAnswers = await askUserQuestion(ctx, invocation, topic.askFields({
+        currentValues,
+        suggestionValues: suggestionValuesForDisplay,
+      }));
+  if (!askedfieldAnswers.ok) {
+    return notify(session, 'error', topic.notify({
+      type: askedfieldAnswers.failure.type,
+      err: askedfieldAnswers.failure.message
+    }));
+  }
+  const fieldAnswers = askedfieldAnswers.answer;
+
+  if (!fieldAnswers?.answers) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+
+  // 收集所有选题字段的值。
+  // 首次收集与必填重试轮必须走同一套取值逻辑（collectAnswerValue）——
+  // 否则多选字段会在重试轮塌成字符串、丢掉第 2 项以后的选择。
+  const fieldValues = { platform: selectedPlatform };
+  for (const ans of fieldAnswers.answers) {
+    const v = collectAnswerValue(ans);
+    if (v !== undefined) fieldValues[ans.id] = v;
+  }
+
+  // 判断一个值是否"为空"（用于必填检查）
+  // 空数组 []、空字符串 ''、null、undefined、数字 0 都视为空
+  // （数字 0 是骨架模板里 target_words / target_chapters 的默认值，无意义）
+  function isEmpty(v) {
+    if (v === undefined || v === null) return true;
+    if (typeof v === 'string') return v.trim() === '';
+    if (Array.isArray(v)) return v.length === 0;
+    if (typeof v === 'number') return v === 0;
+    return false;
+  }
+
+  // 必填字段为空 → 重新弹窗（仅弹缺失字段，最多 3 轮）
+  const MAX_RETRY = 3;
+  for (let retry = 0; retry < MAX_RETRY; retry++) {
+    const missing = topic.TOPIC_FIELDS
+      .filter(f => f.required && isEmpty(fieldValues[f.id]))
+      .map(f => f.id);
+    if (missing.length === 0) break;
+
+    // 这里**不能**往 extraNotes 里塞"必填字段未填写"的告警：
+    // DSH 只有 handler 的返回值会送达用户（中间 notify 会被丢弃），
+    // 而这条告警是**每一轮重试前**无条件塞的 —— 用户在重试轮补全之后，
+    // 那条历史告警仍然留在最终消息里，用户会以为没填成功、流程其实已经成功。
+    // 缺失情况改由下面的最终校验统一报告。
+
+    // 只重新弹缺失字段；已有值保留在 fieldValues 里，
+    // 重试轮只覆盖这次被问到的字段。
+    if (signal?.aborted) {
+      return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+    }
+    const askedreAnswers = await askUserQuestion(ctx, invocation, topic.askFields({
+          currentValues,
+          suggestionValues: suggestionValuesForDisplay,
+        }).filter(q => missing.includes(q.id)));
+    if (!askedreAnswers.ok) {
+      return notify(session, 'error', topic.notify({
+        type: askedreAnswers.failure.type,
+        err: askedreAnswers.failure.message
+      }));
+    }
+    const reAnswers = askedreAnswers.answer;
+    if (!reAnswers?.answers) {
+      return notify(session, 'error', topic.notify({
+        type: 'fields_missing',
+        missing,
+      }));
+    }
+    for (const ans of reAnswers.answers) {
+      const v = collectAnswerValue(ans);
+      if (v !== undefined) fieldValues[ans.id] = v;
+    }
+  }
+
+  // 最终校验：只报**最终仍然缺失**的字段。
+  // 用户补全过就一条告警都不该留。
+  const stillMissing = topic.TOPIC_FIELDS
+    .filter(f => f.required && isEmpty(fieldValues[f.id]))
+    .map(f => f.id);
+  if (stillMissing.length > 0) {
+    return notify(session, 'error', topic.notify({
+      type: 'fields_missing',
+      missing: stillMissing,
+    }));
+  }
+
+  // 调用 select-topic.js 原子写盘 + phase 推进
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const writeArgs = [
+    SELECT_TOPIC_SCRIPT,
+    '--project-root', projectRoot,
+  ];
+  // 字段清单来自 topic.TOPIC_FIELDS（与提示词/弹框/schema 同源），
+  // 新增字段不需要在这里再手写一遍 --xxx 参数。
+  for (const f of topic.TOPIC_FIELDS) {
+    const v = fieldValues[f.id];
+    writeArgs.push(
+      '--' + f.id.replace(/_/g, '-'),
+      Array.isArray(v) ? JSON.stringify(v) : String(v ?? '')
+    );
+  }
+  writeArgs.push('--platform', fieldValues.platform, 'write');
+  const writeResult = await spawnScript('node', writeArgs, { timeout: 30000 });
+
+  if (!writeResult.ok) {
+    const errMsg = writeResult.error || '未知错误';
+    return notify(session, 'error', topic.notify({ type: 'write_failed', err: errMsg }));
+  }
+
+  // phase 没推进成 topic_done 时，选题内容是写进去了的（所以 ok:true），
+  // 但项目状态没跟上 —— 下次运行可能还会提示"需要先选题"。
+  // 这条要说给用户听，不能闷在 JSON 里。
+  let phaseWarning = null;
+  try {
+    const parsed = JSON.parse(writeResult.output || '{}');
+    phaseWarning = parsed.phase_warning || null;
+  } catch {
+    // stdout 不是 JSON —— 没有 phase_warning 可读，忽略
+  }
+
+  const baseDone = topic.notify({
+    type: 'path_b_done',
+    fieldCount: topic.TOPIC_FIELDS.length,
+    extra: [extraNotes.join('\n\n'), phaseWarning].filter(Boolean).join('\n\n'),
+  });
+
+  // Lightweight roots (a single directory with .fancy-deployed, used by the
+  // shared scan/topic tests and older standalone setups) only need the topic
+  // file. Full workspaces additionally create the project directory, database
+  // and per-project user.
+  if (!existsSync(join(projectRoot, '.fancy', 'workspace.json'))) {
+    return notify(session, 'success', baseDone);
+  }
+
+  let projectInfo = null;
+  let projectError = null;
+  let projectAction = 'created';
+  try {
+    const { createProject, getProject, updateProjectTopic } = await import('#projects');
+    const { initProjectDatabase } = await import('#db-init');
+    const finalized = normalizeTopicData(JSON.parse(readFileSync(novelTopicPath, 'utf-8')));
+    const title = finalized.book_name || finalized.title || '';
+    if (!title) throw new Error('选题缺少 book_name，无法创建项目');
+    const found = await getProject(projectRoot, title);
+    projectAction = found ? 'updated' : 'created';
+    const project = found
+      ? await updateProjectTopic(projectRoot, found.project_id, finalized)
+      : await createProject(projectRoot, { title, topic: finalized });
+    await initProjectDatabase(projectRoot, project.project_id);
+    projectInfo = project;
+  } catch (err) {
+    projectError = err && err.message ? err.message : String(err);
+  }
+
+  if (projectError) {
+    return notify(session, 'error', [
+      '⚠️ 选题已写入，但项目创建或更新失败：' + projectError,
+      '修复后运行 /fancy-topic setup 重试，或运行 /fancy-db init 检查数据库。',
+      extraNotes.join('\n\n'),
+    ].filter(Boolean).join('\n\n'));
+  }
+
+  return notify(session, 'success', [
+    baseDone,
+    '',
+    projectAction === 'updated' ? '📚 项目已更新' : '📚 项目已创建',
+    '书名：' + projectInfo.name,
+    'UUID：' + projectInfo.project_id,
+    '目录：' + projectInfo.dir,
+    '数据库：' + projectInfo.db_name,
+  ].join('\n'));
+}
+
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-topic',
+    description: '📝 选题与创意约束 ( usage: /fancy-topic [setup] | help )',
+    input: {
+      hint: '.',
+    },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const { signal } = invocation;
+
+      // 1. 解析路径：A 探索 / B 敲定
+      // 只允许两种形式：
+      //   /fancy-topic          → 探索
+      //   /fancy-topic setup    → 敲定
+      // 其他任何参数都必须报错，不能悄悄当成探索/敲定。
+      const rawInput = (invocation.rawInput || '').trim();
+      const normalizedInput = rawInput.toLowerCase();
+      if (normalizedInput === 'help') {
+        return notify(session, 'success', topic.notify({ type: 'help' }));
+      }
+      if (normalizedInput && normalizedInput !== 'setup') {
+        return notify(session, 'error', topic.notify({
+          type: 'invalid_argument',
+          arg: rawInput,
+        }));
+      }
+      const isSetupPath = normalizedInput === 'setup';
+
+      // 2. 检查项目初始化
+      const projectRoot = getProjectRoot(session);
+      let projectRootAbs = projectRoot ? resolve(projectRoot) : null;
+      if (!projectRootAbs) {
+        return notify(session, 'error', topic.notify({
+          type: 'no_project_root',
+          err: '会话未提供当前工作目录'
+        }));
+      }
+      if (isSensitiveProjectPath(projectRootAbs) || !isValidProjectPath(projectRootAbs)) {
+        return notify(session, 'error', topic.notify({
+          type: 'no_project_root',
+          err: '工作区目录路径不合法或属于受保护目录'
+        }));
+      }
+      try {
+        projectRootAbs = realpathSync(projectRootAbs);
+      } catch (e) {
+        return notify(session, 'error', topic.notify({
+          type: 'no_project_root',
+          err: `无法读取工作区目录：${e.message}`
+        }));
+      }
+      if (isSensitiveProjectPath(projectRootAbs) || !isValidProjectPath(projectRootAbs)) {
+        return notify(session, 'error', topic.notify({
+          type: 'no_project_root',
+          err: '工作区目录的真实路径属于受保护目录'
+        }));
+      }
+      if (!existsSync(join(projectRootAbs, '.fancy-deployed'))) {
+        return notify(session, 'error', topic.notify({ type: 'not_initialized' }));
+      }
+
+      // 3. 检查 phase
+      // 区分"状态文件读不了"和"phase 值不对"——前者跑 scan 也没用，
+      // 报成"请先扫榜"会把用户带偏。
+      const deployedState = readDeployedState(projectRootAbs);
+      if (deployedState.status === DEPLOYED_STATUS.CORRUPT
+        || deployedState.status === DEPLOYED_STATUS.NO_PHASE
+        || deployedState.status === DEPLOYED_STATUS.UNKNOWN_PHASE) {
+        // 用共享的修复指引，而不是只说"重新运行 /fancy-bootstrap"——
+        // 文件**存在**时 bootstrap 会拒绝执行（它只在文件不存在时才初始化），
+        // 让用户去跑 bootstrap 等于把人送进死胡同。
+        return notify(session, 'error',
+          deployedStateProblemText(deployedState, { projectRoot: projectRootAbs })
+          || topic.notify({
+            type: 'phase_unreadable',
+            err: deployedState.status === DEPLOYED_STATUS.CORRUPT
+              ? '.fancy-deployed 不是合法 JSON'
+              : '.fancy-deployed 缺少 phase 字段',
+          }));
+      }
+      const phase = deployedState.phase;
+      if (phase !== 'scanned' && phase !== 'topic_done') {
+        return notify(session, 'error', topic.notify({ type: 'phase_wrong', phase }));
+      }
+
+      if (signal?.aborted) {
+        return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+      }
+
+      // 4. 路径分发
+      if (isSetupPath) {
+        return pathSetup(ctx, session, invocation, signal, projectRootAbs);
+      } else {
+        return pathExplore(ctx, session, invocation, signal, projectRootAbs);
+      }
+    },
+  });
+}