@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-topic/index.js

@@ -3,16 +3,21 @@
  *
  * 两条路径：
  *   A 探索模式  /fancy-topic [参数]            trim 后为空 → 选平台/选文件/LLM 评分
- *   B 敲定模式  /fancy-topic setup             8 弹框收集 → 原子写盘 → phase=topic_done
+ *   B 敲定模式  /fancy-topic setup             逐项弹框 → 原子写盘 → phase=topic_done
  *
  * 不论哪条路径，都先检查 .fancy-deployed 存在且 phase ∈ {scanned, topic_done}。
  */
-import { existsSync, readdirSync, readFileSync } from 'fs';
-import { join } from 'path';
+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'];
 
@@ -42,26 +47,49 @@ 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)) {
-    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 [];
+    const out = Array.isArray(ans.selected) ? ans.selected.slice() : [];
+    if (custom && !out.includes(custom)) out.push(custom);
+    return out;
   }
-  // 单选或文本：取 selected[0] 或 custom
-  return ans.selected?.[0] ?? ans.custom ?? '';
+  // 单选或文本：custom（用户亲手输入的）优先，否则取选中的标签
+  if (custom) return custom;
+  return ans.selected?.[0] ?? '';
 }
 
 function getProjectRoot(session) {
-  // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
-  // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目执行部署与写盘。
-  // 此时返回 null，由调用方给出明确报错。
+  // 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;
-  return cwd || null;
+  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;
+  }
 }
 
 /**
@@ -145,18 +173,33 @@ function splitDecisionSections(content) {
     const platform = title ? platformOfHeader(title) : null;
 
     if (platform) {
-      const isStartMark = /[-—–\s]*start\s*$/i.test(title);
-      const isEndMark = /[-—–\s]*end\s*$/i.test(title);
+      // 分隔符是必需的：`# 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 行：关闭当前块（同平台），**不开新块**
-      // —— 少了这一步，"-end" 自己会变成一个空的新块。
-      if (isEndMark && cur && cur.platform === platform) {
+      // -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 后面紧跟一个报告大标题。
@@ -169,6 +212,7 @@ function splitDecisionSections(content) {
       if (cur) raw.push(cur);
       cur = {
         platform,
+        key: titleKey,
         headers: [`# ${title}`],
         bodyLines: [],
         hasStart: isStartMark,
@@ -279,12 +323,41 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
 
   // 扫描 扫榜结果/ 目录下的 topic_decision_<date>.md 文件
   const scanDir = join(projectRoot, '扫榜结果');
-  const decisionFiles = existsSync(scanDir)
-    ? readdirSync(scanDir)
+  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()  // 最新的在前
-    : [];
+        .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' }));
@@ -319,12 +392,46 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
   // 读取 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: 'write_failed',
-      err: `读取 ${selectedFile} 失败: ${e.message}`,
+      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,
     }));
   }
 
@@ -337,6 +444,96 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
   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);
@@ -366,6 +563,7 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     }));
   }
 
+
   // 诊断：哪些块缺 start/end 标记（LLM 格式不规范，但已按标题隔离，不影响正确性）
   // 分开统计 -start / -end：只缺 -end 的块被说成"标记缺失"是错的 ——
   // 那种块明明写着 -start，却出现在告警名单里，用户会以为切错了。
@@ -382,14 +580,24 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     notes.push(`其中 ${parts.join('；')}，已按标题行切分隔离，不影响平台归属。`);
   }
 
-  // 拼装发给 LLM 的提示
+  // 拼装发给 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}（${s.headers.join(' / ')}）\n${s.body}`
+    `【数据块 ${i + 1}】\n${s.body}`
   ).join('\n\n');
 
   // 汇总按平台分组（保持文件里的出现顺序），并给出每个平台的块数。
   // 之前是"每块一行"，同一个平台会出现多行、总数也和块数对不上；
-  // 术语统一用"块"（与下面的 "## 块 N" 标记一致）。
+  // 术语统一用"块"（与下面的 "【数据块 N】" 标记一致）。
   const summaryByPlatform = new Map();
   for (const s of sections) {
     const name = platformCn(s.platform) || s.platform;
@@ -401,13 +609,31 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     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 分析
@@ -417,15 +643,15 @@ async function pathExplore(ctx, session, invocation, signal, projectRoot) {
     // 否则投递失败也会报"分析已完成"
     if (!follow || follow.ok !== true) {
       return notify(session, 'error', topic.notify({
-        type: 'write_failed',
-        err: `触发 LLM 失败: ${(follow && follow.error) || '提示词投递失败'}`,
+        type: 'llm_delivery_failed',
+        err: (follow && follow.error) || '提示词投递失败',
       }));
     }
   } catch (err) {
     // llmFollowup 通常不抛错（它自己 try/catch），但保险起见
     return notify(session, 'error', topic.notify({
-      type: 'write_failed',
-      err: `触发 LLM 失败: ${err.message}`,
+      type: 'llm_delivery_failed',
+      err: err.message,
     }));
   }
 
@@ -495,10 +721,24 @@ async function pathSetup(ctx, session, invocation, signal, projectRoot) {
   // 那段代码对用户完全不可见，属于死代码，已删除。
   const suggestionPath = join(projectRoot, '_novel_topic_suggestion.json');
   let suggestion = null;
-  if (existsSync(suggestionPath)) {
+  if (existsSync(suggestionPath) && lstatSync(suggestionPath).isSymbolicLink()) {
+    extraNotes.push(topic.notify({
+      type: 'suggestion_corrupt',
+      file: '_novel_topic_suggestion.json（符号链接，已忽略）',
+    }));
+  } else if (existsSync(suggestionPath)) {
     try {
-      suggestion = JSON.parse(readFileSync(suggestionPath, 'utf-8'));
-    } catch (_) { /* 损坏就忽略 */ }
+      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，决定是否应用建议值
@@ -508,11 +748,27 @@ async function pathSetup(ctx, session, invocation, signal, projectRoot) {
   // 读 _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 = JSON.parse(readFileSync(novelTopicPath, 'utf-8'));
+      const data = normalizeTopicData(JSON.parse(readFileSync(novelTopicPath, 'utf-8')));
       if (!data.platform) return data; // 没有 platform 字段就当作一致（兼容旧数据）
       return platformEqual(data.platform, selectedPlatform) ? data : {};
-    } catch (_) { return {}; }
+    } 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 才显示"推荐值"
@@ -537,7 +793,7 @@ async function pathSetup(ctx, session, invocation, signal, projectRoot) {
     return notify(session, 'error', topic.notify({ type: 'cancelled' }));
   }
 
