@cloud411716/fancy-webnovel 1.0.45 → 2.2.0

package/plugins/fancy-import/import-driver.js

@@ -0,0 +1,581 @@
+/**
+ * import-driver.js —— 导入阶段：插件驱动、逐轮反推
+ *
+ * 和写作阶段同一套骨架：**插件当司机，LLM 只按指令写文件；脚本当裁判。**
+ *
+ * 导入和正向四阶段的差别在因果方向：
+ *   正向：先定 quota → 照配额造实体 → 排章节 → 写正文
+ *   反向：旧稿已经在那里 → 反推出实体 → **反推出 quota** → 报告还缺什么
+ *
+ * 所以配额这一环必须由脚本算，不能让模型填：
+ * 模型的"估计"和校验器的口径对不上，导入完就会校验失败。
+ *
+ * 本模块不直接依赖 dsh 运行时：sendPrompt / waitIdle / validateFile 都由
+ * 调用方注入，因此可以在没有 LLM 的情况下用测试夹具驱动。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { makeWaitForTurn } from '#story-builder/writing-driver.js';
+import { countChapterChars } from '#story-builder/scripts/content-quality.js';
+import { chapterFileName } from './import-core.js';
+
+/** 单轮最大尝试次数（含首次） */
+export const IMPORT_MAX_ATTEMPTS = 3;
+
+/** 注入正文的材料上限（每章取前 N 字，避免上下文爆掉） */
+export const IMPORT_EXCERPT_CHARS = 800;
+
+/**
+ * 导入要反推的六轮产物。
+ *
+ * 2026-10-27 修正：注释和报告文案一直写"四轮"，实际是六轮
+ * （input / entities / relations / flesh / rhythm / ledger）——
+ * 用户照着报告数轮次对不上，以为自己漏了流程。
+ *
+ * 文件名与模板名**必须和 story-builder 的校验器一致** ——
+ * 校验器是按固定文件名找产物的，名字对不上就是"文件不存在"。
+ */
+export const IMPORT_ROUNDS = [
+  {
+    // 输入快照必须**先**出来：书名 / 题材 / 核心冲突 / 硬约束
+    // 脚本算不出来（那是书的"自我认知"，只能从旧稿里读），
+    // 而框架.json 的 input_snapshot 是必填项，空值会被 REQUIRED 拦下。
+    id: 'input',
+    stage: '输入快照',
+    dir: '导入资料',
+    files: [
+      { name: '输入快照.json', tpl: null, type: '输入快照' }
+    ],
+    validator: null,
+    templateDir: null
+  },
+  {
+    // 实体先写：配额是**从实体条数反推**出来的，
+    // 所以必须先有实体，脚本才能算出配额。
+    id: 'entities',
+    stage: '骨架·实体',
+    dir: '骨架',
+    files: [
+      { name: '实体.json', tpl: '实体模板.json', type: '实体' }
+    ],
+    validator: 'skeleton-validate.js',
+    templateDir: '骨架'
+  },
+  {
+    // 关系与层级要照着配额写（关系条数由配额决定），所以排在实体之后。
+    id: 'relations',
+    stage: '骨架·关系层级',
+    dir: '骨架',
+    files: [
+      { name: '关系.json', tpl: '关系模板.json', type: '关系' },
+      { name: '层级.json', tpl: '层级模板.json', type: '层级' }
+    ],
+    validator: 'skeleton-validate.js',
+    templateDir: '骨架'
+  },
+  {
+    id: 'flesh',
+    stage: '血肉',
+    dir: '血肉',
+    files: [
+      { name: '角色.json', tpl: '角色模板.json', type: '角色' },
+      { name: '冲突.json', tpl: '冲突模板.json', type: '冲突' },
+      { name: '势力.json', tpl: '势力模板.json', type: '势力' },
+      { name: '剧情.json', tpl: '剧情模板.json', type: '剧情' },
+      { name: '地点.json', tpl: '地点模板.json', type: '地点' },
+      { name: '结局.json', tpl: '结局模板.json', type: '结局' },
+      { name: '世界观规则.json', tpl: '世界观规则模板.json', type: '世界观规则' },
+      { name: '关键道具.json', tpl: '关键道具模板.json', type: '关键道具' }
+    ],
+    validator: 'flesh-validate.js',
+    templateDir: '血肉'
+  },
+  {
+    id: 'rhythm',
+    stage: '节奏',
+    dir: '节奏',
+    files: [
+      { name: '章节规划.json', tpl: '章节规划模板.json', type: '章节规划' },
+      { name: '时序映射.json', tpl: '时序映射模板.json', type: '时序映射' },
+      { name: '节奏参数.json', tpl: '节奏参数模板.json', type: '节奏参数' },
+      { name: '章节细纲.json', tpl: '章节细纲模板.json', type: '章节细纲' }
+    ],
+    validator: 'rhythm-validate.js',
+    templateDir: '节奏'
+  },
+  {
+    id: 'ledger',
+    stage: '台账',
+    dir: '写作/台账',
+    files: [
+      { name: '章台账.json', tpl: null, type: '章台账' },
+      { name: '人物台账.json', tpl: null, type: '人物台账' },
+      { name: '伏笔台账.json', tpl: null, type: '伏笔台账' },
+      { name: '时间线台账.json', tpl: null, type: '时间线台账' }
+    ],
+    validator: null,
+    templateDir: null
+  }
+];
+
+/**
+ * 导入阶段的目录布局。
+ * @param {string} projectRoot
+ */
+export function importDirs(projectRoot) {
+  const src = path.join(projectRoot, '设定', 'raw', 'sources');
+  return {
+    sources: src,
+    writing: path.join(src, '写作'),
+    ledger: path.join(src, '写作', '台账'),
+    skeleton: path.join(src, '骨架'),
+    flesh: path.join(src, '血肉'),
+    rhythm: path.join(src, '节奏'),
+    material: path.join(src, '导入资料'),
+    reports: path.join(projectRoot, '导入报告')
+  };
+}
+
+/**
+ * 挑出要注入提示词的正文摘要。
+ *
+ * 不把全文塞进提示词：T=800 的旧稿全文进上下文会直接爆掉。
+ * 每章取开头一段，够模型认出这是哪一章、什么语气、谁在说话。
+ *
+ * @param {Array<{ch:number,title:string,body:string}>} chapters
+ * @param {number} [maxChapters]
+ * @param {number} [charsPerChapter]
+ * @returns {Array<{ch:number,title:string,excerpt:string}>}
+ */
+export function pickExcerpts(chapters, maxChapters = 12, charsPerChapter = IMPORT_EXCERPT_CHARS) {
+  const out = [];
+  const list = chapters || [];
+  // 均匀取样：开头几章 + 结尾几章 + 中间均匀分布
+  let picks = [];
+  if (list.length <= maxChapters) {
+    picks = list.map((c) => c.ch);
+  } else {
+    const step = (list.length - 1) / (maxChapters - 1);
+    for (let i = 0; i < maxChapters; i++) {
+      picks.push(list[Math.round(i * step)].ch);
+    }
+    picks = Array.from(new Set(picks));
+  }
+  const byCh = new Map(list.map((c) => [c.ch, c]));
+  for (const ch of picks) {
+    const c = byCh.get(ch);
+    if (!c) continue;
+    out.push({
+      ch: c.ch,
+      title: c.title,
+      excerpt: String(c.body || '').slice(0, charsPerChapter)
+    });
+  }
+  return out;
+}
+
+/**
+ * 把配额对象摊成「字段 → 数量」的列表（给提示词渲染表格用）。
+ *
+ * @param {Object} quota
+ * @returns {Array<[string, number]>}
+ */
+export function flattenQuota(quota) {
+  const out = [];
+  const walk = (node, prefix) => {
+    if (!node || typeof node !== 'object') return;
+    for (const k of Object.keys(node)) {
+      const v = node[k];
+      const path = prefix ? prefix + '.' + k : k;
+      if (typeof v === 'number') out.push([path, v]);
+      else if (v && typeof v === 'object') walk(v, path);
+    }
+  };
+  walk(quota, '');
+  return out;
+}
+
+/**
+ * 构建一轮的派活提示词。
+ *
+ * @param {Object} o
+ * @param {Object} o.round IMPORT_ROUNDS 的一项
+ * @param {number} o.attempt 第几次尝试
+ * @param {Array} o.errors 上一轮的校验错误
+ * @param {Object} o.context { chapterCount, settingCount, excerpts, dirs }
+ * @param {string} [o.contract] 导入执行须知
+ * @returns {string}
+ */
+export function buildRoundPrompt(o) {
+  const round = o.round;
+  const ctx = o.context || {};
+  const parts = [];
+
+  if (o.contract) {
+    parts.push(o.contract.trim());
+    parts.push('');
+    parts.push('---');
+    parts.push('');
+  }
+
+  parts.push('# 本轮派活：反推' + round.stage + '（第 ' + (o.attempt || 1) + ' 次尝试）');
+  parts.push('');
+
+  parts.push('## 旧稿在哪');
+  parts.push('');
+  parts.push('- 正文：`设定/raw/sources/写作/`（第001章.md ~ 第' +
+    String(ctx.chapterCount || 0).padStart(3, '0') + '章.md，共 ' + (ctx.chapterCount || 0) + ' 章）');
+  if (ctx.settingCount) {
+    parts.push('- 设定资料：`设定/raw/sources/导入资料/`（' + ctx.settingCount + ' 个文件）');
+  } else {
+    parts.push('- 设定资料：没有（旧稿只有正文）');
+  }
+  parts.push('- **先读这些文件再动笔**，不要凭想象填。');
+  parts.push('');
+
+  if (ctx.excerpts && ctx.excerpts.length) {
+    parts.push('## 正文开头节选（只做定位用，全文在上面的目录里）');
+    parts.push('');
+    for (const e of ctx.excerpts) {
+      parts.push('### 第 ' + e.ch + ' 章 ' + e.title);
+      parts.push('');
+      parts.push('```');
+      parts.push(e.excerpt);
+      parts.push('```');
+      parts.push('');
+    }
+  }
+
+  if (ctx.quota) {
+    parts.push('## 配额（框架.json 由插件生成，照这个写）');
+    parts.push('');
+    parts.push('| 字段 | 数量 |');
+    parts.push('|---|---|');
+    for (const line of flattenQuota(ctx.quota)) {
+      parts.push('| ' + line[0] + ' | ' + line[1] + ' |');
+    }
+    parts.push('');
+    parts.push('**实体条数必须与配额完全一致**（多一个少一个都会报 `QUOTA_MISMATCH`）；' +
+      '关系条数按配额里对应的行数写。');
+    parts.push('');
+  }
+
+  parts.push('## 本轮要写的文件');
+  parts.push('');
+  for (const f of round.files) {
+    parts.push('- `设定/raw/sources/' + round.dir + '/' + f.name + '`');
+  }
+  parts.push('');
+  parts.push('**只写上面这几个文件。** 其余阶段的文件本轮不要动。');
+  parts.push('');
+
+  if (round.id === 'input') {
+    parts.push('## 输入快照的字段');
+    parts.push('');
+    parts.push('```json');
+    parts.push('{');
+    parts.push('  "book_name": "旧稿的书名（没有就用第一章标题）",');
+    parts.push('  "genre": "题材（如：都市复仇 / 玄幻修真）",');
+    parts.push('  "core_summary": "这本书讲什么（一两句，说清主角处境与主线）",');
+    parts.push('  "core_conflict": "核心冲突是什么（谁和谁，为了什么，对抗什么）",');
+    parts.push('  "hard_constraints": ["旧稿里明确写死的设定（没有就写空数组）"],');
+    parts.push('  "anti_tropes": ["旧稿刻意避开的写法（没有就写空数组）"]');
+    parts.push('}');
+    parts.push('```');
+    parts.push('');
+    parts.push('**这 6 个字段都要有实际内容**：空值会被骨架校验器以 `REQUIRED` / ' +
+      '`TEXT_TOO_SHORT` / `TEXT_PLACEHOLDER` 拦下。');
+    parts.push('');
+  }
+
+  if (o.errors && o.errors.length) {
+    parts.push('## 上一轮的校验错误（必须改掉）');
+    parts.push('');
+    for (const e of o.errors) {
+      parts.push('- [' + e.code + '] ' + (e.path || '(无路径)') + '：' + e.message +
+        (e.hint ? '（' + e.hint + '）' : ''));
+    }
+    parts.push('');
+    parts.push('**只改错误指向的字段**，其余部分不要动。');
+    parts.push('');
+  }
+
+  parts.push('## 交活');
+  parts.push('');
+  parts.push('写完给一段话汇报：本轮写了哪些文件、各写了多少条、哪些内容旧稿里没有（已留空）。');
+  parts.push('');
+
+  return parts.join('\n');
+}
+
+/**
+ * 判断一个产物文件是不是"至少存在且是合法 JSON"。
+ * 台账那轮没有模板可校验，用这条底线兜住。
+ *
+ * @param {string} p
+ * @returns {{ok:boolean, error:string|null}}
+ */
+export function checkJsonFile(p) {
+  if (!fs.existsSync(p)) return { ok: false, error: '文件没有生成：' + p };
+  try {
+    JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return { ok: true, error: null };
+  } catch (e) {
+    return { ok: false, error: '不是合法 JSON：' + p + '（' + e.message + '）' };
+  }
+}
+
+/**
+ * 逐轮驱动导入。
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {Array} [opts.rounds]
+ * @param {string} [opts.contract]
+ * @param {(prompt:string) => Promise<{ok:boolean, error?:string}>} opts.sendPrompt
+ * @param {(files:string[]) => Promise<{ok:boolean, reason?:string, code?:string}>} opts.waitIdle
+ * @param {(file:string, round:Object) => Promise<{ok:boolean, errors?:Array}>} opts.validateFile
+ * @param {(msg:string) => void} [opts.onProgress]
+ * @param {(round:Object) => void} [opts.onRound] 一轮结束时的回调（用于生成配额）
+ * @param {number} [opts.maxAttempts]
+ * @returns {Promise<Object>} 汇总报告
+ */
+export async function runImportStage(opts) {
+  const dirs = opts.dirs || importDirs(opts.projectRoot);
+  const rounds = opts.rounds || IMPORT_ROUNDS;
+  const maxAttempts = opts.maxAttempts || IMPORT_MAX_ATTEMPTS;
+
+  const report = {
+    ok: true,
+    error: null,
+    rounds: [],
+    failed: [],
+    chapters: 0,
+    settings: 0,
+    totalWords: 0
+  };
+
+  /** 环境类失败（投递失败/超时/被中断/没有 agent）→ 整条轮次链停掉 */
+  let stopAll = false;
+
+  for (const round of rounds) {
+    const targetDir = path.join(dirs.sources, round.dir);
+    const expected = round.files.map((f) => path.join(targetDir, f.name));
+
+    let attempt = 1;
+    let errors = [];
+    let lastError = null;
+
+    while (attempt <= maxAttempts) {
+      const prompt = buildRoundPrompt({
+        round,
+        attempt,
+        errors,
+        contract: opts.contract,
+        context: opts.context || {}
+      });
+
+      const sent = await opts.sendPrompt(prompt);
+      if (!sent || sent.ok !== true) {
+        lastError = (sent && sent.error) || '提示词投递失败';
+        report.ok = false;
+        report.error = lastError;
+        // 投递失败是**环境问题**（会话没了/插件不可用），不是这一轮的内容问题，
+        // 继续发下一轮只会继续失败，还会往会话里塞更多发不出去的话。
+        stopAll = true;
+        break;
+      }
+
+      const waited = await opts.waitIdle(expected);
+      if (!waited || waited.ok !== true) {
+        lastError = (waited && waited.reason) || '等待 LLM 失败';
+        errors = [{ code: 'NO_OUTPUT', path: round.dir, message: lastError, hint: null }];
+        // 等待失败**也是失败** —— 旧实现这里既不置 report.ok=false，
+        // 也不阻止后面的轮次继续跑，于是"一轮都没等回来"也能报"导入完成"。
+        report.ok = false;
+        if (!report.error) report.error = lastError;
+        // 环境类失败重试没有意义
+        const code = (waited && waited.code) || '';
+        if (code === 'TIMEOUT' || code === 'ABORTED' || code === 'NO_AGENT') {
+          // 而且**不能继续发下一轮**：
+          //   ABORTED = 用户点了停止，继续塞提示词就是在用户喊停后继续消耗额度；
+          //   TIMEOUT = 上一轮可能还在跑，下一轮会和它叠在一起；
+          //   NO_AGENT = 根本没有 agent 在听。
+          // 旧实现的 break 只跳出内层 while，外层 for 照跑不误。
+          stopAll = true;
+          break;
+        }
+        attempt++;
+        continue;
+      }
+
+      // 逐文件校验
+      errors = [];
+      for (let i = 0; i < round.files.length; i++) {
+        const f = round.files[i];
+        const p = expected[i];
+        if (!opts.validateFile) {
+          const chk = checkJsonFile(p);
+          if (!chk.ok) errors.push({ code: 'READ', path: p, message: chk.error, hint: null });
+          continue;
+        }
+        const r = await opts.validateFile(p, round, f);
+        if (!r || !r.ok) {
+          for (const e of (r && r.errors) || [{ code: 'VALIDATE', path: p, message: '校验失败', hint: null }]) {
+            errors.push(e);
+          }
+        }
+      }
+
+      if (errors.length === 0) {
+        if (opts.onProgress) opts.onProgress(round.stage + ' 反推完成（' + round.files.length + ' 个文件）。');
+        break;
+      }
+      if (attempt >= maxAttempts) {
+        lastError = '校验未通过（' + errors.length + ' 个错误）';
+        break;
+      }
+      attempt++;
+    }
+
+    const r = {
+      id: round.id,
+      stage: round.stage,
+      files: round.files.map((f) => f.name),
+      ok: errors.length === 0 && !lastError,
+      errors,
+      error: lastError,
+      attempts: attempt
+    };
+    report.rounds.push(r);
+    if (!r.ok) {
+      report.failed.push(round.stage);
+      // 某一轮没过，整体就不算成功 —— report.ok 的语义是"这次导入成了吗"
+      report.ok = false;
+      if (opts.onProgress) opts.onProgress(round.stage + ' 反推未通过：' + (lastError || errors.length + ' 个错误'));
+    }
+    if (opts.onRound) opts.onRound(r);
+    if (stopAll) break;
+  }
+
+  return report;
+}
+
+/**
+ * 写导入报告（含待补清单）。
+ *
+ * 待补清单 = 校验没过的地方 + 反推不出来的地方。
+ * 导入的价值一半在"把旧稿变成结构化产物"，另一半在
+ * **明确告诉用户还差什么** —— 不说清楚，用户会以为导入完了。
+ *
+ * @param {Object} o
+ * @param {Object} o.scan scanSource() 的结果
+ * @param {Object} o.report runImportStage() 的结果
+ * @param {Array} [o.quotaDecisions] reverseQuota() 的决定
+ * @param {Array} [o.gaps] 额外列出的待补项
+ * @returns {string} markdown
+ */
+export function renderImportReport(o) {
+  const scan = o.scan || {};
+  const report = o.report || {};
+  const lines = [];
+
+  lines.push('# 导入报告');
+  lines.push('');
+
+  lines.push('## 一、导入了什么');
+  lines.push('');
+  lines.push('- 来源：`' + (scan.root || '') + '`');
+  lines.push('- 正文：' + (scan.stats ? scan.stats.chapterCount : 0) + ' 章，' +
+    (scan.stats ? scan.stats.totalWords : 0) + ' 字（平均每章 ' +
+    (scan.stats ? scan.stats.avgWords : 0) + ' 字）');
+  lines.push('- 设定资料：' + (scan.stats ? scan.stats.settingCount : 0) + ' 个文件');
+  lines.push('');
+
+  if (scan.warnings && scan.warnings.length) {
+    lines.push('### 扫描阶段的提醒');
+    lines.push('');
+    for (const w of scan.warnings) lines.push('- ' + w);
+    lines.push('');
+  }
+
+  // 被覆盖的正文：导入会用原始旧稿盖掉已有章节（去味成果会丢），
+  // 必须列出来并给出备份位置 —— 不列出来用户不会意识到覆盖发生了。
+  if (o.overwritten && o.overwritten.length) {
+    lines.push('### 覆盖了已有正文');
+    lines.push('');
+    lines.push('导入用原始旧稿覆盖了 ' + o.overwritten.length + ' 个已有章节：' +
+      o.overwritten.join('、') + '。');
+    if (o.backupDir) {
+      lines.push('');
+      lines.push('覆盖前的原文已备份到：`' + o.backupDir + '`。');
+    }
+    lines.push('');
+  }
+
+  lines.push('## 二、各轮反推结果');
+  lines.push('');
+  lines.push('| 轮次 | 产物 | 结果 |');
+  lines.push('|---|---|---|');
+  for (const r of (report.rounds || [])) {
+    lines.push('| ' + r.stage + ' | ' + r.files.join('、') + ' | ' + (r.ok ? '通过' : '未通过') + ' |');
+  }
+  lines.push('');
+
+  lines.push('## 三、配额是怎么定出来的');
+  lines.push('');
+  lines.push('| 字段 | 值 | 依据 | 说明 |');
+  lines.push('|---|---|---|---|');
+  for (const d of (o.quotaDecisions || [])) {
+    const sourceText = { actual: '旧稿实际规模', formula: '按公式补齐', fallback: '兜底' }[d.source] || d.source;
+    lines.push('| ' + d.field + ' | ' + d.value + ' | ' + sourceText + ' | ' + d.note + ' |');
+  }
+  lines.push('');
+
+  lines.push('## 四、待补清单');
+  lines.push('');
+  const gaps = [];
+  for (const r of (report.rounds || [])) {
+    if (r.ok) continue;
+    gaps.push('### ' + r.stage + '（' + r.errors.length + ' 个错误）');
+    for (const e of r.errors) {
+      gaps.push('- [' + e.code + '] ' + (e.path || '(无路径)') + '：' + e.message +
+        (e.hint ? '（' + e.hint + '）' : ''));
+    }
+    gaps.push('');
+  }
+  for (const g of (o.gaps || [])) {
+    gaps.push('- ' + g);
+  }
+  if (!gaps.length) {
+    lines.push('- 无。六轮产物都通过了校验。');
+  } else {
+    lines.push(...gaps);
+  }
+  lines.push('');
+
+  lines.push('## 五、下一步');
+  lines.push('');
+  lines.push('1. 修掉上面的待补项（可以直接重新跑 `/fancy-import` 覆盖）。');
+  lines.push('2. 跑 `/fancy-story-builder writing` 让台账与章节对齐（导入只登记旧稿已有的事实）。');
+  lines.push('3. 跑 `/fancy-story-builder deslop` 去掉旧稿里的 AI 味。');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * 写导入报告到磁盘。
+ * @returns {string} 路径（失败返回空串）
+ */
+export function writeImportReport(dirs, content) {
+  try {
+    fs.mkdirSync(dirs.reports, { recursive: true });
+    const p = path.join(dirs.reports, '导入报告.md');
+    fs.writeFileSync(p, content, 'utf-8');
+    return p;
+  } catch {
+    return '';
+  }
+}