@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-topic/templates.js

@@ -1,6 +1,57 @@
 /**
- * fancy-topic templates — 通知 + 弹框 + 字段定义
+ * fancy-topic 模板层 — 通知 + 弹框 + 字段定义 + 提示词渲染
+ *
+ * ## 分层
+ *
+ *   prompts/01-exploration-prompt.md  提示词层：静态任务契约、数据边界、
+ *                                      保存脚本的退出码与失败处置。
+ *                                      **不含任何直接写目标文件的命令**。
+ *   templates.js（本文件）             模板层：字段/选项定义、把动态数据注入提示词。
+ *   scripts/select-topic.js           脚本层：setup 写盘 + 字段校验 + phase 推进。
+ *   scripts/save-suggestion.js        脚本层：探索建议的校验 + 原子写盘。
+ *
+ * 提示词只描述契约；校验与写盘都在脚本里，模型按退出码与 stdout JSON 决策。
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
+import { shellSingleQuote } from '#path-guard';
+import {
+  TOPIC_FIELDS,
+  TOPIC_FIELD_CN,
+  GENRE_OPTIONS,
+  topicFieldListBlock,
+  topicJsonTemplateBlock,
+} from '#topic-fields';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** 保存建议的唯一入口（校验 + 原子写盘都在脚本里） */
+export const SAVE_SUGGESTION_SCRIPT = join(__dirname, 'scripts', 'save-suggestion.js');
+/** 静态提示词契约（**提示词层**；动态字段由本文件注入） */
+export const EXPLORATION_PROMPT_FILE = join(__dirname, 'prompts', '01-exploration-prompt.md');
+
+/**
+ * 渲染探索提示词：静态契约在 prompts/01-exploration-prompt.md，
+ * 数据、块清单、路径与脚本命令由本文件注入。
+ *
+ * @param {Record<string, string|number>} vars
+ * @returns {string}
  */
+export function renderExplorationPrompt(vars) {
+  let text = readFileSync(EXPLORATION_PROMPT_FILE, 'utf-8');
+  const meta = text.indexOf('\n@meta-only\n');
+  if (meta !== -1) {
+    text = text.slice(meta + '\n@meta-only\n'.length);
+    text = text.replace(/^\s*---\s*\n/, '');
+  }
+  for (const [key, value] of Object.entries(vars)) {
+    text = text.split('${' + key + '}').join(value === undefined || value === null ? '' : String(value));
+  }
+  text = text.replace(/\$\{[a-z_]+\}/g, '');
+  // 与旧版 array.join('\n') 的输出保持一致：末尾不留多余换行
+  return text.replace(/\n$/, '');
+}
 
 const PLATFORM_OPTIONS = [
   { label: '番茄',  value: 'fanqie'  },
@@ -9,16 +60,39 @@ const PLATFORM_OPTIONS = [
   { label: '七猫',  value: 'qimao'   },
 ];
 
-const GENRE_OPTIONS = [
-  { label: '玄幻', value: 'xianxia' },
-  { label: '都市', value: 'urban' },
-  { label: '言情', value: 'romance' },
-  { label: '悬疑', value: 'mystery' },
-  { label: '历史', value: 'history' },
-  { label: '科幻', value: 'scifi' },
-  { label: '仙侠', value: 'xianxia-cultivation' },
-  { label: '其他', value: 'other' },
-];
+/**
+ * 数据里如果自带 `<<<FANCY_SCAN_DATA>>>` / `<<<END_FANCY_SCAN_DATA>>>`，
+ * 会把哨兵提前闭合、让后面的数据变成“任务指令”。这里把数据里的同名
+ * 哨兵改成带 `_ESCAPED` 的形式，外层哨兵保持固定（测试与解析都认）。
+ */
+function escapeScanSentinels(text) {
+  return String(text == null ? '' : text)
+    .replace(/<<<FANCY_SCAN_DATA>>>/g, '<<<FANCY_SCAN_DATA_ESCAPED>>>')
+    .replace(/<<<END_FANCY_SCAN_DATA>>>/g, '<<<END_FANCY_SCAN_DATA_ESCAPED>>>');
+}
+
+/**
+ * 块清单里只展示块标题：去掉 Markdown 的 `#` 前缀与行尾的 `-start` / `-end`
+ * 标记，同一块里重复的标题只留一次。
+ *
+ * 标记只用来切块，不是给人读的内容；数据块正文里已经不再带它们，
+ * 参考文件清单也没必要重复显示。
+ */
+function summarizeBlockHeaders(headers) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of headers || []) {
+    const text = String(raw)
+      .replace(/^\s*#{1,6}\s*/, '')
+      .replace(/(?:^|[-—–\s])(?:start|end)\s*$/i, '')
+      .trim();
+    if (text && !seen.has(text)) {
+      seen.add(text);
+      out.push(text);
+    }
+  }
+  return out;
+}
 
 // 「取消（重新扫榜）」选项的 label。
 // DSH 的 AskUserQuestionOption 只有 label/description 两个合法字段，
