@cloud411716/fancy-webnovel 3.0.3 → 4.0.0

package/plugins/fancy-topic/index.js

@@ -7,19 +7,21 @@
  *
  * 不论哪条路径，都先检查 .fancy-deployed 存在且 phase ∈ {scanned, topic_done}。
  */
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, mkdirSync } from 'fs';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, mkdirSync, writeFileSync, unlinkSync } 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 { parseDecisionCandidates } from '#topic-candidates';
+import { NOVEL_SUGGESTION_FILE, validateSuggestion, validateMinimalTopic, readSuggestion } from '#material-topic';
+import { atomicWriteJSON } from '#atomic-write';
 import { resolveWorkspace } from '#workspace';
 import { topic } from './templates.js';
-import { deployTopicTools } from './tool-deploy.js';
+import { deployMaterialTools } from '../fancy-material/tool-deploy.js';
 
-export const inject = ['commands', 'userQuestions'];
+export const inject = ['commands', 'userQuestions', 'tools'];
 
 /**
  * select-topic.js 的绝对路径。
@@ -29,10 +31,11 @@ export const inject = ['commands', 'userQuestions'];
  * 拼出来的路径不存在，spawnScript 必然报 MODULE_NOT_FOUND，
  * 选题根本写不进去。run-scan.js 里同一个坑已经修过。
  */
