@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-story-builder/scripts/upstream-query.js

@@ -27,7 +27,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // 各阶段的文件名白名单（防止路径穿越）
 const STAGE_FILES = {
   骨架: ['框架', '实体', '关系', '层级'],
-  血肉: ['角色', '冲突', '势力', '剧情', '地点', '结局', '世界观规则', '关键道具'],
+  血肉: ['角色', '其他实体', '冲突', '势力', '剧情', '地点', '结局', '世界观规则', '关键道具'],
   节奏: ['章节规划', '时序映射', '节奏参数', '章节细纲'],
 };
 

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

@@ -0,0 +1,112 @@
+/**
+ * v2/baseline.js —— 00-baseline：固化选题、参考与公式版本。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  SCHEMA_VERSION,
+  ensureDir,
+  fileExists,
+  nowIso,
+  readJson,
+  stageDir,
+  writeJsonAtomic,
+} from './core.js';
+
+const INPUT_FIELDS = [
+  'book_name', 'genre', 'platform', 'positioning', 'one_line_pitch', 'target_chapters', 'target_words',
+  'core_conflict', 'reader_value', 'golden_finger', 'core_setting', 'selling_points',
+  'hard_constraints', 'anti_tropes', 'protagonist', 'world_setting',
+];
+
+export function buildBaselinePayload(topicData, formulasDoc, genreProfilesDoc) {
+  const topic = topicData || {};
+  const input = {
+    schema_version: SCHEMA_VERSION,
+    book_name: topic.book_name || topic.title || '未命名',
+    genre: topic.genre || '',
+    positioning: topic.positioning || '',
+    one_line_pitch: topic.one_line_pitch || '',
+    target_chapters: Number(topic.target_chapters) || 0,
+    target_words: Number(topic.target_words) || 0,
+    core_conflict: topic.core_conflict || '',
+    reader_value: topic.reader_value || '',
+    golden_finger: topic.golden_finger || '',
+    core_setting: topic.core_setting || '',
+    selling_points: Array.isArray(topic.selling_points) ? topic.selling_points : [],
+    hard_constraints: Array.isArray(topic.hard_constraints) ? topic.hard_constraints : [],
+    anti_tropes: Array.isArray(topic.anti_tropes) ? topic.anti_tropes : [],
+    protagonist: topic.protagonist || '',
+    world_setting: topic.world_setting || '',
+    created_at: nowIso(),
+  };
+  // 只保留已定义字段，避免把 undefined 写进 JSON
+  for (const key of Object.keys(input)) {
+    if (input[key] === undefined) delete input[key];
+  }
+  return {
+    input,
+    references: {
+      schema_version: SCHEMA_VERSION,
+      references: Array.isArray(topic.references) ? topic.references : [],
+      benchmark: topic.benchmark || null,
+      note: '对标与参考决策。没有时保持空数组。',
+    },
+    formulas: {
+      _meta: {
+        schema_version: SCHEMA_VERSION,
+        source: 'quantity-formulas',
+        version: '2026-11-06',
+        read_only: true,
+      },
+      ...formulasDoc,
+    },
+    genreProfiles: genreProfilesDoc || null,
+  };
+}
+
+/**
+ * 确保 00-baseline 存在。已存在时不覆盖，除非 opts.force=true。
+ */
+export function ensureBaseline(projectRoot, topicData, formulasDoc, opts = {}) {
+  const dir = stageDir(projectRoot, '00-baseline');
+  ensureDir(dir);
+  const payload = buildBaselinePayload(topicData, formulasDoc, opts.genreProfilesDoc);
+  const files = ['input.json', 'references.json', 'formulas.json'];
+  if (payload.genreProfiles) files.push('genre-profiles.json');
+  const forceFiles = new Set(opts.forceFiles || []);
+  const written = [];
+  const pairs = {
+    'input.json': payload.input,
+    'references.json': payload.references,
+    'formulas.json': payload.formulas,
+    'genre-profiles.json': payload.genreProfiles,
+  };
+  for (const file of files) {
+    const target = path.join(dir, file);
+    if (!opts.force && !forceFiles.has(file) && fileExists(target)) continue;
+    writeJsonAtomic(target, pairs[file]);
+    written.push(file);
+  }
+  return { ok: true, dir, written };
+}
+
+export function loadBaseline(projectRoot) {
+  const dir = stageDir(projectRoot, '00-baseline');
+  return {
+    input: readJson(path.join(dir, 'input.json'), null),
+    references: readJson(path.join(dir, 'references.json'), null),
+    formulas: readJson(path.join(dir, 'formulas.json'), null),
+  };
+}
+
+export function loadFormulasDoc(projectRoot, fallbackPath) {
+  // references/ 是插件每次阶段启动时刷新的副本；优先它，避免旧项目一直用
+  // 00-baseline 里冻结的老公式。
+  const deployed = readJson(path.join(projectRoot, 'references', 'formulas-skeleton.json'), null);
+  if (deployed && deployed.formulas) return deployed;
+  const local = loadBaseline(projectRoot).formulas;
+  if (local && local.formulas) return local;
+  if (fallbackPath && fs.existsSync(fallbackPath)) return readJson(fallbackPath, null);
+  return null;
+}

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

