@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/plugins/fancy-story-builder/scripts/stage-batches.js

@@ -0,0 +1,1371 @@
+/**
+ * stage-batches.js  v2.0
+ * 阶段批次规划器 + 分片合并器 + 校验错误归因器（血肉 / 节奏共用）。
+ *
+ * 设计要点：
+ * - 一次性派活整个阶段（血肉真实规模 340KB、节奏细纲 320-480KB）会超出
+ *   单回合输出预算。2026-10 tt5 实测：结局.json 写到一半被 provider 中断
+ *   （output new_sensitive 1027），且因为全量校验从未跑过，失败对用户完全不可见。
+ *   所以改成"插件逐批派活"。
+ * - 每一批让模型只写一个**分片**文件（纯生成，不读改写），插件负责把分片
+ *   合并成最终产物。合并是幂等的：目标文件始终由全部分片重新合成，
+ *   因此"重投某一批"只需要重写那一个分片。
+ * - 校验由插件侧调校验脚本完成（脚本判定通过与否），
+ *   错误按 path 归因回具体批次，只重投有问题的批次。
+ *
+ * 三类条目来源：
+ *   byChapter   —— 按章号切（节奏的章节规划 / 章节细纲 / hook_timeline）
+ *   source      —— 按骨架实体切（角色 / 冲突 / 伏笔 / 高潮 / 爽点 …）
+ *   quotaDriven —— 条数由本阶段框架.json 的 quota 决定（骨架阶段的实体清单）
+ *
+ * 本模块不依赖 dsh 运行时：只做文件 IO 与纯计算，可直接用测试夹具驱动。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { quotaCountsByArray, readQuota, getNested } from './skeleton-quota.js';
+
+// ============================================================
+// 常量
+// ============================================================
+
+// 单批目标字节上限。单回合输出预算是硬约束，批次必须远小于它。
+export const DEFAULT_MAX_BYTES_PER_BATCH = 40 * 1024;
+
+// 单批条目数上限：即使估算失真，也不允许一批产出过多条目。
+export const DEFAULT_MAX_ITEMS_PER_BATCH = 12;
+
+// 每个模板字段的估算字节数（正文中文 UTF-8 约 3 字节/字，一个字段约 60-80 字）。
+// 这是估算值，只用于决定"切几批"，不影响正确性。
+export const BYTES_PER_FIELD = 200;
+
+// 血肉阶段分片目录名（放在血肉目录下，校验器只扫顶层 .json，不会碰到子目录）
+export const SHARD_DIR_NAME = '.flesh-build';
+
+// 节奏阶段分片目录名
+export const RHYTHM_SHARD_DIR_NAME = '.rhythm-build';
+
+// 骨架阶段的分片目录。
+// 骨架的分片目录跟血肉/节奏同名会互相覆盖 —— 三个阶段的产物在同一个项目目录下。
+export const SKELETON_SHARD_DIR_NAME = '.skeleton-build';
+
+// ============================================================
+// 血肉 8 个文件的规格
+// ============================================================
+
+/**
+ * 每个文件由若干"数组组"（group）组成。
+ * 一个 group = 一批条目的来源 + 它要写进哪些顶层数组。
+ *   key       —— 顶层数组名（血肉模板 structure.properties 的键）
+ *   source    —— 骨架 实体.json 里的数组名
+ *   category  —— 该组只取骨架实体里 category 等于此值的条目
+ *   detail    —— 与本组条目一一对应的详情数组名（关键道具的 details）
+ *   free      —— 无骨架来源，由模型自主生成（条数由 count 决定）
+ */
+export const FLESH_FILE_SPECS = [
+  {
+    type: '角色',
+    file: '角色.json',
+    template: '角色模板.json',
+    groups: [
+      { key: 'characters', source: 'characters' }
+    ]
+  },
+  {
+    type: '冲突',
+    file: '冲突.json',
+    template: '冲突模板.json',
+    groups: [
+      { key: 'conflicts', source: 'conflicts' }
+    ]
+  },
+  {
+    type: '势力',
+    file: '势力.json',
+    template: '势力模板.json',
+    groups: [
+      { key: 'factions', source: 'factions' }
+    ]
+  },
+  {
+    type: '剧情',
+    file: '剧情.json',
+    template: '剧情模板.json',
+    groups: [
+      { key: 'main_lines', source: 'main_lines' },
+      { key: 'branches', source: 'branches' }
+    ]
+  },
+  {
+    type: '地点',
+    file: '地点.json',
+    template: '地点模板.json',
+    groups: [
+      { key: 'locations', source: 'locations' }
+    ]
+  },
+  {
+    type: '结局',
+    file: '结局.json',
+    template: '结局模板.json',
+    groups: [
+      { key: 'endings', source: 'endings' }
+    ]
+  },
+  {
+    type: '世界观规则',
+    file: '世界观规则.json',
+    template: '世界观规则模板.json',
+    groups: [
+      { key: 'core_rules', source: 'world_rules', category: '核心规则' },
+      { key: 'information_rules', source: 'world_rules', category: '信息规则' },
+      { key: 'social_rules', source: 'world_rules', category: '社会规则' },
+      { key: 'rule_conflict_plan', free: true, count: 5 }
+    ]
+  },
+  {
+    type: '关键道具',
+    file: '关键道具.json',
+    template: '关键道具模板.json',
+    groups: [
+      { key: 'core_items', source: 'items', category: '核心道具', detail: 'details' },
+      { key: 'branch_items', source: 'items', category: '支线道具', detail: 'details' },
+      { key: 'symbolic_items', source: 'items', category: '象征道具', detail: 'details' }
+    ]
+  }
+];
+
+// ============================================================
+// 骨架 4 个文件的规格
+// ============================================================
+
+/**
+ * 骨架阶段的条目来源比血肉/节奏多一类：
+ *   quotaDriven —— 条数由**本阶段自己产出的** `框架.json` 的 quota 决定。
+ *
+ * 骨架是第一个阶段，没有上游可读，实体条数只能由框架的配额推出来：
+ *   quota.character_counts.protagonist = 2  →  characters 里要有 2 个 type=主角
+ *   quota.conflict_counts.core = 3         →  conflicts 里要有 3 个 type=核心
+ * 校验器按同一张映射表核对（QUOTA_MISMATCH），所以批次规模也按它来。
+ *
+ * 这带来一个**段间依赖**：实体批次必须等框架.json 产出并合并后才知道规模，
+ * 所以骨架阶段是三段驱动（框架 → 实体 → 关系+层级）。
+ *
+ * 其余两类与血肉/节奏同构：
+ *   source      —— 按已产出的实体切（关系 / 层级的 span）
+ *   wholeObject —— 整个文件就是一个对象（框架.json），只有一批
+ */
+export const SKELETON_FILE_SPECS = [
+  {
+    type: '框架',
+    file: '框架.json',
+    template: '框架模板.json',
+    groups: [
+      { key: null, wholeObject: true, maxItems: 1 }
+    ]
+  },
+  {
+    type: '实体',
+    file: '实体.json',
+    template: '实体模板.json',
+    groups: [
+      { key: 'characters', quotaDriven: true, maxItems: 20 },
+      { key: 'conflicts', quotaDriven: true, maxItems: 20 },
+      { key: 'factions', quotaDriven: true, maxItems: 20 },
+      { key: 'locations', quotaDriven: true, maxItems: 20 },
+      { key: 'items', quotaDriven: true, maxItems: 20 },
+      { key: 'endings', quotaDriven: true, maxItems: 20 },
+      { key: 'foreshadows', quotaDriven: true, maxItems: 20 },
+      { key: 'climaxes', quotaDriven: true, maxItems: 20 },
+      { key: 'pleasures', quotaDriven: true, maxItems: 20 },
+      { key: 'world_rules', quotaDriven: true, maxItems: 20 },
+      { key: 'main_lines', quotaDriven: true, maxItems: 20 },
+      { key: 'branches', quotaDriven: true, maxItems: 20 }
+    ]
+  },
+  {
+    type: '关系',
+    file: '关系.json',
+    template: '关系模板.json',
+    groups: [
+      // 每组按"关系指向哪类实体"切：模型只需要看到自己这批实体的 id + name，
+      // 不必读整份实体清单（344 个实体全塞进提示词会撑爆单轮预算）。
+      //
+      // refs = 这组要填的**别类**实体的 id（引用完整性校验会逐条查这些 id 存不存在）：
+      //   冲突参与要填角色 id，道具归属要填角色/势力 id ……
+      //
+      // ownerField = 这条关系"归属给谁"的字段：值落在本批源实体里的行归本批管。
+      //   它让"每批写哪些行"有唯一定义（不重不漏），
+      //   分片合并时不会因为两个批次都写了同一行而报 ID_DUP。
+      //
+      // rows = 这个数组的**行数口径**（tt5 实测踩过的坑，见下方三种模式）：
+      //   perEntity —— 每个源实体恰好一行，行数 = 源实体数。
+      //     （冲突参与方、支线主角、道具归属、地点冲突、结局角色、支线挂主线）
+      //   semantic —— 行数由关系本身决定，**不预设**。提示词不能说"写 N 条"。
+      //     （角色关系：两个角色之间有几条关系是剧情决定的；
+      //       势力成员：一个角色可以属于多个势力）
+      //   quota    —— 行数由框架 quota 决定，精确值。
+      //     （势力关系：一个无向对要存成 A→B 与 B→A 两行，
+      //       所以行数 = quota.faction_relation_count * 2，跟势力个数无关）
+      //
+      //   以前这三类一律按"源实体数 = 行数"处理，提示词统一写
+      //   "本批要写的条目（N 条）… 每行一条"。后果（tt5 实测）：
+      //     · faction_relations 提示词说 8 条 → 模型写 8 行 → 校验器要 24 行
+      //       → 白跑 23 批才返工一次；
+      //     · main_line_branch_relation 按主线切（只有 1 条主线）→ 提示词说 1 条
+      //       → 模型写 1 行 → 10 条支线里 9 条静默没挂主线，校验器还不报。
+      { key: 'character_relations', source: 'characters', ownerField: 'from', refs: ['characters'], rows: 'semantic', maxItems: 8 },
+      { key: 'faction_membership', source: 'factions', ownerField: 'faction', refs: ['characters', 'factions'], rows: 'semantic', maxItems: 8 },
+      { key: 'faction_relations', source: 'factions', ownerField: 'from', refs: ['factions'], rows: 'quota', quotaPath: 'faction_relation_count', multiplier: 2, maxItems: 8 },
+      { key: 'conflict_participants', source: 'conflicts', ownerField: 'conflict', refs: ['conflicts', 'characters'], rows: 'perEntity', maxItems: 8 },
+      { key: 'branch_protagonist', source: 'branches', ownerField: 'branch', refs: ['branches', 'characters'], rows: 'perEntity', maxItems: 8 },
+      { key: 'item_owner', source: 'items', ownerField: 'item', refs: ['items', 'characters', 'factions'], rows: 'perEntity', maxItems: 8 },
+      { key: 'location_conflict', source: 'locations', ownerField: 'location', refs: ['locations', 'conflicts'], rows: 'perEntity', maxItems: 8 },
+      { key: 'ending_character', source: 'endings', ownerField: 'ending', refs: ['endings', 'characters'], rows: 'perEntity', maxItems: 8 },
+      // 一行代表"一条支线挂到主线上" → 源实体必须是**支线**（不是主线）。
+      // 按主线切会只写主线条数那一行，其余支线一个都挂不上。
+      { key: 'main_line_branch_relation', source: 'branches', ownerField: 'branch', refs: ['main_lines', 'branches'], rows: 'perEntity', maxItems: 8 }
+    ]
+  },
+  {
+    type: '层级',
+    file: '层级.json',
+    template: '层级模板.json',
+    groups: [
+      // 卷数 = quota.volume_count（校验器拿层级自己的 volumes 长度跟它对账）
+      { key: 'volumes', quotaDriven: true, quotaPath: 'volume_count', maxItems: 20 },
+      // 幕数没有配额字段（校验器只查同卷内 act_index 不重复），
+      // 按每卷 3 幕估规模；模型实际写多少都合法。
+      { key: 'acts', quotaDriven: true, quotaPath: 'volume_count', multiplier: 3, maxItems: 30 },
+      { key: 'main_line_span', source: 'main_lines', ownerField: 'main_line', maxItems: 8 },
+      { key: 'branch_span', source: 'branches', ownerField: 'branch', maxItems: 12 }
+    ]
+  }
+];
+
+// ============================================================
+// 节奏 4 个文件的规格
+// ============================================================
+
+/**
+ * 节奏阶段的条目来源分三类：
+ *   byChapter   —— 按章号 1..T 切（章节规划 / 章节细纲 / hook_timeline）
+ *   source      —— 按骨架实体切（角色 / 冲突 / 伏笔 / 高潮 / 爽点 / 主线 / 支线 /
+ *                  地点 / 道具 / 结局）
+ *   wholeObject —— 整个文件就是一个对象（节奏参数.json），只有一批
+ *
+ * bytesPerItem 是每条的估算字节（只用于决定切几批）：
+ *   章节规划 4 字段、hook_timeline 4 字段、章节细纲 14 字段。
+ *   细纲按 800 章估算总产出 320-480KB（400-600 B/章），取 800 B/章留 1.3-2 倍余量。
+ */
+export const RHYTHM_FILE_SPECS = [
+  {
+    type: '章节规划',
+    file: '章节规划.json',
+    template: '章节规划模板.json',
+    groups: [
+      // 章节规划只有 4 个字段，一次写 40 章（约 16KB）
+      { key: 'chapters', byChapter: true, bytesPerItem: 400, maxItems: 40 }
+    ]
+  },
+  {
+    type: '节奏参数',
+    file: '节奏参数.json',
+    template: '节奏参数模板.json',
+    groups: [
+      { key: null, wholeObject: true, maxItems: 1 }
+    ]
+  },
+  {
+    type: '时序映射',
+    file: '时序映射.json',
+    template: '时序映射模板.json',
+    groups: [
+      { key: 'character_timeline', source: 'characters', maxItems: 50 },
+      { key: 'conflict_timeline', source: 'conflicts', maxItems: 50 },
+      { key: 'foreshadow_timeline', source: 'foreshadows', maxItems: 50 },
+      { key: 'climax_timeline', source: 'climaxes', maxItems: 50 },
+      { key: 'pleasure_timeline', source: 'pleasures', maxItems: 50 },
+      // hook 与章节一一对应，字段少
+      { key: 'hook_timeline', byChapter: true, bytesPerItem: 400, maxItems: 40 },
+      { key: 'main_line_timeline', source: 'main_lines', maxItems: 50 },
+      { key: 'branch_timeline', source: 'branches', maxItems: 50 },
+      { key: 'location_timeline', source: 'locations', maxItems: 50 },
+      { key: 'item_timeline', source: 'items', maxItems: 50 },
+      { key: 'ending_timeline', source: 'endings', maxItems: 50 }
+    ]
+  },
+  {
+    type: '章节细纲',
+    file: '章节细纲.json',
+    template: '章节细纲模板.json',
+    groups: [
+      // 章节细纲 14 个字段且要跟上一批承接，一次 25 章（约 20KB）。
+      // 只写重点章（keyChaptersOnly）——重点章集合要等时序映射生成后才知道。
+      { key: 'outlines', byChapter: true, keyChaptersOnly: true, bytesPerItem: 800, maxItems: 25 }
+    ]
+  }
+];
+
+// ============================================================
+// 小工具
+// ============================================================
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 数一个模板节点里的叶子字段数（对象属性 + 数组元素字段）。
+ * 数组本身也算一个字段（数组本身要写值）。
+ */
+export function countLeafFields(node) {
+  if (!node || typeof node !== 'object') return 0;
+  const props = node.properties;
+  if (!props || typeof props !== 'object') return 0;
+  let n = 0;
+  for (const key of Object.keys(props)) {
+    const p = props[key];
+    if (!p || typeof p !== 'object') continue;
+    const t = p.type;
+    if (t === 'object') {
+      n += countLeafFields(p);
+    } else if (t === 'array') {
+      n += 1 + countLeafFields(p.items || {});
+    } else {
+      n += 1;
+    }
+  }
+  return n;
+}
+
+/**
+ * 数组 key 在模板里占多少个叶子字段。
+ * 找不到就返回 0（调用方会退回到保守估算）。
+ */
+export function arrayFieldCount(templateSpec, arrayKey) {
+  if (!templateSpec || !templateSpec.structure) return 0;
+  const props = templateSpec.structure.properties;
+  if (!props || !props[arrayKey]) return 0;
+  const arr = props[arrayKey];
+  if (arr.type !== 'array') return countLeafFields(arr);
+  return countLeafFields(arr.items || {});
+}
+
+/**
+ * 一条条目在目标文件里占多少字节（估算）。
+ * summary 数组和它的详情数组都要写，所以字段数相加。
+ */
+export function estimateItemBytes(templateSpec, arrayKeys) {
+  let fields = 0;
+  for (const key of arrayKeys) fields += arrayFieldCount(templateSpec, key);
+  return Math.max(1, fields) * BYTES_PER_FIELD;
+}
+
+// ============================================================
+// 批次规划
+// ============================================================
+
+/**
+ * 按 category 从骨架实体里挑出本组条目。
+ */
+function pickSkeletonItems(skeletonEntities, group) {
+  const list = Array.isArray(skeletonEntities[group.source]) ? skeletonEntities[group.source] : [];
+  if (!group.category) return list;
+  return list.filter((e) => e && e.category === group.category);
+}
+
+/**
+ * 规划血肉阶段的批次。
+ *
+ * @param {Object} opts
+ * @param {string} opts.skeletonDir  骨架目录（读 实体.json）
+ * @param {string} opts.templateDir  模板目录（读 *模板.json）
+ * @param {string} [opts.buildDir]   分片目录（绝对路径；给了就把 shardPath 填成绝对路径）
+ * @param {number} [opts.maxBytes]  单批目标字节上限
+ * @param {number} [opts.maxItems]  单批条目数上限
+ * @returns {Object} { ok, error, files, batches }
+ */
+export function planFleshBatches(opts) {
+  return planStageBatches(Object.assign({ stage: 'flesh' }, opts || {}));
+}
+
+/**
+ * 规划骨架阶段的批次。
+ *
+ * 骨架阶段没有上游可读：实体条数来自本阶段框架.json 的 quota，
+ * 所以调用时 `skeletonDir` 要指向**骨架阶段自己的输出目录**
+ * （框架.json / 实体.json 都是那一阶段产出的）。
+ *
+ * @param {Object} opts
+ * @param {string} opts.skeletonDir  骨架阶段输出目录（读 框架.json 的 quota、实体.json 的清单）
+ * @param {string} opts.templateDir   模板目录（读 *模板.json）
+ * @param {string[]} [opts.only]      只要这几个文件（分段驱动用）
+ * @returns {Object} { ok, error, files, batches }
+ */
+export function planSkeletonBatches(opts) {
+  return planStageBatches(Object.assign({ stage: 'skeleton' }, opts || {}));
+}
+
+/**
+ * 规划节奏阶段的批次。
+ *
+ * @param {Object} opts
+ * @param {string} opts.skeletonDir  骨架目录（读 实体.json + 框架.json 的 capacity）
+ * @param {string} opts.templateDir  模板目录（读 *模板.json）
+ * @param {string} [opts.buildDir]   分片目录（绝对路径）
+ * @param {number} [opts.chapters]   目标章数（不传就读骨架 capacity.target_chapters）
+ * @param {number} [opts.maxBytes]   单批目标字节上限
+ * @param {number} [opts.maxItems]   单批条目数上限
+ * @returns {Object} { ok, error, files, batches, chapters }
+ */
+export function planRhythmBatches(opts) {
+  const o = Object.assign({ stage: 'rhythm' }, opts || {});
+  const chapters = o.chapters || readTargetChapters(o.skeletonDir);
+  if (!chapters || chapters < 1) {
+    return {
+      ok: false,
+      error: '读不到目标章数（骨架 框架.json 的 capacity.target_chapters）：' + (o.skeletonDir || ''),
+      files: [],
+      batches: [],
+      chapters: 0
+    };
+  }
+  const plan = planStageBatches(o);
+  plan.chapters = chapters;
+  return plan;
+}
+
+/**
+ * 读骨架的目标章数。
+ */
+export function readTargetChapters(skeletonDir) {
+  const data = readJson(path.join(skeletonDir, '框架.json'));
+  if (!data) return null;
+  const cap = data.capacity && typeof data.capacity === 'object' ? data.capacity : null;
+  const t = cap ? cap.target_chapters : null;
+  if (typeof t !== 'number' || !isFinite(t) || t < 1) return null;
+  return Math.floor(t);
+}
+
+/**
+ * 通用批次规划（血肉 / 节奏共用）。
+ */
+export function planStageBatches(opts) {
+  const o = opts || {};
+  const stage = o.stage || 'flesh';
+  const skeletonDir = o.skeletonDir;
+  const templateDir = o.templateDir;
+  const maxBytes = o.maxBytes || DEFAULT_MAX_BYTES_PER_BATCH;
+  const maxItems = o.maxItems || DEFAULT_MAX_ITEMS_PER_BATCH;
+  const chapters = o.chapters || readTargetChapters(skeletonDir) || 0;
+
+  if (!skeletonDir || !templateDir) {
+    return { ok: false, error: '缺少骨架目录或模板目录', files: [], batches: [] };
+  }
+
+  const skeletonEntities = readJson(path.join(skeletonDir, '实体.json'));
+
+  const allSpecs = stage === 'rhythm' ? RHYTHM_FILE_SPECS : (stage === 'skeleton' ? SKELETON_FILE_SPECS : FLESH_FILE_SPECS);
+  // only: 只要这几个文件（节奏 / 骨架阶段分段驱动：先基础文件，后引用文件）
+  const specs = Array.isArray(o.only) && o.only.length
+    ? allSpecs.filter((sp) => o.only.indexOf(sp.type) >= 0)
+    : allSpecs;
+
+  // 骨架阶段的第一段（框架）还没有实体.json —— 实体清单要到第二段才产出。
+  // 所以这里不硬报错，等到真的要按实体切批次时再报（下面 pickSkeletonItems 处）。
+  const needsEntities = specs.some((sp) => sp.groups.some((g) =>
+    !g.wholeObject && !g.byChapter && !g.free && !g.quotaDriven));
+  if (needsEntities && !skeletonEntities) {
+    return { ok: false, error: '读不到骨架 实体.json：' + path.join(skeletonDir, '实体.json'), files: [], batches: [] };
+  }
+
+  const files = [];
+  const batches = [];
+  let globalIndex = 0;
+
+  for (let fileIndex = 0; fileIndex < specs.length; fileIndex++) {
+    const spec = specs[fileIndex];
+    const templateSpec = readJson(path.join(templateDir, spec.template));
+    if (!templateSpec) {
+      return {
+        ok: false,
+        error: '读不到模板：' + path.join(templateDir, spec.template),
+        files: [],
+        batches: []
+      };
+    }
+
+    const fileBatches = [];
+
+    for (let groupIndex = 0; groupIndex < spec.groups.length; groupIndex++) {
+      const group = spec.groups[groupIndex];
+
+      // 整文件就是一个对象（节奏参数.json）：只有一批，条目是整个对象
+      if (group.wholeObject) {
+        globalIndex += 1;
+        const batch = makeBatch({
+          spec, group, groupIndex, globalIndex, fileIndex,
+          items: [],
+          start: 0,
+          count: 1,
+          bytesPerItem: estimateItemBytes(templateSpec, []),
+          // 整文件型产物的顶层键（从模板读）：模型没写这些键时，
+          // 校验器报的 "branch_chapter_total 必填" 之类错误也要能归因回本批次。
+          objectKeys: Object.keys((templateSpec.structure && templateSpec.structure.properties) || {}),
+          buildDir: o.buildDir,
+          stage
+        });
+        batches.push(batch);
+        fileBatches.push(batch);
+        continue;
+      }
+
+      const arrayKeys = [group.key];
+      if (group.detail) arrayKeys.push(group.detail);
+
+      let items;
+      let groupQuotaCounts = null;
+      // 配额驱动的数组实际要写几条（配额为 0 时是 0，与 items.length 不同）
+      let groupTotal = null;
+      // 行数口径（骨架关系数组用）：perEntity / semantic / quota
+      let rowsMode = group.rows || null;
+      let rowsSpec = null;
+      if (group.byChapter) {
+        // 按章号切。默认 1..T 全部；给了 keyChapters 就只切重点章
+        // （章节细纲只为重点章写，这个集合要等时序映射生成后才知道）。
+        const chapterList = group.keyChaptersOnly && Array.isArray(o.keyChapters)
+          ? o.keyChapters
+          : rangeChapters(chapters);
+        items = chapterList.map((ch) => ({ ch: ch }));
+      } else if (group.free) {
+        // 无骨架来源：模型自主生成固定条数
+        items = [];
+        for (let i = 0; i < (group.count || 1); i++) items.push({ index: i + 1 });
+      } else if (group.quotaDriven) {
+        // 条数由本阶段的 框架.json 的 quota 决定（骨架阶段专用）：
+        // 没有上游可读，实体写几条要先由模型在框架里定配额，再照配额写。
+        const quota = readQuota(skeletonDir);
+        let counts = {};
+        let total = 0;
+        if (group.quotaPath) {
+          // 直接取某个 quota 字段（层级.json 的卷数/幕数不在 QUOTA_MAP 里，
+          // 校验器是拿层级自己的条数跟 quota.volume_count 对账的）
+          const v = getNested(quota, group.quotaPath);
+          const n = typeof v === 'number' && isFinite(v) ? v : 0;
+          total = n * (group.multiplier || 1);
+          counts[group.quotaPath] = total;
+        } else {
+          counts = quotaCountsByArray(quota)[group.key] || {};
+          total = Object.keys(counts).reduce((n, k) => n + counts[k], 0);
+        }
+        items = [];
+        for (let i = 0; i < total; i++) items.push({ index: i + 1 });
+        // 配额为 0 的数组**也要有分片**：键必须存在（写成空数组），
+        // 缺键的话校验器报 REQUIRED（"必填字段不得为空"），
+        // 而这个错归不到任何批次 → 整阶段反复重跑，永远修不好。
+        if (!items.length) items.push({ index: 0 });
+        // 分项配额带到批次上，提示词里要逐项告诉模型写几个
+        groupQuotaCounts = counts;
+        // 这个数组实际要写几条（配额为 0 时是 0，跟 items.length 不是一回事）
+        groupTotal = total;
+      } else if (rowsMode === 'quota') {
+        // 行数由框架 quota 决定（骨架关系数组专用）：
+        //   faction_relations 的行数 = quota.faction_relation_count * 2
+        // （无向关系对存成双向行 A→B 与 B→A，各一行）
+        // 这里取的是**精确总行数**，不是源实体个数 —— 两者不是一回事。
+        const quota = readQuota(skeletonDir);
+        const v = getNested(quota, group.quotaPath);
+        const pairs = typeof v === 'number' && isFinite(v) ? v : 0;
+        const mult = group.multiplier || 1;
+        groupTotal = pairs * mult;
+        // 源实体只是关系的两端（可引用的 id），不是要写的行数
+        items = pickSkeletonItems(skeletonEntities, group).map((e) => ({
+          id: e.id,
+          name: e.name,
+          type: e.type,
+          category: e.category
+        }));
+        rowsSpec = {
+          mode: 'quota',
+          quotaPath: group.quotaPath,
+          pairs: pairs,
+          multiplier: mult,
+          total: groupTotal
+        };
+      } else {
+        items = pickSkeletonItems(skeletonEntities, group).map((e) => ({
+          id: e.id,
+          name: e.name,
+          type: e.type,
+          category: e.category
+        }));
+      }
+
+      const bytesPerItem = group.bytesPerItem || estimateItemBytes(templateSpec, arrayKeys);
+      let perBatch = Math.floor(maxBytes / bytesPerItem);
+      if (!isFinite(perBatch) || perBatch < 1) perBatch = 1;
+      // 条目数上限是"估算失真"的安全阀，不是主要约束：
+      // 血肉的条目是大对象（角色 45 字段），12 条就接近单批字节上限；
+      // 节奏按章的条目很小（细纲一章 ~800B），用同一个上限会把批次切得过碎
+      // （tt5 实测 800 章被切成 232 批）。所以上限按 group 单独定。
+      const itemCap = group.maxItems !== undefined ? group.maxItems : maxItems;
+      if (perBatch > itemCap) perBatch = itemCap;
+      // 配额驱动的数组**不切分**：配额是按类型给的（主角 2 个、核心配角 6 个…），
+      // 切开之后每批该分到几个"主角"就说不清了 —— 而校验器核对的是
+      // 整个数组里各类型的总条数（QUOTA_MISMATCH）。
+      // 实体条目很小（id + name + 枚举字段，~120B），一个数组一批完全装得下。
+      if (group.quotaDriven) perBatch = Math.max(1, items.length);
+      // quota 行数口径的数组**也不切分**：它的行数是精确值（quota × 倍数），
+      // 拆开之后每批该写几行就没法说了 —— 而且"哪些势力互相对立"是模型自己选的，
+      // 跨批切分会让同一对关系写两遍或漏掉。关系行很短（几十字节），一批装得下。
+      if (rowsMode === 'quota') perBatch = Math.max(1, items.length);
+
+      for (let start = 0; start < items.length; start += perBatch) {
+        const slice = items.slice(start, start + perBatch);
+        globalIndex += 1;
+        const batch = makeBatch({
+          spec, group, groupIndex, globalIndex, fileIndex,
+          items: slice,
+          start,
+          count: groupTotal !== null ? groupTotal : slice.length,
+          bytesPerItem,
+          quotaCounts: groupQuotaCounts,
+          rowsMode: rowsMode,
+          rowsSpec: rowsSpec,
+          buildDir: o.buildDir,
+          stage
+        });
+        batches.push(batch);
+        fileBatches.push(batch);
+      }
+    }
+
+    // 一个批次都切不出来 = 这一段没法写。
+    // 不报错的话，合并阶段只会抛一句"合并参数不完整"（天书），
+    // 而真正的原因是"实体清单里没有 characters"这类上游缺失 —— 必须说清楚。
+    if (!fileBatches.length) {
+      const why = spec.groups.map((g) => {
+        const key = g.key || '整个文件';
+        if (g.quotaDriven) return key + '（框架 quota 里这一项是 0）';
+        if (g.source) return key + '（实体清单里没有 ' + g.source + '）';
+        if (g.byChapter) return key + '（章数为 0）';
+        return key;
+      }).join('、');
+      return {
+        ok: false,
+        error: spec.file + ' 切不出任何批次：' + why,
+        files: [],
+        batches: []
+      };
+    }
+
+    files.push({
+      type: spec.type,
+      file: spec.file,
+      template: spec.template,
+      fileIndex: fileIndex + 1,
+      batches: fileBatches,
+      totalItems: fileBatches.reduce((n, b) => n + b.count, 0)
+    });
+  }
+
+  return { ok: true, error: null, files: files, batches: batches, chapters: chapters };
+}
+
+function rangeChapters(n) {
+  const out = [];
+  for (let ch = 1; ch <= n; ch++) out.push(ch);
+  return out;
+}
+
+/**
+ * 算"重点章"——需要写章节细纲的章。
+ *
+ * 依据（与 prompts/03-rhythm-prompt.md §7.2.4 的定义一致）：
+ *   1. 第 1 章
+ *   2. 每卷的第 1 章和最后 1 章
+ *   3. 大高潮对应的章
+ *   4. 结局对应的章
+ *   5. 有钩子的章（细纲的 hook_head/hook_tail 必须与时序映射对齐）
+ *
+ * 这个集合依赖时序映射（高潮章 / 结局章 / 钩子章都是模型生成的），
+ * 所以必须在时序映射生成完之后才能算 —— 这就是节奏阶段要分两批驱动的原因。
+ *
+ * @param {Object} opts
+ * @param {Array}  opts.chapters   章节规划的 chapters 数组
+ * @param {Object} opts.timeline   时序映射（合并后的对象）
+ * @param {Object} opts.climaxTypes  climax_id -> type（来自骨架 climaxes）
+ * @returns {number[]} 升序去重的章号
+ */
+export function computeKeyChapters(opts) {
+  const o = opts || {};
+  const chapters = Array.isArray(o.chapters) ? o.chapters : [];
+  const timeline = o.timeline && typeof o.timeline === 'object' ? o.timeline : {};
+  const climaxTypes = o.climaxTypes && typeof o.climaxTypes === 'object' ? o.climaxTypes : {};
+
+  const set = new Set();
+  if (chapters.length) set.add(1);
+
+  // 每卷的首尾章
+  const byVolume = new Map();
+  for (const c of chapters) {
+    if (!c || typeof c !== 'object') continue;
+    const v = c.volume;
+    const ch = c.ch;
+    if (typeof ch !== 'number') continue;
+    if (!byVolume.has(v)) byVolume.set(v, []);
+    byVolume.get(v).push(ch);
+  }
+  for (const list of byVolume.values()) {
+    list.sort((a, b) => a - b);
+    set.add(list[0]);
+    set.add(list[list.length - 1]);
+  }
+
+  // 大高潮章
+  const climaxTimeline = Array.isArray(timeline.climax_timeline) ? timeline.climax_timeline : [];
+  for (const c of climaxTimeline) {
+    if (!c || typeof c !== 'object') continue;
+    if (climaxTypes[c.climax_id] !== '大高潮') continue;
+    if (typeof c.chapter === 'number') set.add(c.chapter);
+  }
+
+  // 结局章
+  const endingTimeline = Array.isArray(timeline.ending_timeline) ? timeline.ending_timeline : [];
+  for (const e of endingTimeline) {
+    if (e && typeof e.chapter === 'number') set.add(e.chapter);
+  }
+
+  // 钩子章
+  const hookTimeline = Array.isArray(timeline.hook_timeline) ? timeline.hook_timeline : [];
+  for (const h of hookTimeline) {
+    if (h && typeof h.ch === 'number') set.add(h.ch);
+  }
+
+  return Array.from(set).filter((ch) => Number.isFinite(ch)).sort((a, b) => a - b);
+}
+
+/**
+ * 从骨架实体里取 climax_id -> type 的映射。
+ */
+export function buildClimaxTypes(skeletonEntities) {
+  const map = {};
+  if (!skeletonEntities || typeof skeletonEntities !== 'object') return map;
+  for (const c of (skeletonEntities.climaxes || [])) {
+    if (c && c.id) map[c.id] = c.type;
+  }
+  return map;
+}
+
+function makeBatch(ctx) {
+  const spec = ctx.spec;
+  const group = ctx.group;
+  const globalIndex = ctx.globalIndex;
+  const shard = shardName(spec, group, globalIndex, ctx.stage);
+  return {
+    key: spec.file + '#' + (group.key || 'whole') + '#' + ctx.groupIndex + '#' + globalIndex,
+    index: globalIndex,
+    fileIndex: ctx.fileIndex + 1,
+    type: spec.type,
+    file: spec.file,
+    template: spec.template,
+    groupIndex: ctx.groupIndex,
+    groupKey: group.key,
+    wholeObject: !!group.wholeObject,
+    byChapter: !!group.byChapter,
+    // 整文件型产物的顶层键（从模板读）：模型没写这些键时，
+    // 校验器报的 "branch_chapter_total 必填" 之类错误也要能归因回本批次。
+    objectKeys: ctx.objectKeys || [],
+    // details 必须跟着 summary 一起合并：校验器要求两者 id 一一对应，
+    // 只合并 summary 会让关键道具.json 永远缺 details（FLESH_DETAILS_ORPHAN）。
+    arrays: group.key ? (group.detail ? [group.key, group.detail] : [group.key]) : [],
+    summaryArray: group.key,
+    detailArray: group.detail || null,
+    shard: shard,
+    shardPath: ctx.buildDir ? path.join(ctx.buildDir, shard) : null,
+    start: ctx.start,
+    count: ctx.count,
+    items: ctx.items,
+    // 配额分项（骨架阶段专用）：这批要写几个"主角"、几个"核心配角"…
+    // 提示词里要逐项写明，模型才知道每类写几个。
+    quotaCounts: ctx.quotaCounts || null,
+    // 行数口径（骨架关系数组专用）：
+    //   'perEntity' —— 每个源实体一行，行数 = count（= 本批实体数）
+    //   'semantic'  —— 行数由关系本身决定，**不预设**，提示词不能说"写 N 条"
+    //   'quota'     —— 行数 = rowsSpec.total（quota × 倍数），精确值
+    // 以前这三类混为一谈，提示词统一写"本批要写的条目（N 条）…每行一条"，
+    // 模型就把 N 当成真实行数（tt5 实测：faction_relations 要 24 行只写了 8 行）。
+    rowsMode: ctx.rowsMode || null,
+    rowsSpec: ctx.rowsSpec || null,
+    // 这批要引用的实体类型（骨架阶段的关系类批次用）：
+    // 提示词里要给对应的 id 表，否则模型只能凭空编 id（SKELETON_REF_MISSING）。
+    refs: (group.refs || []).slice(),
+    // 这批负责的关系行归属字段（骨架阶段的关系/层级类批次用）：
+    // 行里该字段的值落在本批源实体里 → 这条行归本批管。
+    // 没有它，"每批写哪些行"就没有唯一定义（模型在两批里写同一行 → 合并后 ID_DUP）。
+    ownerField: group.ownerField || null,
+    bytesPerItem: ctx.bytesPerItem,
+    estBytes: ctx.bytesPerItem * ctx.count,
+    free: !!group.free
+  };
+}
+
+/**
+ * 分片文件名：角色.b01.characters.json
+ * 全局批序号保证唯一，数组名保证可读。
+ */
+function shardName(spec, group, globalIndex, stage) {
+  const seq = globalIndex < 10 ? '0' + globalIndex : String(globalIndex);
+  const prefix = stage === 'rhythm' ? '节奏' : (stage === 'skeleton' ? '骨架' : '血肉');
+  const name = spec.type + '.b' + seq + '.' + (group.key || 'whole') + '.json';
+  return prefix + '-' + name;
+}
+
+// ============================================================
+// 分片合并
+// ============================================================
+
+/**
+ * 把一个文件的全部分片合并成最终产物文件。
+ *
+ * 合并是幂等的：目标文件始终由全部分片重新合成，
+ * 所以"重投某一批" = 重写那一个分片 -> 重新合并。
+ *
+ * @param {Object} opts
+ * @param {string} opts.stageDir   阶段目录（目标文件写这里）
+ * @param {string} opts.buildDir   分片目录
+ * @param {Array}  opts.batches    该文件的批次（按顺序）
+ * @returns {Object} { ok, error, path, layout, missing }
+ */
+/**
+ * 清掉中途校验留下的半成品（.partial-*.json）。
+ *
+ * 半成品的名字是 '.partial-' + 文件名：中途校验要把"目前写了一半的产物"
+ * 落到正式文件之外，免得半成品盖掉正式产物。但它们留在产物目录里会让人
+ * 以为那是产物的一部分（tt5 实测 2026-10-25：产物目录里躺着
+ * .partial-框架.json / .partial-实体.json）。
+ *
+ * 按目录实际内容清，而不是写死几个文件名 —— 哪一段都可能留下半成品。
+ *
+ * @param {string} stageDir - 产物目录
+ * @returns {string[]} 被清掉的文件名
+ */
+export function cleanupPartialFiles(stageDir) {
+  const removed = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(stageDir);
+  } catch (e) {
+    return removed;
+  }
+  for (const f of entries) {
+    if (!f.startsWith('.partial-') || !f.endsWith('.json')) continue;
+    try {
+      fs.unlinkSync(path.join(stageDir, f));
+      removed.push(f);
+    } catch (e) { /* 删不掉就留着，下一轮再清 */ }
+  }
+  return removed;
+}
+
+export function mergeFleshShards(opts) {
+  const o = opts || {};
+  const stageDir = o.stageDir;
+  const buildDir = o.buildDir;
+  const batches = o.batches || [];
+  if (!stageDir || !buildDir || !batches.length) {
+    return { ok: false, error: '合并参数不完整', path: null, layout: {}, missing: [] };
+  }
+
+  const target = {};
+  const layout = {};
+  const missing = [];
+  // 行归属越界的行（ownerField 不在本批实体里）
+  const ownershipViolations = [];
+
+  // 中途校验用：allowMissing = 还没生成的批次分片不存在，**跳过而不是失败**；
+  // outPath = 写到别处（中途的半成品不能覆盖正式产物）。
+  const allowMissing = !!o.allowMissing;
+
+  for (const batch of batches) {
+    const shardPath = path.join(buildDir, batch.shard);
+    const shard = readJson(shardPath);
+    if (!shard) {
+      // 分片还没生成（中途校验时正常）：记下来，最后看要不要当失败
+      missing.push(batch.shard);
+      continue;
+    }
+
+    // 整文件就是一个对象（节奏参数.json）：分片内容直接就是目标内容
+    if (batch.wholeObject) {
+      // 模板声明的顶层键也要登记：模型整个键漏写时，
+      // 校验器报的 "branch_chapter_total 必填" 之类错误同样要归因回本批次。
+      if (!layout.__byName) layout.__byName = {};
+      for (const k of (batch.objectKeys || [])) {
+        if (!Array.isArray(layout[k])) layout.__byName[k] = batch.key;
+      }
+      for (const k of Object.keys(shard)) {
+        target[k] = shard[k];
+        // 顶层字段名也要登记：校验器报的路径有两类
+        //   "节奏参数.overlap_chapter_count" —— 文件类型名 + 字段
+        //   "derivations.branch_chapter_feasible" —— 顶层键 + 子键
+        // 第二类只有登记了顶层键才能归因回本批次，否则错误会被丢掉。
+        if (!Array.isArray(layout[k])) layout.__byName[k] = batch.key;
+      }
+      layout.__whole = { batchKey: batch.key };
+      // 整文件型产物（如节奏参数.json）的错误 path 形如
+      // "节奏参数.overlap_chapter_count" / "derivations.xxx"，
+      // 这里把文件类型名登记下来，归因时直接落到这个批次。
+      if (!layout.__byName) layout.__byName = {};
+      layout.__byName[batch.type] = batch.key;
+      layout.__byName[batch.file] = batch.key;
+      continue;
+    }
+
+    for (const arrayKey of batch.arrays) {
+      // 声明登记：即使分片里这个数组是空的，也要记住"这个数组归哪些批次管"。
+      // 模型整个数组漏写时（合并结果里根本没有这个键），
+      // 校验器报的 "chapters 必填" 才能归因回批次而不是变成归不了的错。
+      if (!layout.__declared) layout.__declared = {};
+      if (!Array.isArray(layout.__declared[arrayKey])) layout.__declared[arrayKey] = [];
+      if (layout.__declared[arrayKey].indexOf(batch.key) < 0) {
+        layout.__declared[arrayKey].push(batch.key);
+      }
+
+      if (!Array.isArray(shard[arrayKey])) continue;
+      if (!Array.isArray(target[arrayKey])) target[arrayKey] = [];
+      if (!Array.isArray(layout[arrayKey])) layout[arrayKey] = [];
+      if (!Array.isArray(layout.__arrays)) layout.__arrays = {};
+      if (!layout.__arrays[arrayKey]) layout.__arrays[arrayKey] = [];
+      // 行归属校验（ownerField）：这一行"归谁管"由 ownerField 唯一确定 ——
+      // ownerField 的值必须落在本批的源实体里。
+      // 以前 ownerField 只是写在批次上没人读，"每批写哪些行"全靠提示词一句话；
+      // 模型写串行时没有任何东西拦得住（tt5 实测：提示词说 8 条、实际要 24 行）。
+      const mine = ownerIdSet(batch);
+      for (const item of shard[arrayKey]) {
+        const idx = target[arrayKey].length;
+        target[arrayKey].push(item);
+        layout.__arrays[arrayKey].push(batch.key);
+        layout[arrayKey].push({
+          batchKey: batch.key,
+          // 2026-10-27：原来叫 indexInBatch，但它记的是**合并后目标数组的全局行号**，
+          // 不是批次内下标（第 45 行 ≠ 本批第 45 行）。名字误导会让人以为
+          // "本批写了 45 行"。改名成 indexInGlobal。
+          // 生产代码只读 batchKey / id / keys，不读这个字段，所以改名是安全的。
+          indexInGlobal: layout[arrayKey].length,
+          // 关系 / 归属类行没有 id 字段，合成一个定位键，
+          // 否则这类错误归因不到具体批次（见 synthRowId 的说明）。
+          id: item && item.id ? item.id : synthRowId(item),
+          keys: entryKeys(item)
+        });
+        if (mine && batch.ownerField) {
+          const v = item && item[batch.ownerField];
+          if (typeof v !== 'string' || !v || !mine.has(v)) {
+            ownershipViolations.push({
+              code: 'BATCH_OWNER_MISMATCH',
+              path: arrayKey + '[' + idx + '].' + batch.ownerField,
+              message: '这一行的 ' + batch.ownerField + '="' + (v || '(空)') + '" 不属于本批（' +
+                batch.shard + ' 负责 ' + batch.ownerField + ' ∈ ' + (batch.items || []).map((x) => x.id).join('/') + '）',
+              hint: '每批只写归属到本批实体的行；' + batch.ownerField + ' 不在本批名单里的行留给对应的批次写',
+              batchKey: batch.key
+            });
+          }
+        }
+      }
+    }
+  }
+
+  if (missing.length && !allowMissing) {
+    return {
+      ok: false,
+      error: '缺少分片：' + missing.join('、'),
+      path: null,
+      layout: layout,
+      missing: missing,
+      ownershipViolations: ownershipViolations
+    };
+  }
+
+  const outPath = o.outPath || path.join(stageDir, batches[0].file);
+  try {
+    fs.mkdirSync(stageDir, { recursive: true });
+    const tmp = outPath + '.tmp-' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(target, null, 2), 'utf-8');
+    fs.renameSync(tmp, outPath);
+  } catch (e) {
+    return { ok: false, error: '写目标文件失败：' + e.message, path: outPath, layout: layout, missing: [], ownershipViolations: ownershipViolations };
+  }
+
+  return {
+    ok: true,
+    error: null,
+    path: outPath,
+    layout: layout,
+    missing: missing,
+    ownershipViolations: ownershipViolations,
+    // 已经写进去的数组名（中途校验时用它决定校验哪几个数组）
+    writtenArrays: Object.keys(target)
+  };
+}
+
+/**
+ * 本批"拥有"的实体 id 集合（按 ownerField 判定行归属）。
+ * 没有 ownerField 或没有 items 的批次不参与归属校验（返回 null）。
+ */
+function ownerIdSet(batch) {
+  if (!batch || !batch.ownerField) return null;
+  if (!Array.isArray(batch.items) || !batch.items.length) return null;
+  const set = new Set();
+  for (const it of batch.items) {
+    if (it && it.id) set.add(it.id);
+  }
+  return set.size ? set : null;
+}
+
+/**
+ * 取一个条目的所有标识值（id / ch / xxx_id）。
+ * 归因时用 path 里的标识反查条目，所以要把各种命名的 id 都收进来。
+ */
+/**
+ * 关系 / 归属类行的定位键。
+ *
+ * 这类行本身没有 id 字段（character_relations 的行是 {from,to,relation_kind}，
+ * faction_membership 是 {character,faction}，item_owner 是 {item,character}…），
+ * 而 entryKeys 只收 id / ch / *_id → 关系行一个键都没有。
+ *
+ * 后果：校验器报 `character_relations.C011→C013` 时，归因层一个形态都匹配不上
+ * （entry.id 为 null、entry.keys 为空）→ 只能退化成"该数组的所有批次"，
+ * 模型被派去改 7 个批次，其中大部分根本没有那条错 → 改不动 → NO_CHANGE →
+ * 反复重投（tt5 实测 2026-10-25 session-39fec2c0：b04 连续两次 NO_CHANGE）。
+ *
+ * 这里合成的键与校验器的 path 格式**逐字一致**：
+ *   character_relations / faction_relations → from→to
+ *   faction_membership                      → character@faction
+ *   branch_protagonist                      → branch
+ *   item_owner                              → item
+ *   location_conflict                       → location
+ *
+ * @param {Object} item 行对象
+ * @returns {string|null}
+ */
+export function synthRowId(item) {
+  if (!item || typeof item !== 'object') return null;
+  if (typeof item.from === 'string' && item.from && typeof item.to === 'string' && item.to) {
+    return item.from + '→' + item.to;
+  }
+  if (typeof item.character === 'string' && item.character
+      && typeof item.faction === 'string' && item.faction) {
+    return item.character + '@' + item.faction;
+  }
+  if (typeof item.branch === 'string' && item.branch) return item.branch;
+  if (typeof item.item === 'string' && item.item) return item.item;
+  if (typeof item.location === 'string' && item.location) return item.location;
+  return null;
+}
+
+export function entryKeys(item) {
+  if (!item || typeof item !== 'object') return [];
+  const out = [];
+  for (const key of Object.keys(item)) {
+    const v = item[key];
+    if (key === 'id' || key === 'ch' || /_id$/.test(key)) {
+      if (typeof v === 'string' && v) out.push(v);
+      else if (typeof v === 'number' && isFinite(v)) out.push(String(v));
+    }
+  }
+  return out;
+}
+
+// ============================================================
+// 错误归因
+// ============================================================
+
+/**
+ * 跨文件错误码 → 涉及的顶层键。
+ *
+ * 节奏阶段有一批错误**天然跨文件**：脚本判的是"两个文件合起来对不对"，
+ * 单看 path 只能定位到其中一边（例如 RHYTHM_OVERLAP_COUNT 的 path 是
+ * "节奏参数.overlap_chapter_count"，但真正要改的往往是 main_line_timeline
+ * 或 branch_timeline）。只按 path 归因会导致模型去改错的那一边，
+ * 下一轮还是同样的错。
+ *
+ * 这里显式列出"这个错误牵涉哪些顶层键"，归因时把这些键的全部批次都拉进来重投，
+ * 让模型自己判断该改哪边（错误消息里带着实际值与期望值）。
+ */
+export const RHYTHM_CROSS_FILE_OWNERS = {
+  // 主线 key_nodes 数 ≠ main_progress_chapter_count
+  RHYTHM_NODES_COUNT: ['main_line_timeline', '节奏参数'],
+  // 支线章数之和 ≠ branch_chapter_total
+  RHYTHM_BRANCH_TOTAL: ['branch_timeline', '节奏参数'],
+  // 支线章集 ∩ 主线 key_node 章集 ≠ overlap_chapter_count
+  RHYTHM_OVERLAP_COUNT: ['main_line_timeline', 'branch_timeline', '节奏参数'],
+  // 结局章不在主线 key_nodes 里
+  RHYTHM_COVERAGE: ['ending_timeline', 'main_line_timeline'],
+  // 全书级结局没回收所有大伏笔
+  RHYTHM_LARGE_FS_NOT_RECOVERED: ['ending_timeline', 'foreshadow_timeline'],
+  // 主线节点章节重复
+  RHYTHM_NODE_DUP: ['main_line_timeline'],
+  // 支线区间重叠
+  RHYTHM_BRANCH_OVERLAP: ['branch_timeline'],
+  // 钩子数低于下限
+  RHYTHM_HOOK_MIN: ['hook_timeline', '节奏参数'],
+  // 三个参数不满足 7 条约束
+  RHYTHM_INFEASIBLE: ['节奏参数'],
+  RHYTHM_CONSTRAINT_EVAL: ['节奏参数'],
+  RHYTHM_DERIVATION_MISSING: ['节奏参数'],
+  RHYTHM_DERIVATION_EXTRA: ['节奏参数']
+};
+
+/**
+ * 把校验错误按 path 归因到具体批次。
+ *
+ * flesh-validate 的 path 形态（实测枚举）：
+ *   characters[3].name        —— 数组名 + 下标
+ *   items.P001                —— 数组名 + id
+ *   骨架关系 C001→C002        —— 跨文件，无法按条目归因
+ *
+ * rhythm-validate 的 path 形态（实测枚举）：
+ *   chapters[12].act          —— 数组名 + 下标
+ *   outlines[40].word_target
+ *   hook_timeline.300         —— 数组名 + 章号（条目标识不是 id，是 ch）
+ *   ending_timeline.E001.chapter
+ *   节奏参数.overlap_chapter_count —— 顶层对象字段
+ *   ch:412                    —— 章号（RHYTHM_CHAPTER_UNREF）
+ *
+ * @param {Array} errors  校验器返回的 errors[]
+ * @param {Object} layout mergeFleshShards 返回的 layout
+ * @param {Object} [opts]
+ * @param {Object} [opts.codeOwners] 错误码 → 涉及的顶层键列表（见 RHYTHM_CROSS_FILE_OWNERS）
+ * @param {Function} [opts.pathKeys] (path) => 顶层键|null
+ *   专用路径解析器，**优先于通用形态匹配**。
+ *   存在的理由：有些错误的 path 指向"声明方"，根因却在"被核对方"。
+ *   例如骨架的 QUOTA_MISMATCH，path 是 "quota.character_counts.protagonist"
+ *   （声明在框架里），但真正要改的是实体清单里少写了一个主角。
+ *   按通用规则会归到框架批次，模型就会去改 quota —— 下一轮还是同样的错。
+ * @returns {Object} { byBatch: {batchKey: errors[]}, unattributed: errors[] }
+ */
+export function attributeErrors(errors, layout, opts) {
+  const o = opts || {};
+  const codeOwners = o.codeOwners || null;
+  const pathKeys = typeof o.pathKeys === 'function' ? o.pathKeys : null;
+  const byBatch = {};
+  const unattributed = [];
+  const list = Array.isArray(errors) ? errors : [];
+
+  for (const err of list) {
+    const hit = attributeOne(err, layout, pathKeys);
+    const keys = [];
+    if (hit && hit.length) {
+      for (const k of hit) if (keys.indexOf(k) < 0) keys.push(k);
+    }
+    // 跨文件错误：path 只能定位到一边，把牵涉的顶层键的批次一起拉进来
+    const owners = codeOwners && err && err.code ? codeOwners[err.code] : null;
+    if (owners) {
+      for (const ownerKey of owners) {
+        for (const k of batchesOfKey(layout, ownerKey)) {
+          if (keys.indexOf(k) < 0) keys.push(k);
+        }
+      }
+    }
+    if (!keys.length) {
+      unattributed.push(err);
+      continue;
+    }
+    for (const batchKey of keys) {
+      if (!byBatch[batchKey]) byBatch[batchKey] = [];
+      byBatch[batchKey].push(err);
+    }
+  }
+
+  return { byBatch: byBatch, unattributed: unattributed };
+}
+
+/**
+ * 取某个顶层键涉及的全部批次 key。
+ * 数组键 → 该数组所有条目所在的批次；整文件型产物 → 那一个批次。
+ *
+ * 三级兜底，空了就往下查（不能因为"有登记但登记的是空数组"就提前返回）：
+ *   __arrays  —— 实际有条目的批次（最精确）
+ *   __declared —— 声明该数组的批次（模型整个数组漏写时靠它兜底）
+ *   __byName  —— 整文件型产物（顶层键 → 唯一一个批次）
+ */
+function batchesOfKey(layout, key) {
+  const arrays = (layout && layout.__arrays) || {};
+  if (arrays[key] && arrays[key].length) return arrays[key].slice();
+  const declared = (layout && layout.__declared) || {};
+  if (declared[key] && declared[key].length) return declared[key].slice();
+  const byName = (layout && layout.__byName) || {};
+  if (byName[key]) return [byName[key]];
+  return [];
+}
+
+/**
+ * 把一条错误定位到批次。
+ *
+ * path 形态（血肉 / 节奏实测枚举）：
+ *   key[i].field   —— 数组名 + 下标，精确到条目
+ *   key.标识        —— 数组名 + id/章号，精确到条目
+ *   key.标识.field —— 数组名 + id + 子字段（ending_timeline.E001.chapter）
+ *   ch:123         —— 章号（该章在 hook_timeline 里没有覆盖）
+ *   key            —— 整个数组（如"hook 有重复"），落到该数组的所有批次
+ *   其它 / 空       —— 归不了（跨文件错误），留给调用方兜底
+ *
+ * @returns {string[]|null} 批次 key 列表；null 表示归不了
+ */
+function attributeOne(err, layout, pathKeys) {
+  const p = err && typeof err.path === 'string' ? err.path : '';
+  if (!p) return null;
+
+  // 形态零：专用路径解析器优先（骨架的 quota.<字段> → 实体数组）
+  if (pathKeys) {
+    const key = pathKeys(p);
+    if (key) {
+      const keys = batchesOfKey(layout, key);
+      if (keys.length) return keys;
+    }
+  }
+
+  // 形态零·补：key[标识].field —— 标识命中即算
+  //   （character_timeline[C001].arc_stages[0].chapter）
+  // 节奏阶段的错误 path 用**业务主键**而不是合并后的全局下标：
+  // 下标模型看不懂（不知道第 3 条是哪个角色），业务键才定位得准。
+  // 这个形态只认「标识能命中 entry.id / entry.keys」的情况，
+  // 认不出就继续往下走（形态一负责 key[数字]）。
+  const m0b = p.match(/^([^.[\]]+)\[([^\[\]]+)\]/);
+  if (m0b) {
+    const arr = layout[m0b[1]];
+    if (Array.isArray(arr)) {
+      for (const entry of arr) {
+        if (entry.id && entry.id === m0b[2]) return [entry.batchKey];
+        if (Array.isArray(entry.keys) && entry.keys.indexOf(m0b[2]) >= 0) return [entry.batchKey];
+      }
+    }
+  }
+
+  // 形态一：key[i].field（键名允许中文）
+  const m1 = p.match(/^([^.[\]]+)\[(\d+)\]/);
+  if (m1) {
+    const arr = layout[m1[1]];
+    if (Array.isArray(arr)) {
+      const idx = Number(m1[2]);
+      if (idx >= 0 && idx < arr.length) return [arr[idx].batchKey];
+      // 下标越界 = 这个条目根本不存在（合并结果里没那么多条），
+      // 落到任何一个批次都是错的 → 明确归不了，让调用方兜底。
+      return null;
+    }
+    // 键名不在布局里（如校验器报了另一个文件/另一个阶段的键）：
+    // **继续往下走**（形态二~六），形态六还能按顶层键退化到
+    // "该数组的所有批次"；直接 return null 会让这条错归不到 →
+    // 触发整段重跑（白烧额度）。
+  }
+
+  // 形态二：key.标识.field —— 标识命中即算（ending_timeline.E001.chapter）
+  const m2b = p.match(/^([^.[\]]+)\.([^.[\]]+)\./);
+  if (m2b) {
+    const arr = layout[m2b[1]];
+    if (Array.isArray(arr)) {
+      for (const entry of arr) {
+        if (entry.id && entry.id === m2b[2]) return [entry.batchKey];
+        if (Array.isArray(entry.keys) && entry.keys.indexOf(m2b[2]) >= 0) return [entry.batchKey];
+      }
+      // 标识认不出来 → 别急着放弃，往下走形态五/六（按顶层键退化）。
+    }
+  }
+
+  // 形态三：key.标识（id / 章号 / 名称）
+  const m2 = p.match(/^([^.[\]]+)\.([^.[\]]+)$/);
+  if (m2) {
+    const arr = layout[m2[1]];
+    if (Array.isArray(arr)) {
+      for (const entry of arr) {
+        if (entry.id && entry.id === m2[2]) return [entry.batchKey];
+        if (Array.isArray(entry.keys) && entry.keys.indexOf(m2[2]) >= 0) return [entry.batchKey];
+      }
+      // 标识认不出来（**名称**型标识就是这种情况，见形态六）→ 往下退化。
+    } else {
+      // 整文件型产物（节奏参数.json）
+      const byName = layout.__byName || {};
+      if (byName[m2[1]]) return [byName[m2[1]]];
+      // 往下退化。
+    }
+  }
+
+  // 形态三·补：裸 id（path 整体就是一个 id，如 "C001"）
+  //
+  // 哪些错误长这样：
+  //   G_ISOLATED（骨架图孤立节点）—— path 直接是节点 key（skeleton-validate.js: path = n.key）
+  //   关系类错误里 from/to 只有一个被写出来时也会这样
+  // 之前一个形态都匹配不上（形态一要 `key[i]`、形态二/三要带点）→
+  // 归不到批次 → 整段重跑。
+  if (!/[.[]/.test(p)) {
+    for (const arr of Object.values(layout)) {
+      if (!Array.isArray(arr)) continue;
+      for (const entry of arr) {
+        if (entry.id && entry.id === p) return [entry.batchKey];
+        if (Array.isArray(entry.keys) && entry.keys.indexOf(p) >= 0) return [entry.batchKey];
+      }
+    }
+  }
+
+  // 形态四：ch:123 —— 该章没有任何事件/角色/伏笔/钩子引用。
+  // 章号的唯一真源是时序映射里的 hook_timeline，所以先找覆盖该章的那个批次；
+  // 找不到说明这一章压根没被 hook_timeline 覆盖，负责 hook_timeline 的批次都要重投。
+  const m4 = p.match(/^ch:(\d+)$/);
+  if (m4) {
+    const ch = m4[1];
+    const arr = layout.hook_timeline;
+    if (Array.isArray(arr)) {
+      for (const entry of arr) {
+        if (Array.isArray(entry.keys) && entry.keys.indexOf(ch) >= 0) return [entry.batchKey];
+      }
+    }
+    const owners = (layout.__arrays || {}).hook_timeline;
+    if (owners && owners.length) return owners.slice();
+    return null;
+  }
+
+  // 形态五：整个数组
+  // 声明兜底：模型整个数组漏写时（合并结果里没这个键），
+  // 错误要归到"负责这个数组的批次"上，而不是变成归不了的错。
+  const wholeKey = batchesOfKey(layout, p);
+  if (wholeKey.length) return wholeKey;
+
+  // 形态六：顶层键退化 —— path 的顶层键是一个已知数组时，归到该数组的所有批次。
+  //
+  // 为什么必须有这一层（tt5 骨架实测）：
+  //   骨架校验器的 NAME_DUP 路径是 **名称** 而不是 id
+  //   （skeleton-validate.js: path = key + '.' + item.name），
+  //   而布局里每条只登记了 id（entryKeys 只收 id/ch/*_id），
+  //   于是 "pleasures.修复技艺碾压质疑者" 这种路径**一个条目都匹配不上**。
+  //
+  //   归不了批次的代价极大：stage-driver 的兜底会把同一份错误发给
+  //   **所有**批次并整阶段重跑（tt5 实测：13 个批次各收到同一份 15 条
+  //   pleasures 重名，模型去改根本不属于它的批次，白烧额度还引入新错）。
+  //
+  //   退化成"这个数组的所有批次"是对的：重名/重 ID 的成因在数组内部，
+  //   该数组的批次全都可能牵涉（同名条目可能分属不同批次）。
+  const top = p.split(/[.[]/)[0];
+  if (top && top !== p) {
+    const byTop = batchesOfKey(layout, top);
+    if (byTop.length) return byTop;
+  }
+
+  return null;
+}
+
+/**
+ * 找出某个文件里还缺哪些分片（用于判断"这一批写没写出来"）。
+ */
+export function missingShards(buildDir, batches) {
+  const missing = [];
+  for (const batch of batches || []) {
+    if (!fs.existsSync(path.join(buildDir, batch.shard))) missing.push(batch.shard);
+  }
+  return missing;
+}
+