@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-story-builder/scripts/v2/engine.js

@@ -0,0 +1,1068 @@
+/**
+ * v2/engine.js —— 2.0 插件驱动：插件当司机，LLM 只按指令写文件。
+ *
+ * 这里不直接依赖 DSH：sendPrompt / waitIdle 由命令处理器注入。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  V2_STAGE_BY_ID,
+  asArray,
+  ensureDir,
+  nowIso,
+  readJson,
+  readText,
+  stageDir,
+  stageFile,
+  writeJsonAtomic,
+  writeTextAtomic,
+} from './core.js';
+import { buildChapterMapPrompt, buildOutlinePrompt, buildWritingPrompt } from './prompts.js';
+
+export const FILE_MAX_ATTEMPTS = 3;
+// 单次提示词超过这个长度时，先停下并报告，避免把模型/宿主拖进上下文压缩死循环。
+export const MAX_PROMPT_CHARS = 180000;
+
+function isValidJsonFile(file) {
+  try {
+    JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function pad3(n) {
+  return String(n).padStart(3, '0');
+}
+
+function pickFields(obj, fields) {
+  if (!obj || typeof obj !== 'object') return obj;
+  const out = {};
+  for (const field of fields) {
+    if (obj[field] !== undefined) out[field] = obj[field];
+  }
+  return out;
+}
+
+function compactRows(rows, fields, truncate = {}) {
+  return asArray(rows).map((row) => {
+    const out = pickFields(row, fields);
+    for (const [field, max] of Object.entries(truncate)) {
+      if (typeof out[field] === 'string') out[field] = out[field].slice(0, max);
+    }
+    return out;
+  });
+}
+
+/**
+ * 阶段摘要只给“跨文件引用需要的最小信息”，不把前几个文件全文再塞一遍。
+ * 30-cast 的 characters/foreshadows/payoffs 等文件很容易到几十 KB；
+ * 如果把全文级联进最后一个 information.json 提示词，单次请求会超过模型上下文。
+ */
+const CAST_DIGEST_FILES = {
+  'characters.json': [],
+  'factions.json': [],
+  'locations.json': ['factions.json'],
+  'items.json': ['characters.json', 'factions.json', 'locations.json'],
+  'conflicts.json': ['characters.json', 'factions.json', 'locations.json', 'items.json'],
+  'foreshadows.json': ['characters.json', 'conflicts.json'],
+  'climaxes.json': ['characters.json', 'factions.json', 'conflicts.json', 'foreshadows.json'],
+  'payoffs.json': ['foreshadows.json', 'climaxes.json', 'conflicts.json'],
+  'relations.json': ['characters.json', 'factions.json'],
+  'information.json': ['characters.json', 'conflicts.json'],
+};
+
+function compactCastDigest(name, data) {
+  if (name === 'characters.json') {
+    return { characters: compactRows(data.characters, ['id', 'name', 'type', 'faction', 'role_slot']) };
+  }
+  if (name === 'factions.json') return { factions: compactRows(data.factions, ['id', 'name', 'type']) };
+  if (name === 'locations.json') return { locations: compactRows(data.locations, ['id', 'name', 'type']) };
+  if (name === 'items.json') return { items: compactRows(data.items, ['id', 'name', 'category', 'owner']) };
+  if (name === 'conflicts.json') {
+    return { conflicts: compactRows(data.conflicts, ['id', 'name', 'type', 'participants']) };
+  }
+  if (name === 'foreshadows.json') {
+    return { foreshadows: compactRows(data.foreshadows, ['id', 'name', 'type', 'scope']) };
+  }
+  if (name === 'climaxes.json') {
+    return { climaxes: compactRows(data.climaxes, ['id', 'name', 'type', 'participants']) };
+  }
+  if (name === 'payoffs.json') {
+    return { payoffs: compactRows(data.payoffs, ['id', 'name', 'type', 'scale', 'required_setup']) };
+  }
+  if (name === 'relations.json') {
+    return {
+      character_relations: compactRows(data.character_relations, ['id', 'from', 'to', 'kind']),
+      faction_relations: compactRows(data.faction_relations, ['id', 'from', 'to', 'kind']),
+      memberships: compactRows(data.memberships, ['id', 'character', 'faction', 'position', 'kind']),
+    };
+  }
+  if (name === 'information.json') {
+    return {
+      information_gaps: compactRows(data.information_gaps, ['id', 'conflict', 'info_name', 'who_knows', 'who_does_not_know']),
+    };
+  }
+  return data;
+}
+
+export function stageDigest(projectRoot, stageId, exclude = [], targetFile = '') {
+  const dir = stageDir(projectRoot, stageId);
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.endsWith('.json') && n !== 'bundle.json' && !exclude.includes(n)).sort();
+  } catch {
+    names = [];
+  }
+  const out = [];
+  const allowed = stageId === '30-cast' && targetFile && CAST_DIGEST_FILES[targetFile]
+    ? new Set(CAST_DIGEST_FILES[targetFile])
+    : null;
+  for (const name of names) {
+    if (allowed && !allowed.has(name)) continue;
+    const data = readJson(path.join(dir, name), null);
+    if (!data) continue;
+    out.push('### ' + name);
+    out.push('```json');
+    const digest = stageId === '30-cast' ? compactCastDigest(name, data) : data;
+    out.push(JSON.stringify(digest));
+    out.push('```');
+  }
+  return out.join('\n');
+}
+
+export function snapshotFiles(files) {
+  const out = {};
+  for (const file of files || []) {
+    out[file] = readText(file, null);
+  }
+  return out;
+}
+
+export function filesChangedSince(files, before) {
+  if (!before || typeof before !== 'object') return true;
+  return (files || []).some((file) => readText(file, null) !== before[file]);
+}
+
+function parseJsonFile(file) {
+  const text = readText(file, null);
+  if (text === null) return { ok: false, error: '文件没有落盘' };
+  try {
+    return { ok: true, data: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, error: 'JSON 解析失败：' + e.message };
+  }
+}
+
+function failureList(errors) {
+  return asArray(errors).map((e) => ({
+    code: e.code || 'VALIDATION',
+    path: e.path || '',
+    message: e.message || e.detail || '',
+    expected: e.expected,
+    actual: e.actual,
+    hint: e.hint,
+  }));
+}
+
+/**
+ * 生成一个 JSON 文件（多次尝试）。
+ */
+export async function generateJsonFile(opts) {
+  const o = opts || {};
+  const target = o.target;
+  const relative = o.relative || path.basename(target);
+  let failures = asArray(o.failures);
+  let lastError = null;
+  for (let attempt = 1; attempt <= (o.maxAttempts || FILE_MAX_ATTEMPTS); attempt += 1) {
+    const before = snapshotFiles([target]);
+    const prompt = o.buildPrompt({ attempt, failures });
+    if (prompt.length > MAX_PROMPT_CHARS) {
+      const error = '提示词过长（' + prompt.length + ' 字符，上限 ' + MAX_PROMPT_CHARS + '），已停止投递，避免触发上下文压缩死循环';
+      if (o.onProgress) o.onProgress(relative + '：' + error);
+      return {
+        ok: false,
+        file: relative,
+        errors: [{ code: 'PROMPT_TOO_LARGE', path: relative, message: error, actual: prompt.length, expected: MAX_PROMPT_CHARS }],
+        error,
+        attempts: attempt,
+      };
+    }
+    const sent = await o.sendPrompt(prompt);
+    if (!sent || sent.ok !== true) {
+      failures = [{ code: 'PROMPT_DELIVERY_FAILED', message: (sent && sent.error) || '提示词投递失败' }];
+      lastError = failures[0].message;
+      if (o.onProgress) o.onProgress(relative + '：提示词投递失败，准备重试');
+      continue;
+    }
+    const waited = await o.waitIdle([target], before);
+    const noChange = waited && waited.code === 'NO_CHANGE';
+    if (!waited || (waited.ok !== true && !noChange)) {
+      lastError = (waited && waited.reason) || '等待 LLM 完成失败';
+      failures = [{ code: (waited && waited.code) || 'NO_OUTPUT', path: relative, message: lastError }];
+      if (waited && ['TIMEOUT', 'ABORTED', 'NO_AGENT'].includes(waited.code)) {
+        return { ok: false, file: relative, errors: failures, error: lastError, attempts: attempt };
+      }
+      if (o.onProgress) o.onProgress(relative + '：' + lastError + '，准备重试');
+      continue;
+    }
+    const parsed = parseJsonFile(target);
+    if (!parsed.ok) {
+      lastError = parsed.error;
+      failures = [{ code: 'INVALID_JSON', path: relative, message: parsed.error }];
+      if (o.onProgress) o.onProgress(relative + '：' + parsed.error + '，准备重试');
+      continue;
+    }
+    if (typeof o.validateFile === 'function') {
+      const report = await o.validateFile(parsed.data, target);
+      if (report && report.ok === true) return { ok: true, file: relative, data: parsed.data, attempts: attempt };
+      if (report && report.ok === false) {
+        // 明确返回“不通过”但没有 errors 时不能当成通过，否则会静默放过坏文件。
+        const reportErrors = Array.isArray(report.errors) && report.errors.length
+          ? report.errors
+          : [{ code: 'VALIDATION_FAILED', path: relative, message: report.error || '校验未通过但没有返回错误明细' }];
+        failures = failureList(reportErrors);
+        lastError = failures[0].message;
+        if (o.onProgress) o.onProgress(relative + '：校验未通过（' + failures.length + ' 个错误），准备重试');
+        continue;
+      }
+      // 没有 ok 也没有 errors 的旧校验器返回值，保持兼容，视为通过。
+      return { ok: true, file: relative, data: parsed.data, attempts: attempt };
+    }
+    return { ok: true, file: relative, data: parsed.data, attempts: attempt };
+  }
+  return { ok: false, file: relative, errors: failures, error: lastError || '生成失败', attempts: o.maxAttempts || FILE_MAX_ATTEMPTS };
+}
+
+/**
+ * 按阶段文件清单生成缺失文件，再跑整阶段校验；失败时把错误归因到文件并重试。
+ */
+export async function generateStageFiles(opts) {
+  const o = opts || {};
+  const { projectRoot, stageId } = o;
+  const files = asArray(o.files);
+  const reports = [];
+  let failures = [];
+  for (let round = 1; round <= (o.maxRounds || 2); round += 1) {
+    for (const spec of files) {
+      const target = stageFile(projectRoot, stageId, spec.file);
+      if (fs.existsSync(target) && !o.force && isValidJsonFile(target)) continue;
+      const extraParts = [];
+      if (o.includeStageDigest) {
+        const digest = stageDigest(projectRoot, stageId, [path.basename(spec.file)], path.basename(spec.file));
+        if (digest) {
+          extraParts.push('## 本阶段已生成的文件（必须与它们保持一致）');
+          extraParts.push('');
+          extraParts.push(digest);
+        }
+      }
+      if (spec.extra) extraParts.push(spec.extra);
+      const result = await generateJsonFile({
+        target,
+        relative: spec.file,
+        failures,
+        sendPrompt: o.sendPrompt,
+        waitIdle: o.waitIdle,
+        onProgress: o.onProgress,
+        maxAttempts: o.maxAttempts,
+        buildPrompt: ({ attempt, failures: f }) => o.buildPrompt({
+          stageId,
+          file: spec.file,
+          templateFile: spec.templateFile,
+          attempt,
+          failures: f,
+          extra: extraParts.join('\n'),
+        }),
+      });
+      reports.push(result);
+      if (!result.ok) {
+        // 单文件都写不出来，后面的文件没有继续生成的意义
+        return { ok: false, files: reports, errors: asArray(result.errors), error: result.error };
+      }
+    }
+    if (typeof o.validateStage !== 'function') return { ok: true, files: reports, errors: [] };
+    const report = await o.validateStage();
+    if (report && report.ok) return { ok: true, files: reports, errors: [], report };
+    failures = failureList(report && report.errors);
+    if (!failures.length) return { ok: false, files: reports, errors: [], error: '阶段校验失败但没有返回错误' };
+    if (o.onProgress) o.onProgress(stageId + '：整阶段校验未通过（' + failures.length + ' 个错误），准备按文件回改');
+    // 下一轮强制重生成被错误点名的文件
+    o.force = false;
+    const named = new Set();
+    for (const e of failures) {
+      const p = String(e.path || '');
+      for (const spec of files) {
+        if (p.startsWith(spec.file.replace(/\.json$/, '')) || p.includes(spec.file)) named.add(spec.file);
+      }
+    }
+    if (!named.size) return { ok: false, files: reports, errors: failures, error: '无法把校验错误归因到具体文件' };
+    for (const spec of files) {
+      if (named.has(spec.file)) {
+        const target = stageFile(projectRoot, stageId, spec.file);
+        try {
+          if (fs.existsSync(target)) fs.unlinkSync(target);
+        } catch {
+          // 删不掉就覆盖
+        }
+      }
+    }
+  }
+  const final = typeof o.validateStage === 'function' ? await o.validateStage() : { ok: true, errors: [] };
+  return { ok: Boolean(final && final.ok), files: reports, errors: failureList(final && final.errors), error: final && final.ok ? null : '阶段校验未通过', report: final };
+}
+
+function normalizeChapterShard(data, volume, startCh, endCh, scale) {
+  const raw = Array.isArray(data) ? data : asArray(data && data.chapters);
+  const acts = asArray(scale && scale.structure && scale.structure.acts);
+  const avg = Number(scale && scale.capacity && scale.capacity.avg_words_per_chapter) || 3000;
+  const chapters = [];
+  for (let i = 0; i < raw.length; i += 1) {
+    const row = raw[i] || {};
+    const displayNo = startCh + i;
+    if (displayNo > endCh) break;
+    const act = acts.find((a) => Number(a.chapter_start) <= displayNo && Number(a.chapter_end) >= displayNo);
+    chapters.push({
+      ...row,
+      chapter_id: row.chapter_id || ('CH' + pad3(displayNo)),
+      display_no: displayNo,
+      title: row.title || ('第 ' + displayNo + ' 章'),
+      volume: volume.volume_id,
+      act: act ? act.act_id : (row.act || ''),
+      word_target: Number(row.word_target) > 0 ? Number(row.word_target) : avg,
+    });
+  }
+  return { chapters };
+}
+
+/**
+ * 生成章节地图：按卷分片 → 合并 → 校验 → 按卷回改。
+ */
+export const CHAPTER_MAP_CHUNK_SIZE = 20;
+
+function chunkRanges(start, end, size = CHAPTER_MAP_CHUNK_SIZE) {
+  const out = [];
+  let s = Number(start);
+  const e = Number(end);
+  let i = 0;
+  while (s <= e) {
+    const chunkEnd = Math.min(e, s + size - 1);
+    i += 1;
+    out.push({ index: i, start: s, end: chunkEnd });
+    s = chunkEnd + 1;
+  }
+  return out;
+}
+
+function readVolumeChapters(shardDir, volumeId) {
+  // chunk 文件才是真源；V001.json 只是合并缓存。
+  // 先读 chunk，避免返工某个 chunk 后仍读到旧的整卷缓存。
+  let names = [];
+  try {
+    names = fs.readdirSync(shardDir)
+      .filter((n) => /^V\d{3}-\d{2}\.json$/.test(n) && n.startsWith(volumeId + '-'))
+      .sort();
+  } catch {
+    names = [];
+  }
+  const out = [];
+  for (const name of names) {
+    const data = readJson(path.join(shardDir, name), null);
+    if (data && Array.isArray(data.chapters)) out.push(...data.chapters);
+  }
+  if (out.length) return out;
+  const full = readJson(path.join(shardDir, volumeId + '.json'), null);
+  return full && Array.isArray(full.chapters) ? full.chapters : [];
+}
+
+function chapterMapProgress(shardDir, volumes, size = CHAPTER_MAP_CHUNK_SIZE) {
+  const completed = [];
+  const pending = [];
+  for (const v of volumes) {
+    const ranges = chunkRanges(v.chapter_start, v.chapter_end, size);
+    const missing = ranges.filter((r) => {
+      const name = v.volume_id + '-' + String(r.index).padStart(2, '0') + '.json';
+      return !isValidJsonFile(path.join(shardDir, name));
+    });
+    if (missing.length) pending.push(v.volume_id);
+    else completed.push(v.volume_id);
+  }
+  let chunkFiles = [];
+  try { chunkFiles = fs.readdirSync(shardDir).filter((n) => /^V\d{3}-\d{2}\.json$/.test(n)).sort(); } catch { chunkFiles = []; }
+  return { completed, pending, chunks: chunkFiles.length, chunkFiles };
+}
+
+/**
+ * word_target 是数字目标，不是剧情内容；合并后按目标总字数做一次确定性
+ * 配平，避免 LLM 每章多写 3% 就把整张地图判为失败并触发无意义重生成。
+ */
+function balanceWordTargets(chapters, targetWords) {
+  const target = Number(targetWords);
+  if (!Number.isFinite(target) || target <= 0) return;
+  const rows = asArray(chapters).filter((c) => Number.isInteger(Number(c.word_target)) && Number(c.word_target) > 0);
+  if (!rows.length || rows.length !== asArray(chapters).length) return;
+  const sum = rows.reduce((total, c) => total + Number(c.word_target), 0);
+  if (sum === target) return;
+
+  // 按目标总字数等比缩放，但取整到 50 字，避免配平后出现 2122、2323
+  // 这类明显不是作者设定的数字；最后用 50 字为单位把误差摊平。
+  const unit = 50;
+  const ratio = target / sum;
+  for (const c of rows) {
+    c.word_target = Math.max(unit, Math.round((Number(c.word_target) * ratio) / unit) * unit);
+  }
+  let diff = target - rows.reduce((total, c) => total + Number(c.word_target), 0);
+  let i = 0;
+  let guard = 0;
+  while (diff !== 0 && guard < rows.length * 8) {
+    const c = rows[i % rows.length];
+    const step = diff > 0 ? unit : -unit;
+    if (diff < 0 && c.word_target <= unit) {
+      i += 1;
+      guard += 1;
+      continue;
+    }
+    c.word_target += step;
+    diff -= step;
+    i += 1;
+    guard += 1;
+  }
+  if (diff !== 0) {
+    const last = rows[rows.length - 1];
+    last.word_target = Math.max(1, Number(last.word_target) + diff);
+  }
+}
+
+function chunkRangeForName(volumes, chunkName, size) {
+  const m = /^(V\d{3})-(\d{2})$/.exec(String(chunkName || ''));
+  if (!m) return null;
+  const volume = volumes.find((v) => v.volume_id === m[1]);
+  if (!volume) return null;
+  const index = Number(m[2]);
+  const start = Number(volume.chapter_start) + (index - 1) * size;
+  if (!index || start > Number(volume.chapter_end)) return null;
+  return {
+    volumeId: volume.volume_id,
+    index,
+    start,
+    end: Math.min(Number(volume.chapter_end), start + size - 1),
+  };
+}
+
+/**
+ * 从旧的 chapter_map.json 抢救分片。
+ *
+ * 旧版本先写最终地图再校验，校验失败后又删掉全部分片；此时最终地图里
+ * 其实保留了上一轮的完整内容。非 --force 重跑时，把缺失的 chunk 用它
+ * 补回来，避免用户为了一次校验失败重写整本书。
+ */
+function seedChunksFromChapterMap(dir, shardDir, volumes, size) {
+  const map = readJson(path.join(dir, 'chapter_map.json'), null);
+  if (!map || !Array.isArray(map.chapters) || !map.chapters.length) return;
+  const byDisplay = new Map();
+  for (const c of map.chapters) {
+    const n = Number(c && c.display_no);
+    if (Number.isFinite(n)) byDisplay.set(n, c);
+  }
+  for (const volume of volumes) {
+    for (const range of chunkRanges(volume.chapter_start, volume.chapter_end, size)) {
+      const name = volume.volume_id + '-' + String(range.index).padStart(2, '0');
+      const target = path.join(shardDir, name + '.json');
+      if (isValidJsonFile(target)) continue;
+      const rows = [];
+      for (let n = range.start; n <= range.end; n += 1) {
+        const row = byDisplay.get(n);
+        if (!row) break;
+        rows.push(row);
+      }
+      if (rows.length === range.end - range.start + 1) {
+        writeJsonAtomic(target, { chapters: rows });
+      }
+    }
+  }
+}
+
+function chunkForDisplay(volumes, displayNo, size) {
+  const n = Number(displayNo);
+  if (!Number.isFinite(n)) return '';
+  for (const v of volumes) {
+    if (n >= Number(v.chapter_start) && n <= Number(v.chapter_end)) {
+      const index = Math.floor((n - Number(v.chapter_start)) / size) + 1;
+      return v.volume_id + '-' + String(index).padStart(2, '0');
+    }
+  }
+  return '';
+}
+
+function cnNumber(text) {
+  const s = String(text || '').trim();
+  if (/^\d+$/.test(s)) return Number(s);
+  const digit = { 一: 1, 二: 2, 两: 2, 三: 3, 四: 4, 五: 5, 六: 6, 七: 7, 八: 8, 九: 9 };
+  if (s === '十') return 10;
+  let m = /^十([一二三四五六七八九])$/.exec(s);
+  if (m) return 10 + digit[m[1]];
+  m = /^([一二三四五六七八九])十([一二三四五六七八九])?$/.exec(s);
+  if (m) return digit[m[1]] * 10 + (m[2] ? digit[m[2]] : 0);
+  return digit[s] || 0;
+}
+
+function volumeFromText(text, volumes) {
+  const s = String(text || '');
+  let m = /V(\d{3})/i.exec(s);
+  if (m) {
+    const id = 'V' + m[1];
+    const hit = volumes.find((v) => v.volume_id === id);
+    if (hit) return hit;
+  }
+  m = /第\s*([一二三四五六七八九十两\d]+)\s*卷/.exec(s);
+  if (m) {
+    const n = cnNumber(m[1]);
+    const ordered = [...volumes].sort((a, b) => Number(a.chapter_start) - Number(b.chapter_start));
+    if (n >= 1 && n <= ordered.length) return ordered[n - 1];
+  }
+  return null;
+}
+
+function referenceDisplays(chapters, kind, id) {
+  const out = [];
+  for (const c of asArray(chapters)) {
+    const display = Number(c.display_no);
+    if (!Number.isFinite(display)) continue;
+    let hit = false;
+    if (kind === 'foreshadow') hit = asArray(c.foreshadow_actions).some((a) => a && a.id === id);
+    else if (kind === 'payoff') hit = asArray(c.payoff_actions).some((a) => a && a.id === id);
+    else if (kind === 'info') hit = asArray(c.information_gaps).some((a) => a && a.id === id);
+    else if (kind === 'main') hit = asArray(c.why && c.why.main_line_nodes).some((x) => x === id);
+    else if (kind === 'branch') hit = asArray(c.why && c.why.branch_nodes).some((x) => String(x).startsWith(id));
+    else if (kind === 'conflict') hit = asArray(c.why && c.why.conflict).some((x) => x === id);
+    else if (kind === 'ending') hit = asArray(c.ending_actions).some((a) => a && a.id === id);
+    if (hit) out.push(display);
+  }
+  return out;
+}
+
+/**
+ * 给“没有章节落点”的实体猜一个修复落点。
+ *
+ * 只用于生成返工目标，不直接改地图；优先用实体自带的卷/幕/回收要求，
+ * 其次用它在章节地图里已有的最早/最晚落点。
+ */
+function entityVolumeHint(kind, id, ctx) {
+  const { chapters, volumes, cast, macro } = ctx;
+  const refs = referenceDisplays(chapters, kind, id);
+  const first = refs.length ? refs[0] : null;
+  const last = refs.length ? refs[refs.length - 1] : null;
+  if (kind === 'main') {
+    const node = asArray(macro && macro.lines && macro.lines.main_line && macro.lines.main_line.nodes)
+      .find((n) => n && n.id === id);
+    const volume = node && node.volume ? volumes.find((v) => v.volume_id === node.volume) : null;
+    if (volume) return { displayNo: Number(volume.chapter_start), reason: '主线节点所在卷的开头' };
+  }
+  if (kind === 'branch') {
+    const branch = asArray(macro && macro.lines && macro.lines.branches).find((x) => x && x.id === id);
+    const volume = branch && branch.start ? volumeFromText(branch.start, volumes) : null;
+    if (volume) return { displayNo: Number(volume.chapter_start), reason: '支线开始卷的开头' };
+  }
+  if (kind === 'foreshadow') {
+    const row = asArray(cast && cast.foreshadows && cast.foreshadows.foreshadows).find((x) => x && x.id === id);
+    const text = [row && row.setup, row && row.recovery_requirement, row && row.payoff_target].filter(Boolean).join(' ');
+    const volume = volumeFromText(text, volumes);
+    if (volume) {
+      const late = /后段|末|结束|结尾/.test(text);
+      return {
+        displayNo: late ? Number(volume.chapter_end) : Number(volume.chapter_start),
+        reason: late ? '伏笔回收要求指向该卷后段' : '伏笔回收要求指向该卷开头',
+      };
+    }
+  }
+  if (kind === 'payoff') {
+    const row = asArray(cast && cast.payoffs && cast.payoffs.payoffs).find((x) => x && x.id === id);
+    for (const setupId of asArray(row && row.required_setup)) {
+      if (/^FS\d+/.test(String(setupId))) {
+        const fsRow = asArray(cast && cast.foreshadows && cast.foreshadows.foreshadows)
+          .find((x) => x && x.id === setupId);
+        const text = [fsRow && fsRow.setup, fsRow && fsRow.recovery_requirement, fsRow && fsRow.payoff_target].filter(Boolean).join(' ');
+        const volume = volumeFromText(text, volumes);
+        if (volume) return { displayNo: Number(volume.chapter_end), reason: '爽点依赖的伏笔落在该卷，优先放到卷末' };
+        const setupRefs = referenceDisplays(chapters, 'foreshadow', setupId);
+        if (setupRefs.length) return { displayNo: setupRefs[setupRefs.length - 1], reason: '爽点依赖的伏笔最后一次出现处' };
+      }
+      if (/^CL\d+/.test(String(setupId))) {
+        const cl = asArray(cast && cast.climaxes && cast.climaxes.climaxes).find((x) => x && x.id === setupId);
+        const volume = cl && cl.volume ? volumes.find((v) => v.volume_id === cl.volume) : null;
+        if (volume) return { displayNo: Number(volume.chapter_end), reason: '爽点依赖的高潮所在卷的卷末' };
+      }
+    }
+    const ownVolume = volumeFromText([row && row.setup, row && row.payoff].filter(Boolean).join(' '), volumes);
+    if (ownVolume) return { displayNo: Number(ownVolume.chapter_end), reason: '爽点文本指向该卷' };
+  }
+  if (kind === 'info') {
+    const row = asArray(cast && cast.information && cast.information.information_gaps).find((x) => x && x.id === id);
+    const conflictRefs = row && row.conflict ? referenceDisplays(chapters, 'conflict', row.conflict) : [];
+    if (conflictRefs.length) return { displayNo: conflictRefs[0], reason: '信息差依附的冲突首次出现处' };
+    const conflict = asArray(cast && cast.conflicts && cast.conflicts.conflicts).find((x) => x && x.id === (row && row.conflict));
+    const volume = volumeFromText([conflict && conflict.description, conflict && conflict.stakes].filter(Boolean).join(' '), volumes);
+    if (volume) return { displayNo: Number(volume.chapter_start), reason: '信息差依附的冲突所在卷' };
+  }
+  if (kind === 'conflict') {
+    const row = asArray(cast && cast.conflicts && cast.conflicts.conflicts).find((x) => x && x.id === id);
+    const volume = volumeFromText([row && row.description, row && row.stakes].filter(Boolean).join(' '), volumes);
+    if (volume) return { displayNo: Number(volume.chapter_start), reason: '冲突文本指向该卷' };
+  }
+  if (first !== null) return { displayNo: first, reason: '实体在章节地图里已有落点' };
+  if (last !== null) return { displayNo: last, reason: '实体在章节地图里已有落点' };
+  return null;
+}
+
+function parseMissingIds(message, actual) {
+  if (Array.isArray(actual) && actual.length) return actual.map(String);
+  const s = String(message || '');
+  const idx = s.lastIndexOf('：');
+  if (idx < 0) return [];
+  return s.slice(idx + 1)
+    .split('、')
+    .map((x) => x.replace(/….*$/, '').trim())
+    .filter((x) => /^[A-Z]{1,4}\d{2,}/.test(x));
+}
+
+/**
+ * 把整张地图的校验错误映射到“该返工哪个 chunk”。
+ * 无法定位到任何 chunk 的错误保留在 failures 里，交给调用方报给用户；
+ * 绝不能因为一条全局错误就删掉所有分片。
+ */
+function planChapterMapRepairs(failures, ctx) {
+  const plan = new Map();
+  const add = (chunk, failure) => {
+    if (!chunk) return;
+    if (!plan.has(chunk)) plan.set(chunk, []);
+    plan.get(chunk).push(failure);
+  };
+  for (const e of asArray(failures)) {
+    const p = String(e.path || '');
+    const m = /^chapter_map\.chapters\[(\d+)\]/.exec(p);
+    if (m) {
+      const idx = Number(m[1]);
+      const chapter = ctx.chapters[idx];
+      const display = Number(chapter && chapter.display_no !== undefined ? chapter.display_no : idx + 1);
+      const chunk = chunkForDisplay(ctx.volumes, display, ctx.size);
+      const range = chunkRangeForName(ctx.volumes, chunk, ctx.size);
+      const local = range ? display - range.start : idx;
+      add(chunk, {
+        ...e,
+        path: 'chapters[' + local + ']' + p.slice(m[0].length),
+        message: '第 ' + display + ' 章：' + (e.message || ''),
+      });
+      continue;
+    }
+    if (e.code === 'RHYTHM_CHAPTER_GAP') {
+      const gap = /缺少第\s*(\d+)\s*章/.exec(e.message || '');
+      if (gap) add(chunkForDisplay(ctx.volumes, Number(gap[1]), ctx.size), e);
+      continue;
+    }
+    if (e.code === 'RHYTHM_FORESHADOW_ORDER') {
+      const id = (/：\s*(FS\d{3})/.exec(e.message || '') || [])[1];
+      const hint = id ? entityVolumeHint('foreshadow', id, ctx) : null;
+      const target = hint ? hint.displayNo : null;
+      add(chunkForDisplay(ctx.volumes, target, ctx.size), {
+        ...e,
+        message: (e.message || '') + (hint
+          ? '；本 chunk 必须在回收之前补一次 `埋设`（推荐落点：第 ' + target + ' 章附近）'
+          : '；本 chunk 必须补一次 `埋设`'),
+      });
+      continue;
+    }
+    if (['RHYTHM_MAIN_COVERAGE', 'RHYTHM_BRANCH_COVERAGE', 'RHYTHM_CONFLICT_COVERAGE',
+      'RHYTHM_FORESHADOW_COVERAGE', 'RHYTHM_PAYOFF_COVERAGE', 'RHYTHM_INFO_COVERAGE',
+      'RHYTHM_ENDING_COVERAGE'].includes(e.code)) {
+      const kind = e.code.includes('PAYOFF') ? 'payoff'
+        : e.code.includes('FORESHADOW') ? 'foreshadow'
+          : e.code.includes('INFO') ? 'info'
+            : e.code.includes('MAIN') ? 'main'
+              : e.code.includes('BRANCH') ? 'branch'
+                : e.code.includes('ENDING') ? 'ending' : 'conflict';
+      for (const id of parseMissingIds(e.message, e.actual)) {
+        const hint = entityVolumeHint(kind, id, ctx);
+        if (!hint) continue;
+        add(chunkForDisplay(ctx.volumes, hint.displayNo, ctx.size), {
+          ...e,
+          message: (e.message || '') + '；本 chunk 必须为 ' + id + ' 补一次落点（推荐：第 ' + hint.displayNo + ' 章附近，' + hint.reason + '）',
+        });
+      }
+    }
+  }
+  return plan;
+}
+
+
+/**
+ * 生成章节地图：按卷再按 chunk（默认 20 章）拆分。
+ * 单个 100 章卷会一次生成 20 章左右，避免一个 turn 输出 200KB+ 导致超时。
+ */
+function writeChapterMapFinal(dir, merged) {
+  const chapterMap = {
+    _meta: {
+      schema_version: '2.1',
+      node_id: '40-rhythm.chapter_map',
+      stage: '40-rhythm',
+      generated_at: nowIso(),
+    },
+    chapters: merged,
+  };
+  const index = {
+    _meta: { schema_version: '2.1', node_id: '40-rhythm.index', stage: '40-rhythm' },
+    chapters: merged.map((c) => ({
+      chapter_id: c.chapter_id,
+      display_no: c.display_no,
+      title: c.title,
+      volume: c.volume,
+      act: c.act,
+      path: 'outlines/' + c.chapter_id + '.json',
+      status: c.status || 'draft',
+    })),
+  };
+  writeJsonAtomic(path.join(dir, 'chapter_map.json'), chapterMap);
+  writeJsonAtomic(path.join(dir, 'index.json'), index);
+  return chapterMap;
+}
+
+/**
+ * 生成章节地图：按卷再按 chunk（默认 20 章）拆分。
+ * 单个 100 章卷会一次生成 20 章左右，避免一个 turn 输出 200KB+ 导致超时。
+ *
+ * 关键顺序：先在内存合并候选地图并校验，通过后才写 chapter_map.json。
+ * 校验失败时只返工错误能定位到的 chunk，不删除任何合法分片。
+ */
+export async function generateChapterMap(opts) {
+  const o = opts || {};
+  const { projectRoot, scale } = o;
+  const dir = stageDir(projectRoot, '40-rhythm');
+  const shardDir = path.join(dir, '.chapter-map');
+  ensureDir(shardDir);
+  const volumes = asArray(scale && scale.structure && scale.structure.volumes);
+  const chunkSize = Number(o.chunkSize) > 0 ? Number(o.chunkSize) : CHAPTER_MAP_CHUNK_SIZE;
+  if (!o.force) seedChunksFromChapterMap(dir, shardDir, volumes, chunkSize);
+  const targetWords = scale && scale.capacity && scale.capacity.target_words;
+  const macro = readJson(path.join(dir, '_context', 'macro.json'), null);
+  const cast = readJson(path.join(dir, '_context', 'cast.json'), null);
+  const reports = [];
+  let failures = [];
+  const progressNow = () => chapterMapProgress(shardDir, volumes, chunkSize);
+  const failed = (error) => ({
+    ok: false,
+    files: reports,
+    errors: failures,
+    error,
+    progress: progressNow(),
+  });
+
+  for (let round = 1; round <= 2; round += 1) {
+    // 只有首轮 --force 才重做全部 chunk；返工轮只补缺失/无效 chunk。
+    const forceThisRound = Boolean(o.force) && round === 1;
+    for (const volume of volumes) {
+      const fullTarget = path.join(shardDir, volume.volume_id + '.json');
+      const ranges = chunkRanges(volume.chapter_start, volume.chapter_end, chunkSize);
+      for (const range of ranges) {
+        const shardName = volume.volume_id + '-' + String(range.index).padStart(2, '0');
+        const target = path.join(shardDir, shardName + '.json');
+        if (!forceThisRound && isValidJsonFile(target)) continue;
+        let previous = readVolumeChapters(shardDir, volume.volume_id)
+          .filter((c) => Number(c.display_no) < range.start)
+          .slice(-2);
+        if (!previous.length) {
+          const vi = volumes.findIndex((v) => v.volume_id === volume.volume_id);
+          const prevVolume = vi > 0 ? volumes[vi - 1] : null;
+          if (prevVolume) previous = readVolumeChapters(shardDir, prevVolume.volume_id).slice(-2);
+        }
+        const existing = previous
+          .map((c) => '第 ' + c.display_no + ' 章：' + (c.title || '') + ' / ' + JSON.stringify(c.how || {}))
+          .join('\n');
+        const result = await generateJsonFile({
+          target,
+          relative: '.chapter-map/' + shardName + '.json',
+          sendPrompt: o.sendPrompt,
+          waitIdle: o.waitIdle,
+          onProgress: o.onProgress,
+          failures: [],
+          buildPrompt: ({ attempt, failures: f }) => buildChapterMapPrompt({
+            projectRoot,
+            volumes: shardName,
+            volumeId: volume.volume_id,
+            startCh: range.start,
+            endCh: range.end,
+            attempt,
+            failures: f,
+            existing,
+          }),
+        });
+        reports.push(result);
+        if (!result.ok) {
+          return {
+            ok: false,
+            files: reports,
+            errors: asArray(result.errors),
+            error: result.error,
+            progress: progressNow(),
+          };
+        }
+      }
+      // 把本卷所有 chunk 合并成整卷缓存，兼容人工检查和旧逻辑。
+      const chapters = readVolumeChapters(shardDir, volume.volume_id);
+      if (chapters.length) writeJsonAtomic(fullTarget, { chapters });
+    }
+
+    // 合并候选地图：先从 chunk 读，绝不把旧 chapter_map.json 当输入。
+    const merged = [];
+    for (const volume of volumes) {
+      const normalized = normalizeChapterShard(
+        { chapters: readVolumeChapters(shardDir, volume.volume_id) },
+        volume,
+        volume.chapter_start,
+        volume.chapter_end,
+        scale,
+      );
+      merged.push(...normalized.chapters);
+    }
+    merged.sort((a, b) => a.display_no - b.display_no);
+    balanceWordTargets(merged, targetWords);
+    const chapterMap = {
+      _meta: {
+        schema_version: '2.1',
+        node_id: '40-rhythm.chapter_map',
+        stage: '40-rhythm',
+        generated_at: nowIso(),
+      },
+      chapters: merged,
+    };
+
+    if (typeof o.validateMap !== 'function') {
+      writeChapterMapFinal(dir, merged);
+      return { ok: true, files: reports, errors: [], chapterMap, progress: progressNow() };
+    }
+    const report = await o.validateMap(chapterMap);
+    if (report && report.ok) {
+      writeChapterMapFinal(dir, merged);
+      return { ok: true, files: reports, errors: [], chapterMap, report, progress: progressNow() };
+    }
+    failures = failureList(report && report.errors);
+    if (!failures.length) {
+      return { ok: false, files: reports, errors: [], error: '章节地图校验失败但没有错误', progress: progressNow() };
+    }
+    if (round >= 2) break;
+
+    const plan = planChapterMapRepairs(failures, {
+      chapters: merged,
+      volumes,
+      cast,
+      macro,
+      size: chunkSize,
+    });
+    if (!plan.size) {
+      return failed('章节地图校验未通过，且错误无法定位到具体 chunk；所有分片已保留，chapter_map.json 未写入。');
+    }
+    if (o.onProgress) {
+      o.onProgress('40-rhythm：章节地图校验未通过（' + failures.length + ' 个错误），只返工 ' + plan.size + ' 个 chunk：' + [...plan.keys()].join('、'));
+    }
+    for (const [chunk, chunkFailures] of plan) {
+      const range = chunkRangeForName(volumes, chunk, chunkSize);
+      const target = path.join(shardDir, chunk + '.json');
+      const current = readJson(target, null);
+      if (!range || !current || !Array.isArray(current.chapters)) continue;
+      const result = await generateJsonFile({
+        target,
+        relative: '.chapter-map/' + chunk + '.json',
+        sendPrompt: o.sendPrompt,
+        waitIdle: o.waitIdle,
+        onProgress: o.onProgress,
+        failures: chunkFailures,
+        buildPrompt: ({ attempt, failures: f }) => buildChapterMapPrompt({
+          projectRoot,
+          volumes: chunk,
+          volumeId: range.volumeId,
+          startCh: range.start,
+          endCh: range.end,
+          attempt,
+          failures: f,
+          existing: '',
+          currentChunk: current,
+        }),
+      });
+      reports.push(result);
+      if (!result.ok) {
+        return {
+          ok: false,
+          files: reports,
+          errors: asArray(result.errors),
+          error: result.error,
+          progress: progressNow(),
+        };
+      }
+    }
+    // 返工后刷新受影响卷的整卷缓存。
+    const touched = new Set([...plan.keys()].map((name) => name.split('-')[0]));
+    for (const volumeId of touched) {
+      const volume = volumes.find((v) => v.volume_id === volumeId);
+      if (!volume) continue;
+      const chapters = readVolumeChapters(shardDir, volume.volume_id);
+      if (chapters.length) writeJsonAtomic(path.join(shardDir, volume.volume_id + '.json'), { chapters });
+    }
+  }
+  return failed('章节地图校验未通过；分片已保留，chapter_map.json 未更新。');
+}
+
+
+/** 找出需要生成细纲的章节。 */
+export function pendingOutlineChapters(projectRoot, chapterMap, opts = {}) {
+  const dir = stageDir(projectRoot, '40-rhythm');
+  const only = opts.chapterIds ? new Set(opts.chapterIds.map((x) => String(x))) : null;
+  const out = [];
+  for (const c of asArray(chapterMap && chapterMap.chapters)) {
+    if (!c || c.status === 'archived') continue;
+    const id = c.chapter_id;
+    if (!id) continue;
+    if (only && !only.has(id) && !only.has(String(c.display_no))) continue;
+    const file = path.join(dir, 'outlines', id + '.json');
+    if (opts.force || !isValidJsonFile(file)) out.push(c);
+  }
+  return out;
+}
+
+/**
+ * 逐章生成细纲。
+ */
+export async function generateOutlines(opts) {
+  const o = opts || {};
+  const { projectRoot, chapterMap, validateOutline } = o;
+  const dir = stageDir(projectRoot, '40-rhythm');
+  ensureDir(path.join(dir, 'outlines'));
+  const pending = pendingOutlineChapters(projectRoot, chapterMap, o);
+  const reports = [];
+  const chapters = asArray(chapterMap && chapterMap.chapters);
+  for (const c of pending) {
+    const target = path.join(dir, 'outlines', c.chapter_id + '.json');
+    const idx = chapters.findIndex((x) => x.chapter_id === c.chapter_id);
+    const prev = idx > 0 ? chapters[idx - 1] : null;
+    const next = idx >= 0 && idx < chapters.length - 1 ? chapters[idx + 1] : null;
+    const prevSummary = prev ? ('第 ' + prev.display_no + ' 章《' + prev.title + '》\n' + JSON.stringify(prev.how || {}, null, 2)) : '';
+    const nextSummary = next ? ('第 ' + next.display_no + ' 章《' + next.title + '》\n' + JSON.stringify(next.how || {}, null, 2)) : '';
+    const result = await generateJsonFile({
+      target,
+      relative: 'outlines/' + c.chapter_id + '.json',
+      sendPrompt: o.sendPrompt,
+      waitIdle: o.waitIdle,
+      onProgress: o.onProgress,
+      validateFile: async (data) => {
+        if (typeof validateOutline !== 'function') return { ok: true, errors: [] };
+        return validateOutline(data, c);
+      },
+      buildPrompt: ({ attempt, failures }) => buildOutlinePrompt({
+        projectRoot,
+        chapter: c,
+        chapterMap: c,
+        previous: prevSummary,
+        next: nextSummary,
+        macroDigest: o.macroDigest,
+        castDigest: o.castDigest,
+        attempt,
+        failures,
+      }),
+    });
+    reports.push(result);
+    if (!result.ok) return { ok: false, files: reports, errors: asArray(result.errors), error: result.error, failedChapter: c.chapter_id };
+  }
+  return { ok: true, files: reports, errors: [] };
+}
+
+/** 找出缺正文的章节。 */
+export function pendingWritingChapters(projectRoot, chapterMap, opts = {}) {
+  const dir = path.join(stageDir(projectRoot, '50-writing'), 'chapters');
+  const only = opts.chapterIds ? new Set(opts.chapterIds.map((x) => String(x))) : null;
+  const out = [];
+  for (const c of asArray(chapterMap && chapterMap.chapters)) {
+    if (!c || c.status === 'archived') continue;
+    if (only && !only.has(c.chapter_id) && !only.has(String(c.display_no))) continue;
+    const file = path.join(dir, chapterFileName(c.display_no));
+    if (opts.force || !fs.existsSync(file)) out.push(c);
+  }
+  return out;
+}
+
+export function chapterFileName(displayNo) {
+  return '第' + String(displayNo).padStart(3, '0') + '章.md';
+}
+
+/**
+ * 按批生成正文。
+ */
+export async function generateWriting(opts) {
+  const o = opts || {};
+  const { projectRoot, chapterMap, outlines, dossiers, validateChapters } = o;
+  const dir = stageDir(projectRoot, '50-writing');
+  ensureDir(path.join(dir, 'chapters'));
+  const pending = pendingWritingChapters(projectRoot, chapterMap, o).sort((a, b) => a.display_no - b.display_no);
+  const batchSize = o.batchSize || 4;
+  const reports = [];
+  for (let i = 0; i < pending.length; i += batchSize) {
+    const batch = pending.slice(i, i + batchSize);
+    const chapters = batch.map((c) => c.display_no);
+    const files = batch.map((c) => path.join(dir, 'chapters', chapterFileName(c.display_no)));
+    const ledgerFile = path.join(dir, 'ledger.json');
+    const allFiles = [...files, ledgerFile];
+    let failures = [];
+    let ok = false;
+    let prevTail = o.prevTail || '';
+    // 每批都从磁盘重新取“上一章结尾”，不能整轮复用同一段前情。
+    const allChapters = asArray(chapterMap && chapterMap.chapters);
+    const firstNo = Math.min(...batch.map((c) => Number(c.display_no)));
+    for (let n = firstNo - 1; n >= 1; n -= 1) {
+      const c = allChapters.find((x) => Number(x.display_no) === n);
+      if (!c) continue;
+      const text = readText(path.join(dir, 'chapters', chapterFileName(n)), null);
+      if (text !== null && text.trim()) {
+        prevTail = text.slice(-500);
+        break;
+      }
+    }
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+      const before = snapshotFiles(allFiles);
+      const prompt = buildWritingPrompt({
+        projectRoot,
+        chapters,
+        outlines,
+        dossiers,
+        prevTail,
+        ledger: readJson(ledgerFile, { chapters: [] }),
+        attempt,
+        failures,
+      });
+      const sent = await o.sendPrompt(prompt);
+      if (!sent || sent.ok !== true) {
+        failures = [{ code: 'PROMPT_DELIVERY_FAILED', message: (sent && sent.error) || '提示词投递失败' }];
+        continue;
+      }
+      const waited = await o.waitIdle(allFiles, before);
+      const noChange = waited && waited.code === 'NO_CHANGE';
+      if (!waited || (waited.ok !== true && !noChange)) {
+        if (waited && ['TIMEOUT', 'ABORTED', 'NO_AGENT'].includes(waited.code)) {
+          reports.push({ ok: false, chapters, error: waited.reason, errors: [{ code: waited.code, message: waited.reason }] });
+          return { ok: false, reports, errors: reports.flatMap((r) => r.errors || []), error: waited.reason };
+        }
+        failures = [{ code: (waited && waited.code) || 'NO_OUTPUT', message: (waited && waited.reason) || '等待 LLM 完成失败' }];
+        continue;
+      }
+      const report = typeof validateChapters === 'function'
+        ? await validateChapters(chapters)
+        : { ok: true, errors: [] };
+      if (report && report.ok) {
+        reports.push({ ok: true, chapters });
+        ok = true;
+        break;
+      }
+      failures = failureList(report && report.errors);
+    }
+    if (!ok) {
+      reports.push({ ok: false, chapters, errors: failures });
+      return { ok: false, reports, errors: failures, error: '正文批次校验未通过' };
+    }
+  }
+  return { ok: true, reports, errors: [] };
+}