@@ -0,0 +1,517 @@
+/**
+ * v2/cast.js —— 30-cast：人物、势力、地点、道具、冲突、伏笔、高潮、爽点、关系、信息差。
+ *
+ * 这一层只负责“谁、在哪里、为什么对抗、埋什么、怎么爽”。
+ * 章节落点留给 40-rhythm；正文留给 50-writing。
+ */
+import {
+  asArray,
+  indexById,
+  v2Error,
+} from './core.js';
+import { validateInitialKnowledge } from './knowledge.js';
+
+export const CAST_FILES = [
+  'characters.json', 'factions.json', 'locations.json', 'items.json',
+  'conflicts.json', 'foreshadows.json', 'climaxes.json', 'payoffs.json',
+  'relations.json', 'information.json',
+];
+
+const CHARACTER_TYPE_TO_QUOTA = {
+  '主角': 'protagonist',
+  '核心配角': 'core_supporting',
+  '贯穿级核心配角': 'core_supporting',
+  '卷级配角': 'volume_supporting',
+  '卷级重要配角': 'volume_supporting',
+  '核心反派': 'core_antagonist',
+  '贯穿级核心反派': 'core_antagonist',
+  '卷级反派': 'volume_antagonist',
+};
+const ROLE_FUNCTION_TO_QUOTA = {
+  '主角': 'protagonist',
+  '核心配角': 'core_supporting',
+  '贯穿级核心配角': 'core_supporting',
+  '卷级配角': 'volume_supporting',
+  '卷级重要配角': 'volume_supporting',
+  '核心反派': 'core_antagonist',
+  '贯穿级核心反派': 'core_antagonist',
+  '卷级反派': 'volume_antagonist',
+};
+const ITEM_CATEGORY = { core: 'core', 核心: 'core', branch: 'branch', 支线: 'branch', symbolic: 'symbolic', 象征: 'symbolic' };
+const CONFLICT_TYPE = { core: 'core', 核心: 'core', phase: 'phase', 阶段: 'phase', branch: 'branch', 交织: 'branch' };
+const SCALE_SIZE = {
+  small: 'small', 小: 'small', 小型: 'small',
+  medium: 'medium', 中: 'medium', 中型: 'medium',
+  large: 'large', 大: 'large', 大型: 'large',
+};
+
+function requireString(errors, obj, path, field, contract) {
+  const value = obj && obj[field];
+  if (typeof value !== 'string' || !value.trim()) {
+    errors.push(v2Error('CAST_REQUIRED_FIELD', {
+      path: path + '.' + field,
+      message: '缺少必填文本字段',
+      actual: value,
+      contract,
+    }));
+  }
+}
+
+function requireArray(errors, obj, path, field, contract, min = 1) {
+  const value = obj && obj[field];
+  if (!Array.isArray(value) || value.length < min) {
+    errors.push(v2Error('CAST_REQUIRED_FIELD', {
+      path: path + '.' + field,
+      message: '必须是至少 ' + min + ' 项的数组',
+      actual: Array.isArray(value) ? value.length : typeof value,
+      contract,
+    }));
+  }
+}
+
+function collectUnique(errors, rows, path, contract, prefix, pattern) {
+  const ids = new Set();
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i] || {};
+    const id = row.id;
+    if (!id) {
+      errors.push(v2Error('CAST_ID_MISSING', { path: path + '[' + i + '].id', message: '缺少 id', contract }));
+      continue;
+    }
+    if ((pattern && !pattern.test(id)) || (!pattern && prefix && !new RegExp('^' + prefix + '\\d{3,}$').test(id))) {
+      errors.push(v2Error('CAST_ID_FORMAT', {
+        path: path + '[' + i + '].id',
+        message: 'ID 格式不符',
+        expected: pattern ? String(pattern) : prefix + '001',
+        actual: id,
+        contract,
+      }));
+    }
+    if (ids.has(id)) {
+      errors.push(v2Error('CAST_ID_DUP', { path: path + '[' + i + '].id', message: 'ID 重复：' + id, contract }));
+    }
+    ids.add(id);
+  }
+  return ids;
+}
+
+function countBy(rows, resolver) {
+  const out = {};
+  for (const row of rows) {
+    const key = resolver(row || {});
+    if (!key) continue;
+    out[key] = (out[key] || 0) + 1;
+  }
+  return out;
+}
+
+function compareQuota(errors, code, path, actual, expected, label, reference, contract) {
+  if (Number(actual) !== Number(expected)) {
+    errors.push(v2Error(code, {
+      path,
+      message: label + '数量与 scale 配额不一致',
+      expected: Number(expected),
+      actual: Number(actual),
+      contract,
+      reference,
+    }));
+  }
+}
+
+export function validateCast(cast, scale, macro, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const docs = cast || {};
+  const quotas = (scale && scale.quotas) || {};
+  const characters = asArray(docs.characters && docs.characters.characters);
+  const factions = asArray(docs.factions && docs.factions.factions);
+  const locations = asArray(docs.locations && docs.locations.locations);
+  const items = asArray(docs.items && docs.items.items);
+  const conflicts = asArray(docs.conflicts && docs.conflicts.conflicts);
+  const foreshadows = asArray(docs.foreshadows && docs.foreshadows.foreshadows);
+  const climaxes = asArray(docs.climaxes && docs.climaxes.climaxes);
+  const payoffs = asArray(docs.payoffs && docs.payoffs.payoffs);
+  const relations = docs.relations || {};
+  const characterRelations = asArray(relations.character_relations);
+  const factionRelations = asArray(relations.faction_relations);
+  const memberships = asArray(relations.memberships);
+  const information = asArray(docs.information && docs.information.information_gaps);
+  collectUnique(errors, characterRelations, 'relations.character_relations', '30-cast/README.md#relations', 'REL');
+  collectUnique(errors, factionRelations, 'relations.faction_relations', '30-cast/README.md#relations', 'FREL');
+  collectUnique(errors, memberships, 'relations.memberships', '30-cast/README.md#relations', 'MEM');
+
+  // ---- 唯一 ID ----
+  const charIds = collectUnique(errors, characters, 'characters.characters', '30-cast/README.md#characters', 'C');
+  const factionIds = collectUnique(errors, factions, 'factions.factions', '30-cast/README.md#factions', 'F');
+  const locationIds = collectUnique(errors, locations, 'locations.locations', '30-cast/README.md#locations', 'L');
+  const itemIds = collectUnique(errors, items, 'items.items', '30-cast/README.md#items', 'P');
+  const conflictIds = collectUnique(errors, conflicts, 'conflicts.conflicts', '30-cast/README.md#conflicts', 'X');
+  const foreshadowIds = collectUnique(errors, foreshadows, 'foreshadows.foreshadows', '30-cast/README.md#foreshadows', 'FS');
+  const climaxIds = collectUnique(errors, climaxes, 'climaxes.climaxes', '30-cast/README.md#climaxes', 'CL');
+  const payoffIds = collectUnique(errors, payoffs, 'payoffs.payoffs', '30-cast/README.md#payoffs', 'PL');
+  collectUnique(errors, information, 'information.information_gaps', '30-cast/README.md#information', null, /^IG-[A-Za-z0-9-]+$/);
+
+  // ---- 人物 ----
+  const expectedChar = {
+    protagonist: Number((quotas.characters && quotas.characters.protagonist) || 0),
+    core_supporting: Number((quotas.characters && quotas.characters.core_supporting) || 0),
+    volume_supporting: Number((quotas.characters && quotas.characters.volume_supporting) || 0),
+    core_antagonist: Number((quotas.characters && quotas.characters.core_antagonist) || 0),
+    volume_antagonist: Number((quotas.characters && quotas.characters.volume_antagonist) || 0),
+  };
+  const charTypeCounts = countBy(characters, (c) => CHARACTER_TYPE_TO_QUOTA[c.type || c.role]);
+  for (const [key, expected] of Object.entries(expectedChar)) {
+    compareQuota(errors, 'CAST_CHARACTER_QUOTA', 'characters.characters',
+      charTypeCounts[key] || 0, expected,
+      '角色（' + key + '）', '10-scale/scale.json#quotas.characters.' + key, '30-cast/README.md#characters');
+  }
+  const roleMap = new Map();
+  for (const r of asArray(macro && macro.roles && macro.roles.roles)) {
+    if (r && r.role_id) roleMap.set(r.role_id, r);
+  }
+  const usedRoles = new Map();
+  for (let i = 0; i < characters.length; i += 1) {
+    const c = characters[i] || {};
+    const p = 'characters.characters[' + i + ']';
+    requireString(errors, c, p, 'name', '30-cast/README.md#characters');
+    requireString(errors, c, p, 'type', '30-cast/README.md#characters');
+    requireString(errors, c, p, 'description', '30-cast/README.md#characters');
+    requireString(errors, c, p, 'flaw', '30-cast/README.md#characters');
+    requireString(errors, c, p, 'golden_finger', '30-cast/README.md#characters');
+    if (!CHARACTER_TYPE_TO_QUOTA[c.type || c.role]) {
+      errors.push(v2Error('CAST_CHARACTER_TYPE', {
+        path: p + '.type',
+        message: '未知人物类型',
+        expected: Object.keys(CHARACTER_TYPE_TO_QUOTA).join(' / '),
+        actual: c.type || c.role,
+        contract: '30-cast/README.md#characters',
+      }));
+    }
+    if (!c.faction || !factionIds.has(c.faction)) {
+      errors.push(v2Error('CAST_CHARACTER_FACTION', {
+        path: p + '.faction',
+        message: '人物必须引用已存在的势力',
+        actual: c.faction,
+        contract: '30-cast/README.md#characters',
+        reference: 'factions.factions',
+      }));
+    }
+    for (const f of ['short_term', 'medium_term', 'long_term']) {
+      if (!c.goal || typeof c.goal[f] !== 'string' || !c.goal[f].trim()) {
+        errors.push(v2Error('CAST_CHARACTER_GOAL', { path: p + '.goal.' + f, message: '缺少目标层级', contract: '30-cast/README.md#characters' }));
+      }
+    }
+    if (!c.information_state || typeof c.information_state !== 'object') {
+      errors.push(v2Error('CAST_CHARACTER_INFO_STATE', { path: p + '.information_state', message: '缺少信息状态', contract: '30-cast/README.md#characters' }));
+    } else {
+      requireArray(errors, c.information_state, p + '.information_state', 'known', '30-cast/README.md#characters', 1);
+      requireArray(errors, c.information_state, p + '.information_state', 'unknown', '30-cast/README.md#characters', 1);
+    }
+    if (!c.arc || typeof c.arc !== 'object' || !Array.isArray(c.arc.stages) || !c.arc.stages.length) {
+      errors.push(v2Error('CAST_CHARACTER_ARC', { path: p + '.arc', message: '人物必须有弧光阶段', contract: '30-cast/README.md#characters' }));
+    } else {
+      for (let j = 0; j < c.arc.stages.length; j += 1) {
+        const st = c.arc.stages[j] || {};
+        for (const f of ['name', 'question', 'planned_change']) {
+          requireString(errors, st, p + '.arc.stages[' + j + ']', f, '30-cast/README.md#characters');
+        }
+      }
+    }
+    if (!c.voice || typeof c.voice !== 'object' || !c.voice.catchphrase || !c.voice.rhythm) {
+      errors.push(v2Error('CAST_CHARACTER_VOICE', { path: p + '.voice', message: '人物必须有口头禅与语言节奏', contract: '30-cast/README.md#characters' }));
+    }
+    if (!c.role_slot) {
+      errors.push(v2Error('CAST_ROLE_SLOT_MISSING', { path: p + '.role_slot', message: '人物必须绑定宏观阶段的 role_slot', contract: '30-cast/README.md#characters' }));
+    } else {
+      const role = roleMap.get(c.role_slot);
+      if (!role) {
+        errors.push(v2Error('CAST_ROLE_SLOT_REF', {
+          path: p + '.role_slot', message: '引用了不存在的角色功能位：' + c.role_slot,
+          contract: '30-cast/README.md#characters', reference: '20-macro/roles.json#roles',
+        }));
+      } else {
+        const roleKey = ROLE_FUNCTION_TO_QUOTA[role.function];
+        const charKey = CHARACTER_TYPE_TO_QUOTA[c.type || c.role];
+        if (roleKey && charKey && roleKey !== charKey) {
+          errors.push(v2Error('CAST_ROLE_FUNCTION_MISMATCH', {
+            path: p + '.role_slot',
+            message: '角色类型与功能位不一致',
+            expected: role.function, actual: c.type,
+            contract: '30-cast/README.md#characters',
+          }));
+        }
+      }
+      usedRoles.set(c.role_slot, (usedRoles.get(c.role_slot) || 0) + 1);
+    }
+  }
+  for (const roleId of roleMap.keys()) {
+    const count = usedRoles.get(roleId) || 0;
+    if (count === 0) {
+      errors.push(v2Error('CAST_ROLE_SLOT_UNFILLED', {
+        path: 'characters.characters', message: '角色功能位没有被填充：' + roleId,
+        contract: '30-cast/README.md#characters', reference: '20-macro/roles.json#roles',
+      }));
+    } else if (count > 1) {
+      errors.push(v2Error('CAST_ROLE_SLOT_REUSED', {
+        path: 'characters.characters', message: '角色功能位被多个角色重复使用：' + roleId,
+        actual: count, contract: '30-cast/README.md#characters', reference: '20-macro/roles.json#roles',
+      }));
+    }
+  }
+
+  // ---- 势力/地点/道具/冲突/伏笔/高潮/爽点 ----
+  compareQuota(errors, 'CAST_FACTION_QUOTA', 'factions.factions', factions.length, quotas.factions, '势力', '10-scale/scale.json#quotas.factions', '30-cast/README.md#factions');
+  compareQuota(errors, 'CAST_LOCATION_QUOTA', 'locations.locations', locations.length, quotas.locations, '地点', '10-scale/scale.json#quotas.locations', '30-cast/README.md#locations');
+  for (let i = 0; i < factions.length; i += 1) {
+    const f = factions[i] || {};
+    for (const field of ['name', 'type', 'description', 'goal']) {
+      requireString(errors, f, 'factions.factions[' + i + ']', field, '30-cast/README.md#factions');
+    }
+    for (const field of ['resources', 'territory']) {
+      const value = f && f[field];
+      if (Array.isArray(value) ? value.length === 0 : !(typeof value === 'string' && value.trim())) {
+        errors.push(v2Error('CAST_REQUIRED_FIELD', { path: 'factions.factions[' + i + '].' + field, message: '必须是非空数组或文本', actual: value, contract: '30-cast/README.md#factions' }));
+      }
+    }
+  }
+  for (let i = 0; i < locations.length; i += 1) {
+    const l = locations[i] || {};
+    for (const field of ['name', 'type', 'description', 'narrative_function']) {
+      requireString(errors, l, 'locations.locations[' + i + ']', field, '30-cast/README.md#locations');
+    }
+  }
+  const itemCounts = countBy(items, (x) => ITEM_CATEGORY[x.category]);
+  for (const key of ['core', 'branch', 'symbolic']) {
+    compareQuota(errors, 'CAST_ITEM_QUOTA', 'items.items', itemCounts[key] || 0,
+      (quotas.items && quotas.items[key]) || 0, '道具（' + key + '）',
+      '10-scale/scale.json#quotas.items.' + key, '30-cast/README.md#items');
+  }
+  for (let i = 0; i < items.length; i += 1) {
+    const it = items[i] || {};
+    for (const field of ['name', 'category', 'description', 'function']) {
+      requireString(errors, it, 'items.items[' + i + ']', field, '30-cast/README.md#items');
+    }
+    if (!ITEM_CATEGORY[it.category]) {
+      errors.push(v2Error('CAST_ITEM_CATEGORY', { path: 'items.items[' + i + '].category', message: '道具类别非法', expected: 'core / branch / symbolic', actual: it.category, contract: '30-cast/README.md#items' }));
+    }
+  }
+  const conflictCounts = countBy(conflicts, (x) => CONFLICT_TYPE[x.type]);
+  for (const key of ['core', 'phase', 'branch']) {
+    compareQuota(errors, 'CAST_CONFLICT_QUOTA', 'conflicts.conflicts', conflictCounts[key] || 0,
+      (quotas.conflicts && quotas.conflicts[key]) || 0, '冲突（' + key + '）',
+      '10-scale/scale.json#quotas.conflicts.' + key, '30-cast/README.md#conflicts');
+  }
+  for (let i = 0; i < conflicts.length; i += 1) {
+    const x = conflicts[i] || {};
+    const p = 'conflicts.conflicts[' + i + ']';
+    for (const field of ['name', 'type', 'description', 'core_goal', 'stakes']) {
+      requireString(errors, x, p, field, '30-cast/README.md#conflicts');
+    }
+    if (!CONFLICT_TYPE[x.type]) {
+      errors.push(v2Error('CAST_CONFLICT_TYPE', { path: p + '.type', message: '冲突类型非法', expected: 'core / phase / branch', actual: x.type, contract: '30-cast/README.md#conflicts' }));
+    }
+    const path = asArray(x.escalation_path);
+    if (path.length < 2) {
+      errors.push(v2Error('CAST_CONFLICT_ESCALATION', { path: p + '.escalation_path', message: '冲突至少要有 2 个升级节点', contract: '30-cast/README.md#conflicts' }));
+    }
+    for (let j = 0; j < path.length; j += 1) {
+      for (const field of ['node_type', 'description']) requireString(errors, path[j] || {}, p + '.escalation_path[' + j + ']', field, '30-cast/README.md#conflicts');
+    }
+    if (!x.resolution_plan || !x.resolution_plan.method) {
+      errors.push(v2Error('CAST_CONFLICT_RESOLUTION', { path: p + '.resolution_plan', message: '冲突必须有解决方式', contract: '30-cast/README.md#conflicts' }));
+    }
+    const participants = asArray(x.participants);
+    if (!participants.length) {
+      errors.push(v2Error('CAST_CONFLICT_PARTICIPANTS', { path: p + '.participants', message: '冲突必须至少有一个参与者', contract: '30-cast/README.md#conflicts' }));
+    }
+    for (const id of participants) {
+      if (!charIds.has(id) && !factionIds.has(id) && !locationIds.has(id)) {
+        errors.push(v2Error('CAST_CONFLICT_PARTICIPANT_REF', { path: p + '.participants', message: '冲突参与者不存在：' + id, contract: '30-cast/README.md#conflicts' }));
+      }
+    }
+  }
+  const foreshadowCounts = countBy(foreshadows, (x) => SCALE_SIZE[x.type] || SCALE_SIZE[x.scale]);
+  for (const key of ['small', 'medium', 'large']) {
+    compareQuota(errors, 'CAST_FORESHADOW_QUOTA', 'foreshadows.foreshadows', foreshadowCounts[key] || 0,
+      (quotas.foreshadows && quotas.foreshadows[key]) || 0, '伏笔（' + key + '）',
+      '10-scale/scale.json#quotas.foreshadows.' + key, '30-cast/README.md#foreshadows');
+  }
+  for (let i = 0; i < foreshadows.length; i += 1) {
+    const f = foreshadows[i] || {};
+    const p = 'foreshadows.foreshadows[' + i + ']';
+    for (const field of ['name', 'type', 'setup', 'payoff_target', 'recovery_requirement']) {
+      requireString(errors, f, p, field, '30-cast/README.md#foreshadows');
+    }
+    if (!SCALE_SIZE[f.type] && !SCALE_SIZE[f.scale]) {
+      errors.push(v2Error('CAST_FORESHADOW_TYPE', { path: p + '.type', message: '伏笔级别非法', expected: '小 / 中 / 大', actual: f.type, contract: '30-cast/README.md#foreshadows' }));
+    }
+    if (f.scope && !['book', 'volume', 'arc', 'chapter'].includes(f.scope)) {
+      errors.push(v2Error('CAST_FORESHADOW_SCOPE', { path: p + '.scope', message: '伏笔 scope 非法', expected: 'book / volume / arc / chapter', actual: f.scope, contract: '30-cast/README.md#foreshadows' }));
+    }
+    requireArray(errors, f, p, 'clues', '30-cast/README.md#foreshadows', 1);
+    if (f.initial_knowledge !== undefined) {
+      const k = validateInitialKnowledge(f.initial_knowledge, { cast: docs, path: p + '.initial_knowledge' });
+      for (const e of k.errors) errors.push(v2Error(e.code, { ...e, contract: '30-cast/README.md#foreshadows' }));
+      for (const w of k.warnings) warnings.push(v2Error(w.code, { ...w, severity: 'warning', contract: '30-cast/README.md#foreshadows' }));
+    }
+  }
+  const climaxCounts = countBy(climaxes, (x) => SCALE_SIZE[x.type] || SCALE_SIZE[x.scale]);
+  for (const key of ['small', 'medium', 'large']) {
+    compareQuota(errors, 'CAST_CLIMAX_QUOTA', 'climaxes.climaxes', climaxCounts[key] || 0,
+      (quotas.climaxes && quotas.climaxes[key]) || 0, '高潮（' + key + '）',
+      '10-scale/scale.json#quotas.climaxes.' + key, '30-cast/README.md#climaxes');
+  }
+  for (let i = 0; i < climaxes.length; i += 1) {
+    const cl = climaxes[i] || {};
+    const p = 'climaxes.climaxes[' + i + ']';
+    for (const field of ['name', 'type', 'description', 'payoff']) {
+      requireString(errors, cl, p, field, '30-cast/README.md#climaxes');
+    }
+    for (const id of asArray(cl.participants)) {
+      if (!charIds.has(id) && !factionIds.has(id) && !locationIds.has(id)) {
+        errors.push(v2Error('CAST_CLIMAX_PARTICIPANT_REF', { path: p + '.participants', message: '高潮参与者不存在：' + id, contract: '30-cast/README.md#climaxes' }));
+      }
+    }
+  }
+  const payoffCounts = countBy(payoffs, (x) => SCALE_SIZE[x.scale] || SCALE_SIZE[x.type]);
+  for (const key of ['small', 'medium', 'large']) {
+    compareQuota(errors, 'CAST_PAYOFF_QUOTA', 'payoffs.payoffs', payoffCounts[key] || 0,
+      (quotas.pleasures && quotas.pleasures[key]) || 0, '爽点（' + key + '）',
+      '10-scale/scale.json#quotas.pleasures.' + key, '30-cast/README.md#payoffs');
+  }
+  for (let i = 0; i < payoffs.length; i += 1) {
+    const pl = payoffs[i] || {};
+    const p = 'payoffs.payoffs[' + i + ']';
+    for (const field of ['name', 'type', 'setup', 'payoff', 'emotional_effect']) {
+      requireString(errors, pl, p, field, '30-cast/README.md#payoffs');
+    }
+    for (const id of asArray(pl.required_setup)) {
+      if (!foreshadowIds.has(id) && !conflictIds.has(id) && !climaxIds.has(id) && !payoffIds.has(id)) {
+        // 允许设置一个尚未生成的冲突升级节点引用（X001-escalation-1）
+        if (!/^X\d{3}-escalation-\d+$/.test(String(id))) {
+          errors.push(v2Error('CAST_PAYOFF_SETUP_REF', { path: p + '.required_setup', message: '爽点铺垫引用不存在：' + id, contract: '30-cast/README.md#payoffs' }));
+        }
+      }
+    }
+  }
+
+  // ---- 关系 ----
+  compareQuota(errors, 'CAST_CHARACTER_RELATION_QUOTA', 'relations.character_relations', characterRelations.length,
+    quotas.relations && quotas.relations.character, '人物关系', '10-scale/scale.json#quotas.relations.character', '30-cast/README.md#relations');
+  compareQuota(errors, 'CAST_FACTION_RELATION_QUOTA', 'relations.faction_relations', factionRelations.length,
+    quotas.relations && quotas.relations.faction, '势力关系', '10-scale/scale.json#quotas.relations.faction', '30-cast/README.md#relations');
+  compareQuota(errors, 'CAST_MEMBERSHIP_QUOTA', 'relations.memberships', memberships.length,
+    quotas.relations && quotas.relations.membership, '势力成员', '10-scale/scale.json#quotas.relations.membership', '30-cast/README.md#relations');
+  for (let i = 0; i < characterRelations.length; i += 1) {
+    const r = characterRelations[i] || {};
+    const p = 'relations.character_relations[' + i + ']';
+    if (!charIds.has(r.from) || !charIds.has(r.to)) {
+      errors.push(v2Error('CAST_RELATION_REF', { path: p, message: '人物关系两端必须存在', actual: r.from + ' -> ' + r.to, contract: '30-cast/README.md#relations' }));
+    }
+    if (r.from === r.to) {
+      errors.push(v2Error('CAST_RELATION_SELF', { path: p, message: '人物关系不能指向自己', contract: '30-cast/README.md#relations' }));
+    }
+    for (const field of ['kind', 'initial_state']) requireString(errors, r, p, field, '30-cast/README.md#relations');
+    const changes = asArray(r.changes);
+    // 关系可以保持静态；只有写出来的变化节点才做结构校验。
+    for (let j = 0; j < changes.length; j += 1) {
+      for (const field of ['stage', 'trigger', 'description']) requireString(errors, changes[j] || {}, p + '.changes[' + j + ']', field, '30-cast/README.md#relations');
+    }
+  }
+  for (let i = 0; i < factionRelations.length; i += 1) {
+    const r = factionRelations[i] || {};
+    const p = 'relations.faction_relations[' + i + ']';
+    if (!factionIds.has(r.from) || !factionIds.has(r.to)) {
+      errors.push(v2Error('CAST_FACTION_RELATION_REF', { path: p, message: '势力关系两端必须存在', contract: '30-cast/README.md#relations' }));
+    }
+    if (r.from === r.to) errors.push(v2Error('CAST_FACTION_RELATION_SELF', { path: p, message: '势力关系不能指向自己', contract: '30-cast/README.md#relations' }));
+    for (const field of ['kind', 'initial_state']) requireString(errors, r, p, field, '30-cast/README.md#relations');
+    const changes = asArray(r.changes);
+    for (let j = 0; j < changes.length; j += 1) {
+      for (const field of ['stage', 'trigger', 'description']) requireString(errors, changes[j] || {}, p + '.changes[' + j + ']', field, '30-cast/README.md#relations');
+    }
+  }
+  for (let i = 0; i < memberships.length; i += 1) {
+    const m = memberships[i] || {};
+    const p = 'relations.memberships[' + i + ']';
+    if (!charIds.has(m.character) || !factionIds.has(m.faction)) {
+      errors.push(v2Error('CAST_MEMBERSHIP_REF', { path: p, message: '成员关系的人物/势力必须存在', contract: '30-cast/README.md#relations' }));
+    }
+    for (const field of ['position', 'kind']) requireString(errors, m, p, field, '30-cast/README.md#relations');
+  }
+
+  // ---- 信息差 ----
+  compareQuota(errors, 'CAST_INFORMATION_QUOTA', 'information.information_gaps', information.length,
+    quotas.information_gaps, '信息差', '10-scale/scale.json#quotas.information_gaps', '30-cast/README.md#information');
+  for (let i = 0; i < information.length; i += 1) {
+    const g = information[i] || {};
+    const p = 'information.information_gaps[' + i + ']';
+    for (const field of ['info_name', 'resolution_method', 'writing_ban']) requireString(errors, g, p, field, '30-cast/README.md#information');
+    if (!g.conflict || !conflictIds.has(g.conflict)) {
+      errors.push(v2Error('CAST_INFORMATION_CONFLICT', { path: p + '.conflict', message: '信息差必须关联已存在的冲突', actual: g.conflict, contract: '30-cast/README.md#information' }));
+    }
+    const knows = new Set([...asArray(g.who_knows), ...asArray(g.who_does_not_know)]);
+    if (!knows.size) {
+      errors.push(v2Error('CAST_INFORMATION_WHO', { path: p, message: '信息差必须说明谁知道/谁不知道', contract: '30-cast/README.md#information' }));
+    }
+    for (const id of knows) {
+      if (!charIds.has(id)) {
+        errors.push(v2Error('CAST_INFORMATION_WHO_REF', { path: p, message: '信息差引用了不存在的人物：' + id, contract: '30-cast/README.md#information' }));
+      }
+    }
+    if (g.initial_knowledge !== undefined) {
+      const k = validateInitialKnowledge(g.initial_knowledge, { cast: docs, path: p + '.initial_knowledge' });
+      for (const e of k.errors) errors.push(v2Error(e.code, { ...e, contract: '30-cast/README.md#information' }));
+      for (const w of k.warnings) warnings.push(v2Error(w.code, { ...w, severity: 'warning', contract: '30-cast/README.md#information' }));
+      const initial = new Map(asArray(g.initial_knowledge).map((row) => [row.character, row.state]));
+      for (const id of asArray(g.who_knows)) {
+        if (initial.has(id) && initial.get(id) === 'unknown') {
+          errors.push(v2Error('CAST_INFORMATION_KNOWLEDGE_CONFLICT', { path: p + '.initial_knowledge', message: 'who_knows 与 initial_knowledge 冲突：' + id + ' 被写成不知道', contract: '30-cast/README.md#information' }));
+        }
+      }
+      for (const id of asArray(g.who_does_not_know)) {
+        // false 表示“知道一个错误版本”，本质仍不知道真相，和 who_does_not_know 兼容。
+        if (initial.has(id) && !['unknown', 'false'].includes(initial.get(id))) {
+          errors.push(v2Error('CAST_INFORMATION_KNOWLEDGE_CONFLICT', { path: p + '.initial_knowledge', message: 'who_does_not_know 与 initial_knowledge 冲突：' + id + ' 被写成知道真相', contract: '30-cast/README.md#information' }));
+        }
+      }
+    }
+  }
+
+  // ---- 30-cast 不允许出现章节落点 ----
+  const scanChapterKeys = (value, prefix) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => scanChapterKeys(item, prefix + '[' + i + ']'));
+      return;
+    }
+    if (!value || typeof value !== 'object') return;
+    for (const [key, val] of Object.entries(value)) {
+      if (key === '_meta') continue;
+      const p = prefix ? prefix + '.' + key : key;
+      if (/^(chapter|chapter_id|chapter_no|ch)$/i.test(key) || /_chapter$/i.test(key)) {
+        errors.push(v2Error('CAST_CHAPTER_REF', {
+          path: p,
+          message: '30-cast 不允许写章节号；章节落点只能在 40-rhythm 分配',
+          contract: '30-cast/README.md#forbidden',
+        }));
+      }
+      scanChapterKeys(val, p);
+    }
+  };
+  scanChapterKeys(docs, '');
+
+  return { ok: errors.length === 0, errors, warnings, data: docs };
+}
+
+export function castIndexes(cast) {
+  return {
+    characters: indexById(asArray(cast && cast.characters && cast.characters.characters)),
+    factions: indexById(asArray(cast && cast.factions && cast.factions.factions)),
+    locations: indexById(asArray(cast && cast.locations && cast.locations.locations)),
+    items: indexById(asArray(cast && cast.items && cast.items.items)),
+    conflicts: indexById(asArray(cast && cast.conflicts && cast.conflicts.conflicts)),
+    foreshadows: indexById(asArray(cast && cast.foreshadows && cast.foreshadows.foreshadows)),
+    climaxes: indexById(asArray(cast && cast.climaxes && cast.climaxes.climaxes)),
+    payoffs: indexById(asArray(cast && cast.payoffs && cast.payoffs.payoffs)),
+  };
+}