@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

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

@@ -0,0 +1,618 @@
+/**
+ * v2/rhythm.js —— 40-rhythm：章节地图 + 可落地细纲。
+ *
+ * 章节地图回答“每章写什么”（5W），细纲回答“这一章具体怎么执行”。
+ * 细纲是一章一文件的自包含契约；章节地图是全局覆盖矩阵。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  asArray,
+  indexById,
+  readJson,
+  v2Error,
+} from './core.js';
+import { eventKey, replayKnowledge, validateKnowledgeSnapshot } from './knowledge.js';
+
+const BRANCH_REGEX = /^(B\d{3})(?:-\d+)?$/;
+
+function requireString(errors, obj, p, field, contract) {
+  const value = obj && obj[field];
+  if (typeof value !== 'string' || !value.trim()) {
+    errors.push(v2Error('RHYTHM_REQUIRED_FIELD', { path: p + '.' + field, message: '缺少必填文本字段', actual: value, contract }));
+  }
+}
+
+function requireArray(errors, obj, p, field, contract, min = 0) {
+  const value = obj && obj[field];
+  if (!Array.isArray(value) || value.length < min) {
+    errors.push(v2Error('RHYTHM_REQUIRED_FIELD', {
+      path: p + '.' + field,
+      message: '必须是至少 ' + min + ' 项的数组',
+      actual: Array.isArray(value) ? value.length : typeof value,
+      contract,
+    }));
+  }
+}
+
+function normAction(value) {
+  const s = String(value || '').trim();
+  if (/埋|plant|setup/i.test(s)) return '埋设';
+  if (/收|recover|payoff|回收/i.test(s)) return '回收';
+  if (/推进|progress/i.test(s)) return '推进';
+  if (/强化|reinforce/i.test(s)) return '强化';
+  return s;
+}
+
+function actionSet(rows) {
+  const out = new Set();
+  for (const row of asArray(rows)) {
+    if (!row) continue;
+    const id = typeof row === 'string' ? row : row.id;
+    if (!id) continue;
+    out.add(id + '|' + (typeof row === 'string' ? '' : normAction(row.action)));
+  }
+  return out;
+}
+
+function actionIds(rows) {
+  return new Set(asArray(rows).map((row) => (typeof row === 'string' ? row : row && row.id)).filter(Boolean));
+}
+
+function outlineCandidates(outline) {
+  const chapter = (outline && outline.chapter) || {};
+  const hard = chapter.hard_constraints || outline.hard_constraints || {};
+  const how = chapter.how || outline.how || {};
+  return { chapter, hard, how };
+}
+
+export function validateRhythm(rhythm, scale, macro, cast, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const docs = rhythm || {};
+  const chapterMap = docs.chapter_map || {};
+  const chapters = asArray(chapterMap.chapters);
+  const T = Number(scale && scale.capacity && scale.capacity.target_chapters);
+  const scaleVolumes = asArray(scale && scale.structure && scale.structure.volumes);
+  const scaleActs = asArray(scale && scale.structure && scale.structure.acts);
+  const volumeById = indexById(scaleVolumes.map((v) => ({ ...v, id: v.volume_id || v.id })));
+  const actById = indexById(scaleActs.map((a) => ({ ...a, id: a.act_id })));
+  const charIds = new Set(asArray(cast && cast.characters && cast.characters.characters).map((c) => c && c.id).filter(Boolean));
+  const locationIds = new Set(asArray(cast && cast.locations && cast.locations.locations).map((l) => l && l.id).filter(Boolean));
+  const conflictIds = new Set(asArray(cast && cast.conflicts && cast.conflicts.conflicts).map((x) => x && x.id).filter(Boolean));
+  const foreshadowIds = new Set(asArray(cast && cast.foreshadows && cast.foreshadows.foreshadows).map((x) => x && x.id).filter(Boolean));
+  const payoffIds = new Set(asArray(cast && cast.payoffs && cast.payoffs.payoffs).map((x) => x && x.id).filter(Boolean));
+  const infoIds = new Set(asArray(cast && cast.information && cast.information.information_gaps).map((x) => x && x.id).filter(Boolean));
+  const mainNodeIds = new Set(asArray(macro && macro.lines && macro.lines.main_line && macro.lines.main_line.nodes).map((n) => n && n.id).filter(Boolean));
+  const branchIds = new Set(asArray(macro && macro.lines && macro.lines.branches).map((b) => b && b.id).filter(Boolean));
+  const endingIds = new Set(asArray(macro && macro.endings && macro.endings.endings).map((e) => e && e.id).filter(Boolean));
+
+  if (!Number.isInteger(T) || T <= 0) {
+    errors.push(v2Error('RHYTHM_SCALE', { path: 'chapter_map.chapters', message: '读不到 scale.capacity.target_chapters，无法校验章节地图', contract: '40-rhythm/README.md' }));
+    return { ok: false, errors, warnings, data: docs };
+  }
+  if (chapters.length !== T) {
+    errors.push(v2Error('RHYTHM_CHAPTER_COUNT', {
+      path: 'chapter_map.chapters',
+      message: '章节地图必须覆盖全部章节',
+      expected: T, actual: chapters.length,
+      contract: '40-rhythm/README.md#chapter-map',
+      reference: '10-scale/scale.json#capacity.target_chapters',
+    }));
+  }
+
+  const byDisplay = new Map();
+  const chapterIdSet = new Set();
+  const displaySeen = new Set();
+  const coveredMain = new Set();
+  const coveredBranch = new Set();
+  const coveredConflict = new Set();
+  const coveredForeshadow = new Set();
+  const coveredPayoff = new Set();
+  const coveredInfo = new Set();
+  const coveredEnding = new Set();
+  const foreshadowFirst = new Map();
+  const payoffFirst = new Map();
+  let wordSum = 0;
+  let prevEmotion = null;
+  const recentEmotions = [];
+
+  for (let i = 0; i < chapters.length; i += 1) {
+    const c = chapters[i] || {};
+    const p = 'chapter_map.chapters[' + i + ']';
+    const displayNo = Number(c.display_no);
+    if (!Number.isInteger(displayNo) || displayNo <= 0) {
+      errors.push(v2Error('RHYTHM_DISPLAY_NO', { path: p + '.display_no', message: 'display_no 必须是正整数', actual: c.display_no, contract: '40-rhythm/README.md#chapter-map' }));
+    } else {
+      if (displayNo < 1 || displayNo > T) {
+        errors.push(v2Error('RHYTHM_DISPLAY_NO_RANGE', { path: p + '.display_no', message: 'display_no 超出 1..T', actual: displayNo, contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      if (displaySeen.has(displayNo)) {
+        errors.push(v2Error('RHYTHM_DISPLAY_NO_DUP', { path: p + '.display_no', message: 'display_no 重复：' + displayNo, contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      displaySeen.add(displayNo);
+      byDisplay.set(displayNo, c);
+    }
+    if (!c.chapter_id) {
+      errors.push(v2Error('RHYTHM_CHAPTER_ID', { path: p + '.chapter_id', message: '缺少稳定 chapter_id', contract: '40-rhythm/README.md#chapter-map' }));
+    } else if (chapterIdSet.has(c.chapter_id)) {
+      errors.push(v2Error('RHYTHM_CHAPTER_ID_DUP', { path: p + '.chapter_id', message: 'chapter_id 重复：' + c.chapter_id, contract: '40-rhythm/README.md#chapter-map' }));
+    } else {
+      chapterIdSet.add(c.chapter_id);
+    }
+    requireString(errors, c, p, 'title', '40-rhythm/README.md#chapter-map');
+
+    // 卷/幕归属
+    const vol = volumeById.get(c.volume);
+    if (!vol) {
+      errors.push(v2Error('RHYTHM_VOLUME_REF', { path: p + '.volume', message: '引用了不存在的卷：' + c.volume, contract: '40-rhythm/README.md#chapter-map' }));
+    } else if (Number.isInteger(displayNo) && (displayNo < Number(vol.chapter_start) || displayNo > Number(vol.chapter_end))) {
+      errors.push(v2Error('RHYTHM_VOLUME_RANGE', {
+        path: p + '.volume',
+        message: '本章不在该卷的章节区间内',
+        expected: vol.chapter_start + '-' + vol.chapter_end,
+        actual: displayNo,
+        contract: '40-rhythm/README.md#chapter-map',
+      }));
+    }
+    const act = actById.get(c.act);
+    if (!act) {
+      errors.push(v2Error('RHYTHM_ACT_REF', { path: p + '.act', message: '引用了不存在的幕：' + c.act, contract: '40-rhythm/README.md#chapter-map' }));
+    } else {
+      if (act.volume_id !== c.volume) {
+        errors.push(v2Error('RHYTHM_ACT_VOLUME', { path: p + '.act', message: '幕不属于本章的卷', expected: act.volume_id, actual: c.volume, contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      if (Number.isInteger(displayNo) && (displayNo < Number(act.chapter_start) || displayNo > Number(act.chapter_end))) {
+        errors.push(v2Error('RHYTHM_ACT_RANGE', {
+          path: p + '.act',
+          message: '本章不在该幕的章节区间内',
+          expected: act.chapter_start + '-' + act.chapter_end,
+          actual: displayNo,
+          contract: '40-rhythm/README.md#chapter-map',
+        }));
+      }
+    }
+
+    // 5W：谁/何时/何地/为什么/怎么写
+    if (!charIds.has(c.pov)) {
+      errors.push(v2Error('RHYTHM_POV_REF', { path: p + '.pov', message: '视角人物不存在：' + c.pov, contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    const castIds = asArray(c.cast);
+    if (!castIds.length) {
+      errors.push(v2Error('RHYTHM_CAST_EMPTY', { path: p + '.cast', message: '每章至少要有一个出场人物', contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    if (c.pov && !castIds.includes(c.pov)) {
+      errors.push(v2Error('RHYTHM_POV_NOT_CAST', { path: p + '.cast', message: '视角人物必须在本章出场人物里', actual: c.pov, contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    for (const id of castIds) {
+      if (!charIds.has(id)) errors.push(v2Error('RHYTHM_CAST_REF', { path: p + '.cast', message: '出场人物不存在：' + id, contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    const locs = asArray(c.locations);
+    if (!locs.length) {
+      errors.push(v2Error('RHYTHM_LOCATION_EMPTY', { path: p + '.locations', message: '每章至少要有一个地点', contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    for (const id of locs) {
+      if (!locationIds.has(id)) errors.push(v2Error('RHYTHM_LOCATION_REF', { path: p + '.locations', message: '地点不存在：' + id, contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    if (!c.time || typeof c.time !== 'object') {
+      errors.push(v2Error('RHYTHM_TIME', { path: p + '.time', message: '缺少本章故事时间', contract: '40-rhythm/README.md#chapter-map' }));
+    } else {
+      if (c.time.story_day !== undefined && (!Number.isInteger(Number(c.time.story_day)) || Number(c.time.story_day) <= 0)) {
+        errors.push(v2Error('RHYTHM_TIME_DAY', { path: p + '.time.story_day', message: 'story_day 必须是正整数', contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      requireString(errors, c.time, p + '.time', 'clock', '40-rhythm/README.md#chapter-map');
+    }
+    const why = c.why || {};
+    requireArray(errors, why, p + '.why', 'main_line_nodes', '40-rhythm/README.md#chapter-map', 1);
+    for (const id of asArray(why.main_line_nodes)) {
+      if (!mainNodeIds.has(id)) errors.push(v2Error('RHYTHM_MAIN_NODE_REF', { path: p + '.why.main_line_nodes', message: '主线节点不存在：' + id, contract: '40-rhythm/README.md#chapter-map' }));
+      else coveredMain.add(id);
+    }
+    for (const id of asArray(why.branch_nodes)) {
+      const m = BRANCH_REGEX.exec(String(id));
+      if (!m || !branchIds.has(m[1])) {
+        errors.push(v2Error('RHYTHM_BRANCH_REF', { path: p + '.why.branch_nodes', message: '支线不存在：' + id, contract: '40-rhythm/README.md#chapter-map' }));
+      } else {
+        coveredBranch.add(m[1]);
+      }
+    }
+    for (const id of asArray(why.conflict)) {
+      if (!conflictIds.has(id)) errors.push(v2Error('RHYTHM_CONFLICT_REF', { path: p + '.why.conflict', message: '冲突不存在：' + id, contract: '40-rhythm/README.md#chapter-map' }));
+      else coveredConflict.add(id);
+    }
+    requireString(errors, why, p + '.why', 'theme', '40-rhythm/README.md#chapter-map');
+    requireString(errors, why, p + '.why', 'stakes', '40-rhythm/README.md#chapter-map');
+    const how = c.how || {};
+    for (const field of ['function_main', 'turn', 'ending_hook']) requireString(errors, how, p + '.how', field, '40-rhythm/README.md#chapter-map');
+
+    // 伏笔/爽点动作
+    const fsActions = asArray(c.foreshadow_actions);
+    for (let j = 0; j < fsActions.length; j += 1) {
+      const a = fsActions[j] || {};
+      if (!foreshadowIds.has(a.id)) {
+        errors.push(v2Error('RHYTHM_FORESHADOW_REF', { path: p + '.foreshadow_actions[' + j + '].id', message: '伏笔不存在：' + a.id, contract: '40-rhythm/README.md#chapter-map' }));
+        continue;
+      }
+      coveredForeshadow.add(a.id);
+      const action = normAction(a.action);
+      if (!action) {
+        errors.push(v2Error('RHYTHM_FORESHADOW_ACTION', { path: p + '.foreshadow_actions[' + j + '].action', message: '伏笔动作不能为空', contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      if (action === '埋设' && !foreshadowFirst.has(a.id)) foreshadowFirst.set(a.id, { plant: displayNo, recover: null });
+      if (action === '回收') {
+        const rec = foreshadowFirst.get(a.id) || { plant: null, recover: null };
+        if (rec.recover === null) rec.recover = displayNo;
+        foreshadowFirst.set(a.id, rec);
+      }
+    }
+    const plActions = asArray(c.payoff_actions);
+    for (let j = 0; j < plActions.length; j += 1) {
+      const a = plActions[j] || {};
+      if (!payoffIds.has(a.id)) {
+        errors.push(v2Error('RHYTHM_PAYOFF_REF', { path: p + '.payoff_actions[' + j + '].id', message: '爽点不存在：' + a.id, contract: '40-rhythm/README.md#chapter-map' }));
+        continue;
+      }
+      coveredPayoff.add(a.id);
+      if (normAction(a.action) === '回收' && !payoffFirst.has(a.id)) payoffFirst.set(a.id, displayNo);
+    }
+    for (let j = 0; j < asArray(c.information_gaps).length; j += 1) {
+      const g = c.information_gaps[j] || {};
+      if (!infoIds.has(g.id)) {
+        errors.push(v2Error('RHYTHM_INFO_REF', { path: p + '.information_gaps[' + j + '].id', message: '信息差不存在：' + g.id, contract: '40-rhythm/README.md#chapter-map' }));
+      } else {
+        coveredInfo.add(g.id);
+      }
+      if (!['created', 'progressed', 'resolved'].includes(g.state)) {
+        errors.push(v2Error('RHYTHM_INFO_STATE', { path: p + '.information_gaps[' + j + '].state', message: '信息差状态必须是 created/progressed/resolved', actual: g.state, contract: '40-rhythm/README.md#chapter-map' }));
+      }
+    }
+    for (const a of asArray(c.ending_actions)) {
+      if (!endingIds.has(a.id)) {
+        errors.push(v2Error('RHYTHM_ENDING_REF', { path: p + '.ending_actions', message: '结局节点不存在：' + a.id, contract: '40-rhythm/README.md#chapter-map' }));
+      } else {
+        coveredEnding.add(a.id);
+      }
+    }
+
+    // 情绪 + 钩子
+    const emotion = c.emotion || {};
+    const value = Number(emotion.value);
+    if (!Number.isFinite(value) || value < 1 || value > 10) {
+      errors.push(v2Error('RHYTHM_EMOTION', { path: p + '.emotion.value', message: '情绪强度必须是 1..10', actual: emotion.value, contract: '40-rhythm/README.md#chapter-map' }));
+    } else {
+      if (prevEmotion !== null && Math.abs(value - prevEmotion) > 6) {
+        warnings.push(v2Error('RHYTHM_EMOTION_JUMP', { path: p + '.emotion.value', severity: 'warning', message: '相邻章节情绪跳变超过 6；转折/高潮章可忽略', actual: prevEmotion + ' -> ' + value, contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      recentEmotions.push(value);
+      if (recentEmotions.length > 3) recentEmotions.shift();
+      if (recentEmotions.length === 3 && Math.max(...recentEmotions) - Math.min(...recentEmotions) < 1) {
+        warnings.push(v2Error('RHYTHM_EMOTION_FLAT', { path: p + '.emotion.value', severity: 'warning', message: '连续 3 章情绪波动 < 1，剧情可能平流', actual: recentEmotions.join(' / '), contract: '40-rhythm/README.md#chapter-map' }));
+      }
+      prevEmotion = value;
+    }
+    requireString(errors, emotion, p + '.emotion', 'phase', '40-rhythm/README.md#chapter-map');
+    const hook = c.hook || {};
+    if (!hook.type || !['强', '中', '弱', 'strong', 'medium', 'weak'].includes(String(hook.strength))) {
+      errors.push(v2Error('RHYTHM_HOOK', { path: p + '.hook', message: '每章必须有钩子类型与强度（强/中/弱）', contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    if (i < 3 && String(hook.strength) !== '强' && String(hook.strength) !== 'strong') {
+      warnings.push(v2Error('RHYTHM_GOLDEN_THREE_HOOK', { path: p + '.hook.strength', severity: 'warning', message: '黄金三章建议使用强钩子', contract: '40-rhythm/README.md#chapter-map' }));
+    }
+    const wt = Number(c.word_target);
+    if (!Number.isInteger(wt) || wt <= 0) {
+      errors.push(v2Error('RHYTHM_WORD_TARGET', { path: p + '.word_target', message: 'word_target 必须是正整数', actual: c.word_target, contract: '40-rhythm/README.md#chapter-map' }));
+    } else {
+      wordSum += wt;
+    }
+  }
+
+  for (let ch = 1; ch <= T; ch += 1) {
+    if (!displaySeen.has(ch)) {
+      errors.push(v2Error('RHYTHM_CHAPTER_GAP', { path: 'chapter_map.chapters', message: '缺少第 ' + ch + ' 章', contract: '40-rhythm/README.md#chapter-map' }));
+    }
+  }
+  if (Number(scale.capacity.target_words) && Math.abs(wordSum - Number(scale.capacity.target_words)) > T) {
+    errors.push(v2Error('RHYTHM_WORD_SUM', {
+      path: 'chapter_map.chapters[*].word_target',
+      message: '各章字数目标总和必须匹配 capacity.target_words',
+      expected: Number(scale.capacity.target_words), actual: wordSum,
+      contract: '40-rhythm/README.md#chapter-map',
+      reference: '10-scale/scale.json#capacity.target_words',
+    }));
+  }
+
+  // 覆盖矩阵
+  const coverageChecks = [
+    ['RHYTHM_MAIN_COVERAGE', '主线节点', mainNodeIds, coveredMain, '20-macro/lines.json#main_line.nodes'],
+    ['RHYTHM_BRANCH_COVERAGE', '支线', branchIds, coveredBranch, '20-macro/lines.json#branches'],
+    ['RHYTHM_CONFLICT_COVERAGE', '冲突', conflictIds, coveredConflict, '30-cast/conflicts.json#conflicts'],
+    ['RHYTHM_FORESHADOW_COVERAGE', '伏笔', foreshadowIds, coveredForeshadow, '30-cast/foreshadows.json#foreshadows'],
+    ['RHYTHM_PAYOFF_COVERAGE', '爽点', payoffIds, coveredPayoff, '30-cast/payoffs.json#payoffs'],
+    ['RHYTHM_INFO_COVERAGE', '信息差', infoIds, coveredInfo, '30-cast/information.json#information_gaps'],
+  ];
+  for (const [code, label, all, covered, reference] of coverageChecks) {
+    const missing = [...all].filter((id) => !covered.has(id));
+    if (missing.length) {
+      errors.push(v2Error(code, {
+        path: 'chapter_map.chapters',
+        message: label + '没有章节落点：' + missing.slice(0, 12).join('、') + (missing.length > 12 ? ' …' : ''),
+        actual: missing,
+        contract: '40-rhythm/README.md#coverage',
+        reference,
+      }));
+    }
+  }
+  const uncoveredEnding = [...endingIds].filter((id) => !coveredEnding.has(id));
+  if (uncoveredEnding.length) {
+    warnings.push(v2Error('RHYTHM_ENDING_COVERAGE', { path: 'chapter_map.chapters', severity: 'warning', message: '结局节点没有章节落点：' + uncoveredEnding.join('、'), contract: '40-rhythm/README.md#coverage' }));
+  }
+
+  // 伏笔顺序
+  for (const [id, rec] of foreshadowFirst.entries()) {
+    if (rec.recover !== null && (rec.plant === null || rec.recover < rec.plant)) {
+      errors.push(v2Error('RHYTHM_FORESHADOW_ORDER', {
+        path: 'chapter_map.chapters',
+        message: '伏笔必须先埋后收：' + id,
+        actual: rec.plant === null ? '只回收未埋设' : '第 ' + rec.recover + ' 章回收，第 ' + rec.plant + ' 章才埋设',
+        hint: '检查 30-cast/foreshadows.json 的 setup 与 payoff_target，再调整章节地图',
+        contract: '40-rhythm/README.md#foreshadow-order',
+        reference: '30-cast/foreshadows.json#foreshadows',
+      }));
+    }
+  }
+
+  // ---- 角色知识时间线 ----
+  const knowledge = replayKnowledge(chapters, cast);
+  errors.push(...knowledge.errors.map((e) => v2Error(e.code, { ...e, contract: '40-rhythm/README.md#knowledge' })));
+  warnings.push(...knowledge.warnings.map((e) => v2Error(e.code, { ...e, severity: 'warning', contract: '40-rhythm/README.md#knowledge' })));
+  if (!knowledge.events.length && chapters.some((c) => asArray(c.information_gaps).length || asArray(c.foreshadow_actions).length)) {
+    warnings.push(v2Error('RHYTHM_KNOWLEDGE_MISSING', {
+      path: 'chapter_map.chapters[*].knowledge_events',
+      severity: 'warning',
+      message: '章节地图尚无角色级知识事件，无法校验“谁在何时、如何知道什么”。建议重跑 rhythm 或补充 knowledge_events。',
+      contract: '40-rhythm/README.md#knowledge',
+    }));
+  }
+
+  // ---- 细纲 ----
+  const outlines = docs.outlines instanceof Map ? docs.outlines : new Map();
+  const requireOutlines = opts.requireOutlines !== false;
+  const outlineFilter = opts.outlineFilter instanceof Set ? opts.outlineFilter : null;
+  if (requireOutlines) {
+    for (const [displayNo, c] of byDisplay.entries()) {
+      const id = c.chapter_id;
+      if (outlineFilter && !outlineFilter.has(id)) continue;
+      const outline = id ? outlines.get(id) : null;
+      if (!outline) {
+        errors.push(v2Error('OUTLINE_MISSING', {
+          path: 'outlines/' + (id || '?') + '.json',
+          message: '第 ' + displayNo + ' 章缺少可落地细纲',
+          contract: '40-rhythm/README.md#outline',
+          reference: 'chapter_map.chapters[' + displayNo + ']',
+        }));
+        continue;
+      }
+      const p = 'outlines/' + id + '.json';
+      const { chapter, hard, how } = outlineCandidates(outline);
+      const number = Number(chapter.number || chapter.display_no || chapter.ch);
+      if (Number.isInteger(number) && number !== displayNo) {
+        errors.push(v2Error('OUTLINE_CHAPTER_MISMATCH', { path: p + '.chapter.number', message: '细纲章号与章节地图不一致', expected: displayNo, actual: number, contract: '40-rhythm/README.md#outline' }));
+      }
+      if (chapter.chapter_id && chapter.chapter_id !== id) {
+        errors.push(v2Error('OUTLINE_CHAPTER_ID_MISMATCH', { path: p + '.chapter.chapter_id', message: '细纲 chapter_id 与章节地图不一致', expected: id, actual: chapter.chapter_id, contract: '40-rhythm/README.md#outline' }));
+      }
+      if (!chapter.pov || !chapter.pov.id) {
+        errors.push(v2Error('OUTLINE_POV', { path: p + '.chapter.pov', message: '细纲必须有视角人物', contract: '40-rhythm/README.md#outline' }));
+      } else if (!charIds.has(chapter.pov.id)) {
+        errors.push(v2Error('OUTLINE_POV_REF', { path: p + '.chapter.pov.id', message: '视角人物不存在：' + chapter.pov.id, contract: '40-rhythm/README.md#outline' }));
+      }
+      const oCast = asArray(chapter.cast);
+      if (!oCast.length) {
+        errors.push(v2Error('OUTLINE_CAST_EMPTY', { path: p + '.chapter.cast', message: '细纲必须列出本章出场人物', contract: '40-rhythm/README.md#outline' }));
+      }
+      const oCastIds = new Set(oCast.map((x) => (typeof x === 'string' ? x : x && x.id)).filter(Boolean));
+      for (const cid of oCastIds) {
+        if (!charIds.has(cid)) {
+          errors.push(v2Error('OUTLINE_CAST_REF', { path: p + '.chapter.cast', message: '细纲出场人物不存在：' + cid, contract: '40-rhythm/README.md#outline' }));
+        }
+        if (!asArray(c.cast).includes(cid)) {
+          errors.push(v2Error('OUTLINE_CAST_MISMATCH', {
+            path: p + '.chapter.cast', message: '细纲出场人物必须与章节地图一致：' + cid,
+            contract: '40-rhythm/README.md#outline', reference: 'chapter_map.chapters[' + displayNo + '].cast',
+          }));
+        }
+      }
+      for (const cid of asArray(c.cast)) {
+        if (!oCastIds.has(cid)) {
+          errors.push(v2Error('OUTLINE_CAST_MISMATCH', {
+            path: p + '.chapter.cast', message: '细纲漏掉章节地图里的出场人物：' + cid,
+            contract: '40-rhythm/README.md#outline', reference: 'chapter_map.chapters[' + displayNo + '].cast',
+          }));
+        }
+      }
+      const oLocs = asArray(chapter.locations);
+      const oLocIds = new Set(oLocs.map((x) => (typeof x === 'string' ? x : x && x.id)).filter(Boolean));
+      if (!oLocIds.size) {
+        errors.push(v2Error('OUTLINE_LOCATION_EMPTY', { path: p + '.chapter.locations', message: '细纲必须列出本章地点', contract: '40-rhythm/README.md#outline' }));
+      }
+      for (const lid of oLocIds) {
+        if (!locationIds.has(lid)) errors.push(v2Error('OUTLINE_LOCATION_REF', { path: p + '.chapter.locations', message: '细纲地点不存在：' + lid, contract: '40-rhythm/README.md#outline' }));
+      }
+      for (const lid of asArray(c.locations)) {
+        if (!oLocIds.has(lid)) {
+          errors.push(v2Error('OUTLINE_LOCATION_MISMATCH', {
+            path: p + '.chapter.locations', message: '细纲漏掉章节地图里的地点：' + lid,
+            contract: '40-rhythm/README.md#outline', reference: 'chapter_map.chapters[' + displayNo + '].locations',
+          }));
+        }
+      }
+
+      const scenes = asArray(how.scenes);
+      if (!scenes.length) {
+        errors.push(v2Error('OUTLINE_SCENES', { path: p + '.chapter.how.scenes', message: '细纲至少要有 1 个场景', contract: '40-rhythm/README.md#outline' }));
+      }
+      for (let j = 0; j < scenes.length; j += 1) {
+        const s = scenes[j] || {};
+        for (const field of ['goal', 'obstacle', 'turn', 'outcome']) {
+          if (typeof s[field] !== 'string' || !s[field].trim()) {
+            errors.push(v2Error('OUTLINE_BEAT_INCOMPLETE', {
+              path: p + '.chapter.how.scenes[' + j + '].' + field,
+              message: '场景缺少 ' + field,
+              contract: '40-rhythm/README.md#outline',
+            }));
+          }
+        }
+        if (s.location && !oLocIds.has(s.location)) {
+          errors.push(v2Error('OUTLINE_SCENE_LOCATION', { path: p + '.chapter.how.scenes[' + j + '].location', message: '场景地点不在本章地点里：' + s.location, contract: '40-rhythm/README.md#outline' }));
+        }
+      }
+      const must = asArray(hard.must_write || how.must_write || chapter.must_write);
+      const mustNot = asArray(hard.must_not_write || how.must_not_write || chapter.must_not_write);
+      if (!must.length) errors.push(v2Error('OUTLINE_MUST_WRITE', { path: p + '.chapter.hard_constraints.must_write', message: '细纲必须写清楚本章必须写什么', contract: '40-rhythm/README.md#outline' }));
+      if (!mustNot.length) errors.push(v2Error('OUTLINE_BAN_MISSING', { path: p + '.chapter.hard_constraints.must_not_write', message: '细纲必须写清楚本章绝对不能写什么', contract: '40-rhythm/README.md#outline' }));
+      const ending = how.ending || hard.ending || {};
+      if (!ending.type || !ending.text || !ending.hook) {
+        errors.push(v2Error('OUTLINE_ENDING', { path: p + '.chapter.how.ending', message: '细纲必须说明本章如何结束与章尾钩子', contract: '40-rhythm/README.md#outline' }));
+      }
+      requireString(errors, whyOf(chapter), p + '.chapter.why', 'stakes', '40-rhythm/README.md#outline');
+
+      // 硬约束与章节地图一致
+      const mapFs = actionSet(c.foreshadow_actions);
+      const outlineFs = actionSet(hard.foreshadow_actions || chapter.foreshadow_actions || how.foreshadow_actions);
+      for (const key of mapFs) {
+        if (!outlineFs.has(key)) {
+          errors.push(v2Error('OUTLINE_FORESHADOW_MISMATCH', {
+            path: p + '.chapter.hard_constraints.foreshadow_actions',
+            message: '细纲漏掉章节地图的伏笔动作：' + key,
+            contract: '40-rhythm/README.md#outline',
+            reference: 'chapter_map.chapters[' + displayNo + '].foreshadow_actions',
+          }));
+        }
+      }
+      const mapPl = actionSet(c.payoff_actions);
+      const outlinePl = actionSet(hard.payoff_actions || chapter.payoff_actions || how.payoff_actions);
+      for (const key of mapPl) {
+        if (!outlinePl.has(key)) {
+          errors.push(v2Error('OUTLINE_PAYOFF_MISMATCH', {
+            path: p + '.chapter.hard_constraints.payoff_actions',
+            message: '细纲漏掉章节地图的爽点动作：' + key,
+            contract: '40-rhythm/README.md#outline',
+            reference: 'chapter_map.chapters[' + displayNo + '].payoff_actions',
+          }));
+        }
+      }
+      const coverage = chapter.coverage || outline.coverage || {};
+      const mapMain = new Set(asArray(c.why && c.why.main_line_nodes));
+      const covMain = new Set(asArray(coverage.main_line));
+      for (const id of mapMain) if (!covMain.has(id)) {
+        errors.push(v2Error('OUTLINE_COVERAGE_GAP', { path: p + '.chapter.coverage.main_line', message: '细纲覆盖矩阵漏掉主线节点：' + id, contract: '40-rhythm/README.md#outline' }));
+      }
+      const mapConflict = new Set(asArray(c.why && c.why.conflict));
+      const covConflict = new Set(asArray(coverage.conflict));
+      for (const id of mapConflict) if (!covConflict.has(id)) {
+        errors.push(v2Error('OUTLINE_COVERAGE_GAP', { path: p + '.chapter.coverage.conflict', message: '细纲覆盖矩阵漏掉冲突：' + id, contract: '40-rhythm/README.md#outline' }));
+      }
+      const mapInfo = actionIds(c.information_gaps);
+      const covInfo = actionIds(coverage.information);
+      for (const id of mapInfo) if (!covInfo.has(id)) {
+        errors.push(v2Error('OUTLINE_COVERAGE_GAP', { path: p + '.chapter.coverage.information', message: '细纲覆盖矩阵漏掉信息差：' + id, contract: '40-rhythm/README.md#outline' }));
+      }
+
+      // 知识状态必须与章节地图回放一致；细纲是最接近正文的一层，不能再各自发明知识。
+      const expectedKnowledge = knowledge.snapshots.get(displayNo) || new Map();
+      const snapshotRows = [];
+      for (const person of asArray(chapter.cast)) {
+        if (!person || !Array.isArray(person.knowledge)) continue;
+        for (const item of person.knowledge) if (item && typeof item === 'object') snapshotRows.push(item);
+      }
+      if (Array.isArray(hard.knowledge_state)) snapshotRows.push(...hard.knowledge_state.filter((x) => x && typeof x === 'object'));
+      const snapshot = validateKnowledgeSnapshot(snapshotRows, expectedKnowledge, {
+        chapterNo: displayNo,
+        path: p + '.chapter.cast[].knowledge',
+      });
+      errors.push(...snapshot.errors.map((e) => v2Error(e.code, { ...e, contract: '40-rhythm/README.md#knowledge' })));
+      warnings.push(...snapshot.warnings.map((e) => v2Error(e.code, { ...e, severity: 'warning', contract: '40-rhythm/README.md#knowledge' })));
+
+      const mapEvents = asArray(c.knowledge_events);
+      const outlineEvents = asArray(chapter.knowledge_events);
+      if (mapEvents.length || outlineEvents.length) {
+        const mapKeys = new Set(mapEvents.map(eventKey));
+        const outlineKeys = new Set(outlineEvents.map(eventKey));
+        for (const key of mapKeys) {
+          if (!outlineKeys.has(key)) {
+            errors.push(v2Error('OUTLINE_KNOWLEDGE_MISSING', {
+              path: p + '.chapter.knowledge_events',
+              message: '细纲漏掉章节地图的知识事件：' + key,
+              contract: '40-rhythm/README.md#knowledge',
+              reference: 'chapter_map.chapters[' + displayNo + '].knowledge_events',
+            }));
+          }
+        }
+        for (const key of outlineKeys) {
+          if (!mapKeys.has(key)) {
+            warnings.push(v2Error('OUTLINE_KNOWLEDGE_EXTRA', {
+              path: p + '.chapter.knowledge_events',
+              severity: 'warning',
+              message: '细纲新增了章节地图没有的知识事件：' + key,
+              contract: '40-rhythm/README.md#knowledge',
+            }));
+          }
+        }
+      }
+      const continuity = chapter.continuity || outline.continuity || {};
+      if (displayNo > 1 && !continuity.from_prev) {
+        errors.push(v2Error('OUTLINE_CONTINUITY_GAP', { path: p + '.chapter.continuity.from_prev', message: '非首章细纲必须说明与上一章的衔接', contract: '40-rhythm/README.md#outline' }));
+      }
+      if (displayNo < T && !continuity.to_next) {
+        errors.push(v2Error('OUTLINE_CONTINUITY_GAP', { path: p + '.chapter.continuity.to_next', message: '非末章细纲必须说明与下一章的衔接', contract: '40-rhythm/README.md#outline' }));
+      }
+      if (outline._meta && Array.isArray(outline._meta.context_files)) {
+        for (const rel of outline._meta.context_files) {
+          if (typeof rel !== 'string' || rel.startsWith('/') || rel.includes('..')) {
+            errors.push(v2Error('OUTLINE_CONTEXT_MISSING', { path: p + '._meta.context_files', message: '细纲上下文必须是阶段目录内的相对路径', actual: rel, contract: '40-rhythm/README.md#outline' }));
+            continue;
+          }
+          const target = path.join(path.dirname(path.join(opts.stageDir || '.', path.basename(p))), rel);
+          if (opts.stageDir && !fs.existsSync(target)) {
+            errors.push(v2Error('OUTLINE_CONTEXT_MISSING', { path: p + '._meta.context_files', message: '细纲引用的上下文文件不存在：' + rel, contract: '40-rhythm/README.md#outline' }));
+          }
+        }
+      }
+    }
+    const extra = [...outlines.keys()].filter((id) => !chapterIdSet.has(id));
+    if (!outlineFilter && extra.length) {
+      warnings.push(v2Error('OUTLINE_EXTRA', { path: 'outlines', severity: 'warning', message: '存在章节地图里没有的细纲：' + extra.slice(0, 10).join('、'), contract: '40-rhythm/README.md#outline' }));
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings, data: docs };
+}
+
+function whyOf(chapter) {
+  return chapter.why || {};
+}
+
+/** 从阶段目录读取章节地图与所有细纲。 */
+export function loadRhythm(projectRoot, stageDirPath, opts = {}) {
+  const chapterMap = opts.chapterMap || readJson(path.join(stageDirPath, 'chapter_map.json'), null);
+  const outlineDir = path.join(stageDirPath, 'outlines');
+  const outlines = new Map();
+  let names = [];
+  try {
+    names = fs.readdirSync(outlineDir);
+  } catch {
+    names = [];
+  }
+  const only = opts.outlineIds instanceof Set ? opts.outlineIds : null;
+  for (const name of names) {
+    if (!name.endsWith('.json') || name.startsWith('.')) continue;
+    const fileId = name.replace(/\.json$/, '');
+    if (only && !only.has(fileId)) continue;
+    const data = readJson(path.join(outlineDir, name), null);
+    if (!data) continue;
+    const chapter = data.chapter || {};
+    const id = chapter.chapter_id || chapter.id || fileId;
+    outlines.set(id, data);
+  }
+  return { chapter_map: chapterMap || { chapters: [] }, outlines };
+}