@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

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

@@ -0,0 +1,1118 @@
+/**
+ * import-core.js —— 导入阶段的确定性内核
+ *
+ * 导入的因果方向和 story-builder 正相反：
+ *   正向：先定 quota（框架.json）→ 照配额造实体 → 排章节 → 写正文
+ *   反向：旧稿已经在那里了 → 先量出旧稿的实际规模 → 再反推 quota
+ *
+ * 所以导入不能直接套用骨架校验器：
+ *   校验器问的是"实体条数符不符合 quota"；
+ *   导入问的是"旧稿的实际规模能不能落进 quota 的合法区间，
+ *   落不进去该取哪个值"。
+ *
+ * 这个模块只做确定性的事（扫描、切章、统计、反推配额），
+ * 不涉及模型。模型要做的"从旧稿读出实体/关系"由插件派活。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { cnToNumber } from '#chinese-num';
+import { countChapterChars } from '#story-builder/scripts/content-quality.js';
+import { QUOTA_MAP } from '#story-builder/scripts/skeleton-quota.js';
+import { formulaRange, defaultInRange } from '#story-builder/scripts/formula-engine.js';
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** 正文目录名（在这些目录下的文件一律当正文） */
+export const CHAPTER_DIR_HINTS = ['正文', '章节', '章节正文', 'chapter', 'chapters', 'manuscript'];
+
+/** 设定目录名（在这些目录下的文件一律当设定） */
+export const SETTING_DIR_HINTS = ['设定', '设定集', '背景设定', '背景', '资料', '素材', 'setting', 'settings'];
+
+/** 导入时要跳过的目录（项目自己的产物 / 工具目录） */
+export const SKIP_DIRS = [
+  '.git', 'node_modules', 'references', '模板', '审查报告', '对标', '.fancy',
+  '导入报告'
+];
+
+/**
+ * 插件自己的产物路径（相对导入根）。
+ *
+ * 扫描项目根时不能把上一轮导入的产物当"旧稿"再导一遍 ——
+ * 那会让章节数翻倍、内容自相矛盾。
+ *
+ * 这里按**路径**排除而不是按目录名排除：目录名 "设定" 是用户的旧稿里
+ * 非常常见的文件夹（设定资料就放在那儿），按名字排除会连用户的设定一起跳过。
+ * 只排除插件真正写东西的那条路径。
+ */
+export const OWN_OUTPUT_PATHS = ['设定/raw/sources'];
+
+/** 正文字体量与扩展名 */
+const TEXT_EXT = new Set(['.txt', '.md', '.markdown', '.text']);
+
+/** 单文件上限（16MB）：超了多半不是小说正文 */
+const MAX_FILE_BYTES = 16 * 1024 * 1024;
+
+// ============================================================
+// 切章
+// ============================================================
+
+/** 卷/部/篇标题行 */
+const VOLUME_RE = /^[ \t　]*第[ \t　]*([0-9]+|[〇零一二三四五六七八九十百千万两]+)[ \t　]*([卷部篇])[ \t　]*(.*)$/;
+
+/** 章/回/节标题行 */
+const CHAPTER_RE = /^[ \t　]*第[ \t　]*([0-9]+|[〇零一二三四五六七八九十百千万两]+)[ \t　]*([章回节])[ \t　]*(.*)$/;
+
+/**
+ * 文件名里的章号（不锚定行首行尾）。
+ *
+ * 不能用 CHAPTER_RE：它带 `(.*)$`，匹配的是**整行**，
+ * 于是 m[0] = "第003章_夜巡.txt"，截不出标题。
+ */
+const CHAPTER_FILE_RE = /第[ \t　]*([0-9]+|[〇零一二三四五六七八九十百千万两]+)[ \t　]*([章回节])/;
+
+/**
+ * 文件名/目录名里的卷号（同样不锚定，用于排序时的卷次分组）。
+ *
+ * 与 CHAPTER_FILE_RE 是两个正则而不是一个：章尾是 [章回节]、卷尾是 [卷部篇]，
+ * 互不重叠，"第一卷/第1章.txt" 这种命名才能同时解析出卷号和章号。
+ */
+const VOLUME_FILE_RE = /第[ \t　]*([0-9]+|[〇零一二三四五六七八九十百千万两]+)[ \t　]*([卷部篇])/;
+
+/**
+ * 判断一行是不是章节标题。
+ *
+ * 光看"第N章"开头不够：正文里"第一章里陆子仲去了园区。"这种句子
+ * 也会被当标题（尤其出现在行首时），切出来的章标题就成了半句话。
+ *
+ * 追加判据：**标题部分不以句末标点结尾**。
+ *   - "第一章 夜巡"      → 标题"夜巡"，无句末标点 → 是标题
+ *   - "第一章 夜巡（上）" → 标题以右括号结尾，也不是句末标点 → 是标题
+ *   - "第一章里陆子仲去了园区。" → 以句号结尾 → 是句子，不是标题
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function isChapterHeadingLine(line) {
+  const m = CHAPTER_RE.exec(String(line || ''));
+  if (!m) return false;
+  const rest = (m[3] || '').trim();
+  if (!rest) return true;
+  return !/[。！？，；、,.!?;：:]$/.test(rest);
+}
+
+/**
+ * 从一段文本里切出章节，**保留原标题**。
+ *
+ * 旧实现（fancy-import/references/run-import.py）用
+ * `第\s*([0-9]+|[一二三四五六七八九十]+)\s*章` 全局匹配，
+ * 两个问题：
+ *   1. 不要求在行首 —— 正文里"他翻到第三章"也会被当成章节边界；
+ *   2. 只取 `m.group(0)`（"第三章"三个字），**标题整个丢了**，
+ *      落盘成 `第001章_untitled.md`。
+ *
+ * @param {string} text
+ * @returns {{chapters:Array, volumes:Array}}
+ *   chapters[i] = { no, unit, title, heading, body, startLine, volume }
+ */
+export function splitChapters(text) {
+  const src = String(text || '');
+  const lines = src.split('\n');
+  const chapters = [];
+  const volumes = [];
+
+  let current = null;
+  let volume = null;
+
+  const flush = (endLine) => {
+    if (!current) return;
+    current.endLine = endLine;
+    current.body = current.bodyLines.join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+    delete current.bodyLines;
+    chapters.push(current);
+    // 必须置空：卷标题会 flush 掉当前章，之后的正文行不该再往旧章里塞
+    current = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    const vm = VOLUME_RE.exec(line);
+    if (vm) {
+      flush(i);
+      volume = {
+        no: cnToNumber(vm[1]),
+        unit: vm[2],
+        title: (vm[3] || '').trim(),
+        heading: line.trim(),
+        line: i + 1
+      };
+      volumes.push(volume);
+      continue;
+    }
+
+    if (isChapterHeadingLine(line)) {
+      const cm = CHAPTER_RE.exec(line);
+      flush(i);
+      const rest = (cm[3] || '').trim();
+      current = {
+        no: cnToNumber(cm[1]),
+        unit: cm[2],
+        // 标题为空时保留原始标题行（绝不退化成 "untitled" —— 那是旧实现的老毛病）
+        title: rest || line.trim(),
+        titleFromHeading: rest.length > 0,
+        heading: line.trim(),
+        startLine: i + 1,
+        volume,
+        bodyLines: []
+      };
+      continue;
+    }
+
+    if (current) current.bodyLines.push(line);
+  }
+  flush(lines.length);
+
+  return { chapters, volumes };
+}
+
+/**
+ * 从一个文件里取章节。
+ *
+ * 两种布局：
+ *   a) 一个大文件里含多章 → 按标题行切
+ *   b) 一个文件就是一章（文件名带"第N章"）→ 整篇算一章
+ *
+ * @param {string} fileName 文件名（含路径）
+ * @param {string} text 文件内容
+ * @returns {{chapters:Array, volumes:Array}}
+ */
+export function chaptersFromFile(fileName, text) {
+  const base = path.basename(fileName);
+  const m = CHAPTER_FILE_RE.exec(base);
+  const split = splitChapters(text);
+
+  if (m) {
+    // 文件名就标明了章号：整篇算一章，正文里的其它"第N章"不算边界
+    const first = split.chapters[0];
+    const rest = split.chapters.length > 1
+      ? '\n\n' + split.chapters.slice(1).map((c) => c.heading + '\n' + c.body).join('\n\n')
+      : '';
+    const no = cnToNumber(m[1]);
+    // 先剥扩展名，再剥前导分隔符 —— 顺序反了会把 "第1章.txt" 切成 "txt"
+    // （先去分隔符："." 被打掉 → ".txt" 变成 "txt" → 扩展名正则再也匹配不上）。
+    // 剥完扩展名还剩 "第1章" 时，章号后面没有标题 → 用正文里解析出的标题。
+    const stem = base.replace(/\.(txt|md|markdown|text)$/i, '');
+    const titleFromName = stem.slice(m.index + m[0].length)
+      .replace(/^[_\-.·、\s]+/, '');
+    return {
+      chapters: [{
+        no,
+        unit: m[2],
+        title: titleFromName || (first ? first.title : stem),
+        titleFromHeading: !!(first && first.titleFromHeading),
+        heading: first ? first.heading : base,
+        startLine: 1,
+        body: ((first ? first.body : text) + rest).trim(),
+        volume: null
+      }],
+      volumes: split.volumes
+    };
+  }
+
+  return split;
+}
+
+// ============================================================
+// 扫描
+// ============================================================
+
+function listFiles(root) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.includes(e.name)) continue;
+        // 插件自己的产物路径不扫（见 OWN_OUTPUT_PATHS 的说明）
+        const relDir = path.relative(root, full).split(path.sep).join('/');
+        if (OWN_OUTPUT_PATHS.some((p) => relDir === p || relDir.startsWith(p + '/'))) continue;
+        walk(full, depth + 1);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (!TEXT_EXT.has(path.extname(e.name).toLowerCase())) continue;
+      out.push(full);
+    }
+  };
+  walk(root, 0);
+  sortFiles(out, root);
+  return out;
+}
+
+/**
+ * 从文件路径里解析卷号（取路径中**最后一个**带卷号的目录名）。
+ *
+ * 多卷旧稿常按"第一卷/第1章.txt"这样分目录；卷号取目录名而不是文件名，
+ * 因为文件名里通常只有章号。
+ *
+ * @param {string} root 导入根目录
+ * @param {string} full 文件绝对路径
+ * @returns {number|null} 卷号，解析不出返回 null
+ */
+export function volumeNoFromPath(root, full) {
+  const rel = path.relative(root, full) || path.basename(full);
+  const segs = rel.split(/[\\/]+/);
+  const base = segs[segs.length - 1] || '';
+  let volume = null;
+  for (const s of segs.slice(0, -1)) {
+    const vm = VOLUME_FILE_RE.exec(s);
+    if (vm) volume = cnToNumber(vm[1]);
+  }
+  if (volume === null) {
+    const vm = VOLUME_FILE_RE.exec(base);
+    if (vm) volume = cnToNumber(vm[1]);
+  }
+  return volume;
+}
+
+/**
+ * 给文件列表排序 —— 导入的章序必须来自文件名，不能来自 readdir 的返回顺序。
+ *
+ * 为什么这是必须修的：readdirSync 的顺序是文件系统决定的（ext4 是 hash 序、
+ * NTFS 是名字序、APFS 又不一样），把 `第1章` 排到 `第10章` 前面是常事。
+ * 旧实现直接按遍历顺序 `seq += 1`，于是**正文被静默错位**：
+ * 标题是连续的（第1章…第5章），正文却是（第10章 → 第1章 → 第20章 → …）。
+ * 导入报告不报错，写作阶段按错序续写，前情/伏笔/时间线全部错位。
+ *
+ * 排序规则：
+ *   1. 能解析出章号的 → 按 (卷号, 章号) 升序
+ *      卷号取自路径里**最后一个**带卷号的目录名（"第一卷/第1章.txt" → 1），
+ *      没有卷目录时取 0；
+ *   2. 解析不出章号的 → 按相对路径自然序（`localeCompare(..., {numeric:true})`，
+ *      这样 "第2章" 排在 "第10章" 前面）；
+ *   3. 有章号的排在没章号的前面；
+ *   4. 最终以相对路径自然序兜底，保证排序是**稳定且确定**的。
+ *
+ * @param {string[]} files 绝对路径数组（原地排序）
+ * @param {string} root 导入根目录
+ * @returns {string[]} 同一个数组
+ */
+export function sortFiles(files, root) {
+  const key = (full) => {
+    const rel = path.relative(root, full) || path.basename(full);
+    const segs = rel.split(/[\\/]+/);
+    const base = segs[segs.length - 1] || '';
+    const volume = volumeNoFromPath(root, full);
+    const cm = CHAPTER_FILE_RE.exec(base);
+    const chapter = cm ? cnToNumber(cm[1]) : null;
+    return { rel, volume, chapter };
+  };
+
+  files.sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    const aHas = ka.chapter !== null;
+    const bHas = kb.chapter !== null;
+    if (aHas && bHas) {
+      const va = ka.volume === null ? 0 : ka.volume;
+      const vb = kb.volume === null ? 0 : kb.volume;
+      if (va !== vb) return va - vb;
+      if (ka.chapter !== kb.chapter) return ka.chapter - kb.chapter;
+    } else if (aHas !== bHas) {
+      return aHas ? -1 : 1;
+    }
+    return ka.rel.localeCompare(kb.rel, 'zh-Hans-CN', { numeric: true });
+  });
+  return files;
+}
+
+/**
+ * 把原始字节解码成文本：UTF-8 优先，失败按 GBK 解。
+ *
+ * 为什么必须做：Node 的 `readFileSync(p, 'utf-8')` 遇到非法字节**不抛错**，
+ * 而是把每个坏字节替换成 U+FFFD。GBK 旧稿于是变成一堆 "�"，
+ * 章标题匹配不到 → 文件被归类成"设定" → **静默导入 0 章**，
+ * 而 scanSource 只在"章节和设定都为空"时才报错，所以还报 ok:true。
+ * 早期中文 txt 大量是 GBK，这个坑命中面很大。
+ *
+ * 顺带处理 UTF-8 BOM：带 BOM 的文件，第一行是 "\uFEFF第一章 …"，
+ * 而 CHAPTER_RE 锚定行首（只允许空格/制表符/全角空格），
+ * BOM 会让**第一章的标题匹配不上**，切章从第二章开始。
+ *
+ * @param {Buffer|Uint8Array|string} raw 原始字节
+ * @returns {string}
+ */
+export function decodeText(raw) {
+  let bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw), 'utf-8');
+  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+    bytes = bytes.slice(3);
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    try {
+      return new TextDecoder('gbk').decode(bytes);
+    } catch {
+      // Node 没带 full-icu 时 gbk 解码器不可用 → 退回宽松的 UTF-8
+      // （会带 U+FFFD，但至少不会整体失败）
+      return bytes.toString('utf-8');
+    }
+  }
+}
+
+function readIfSmall(p) {
+  try {
+    const st = fs.statSync(p);
+    if (st.size > MAX_FILE_BYTES) return null;
+    return decodeText(fs.readFileSync(p));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 判断一个文件是正文还是设定。
+ *
+ * 判定顺序（先命中先定）：
+ *   1. 路径里有正文目录名 → 正文
+ *   2. 路径里有设定目录名 → 设定
+ *   3. 文件名带"第N章" → 正文
+ *   4. 内容里有合法章标题行 → 正文（单章文件、一个大 txt 都算）
+ *   5. 其余 → 设定
+ *
+ * 第 4 条为什么单独判：设定资料里常出现"第一章"这种引用
+ * （"第一章里陆子仲去了园区"），只在文中出现不足以说明这是正文；
+ * 但**开头就是**"第一章 xxx"的文件，就是一章正文。
+ *
+ * @param {string} filePath
+ * @param {string} relPath 相对 root 的路径
+ * @param {string} text
+ * @returns {'chapter'|'setting'}
+ */
+export function classifyFile(filePath, relPath, text) {
+  const segs = relPath.split(/[\\/]+/);
+  const dirs = segs.slice(0, -1);
+  const base = segs[segs.length - 1] || '';
+
+  for (const d of dirs) {
+    if (CHAPTER_DIR_HINTS.includes(d.toLowerCase())) return 'chapter';
+  }
+  for (const d of dirs) {
+    if (SETTING_DIR_HINTS.includes(d.toLowerCase())) return 'setting';
+  }
+  if (CHAPTER_RE.test(base)) return 'chapter';
+
+  const { chapters } = splitChapters(text);
+  return chapters.length >= 1 ? 'chapter' : 'setting';
+}
+
+/**
+ * 剔除"目录页"造成的空章，并合并完全重复的章节。
+ *
+ * ## 为什么必须有这一步
+ *
+ * 旧稿开头常有目录：
+ *
+ *     目录
+ *     第一章 开端      ← 被切成一个"章"，但后面没有正文
+ *     第二章 转折
+ *     第三章 终局
+ *     第一章 开端      ← 真正的正文在这里开始
+ *     正文一。
+ *
+ * `splitChapters()` 只按"行首第N章 + 标题不以句末标点结尾"判断，
+ * 所以目录里的每一行都成了一个**空章**。旧实现只是记一条 warning，
+ * 空章照样写盘，章节数直接翻倍：
+ *   - `scan.stats.chapterCount` 翻倍 → 反推出的 T、卷数、支线数、所有配额全被抬高；
+ *   - 写作阶段 `readWritingState()` 把这些空文件当成"已存在"直接跳过；
+ *   - 最终报"0 章"或一堆 EMPTY_BODY。
+ *
+ * ## 判定规则（刻意保守，宁可漏判也不误删正文）
+ *
+ * 只有同时满足三条的连续块才判为目录区：
+ *   1. 块长 ≥ 2（单个空章更可能是作者留白，不动它）；
+ *   2. 块内每一章的正文都是空的；
+ *   3. 块内**每一个**章号都出现在后面的章节里
+ *      （说明块里列的章确实都存在于正文中，是目录而不是正文）。
+ *
+ * 第 3 条用"全部出现"而不是"有交集"：交集会在"块内列了 1、2，
+ * 而正文里只有 2"这种形态下误删 —— 那种其实是第 1 章没正文，不是目录。
+ *
+ * 多卷小说每卷都从"第一章"重新编号，这种情况各卷的号会重复 ——
+ * 但**章号相同不等于重复**：正文内容不同的同号章节一律保留（那多半是多卷），
+ * 只合并"章号相同**且正文逐字相同**"的（那才是真重复）。
+ *
+ * @param {Array} chapters 章节数组（原地过滤）
+ * @param {string[]} warnings 告警收集器（原地追加）
+ * @returns {{kept:Array, droppedToc:number, merged:number}}
+ */
+export function stripTocChapters(chapters, warnings) {
+  const isEmpty = (c) => !String(c.body || '').trim();
+
+  // ---- 1. 找连续空章块 ----
+  const blocks = [];
+  let start = -1;
+  for (let i = 0; i <= chapters.length; i++) {
+    const empty = i < chapters.length && isEmpty(chapters[i]);
+    if (empty && start < 0) start = i;
+    if (!empty && start >= 0) {
+      blocks.push({ start, end: i - 1 });
+      start = -1;
+    }
+  }
+
+  const dropped = new Set();
+  let droppedToc = 0;
+  for (const b of blocks) {
+    if (b.end - b.start + 1 < 2) continue;
+    const blockNos = new Set();
+    for (let i = b.start; i <= b.end; i++) blockNos.add(chapters[i].no);
+    // 块内的章号是不是**全部**都在后面的章节里出现过？
+    const laterNos = new Set();
+    for (let i = b.end + 1; i < chapters.length; i++) laterNos.add(chapters[i].no);
+    let allLater = blockNos.size > 0;
+    for (const no of blockNos) {
+      if (!laterNos.has(no)) { allLater = false; break; }
+    }
+    if (!allLater) continue;
+    for (let i = b.start; i <= b.end; i++) dropped.add(i);
+    droppedToc += b.end - b.start + 1;
+    warnings.push(
+      '识别到目录页（' + (b.end - b.start + 1) + ' 行空章，章号与正文重复），已跳过'
+    );
+  }
+
+  // ---- 2. 合并"同号且正文逐字相同"的真重复 ----
+  const kept = [];
+  const seen = new Map(); // key = no + '\u0000' + body → 保留的那一条
+  let merged = 0;
+  for (let i = 0; i < chapters.length; i++) {
+    if (dropped.has(i)) continue;
+    const c = chapters[i];
+    const key = String(c.no) + '\u0000' + String(c.body || '');
+    if (seen.has(key)) {
+      merged += 1;
+      warnings.push('章号与正文都重复：' + c.no + '（' + (c.sourceRel || '') + '），已合并');
+      continue;
+    }
+    seen.set(key, c);
+    kept.push(c);
+  }
+
+  chapters.length = 0;
+  for (const c of kept) chapters.push(c);
+  return { kept, droppedToc, merged };
+}
+
+/**
+ * 扫描导入源（目录或单个文件）。
+ *
+ * @param {string} inputPath
+ * @returns {{
+ *   ok: boolean, error: string|null,
+ *   root: string,
+ *   chapters: Array<{ch:number,no:number,title:string,body:string,sourcePath:string,words:number}>,
+ *   settings: Array<{path:string,name:string,text:string,words:number}>,
+ *   volumes: Array,
+ *   stats: Object,
+ *   warnings: string[]
+ * }}
+ */
+export function scanSource(inputPath) {
+  const warnings = [];
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { ok: false, error: '没有指定导入路径', root: '', chapters: [], settings: [], volumes: [], stats: {}, warnings };
+  }
+  let st;
+  try {
+    st = fs.statSync(inputPath);
+  } catch {
+    return { ok: false, error: '导入路径不存在：' + inputPath, root: inputPath, chapters: [], settings: [], volumes: [], stats: {}, warnings };
+  }
+
+  const chapters = [];
+  const settings = [];
+  const volumes = [];
+  let seq = 0;
+
+  const takeChapters = (filePath, text) => {
+    const rel = path.relative(inputPath, filePath) || path.basename(filePath);
+    const { chapters: cs, volumes: vs } = chaptersFromFile(filePath, text);
+    for (const v of vs) volumes.push(Object.assign({}, v, { sourcePath: filePath }));
+    for (const c of cs) {
+      seq += 1;
+      // 卷信息必须带出来：排序要按卷分组、重复检测要区分"同号不同卷"
+      // （多卷小说每卷都从"第一章"重新编号，同号是正常的）、
+      // chaptersPerVolume 要按卷分桶。
+      // 卷号优先取正文里解析出的卷标题，其次取路径里的卷目录名
+      // （"第一卷/第1章.txt" 这种分卷目录，正文里根本没有卷标题行）。
+      const volNo = c.volume ? c.volume.no : volumeNoFromPath(inputPath, filePath);
+      const volume = c.volume || (volNo !== null && volNo !== undefined
+        ? { no: volNo, unit: '卷', title: '', heading: '第' + volNo + '卷' }
+        : null);
+      chapters.push({
+        ch: seq,
+        no: c.no,
+        unit: c.unit,
+        title: c.title,
+        body: c.body,
+        volume,
+        volumeNo: volNo,
+        sourcePath: filePath,
+        sourceRel: rel,
+        words: countChapterChars(c.body)
+      });
+    }
+  };
+
+  const takeSetting = (filePath, text) => {
+    const rel = path.relative(inputPath, filePath) || path.basename(filePath);
+    settings.push({
+      path: filePath,
+      relPath: rel,
+      // 用**相对路径**做落盘名，不用 basename ——
+      // 旧稿里"设定/人物.md"和"补充资料/人物.md"同名，
+      // 平铺到导入资料目录后后者把前者覆盖了，
+      // 模型反推时只看到一份，另一份的设定凭空消失。
+      // 相对路径保留了目录结构，也天然不会撞名。
+      name: rel.split(path.sep).join('/'),
+      text,
+      words: countChapterChars(text)
+    });
+  };
+
+  if (st.isFile()) {
+    const text = readIfSmall(inputPath);
+    if (text === null) {
+      return { ok: false, error: '文件读不出来或太大（上限 16MB）：' + inputPath, root: inputPath, chapters: [], settings: [], volumes: [], stats: {}, warnings };
+    }
+    const kind = classifyFile(inputPath, path.basename(inputPath), text);
+    if (kind === 'chapter') takeChapters(inputPath, text);
+    else takeSetting(inputPath, text);
+  } else if (st.isDirectory()) {
+    const files = listFiles(inputPath);
+    if (files.length === 0) {
+      return { ok: false, error: '目录里没有可导入的文本文件（支持 .txt / .md）：' + inputPath, root: inputPath, chapters: [], settings: [], volumes: [], stats: {}, warnings };
+    }
+    for (const f of files) {
+      const text = readIfSmall(f);
+      if (text === null) {
+        warnings.push('跳过（读不出或超过 16MB）：' + path.relative(inputPath, f));
+        continue;
+      }
+      const rel = path.relative(inputPath, f);
+      const kind = classifyFile(f, rel, text);
+      if (kind === 'chapter') takeChapters(f, text);
+      else takeSetting(f, text);
+    }
+  } else {
+    return { ok: false, error: '导入路径既不是文件也不是目录：' + inputPath, root: inputPath, chapters: [], settings: [], volumes: [], stats: {}, warnings };
+  }
+
+  // 目录页剔除 + 真重复合并（必须在统计章数之前 —— 否则配额全被抬高）
+  stripTocChapters(chapters, warnings);
+
+  if (chapters.length === 0 && settings.length === 0) {
+    return { ok: false, error: '没有找到任何可导入的内容：' + inputPath, root: inputPath, chapters: [], settings: [], volumes: [], stats: {}, warnings };
+  }
+
+  if (chapters.length === 0) {
+    // 扫到了设定资料但一章正文都没扫到 —— 旧实现这里照样 ok:true，
+    // 下游 target_chapters=0、avg_words_per_chapter=0，
+    // 骨架校验必失败，而导入可能仍报"✅ 导入完成：0 章"。
+    // 常见原因：编码不是 UTF-8/GBK、章标题格式认不出（"第一章"之外的分隔符）。
+    //
+    // 设定资料照样返回去：用户要靠它判断"到底是编码问题还是内容问题"。
+    return {
+      ok: false,
+      error: '检测到 0 章：扫到了 ' + settings.length + ' 份设定资料，但没有一章正文。' +
+        '请确认旧稿是不是 UTF-8 或 GBK 编码、章节标题是不是"第N章/回/节"这种写法。',
+      root: inputPath,
+      chapters: [],
+      settings,
+      volumes,
+      stats: { chapterCount: 0, settingCount: settings.length },
+      warnings
+    };
+  }
+
+  // 剔除后重新连续编号：写盘文件名（`第NNN章.md`）和标题（`# 第N章`）都用它。
+  // 下游写作校验器要求章号与文件序号严格对应（CHAPTER_TITLE 会核对），
+  // 所以这里**重编号**是有意为之，导入报告里也会写明"已按顺序重编号"。
+  for (let i = 0; i < chapters.length; i++) chapters[i].ch = i + 1;
+
+  const words = chapters.map((c) => c.words);
+  const totalWords = words.reduce((a, b) => a + b, 0);
+  const stats = {
+    chapterCount: chapters.length,
+    settingCount: settings.length,
+    totalWords,
+    avgWords: chapters.length ? Math.round(totalWords / chapters.length) : 0,
+    minWords: words.length ? Math.min(...words) : 0,
+    maxWords: words.length ? Math.max(...words) : 0,
+    volumeCount: volumes.length
+  };
+
+  // 章号不连续 / 重复 / 倒退：记录下来，导入时按顺序重编号。
+  //
+  // 按**卷**分组判断：多卷小说每卷都从"第一章"重新编号，
+  // 跨卷同号是正常的，不该报"章号重复"；同卷内同号才是真重复。
+  const seen = new Map();   // (卷号, 章号) → 已出现
+  const prevByVolume = new Map(); // 卷号 → 上一个章号
+  for (const c of chapters) {
+    if (c.no === null || c.no === undefined) continue;
+    const vk = String(c.volumeNo === null || c.volumeNo === undefined ? '' : c.volumeNo);
+    const sk = vk + '\u0000' + c.no;
+    if (seen.has(sk)) warnings.push('章号重复：' + c.no + '（' + c.sourceRel + '）');
+    seen.set(sk, true);
+    const prev = prevByVolume.get(vk);
+    if (prev !== undefined && c.no < prev) {
+      warnings.push('章号倒退：' + prev + ' → ' + c.no + '（' + c.sourceRel + '）');
+    }
+    prevByVolume.set(vk, c.no);
+  }
+
+  // 空章：目录页残留或切章失败。空章在写作阶段一律报 EMPTY_BODY，
+  // 与其让下游一地鸡毛，不如在这里明确说出来。
+  const empties = chapters.filter((c) => !String(c.body || '').trim());
+  if (empties.length) {
+    for (const c of empties) {
+      warnings.push('空章：第 ' + c.ch + ' 章（' + (c.sourceRel || '') + '）没有正文');
+    }
+    const ratio = chapters.length ? empties.length / chapters.length : 0;
+    // 阈值取"数量 > 3 且占比 > 1%"：单个空章更可能是作者留白，只告警；
+    // 大量空章几乎一定是目录页残留或切章失败，这时**拒绝导入**，
+    // 而不是让用户在写作阶段才发现。
+    if (empties.length > 3 && ratio > 0.01) {
+      return {
+        ok: false,
+        error: '疑似目录页残留或切章失败：' + empties.length + '/' + chapters.length +
+          ' 章没有正文（占比 ' + Math.round(ratio * 100) + '%）。' +
+          '请确认旧稿的章节标题格式，或先把目录页删掉再导入。',
+        root: inputPath,
+        chapters: [],
+        settings: [],
+        volumes,
+        stats,
+        warnings
+      };
+    }
+  }
+
+  return { ok: true, error: null, root: inputPath, chapters, settings, volumes, stats, warnings };
+}
+
+// ============================================================
+// quota 反推
+// ============================================================
+
+/**
+ * 按实体数组统计"实际规模"（与骨架校验器的配额口径一致）。
+ *
+ * 直接复用 skeleton-quota.js 的 QUOTA_MAP —— 那张表就是
+ * "quota 路径 ↔ 实体数组 + 过滤条件"的唯一真源，
+ * 这里再抄一份的话，实体类型枚举一改，两边就会对不上。
+ *
+ * 返回的键**不带 `quota.` 前缀**（与 QUOTA_MAP 的键一致）。
+ *
+ * @param {Object} entityData 实体.json 的内容
+ * @returns {Object} { 'character_counts.protagonist': 1, ... }
+ */
+export function actualCountsByQuota(entityData) {
+  const out = {};
+  if (!entityData || typeof entityData !== 'object') return out;
+  for (const quotaPath of Object.keys(QUOTA_MAP)) {
+    const spec = QUOTA_MAP[quotaPath];
+    const arr = entityData[spec.arr];
+    if (!Array.isArray(arr)) continue;
+    let n = 0;
+    for (const item of arr) {
+      if (!item) continue;
+      if (spec.filter(item)) n += 1;
+    }
+    out[quotaPath] = n;
+  }
+  return out;
+}
+
+/**
+ * 反推 quota。
+ *
+ * 规则（按顺序）：
+ *   1. **能反推就用实际值**（旧稿里真实有多少角色、多少势力…）——
+ *      导入的目标是复现旧稿，不是重造一本。
+ *   2. 实际值落在公式区间外 → **仍然用实际值**，但记一条"与公式冲突"。
+ *      不能改成区间内的值：quota 必须与实体条数一致
+ *      （骨架校验器按 QUOTA_MISMATCH 核对实体数组条数），
+ *      把 quota 改成公式区间里的数，只会让"实体条数 ≠ quota"换个地方爆。
+ *      区间不符在骨架校验里是 warning（QUANTITY_MISMATCH），会出现在导入报告里。
+ *   3. 反推不出来（该类实体旧稿里根本没有）→ 按公式取下界，
+ *      记一条"按公式补齐"的决定。
+ *
+ * 依赖顺序有讲究：volume_count → 主线/支线 → 主角/核心配角/核心反派 →
+ * 核心冲突 → 其余。公式里 V/P/CS/CA/BC/CC 互相引用，
+ * 顺序错了区间会算错。
+ *
+ * @param {Object} o
+ * @param {number} o.targetChapters 旧稿实际章数
+ * @param {number} [o.volumeCount] 旧稿实际卷数
+ * @param {Object} [o.actualCounts] actualCountsByQuota() 的结果（键不带 quota. 前缀）
+ * @param {Object} formulas formulas-skeleton.json 的 formulas 段
+ * @returns {{quota:Object, decisions:Array, derivations:Object}}
+ */
+export function reverseQuota(o) {
+  const formulas = o.formulas || {};
+  const actual = o.actualCounts || {};
+  const decisions = [];
+  const quota = {};
+
+  const setPath = (obj, path, value) => {
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!cur[parts[i]] || typeof cur[parts[i]] !== 'object') cur[parts[i]] = {};
+      cur = cur[parts[i]];
+    }
+    cur[parts[parts.length - 1]] = value;
+  };
+
+  // 求值用的框架上下文（公式引用 quota 里的其它字段）
+  const framework = {
+    capacity: { target_chapters: o.targetChapters },
+    quota
+  };
+
+  /**
+   * 处理一个 quota 字段。
+   * @param {string} quotaPath 如 'quota.branch_count'
+   * @param {number|null} actualValue 旧稿实际值（null = 反推不出来）
+   */
+  const resolve = (quotaPath, actualValue) => {
+    const ctx = buildCtx(framework);
+    const range = formulaRange(formulas, quotaPath, ctx);
+    const low = range ? Math.round(range.low) : null;
+    const high = range ? Math.round(range.high) : null;
+
+    let value = null;
+    let source = null;
+    let outOfRange = false;
+    let note = '';
+
+    if (actualValue !== null && actualValue !== undefined && isFinite(actualValue) && actualValue >= 0) {
+      value = Math.round(actualValue);
+      source = 'actual';
+      if (range && (value < low || value > high)) {
+        outOfRange = true;
+        // 保留实际值（不夹到区间里）：quota 必须与实体条数一致，
+        // 夹取值只会把"区间 warning"换成"实体条数 ≠ quota"的 error。
+        // 越界只报 QUANTITY_MISMATCH（warning），骨架阶段能过。
+        note = '旧稿实际值 ' + value + ' 不在公式区间 [' + low + ', ' + high + '] 内；'
+          + '按旧稿实际规模保留（quota 必须与实体条数一致），骨架校验会报 QUANTITY_MISMATCH 警告';
+      } else {
+        note = '旧稿实际值落在公式区间内';
+      }
+    } else if (range) {
+      value = defaultInRange(range);
+      source = 'formula';
+      if (value === null) {
+        // 公式区间为空（下界 > 上界）—— 取任何值都不合法。
+        // 如实说明，别写一个"看起来像合法值"的数进去。
+        value = 1;
+        source = 'fallback';
+        note = '公式区间为空（[' + low + ', ' + high + ']，下界 > 上界），暂取 1；'
+          + '请调 capacity.target_chapters 或相关的 quota 字段让区间恢复非空';
+      } else {
+        note = '旧稿推不出来，按公式取下界（区间 [' + low + ', ' + high + ']）';
+      }
+    } else {
+      value = 1;
+      source = 'fallback';
+      note = '既无实际值也无公式，取 1';
+    }
+
+    setPath(quota, quotaPath.replace(/^quota\./, ''), value);
+    decisions.push({ field: quotaPath, value, source, low, high, outOfRange, note });
+    return value;
+  };
+
+  // ---- 依赖顺序 ----
+  // 卷数（T → V）
+  resolve('quota.volume_count', o.volumeCount && o.volumeCount > 0 ? o.volumeCount : null);
+
+  // 主角 / 核心配角 / 核心反派（P / CS / CA）—— 角色类的分项配额
+  resolve('quota.character_counts.protagonist', pick(actual, 'quota.character_counts.protagonist'));
+  resolve('quota.character_counts.core_supporting', pick(actual, 'quota.character_counts.core_supporting'));
+  resolve('quota.character_counts.core_antagonist', pick(actual, 'quota.character_counts.core_antagonist'));
+
+  // 支线（BC）
+  resolve('quota.branch_count', pick(actual, 'quota.branch_count'));
+  // 核心冲突（CC）
+  resolve('quota.conflict_counts.core', pick(actual, 'quota.conflict_counts.core'));
+  // 主线（固定公式）
+  resolve('quota.main_line_count', pick(actual, 'quota.main_line_count'));
+
+  // 其余全部字段
+  const rest = [
+    'quota.character_counts.volume_supporting',
+    'quota.character_counts.volume_antagonist',
+    'quota.conflict_counts.phase',
+    'quota.conflict_counts.branch',
+    'quota.faction_count',
+    'quota.faction_relation_count',
+    'quota.location_count',
+    'quota.ending_count',
+    'quota.foreshadow_counts.small',
+    'quota.foreshadow_counts.medium',
+    'quota.foreshadow_counts.large',
+    'quota.climax_counts.small',
+    'quota.climax_counts.medium',
+    'quota.climax_counts.large',
+    'quota.pleasure_counts.small',
+    'quota.pleasure_counts.medium',
+    'quota.pleasure_counts.large',
+    'quota.item_counts.core',
+    'quota.item_counts.branch',
+    'quota.item_counts.symbolic',
+    'quota.world_rule_counts.core',
+    'quota.world_rule_counts.information',
+    'quota.world_rule_counts.social'
+  ];
+  for (const p of rest) resolve(p, pick(actual, p));
+
+  // ---- 公式推导记录（骨架校验器要求 30 条齐全，key 与 formulas-skeleton.json 一致） ----
+  // 每条：{ formula（逐字照抄）, range_low, range_high, note }
+  // 终值超出区间时 note 必须写明理由（否则 QUANTITY_MISMATCH 只是个没头没尾的警告）。
+  const byField = {};
+  for (const d of decisions) byField[d.field] = d;
+  const derivations = {};
+  for (const key of Object.keys(formulas)) {
+    const spec = formulas[key];
+    if (!spec) continue;
+    const field = spec.applies_to_field;
+    const d = byField[field];
+    const range = formulaRange(formulas, field, buildCtx(framework));
+    const low = range ? Math.round(range.low) : 0;
+    const high = range ? Math.round(range.high) : 0;
+    let note = '';
+    if (d && d.outOfRange) {
+      note = '终值 ' + d.value + ' 按旧稿实际规模保留，落在公式区间 [' + low + ', ' + high + '] 之外';
+    } else if (d && d.source === 'formula') {
+      note = '旧稿推不出来，按公式取下界';
+    }
+    derivations[key] = {
+      formula: spec.formula,
+      range_low: low,
+      range_high: high,
+      note: note
+    };
+  }
+
+  return { quota, decisions, derivations };
+}
+
+/**
+ * 最大余数法分配整数。
+ *
+ * 给定每个槽位的权重和要分配的总份数，按权重比例分整数份，
+ * 余数大的先拿 —— 保证：
+ *   - 每份都是**整数**（不会分出 0.5 章）
+ *   - 所有份数加起来**恰好等于**总数（不丢不重）
+ *   - 每份都 ≥ 0
+ *
+ * @param {number[]} weights 各槽位的权重（非负）
+ * @param {number} total 要分配的总份数
+ * @param {number} slots 槽位数
+ * @returns {number[]} 长度 = slots
+ */
+export function largestRemainder(weights, total, slots) {
+  const n = Math.max(0, Math.round(slots));
+  const out = new Array(n).fill(0);
+  if (!n) return out;
+  const t = Math.max(0, Math.round(total));
+  if (!t) return out;
+
+  let w = Array.isArray(weights) ? weights.slice(0, n) : [];
+  while (w.length < n) w.push(0);
+  w = w.map((x) => {
+    const v = Number(x);
+    return isFinite(v) && v > 0 ? v : 0;
+  });
+  const wsum = w.reduce((a, b) => a + b, 0);
+  // 全是 0 权重 → 均分
+  const eff = wsum > 0 ? w : new Array(n).fill(1);
+  const esum = eff.reduce((a, b) => a + b, 0);
+
+  const quota = eff.map((x) => (t * x) / esum);
+  const floors = quota.map((x) => Math.floor(x));
+  let rest = t - floors.reduce((a, b) => a + b, 0);
+  // 余数大的先拿；余数相同按下标小的先拿（结果确定，不随运行变化）
+  const order = quota
+    .map((x, i) => ({ i, frac: x - Math.floor(x) }))
+    .sort((a, b) => (b.frac - a.frac) || (a.i - b.i));
+  for (const o of order) {
+    if (rest <= 0) break;
+    floors[o.i] += 1;
+    rest -= 1;
+  }
+  return floors;
+}
+
+/**
+ * 生成 volume_ratio（每卷占多少章）。
+ *
+ * 骨架校验器要求：长度 = quota.volume_count，各项 chapter_ratio 之和 = 1.0。
+ *
+ * 优先用**旧稿的实际分卷**：每卷实际写了多少章，就占多少比例。
+ * 旧稿没分卷信息时才均分（opts.hasVolumeInfo === false）。
+ *
+ * ## 为什么用最大余数法而不是"各算各的再让最后一项吃差额"
+ *
+ * 旧实现最后一项吃差额，于是：
+ *   buildVolumeRatio(30, [29 个 1000, 1]) → 前 29 项 0.0345，最后一项 **-0.0005**
+ * 负比例会让节奏阶段算出"期望约 -2 章"，负数还会一路传下去。
+ *
+ * 现在先按权重分配**整数章数**（每份天然 ≥ 0、加起来恰好等于总章数），
+ * 再把整数转成比例（放大到万分之一单位后用最大余数法补齐），
+ * 于是每一项都在 [0,1]、没有负数、和**精确等于** 1。
+ *
+ * @param {number} volumeCount
+ * @param {number[]} [chaptersPerVolume] 每卷实际章数（按卷序）
+ * @param {Object} [opts]
+ * @param {number} [opts.total] 总章数（默认 = chaptersPerVolume 之和）
+ * @param {boolean} [opts.hasVolumeInfo] 旧稿是否有分卷信息（默认 true）
+ * @returns {Array<{volume_id:string, chapter_ratio:number}>}
+ */
+export function buildVolumeRatio(volumeCount, chaptersPerVolume, opts = {}) {
+  const v = Math.max(0, Math.round(volumeCount || 0));
+  if (!v) return [];
+
+  let counts = Array.isArray(chaptersPerVolume)
+    ? chaptersPerVolume.slice(0, v).map((c) => {
+      const n = Number(c);
+      return isFinite(n) && n > 0 ? n : 0;
+    })
+    : [];
+  while (counts.length < v) counts.push(0);
+
+  const counted = counts.reduce((a, b) => a + b, 0);
+  const hasVolumeInfo = opts.hasVolumeInfo !== false;
+  const total = opts.total !== undefined && opts.total !== null && isFinite(opts.total)
+    ? Math.max(0, Math.round(opts.total))
+    : counted;
+
+  // 权重：旧稿有分卷信息就按各卷实际章数；没有就均分（等权）
+  const weights = hasVolumeInfo ? counts : new Array(v).fill(1);
+  // 比例的分母：真实总章数。旧稿一章都没有时（total=0）没有分母可言，
+  // 这时按"每卷 1 份"均分 —— 骨架只要求各项加起来等于 1。
+  const base = total > 0 ? total : v;
+  const alloc = largestRemainder(weights, base, v);
+
+  // 整数 → 比例（放大到万分之一单位，再用最大余数法补齐，和恰好是 1）
+  const UNIT = 10000;
+  const scaled = alloc.map((a) => (a * UNIT) / base);
+  const floors = scaled.map((x) => Math.floor(x));
+  let rest = UNIT - floors.reduce((a, b) => a + b, 0);
+  const order = scaled
+    .map((x, i) => ({ i, frac: x - Math.floor(x) }))
+    .sort((a, b) => (b.frac - a.frac) || (a.i - b.i));
+  for (const o of order) {
+    if (rest <= 0) break;
+    floors[o.i] += 1;
+    rest -= 1;
+  }
+
+  const out = [];
+  for (let i = 0; i < v; i++) {
+    out.push({
+      volume_id: 'V' + String(i + 1).padStart(3, '0'),
+      chapter_ratio: floors[i] / UNIT
+    });
+  }
+  return out;
+}
+
+/**
+ * 取实际值。
+ *
+ * 键的两种形态都认：`quota.faction_count`（公式里的路径写法）
+ * 与 `faction_count`（QUOTA_MAP 的键写法）。
+ * 两个来源的键形态不一致是历史遗留，硬要调用方记住一种太容易出错。
+ *
+ * **0 是合法统计值，不是"推不出来"**（2026-10-27 修）：
+ * 旧实现只接受 v > 0，于是"旧稿里一个势力都没有"（actual=0）
+ * 被当成"反推不出来"，改用公式下界 → quota 变成 2，
+ * 而实体数组里 factions 是 0 条 → 骨架阶段 QUOTA_MISMATCH（error），
+ * 导入却报成功。旧稿本来就没有的东西，不该凭空要求模型造出来。
+ *
+ * @returns {number|null} null = 缺失（没有这个统计项）
+ */
+function pick(actual, key) {
+  const bare = key.replace(/^quota\./, '');
+  const v = actual[key] !== undefined ? actual[key] : actual[bare];
+  return typeof v === 'number' && isFinite(v) && v >= 0 ? v : null;
+}
+
+/**
+ * 造公式求值用的变量表。
+ * 每次 resolve 之后要重建 —— quota 变了，依赖它的区间也会变。
+ */
+function buildCtx(framework) {
+  const quota = framework.quota || {};
+  const get = (path) => {
+    const parts = path.split('.');
+    let cur = quota;
+    for (const p of parts) {
+      if (!cur || typeof cur !== 'object') return undefined;
+      cur = cur[p];
+    }
+    return cur;
+  };
+  return {
+    T: framework.capacity ? framework.capacity.target_chapters : undefined,
+    V: get('volume_count'),
+    P: get('character_counts.protagonist'),
+    CS: get('character_counts.core_supporting'),
+    CA: get('character_counts.core_antagonist'),
+    BC: get('branch_count'),
+    CC: get('conflict_counts.core'),
+    quota,
+    Math
+  };
+}
+
+// ============================================================
+// 落盘
+// ============================================================
+
+/**
+ * 章节正文 → story-builder 格式（第一行必须是 `# 第N章 <标题>`）。
+ *
+ * @param {Object} chapter scanSource 里的章节
+ * @param {number} seq 顺序章号（1..N）
+ * @returns {string}
+ */
+export function buildChapterFile(chapter, seq) {
+  const head = '# 第' + seq + '章 ' + chapter.title;
+  const body = String(chapter.body || '').trim();
+  return body ? head + '\n\n' + body + '\n' : head + '\n';
+}
+
+/**
+ * 章节文件名：`第NNN章.md`（三位补零，与写作阶段一致）。
+ * @param {number} seq
+ * @returns {string}
+ */
+export function chapterFileName(seq) {
+  return '第' + String(seq).padStart(3, '0') + '章.md';
+}