@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-topic/templates.js

@@ -0,0 +1,476 @@
+/**
+ * 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'  },
+  { label: '起点',  value: 'qidian'  },
+  { label: '晋江',  value: 'jinjiang' },
+  { label: '七猫',  value: 'qimao'   },
+];
+
+/**
+ * 数据里如果自带 `<<<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 两个合法字段，
+// selected 回传的是 label —— 此前这里用 value:'__rescan__' 判断，
+// 而 value 根本不会被 DSH 回传，导致"重新扫榜"分支永远不可达。
+const RESCAN_LABEL = '取消（重新扫榜）';
+
+/**
+ * 剥离 value，转换成 DSH 合法的 AskUserQuestionOption。
+ *
+ * DSH 的 AskUserQuestionOption 只有 label / description；
+ * value 属于契约外字段，传了会被运行时静默忽略。
+ * 上面的 value 仅供插件内部做 label↔value 映射（platformCn/platformToValue）。
+ *
+ * description 是可选字段：**没有就整个键省掉**，不能写成 undefined ——
+ * DSH 的 api gateway 在远程模式下要求提问请求是"lossless JSON"，
+ * 属性值不允许是 undefined（JSON.stringify 会悄悄丢掉它，但网关按属性
+ * 存在性判定），带上就会让整个请求被拒：
+ *   "api gateway: Remote event request is not lossless JSON data"
+ */
+function toAskOptions(options) {
+  return options.map(o => {
+    const opt = { label: o.label };
+    if (o.description !== undefined) opt.description = o.description;
+    return opt;
+  });
+}
+
+/**
+ * 选题字段定义（路径 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 个”。
+ */
+
+export const topic = {
+  PLATFORM_OPTIONS,
+  GENRE_OPTIONS,
+  TOPIC_FIELDS,
+  RESCAN_LABEL,
+
+  /**
+   * 路径 A：选平台弹框
+   */
+  askPlatform() {
+    return {
+      id: 'topic-platform',
+      question: '📚 请选择小说计划发布到哪个平台：',
+      options: toAskOptions(PLATFORM_OPTIONS),
+    };
+  },
+
+  /**
+   * 路径 A：选 topic_decision 文件
+   * @param {string[]} decisionFiles - 所有可用的 topic_decision_<date>.md 文件名（不含路径）
+   */
+  askDecisionFile(decisionFiles) {
+    return {
+      id: 'topic-decision',
+      question: '📊 请选择参考的扫榜分析文件：',
+      options: [
+        ...decisionFiles.map(f => ({ label: f })),
+        { label: RESCAN_LABEL },
+      ],
+    };
+  },
+
+  /**
+   * 路径 B：选题字段弹框
+   *
+   * 问题对象只允许 DSH 的合法字段：id / question / detail / header /
+   * options / multiSelect / intent。
+   *
+   * placeholder / default / question 上的 description 都**不是** DSH 的字段，
+   * 传了会被运行时静默忽略（与 options.value 同类问题）—— 所以：
+   *   - placeholder 里的示例、description 里的字段说明，都写进**标题行**
+   *     （question 的第一行），归到标题的括号里；
+   *   - "📌 当前值"和"💡 推荐值"写进 **detail**（不是 question）：
+   *     question 在 web 端被渲染成 <h2>，那条 CSS 没有 white-space: pre-wrap，
+   *     换行会被折成空格，标题和两个值会挤在同一行；detail 才是两端
+   *     都独立成块、都能换行的字段（web 走 markdown 硬换行，TUI 逐行渲染）；
+   *   - default 字段直接删掉：DSH 没有"预填输入框"的能力，
+   *     上次的值通过 detail 里的 "📌 当前值" 展示，能力不丢。
+   *
+   * @param {object} [opts]
+   * @param {object} [opts.currentValues] - _novel_topic.json 中的值（已按平台过滤）
+   * @param {object} [opts.suggestionValues] - _novel_topic_suggestion.json 中的值（已按平台过滤）
+   */
+  askFields(opts = {}) {
+    const { currentValues = {}, suggestionValues = null } = opts;
+    return TOPIC_FIELDS.map(f => {
+      const curVal = currentValues[f.id];
+      const sugVal = suggestionValues ? suggestionValues[f.id] : undefined;
+
+      // null / undefined / '' / 空数组 / 数字 0 → 视为无值
+      // （target_words / target_chapters = 0 是骨架模板的默认值，无意义）
+      const hasValue = (v) =>
+        v !== undefined && v !== null && v !== '' &&
+        !(Array.isArray(v) && v.length === 0) &&
+        !(typeof v === 'number' && v === 0);
+
+      const fmt = (v) => (Array.isArray(v) ? v.join('、') : String(v));
+      const curStr = hasValue(curVal) ? fmt(curVal) : '';
+      const sugStr = hasValue(sugVal) ? fmt(sugVal) : '';
+
+      // 标题 = 字段名 + （必填，示例 / 说明）
+      // 示例（placeholder）与说明（description）都归到括号里。
+      const titleBits = [];
+      if (f.required) titleBits.push('必填');
+      if (f.placeholder) titleBits.push(f.placeholder);
+      if (f.description) titleBits.push(f.description);
+      const title = titleBits.length ? `（${titleBits.join('，')}）` : '';
+      const titleLine = `📝 ${f.label}${title}：`;
+
+      // 当前值 / 推荐值放 **detail**，不放 question。
+      //
+      // 为什么不能放 question：两端渲染方式不一样。
+      //   web 端把 question 渲染成 <h2 class="title">，那条 CSS 没有
+      //     white-space: pre-wrap —— HTML 默认会把 \n 折成空格，于是
+      //     "标题 + 当前值 + 推荐值"挤在同一行（用户实测过）。
+      //   TUI 端是 <Text>{question.question}</Text>，\n 会换行。
+      // 同一份内容两端表现不一致，必须改用两端都支持的 detail。
+      //
+      // detail 是独立的块，两端都是：
+      //   web 端 → 标题下方的 <div class="detail">（走 MarkdownText）
+      //   TUI 端 → detail.split('\n') 逐行渲染（dim 文本）
+      //
+      // 但 web 端的 detail 走 markdown：**单个 \n 是"软换行"**，mdast 会把它
+      // 留在 text 节点里，HTML 照样折成空格 —— 还是一行。
+      // 必须用**硬换行**（行尾两个空格）：mdast 产出 break 节点，
+      // DSH 的 MarkdownText 把 break 渲染成 <br>，这才是真换行。
+      // （依据：dsh-web-frontend 的 markdown 渲染器里有
+      //   case "break": <><br/>{"\n"}</>
+      // 而 .markdown 容器没有 white-space: pre-wrap，软换行必被折叠。）
+      //
+      // 两个空格写在字符串字面量里（'  \n'），源码中没有行尾空白，
+      // 不会被格式化工具或编辑器悄悄吃掉。
+      const hints = [];
+      // 字段已经拆成 11 个平级项，单个字段的值是短文本/单段说明，
+      // 直接和“当前值 / 推荐值”放同一行即可；两项之间仍用硬换行分隔。
+      if (curStr) hints.push(`📌 当前值：${curStr}`);
+      if (sugStr) hints.push(`💡 推荐值：${sugStr}`);
+
+      const def = {
+        id: f.id,
+        question: titleLine,
+      };
+      // 没有当前值/推荐值时**不要**给 detail 赋值：DSH 端按
+      // `detail !== undefined` 判断要不要渲染这个块，给空串会渲染出一个
+      // 空 div（web 端还带 8px 下边距），TUI 端会渲染一行空的 dim 文本。
+      if (hints.length) def.detail = hints.join('  \n');
+      if (f.options) def.options = toAskOptions(f.options);
+      // multiSelect 必须在问题对象上声明：DSH 的 UI 靠它决定渲染 checkbox
+      // 还是 radio（dsh-client-ui-user-questions/lib/client.js：
+      // question.multiSelect === true ? "checkbox" : "radio"）。
+      // 不设就是单选，会与标题里"可多选"的说明自相矛盾。
+      if (f.kind === 'multiselect') def.multiSelect = true;
+      return def;
+    });
+  },
+
+  /**
+   * 路径 A 的 LLM 提示词
+   * @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, 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} 块）：`);
+        s.blocks.forEach((b, i) => {
+          const titles = summarizeBlockHeaders(b.headers);
+          sourceLines.push(`      ${i + 1}. ${escapeScanSentinels(titles.join(' / ') || '（无标题）')}`);
+        });
+      }
+      sourceLines.push(`本次只使用「${platform}」的 ${blockCount} 块。`);
+    }
+    if (notes.length) {
+      sourceLines.push('');
+      sourceLines.push('解析说明：');
+      for (const n of notes) sourceLines.push(`  - ${escapeScanSentinels(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, 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 '🚫 操作已取消。';
+
+      case 'no_provider':
+        return '⚠️ 当前运行环境不支持交互式提问。请在 dsh-tui 中运行该命令，或确认 Web UI 已正确加载交互组件。';
+
+      case 'no_project_root':
+        return '❌ 无法确定工作区目录：' + (err || '会话未提供当前工作目录') + '。请在工作区目录下运行该命令。';
+
+      case 'ask_failed':
+        return '❌ 交互提问失败：' + (err || '未知错误');
+
+      case 'not_initialized':
+        return '⚠️ 当前目录不属于已初始化的 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。';
+
+      case 'phase_wrong':
+        return `⚠️ 当前工作区阶段为「${phase || '未知'}」，不能运行 /fancy-topic。请先运行 /fancy-scan 完成扫榜。`;
+
+      case 'phase_unreadable':
+        return (
+          `❌ 无法读取状态文件 .fancy-deployed（${err || '内容异常'}），因此无法确定当前工作区阶段。\n` +
+          '请检查该文件是否被手动修改或损坏；如无法修复，请重新运行 /fancy-bootstrap 初始化工作区。'
+        );
+
+      case 'no_decision_file':
+        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 触发分析。'
+        );
+
+      case 'empty_decision_file':
+        return (
+          `❌ ${decisionFile || '所选文件'} 为空，未包含任何分析内容。\n` +
+          '空文件无法用于选题。请重新运行 /fancy-scan，等待 LLM 写入报告正文。'
+        );
+
+      case 'platform_not_in_decision':
+        return (
+          `⚠️ 在 ${decisionFile || '所选文件'} 中未找到「${platform || ''}」的内容块。\n` +
+          `文件中已有的内容块：\n${(available && available.length) ? available.map((b, i) => `${i + 1}. ${b}`).join('\n') : '（无）'}\n` +
+          '请确认是否已采集该平台。'
+        );
+
+      case 'invalid_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` +
+          `📚 平台：${platform || ''}\n` +
+          `📁 参考：${decisionFile || ''}` +
+          noteText + '\n' +
+          `💡 LLM 将在对话中给出 6 维评分与 ${TOPIC_FIELDS.length} 个字段建议。确认选题后，请运行 /fancy-topic setup 写入最终决定。`
+        );
+      }
+
+      case 'path_b_done':
+        return `✅ 选题已确认。
+下一步：运行 /fancy-build scale 构建故事（在此之前可选择运行 /fancy-analyze 拆解同题材爆款小说）。` +
+          (extra ? '\n\n' + extra : '');
+
+      case 'write_failed':
+        return '❌ 写入 _novel_topic.json 失败：' + (err || '未知错误');
+
+      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。';
+
+      case 'create_skeleton':
+        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 };
+}