@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/plugins/fancy-import/index.js

@@ -0,0 +1,730 @@
+/**
+ * fancy-import plugin entry
+ *
+ * 把一部**已经写好的旧稿**转成 fancy-story-builder 的四阶段产物，
+ * 让旧稿能接着用正���流程继续做（补设定、排节奏、去 AI 味）。
+ *
+ * 流程（插件驱动，脚本当裁判）：
+ *   1. 扫描导入源（目录或单文件）→ 切章（保留原标题）→ 统计实际规模
+ *   2. 正文按 story-builder 格式落盘：设定/raw/sources/写作/第NNN章.md
+ *   3. 逐轮派活让模型反推：骨架 → 血肉 → 节奏 → 台账
+ *   4. 脚本按旧稿实际规模**反推 quota**，缺失项按公式补齐 → 写 框架.json
+ *   5. 每轮产物都跑 story-builder 自己的校验器；不过就带着错误重投
+ *   6. 生成导入报告（含待补清单）
+ *
+ * 为什么配额由脚本算而不是让模型填：
+ *   模型的"估计"和校验器的口径对不上，导入完就会校验失败；
+ *   而且 quota 必须与实体条数一致（骨架校验器按 QUOTA_MISMATCH 核对），
+ *   模型填的数和实际写出来的实体数必然对不上。
+ *
+ * 依赖：
+ *   - fancy-bootstrap（初始化项目）
+ *   - fancy-story-builder（四阶段产物格式与校验器）
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { llmFollowup, notify, spawnScript } from '#infra';
+import { readDeployedConfig, ensureSetupId } from '#story-builder/index.js';
+import { phaseScriptFiles } from '#story-builder/deploy-manifest.js';
+import { makeWaitForTurn } from '#story-builder/writing-driver.js';
+
+import {
+  scanSource,
+  reverseQuota,
+  actualCountsByQuota,
+  buildVolumeRatio,
+  buildChapterFile,
+  chapterFileName
+} from './import-core.js';
+import {
+  importDirs,
+  runImportStage,
+  renderImportReport,
+  writeImportReport,
+  pickExcerpts,
+  IMPORT_ROUNDS
+} from './import-driver.js';
+import { importTemplates } from './templates.js';
+
+export const inject = ['commands', 'userQuestions'];
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** story-builder 插件目录（导入要借它的模板与校验器） */
+const STORY_BUILDER_DIR = path.resolve(__dirname, '..', 'fancy-story-builder');
+
+/** 导入阶段要用的脚本（按各自阶段的入口推导依赖闭包） */
+const IMPORT_SCRIPT_PHASES = ['skeleton', 'flesh', 'rhythm'];
+
+/** 导入阶段要用的参考文件 */
+const IMPORT_REFERENCE_FILES = ['glossary.md', 'formulas-skeleton.json', 'formulas-rhythm.json'];
+
+/** 导入阶段要用的模板分类 */
+const IMPORT_TEMPLATE_DIRS = ['骨架', '血肉', '节奏'];
+
+function getProjectRoot(session) {
+  // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
+  const cwd = session.header && session.header.cwd;
+  return cwd || null;
+}
+
+function copyDirRecursive(srcDir, destDir) {
+  try {
+    if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch {
+    return false;
+  }
+  let allOk = true;
+  let entries;
+  try {
+    entries = fs.readdirSync(srcDir);
+  } catch {
+    return false;
+  }
+  for (const f of entries) {
+    const src = path.join(srcDir, f);
+    const dest = path.join(destDir, f);
+    let st;
+    try {
+      st = fs.statSync(src);
+    } catch {
+      allOk = false;
+      continue;
+    }
+    if (st.isDirectory()) {
+      if (!copyDirRecursive(src, dest)) allOk = false;
+    } else if (st.isFile()) {
+      try {
+        fs.copyFileSync(src, dest);
+      } catch {
+        allOk = false;
+      }
+    }
+  }
+  return allOk;
+}
+
+/**
+ * 把导入阶段要用的脚本 / 参考 / 模板部署到项目里。
+ *
+ * 清单**不是手写的**：从各阶段入口校验脚本的 import 闭包推出来
+ * （见 story-builder/deploy-manifest.js）。少拷一个文件，
+ * 校验器在运行时才报 ERR_MODULE_NOT_FOUND —— 部署阶段看不出问题。
+ *
+ * @returns {{ok:boolean, missing:string[], err:string|null}}
+ */
+export function deployImportFiles(projectRoot) {
+  const missing = [];
+  const refsDir = path.join(projectRoot, 'references');
+  const tplRoot = path.join(projectRoot, '模板');
+
+  try {
+    fs.mkdirSync(refsDir, { recursive: true });
+  } catch (e) {
+    return { ok: false, missing, err: 'references/ 目录建不出来：' + e.message };
+  }
+
+  // 1. 校验脚本（按 import 闭包）
+  const files = new Set();
+  for (const phase of IMPORT_SCRIPT_PHASES) {
+    const manifest = phaseScriptFiles(
+      phase,
+      path.join(STORY_BUILDER_DIR, 'scripts'),
+      path.join(STORY_BUILDER_DIR, 'prompts'),
+      path.join(STORY_BUILDER_DIR, 'references')
+    );
+    if (!manifest) continue;
+    for (const m of manifest.missing) missing.push(m);
+    for (const f of manifest.files) files.add(f);
+  }
+  for (const f of files) {
+    const src = path.join(STORY_BUILDER_DIR, 'scripts', f);
+    if (!fs.existsSync(src)) {
+      missing.push(f + '（清单里有，磁盘上没有）');
+      continue;
+    }
+    try {
+      fs.copyFileSync(src, path.join(refsDir, f));
+    } catch {
+      missing.push(f + '（拷贝失败）');
+    }
+  }
+
+  // 2. 参考文件（词表 / 公式）
+  for (const f of IMPORT_REFERENCE_FILES) {
+    const src = path.join(STORY_BUILDER_DIR, 'references', f);
+    if (!fs.existsSync(src)) {
+      missing.push(f + '（references 里没有）');
+      continue;
+    }
+    try {
+      fs.copyFileSync(src, path.join(refsDir, f));
+    } catch {
+      missing.push(f + '（拷贝失败）');
+    }
+  }
+
+  // 3. 模板
+  for (const d of IMPORT_TEMPLATE_DIRS) {
+    if (!copyDirRecursive(path.join(STORY_BUILDER_DIR, 'templates', d), path.join(tplRoot, d))) {
+      missing.push('模板/' + d);
+    }
+  }
+
+  return { ok: missing.length === 0, missing, err: null };
+}
+
+/**
+ * 把扫描结果落盘：正文按 story-builder 格式，设定资料单独放一份。
+ *
+ * 覆盖已有正文前**必须先备份**（2026-10-27 修）：
+ * 用户跑过写作/去味之后再导入一次，旧实现直接用原始旧稿覆盖
+ * `设定/raw/sources/写作/第NNN章.md` —— 去味成果全部丢失且不可恢复
+ * （`.revisions/` 只覆盖去味阶段的备份，不覆盖导入）。
+ * 现在覆盖前先复制到 `写作/.revisions/import-<时间戳>/`，
+ * **备份不成功就不覆盖**（宁可这一章导入失败，也不能丢用户已有的正文）。
+ *
+ * @returns {{written:number, skipped:number, errors:string[], overwritten:string[], backupDir:string}}
+ */
+export function writeScannedChapters(dirs, scan) {
+  const written = [];
+  const errors = [];
+  const overwritten = [];
+  let backupDir = '';
+
+  try {
+    fs.mkdirSync(dirs.writing, { recursive: true });
+  } catch (e) {
+    return { written: 0, skipped: 0, errors: ['写作目录建不出来：' + e.message], overwritten, backupDir };
+  }
+
+  for (const ch of scan.chapters) {
+    const p = path.join(dirs.writing, chapterFileName(ch.ch));
+
+    // 覆盖前先备份
+    if (fs.existsSync(p)) {
+      if (!backupDir) {
+        backupDir = path.join(dirs.writing, '.revisions', 'import-' + importStamp());
+      }
+      try {
+        fs.mkdirSync(backupDir, { recursive: true });
+        fs.copyFileSync(p, path.join(backupDir, path.basename(p)));
+        overwritten.push(path.basename(p));
+      } catch (e) {
+        errors.push('备份不了 ' + path.basename(p) + '（不覆盖它）：' + e.message);
+        continue;
+      }
+    }
+
+    try {
+      fs.writeFileSync(p, buildChapterFile(ch, ch.ch), 'utf-8');
+      written.push(p);
+    } catch (e) {
+      errors.push('第 ' + ch.ch + ' 章写不下去：' + e.message);
+    }
+  }
+
+  // 设定资料：原样放一份，供模型反推时读
+  if (scan.settings.length) {
+    try {
+      for (const s of scan.settings) {
+        // s.name 现在是**相对路径**（可能带子目录），要先把父目录建出来
+        const target = path.join(dirs.material, s.name);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, s.text, 'utf-8');
+      }
+    } catch (e) {
+      errors.push('设定资料落盘失败：' + e.message);
+    }
+  }
+
+  return { written: written.length, skipped: scan.chapters.length - written.length, errors, overwritten, backupDir };
+}
+
+/**
+ * 备份目录用的时间戳（可读 + 同一秒内不撞车）。
+ * @returns {string}
+ */
+function importStamp() {
+  const d = new Date();
+  const p = (n, w) => String(n).padStart(w, '0');
+  return d.getFullYear() + '-' + p(d.getMonth() + 1, 2) + '-' + p(d.getDate(), 2) +
+    'T' + p(d.getHours(), 2) + '-' + p(d.getMinutes(), 2) + '-' + p(d.getSeconds(), 2) +
+    '-' + p(d.getMilliseconds(), 3);
+}
+
+/**
+ * 导入阶段的命令入口。
+ */
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-import',
+    description: '📥 旧稿导入 ( usage: /fancy-import <旧稿目录或文件> )',
+    input: {
+      hint: '旧稿目录或文件'
+    },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const { signal } = invocation;
+
+      const projectRoot = getProjectRoot(session);
+      if (!projectRoot) {
+        return notify(session, 'error', importTemplates.notify({
+          type: 'no_project_root',
+          err: '会话未提供 cwd'
+        }));
+      }
+
+      if (!fs.existsSync(path.join(projectRoot, '.fancy-deployed'))) {
+        return notify(session, 'error', importTemplates.notify({ type: 'not_initialized' }));
+      }
+
+      const deployedRes = readDeployedConfig(projectRoot);
+      if (!deployedRes.ok || !deployedRes.config) {
+        return notify(session, 'error', importTemplates.notify({
+          type: deployedRes.reason === 'not_found' ? 'not_initialized' : 'no_source',
+          err: '.fancy-deployed 读不到（' + (deployedRes.reason || '未知') + '）'
+        }));
+      }
+      const deployedConfig = deployedRes.config;
+
+      // 1. 导入源
+      const rawInput = (invocation.rawInput || '').trim();
+      let sourcePath = rawInput;
+      if (!sourcePath) {
+        // 没给路径：默认找项目里的 旧稿/ 目录
+        const fallback = path.join(projectRoot, '旧稿');
+        if (fs.existsSync(fallback) && fs.statSync(fallback).isDirectory()) {
+          sourcePath = fallback;
+        } else {
+          return notify(session, 'error', importTemplates.notify({ type: 'no_source_arg' }));
+        }
+      }
+      if (!path.isAbsolute(sourcePath)) {
+        sourcePath = path.resolve(projectRoot, sourcePath);
+      }
+
+      // 2. 扫描（确定性：切章保标题 + 统计实际规模）
+      const scan = scanSource(sourcePath);
+      if (!scan.ok) {
+        return notify(session, 'error', importTemplates.notify({ type: 'no_source', err: scan.error }));
+      }
+
+      // 3. 部署导入要用的脚本 / 模板
+      const deploy = deployImportFiles(projectRoot);
+      if (!deploy.ok) {
+        return notify(session, 'error', importTemplates.notify({
+          type: 'deploy_failed',
+          err: deploy.missing.join('、')
+        }));
+      }
+
+      // 4. 设定项目（导入的产物要落在「设定」目录下才会被 ingest 纳管）
+      const llmWikiUrl = (deployedConfig.llm_wiki_url || '').replace(/\/$/, '');
+      const llmWikiToken = deployedConfig.llm_wiki_token || '';
+      const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+      if (!setupResult.id) {
+        return notify(session, 'error', importTemplates.notify({
+          type: 'setup_id_unavailable',
+          err: setupResult.reason
+        }));
+      }
+
+      const dirs = importDirs(projectRoot);
+
+      // 5. 正文落盘
+      const writeRes = writeScannedChapters(dirs, scan);
+      if (writeRes.errors.length) {
+        return notify(session, 'error', importTemplates.notify({
+          type: 'no_source',
+          err: writeRes.errors.join('；')
+        }));
+      }
+
+      // 6. 公式（算配额用）
+      let formulas = {};
+      try {
+        formulas = JSON.parse(
+          fs.readFileSync(path.join(projectRoot, 'references', 'formulas-skeleton.json'), 'utf-8')
+        ).formulas || {};
+      } catch (e) {
+        return notify(session, 'error', importTemplates.notify({
+          type: 'deploy_failed',
+          err: 'formulas-skeleton.json 读不出来：' + e.message
+        }));
+      }
+
+      // 7. 逐轮反推
+      const progressNotes = [];
+      const contract = readImportContract();
+      const waitForTurn = makeImportWait(invocation);
+
+      // 配额是算出来的，实体轮之后才有值 —— 关系/血肉/节奏轮都要照它写
+      const promptContext = {
+        chapterCount: scan.chapters.length,
+        settingCount: scan.settings.length,
+        excerpts: pickExcerpts(scan.chapters),
+        quota: null
+      };
+
+      const report = await runImportStage({
+        projectRoot,
+        dirs,
+        contract,
+        context: promptContext,
+        sendPrompt: async (prompt) => llmFollowup(invocation, prompt),
+        waitIdle: async (files) => waitForTurn(files),
+        validateFile: async (file, round, f) => {
+          if (!round.validator || !f.tpl) return { ok: true, errors: [] };
+          const script = path.join(projectRoot, 'references', round.validator);
+          const tpl = path.join(projectRoot, '模板', round.templateDir, f.tpl);
+          const r = await spawnScript('node', [
+            script,
+            '--input=' + file,
+            '--template=' + tpl,
+            '--file=' + f.type
+          ], { timeout: 120000, cwd: projectRoot });
+          if (!r.ok) {
+            return { ok: false, errors: [{ code: 'VALIDATOR_CRASH', path: file, message: '校验脚本异常：' + (r.error || r.stderr || '未知错误'), hint: null }] };
+          }
+          try {
+            const parsed = JSON.parse(r.output);
+            return { ok: parsed.status === 0, errors: parsed.errors || [] };
+          } catch (e) {
+            return { ok: false, errors: [{ code: 'VALIDATOR_OUTPUT_INVALID', path: file, message: '校验脚本输出不是合法 JSON：' + e.message, hint: null }] };
+          }
+        },
+        onProgress: (msg) => { progressNotes.push(msg); },
+        onRound: (r) => {
+          // 实体轮结束后按实际条数算出配额，写 框架.json，
+          // 后面的关系/血肉/节奏轮都照这份配额写。
+          if (r.id !== 'entities') return;
+          const q = writeFramework(dirs, scan, formulas);
+          promptContext.quota = q.quota;
+        }
+      });
+
+      // 8. 兜底重算一次配额（即便实体轮没通过，也要给出配额与报告）
+      const quotaInfo = writeFramework(dirs, scan, formulas);
+
+      // 9. 框架.json 自己也要过一遍校验器（它是导入的核心产物）
+      const frameworkErrors = await validateFramework(projectRoot, dirs);
+
+      // 10. 报告
+      const gaps = frameworkErrors.map(
+        (e) => '[框架.json] [' + e.code + '] ' + (e.path || '(无路径)') + '：' + e.message +
+        (e.hint ? '（' + e.hint + '）' : '')
+      );
+      const infeasible = rhythmInfeasibleReason(scan.stats.chapterCount, quotaInfo.quota.branch_count);
+      if (infeasible) gaps.push(infeasible);
+
+      // 10.1 **阻塞项**：这些不是"建议补全"，是"产物不可用"。
+      //
+      // 旧实现把它们全塞进 gaps，而成功判定只看 report.failed ——
+      // 于是"框架校验不过 / 框架没写出来 / 校验器没部署 / 节奏无解"
+      // 全都只写进报告，通知仍然是"✅ 导入完成"（2026-10-27 核实）。
+      // 产物在下游骨架阶段必然失败，用户却被告知成功。
+      const blocking = [];
+      if (!quotaInfo.ok) {
+        blocking.push('框架.json 写入失败：' + (quotaInfo.error || '未知错误'));
+      }
+      for (const e of frameworkErrors) {
+        blocking.push('[' + e.code + '] ' + (e.path || '(无路径)') + '：' + e.message);
+      }
+      if (infeasible) blocking.push(infeasible);
+
+      const reportMd = renderImportReport({
+        scan,
+        report,
+        quotaDecisions: quotaInfo.decisions,
+        gaps,
+        overwritten: writeRes.overwritten,
+        backupDir: writeRes.backupDir
+      });
+      writeImportReport(dirs, reportMd);
+
+      const progressSummary = progressNotes.length
+        ? '导入进度：' + progressNotes.slice(-3).join('；')
+        : '';
+
+      // 覆盖提示必须说清楚：用户可能已经跑过写作/去味，
+      // 这次导入把旧稿原样盖回去了（原文已备份，但成果确实被覆盖）。
+      const overwriteNote = writeRes.overwritten.length
+        ? '⚠️ 覆盖了 ' + writeRes.overwritten.length + ' 个已有章节' +
+          '（原文已备份到 `' + writeRes.backupDir + '`）。'
+        : '';
+
+      if (report.failed.length || blocking.length) {
+        const detail = blocking.length
+          ? '**阻塞项（产物当前不可用）**：\n' + blocking.map((b) => '- ' + b).join('\n')
+          : '';
+        return notify(session, 'error', importTemplates.notify({
+          type: 'import_incomplete',
+          failed: report.failed.length,
+          extra: [progressSummary, overwriteNote, detail].filter(Boolean).join('\n\n')
+        }));
+      }
+
+      return notify(session, 'success', importTemplates.notify({
+        type: 'import_done',
+        chapters: scan.stats.chapterCount,
+        rounds: report.rounds.length,
+        extra: [progressSummary, overwriteNote].filter(Boolean).join('\n\n')
+      }));
+    }
+  });
+}
+
+// ============================================================
+// 辅助
+// ============================================================
+
+/**
+ * 读导入执行须知（prompts/01-import-prompt.md）。
+ */
+function readImportContract() {
+  try {
+    return fs.readFileSync(path.join(__dirname, 'prompts', '01-import-prompt.md'), 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 等 LLM 跑完一轮。
+ *
+ * 用 story-builder 的 makeWaitForTurn —— 轮询 agent.status 的那套逻辑
+ * 两边一样，自己抄一份必然漂移。
+ */
+function makeImportWait(invocation) {
+  return makeWaitForTurn(invocation, { timeoutMs: 45 * 60 * 1000 });
+}
+
+/**
+ * 按旧稿实际规模反推 quota，写 骨架/框架.json。
+ *
+ * @returns {{quota:Object, decisions:Array, path:string}}
+ */
+export function writeFramework(dirs, scan, formulas) {
+  // 实体.json 是骨架轮产出的；读不到就按"没有实体"处理（配额会全部走公式）
+  let entityData = null;
+  try {
+    entityData = JSON.parse(fs.readFileSync(path.join(dirs.skeleton, '实体.json'), 'utf-8'));
+  } catch {
+    entityData = null;
+  }
+
+  const actualCounts = actualCountsByQuota(entityData);
+  const { quota, decisions, derivations } = reverseQuota({
+    targetChapters: scan.stats.chapterCount,
+    volumeCount: scan.stats.volumeCount || null,
+    actualCounts,
+    formulas
+  });
+
+  const capacity = {
+    target_chapters: scan.stats.chapterCount,
+    target_words: scan.stats.totalWords,
+    avg_words_per_chapter: scan.stats.avgWords
+  };
+
+  // 输入快照：书名 / 题材 / 核心冲突这些脚本算不出来（那是书的自我认知），
+  // 由第一轮反推产出；读不到就留空 —— 空值会被骨架校验器如实拦下。
+  const snapshot = readInputSnapshot(dirs);
+
+  // 卷比例：按旧稿的实际分卷（没分卷信息就均分）
+  const perVolume = chaptersPerVolume(scan);
+  const volumeRatio = buildVolumeRatio(quota.volume_count || 0, perVolume.counts, {
+    total: (scan.chapters || []).length,
+    hasVolumeInfo: perVolume.hasVolumeInfo
+  });
+
+  const framework = {
+    capacity,
+    input_snapshot: snapshot,
+    quota,
+    volume_ratio: volumeRatio,
+    derivations
+  };
+
+  let written = '';
+  let writeError = null;
+  try {
+    fs.mkdirSync(dirs.skeleton, { recursive: true });
+    written = path.join(dirs.skeleton, '框架.json');
+    fs.writeFileSync(written, JSON.stringify(framework, null, 2), 'utf-8');
+  } catch (e) {
+    // 写不出来必须**如实报**，不能悄悄吞掉 —— 旧实现吞掉之后
+    // validateFramework 因为"文件不存在"直接返回 []，于是导入报成功，
+    // 而框架.json 根本没生成（2026-10-27 核实）。
+    written = '';
+    writeError = e && e.message ? e.message : String(e);
+  }
+
+  return { quota, decisions, derivations, snapshot, path: written, ok: !writeError, error: writeError };
+}
+
+/**
+ * 读模型反推出的输入快照。
+ * @param {Object} dirs
+ * @returns {Object}
+ */
+function readInputSnapshot(dirs) {
+  const empty = {
+    book_name: '',
+    genre: '',
+    core_summary: '',
+    core_conflict: '',
+    hard_constraints: [],
+    anti_tropes: []
+  };
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.join(dirs.material, '输入快照.json'), 'utf-8'));
+  } catch {
+    return empty;
+  }
+  if (!raw || typeof raw !== 'object') return empty;
+  const arr = (v) => (Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : []);
+  return {
+    book_name: typeof raw.book_name === 'string' ? raw.book_name : '',
+    genre: typeof raw.genre === 'string' ? raw.genre : '',
+    core_summary: typeof raw.core_summary === 'string' ? raw.core_summary : '',
+    core_conflict: typeof raw.core_conflict === 'string' ? raw.core_conflict : '',
+    hard_constraints: arr(raw.hard_constraints),
+    anti_tropes: arr(raw.anti_tropes)
+  };
+}
+
+/**
+ * 旧稿每卷实际写了多少章（按卷序）。
+ *
+ * ## 旧实现错在哪
+ *
+ * 旧代码是"每遇到一个带 volume 的章就 counts.push(1)" —— 那不是按卷分桶，
+ * 是把 600 章变成 600 个桶，再截断到 V 个，结果还是 [1,1,1,…]；
+ * 而 scanSource 又没把 volume 写进 chapter，`ch.volume` 永远是 undefined，
+ * 于是全部落进"第 0 卷"分支 → counts = [总章数]。
+ * 注释写着"优先用旧稿的实际分卷，没分卷信息才均分"，实现恰好相反。
+ *
+ * 现在按**卷**分桶：
+ *   - 有卷信息的章 → 按卷归桶（卷的标识用卷标题行，取不到就用卷号）；
+ *   - 卷标题之前那些没卷信息的章 → 归入第一卷（旧稿里它们确实排在最前面）；
+ *   - 旧稿**完全**没有卷信息 → 返回 hasVolumeInfo=false，调用方据此均分。
+ *
+ * @param {Object} scan
+ * @returns {{counts:number[], hasVolumeInfo:boolean}}
+ */
+function chaptersPerVolume(scan) {
+  const chapters = scan.chapters || [];
+  const counts = [];
+  const bucketOf = new Map();
+  let loose = 0;
+
+  for (const ch of chapters) {
+    const v = ch.volume || null;
+    if (!v) {
+      loose += 1;
+      continue;
+    }
+    const key = v.heading || (v.no !== null && v.no !== undefined ? 'no:' + v.no : 'title:' + (v.title || ''));
+    let idx = bucketOf.get(key);
+    if (idx === undefined) {
+      idx = counts.length;
+      counts.push(0);
+      bucketOf.set(key, idx);
+    }
+    counts[idx] += 1;
+  }
+
+  if (!counts.length) {
+    // 旧稿完全没有卷信息
+    return { counts: loose ? [loose] : [], hasVolumeInfo: false };
+  }
+  if (loose) counts[0] += loose;
+  return { counts, hasVolumeInfo: true };
+}
+
+/**
+ * 校验插件生成的 框架.json。
+ *
+ * 框架.json 是导入的核心产物（配额、卷比例、推导全在里面），
+ * 它必须和别的东西一样过校验器 —— 不然导入"成功"了，
+ * 下游骨架阶段一跑就炸。
+ *
+ * @returns {Promise<Array>} 错误列表
+ */
+export async function validateFramework(projectRoot, dirs) {
+  const file = path.join(dirs.skeleton, '框架.json');
+  if (!fs.existsSync(file)) {
+    // 文件不存在 ≠ 校验通过。旧实现这里 return []，于是"框架没写出来"
+    // 被当成"没问题"，导入照样报成功（2026-10-27 核实）。
+    return [{
+      code: 'FRAMEWORK_MISSING',
+      path: file,
+      message: '框架.json 没有生成（写入失败，或实体轮没有产出实体清单）',
+      hint: '检查磁盘空间/目录权限，以及导入报告里的实体轮结果'
+    }];
+  }
+  const script = path.join(projectRoot, 'references', 'skeleton-validate.js');
+  const tpl = path.join(projectRoot, '模板', '骨架', '框架模板.json');
+  if (!fs.existsSync(script)) {
+    // 校验器缺失是**部署失败**，不是"跳过" —— 跳过后框架根本没被校验过。
+    return [{ code: 'VALIDATOR_MISSING', path: script, message: '骨架校验器没部署，无法校验框架.json', hint: '重新部署插件后再导入' }];
+  }
+  const r = await spawnScript('node', [
+    script,
+    '--input=' + file,
+    '--template=' + tpl,
+    '--file=框架'
+  ], { timeout: 120000, cwd: projectRoot });
+  if (!r.ok) {
+    return [{ code: 'VALIDATOR_CRASH', path: file, message: '校验脚本异常：' + (r.error || r.stderr || '未知错误'), hint: null }];
+  }
+  try {
+    const parsed = JSON.parse(r.output);
+    return parsed.errors || [];
+  } catch (e) {
+    return [{ code: 'VALIDATOR_OUTPUT_INVALID', path: file, message: '校验脚本输出不是合法 JSON：' + e.message, hint: null }];
+  }
+}
+
+/**
+ * 支线可行性：骨架校验器要求 BC*3 <= T*0.5 且 BC*30 >= T*0.3。
+ *
+ * T 太小的时候这个条件**无解**（T=3 时 BC 至少要 <=0.5、>=0.03，
+ * 没有整数满足）。这不是导入的 bug，是旧稿太短撑不起骨架阶段的规模要求。
+ * 如实说出来，别装作导入成功了。
+ *
+ * 关于"即 T >= 6"：那句话是错的（2026-10-27 核实）——
+ * 可行条件是 **BC <= floor(ceil(0.5T)/3) 且 BC >= ceil(floor(0.3T)/30)**，
+ * 与 T 无关地还要求 BC 本身落在某个区间里。T=6 时只有 BC=1 可行，
+ * BC=2、BC=3 都无解。所以这里直接给出**可行的 BC 区间**，让用户照着调。
+ *
+ * @param {number} T 旧稿章数
+ * @param {number} BC 支线配额
+ * @returns {string|null} 有问题返回说明，否则 null
+ */
+export function rhythmInfeasibleReason(T, BC) {
+  if (typeof T !== 'number' || typeof BC !== 'number') return null;
+  const lower = Math.max(BC * 3, Math.floor(T * 0.3));
+  const upper = Math.min(BC * 30, Math.ceil(T * 0.5));
+  if (lower <= upper) return null;
+  // 可行的 BC 区间：把 lower/upper 两边对 BC 解出来
+  const bcLower = Math.max(1, Math.ceil(Math.floor(T * 0.3) / 30));
+  const bcUpper = Math.floor(Math.ceil(T * 0.5) / 3);
+  const feasible = bcUpper >= bcLower
+    ? '可行的支线数区间是 [' + bcLower + ', ' + bcUpper + ']（BC*3 <= T*0.5 且 BC*30 >= T*0.3）'
+    : '当前 T 下没有任何支线数可行（需要 ceil(floor(0.3T)/30) <= BC <= floor(ceil(0.5T)/3)）';
+  return '旧稿只有 ' + T + ' 章，达不到骨架阶段的规模要求：' +
+    '支线配额 ' + BC + ' 要求区间 [' + lower + ', ' + upper + '] 无解' +
+    '（' + feasible + '）。' +
+    '建议把支线数改到上面的可行区间，或改用 /fancy-story-builder 从骨架重新起稿。';
+}