-const SELECT_TOPIC_SCRIPT = join(
+
+const SAVE_MINIMAL_TOPIC_SCRIPT = join(
   fileURLToPath(new URL('.', import.meta.url)),
   'scripts',
-  'select-topic.js'
+  'save-minimal-topic.js'
 );
 
 /**
@@ -301,27 +304,8 @@ function platformEqual(a, b) {
 // ---------------------------------------------------------------------------
 
 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 文件
+  // 路径 A 不再调用 LLM：
+  //   选 topic_decision 文件 → 选该文件里已有的平台 → 选候选方向 → 写 suggestion。
   const scanDir = join(projectRoot, '扫榜结果');
   let decisionFiles = [];
   if (existsSync(scanDir)) {
@@ -342,7 +326,6 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     try {
       decisionFiles = readdirSync(scanDir)
         .filter(f => /^topic_decision_\d{8}\.md$/.test(f))
-        // 不跟随符号链接：决策文件必须在工作区目录内，防止读到项目外的内容。
         .filter(f => {
           try {
             const st = lstatSync(join(scanDir, f));
@@ -350,7 +333,7 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
           } catch { return false; }
         })
         .sort()
-        .reverse();  // 最新的在前
+        .reverse();
     } catch (e) {
       return notify(session, 'error', topic.notify({
         type: 'read_failed',
@@ -363,25 +346,17 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     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) {
+  const askedFile = await askUserQuestion(ctx, invocation, [topic.askDecisionFile(decisionFiles)]);
+  if (!askedFile.ok) {
     return notify(session, 'error', topic.notify({
-      type: askedfileChoice.failure.type,
-      err: askedfileChoice.failure.message
+      type: askedFile.failure.type,
+      err: askedFile.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__' 判断导致该分支永远不可达。
+  const selectedFile = askedFile.answer?.answers?.[0]?.selected?.[0];
   if (selectedFile === topic.RESCAN_LABEL) {
     return notify(session, 'success', topic.notify({ type: 'path_a_rescan' }));
   }
@@ -389,27 +364,8 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     return notify(session, 'error', topic.notify({ type: 'cancelled' }));
   }
 
-  // 读取 topic_decision_<date>.md
-  const decisionPath = join(projectRoot, '扫榜结果', selectedFile);
+  const decisionPath = join(scanDir, 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) {
@@ -419,248 +375,80 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     }));
   }
 
-  // 空文件不能走“只扫过一个平台 → 整份文件都归它”的降级分支：
-  // 那会把空字符串当成数据发给 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) {
+  const { platforms } = parseDecisionCandidates(content);
+  if (!platforms.length) {
     return notify(session, 'error', topic.notify({
-      type: 'empty_decision_file',
+      type: 'no_directions',
       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('；')}`),
-        }));
-      }
-    }
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
   }
-
-  // 同平台的块去冗余 ——
-  //
-  // 同一平台一天里可能被扫多次，每次追加一个标记块。文件里两块都留着
-  // （数据不丢），但把两块**一起**发给 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；文件里的原始数据没有删除。'
-      );
-    }
+  const askedPlatform = await askUserQuestion(ctx, invocation, [topic.askPlatformOptions(platforms)]);
+  if (!askedPlatform.ok) {
+    return notify(session, 'error', topic.notify({
+      type: askedPlatform.failure.type,
+      err: askedPlatform.failure.message,
+    }));
   }
-
-  // 被覆盖过的段落已从备份补回 —— 必须告诉用户"这份文件刚才丢过东西"
-  if (repairedKeys.length) {
-    notes.push(
-      `检测到该文件曾被覆盖（LLM 写文件时用了覆盖语义），已从备份补回 ${repairedKeys.length} 个内容块：` +
-      repairedKeys.join('、') + '。'
-    );
+  const selectedPlatform = askedPlatform.answer?.answers?.[0]?.selected?.[0];
+  const platform = platforms.find(p => p.label === selectedPlatform || p.value === selectedPlatform);
+  if (!platform) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
   }
 
-  // 一次平台标记都没写：若只扫过一个平台，整份文件都属于它（降级，不直接失败）
-  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) {
+  if (signal?.aborted) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  }
+  const askedDirection = await askUserQuestion(ctx, invocation, [topic.askDirection(platform.directions)]);
+  if (!askedDirection.ok) {
     return notify(session, 'error', topic.notify({
-      type: 'platform_not_in_decision',
-      platform: platformCnName,
-      decisionFile: selectedFile,
-      available: [...new Set(sections.map(s => s.headers[0]))],
+      type: askedDirection.failure.type,
+      err: askedDirection.failure.message,
     }));
   }
-
-
-  // 诊断：哪些块缺 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 selectedTitle = askedDirection.answer?.answers?.[0]?.selected?.[0];
+  const direction = platform.directions.find(d => d.title === selectedTitle);
+  if (!direction) {
+    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
   }
-  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) {
+  const suggestion = {
+    platform: platform.label,
+    source_decision_file: resolve(decisionPath),
+    direction_title: direction.title,
+    genre: direction.genre,
+    positioning: direction.positioning,
+    market_score: direction.market_score,
+    recommendation: direction.recommendation,
+  };
+  const validated = validateSuggestion(suggestion);
+  if (!validated.ok) {
     return notify(session, 'error', topic.notify({
-      type: 'tool_deploy_failed',
-      err: deployed.problems.join('；'),
+      type: 'suggestion_write_failed',
+      err: validated.errors.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 分析
+  const outPath = join(projectRoot, NOVEL_SUGGESTION_FILE);
   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），但保险起见
+    atomicWriteJSON(outPath, validated.normalized);
+  } catch (e) {
     return notify(session, 'error', topic.notify({
-      type: 'llm_delivery_failed',
-      err: err.message,
+      type: 'suggestion_write_failed',
+      err: e.message,
     }));
   }
 
   return notify(session, 'success', topic.notify({
-    type: 'path_a_done',
-    platform: platformCnName,
+    type: 'path_a_suggestion_done',
+    platform: platform.label,
     decisionFile: selectedFile,
-    blockCount: matchedSections.length,
-    notes,
+    direction: direction.title,
+    genre: direction.genre,
+    suggestionPath: outPath,
   }));
 }
 
@@ -669,294 +457,176 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
 // ---------------------------------------------------------------------------
 
 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' }));
+  const suggestion = readSuggestion(projectRoot);
+  if (!suggestion) {
+    return notify(session, 'error', topic.notify({ type: 'no_suggestion' }));
   }
-
-  // 弹框：选平台（路径 B 也独立选，因为路径 A 不写文件）
-  if (signal?.aborted) {
-    return notify(session, 'error', topic.notify({ type: 'cancelled' }));
+  if (!existsSync(join(projectRoot, '.fancy', 'workspace.json'))) {
+    return notify(session, 'error', topic.notify({ type: 'material_not_initialized' }));
   }
-  const askedplatformChoice = await askUserQuestion(ctx, invocation, [topic.askPlatform()]);
-  if (!askedplatformChoice.ok) {
+
+  const tools = deployMaterialTools(projectRoot);
+  if (!tools.ok) {
     return notify(session, 'error', topic.notify({
-      type: askedplatformChoice.failure.type,
-      err: askedplatformChoice.failure.message
+      type: 'tool_deploy_failed',
+      err: tools.problems.join('；') || '未知错误',
     }));
   }
-  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（符号链接，已忽略）',
+  try {
+    const { ensureMaterialDatabase } = await import('#material-db');
+    await ensureMaterialDatabase(projectRoot);
+  } catch (e) {
+    return notify(session, 'error', topic.notify({
+      type: 'material_not_initialized',
+      err: e.message,
     }));
-  } 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) {
+  const prompt = topic.setupPrompt({
+    suggestion,
+    queryScript: tools.queryScript,
+    workspace: projectRoot,
+  });
+  let follow;
+  try {
+    follow = await llmFollowup(invocation, prompt, { appendTempRule: false });
+  } catch (e) {
     return notify(session, 'error', topic.notify({
-      type: askedfieldAnswers.failure.type,
-      err: askedfieldAnswers.failure.message
+      type: 'setup_prompt_failed',
+      err: e.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) {
+  if (!follow || follow.ok !== true) {
     return notify(session, 'error', topic.notify({
-      type: 'fields_missing',
-      missing: stillMissing,
+      type: 'setup_prompt_failed',
+      err: (follow && follow.error) || '提示词投递失败',
     }));
   }
+  return notify(session, 'success', topic.notify({
+    type: 'setup_started',
+    genre: suggestion.genre,
+  }));
+}
 
-  // 调用 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;
+/**
+ * 注册 fancy_topic_finalize 工具。
+ *
+ * LLM 在用户确认 5 个候选方案之一后调用：
+ *   - 校验最小 topic（genre + ability 6 kinds + plot 7 kinds）
+ *   - 原子写入 _novel_topic.json
+ *   - 推进 phase
+ *   - 创建/更新项目库
+ */
+async function registerFinalizeTool(ctx) {
+  if (!ctx.tools || typeof ctx.tools.register !== 'function') return;
+  let defineTool;
   try {
-    const parsed = JSON.parse(writeResult.output || '{}');
-    phaseWarning = parsed.phase_warning || null;
+    ({ defineTool } = await import('@deepseek-ai/dsh-tools'));
   } 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;
+  }
+  const json = { type: 'json' };
+  const str = (description) => ({ type: 'string', description });
+  ctx.tools.register(defineTool({
+    name: 'fancy_topic_finalize',
+    description: '用户明确确认某个选题方案后，将 genre + 能力组 6 个 kind + 剧情与脑洞组 7 个 kind 写入 _novel_topic.json，并创建/更新项目库。不要在讨论阶段调用。',
+    parameters: {
+      title: str('选中方案的标题，用作项目名'),
+      genre: str('题材'),
+      ability: json,
+      plot: json,
+      workspace: str('工作区路径；省略时用当前会话目录'),
+    },
+    output: {
+      schema: json,
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args, exec) {
+      const session = exec?.agent?.session;
+      let root;
+      try {
+        root = resolveWorkspace({ cwd: args.workspace || session?.cwd || session?.header?.cwd || process.cwd() });
+      } catch (e) {
+        return { ok: false, error: { code: 'WORKSPACE_NOT_FOUND', message: e.message } };
+      }
+      const title = typeof args.title === 'string' ? args.title.trim() : '';
+      if (!title) {
+        return { ok: false, error: { code: 'TITLE_REQUIRED', message: 'title 必须是非空字符串' } };
+      }
+      const validated = validateMinimalTopic({
+        genre: args.genre,
+        ability: args.ability,
+        plot: args.plot,
+      });
+      if (!validated.ok) {
+        return {
+          ok: false,
+          error: { code: 'TOPIC_INVALID', message: validated.errors.join('；') },
+        };
+      }
 
-  return notify(session, 'success', [
-    baseDone,
-    '',
-    projectAction === 'updated' ? '📚 项目已更新' : '📚 项目已创建',
-    '书名：' + projectInfo.name,
-    'UUID：' + projectInfo.project_id,
-    '目录：' + projectInfo.dir,
-    '数据库：' + projectInfo.db_name,
-  ].join('\n'));
+      const tmpDir = join(root, '.tmp');
+      mkdirSync(tmpDir, { recursive: true });
+      const inputPath = join(tmpDir, 'fancy_topic_finalize_' + Date.now() + '.json');
+      try {
+        writeFileSync(inputPath, JSON.stringify({ title, ...validated.normalized }, null, 2), 'utf8');
+        const written = await spawnScript('node', [
+          SAVE_MINIMAL_TOPIC_SCRIPT,
+          '--project-root', root,
+          '--input', inputPath,
+        ], { timeout: 30000 });
+        if (!written.ok) {
+          return { ok: false, error: { code: 'TOPIC_WRITE_FAILED', message: written.error || '写入失败' } };
+        }
+        let parsed = {};
+        try { parsed = JSON.parse(written.output || '{}'); } catch { /* ignore */ }
+        if (parsed.ok !== true) {
+          return { ok: false, error: { code: 'TOPIC_WRITE_FAILED', message: (parsed.error && parsed.error.message) || '写入失败' } };
+        }
+
+        // 轻量目录（只有 .fancy-deployed）不创建项目库
+        if (!existsSync(join(root, '.fancy', 'workspace.json'))) {
+          return { ok: true, title, topic: parsed.topic, phase: parsed.phase, project: null };
+        }
+
+        try {
+          const { createProject, getProject, updateProjectTopic } = await import('#projects');
+          const { initProjectDatabase } = await import('#db-init');
+          const found = await getProject(root, title);
+          const project = found
+            ? await updateProjectTopic(root, found.project_id, parsed.topic)
+            : await createProject(root, { title, topic: parsed.topic });
+          await initProjectDatabase(root, project.project_id);
+          return {
+            ok: true,
+            title,
+            topic: parsed.topic,
+            phase: parsed.phase,
+            project: {
+              project_id: project.project_id,
+              name: project.name,
+              dir: project.dir,
+              db_name: project.db_name,
+            },
+          };
+        } catch (e) {
+          return {
+            ok: true,
+            title,
+            topic: parsed.topic,
+            phase: parsed.phase,
+            warning: '选题已写入，但项目库创建/更新失败：' + (e && e.message ? e.message : String(e)),
+          };
+        }
+      } finally {
+        try { unlinkSync(inputPath); } catch { /* ignore */ }
+      }
+    },
+  }));
 }
 
 export async function apply(ctx) {
+  await registerFinalizeTool(ctx);
   ctx.commands.register({
     name: 'fancy-topic',
     description: '📝 选题与创意约束 ( usage: /fancy-topic [setup] | help )',