@@ -48,26 +122,17 @@ function toAskOptions(options) {
 }
 
 /**
- * 8 个字段定义（路径 B 弹框用）
- * 每个字段：id、prompt 提示、kind（text/number/multiselect）、options、defaultGetter
+ * 选题字段定义（路径 B 弹框用）。
+ *
+ * 字段清单不在这里维护 —— 全部来自 `lib/topic-fields.js`：
+ * `_novel_topic_suggestion.json`、`_novel_topic.json`、探索提示词、
+ * setup 弹框、写盘脚本、story-builder 快照共用同一份。
+ *
+ * 2026-10-30 重新设计：
+ *   - `core_summary` 与「定位」合并为 `positioning`；
+ *   - `direction_design` 大字符串拆成 11 个平级字段，每项一个弹框；
+ *   - 字段数由 `TOPIC_FIELDS.length` 决定，提示词与通知里不再写死“10 个”。
  */
-const TOPIC_FIELDS = [
-  { id: 'book_name',        label: '书名',         kind: 'text',        required: true,
-    placeholder: '例如：诡秘之主' },
-  { id: 'genre',            label: '题材',         kind: 'select',      options: GENRE_OPTIONS, required: true },
-  { id: 'target_words',     label: '目标字数',     kind: 'number',      required: true,
-    placeholder: '例如：2000000' },
-  { id: 'target_chapters',  label: '目标章数',     kind: 'number',      required: true,
-    placeholder: '例如：600' },
-  { id: 'core_summary',     label: '一句话故事',   kind: 'text',        required: true,
-    placeholder: '用一句话概括故事核心' },
-  { id: 'core_conflict',    label: '核心冲突',     kind: 'text',        required: true,
-    placeholder: '故事的主要矛盾是什么' },
-  { id: 'hard_constraints', label: '硬门禁',       kind: 'multiselect', required: true,
-    description: '绝对不能违反的约束；可多选；如无约束，输入 "无"' },
-  { id: 'anti_tropes',      label: '反套路',       kind: 'multiselect', required: true,
-    description: '必须避免的俗套；可多选；如无，输入 "无"' },
-];
 
 export const topic = {
   PLATFORM_OPTIONS,
@@ -102,7 +167,7 @@ export const topic = {
   },
 
   /**
-   * 路径 B：8 字段弹框
+   * 路径 B：选题字段弹框
    *
    * 问题对象只允许 DSH 的合法字段：id / question / detail / header /
    * options / multiSelect / intent。
@@ -172,6 +237,8 @@ export const topic = {
       // 两个空格写在字符串字面量里（'  \n'），源码中没有行尾空白，
       // 不会被格式化工具或编辑器悄悄吃掉。
       const hints = [];
+      // 字段已经拆成 11 个平级项，单个字段的值是短文本/单段说明，
+      // 直接和“当前值 / 推荐值”放同一行即可；两项之间仍用硬换行分隔。
       if (curStr) hints.push(`📌 当前值：${curStr}`);
       if (sugStr) hints.push(`💡 推荐值：${sugStr}`);
 
@@ -198,22 +265,47 @@ export const topic = {
    * @param {object} args
    * @param {string} args.platform - 中文平台名（番茄/起点/晋江/七猫）
    * @param {string} args.decisionFile - topic_decision_<date>.md 文件名
+   * @param {string} [args.decisionPath] - 该文件的**绝对路径**。
+   *        只给文件名的话，模型拼不出它在哪儿（实际在 `<工作区目录>/扫榜结果/` 下），
+   *        写进 `source_decision_file` 的就是个解析不了的裸名。
    * @param {string} args.blocks - 拼接好的内容块（多个 # start/end 块用 --- 分隔）
    * @param {number} args.blockCount - 本次平台用到的块数
    * @param {Array} args.sectionSummary - 按平台分组的全文件块清单
    *        [{ platform: '起点', blocks: [{ headers: [...] }, ...] }, ...]
    * @param {string[]} args.notes - 解析备注（写进提示词，让用户看见解析情况）
+   * @param {string} args.projectRoot - 工作区目录绝对路径。
+   *        用来把建议文件写成**绝对路径** —— 只给相对路径的话，
+   *        LLM 的工作目录未必是工作区目录，文件会写到别的地方，
+   *        插件读 `<工作区目录>/_novel_topic_suggestion.json` 时读到的是空。
+   * @param {string} [args.saveScriptPath] - 工作区内部署后的 save-suggestion.js
+   *        绝对路径。不传时回退插件内路径，仅用于测试/直接调用；
+   *        生产路径必须由 index.js 部署后传入。
    */
-  explorePrompt({ platform, decisionFile, blocks, blockCount, sectionSummary = [], notes = [] }) {
+  explorePrompt({ platform, decisionFile, decisionPath, blocks, blockCount, sectionSummary = [], notes = [], projectRoot, saveScriptPath }) {
+    // 建议文件路径：插件读的是 <工作区目录>/_novel_topic_suggestion.json，
+    // 提示词里必须给**同一个绝对路径**，否则 LLM 可能写到别处。
+    const suggestionPath = projectRoot
+      ? join(projectRoot, '_novel_topic_suggestion.json')
+      : '_novel_topic_suggestion.json';
+    // 输入 JSON 放 <工作区目录>/.tmp；目标文件由脚本原子写入工作区目录。
+    // 文件名带上项目/来源文件的哈希，避免两个会话共用同一个临时文件。
+    const inputKey = createHash('sha256')
+      .update(`${projectRoot || ''}|${decisionPath || decisionFile || ''}`)
+      .digest('hex')
+      .slice(0, 10);
+    const tempDir = projectRoot ? join(projectRoot, '.tmp') : '.tmp';
+    const suggestionInputPath = join(tempDir, `fancy_topic_suggestion_input_${inputKey}.json`);
+    const saveScript = saveScriptPath || SAVE_SUGGESTION_SCRIPT;
     const sourceLines = [];
     if (sectionSummary.length) {
       // 总数是**块数**（不是平台数）：同一平台可能有多个 -start 块
       const totalBlocks = sectionSummary.reduce((n, s) => n + s.blocks.length, 0);
       sourceLines.push(`该文件按平台切分出 ${totalBlocks} 块：`);
       for (const s of sectionSummary) {
-        sourceLines.push(`  · ${s.platform}（${s.blocks.length} 块）：`);
+        sourceLines.push(`  - ${s.platform}（${s.blocks.length} 块）：`);
         s.blocks.forEach((b, i) => {
-          sourceLines.push(`      ${i + 1}. ${b.headers.join(' / ')}`);
+          const titles = summarizeBlockHeaders(b.headers);
+          sourceLines.push(`      ${i + 1}. ${escapeScanSentinels(titles.join(' / ') || '（无标题）')}`);
         });
       }
       sourceLines.push(`本次只使用「${platform}」的 ${blockCount} 块。`);
@@ -221,150 +313,161 @@ export const topic = {
     if (notes.length) {
       sourceLines.push('');
       sourceLines.push('解析说明：');
-      for (const n of notes) sourceLines.push(`  · ${n}`);
+      for (const n of notes) sourceLines.push(`  - ${escapeScanSentinels(n)}`);
     }
-    return [
-      `## 选题探索任务`,
-      ``,
-      `平台：${platform}`,
-      `参考文件：${decisionFile}（含 ${blockCount} 个内容块）`,
-      ...(sourceLines.length ? ['', ...sourceLines] : []),
-      ``,
-      `以下是用户选中的 topic_decision 文件中与"${platform}"相关的所有内容块（每块用 ## 块 N 标记）：`,
-      ``,
-      blocks,
-      ``,
-      `请执行以下分析：`,
-      ``,
-      `### 第一部分：8 个字段建议`,
-      `基于扫榜内容，给出以下字段的推荐值（**必须**忽略历史上下文和之前的选择，且**禁止**使用单引号或者双引号）：`,
-      `1. **书名**（book_name）— 根据榜单上同题材书籍的命名方式给出契合本平台风格的建议`,
-      `2. **题材**（genre）— 根据榜单中的热门题材给出契合的建议`,
-      `3. **目标字数**（target_words）— 整数，例如 2000000`,
-      `4. **目标章数**（target_chapters）— 整数，例如 600`,
-      `5. **一句话故事**（core_summary）— 50 字以内概括核心`,
-      `6. **核心冲突**（core_conflict）— 主要矛盾是什么`,
-      `7. **硬门禁**（hard_constraints）— 绝对不能违反的约束（可多值）`,
-      `8. **反套路**（anti_tropes）— 必须避免的俗套（可多值）`,
-      ``,
-      `每个字段请给出一个推荐值 + 一句话解释为什么这样推荐。`,
-      ``,
-      `### 第二部分：6 维评分`,
-      `基于上面给出的建议，对"在 ${platform} 平台写一本新书"这件事，从以下 6 个维度评分（1-10）：`,
-      `1. **市场热度** — 该平台当前题材热度如何，在读人数越多、增长趋势越快、月票积分等指标越高则评分越高`,
-      `2. **竞争格局** — 同类作品的多少。同类作品多+市场热度高->竞争一般，同类作品少+市场热度高->竞争少,竞争越少评分越高`,
-      `3. **受众规模** — 题材潜在读者群大小，读者越多、积分越多则评分越高`,
-      `4. **创作难度** — 作者需要投入的精力，投入精力越少评分越高`,
-      `5. **变现潜力** — 商业化前景，变现能力越强评分越高`,
-      `6. **合规风险** — 低/中/高，风险越低评分越高、风险越高评分越低`,
-      `最后给出综合分（1-10）和是否值得进入的结论。`,
-      ``,
-      `### 第三部分：保存建议`,
-      `在你给出 8 个字段推荐值后，把推荐值保存到 \`_novel_topic_suggestion.json\`：`,
-      `注意：platform 字段必须写平台中文名（"${platform}"），不要写英文 value（如 "qidian"）。` +
-        `所有字段值必须是合法 JSON（双引号、逗号、换行都要转义或避开）。` +
-        `core_summary / core_conflict 中如需引用书名 / 概念，用全角引号"…"或『…』，避免与 JSON 双引号冲突。`,
-      ``,
-      `\`\`\`json`,
-      `{`,
-      `  "book_name": "...",`,
-      `  "genre": "...",`,
-      `  "target_words": 2000000,`,
-      `  "target_chapters": 600,`,
-      `  "core_summary": "...",`,
-      `  "core_conflict": "...",`,
-      `  "hard_constraints": ["..."],`,
-      `  "anti_tropes": ["..."],`,
-      `  "platform": "${platform}",`,
-      `  "source_decision_file": "${decisionFile}"`,
-      `}`,
-      `\`\`\``,
-      ``,
-      `### 第四部分：与用户对话`,
-      `1. **必须**以用户可见的方式**完整**展示出 8 个字段推荐值和 6 维评分`,
-      `2. 提醒用户可继续根据当前给出的 8 个字段推荐值和 6 维评分展开讨论,根据用户的需求进行多次修正,并将用户最终的意见更新至 _novel_topic_suggestion.json 中`,
-      `3. 提醒用户运行 /fancy-topic setup 提交最终决定`,
-    ].join('\n');
+    return renderExplorationPrompt({
+      platform,
+      decision_path: decisionPath || decisionFile,
+      source_summary_block: sourceLines.length ? '\n' + sourceLines.join('\n') + '\n' : '',
+      data_block: escapeScanSentinels(blocks),
+      field_count: TOPIC_FIELDS.length,
+      field_list_block: topicFieldListBlock(),
+      json_template_block: topicJsonTemplateBlock(),
+      suggestion_path: suggestionPath,
+      suggestion_input_path: suggestionInputPath,
+      suggestion_input_quoted: shellSingleQuote(suggestionInputPath),
+      save_script_quoted: shellSingleQuote(saveScript),
+      project_root_quoted: shellSingleQuote(projectRoot || ''),
+      platform_quoted: shellSingleQuote(platform),
+      source_decision_quoted: shellSingleQuote(decisionPath || decisionFile),
+    });
   },
 
   /**
    * 通知模板（左侧消息栏）
    */
-  notify({ type, platform, phase, decisionFile, blockCount, fieldCount, missing, err, projectRoot, extra, available, notes }) {
+  notify({ type, platform, phase, decisionFile, blockCount, fieldCount, missing, err, projectRoot, extra, available, notes, file, reasons, arg }) {
     switch (type) {
+      case 'help':
+        return `📝 选题 用法
+
+/fancy-topic         探索选题：读取扫榜结果，生成字段建议和 6 维评分
+/fancy-topic setup   敲定选题：逐项确认字段并写入 _novel_topic.json
+/fancy-topic help    显示本帮助
+
+作用：生成/确认选题与创意约束，供 fancy-build 使用。`;
+
+      case 'invalid_argument':
+        return `❌ 参数无效：${arg || '（空）'}\n`
+          + '/fancy-topic 支持以下用法：\n'
+          + `- /fancy-topic：不带参数，进入探索模式 —— 读取扫榜结果，生成 ${TOPIC_FIELDS.length} 个字段建议和 6 维评分；\n`
+          + '- /fancy-topic setup：带 setup 参数，进入敲定模式 —— 逐项确认选题字段并写入 _novel_topic.json；\n'
+          + '- /fancy-topic help：查看本命令帮助。';
+
       case 'cancelled':
-        return '🚫 已取消';
+        return '🚫 操作已取消。';
 
       case 'no_provider':
-        return '⚠️ 当前环境不支持交互式提问。请在 dsh-tui 中运行此命令，或确保 web UI 已正确加载交互组件。';
+        return '⚠️ 当前运行环境不支持交互式提问。请在 dsh-tui 中运行该命令，或确认 Web UI 已正确加载交互组件。';
 
       case 'no_project_root':
-        return '❌ 无法确定项目目录：' + (err || '会话未提供 cwd') + '。请在项目目录下运行该命令。';
+        return '❌ 无法确定工作区目录：' + (err || '会话未提供当前工作目录') + '。请在工作区目录下运行该命令。';
 
       case 'ask_failed':
-        return '❌ 提问失败：' + (err || '未知错误');
+        return '❌ 交互提问失败：' + (err || '未知错误');
 
       case 'not_initialized':
-        return '⚠️ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+        return '⚠️ 当前目录不属于已初始化的 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。';
 
       case 'phase_wrong':
-        return `⚠️ 当前 phase（${phase || '未知'}）不允许运行 /fancy-topic，请先运行 /fancy-scan 扫榜。`;
+        return `⚠️ 当前工作区阶段为「${phase || '未知'}」，不能运行 /fancy-topic。请先运行 /fancy-scan 完成扫榜。`;
 
       case 'phase_unreadable':
         return (
-          `❌ 状态文件 .fancy-deployed 无法读取（${err || '内容异常'}），无法确定项目状态。\n` +
-          '请检查该文件是否被手工改坏，或重新运行 /fancy-bootstrap 初始化。'
+          `❌ 无法读取状态文件 .fancy-deployed（${err || '内容异常'}），因此无法确定当前工作区阶段。\n` +
+          '请检查该文件是否被手动修改或损坏；如无法修复，请重新运行 /fancy-bootstrap 初始化工作区。'
         );
 
       case 'no_decision_file':
-        return '⚠️ 未找到 topic_decision_<date>.md 文件。请先运行 /fancy-scan 采集榜单并等待 LLM 分析完成';
+        return '⚠️ 未找到 topic_decision_<date>.md 文件。请先运行 /fancy-scan 采集榜单，并等待 LLM 完成分析。';
+
+      case 'suggestion_corrupt':
+        return (
+          `⚠️ 无法读取 ${file || '_novel_topic_suggestion.json'}（不是合法 JSON），本次已忽略其中的推荐值。\n` +
+          '该文件通常由上一次 LLM 写入。重新运行 /fancy-topic 可生成新的建议文件。'
+        );
+
+      case 'current_values_corrupt':
+        return (
+          `⚠️ 无法读取 ${file || '_novel_topic.json'}（不是合法 JSON），本次按“无当前值”处理。\n` +
+          '该文件保存已确认的选题设定；损坏会导致后续阶段无法读取。请检查文件内容，或删除后重新运行 /fancy-topic setup。'
+        );
 
       case 'no_decision_block':
         return (
-          `⚠️ 在 ${decisionFile || '所选文件'} 里没有找到任何 "# 平台-榜单-日期-start/end" 内容块。\n` +
-          '多半是 LLM 没有按约定格式写入，建议重新运行 /fancy-scan 触发分析。'
+          `⚠️ 在 ${decisionFile || '所选文件'} 中未找到任何 “# 平台-榜单-日期-start/end” 内容块。\n` +
+          '通常是因为 LLM 未按约定格式写入。建议重新运行 /fancy-scan 触发分析。'
+        );
+
+      case 'empty_decision_file':
+        return (
+          `❌ ${decisionFile || '所选文件'} 为空，未包含任何分析内容。\n` +
+          '空文件无法用于选题。请重新运行 /fancy-scan，等待 LLM 写入报告正文。'
         );
 
       case 'platform_not_in_decision':
         return (
-          `⚠️ 在 ${decisionFile || '所选文件'} 里没有找到「${platform || ''}」的内容块。\n` +
-          `该文件里已有的块：${(available && available.length) ? available.join('、') : '（无）'}\n` +
-          '请确认是否扫过该平台。'
+          `⚠️ 在 ${decisionFile || '所选文件'} 中未找到「${platform || ''}」的内容块。\n` +
+          `文件中已有的内容块：\n${(available && available.length) ? available.map((b, i) => `${i + 1}. ${b}`).join('\n') : '（无）'}\n` +
+          '请确认是否已采集该平台。'
         );
 
       case 'invalid_platform':
-        return `❌ 无效的平台：${platform}`;
+        return `❌ 平台无效：${platform}。`;
+
+      case 'block_body_invalid':
+        return (
+          `❌ ${decisionFile || '所选文件'} 中的内容块正文缺失（标记行存在，但内容为空或仅为占位符）。\n` +
+          (reasons && reasons.length ? reasons.map(r => '- ' + r).join('\n') + '\n' : '') +
+          '基于此类内容生成的选题结论缺少依据。\n' +
+          '请重新运行 /fancy-scan，让 LLM 重新写入报告正文。'
+        );
 
       case 'path_a_done': {
         const noteText = (notes && notes.length)
           ? '\n' + notes.map(n => 'ℹ️ ' + n).join('\n')
           : '';
         return (
-          `📊 已根据扫榜结果请 LLM 分析 ${blockCount || '?'} 个数据块\n` +
+          `📊 已请求 LLM 分析 ${blockCount || '?'} 个数据块\n` +
           `📚 平台：${platform || ''}\n` +
           `📁 参考：${decisionFile || ''}` +
           noteText + '\n' +
-          `💡 LLM 即将在对话中给出 6 维评分 + 8 字段建议；敲定后请运行 /fancy-topic setup 写入最终决定`
+          `💡 LLM 将在对话中给出 6 维评分与 ${TOPIC_FIELDS.length} 个字段建议。确认选题后，请运行 /fancy-topic setup 写入最终决定。`
         );
       }
 
       case 'path_b_done':
-        return `✅ 选题已确认！
-下一步：
-运行 /fancy-story-builder 构建故事 (在此之前可选择运行 /fancy-analyze 拆解同题材爆款小说)` +
+        return `✅ 选题已确认。
+下一步：运行 /fancy-build scale 构建故事（在此之前可选择运行 /fancy-analyze 拆解同题材爆款小说）。` +
           (extra ? '\n\n' + extra : '');
 
       case 'write_failed':
         return '❌ 写入 _novel_topic.json 失败：' + (err || '未知错误');
 
-      case 'fields_missing':
-        return `⚠️ 以下必填字段未填写，请补全：${(missing || []).join('、')}`;
+      case 'tool_deploy_failed':
+        return '❌ 部署 fancy-topic 只读工具失败：' + (err || '未知错误') +
+          '\n未向 LLM 发送提示词；请修复工作区目录权限后重试。';
+
+      case 'llm_delivery_failed':
+        return '❌ 向 LLM 发送分析提示词失败：' + (err || '提示词发送失败') +
+          '\n数据文件未被修改，请重新运行 /fancy-topic。';
+
+      case 'read_failed':
+        return '❌ 读取扫榜分析失败：' + (err || '未知错误');
+
+      case 'fields_missing': {
+        const labels = (missing || []).map((id) => {
+          const label = TOPIC_FIELD_CN[id];
+          return label && label !== id ? `${label}（${id}）` : id;
+        });
+        return `⚠️ 以下必填字段尚未填写，请补全：${labels.join('、')}`;
+      }
 
       case 'path_a_rescan':
-        return '🔄 已选择重新扫榜。请运行 /fancy-scan';
+        return '🔄 已选择重新扫榜。请运行 /fancy-scan。';
 
       case 'create_skeleton':
-        return '📝 未找到 _novel_topic.json，已创建骨架文件';
+        return '📝 未找到 _novel_topic.json，已创建骨架文件。';
 
       default:
         return String(type);

package/plugins/fancy-topic/tool-deploy.js

@@ -0,0 +1,200 @@
+/**
+ * fancy-topic 工具部署
+ *
+ * LLM 只应该执行工作区内的只读脚本，不能去 node_modules 里跑脚本：
+ *   - 插件目录随安装位置变化，提示词里的路径容易抄错；
+ *   - 包管理器目录不该承担运行职责；
+ *   - 工作区内的脚本可以统一去掉写权限，避免模型改脚本绕过校验。
+ *
+ * 这里把 `save-suggestion.js` 及其 import 闭包复制到
+ * `<工作区目录>/.fancy-tools/fancy-topic/`，并写成 0444 只读。
+ */
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from 'fs';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { atomicWriteFile } from '#atomic-write';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+/** 工作区内的工具目录（相对工作区目录） */
+export const TOPIC_TOOL_DIR = join('.fancy-tools', 'fancy-topic');
+
+/**
+ * 部署清单。
+ *
+ * `src` 相对插件包根，`dest` 相对 `.fancy-tools/fancy-topic/`。
+ * `save-suggestion.js` 的 import 闭包必须完整，否则启动就是
+ * ERR_MODULE_NOT_FOUND。
+ */
+export const TOPIC_FILES = [
+  { src: 'lib/error-codes.js', dest: join('lib', 'error-codes.js') },
+  { src: 'lib/atomic-write.js', dest: join('lib', 'atomic-write.js') },
+  { src: 'lib/deployed-state.js', dest: join('lib', 'deployed-state.js') },
+  { src: 'lib/path-guard.js', dest: join('lib', 'path-guard.js') },
+  { src: 'lib/direction-labels.js', dest: join('lib', 'direction-labels.js') },
+  { src: 'lib/topic-fields.js', dest: join('lib', 'topic-fields.js') },
+  { src: 'lib/topic-schema.js', dest: join('lib', 'topic-schema.js') },
+  { src: 'plugins/fancy-topic/scripts/save-suggestion.js', dest: join('scripts', 'save-suggestion.js') },
+];
+
+/** 部署目录的 package.json：ESM + import aliases */
+export const TOPIC_PACKAGE_JSON = {
+  name: 'fancy-tools-fancy-topic',
+  private: true,
+  type: 'module',
+  imports: {
+    '#error-codes': './lib/error-codes.js',
+    '#atomic-write': './lib/atomic-write.js',
+    '#deployed-state': './lib/deployed-state.js',
+    '#path-guard': './lib/path-guard.js',
+    '#direction-labels': './lib/direction-labels.js',
+    '#topic-fields': './lib/topic-fields.js',
+    '#topic-schema': './lib/topic-schema.js',
+  },
+};
+
+/** 确保目录存在且不是符号链接（逐级 lstat，防 symlink 穿透） */
+function ensureRealDir(dir, problems) {
+  let st = null;
+  try { st = lstatSync(dir); } catch { /* 不存在 */ }
+  if (st) {
+    if (st.isSymbolicLink()) {
+      problems.push(`${dir} 是符号链接，拒绝部署工具（请换成真实目录）`);
+      return false;
+    }
+    if (!st.isDirectory()) {
+      problems.push(`${dir} 已存在但不是目录，拒绝部署工具`);
+      return false;
+    }
+    return true;
+  }
+  try {
+    mkdirSync(dir);
+    return true;
+  } catch (e) {
+    problems.push(`创建目录失败 ${dir}：${e.message}`);
+    return false;
+  }
+}
+
+/** 内容相同就跳过；目标存在但是符号链接/目录则拒绝。 */
+function writeIfChanged(dest, content, problems, written, unchanged) {
+  let st = null;
+  try { st = lstatSync(dest); } catch { /* 不存在 */ }
+  if (st) {
+    if (st.isSymbolicLink()) {
+      problems.push(`${dest} 是符号链接，拒绝覆盖`);
+      return;
+    }
+    if (!st.isFile()) {
+      problems.push(`${dest} 已存在但不是普通文件，拒绝覆盖`);
+      return;
+    }
+    try {
+      if (readFileSync(dest, 'utf-8') === content) {
+        // 老项目里的工具文件可能是 0644；内容没变也要去掉写权限。
+        try { chmodSync(dest, 0o444); } catch (e) {
+          problems.push(`设置只读权限失败 ${dest}：${e.message}`);
+        }
+        unchanged.push(dest);
+        return;
+      }
+    } catch (e) {
+      problems.push(`读取已有工具文件失败 ${dest}：${e.message}`);
+      return;
+    }
+  }
+  atomicWriteFile(dest, content, { mode: 0o444 });
+  written.push(dest);
+}
+
+/**
+ * 把 fancy-topic 工具部署到 `<projectRoot>/.fancy-tools/fancy-topic/`。
+ *
+ * @param {string} projectRoot 工作区目录（绝对路径）
+ * @returns {{ok:boolean,problems:string[],dir:string,saveScript:string,written:string[],unchanged:string[]}}
+ */
+export function deployTopicTools(projectRoot) {
+  const problems = [];
+  const written = [];
+  const unchanged = [];
+  let root = '';
+
+  try {
+    if (!projectRoot || typeof projectRoot !== 'string') {
+      return { ok: false, problems: ['缺少工作区目录'], dir: '', saveScript: '', written, unchanged };
+    }
+    if (!isAbsolute(projectRoot)) {
+      return { ok: false, problems: [`工作区目录必须是绝对路径：${projectRoot}`], dir: '', saveScript: '', written, unchanged };
+    }
+    root = resolve(projectRoot);
+    if (isSensitiveProjectPath(root) || !isValidProjectPath(root)) {
+      return { ok: false, problems: [`工作区目录路径不合法或属于受保护目录：${root}`], dir: '', saveScript: '', written, unchanged };
+    }
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+      return { ok: false, problems: [`工作区目录不存在或不是目录：${root}`], dir: '', saveScript: '', written, unchanged };
+    }
+    root = realpathSync(root);
+  } catch (e) {
+    return { ok: false, problems: [`检查工作区目录失败：${e.message}`], dir: '', saveScript: '', written, unchanged };
+  }
+
+  const toolsDir = join(root, '.fancy-tools');
+  const topicDir = join(toolsDir, 'fancy-topic');
+  const libDir = join(topicDir, 'lib');
+  const scriptsDir = join(topicDir, 'scripts');
+
+  for (const dir of [toolsDir, topicDir, libDir, scriptsDir]) {
+    if (!ensureRealDir(dir, problems)) {
+      return { ok: false, problems, dir: topicDir, saveScript: join(scriptsDir, 'save-suggestion.js'), written, unchanged };
+    }
+  }
+
+  // package.json 先写：避免“脚本在、包配置不在”的半成品。
+  const pkgPath = join(topicDir, 'package.json');
+  const pkgContent = JSON.stringify(TOPIC_PACKAGE_JSON, null, 2) + '\n';
+  try {
+    writeIfChanged(pkgPath, pkgContent, problems, written, unchanged);
+  } catch (e) {
+    problems.push(`写 package.json 失败：${e.message}`);
+  }
+
+  for (const item of TOPIC_FILES) {
+    const srcPath = join(PACKAGE_ROOT, item.src);
+    const destPath = join(topicDir, item.dest);
+    try {
+      if (!existsSync(srcPath)) {
+        problems.push(`插件内缺少工具源文件：${item.src}`);
+        continue;
+      }
+      const content = readFileSync(srcPath, 'utf-8');
+      writeIfChanged(destPath, content, problems, written, unchanged);
+      const back = readFileSync(destPath, 'utf-8');
+      if (back !== content) problems.push(`部署后回读不一致：${item.dest}`);
+    } catch (e) {
+      problems.push(`部署 ${item.dest} 失败：${e.message}`);
+    }
+  }
+
+  const saveScript = join(scriptsDir, 'save-suggestion.js');
+  try {
+    const st = lstatSync(saveScript);
+    if (st.isSymbolicLink() || !st.isFile()) {
+      problems.push(`部署后的 save-suggestion.js 不是普通文件：${saveScript}`);
+    }
+  } catch (e) {
+    problems.push(`部署后未找到 save-suggestion.js：${e.message}`);
+  }
+
+  return { ok: problems.length === 0, problems, dir: topicDir, saveScript, written, unchanged };
+}