@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-story-builder/stage-driver.js

@@ -0,0 +1,1049 @@
+/**
+ * stage-driver.js  v1.0
+ * 阶段驱动的通用实现：插件当司机，脚本当裁判，LLM 只负责按指令生成文件。
+ *
+ * 为什么要这么改（2026-10 tt5 实测）：
+ * - 原来血肉阶段的"循环"写在提示词里，由 LLM 自己调 flesh-validate.js、
+ *   自己读错误码、自己决定改哪里、自己决定下一步。实测后果：
+ *   102 次工具调用里 50 次是模型自己在调校验器，60 次 edit 是模型自己
+ *   解读错误码改文件，而全量校验（--all）**一次都没跑**
+ *   （.stage-status.json 里的 all_check:PENDING 是 flesh-validate.js:925
+ *   的初始化默认值，不是判定结果）。
+ * - 结局.json 写到一半被 provider 中断（output new_sensitive 1027），
+ *   插件只报了"阶段开始"，用户对失败完全无感。
+ *
+ * 现在：生成粒度 = 批次，校验粒度 = 文件，判定权 = 插件 + 脚本。
+ * LLM 收到的是"本轮写哪个文件、写哪几条"的指令和脚本判出来的错误清单，
+ * 不再自己调脚本、不再自己判断通过与否。
+ *
+ * 本模块不直接依赖 dsh 运行时：sendPrompt / waitIdle / validateFile
+ * 都由调用方注入，因此可以在没有 LLM 的情况下用测试夹具驱动。
+ */
+
+import { existsSync, readdirSync, readFileSync, renameSync } from 'fs';
+import { join } from 'path';
+import { classifyIssues, describeInfraIssues } from './scripts/error-classes.js';
+
+/**
+ * 读一个分片文件的文本（不存在或读不了返回 null）。
+ *
+ * 用途：重投前记下"旧内容"当基线，用来判断模型这一轮是不是真写了。
+ * 为什么需要它：旧分片不能删（删了 DSH 的 write 会报 FS_STALE_VERSION，
+ * 见 generateBatch 里的注释），所以完成判据只能改成"内容变了没有"。
+ */
+function readShardText(shardPath) {
+  try {
+    if (!shardPath || !existsSync(shardPath)) return null;
+    return readFileSync(shardPath, 'utf-8');
+  } catch (e) {
+    return null;
+  }
+}
+
+// 单批生成的最大尝试次数（含首次）
+export const STAGE_MAX_BATCH_ATTEMPTS = 3;
+
+/**
+ * provider 报错里哪些是**瞬时**的（重投一次可能好）。
+ *
+ * 码字面量来自 DSH：dsh-llm/lib/index.js:238 RATE_LIMIT、:133 QUOTA、
+ * :143 EMPTY_RESPONSE。鉴权失败（INVALID_CREDENTIAL）、上下文超限
+ * （CONTEXT_WINDOW_EXCEEDED）和 UNKNOWN 重投必然同样失败 —— 直接报出去，
+ * 别白烧三个回合的额度。
+ *
+ * @param {string} [code] - provider 错误码
+ * @returns {boolean}
+ */
+export function isTransientProviderCode(code) {
+  return code === 'RATE_LIMIT' || code === 'QUOTA' || code === 'EMPTY_RESPONSE';
+}
+
+// 中途校验最多允许重启几次生成（防死循环）
+export const MAX_CHECKPOINT_RESTARTS = 3;
+
+// 单个文件的最大校验轮次（第 1 轮是首次生成，后面的轮次是回改）
+export const STAGE_MAX_FILE_ROUNDS = 3;
+
+/**
+ * 生成一个批次：投递提示词 -> 等 LLM 空闲 -> 确认分片落盘。
+ *
+ * 失败（分片没落盘 / JSON 非法）时用同一批的失败原因再投一次，
+ * 最多 STAGE_MAX_BATCH_ATTEMPTS 次。
+ *
+ * @param {Object} opts
+ * @param {Object} opts.batch       批次描述
+ * @param {Array}  [opts.failures]  上一轮校验指出的错误（回喂用）
+ * @param {number} [opts.attempt]   当前是第几次尝试（1 起）
+ * @param {(batch, attempt, failures) => string} opts.buildPrompt
+ * @param {(prompt) => Promise<{ok: boolean, error?: string}>} opts.sendPrompt
+ * @param {(files) => Promise<{ok: boolean, reason?: string}>} opts.waitIdle
+ * @param {(batch) => {ok: boolean, error?: string}} opts.readShard
+ * @param {(batch) => boolean} [opts.removeShard] 重投前删掉旧分片
+ * @param {(batch) => boolean} [opts.adoptShard] 分片名不对时的兜底认领
+ * @param {(msg: string) => void} [opts.onProgress]
+ * @returns {Promise<Object>} { ok, error, attempts }
+ */
+export async function generateBatch(opts) {
+  const o = opts || {};
+  const batch = o.batch;
+  const maxAttempts = o.maxAttempts || STAGE_MAX_BATCH_ATTEMPTS;
+  let attempt = o.attempt || 1;
+  let failures = o.failures || [];
+  let lastError = null;
+  let lastCode = null;
+
+  while (attempt <= maxAttempts) {
+    // 重投前**不要删旧分片**。
+    //
+    // 删了会跟 DSH 的文件版本守卫撞车（tt5 实测 2026-10-24 22:00）：
+    //   DSH 的 write 工具记着"本会话上次看到这个文件时的版本"，
+    //   文件被外部删掉后再写同一路径 → FS_STALE_VERSION
+    //   → "cannot write ...: file no longer exists — re-read the file, then retry"；
+    //   而 re-read 同样失败（文件已经没了）→ 模型卡死，
+    //   最后只能改用 bash heredoc 绕路。实测 3 次 write 全废，turn 废掉一半。
+    //
+    // 改成 deslop 那套判据（见 index.js 的 deslop 阶段）：文件留着，
+    // 用"内容相对基线有没有变"判断本轮是不是真写了。
+    //
+    // **首轮也要取基线**：分片目录从不清理，而分片名是确定性的
+    // （骨架-<type>.b<seq>.<group>.json），所以重跑时上一轮的分片一定还在。
+    // 首轮不取基线的话，旧分片会立刻满足"文件在" → 批次被判 done →
+    // 旧内容被合并进产物，插件还跑到模型前面去了（实测 0ms 就判成功）。
+    // 首轮时文件本来不存在 → before 为 null → 内容判据自动放行，行为不变。
+    const before = readShardText(batch.shardPath);
+
+    const prompt = o.buildPrompt(batch, attempt, failures);
+    const sent = await o.sendPrompt(prompt);
+    if (!sent || sent.ok !== true) {
+      lastError = (sent && sent.error) || '提示词投递失败';
+      failures = [{ code: 'PROMPT_DELIVERY_FAILED', path: '', message: lastError, hint: null }];
+      attempt += 1;
+      continue;
+    }
+
+    const waited = await o.waitIdle([batch.shardPath], before);
+    if (!waited || waited.ok !== true) {
+      lastError = (waited && waited.reason) || '等待 LLM 结束失败';
+      // LLM 写到了别的文件名：尝试认领（只认领唯一一个多出来的 json）
+      let adopted = false;
+      if (typeof o.adoptShard === 'function') {
+        adopted = o.adoptShard(batch);
+        if (adopted) {
+          const re = o.readShard(batch);
+          if (re && re.ok) {
+            if (o.onProgress) o.onProgress('分片 ' + batch.shard + ' 落在别的文件名上，已认领');
+            return { ok: true, error: null, attempts: attempt };
+          }
+        }
+      }
+      failures = [{ code: 'BATCH_SHARD_MISSING', path: batch.shard, message: lastError, hint: null }];
+      lastCode = (waited && waited.code) || 'BATCH_SHARD_MISSING';
+      // 环境类失败（超时 / 用户中断 / 运行时缺失）重试没有意义：
+      // 再投一次还是同样失败，白烧额度（用户按了 Ctrl-C 还在喂 LLM）。
+      // 与 deslop-driver 的处理口径一致。
+      const waitCode = (waited && waited.code) || '';
+      if (waitCode === 'TIMEOUT' || waitCode === 'ABORTED' || waitCode === 'NO_AGENT') {
+        return { ok: false, error: lastError, attempts: attempt, code: waitCode };
+      }
+      // NO_CHANGE：模型这轮**没动**这个文件。
+      //
+      // 常见于**重跑 / 重投**场景：文件里已经是上一轮写对的内容，
+      // 模型读完说"已经是对的"就不改了（tt5 实测 2026-10-25：
+      // 实体 b03.factions 死在这 —— 模型回"The file already has the correct
+      // 6 factions"，插件却判它没写，整段卡死）。
+      //
+      // 直接判失败会卡死整个阶段。正确处置是**让脚本裁判**：
+      // 对这个分片跑一次局部校验 —— 通过就说明内容本来就对（模型说得没错），
+      // 这批算成功；不过就照常报失败，重投时把错误清单喂回去。
+      if (waitCode === 'NO_CHANGE' && typeof o.validateBatch === 'function') {
+        const verdict = await o.validateBatch(batch);
+        if (verdict && verdict.status === 0) {
+          if (o.onProgress) {
+            o.onProgress('分片 ' + batch.shard + ' 内容未变，但局部校验通过，按已完成计入');
+          }
+          return { ok: true, error: null, attempts: attempt, unchanged: true };
+        }
+      }
+      // provider 报错同理：只有**瞬时**错误值得再投一次。
+      // 限流 / 配额 / 空响应 → 重投可能好（dsh-llm/lib/index.js:238 RATE_LIMIT、
+      // :133 QUOTA、:143 EMPTY_RESPONSE）；
+      // 鉴权失败 / 上下文超限 / 未知错误 → 重投必然同样失败，直接报出去。
+      if (waitCode === 'TURN_ERROR' && !isTransientProviderCode(waited && waited.providerCode)) {
+        return { ok: false, error: lastError, attempts: attempt, code: waitCode };
+      }
+      attempt += 1;
+      continue;
+    }
+
+    const read = o.readShard(batch);
+    if (!read || read.ok !== true) {
+      lastError = (read && read.error) || '分片内容不是合法 JSON';
+      failures = [{ code: 'BATCH_SHARD_INVALID', path: batch.shard, message: lastError, hint: null }];
+      attempt += 1;
+      continue;
+    }
+
+    return { ok: true, error: null, attempts: attempt };
+  }
+
+  return { ok: false, error: lastError || '批次生成失败', attempts: attempt - 1, code: lastCode || null };
+}
+
+/**
+ * 按文件驱动整个阶段。
+ *
+ * 单个文件的流程：
+ *   1. 逐批生成（未通过校验的批次用错误清单回喂重投）
+ *   2. 合并该文件的全部分片 -> 目标文件
+ *   3. 插件跑校验脚本（判定权在脚本）
+ *   4. status != 0 -> 按 path 把错误归因回具体批次 -> 回到第 1 步
+ *   5. 轮次用尽 -> 该文件失败，带着完整错误清单上报
+ *
+ * @param {Object} opts
+ * @param {Array}  opts.files          文件列表 [{ file, type, template, batches }]
+ * @param {(batch, attempt, failures) => string} opts.buildPrompt
+ * @param {(prompt) => Promise<{ok: boolean, error?: string}>} opts.sendPrompt
+ * @param {(files) => Promise<{ok: boolean, reason?: string}>} opts.waitIdle
+ * @param {(batch) => {ok: boolean, error?: string}} opts.readShard
+ * @param {(file) => Promise<{ok: boolean, error?: string, layout?: Object}>} opts.applyFile
+ * @param {(file) => Promise<{status: number, errors: Array, warnings: Array}>} opts.validateFile
+ * @param {(errors, layout) => {byBatch: Object, unattributed: Array}} opts.attribute
+ * @param {(batch) => boolean} [opts.removeShard]
+ * @param {(batch) => boolean} [opts.adoptShard]
+ * @param {(msg: string) => void} [opts.onProgress]
+ * @param {number} [opts.maxAttempts]
+ * @param {number} [opts.maxFileRounds]
+ * @returns {Promise<Object>} 汇总报告
+ */
+export async function runStageBatches(opts) {
+  const o = opts || {};
+  // 校验粒度：
+  //   'file'  —— 每个文件生成完就单检（血肉：引用都指向骨架，单文件就能判）
+  //   'stage' —— 全部生成完再跑全量校验（节奏：章节号范围 / 覆盖率 / 重复
+  //              这些问题基本都是跨文件的，单文件查不出来）
+  //   'none'  —— 只生成，不校验（节奏的"时序基础"必须等细纲生成完才能全量判）
+  if (o.validateScope === 'stage') return runStageScope(o);
+  if (o.validateScope === 'none') return runNoneScope(o);
+  return runFileScope(o);
+}
+
+/**
+ * 阶段会话：跨多次调用保存批次状态。
+ *
+ * 节奏阶段需要分两次驱动：
+ *   1) 生成"章节规划 + 节奏参数 + 时序映射"（校验范围 'none'）
+ *   2) 读已合并的时序映射算出重点章，规划"章节细纲"的批次，再生成
+ *   3) 跑全量校验 + 归因重投（校验范围 'stage'）
+ * 第 2、3 步不能重跑第 1 步的批次，所以批次状态必须跨调用保留。
+ */
+export function createStageSession() {
+  return { state: new Map(), files: [], rounds: 0 };
+}
+
+/**
+ * 只生成不校验的一轮（节奏的"时序基础"）。
+ */
+async function runNoneScope(o) {
+  const session = o.session || createStageSession();
+  const files = o.files || [];
+  const maxAttempts = o.maxAttempts || STAGE_MAX_BATCH_ATTEMPTS;
+
+  const report = {
+    ok: true, error: null, files: [], failedFiles: [], batches: [],
+    errors: [], warnings: [], unattributed: [],
+    // 脚本/环境问题：单独存，不进重投队列（模型改不了）
+    infraErrors: [],
+    totalBatches: 0, totalRounds: 0
+  };
+
+  for (const file of files) {
+    const fileReport = {
+      file: file.file,
+      type: file.type,
+      ok: false,
+      rounds: 0,
+      batches: [],
+      errors: [],
+      warnings: [],
+      infraErrors: [],
+      error: null
+    };
+    report.files.push(fileReport);
+    for (const batch of file.batches) {
+      session.state.set(batch.key, session.state.get(batch.key) || { status: 'pending', errors: [], attempts: 0 });
+      report.totalBatches += 1;
+    }
+  }
+  rememberFiles(session, files);
+
+  for (const file of files) {
+    const fileReport = report.files.find((f) => f.file === file.file);
+    for (const batch of file.batches) {
+      const st = session.state.get(batch.key);
+      if (st.status === 'done') continue;
+      const gen = await generateBatch({
+        batch: batch,
+        failures: st.errors,
+        attempt: st.attempts + 1,
+        maxAttempts: st.attempts + maxAttempts,
+        buildPrompt: o.buildPrompt,
+        sendPrompt: o.sendPrompt,
+        waitIdle: o.waitIdle,
+        readShard: o.readShard,
+        removeShard: o.removeShard,
+        adoptShard: o.adoptShard,
+        onProgress: o.onProgress,
+        validateBatch: o.validateBatch
+      });
+      st.attempts = gen.attempts;
+      const batchReport = {
+        key: batch.key, file: batch.file, shard: batch.shard,
+        count: batch.count, attempts: gen.attempts, ok: gen.ok,
+        error: gen.error || null, code: gen.code || null
+      };
+      report.batches.push(batchReport);
+      if (fileReport) fileReport.batches.push(batchReport);
+      if (gen.ok) {
+        st.status = 'done';
+        st.errors = [];
+      } else {
+        st.status = 'failed';
+        st.errors = [{ code: 'BATCH_GENERATION_FAILED', path: batch.shard, message: gen.error || '批次生成失败', hint: null }];
+        report.ok = false;
+        report.error = '批次生成失败：' + batch.shard
+          + (gen.error ? '（' + (gen.code || 'BATCH_FAILED') + '：' + String(gen.error).slice(0, 80) + '）' : '');
+        report.failedFiles.push(batch.file);
+        if (fileReport) {
+          fileReport.error = report.error;
+          fileReport.rounds = 1;
+        }
+        return report;
+      }
+    }
+  }
+
+  // 生成完就把分片合并成目标文件（下一阶段要读）
+  for (const file of files) {
+    const fileReport = report.files.find((f) => f.file === file.file);
+    const merged = await o.applyFile(file);
+    if (!merged || merged.ok !== true) {
+      report.ok = false;
+      report.error = (merged && merged.error) || ('合并失败：' + file.file);
+      report.failedFiles.push(file.file);
+      if (fileReport) fileReport.error = report.error;
+      return report;
+    }
+    if (fileReport) fileReport.ok = true;
+  }
+
+  return report;
+}
+
+/**
+ * 把文件登记进会话（跨调用共享文件列表）。
+ *
+ * @returns {Array} 会话里累计的文件列表（跨多次调用）
+ */
+function rememberFiles(session, files) {
+  for (const f of files || []) {
+    if (!session.files.find((x) => x.file === f.file)) session.files.push(f);
+  }
+  return session.files;
+}
+
+/**
+ * 阶段级驱动：全部生成完 -> 全量校验 -> 跨文件归因 -> 只重投被点名的批次。
+ */
+async function runStageScope(o) {
+  const files = o.files || [];
+  const maxAttempts = o.maxAttempts || STAGE_MAX_BATCH_ATTEMPTS;
+  const maxFileRounds = o.maxFileRounds || STAGE_MAX_FILE_ROUNDS;
+  // 中途校验：每生成多少个批次做一次局部判（0 = 不做）
+  const checkpointEvery = o.checkpointEvery || 0;
+  let sinceCheckpoint = 0;
+  // 本轮 checkpoint 点名的批次（用于到上限时把点名写进报告）
+  let lastCheckpointHits = {};
+  // **本段**的批次（归因失败兜底只能动它们，不能动上一段已通过的）
+  const currentSegmentBatches = files.flatMap((f) => f.batches || []);
+  const session = o.session || createStageSession();
+
+  const report = {
+    ok: true,
+    error: null,
+    files: [],
+    failedFiles: [],
+    batches: [],
+    errors: [],
+    warnings: [],
+    unattributed: [],
+    // 脚本/环境问题：单独存，不进重投队列（模型改不了）
+    infraErrors: [],
+    totalBatches: 0,
+    totalRounds: 0
+  };
+
+  // 全量校验要覆盖**所有**文件（可能跨多次调用产生）
+  const allFiles = rememberFiles(session, files);
+  const state = session.state;
+  for (const f of files) {
+    for (const b of f.batches) {
+      if (!state.has(b.key)) state.set(b.key, { status: 'pending', errors: [], attempts: 0 });
+      report.totalBatches += 1;
+    }
+  }
+
+  // 每个文件一份小结（血肉的 buildFleshBatchNote 靠它统计批次数）
+  for (const f of allFiles) {
+    if (report.files.find((x) => x.file === f.file)) continue;
+    report.files.push({
+      file: f.file,
+      type: f.type,
+      ok: false,
+      rounds: 0,
+      batches: [],
+      errors: [],
+      warnings: [],
+      error: null
+    });
+  }
+  const fileReportOf = (file) => report.files.find((x) => x.file === file);
+
+  /**
+   * 中途校验：把已生成的批次局部合并 + 局部判一次。
+   *
+   * 存在的原因（tt5 实测）：关系+层级段 31 个批次连续派活、全部写完才判一次，
+   * 第 8 批写错行数要等 23 批都写完才发现。模型在没有反馈通道的那 31 轮里
+   * 自己造了 45 个检查脚本在猜判据。
+   *
+   * 为什么是"局部"而不是全量：中途文件还没写完，全量校验会误报
+   * （别的数组还缺 → REQUIRED；关系网还不全 → G_ISOLATED）。
+   * 局部模式只判当场可判的：模板子树 / 引用完整性 / 重复 / 自环 / 对称性 / 行数对账。
+   *
+   * @returns {boolean} true = 发现了问题，需要重启本轮生成
+   */
+  async function runCheckpoint() {
+    if (typeof o.applyPartial !== 'function' || typeof o.validatePartial !== 'function') return false;
+    // 先把**已定稿产物**用分片覆盖回去（见 index.js 的 restoreSettled）。
+    //
+    // 为什么必须做：模型可能被错误 hint 引导去改已经 PASSED 过的产物
+    // （tt5 实测 2026-10-25：QUOTA_MISMATCH 的 hint 说"或者把 quota 改成 28"，
+    // 模型就把 框架.json 改了 → 框架.json 与它的分片失配 →
+    // 错误从 3 条涨到 126 条 → 重投到上限 → 关系段 18 个分片没生成）。
+    //
+    // 分片才是真源（产物是分片合并出来的），所以用分片覆盖回去，
+    // 模型的越权修改就自动失效了 —— 不指望模型听话，脚本兜底。
+    if (typeof o.restoreSettled === 'function') {
+      try {
+        const restored = await o.restoreSettled();
+        if (restored && restored.length) {
+          report.errors.push({
+            code: 'SETTLED_PRODUCT_TAMPERED',
+            path: restored.join(','),
+            message: '模型改动了已定稿产物（' + restored.join('、') + '），已用分片覆盖回去',
+            hint: '模型只该写本轮的分片文件；已定稿的产物由分片决定，改了会被覆盖'
+          });
+          if (o.onProgress) {
+            o.onProgress('模型改动了已定稿产物（' + restored.join('、') + '），已用分片覆盖回去');
+          }
+        }
+      } catch (e) {
+        report.infraErrors.push({
+          code: 'RESTORE_SETTLED_FAILED',
+          path: '',
+          message: '恢复已定稿产物失败：' + String(e && e.message ? e.message : e),
+          hint: null
+        });
+      }
+    }
+    let hit = false;
+    // 只校验**本段**的文件，不能用 allFiles。
+    //
+    // allFiles 是跨段累积的（session 共享），到关系段时里面已经有
+    // 框架.json / 实体.json —— 它们早就 PASSED 了，拿它们做局部校验会误判：
+    //   - 框架.json 是纯对象结构，局部口径把它的顶层键当"数组名"传给 --arrays
+    //     → 4 条 [TYPE] capacity/input_snapshot/quota/derivations 假阳性；
+    //   - 假阳性被归因到框架批次 → 重投**已经通过**的框架，
+    //     模型把已定稿的 volume_ratio 改坏（tt5 实测 2026-10-25 00:00：
+    //     框架分片 mtime 变成 23:58，volume_ratio 被改，而框架.json 还是旧的），
+    //     关系段也跟着拖挂：写到 22/25 批就停，关系.json / 层级.json 没生成。
+    for (const file of files) {
+      // 整文件型产物（框架.json）没有数组，局部口径（--arrays）本来就不适用。
+      const hasArrayBatch = (file.batches || [])
+        .some((b) => b.wholeObject !== true && (b.arrays || []).length);
+      if (!hasArrayBatch) continue;
+      const part = await o.applyPartial(file);
+      if (!part || part.ok !== true) continue;
+      const arrays = part.writtenArrays || [];
+      if (!arrays.length) continue;
+      const v = await o.validatePartial(file, part);
+      const errs = (v && v.errors) || [];
+      if (!errs.length) continue;
+      const attr = o.attribute(errs, part.layout || {});
+      let marked = 0;
+      for (const batchKey of Object.keys(attr.byBatch || {})) {
+        const st = state.get(batchKey);
+        if (!st) continue;
+        st.status = 'pending';
+        st.errors = attr.byBatch[batchKey];
+        marked += 1;
+      }
+      if (!marked) continue;
+      hit = true;
+      lastCheckpointHits = attr.byBatch || {};
+      if (o.onProgress) {
+        o.onProgress('中途校验：' + file.file + ' 有 ' + errs.length + ' 条错，' + marked + ' 个批次要重写（' + arrays.join('、') + '）');
+      }
+    }
+    return hit;
+  }
+
+  for (let round = 1; round <= maxFileRounds; round++) {
+    report.totalRounds += 1;
+    for (const f of allFiles) {
+      const fr = fileReportOf(f.file);
+      if (fr) fr.rounds = round;
+    }
+
+    // ---- 1. 生成所有还没通过的批次 ----
+    let generationFailed = false;
+    // 中途校验（checkpoint）：每生成 checkpointEvery 个批次就局部判一次。
+    // 发现问题就把被点名的批次标回 pending 并**重启本轮生成** ——
+    // 那个批次会在剩余批次之前被重写，错误不会拖到整段写完才暴露。
+    let restartGeneration = true;
+    // 重启**必须有上限**：中途校验一次点名 ≥ checkpointEvery 个批次时，
+    // 这些批次会被标回 pending → 重写 → 又攒够 checkpointEvery 个 → 再被点名
+    // → 无限循环、无限烧额度、命令永不返回（实测：点名 8 个批次就不收敛）。
+    let restarts = 0;
+    while (restartGeneration) {
+      if (restarts >= MAX_CHECKPOINT_RESTARTS) {
+        // 到上限就停：把这一轮的点名写进报告，让用户看得见"哪几个批次反复不过"
+        for (const batchKey of Object.keys(lastCheckpointHits || {})) {
+          const st = state.get(batchKey);
+          if (!st) continue;
+          st.status = 'pending';
+          st.errors = lastCheckpointHits[batchKey];
+        }
+        report.errors.push({
+          code: 'CHECKPOINT_RESTART_LIMIT',
+          path: '',
+          message: '中途校验反复点名同一批批次，已停止重启（第 ' + MAX_CHECKPOINT_RESTARTS + ' 次）',
+          hint: '这些批次连续几轮校验都没过，请直接看下面的错误清单'
+        });
+        if (o.onProgress) {
+          o.onProgress('中途校验重启次数达上限（' + MAX_CHECKPOINT_RESTARTS + ' 次），停止重启');
+        }
+        break;
+      }
+      restarts += 1;
+      restartGeneration = false;
+      for (const file of allFiles) {
+        for (const batch of file.batches) {
+          const st = state.get(batch.key);
+          // allFiles 是跨段累积的，state 里可能没有对应条目（上一段登记过文件
+          // 但批次还没进 state）—— 不能直接读 st.status，会 TypeError。
+          if (!st) continue;
+          if (st.status === 'done') continue;
+          const gen = await generateBatch({
+            batch: batch,
+            failures: st.errors,
+            attempt: st.attempts + 1,
+            maxAttempts: st.attempts + maxAttempts,
+            buildPrompt: o.buildPrompt,
+            sendPrompt: o.sendPrompt,
+            waitIdle: o.waitIdle,
+            readShard: o.readShard,
+            removeShard: o.removeShard,
+            adoptShard: o.adoptShard,
+            onProgress: o.onProgress,
+            validateBatch: o.validateBatch
+          });
+          st.attempts = gen.attempts;
+          const batchReport = {
+            key: batch.key,
+            file: batch.file,
+            shard: batch.shard,
+            count: batch.count,
+            attempts: gen.attempts,
+            ok: gen.ok,
+            // 失败原因必须带出来：只写分片名的话，用户分不清是超时、
+            // 被中断、分片没落盘还是 JSON 非法（失败必须可见）。
+            error: gen.error || null,
+            code: gen.code || null
+          };
+          report.batches.push(batchReport);
+          const fr = fileReportOf(batch.file);
+          if (fr) fr.batches.push(batchReport);
+          if (gen.ok) {
+            st.status = 'done';
+            st.errors = [];
+          } else {
+            st.status = 'failed';
+            st.errors = [{ code: 'BATCH_GENERATION_FAILED', path: batch.shard, message: gen.error || '批次生成失败', hint: null }];
+            generationFailed = true;
+            break;
+          }
+          // ---- 中途校验点 ----
+          if (checkpointEvery > 0) {
+            sinceCheckpoint += 1;
+            if (sinceCheckpoint >= checkpointEvery) {
+              sinceCheckpoint = 0;
+              const hit = await runCheckpoint();
+              if (hit) restartGeneration = true;
+            }
+          }
+          if (restartGeneration) break;
+        }
+        if (generationFailed || restartGeneration) break;
+      }
+    }
+
+    if (generationFailed) {
+      const failed = report.batches.filter((b) => !b.ok).map((b) => b.shard);
+      // 带上每个失败批次的原因（截断，避免刷屏）：
+      // 只写分片名的话，用户分不清是超时、被中断、分片没落盘还是 JSON 非法。
+      const why = report.batches
+        .filter((b) => !b.ok && b.error)
+        .slice(0, 3)
+        .map((b) => b.shard + '（' + (b.code || 'BATCH_FAILED') + '：' + String(b.error).slice(0, 80) + '）')
+        .join('；');
+      report.error = '批次生成失败：' + failed.join('、') + (why ? ' —— ' + why : '');
+      report.ok = false;
+      for (const b of report.batches.filter((x) => !x.ok)) {
+        const fr = fileReportOf(b.file);
+        if (fr) fr.error = '批次生成失败：' + b.shard;
+      }
+      break;
+    }
+
+    // ---- 2. 合并全部分片（所有文件，含之前调用生成的） ----
+    const layouts = {};
+    let mergeFailed = false;
+    // 行归属越界（ownerField 不在本批实体里）——
+    // 这是"每批写哪些行"的代码级保证：模型写串行时立刻能发现，
+    // 而不是等合并后被校验器报一个说不清来源的 ID_DUP。
+    const ownershipErrors = [];
+    for (const file of allFiles) {
+      const merged = await o.applyFile(file);
+      if (!merged || merged.ok !== true) {
+        report.error = (merged && merged.error) || ('合并失败：' + file.file);
+        report.ok = false;
+        mergeFailed = true;
+        const fr = fileReportOf(file.file);
+        if (fr) fr.error = report.error;
+        break;
+      }
+      layouts[file.file] = merged.layout || {};
+      for (const v of (merged.ownershipViolations || [])) {
+        ownershipErrors.push(v);
+      }
+    }
+    if (mergeFailed) break;
+
+    // ---- 3. 阶段级全量校验（判定权在脚本） ----
+    const v = await o.validateStage(allFiles, layouts);
+    const errors = (v && v.errors) || [];
+    const warnings = (v && v.warnings) || [];
+    // 合并而不是覆盖：**结构性**提示（中途校验重启上限、模型越权改了已定稿产物…）
+    // 不能被本轮校验错误冲掉（否则用户看不到"为什么停了"）。
+    // 这里保留 report.errors 里的**全部**条目 —— 它们都是驱动层自己记的，
+    // 不是校验器的内容错误；以前只留 CHECKPOINT_RESTART_LIMIT 一条，
+    // 其余插件级错误会被静默吞掉（失败不可见）。
+    report.errors = errors.concat(report.errors || []);
+    report.warnings = warnings;
+    // 脚本/环境问题（词表读不到 / 部署缺文件 / 参数错 …）不是产物内容的问题，
+    // 甩给模型没用（提示词禁止模型改 references/），重投多少次都一样。
+    // 所以把它们单独挑出来：进报告，但不进重投队列。
+    const split = classifyIssues(errors);
+    for (const e of split.infra) report.infraErrors.push(e);
+    // fileStatus 是"逐文件结论"（{ 文件名: status }）：
+    // 阶段级校验把多个文件的错误混在一起返回，但下游段只关心
+    // 自己依赖的那个文件过没过（比如时序映射只依赖节奏参数）。
+    const fileStatus = (v && v.fileStatus) || null;
+    for (const f of allFiles) {
+      const fr = fileReportOf(f.file);
+      if (!fr) continue;
+      fr.errors = errors;
+      fr.warnings = warnings;
+      if (fileStatus && fileStatus[f.file] !== undefined) {
+        fr.ok = fileStatus[f.file] === 0;
+      }
+    }
+
+    // 归属越界也算这一轮没过：校验器可能根本查不出来（它只看最终文件），
+    // 但产物结构是错的（同一行可能被两个批次各写一次）。
+    if (ownershipErrors.length) {
+      report.errors = errors.concat(ownershipErrors, report.errors || []);
+      report.ok = false;
+      if (o.onProgress) {
+        o.onProgress('有 ' + ownershipErrors.length + ' 行的归属字段不在本批实体里，需要重写对应批次');
+      }
+    }
+
+    if (v && v.status === 0 && !ownershipErrors.length) {
+      report.ok = true;
+      for (const f of allFiles) {
+        const fr = fileReportOf(f.file);
+        if (fr) { fr.ok = true; fr.error = null; }
+      }
+      break;
+    }
+
+    // 校验没过：这一轮的结果就是"没通过"，不能留着 ok=true 装作成功。
+    // （血肉的 runFileScope 是按文件置 ok 的，阶段级这里必须同样置 false。）
+    report.ok = false;
+
+    // 只有内容错误才值得重投。没有内容错误 = 没过是脚本自己的问题，
+    // 重投模型改不动（也不该让它改），直接停下来报错。
+    if (!split.content.length && !ownershipErrors.length) {
+      report.error = describeInfraIssues(split.infra) || '校验没通过，但没有产物内容错误';
+      break;
+    }
+
+    // ---- 4. 跨文件归因 -> 标记要重跑的批次 ----
+    // 归属越界也进归因队列：它带的 batchKey 就是该重写的批次
+    // （path 形如 "character_relations[3].from"，归因会落到写下标那一行的批次）。
+    const contentErrors = split.content.concat(ownershipErrors);
+    const attr = o.attribute(contentErrors, mergeLayouts(layouts));
+    // 归因不到的错误必须留在报告里：它们既没进任何批次，
+    // 也不会被重投修掉，只能让人看见（失败必须可见）。
+    //
+    // **累积而不是覆盖**：每轮都留。早先只留最后一轮，结果 tt5 骨架
+    // 第 1 轮归不了的一批错（15 条 NAME_DUP）在最终报告里整个消失了 ——
+    // 报告只显示最后一轮的 1 条，看起来像"就这 1 条没归因"。
+    // 累积时按 code+path 去重：同一条错在多轮重复出现只算一条。
+    report.unattributed = mergeUnattributed(report.unattributed, attr.unattributed);
+    let marked = 0;
+    for (const batchKey of Object.keys(attr.byBatch || {})) {
+      const st = state.get(batchKey);
+      if (!st) continue;
+      st.status = 'pending';
+      st.errors = attr.byBatch[batchKey];
+      marked += 1;
+    }
+    let attributionFailed = false;
+    if (marked === 0) {
+      // 一条都归不了：只能整阶段重跑，否则错误永远留在原地。
+      //
+      // 代价很大（tt5 骨架实测）：同一份错误会发给**所有**批次，
+      // 框架那种整文件批次也会收到"改某个实体数组"的指令，模型去改
+      // 根本不属于它的批次 —— 白烧额度，还可能引入新错（实测第 3 轮
+      // 重写 climaxes 时编出了重复 ID）。
+      // 所以归因函数必须尽量归准（见 stage-batches.js 的形态六）；
+      // 这里只负责兜底 + 把"归因失败"这件事说清楚。
+      attributionFailed = true;
+      const unattributed = (attr.unattributed && attr.unattributed.length) ? attr.unattributed : contentErrors;
+      // 只兜底**本段**的批次：state 是跨段共享的（骨架三段共用一个 session），
+      // 遍历 state.values() 会把上一段已经 PASSED 的批次也标回 pending ——
+      // 下一轮就会重投已定稿的产物，模型把定稿改坏（tt5 实测 2026-10-25：
+      // 框架分片被改写，框架.json 与分片对不上）。
+      for (const batch of currentSegmentBatches) {
+        const st = state.get(batch.key);
+        if (!st) continue;
+        st.status = 'pending';
+        st.errors = unattributed;
+        marked += 1;
+      }
+    }
+    if (o.onProgress) {
+      o.onProgress('第 ' + round + ' 轮校验未通过，' + marked + ' 个批次需要重跑'
+        + (attributionFailed
+          ? '（错误归不到具体批次，只能整阶段重跑：' + contentErrors.length + ' 条错会发给每个批次）'
+          : ''));
+    }
+  }
+
+  if (!report.ok && !report.error) {
+    report.error = '阶段在 ' + maxFileRounds + ' 轮内未通过校验';
+  }
+  return report;
+}
+
+/**
+ * 累积"归因不到批次"的错误，按 code+path 去重。
+ *
+ * 为什么累积：报告只显示最后一轮的话，早先轮次里归不了的错会凭空消失
+ * （tt5 骨架：第 1 轮 15 条 NAME_DUP 归不了，最终报告里一条都没有）。
+ * 失败必须可见 —— 归因失败本身就是需要人看的问题。
+ *
+ * @param {Array} prev - 之前累积的
+ * @param {Array} next - 本轮的
+ * @returns {Array}
+ */
+function mergeUnattributed(prev, next) {
+  const out = Array.isArray(prev) ? prev.slice() : [];
+  const seen = new Set(out.map((e) => (e && e.code ? e.code : '') + '|' + (e && e.path ? e.path : '')));
+  for (const e of (Array.isArray(next) ? next : [])) {
+    const k = (e && e.code ? e.code : '') + '|' + (e && e.path ? e.path : '');
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(e);
+  }
+  return out;
+}
+
+/**
+ * 把多个文件的 layout 合成一张表（跨文件归因用）。
+ * 数组键在血肉/节奏里都不重名，所以直接合。
+ */
+function mergeLayouts(layouts) {
+  const merged = { __arrays: {}, __byName: {}, __declared: {} };
+  for (const key of Object.keys(layouts || {})) {
+    const layout = layouts[key] || {};
+    for (const arrayKey of Object.keys(layout)) {
+      if (arrayKey === '__arrays' || arrayKey === '__byName' || arrayKey === '__whole' || arrayKey === '__declared') {
+        if (layout[arrayKey]) merged[arrayKey] = Object.assign(merged[arrayKey] || {}, layout[arrayKey]);
+        continue;
+      }
+      if (!Array.isArray(layout[arrayKey])) continue;
+      merged[arrayKey] = (merged[arrayKey] || []).concat(layout[arrayKey]);
+    }
+  }
+  return merged;
+}
+
+async function runFileScope(o) {
+  const files = o.files || [];
+  const maxAttempts = o.maxAttempts || STAGE_MAX_BATCH_ATTEMPTS;
+  const maxFileRounds = o.maxFileRounds || STAGE_MAX_FILE_ROUNDS;
+
+  const report = {
+    ok: true,
+    error: null,
+    files: [],
+    failedFiles: [],
+    errors: [],
+    warnings: [],
+    unattributed: [],
+    // 脚本/环境问题：单独存，不进重投队列（模型改不了）
+    infraErrors: [],
+    totalBatches: 0,
+    totalRounds: 0
+  };
+
+  for (const file of files) {
+    const fileReport = {
+      file: file.file,
+      type: file.type,
+      ok: false,
+      rounds: 0,
+      batches: [],
+      errors: [],
+      warnings: [],
+      infraErrors: [],
+      error: null
+    };
+    report.files.push(fileReport);
+    report.totalBatches += file.batches.length;
+
+    // batchKey -> { status, errors, attempts }
+    // attempts 是这个批次**累计**被投递过几次：文件级重跑时必须接着上次继续数，
+    // 否则提示词里的"第 N 次"会重置，模型不知道自己已经错过几轮。
+    const state = new Map();
+    for (const b of file.batches) state.set(b.key, { status: 'pending', errors: [], attempts: 0 });
+
+    let finished = false;
+    // 本文件累计"归因不到批次"的错误（跨轮累积，按 code+path 去重）。
+    // 每个文件各记各的：不同文件里 code+path 相同的是两条不同的错。
+    let fileUnattributed = [];
+
+    for (let round = 1; round <= maxFileRounds && !finished; round++) {
+      fileReport.rounds = round;
+      report.totalRounds += 1;
+
+      // ---- 1. 逐批生成 ----
+      let generationFailed = false;
+      for (const batch of file.batches) {
+        const st = state.get(batch.key);
+        if (!st) continue;
+        if (st.status === 'done') continue;
+
+        const gen = await generateBatch({
+          batch: batch,
+          failures: st.errors,
+          attempt: st.attempts + 1,
+          maxAttempts: st.attempts + maxAttempts,
+          buildPrompt: o.buildPrompt,
+          sendPrompt: o.sendPrompt,
+          waitIdle: o.waitIdle,
+          readShard: o.readShard,
+          removeShard: o.removeShard,
+          adoptShard: o.adoptShard,
+          onProgress: o.onProgress,
+          validateBatch: o.validateBatch
+        });
+        st.attempts = gen.attempts;
+
+        fileReport.batches.push({
+          key: batch.key,
+          shard: batch.shard,
+          count: batch.count,
+          attempts: gen.attempts,
+          ok: gen.ok
+        });
+
+        if (gen.ok) {
+          st.status = 'done';
+          st.errors = [];
+        } else {
+          st.status = 'failed';
+          st.errors = [{ code: 'BATCH_GENERATION_FAILED', path: batch.shard, message: gen.error || '批次生成失败', hint: null }];
+          generationFailed = true;
+          break;
+        }
+      }
+
+      if (generationFailed) {
+        const failedShards = file.batches
+          .filter((b) => {
+            const st = state.get(b.key);
+            return st && st.status === 'failed';
+          })
+          .map((b) => b.shard);
+        fileReport.error = '批次生成失败：' + failedShards.join('、');
+        report.failedFiles.push(fileReport.file);
+        break;
+      }
+
+      // ---- 2. 合并 ----
+      const applied = await o.applyFile(file);
+      if (!applied || applied.ok !== true) {
+        fileReport.error = (applied && applied.error) || '分片合并失败';
+        report.failedFiles.push(fileReport.file);
+        break;
+      }
+
+      // ---- 3. 校验（判定权在脚本） ----
+      const v = await o.validateFile(file);
+      const errors = (v && v.errors) || [];
+      const warnings = (v && v.warnings) || [];
+      fileReport.errors = errors;
+      fileReport.warnings = warnings;
+      // 脚本/环境问题不是产物内容的问题：不进重投队列（模型改不了，
+      // 提示词也禁止模型改 references/），单独记进报告。
+      const split = classifyIssues(errors);
+      fileReport.infraErrors = split.infra;
+      for (const e of split.infra) report.infraErrors.push(e);
+
+      if (v && v.status === 0) {
+        fileReport.ok = true;
+        finished = true;
+        break;
+      }
+
+      // 只有内容错误才值得重投。没有内容错误 = 没过是脚本自己的问题，
+      // 重投模型改不动，直接停下来报错。
+      if (!split.content.length) {
+        fileReport.error = describeInfraIssues(split.infra) || '校验没通过，但没有产物内容错误';
+        report.failedFiles.push(fileReport.file);
+        report.error = fileReport.error;
+        break;
+      }
+
+      // ---- 4. 归因 -> 标记要重跑的批次 ----
+      const attr = o.attribute(split.content, applied.layout || {});
+      const byBatch = attr.byBatch || {};
+      // 归因不到的错误必须留在报告里：它们既没进任何批次，
+      // 也不会被重投修掉，只能让人看见（失败必须可见）。
+      //
+      // 累积而不是覆盖：早先轮次里归不了的错不能凭空消失
+      // （tt5 骨架：第 1 轮 15 条 NAME_DUP 归不了，最终报告里一条都没有）。
+      //
+      // 去重范围是**本文件**：不同文件里 code+path 相同的错是两条不同的错，
+      // 一起去重会少报（所以只把本轮新增的并进总报告）。
+      const cumUnattributed = mergeUnattributed(fileUnattributed, attr.unattributed);
+      const freshUnattributed = cumUnattributed.slice(fileUnattributed.length);
+      fileUnattributed = cumUnattributed;
+      fileReport.unattributed = cumUnattributed;
+      for (const e of freshUnattributed) report.unattributed.push(e);
+      let marked = 0;
+      for (const batchKey of Object.keys(byBatch)) {
+        const st = state.get(batchKey);
+        if (!st) continue;
+        st.status = 'pending';
+        st.errors = byBatch[batchKey];
+        marked += 1;
+      }
+      let attributionFailed = false;
+
+      if (marked === 0) {
+        // 一条都归因不到（跨文件错误 / 全量口径的错误）：
+        // 只能整份文件重跑，否则错误永远留在原地。
+        //
+        // 代价（tt5 骨架实测）：同一份错误会发给**这个文件的所有批次**，
+        // 模型去改根本不属于它的批次 —— 白烧额度，还可能引入新错。
+        // 所以归因函数必须尽量归准（见 stage-batches.js 的形态六）。
+        attributionFailed = true;
+        const unattributed = (attr.unattributed && attr.unattributed.length)
+          ? attr.unattributed
+          : split.content;
+        for (const batch of file.batches) {
+          const st = state.get(batch.key);
+          if (!st) continue;
+          st.status = 'pending';
+          st.errors = unattributed;
+          marked += 1;
+        }
+      }
+
+      if (o.onProgress) {
+        o.onProgress(file.file + ' 第 ' + round + ' 轮校验未通过，' + marked + ' 个批次需要重跑'
+          + (attributionFailed
+            ? '（错误归不到具体批次，只能整份重跑：' + split.content.length + ' 条错会发给每个批次）'
+            : ''));
+      }
+    }
+
+    if (!fileReport.ok && !fileReport.error) {
+      fileReport.error = '文件在 ' + maxFileRounds + ' 轮内未通过校验';
+      report.failedFiles.push(fileReport.file);
+    }
+    if (!fileReport.ok) report.ok = false;
+  }
+
+  if (!report.ok && !report.error) {
+    // 优先说清楚"为什么失败"（批次生成失败比"没过校验"更有指向性）
+    const reasons = (report.files || [])
+      .filter((f) => !f.ok && f.error)
+      .map((f) => f.file + '：' + f.error);
+    report.error = reasons.length
+      ? reasons.join('；')
+      : '有文件未通过校验：' + report.failedFiles.join('、');
+  }
+  return report;
+}
+
+/**
+ * 造一个"认领写歪了的分片"的函数：
+ * 模型把内容写到了 buildDir 下另一个 json 文件名上时，
+ * 如果只多出一个候选，就把它改名成期望的分片名。
+ *
+ * knownShards 每次调用时**重新读取**（而不是建函数时拍快照）：
+ * 节奏阶段是分三段驱动的，第三段的批次是后加进这个列表的，
+ * 拍快照会让第三段自己刚写出来的分片被当成"多出来的候选"。
+ *
+ * @param {string} buildDir 分片目录
+ * @param {Array} knownShards 全部批次的分片名（用于排除已知文件）
+ * @returns {(batch) => boolean}
+ */
+export function makeShardAdopter(buildDir, knownShards) {
+  return function adoptShard(batch) {
+    const known = new Set(knownShards || []);
+    const expected = join(buildDir, batch.shard);
+    if (existsSync(expected)) return false;
+    let entries = [];
+    try {
+      entries = readdirSync(buildDir);
+    } catch (e) {
+      return false;
+    }
+    const candidates = entries.filter((f) => f.endsWith('.json') && !known.has(f));
+    if (candidates.length !== 1) return false;
+    try {
+      renameSync(join(buildDir, candidates[0]), expected);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  };
+}
+