@cloud411716/fancy-webnovel 1.0.45 → 2.2.0

package/plugins/fancy-topic/index.js

@@ -0,0 +1,704 @@
+/**
+ * fancy-topic plugin entry
+ *
+ * 两条路径：
+ *   A 探索模式  /fancy-topic [参数]            trim 后为空 → 选平台/选文件/LLM 评分
+ *   B 敲定模式  /fancy-topic setup             8 弹框收集 → 原子写盘 → phase=topic_done
+ *
+ * 不论哪条路径，都先检查 .fancy-deployed 存在且 phase ∈ {scanned, topic_done}。
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { askUserQuestion, llmFollowup, notify, spawnScript } from '#infra';
+import { readDeployedState, deployedStateProblemText, DEPLOYED_STATUS } from '#deployed-state';
+import { topic } from './templates.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 里取值。
+ *
+ * @param {object} ans - DSH 的 AskUserQuestionAnswerItem
+ * @returns {string|string[]|undefined} undefined 表示这条 answer 没有对应字段
+ */
+function collectAnswerValue(ans) {
+  if (!ans || !ans.id) return undefined;
+  if (MULTISELECT_IDS.has(ans.id)) {
+    if (Array.isArray(ans.selected) && ans.selected.length > 0) return ans.selected.slice();
+    if (typeof ans.custom === 'string' && ans.custom.trim() !== '') return [ans.custom.trim()];
+    return [];
+  }
+  // 单选或文本：取 selected[0] 或 custom
+  return ans.selected?.[0] ?? ans.custom ?? '';
+}
+
+function getProjectRoot(session) {
+  // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
+  // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目执行部署与写盘。
+  // 此时返回 null，由调用方给出明确报错。
+  const cwd = session.header?.cwd;
+  return cwd || null;
+}
+
+/**
+ * 读取项目 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) {
+      const isStartMark = /[-—–\s]*start\s*$/i.test(title);
+      const isEndMark = /[-—–\s]*end\s*$/i.test(title);
+
+      // -end 行：关闭当前块（同平台），**不开新块**
+      // —— 少了这一步，"-end" 自己会变成一个空的新块。
+      if (isEndMark && cur && cur.platform === platform) {
+        cur.hasEnd = true;
+        cur.headers.push(`# ${title}`);
+        raw.push(cur);
+        cur = null;
+        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,
+        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, '扫榜结果');
+  const decisionFiles = existsSync(scanDir)
+    ? readdirSync(scanDir)
+        .filter(f => /^topic_decision_\d{8}\.md$/.test(f))
+        .sort()
+        .reverse()  // 最新的在前
+    : [];
+
+  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;
+  try {
+    content = readFileSync(decisionPath, 'utf-8');
+  } catch (e) {
+    return notify(session, 'error', topic.notify({
+      type: 'write_failed',
+      err: `读取 ${selectedFile} 失败: ${e.message}`,
+    }));
+  }
+
+  // 按平台归属切段。段边界由标题行决定，不靠 -start/-end 配对 ——
+  // 靠配对会让漏写 -end 的那段吞掉别的平台的内容（实测串台）。
+  const sections = splitDecisionSections(content);
+  const platformCnName = platformCn(selectedPlatform);
+  const platformValue = platformToValue(selectedPlatform);
+
+  let matchedSections = filterSectionsByPlatform(sections, platformValue);
+  const notes = [];
+
+  // 一次平台标记都没写：若只扫过一个平台，整份文件都属于它（降级，不直接失败）
+  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 的提示
+  const blocksText = matchedSections.map((s, i) =>
+    `## 块 ${i + 1}（${s.headers.join(' / ')}）\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,
+  }));
+
+  const prompt = topic.explorePrompt({
+    platform: platformCnName,
+    decisionFile: selectedFile,
+    blocks: blocksText,
+    blockCount: matchedSections.length,
+    sectionSummary,
+    notes,
+  });
+
+  // 触发 LLM 分析
+  try {
+    const follow = await llmFollowup(invocation, prompt);
+    // llmFollowup 内部已捕获异常并返回 { ok, error }，必须检查返回值，
+    // 否则投递失败也会报"分析已完成"
+    if (!follow || follow.ok !== true) {
+      return notify(session, 'error', topic.notify({
+        type: 'write_failed',
+        err: `触发 LLM 失败: ${(follow && follow.error) || '提示词投递失败'}`,
+      }));
+    }
+  } catch (err) {
+    // llmFollowup 通常不抛错（它自己 try/catch），但保险起见
+    return notify(session, 'error', topic.notify({
+      type: 'write_failed',
+      err: `触发 LLM 失败: ${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)) {
+    try {
+      suggestion = JSON.parse(readFileSync(suggestionPath, 'utf-8'));
+    } catch (_) { /* 损坏就忽略 */ }
+  }
+
+  // 比较 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 {};
+    try {
+      const data = JSON.parse(readFileSync(novelTopicPath, 'utf-8'));
+      if (!data.platform) return data; // 没有 platform 字段就当作一致（兼容旧数据）
+      return platformEqual(data.platform, selectedPlatform) ? data : {};
+    } catch (_) { 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' }));
+  }
+
+  // 收集 8 字段的值。
+  // 首次收集与必填重试轮必须走同一套取值逻辑（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 writeResult = await spawnScript('node', [
+    SELECT_TOPIC_SCRIPT,
+    '--project-root', projectRoot,
+    '--book-name', fieldValues.book_name,
+    '--genre', fieldValues.genre,
+    '--target-words', String(fieldValues.target_words),
+    '--target-chapters', String(fieldValues.target_chapters),
+    '--core-summary', fieldValues.core_summary,
+    '--core-conflict', fieldValues.core_conflict,
+    '--platform', fieldValues.platform,
+    '--hard-constraints', JSON.stringify(fieldValues.hard_constraints || []),
+    '--anti-tropes', JSON.stringify(fieldValues.anti_tropes || []),
+    'write',
+  ], { timeout: 30000 });
+
+  if (!writeResult.ok) {
+    const errMsg = writeResult.error || '未知错误';
+    return notify(session, 'error', topic.notify({ type: 'write_failed', err: errMsg }));
+  }
+
+  return notify(session, 'success', topic.notify({
+    type: 'path_b_done',
+    fieldCount: Object.keys(fieldValues).length,
+    extra: extraNotes.join('\n\n'),
+  }));
+}
+
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-topic',
+    description: '📝 选题与创意约束 ( usage: /fancy-topic [setup] )',
+    input: {
+      hint: '.',
+    },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const { signal } = invocation;
+
+      // 1. 解析路径：A 探索 / B 敲定
+      const rawInput = (invocation.rawInput || '').trim();
+      const isSetupPath = rawInput.toLowerCase() === 'setup';
+
+      // 2. 检查项目初始化
+      const projectRoot = getProjectRoot(session);
+      if (!projectRoot) {
+        return notify(session, 'error', topic.notify({
+          type: 'no_project_root',
+          err: '会话未提供 cwd'
+        }));
+      }
+      if (!existsSync(join(projectRoot, '.fancy-deployed'))) {
+        return notify(session, 'error', topic.notify({ type: 'not_initialized' }));
+      }
+
+      // 3. 检查 phase
+      // 区分"状态文件读不了"和"phase 值不对"——前者跑 scan 也没用，
+      // 报成"请先扫榜"会把用户带偏。
+      const deployedState = readDeployedState(projectRoot);
+      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 })
+          || 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 }));
+      }
+
+      // 4. 路径分发
+      if (isSetupPath) {
+        return pathSetup(ctx, session, invocation, signal, projectRoot);
+      } else {
+        return pathExplore(ctx, session, invocation, signal, projectRoot);
+      }
+    },
+  });
+}