-  // 收集 8 字段的值。
+  // 收集所有选题字段的值。
   // 首次收集与必填重试轮必须走同一套取值逻辑（collectAnswerValue）——
   // 否则多选字段会在重试轮塌成字符串、丢掉第 2 项以后的选择。
   const fieldValues = { platform: selectedPlatform };
@@ -615,37 +871,95 @@ async function pathSetup(ctx, session, invocation, signal, projectRoot) {
   if (signal?.aborted) {
     return notify(session, 'error', topic.notify({ type: 'cancelled' }));
   }
-  const writeResult = await spawnScript('node', [
+  const writeArgs = [
     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 });
+  ];
+  // 字段清单来自 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 }));
   }
 
-  return notify(session, 'success', topic.notify({
+  // 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: Object.keys(fieldValues).length,
-    extra: extraNotes.join('\n\n'),
-  }));
+    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] )',
+    description: '📝 选题与创意约束 ( usage: /fancy-topic [setup] | help )',
     input: {
       hint: '.',
     },
@@ -654,25 +968,60 @@ export async function apply(ctx) {
       const { signal } = invocation;
 
       // 1. 解析路径：A 探索 / B 敲定
+      // 只允许两种形式：
+      //   /fancy-topic          → 探索
+      //   /fancy-topic setup    → 敲定
+      // 其他任何参数都必须报错，不能悄悄当成探索/敲定。
       const rawInput = (invocation.rawInput || '').trim();
-      const isSetupPath = rawInput.toLowerCase() === 'setup';
+      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);
-      if (!projectRoot) {
+      let projectRootAbs = projectRoot ? resolve(projectRoot) : null;
+      if (!projectRootAbs) {
         return notify(session, 'error', topic.notify({
           type: 'no_project_root',
-          err: '会话未提供 cwd'
+          err: '会话未提供当前工作目录'
         }));
       }
-      if (!existsSync(join(projectRoot, '.fancy-deployed'))) {
+      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(projectRoot);
+      const deployedState = readDeployedState(projectRootAbs);
       if (deployedState.status === DEPLOYED_STATUS.CORRUPT
         || deployedState.status === DEPLOYED_STATUS.NO_PHASE
         || deployedState.status === DEPLOYED_STATUS.UNKNOWN_PHASE) {
@@ -680,7 +1029,7 @@ export async function apply(ctx) {
         // 文件**存在**时 bootstrap 会拒绝执行（它只在文件不存在时才初始化），
         // 让用户去跑 bootstrap 等于把人送进死胡同。
         return notify(session, 'error',
-          deployedStateProblemText(deployedState, { projectRoot })
+          deployedStateProblemText(deployedState, { projectRoot: projectRootAbs })
           || topic.notify({
             type: 'phase_unreadable',
             err: deployedState.status === DEPLOYED_STATUS.CORRUPT
@@ -693,11 +1042,15 @@ export async function apply(ctx) {
         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, projectRoot);
+        return pathSetup(ctx, session, invocation, signal, projectRootAbs);
       } else {
-        return pathExplore(ctx, session, invocation, signal, projectRoot);
+        return pathExplore(ctx, session, invocation, signal, projectRootAbs);
       }
     },
   });