@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

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

@@ -0,0 +1,843 @@
+/**
+ * v2/scale.js —— 10-scale：只算数量，不写任何内容。
+ *
+ * 数量是全书唯一事实源：
+ *   - 章/卷/幕结构
+ *   - 人物/势力/地点/道具/冲突/伏笔/高潮/爽点/结局/信息差配额
+ *   - 节奏预算
+ *
+ * 本模块负责三件事：
+ *   1. 生成 LLM 选值的参考骨架（推荐值 + 公式区间 + 题材 profile）
+ *   2. 补齐公式/推导结果（value / range_low / range_high / derivations）
+ *   3. 校验所有数量、求和、题材倍率区间和内容字段
+ *
+ * 最终 scale.json 由 LLM 选择；buildScale() 只是推荐参考，不是最终事实源。
+ */
+import {
+  V2_STAGE_BY_ID,
+  asArray,
+  contentHash,
+  getByPath,
+  setByPath,
+  v2Error,
+} from './core.js';
+import {
+  actCountForChapters,
+  applyMultiplier,
+  distributionWeights,
+  formulaOverrides,
+  getProfile,
+  multiplierForCategory,
+  multiplierForFormula,
+  preferredVolumeCount,
+  structureVolumeRange,
+} from './genre.js';
+
+/**
+ * 旧公式字段路径 → 2.0 scale 路径。
+ * formulas-skeleton.json 里的 applies_to_field 是 1.x 路径，这里做唯一映射。
+ */
+export const FORMULA_FIELD_TO_SCALE = {
+  'quota.volume_count': 'structure.volume_count',
+  'quota.branch_count': 'quotas.branches',
+  'quota.character_counts.volume_supporting': 'quotas.characters.volume_supporting',
+  'quota.character_counts.volume_antagonist': 'quotas.characters.volume_antagonist',
+  'quota.conflict_counts.phase': 'quotas.conflicts.phase',
+  'quota.conflict_counts.branch': 'quotas.conflicts.branch',
+  'quota.faction_count': 'quotas.factions',
+  'quota.faction_relation_count': 'quotas.faction_relations',
+  'quota.location_count': 'quotas.locations',
+  'quota.foreshadow_counts.small': 'quotas.foreshadows.small',
+  'quota.foreshadow_counts.medium': 'quotas.foreshadows.medium',
+  'quota.foreshadow_counts.large': 'quotas.foreshadows.large',
+  'quota.climax_counts.small': 'quotas.climaxes.small',
+  'quota.climax_counts.medium': 'quotas.climaxes.medium',
+  'quota.climax_counts.large': 'quotas.climaxes.large',
+  'quota.pleasure_counts.small': 'quotas.pleasures.small',
+  'quota.pleasure_counts.medium': 'quotas.pleasures.medium',
+  'quota.pleasure_counts.large': 'quotas.pleasures.large',
+  'quota.item_counts.core': 'quotas.items.core',
+  'quota.item_counts.branch': 'quotas.items.branch',
+  'quota.item_counts.symbolic': 'quotas.items.symbolic',
+  'quota.world_rule_counts.core': 'quotas.world_rules.core',
+  'quota.world_rule_counts.information': 'quotas.world_rules.information',
+  'quota.world_rule_counts.social': 'quotas.world_rules.social',
+  'quota.ending_count': 'quotas.endings',
+  'quota.main_line_count': 'quotas.main_lines',
+  'quota.character_counts.protagonist': 'quotas.characters.protagonist',
+  'quota.character_counts.core_supporting': 'quotas.characters.core_supporting',
+  'quota.character_counts.core_antagonist': 'quotas.characters.core_antagonist',
+  'quota.conflict_counts.core': 'quotas.conflicts.core',
+};
+
+const CONTENT_KEYS = new Set([
+  'name', 'title', 'description', 'plot', 'story', 'outline', 'content',
+  'protagonist_name', 'antagonist_name', 'character_name', 'faction_name',
+  'location_name', 'item_name', 'chapter_title', 'summary',
+]);
+
+function evalExpr(expr, ctx) {
+  if (typeof expr !== 'string' || !expr) throw new Error('表达式为空');
+  if (!/^[0-9a-zA-Z_.\[\]()+\-*/%,\s=<>!&|?:]+$/.test(expr)) {
+    throw new Error('表达式含非法字符：' + expr);
+  }
+  const keys = Object.keys(ctx);
+  const fn = new Function(...keys, '"use strict"; return (' + expr + ');');
+  return fn(...keys.map((k) => ctx[k]));
+}
+
+export function formulaContext(scale) {
+  const q = (scale && scale.quotas) || {};
+  const char = q.characters || {};
+  return {
+    T: scale && scale.capacity ? Number(scale.capacity.target_chapters) : undefined,
+    V: scale && scale.structure ? Number(scale.structure.volume_count) : undefined,
+    P: Number(char.protagonist || 0),
+    CS: Number(char.core_supporting || 0),
+    CA: Number(char.core_antagonist || 0),
+    BC: Number(q.branches || 0),
+    CC: Number((q.conflicts && q.conflicts.core) || 0),
+    charTotal: ['protagonist', 'core_supporting', 'volume_supporting', 'core_antagonist', 'volume_antagonist']
+      .reduce((sum, key) => sum + Number((char && char[key]) || 0), 0),
+    quota: { faction_count: Number(q.factions || 0) },
+    Math,
+  };
+}
+
+/**
+ * 计算所有公式的合法区间与当前值。
+ * 返回 { formulas, errors }：errors 只包含公式表达式自身无法求值的情况。
+ */
+export function computeFormulas(scale, formulasDoc, opts = {}) {
+  const spec = {
+    ...((formulasDoc && formulasDoc.formulas) || {}),
+    ...((formulasDoc && formulasDoc.custom_formulas) || {}),
+  };
+  const profile = opts.profile || {};
+  const ctx = formulaContext(scale);
+  const out = {};
+  const errors = [];
+  const overrides = formulaOverrides(profile);
+  for (const key of Object.keys(spec)) {
+    const f = spec[key] || {};
+    const field = f.scale_field || FORMULA_FIELD_TO_SCALE[f.applies_to_field] || null;
+    let baseLow = null;
+    let baseHigh = null;
+    try {
+      if (key === 'structure.volume_count' && profile.structure && Array.isArray(profile.structure.volume_chapters)) {
+        const r = structureVolumeRange(ctx.T, profile);
+        baseLow = r.low;
+        baseHigh = r.high;
+      } else {
+        baseLow = evalExpr(f.expr_low, ctx);
+        baseHigh = evalExpr(f.expr_high, ctx);
+      }
+      const override = overrides[key];
+      if (Array.isArray(override) && override.length >= 2) {
+        baseLow = Number(override[0]);
+        baseHigh = Number(override[1]);
+      } else if (typeof override === 'string' && override.includes('~')) {
+        const [a, b] = override.split('~').map((x) => x.trim());
+        baseLow = evalExpr(a, ctx);
+        baseHigh = evalExpr(b, ctx);
+      }
+    } catch (err) {
+      errors.push(v2Error('SCALE_FORMULA_EVAL', {
+        path: 'formulas.' + key,
+        message: '公式无法求值：' + err.message,
+        contract: '10-scale/README.md#formulas',
+      }));
+    }
+    const multiplier = f.multiplier_category === null
+      ? 1
+      : (f.multiplier_category
+        ? multiplierForCategory(f.multiplier_category, profile)
+        : multiplierForFormula(key, profile));
+    const adjusted = applyMultiplier(baseLow, baseHigh, multiplier, {
+      allowZero: Number(baseLow) === 0,
+    });
+    const value = field ? getByPath(scale, field) : undefined;
+    out[key] = {
+      field,
+      formula: f.formula || '',
+      note: f.note || '',
+      value,
+      base_range_low: typeof baseLow === 'number' && Number.isFinite(baseLow) ? baseLow : null,
+      base_range_high: typeof baseHigh === 'number' && Number.isFinite(baseHigh) ? baseHigh : null,
+      genre_multiplier: multiplier,
+      range_low: typeof adjusted.low === 'number' && Number.isFinite(adjusted.low) ? adjusted.low : null,
+      range_high: typeof adjusted.high === 'number' && Number.isFinite(adjusted.high) ? adjusted.high : null,
+    };
+  }
+  return { formulas: out, errors };
+}
+
+/** 把公式与约束写回 scale（幂等）。 */
+export function finalizeScale(scale, formulasDoc, opts = {}) {
+  if (!scale || typeof scale !== 'object') return scale;
+  const profile = opts.profile || {};
+  const profileKey = opts.genreProfileKey || scale.genre_profile || 'default';
+  scale.formula_version = opts.formulaVersion || scale.formula_version || '2.1';
+  scale.genre_profile = profileKey;
+  if (!scale.capacity || typeof scale.capacity !== 'object') scale.capacity = {};
+  scale.capacity.base_words_per_chapter = Number(opts.baseWordsPerChapter || scale.capacity.base_words_per_chapter || 2000);
+  const avg = Number(scale.capacity.avg_words_per_chapter || 0);
+  scale.capacity.chapter_scale = avg > 0
+    ? Number((Number(scale.capacity.base_words_per_chapter) / avg).toFixed(4))
+    : null;
+
+  if (!scale.constraints || typeof scale.constraints !== 'object') scale.constraints = {};
+  const volumes = asArray(scale.structure && scale.structure.volumes);
+  const acts = asArray(scale.structure && scale.structure.acts);
+  const target = Number(scale.capacity && scale.capacity.target_chapters || 0);
+  scale.constraints.chapter_sum = volumes.reduce((sum, v) => sum + Number(v.chapters || 0), 0);
+  scale.constraints.act_chapter_sum = acts.reduce((sum, a) => sum + Number(a.chapters || 0), 0);
+  scale.constraints.target_chapters = target;
+  scale.constraints.volume_ratio_sum = Number(
+    volumes.reduce((sum, v) => sum + Number(v.ratio || 0), 0).toFixed(6)
+  );
+  scale.constraints.no_content_fields = true;
+
+  const computed = computeFormulas(scale, formulasDoc, { profile });
+  const existing = (scale.formulas && typeof scale.formulas === 'object') ? scale.formulas : {};
+  const existingDerivations = (scale.derivations && typeof scale.derivations === 'object') ? scale.derivations : {};
+  const llmReasons = (scale.derivation_reasons && typeof scale.derivation_reasons === 'object') ? scale.derivation_reasons : {};
+  scale.formulas = {};
+  scale.derivations = {};
+  for (const key of Object.keys(computed.formulas)) {
+    const item = computed.formulas[key];
+    const old = existing[key] || {};
+    const oldDerivation = existingDerivations[key] || {};
+    const reason = [
+      llmReasons[key],
+      llmReasons[item.field],
+      llmReasons[item.scale_field],
+      oldDerivation.reason,
+      old.deviation_reason,
+    ].find((x) => typeof x === 'string' && x.trim()) || '';
+    scale.formulas[key] = {
+      ...item,
+      deviation_reason: reason,
+    };
+    scale.derivations[key] = {
+      formula: item.formula,
+      base_range: [item.base_range_low, item.base_range_high],
+      genre_multiplier: item.genre_multiplier,
+      adjusted_range: [item.range_low, item.range_high],
+      chosen: item.value,
+      reason,
+    };
+  }
+  return scale;
+}
+
+function rangeOf(formulas, key) {
+  const f = formulas && formulas[key];
+  if (!f) return null;
+  const low = Number(f.range_low);
+  const high = Number(f.range_high);
+  if (!Number.isFinite(low) || !Number.isFinite(high)) return null;
+  return low <= high ? { low, high } : { low: high, high: low };
+}
+
+function choose(formulas, key, fallback = 0) {
+  const r = rangeOf(formulas, key);
+  if (!r) return fallback;
+  return Math.max(0, Math.round(r.low));
+}
+
+function allocate(total, parts) {
+  const out = [];
+  const n = Math.max(0, Math.floor(Number(total) || 0));
+  const p = Math.max(1, Math.floor(Number(parts) || 1));
+  const base = Math.floor(n / p);
+  let rem = n % p;
+  for (let i = 0; i < p; i += 1) {
+    let v = base + (rem > 0 ? 1 : 0);
+    if (rem > 0) rem -= 1;
+    out.push(v);
+  }
+  return out;
+}
+
+function distributeTotal(total, weights) {
+  const n = Math.max(0, Math.floor(Number(total) || 0));
+  const ws = (weights || []).map((w) => Math.max(0, Number(w) || 0));
+  const sum = ws.reduce((a, b) => a + b, 0) || ws.length || 1;
+  const raw = ws.map((w) => n * w / sum);
+  const out = raw.map((x) => Math.floor(x));
+  let rem = n - out.reduce((a, b) => a + b, 0);
+  const order = raw.map((x, i) => ({ i, frac: x - Math.floor(x) }))
+    .sort((a, b) => b.frac - a.frac || a.i - b.i);
+  for (let k = 0; k < order.length && rem > 0; k += 1) {
+    out[order[k].i] += 1;
+    rem -= 1;
+  }
+  return out;
+}
+
+function distributeWeighted(total, weights) {
+  const n = Math.max(0, Math.floor(Number(total) || 0));
+  const ws = (weights || []).map((w) => Math.max(0, Number(w) || 0));
+  if (!ws.length) return [];
+  const sum = ws.reduce((a, b) => a + b, 0) || ws.length;
+  const raw = ws.map((w) => n * w / sum);
+  const out = raw.map((x) => Math.floor(x));
+  let rem = n - out.reduce((a, b) => a + b, 0);
+  const order = raw.map((x, i) => ({ i, frac: x - Math.floor(x) }))
+    .sort((a, b) => b.frac - a.frac || a.i - b.i);
+  for (let k = 0; k < order.length && rem > 0; k += 1) {
+    out[order[k].i] += 1;
+    rem -= 1;
+  }
+  return out;
+}
+
+function pad3(n) {
+  return String(n).padStart(3, '0');
+}
+
+/**
+ * 生成 LLM 选值的参考数量表：公式区间 + 题材倍率 + 推荐结构。
+ * 这不是最终事实源；最终值由 LLM 在区间内选择并经 validateScale 校验。
+ */
+export function buildScale(topicData, formulasDoc, opts = {}) {
+  const topic = topicData || {};
+  const profile = opts.profile || {};
+  const profileKey = opts.genreProfileKey || 'default';
+  const T = Math.max(1, Math.floor(Number(topic.target_chapters) || 300));
+  const words = Math.max(T, Math.floor(Number(topic.target_words) || T * 3000));
+  const avg = Math.max(1, Math.round(words / T));
+
+  const vr = structureVolumeRange(T, profile);
+  const lowV = vr.low;
+  const highV = vr.high;
+  const V = preferredVolumeCount(T, profile, lowV, highV);
+
+  // 先放一个临时 scale，让公式引擎能算出区间。
+  const scale = {
+    formula_version: opts.formulaVersion || '2.1',
+    genre_profile: profileKey,
+    capacity: {
+      target_chapters: T,
+      target_words: words,
+      avg_words_per_chapter: avg,
+      base_words_per_chapter: Number(opts.baseWordsPerChapter || 2000),
+    },
+    structure: { volume_count: V, total_acts: 0, volumes: [], acts: [] },
+    quotas: {
+      characters: { protagonist: 0, core_supporting: 0, volume_supporting: 0, core_antagonist: 0, volume_antagonist: 0 },
+      factions: 0,
+      faction_relations: 0,
+      locations: 0,
+      items: { core: 0, branch: 0, symbolic: 0 },
+      conflicts: { core: 0, phase: 0, branch: 0 },
+      foreshadows: { small: 0, medium: 0, large: 0 },
+      climaxes: { small: 0, medium: 0, large: 0 },
+      pleasures: { small: 0, medium: 0, large: 0 },
+      endings: 0,
+      world_rules: { core: 0, information: 0, social: 0 },
+      main_lines: 1,
+      branches: 0,
+      information_gaps: 0,
+      relations: { character: 0, faction: 0, membership: 0 },
+    },
+    rhythm_budget: {},
+    distribution: {},
+    formulas: {},
+    constraints: {},
+  };
+
+  const q = scale.quotas;
+  // 先把不依赖其它配额的量算出来。
+  let computed = computeFormulas(scale, formulasDoc, { profile }).formulas;
+  q.characters.protagonist = choose(computed, 'fixed.character_elements.protagonist_count', 1);
+  q.characters.core_supporting = choose(computed, 'fixed.character_elements.core_supporting_count', 2);
+  q.characters.core_antagonist = choose(computed, 'fixed.character_elements.core_antagonist_count', 1);
+  q.characters.volume_supporting = choose(computed, 'character_elements.volume_supporting_count', 0);
+  q.characters.volume_antagonist = choose(computed, 'character_elements.volume_antagonist_count', 0);
+  q.factions = choose(computed, 'faction_elements.faction_count', 2);
+  q.locations = choose(computed, 'location_elements.key_location_count', 3);
+  q.main_lines = 1;
+  q.branches = choose(computed, 'structure.branch_count', 1);
+  q.conflicts.core = choose(computed, 'fixed.conflict_elements.core_conflict_count', 1);
+  // BC / CC / n 现在才齐；重算一次，再算依赖它们的配额。
+  computed = computeFormulas(scale, formulasDoc, { profile }).formulas;
+  q.faction_relations = choose(computed, 'faction_elements.faction_relation_count', Math.max(1, q.factions - 1));
+  q.items.core = choose(computed, 'item_elements.core_item_count', 2);
+  q.items.branch = choose(computed, 'item_elements.branch_item_count', 2);
+  q.items.symbolic = choose(computed, 'item_elements.symbolic_item_count', 1);
+  q.conflicts.phase = choose(computed, 'conflict_elements.phase_conflict_count', 1);
+  q.conflicts.branch = choose(computed, 'conflict_elements.branch_conflict_count', 2);
+  q.foreshadows.small = choose(computed, 'foreshadow_elements.small_foreshadow_count', 3);
+  q.foreshadows.medium = choose(computed, 'foreshadow_elements.medium_foreshadow_count', 1);
+  q.foreshadows.large = choose(computed, 'foreshadow_elements.large_foreshadow_count', 1);
+  q.climaxes.small = choose(computed, 'climax_elements.small_climax_count', 5);
+  q.climaxes.medium = choose(computed, 'climax_elements.medium_climax_count', 1);
+  q.climaxes.large = choose(computed, 'climax_elements.large_climax_count', 1);
+  q.pleasures.small = choose(computed, 'pleasure_elements.small_pleasure_count', 8);
+  q.pleasures.medium = choose(computed, 'pleasure_elements.medium_pleasure_count', 3);
+  q.pleasures.large = choose(computed, 'pleasure_elements.large_pleasure_count', 1);
+  q.endings = choose(computed, 'ending_elements.ending_count', V);
+  q.world_rules.core = choose(computed, 'world_rule_counts.core', 1);
+  q.world_rules.information = choose(computed, 'world_rule_counts.information', 1);
+  q.world_rules.social = choose(computed, 'world_rule_counts.social', 1);
+  q.information_gaps = Math.max(15, Math.ceil(T / 8));
+  const charTotal = q.characters.protagonist + q.characters.core_supporting +
+    q.characters.volume_supporting + q.characters.core_antagonist + q.characters.volume_antagonist;
+  q.relations.character = Math.max(charTotal + 2, Math.round(charTotal * 1.75));
+  const custom = computeFormulas(scale, formulasDoc, { profile }).formulas;
+  q.information_gaps = Math.max(1, Number(custom['custom.information_gaps']?.range_low || q.information_gaps));
+  q.relations.character = Math.max(1, Number(custom['custom.relations_character']?.range_low || q.relations.character));
+  q.relations.faction = q.faction_relations;
+  q.relations.membership = Math.max(charTotal, q.factions);
+
+  // 卷/幕分配
+  const volumeChapters = allocate(T, V);
+  let chapterStart = 1;
+  const actIds = [];
+  for (let i = 0; i < V; i += 1) {
+    const volumeId = 'V' + pad3(i + 1);
+    const chapters = volumeChapters[i];
+    const actCount = actCountForChapters(chapters, profile);
+    const actChapters = allocate(chapters, actCount);
+    const acts = [];
+    let actStart = chapterStart;
+    for (let a = 0; a < actCount; a += 1) {
+      const actId = 'A' + pad3(actIds.length + 1);
+      actIds.push(actId);
+      acts.push({
+        act_id: actId,
+        volume_id: volumeId,
+        act_index: a + 1,
+        chapter_start: actStart,
+        chapter_end: actStart + actChapters[a] - 1,
+        chapters: actChapters[a],
+      });
+      actStart += actChapters[a];
+    }
+    scale.structure.volumes.push({
+      volume_id: volumeId,
+      chapters,
+      ratio: Number((chapters / T).toFixed(6)),
+      act_count: actCount,
+      chapter_start: chapterStart,
+      chapter_end: chapterStart + chapters - 1,
+      acts,
+    });
+    scale.structure.acts.push(...acts);
+    chapterStart += chapters;
+  }
+  scale.structure.total_acts = scale.structure.acts.length;
+  // 比例尾差补到最后 1 卷，保证严格等于 1。
+  const ratioSum = scale.structure.volumes.reduce((sum, v) => sum + v.ratio, 0);
+  if (scale.structure.volumes.length) {
+    const last = scale.structure.volumes[scale.structure.volumes.length - 1];
+    last.ratio = Number((last.ratio + (1 - ratioSum)).toFixed(6));
+  }
+
+  // 分布
+  const volumeIds = scale.structure.volumes.map((v) => v.volume_id);
+  const volumeSupporting = distributeWeighted(q.characters.volume_supporting, distributionWeights(profile, 'new_entities', V));
+  const volumeAntagonist = distributeWeighted(q.characters.volume_antagonist, distributionWeights(profile, 'new_entities', V));
+  const phaseConflicts = distributeWeighted(q.conflicts.phase, distributionWeights(profile, 'conflicts', V));
+  const fSmall = distributeWeighted(q.foreshadows.small, distributionWeights(profile, 'foreshadows', V));
+  const fMedium = distributeWeighted(q.foreshadows.medium, distributionWeights(profile, 'foreshadows', V));
+  const fLarge = distributeWeighted(q.foreshadows.large, distributionWeights(profile, 'foreshadows', V));
+  const cSmall = distributeWeighted(q.climaxes.small, distributionWeights(profile, 'climaxes', V));
+  const cMedium = distributeWeighted(q.climaxes.medium, distributionWeights(profile, 'climaxes', V));
+  const cLarge = distributeWeighted(q.climaxes.large, distributionWeights(profile, 'climaxes', V));
+  const pSmall = distributeWeighted(q.pleasures.small, distributionWeights(profile, 'payoffs', V));
+  const pMedium = distributeWeighted(q.pleasures.medium, distributionWeights(profile, 'payoffs', V));
+  const pLarge = distributeWeighted(q.pleasures.large, distributionWeights(profile, 'payoffs', V));
+  for (let i = 0; i < V; i += 1) {
+    const id = volumeIds[i];
+    scale.distribution[id] = {
+      chapters: volumeChapters[i],
+      volume_supporting: volumeSupporting[i],
+      volume_antagonist: volumeAntagonist[i],
+      phase_conflicts: phaseConflicts[i],
+      foreshadows: { small: fSmall[i], medium: fMedium[i], large: fLarge[i] },
+      climaxes: { small: cSmall[i], medium: cMedium[i], large: cLarge[i] },
+      pleasures: { small: pSmall[i], medium: pMedium[i], large: pLarge[i] },
+    };
+  }
+
+  const reversalMultiplier = multiplierForCategory('reversals', profile);
+  const reversalMinBase = Math.max(1, Math.floor(T / 12));
+  const reversalTargetBase = Math.max(reversalMinBase, Math.floor(T / 7));
+  const reversalMin = Math.max(1, Math.round(reversalMinBase * reversalMultiplier));
+  const reversalTarget = Math.max(reversalMin, Math.round(reversalTargetBase * reversalMultiplier));
+  scale.rhythm_budget = {
+    hooks: { min: T, target: Math.ceil(T * 1.3) },
+    reveals: { min: Math.floor(T / 10), target: Math.floor(T / 6) },
+    reversals: { min: reversalMin, target: reversalTarget },
+    emotional_peaks: { min: Math.floor(T / 12), target: Math.floor(T / 8) },
+    climax_chapters: q.climaxes.large,
+    payoff_chapters: q.pleasures.large + q.pleasures.medium,
+    golden_three: { hook_strength: '强', must_establish: ['世界观入门', '主角立住', '核心冲突抛出'] },
+  };
+  scale.distribution_weights = {
+    new_entities: distributionWeights(profile, 'new_entities', V),
+    relationships: distributionWeights(profile, 'relationships', V),
+    foreshadows: distributionWeights(profile, 'foreshadows', V),
+    payoffs: distributionWeights(profile, 'payoffs', V),
+    climaxes: distributionWeights(profile, 'climaxes', V),
+    conflicts: distributionWeights(profile, 'conflicts', V),
+    information: distributionWeights(profile, 'information', V),
+  };
+
+  finalizeScale(scale, formulasDoc, {
+    profile,
+    genreProfileKey: profileKey,
+    formulaVersion: opts.formulaVersion,
+    baseWordsPerChapter: opts.baseWordsPerChapter,
+  });
+  // 修正 total_acts 等派生字段在 finalize 之后仍保持
+  return scale;
+}
+
+/** 人类可读数量表（stage 内自包含文件）。 */
+export function renderScaleMd(scale) {
+  const lines = [];
+  const c = scale.capacity || {};
+  lines.push('# 数量表（10-scale）');
+  lines.push('');
+  lines.push('> 本文件只记录数量与预算，不含人物、势力、地点和剧情。');
+  lines.push('');
+  lines.push('## 规模');
+  lines.push('');
+  lines.push('- 总章数：' + c.target_chapters);
+  lines.push('- 总字数：' + c.target_words);
+  lines.push('- 平均每章：' + c.avg_words_per_chapter);
+  lines.push('- 卷数：' + (scale.structure && scale.structure.volume_count));
+  lines.push('- 幕数：' + (scale.structure && scale.structure.total_acts));
+  lines.push('- 题材 profile：' + (scale.genre_profile || 'default'));
+  lines.push('- 公式版本：' + (scale.formula_version || '2.1'));
+  lines.push('- 章节字数基准：' + (c.base_words_per_chapter || 2000) + ' 字；chapter_scale=' + (c.chapter_scale ?? ''));
+  lines.push('');
+  lines.push('## 卷');
+  lines.push('');
+  lines.push('| 卷 | 章节区间 | 章数 | 幕数 | 占比 |');
+  lines.push('|---|---|---|---|---|');
+  for (const v of asArray(scale.structure && scale.structure.volumes)) {
+    lines.push('| ' + v.volume_id + ' | ' + v.chapter_start + '-' + v.chapter_end + ' | ' +
+      v.chapters + ' | ' + v.act_count + ' | ' + v.ratio + ' |');
+  }
+  lines.push('');
+  lines.push('## 配额');
+  lines.push('');
+  const q = scale.quotas || {};
+  const rows = [
+    ['人物', '主角', q.characters && q.characters.protagonist],
+    ['人物', '贯穿级核心配角', q.characters && q.characters.core_supporting],
+    ['人物', '卷级重要配角', q.characters && q.characters.volume_supporting],
+    ['人物', '贯穿级核心反派', q.characters && q.characters.core_antagonist],
+    ['人物', '卷级反派', q.characters && q.characters.volume_antagonist],
+    ['势力', '全部', q.factions],
+    ['势力关系', '全部', q.faction_relations],
+    ['地点', '全部', q.locations],
+    ['道具', '核心/支线/象征', [q.items && q.items.core, q.items && q.items.branch, q.items && q.items.symbolic].join(' / ')],
+    ['冲突', '核心/阶段/交织', [q.conflicts && q.conflicts.core, q.conflicts && q.conflicts.phase, q.conflicts && q.conflicts.branch].join(' / ')],
+    ['伏笔', '小/中/大', [q.foreshadows && q.foreshadows.small, q.foreshadows && q.foreshadows.medium, q.foreshadows && q.foreshadows.large].join(' / ')],
+    ['高潮', '小/中/大', [q.climaxes && q.climaxes.small, q.climaxes && q.climaxes.medium, q.climaxes && q.climaxes.large].join(' / ')],
+    ['爽点', '小/中/大', [q.pleasures && q.pleasures.small, q.pleasures && q.pleasures.medium, q.pleasures && q.pleasures.large].join(' / ')],
+    ['结局', '全部', q.endings],
+    ['主线/支线', '全部', [q.main_lines, q.branches].join(' / ')],
+    ['信息差', '全部', q.information_gaps],
+  ];
+  lines.push('| 类型 | 细分 | 数量 |');
+  lines.push('|---|---|---|');
+  for (const [a, b, n] of rows) lines.push('| ' + a + ' | ' + b + ' | ' + n + ' |');
+  lines.push('');
+  lines.push('## 节奏预算');
+  lines.push('');
+  for (const [key, value] of Object.entries(scale.rhythm_budget || {})) {
+    lines.push('- ' + key + '：' + JSON.stringify(value));
+  }
+  lines.push('');
+  lines.push('## 公式');
+  lines.push('');
+  lines.push('| 公式 | 值 | 合法区间 |');
+  lines.push('|---|---|---|');
+  for (const [key, f] of Object.entries(scale.formulas || {})) {
+    lines.push('| ' + key + ' | ' + f.value + ' | ' + f.range_low + ' ~ ' + f.range_high + ' |');
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * 校验数量表。
+ * @returns {{ok:boolean, errors:Array, warnings:Array, data:Object}}
+ */
+export function validateScale(scale, formulasDoc, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!scale || typeof scale !== 'object') {
+    return {
+      ok: false,
+      errors: [v2Error('SCALE_MISSING', { path: '10-scale/scale.json', message: '数量表不存在或不是 JSON 对象', contract: '10-scale/README.md' })],
+      warnings,
+      data: null,
+    };
+  }
+
+  const profilesDoc = opts.profilesDoc || null;
+  const profileKey = scale.genre_profile || opts.genreProfileKey || 'default';
+  const profile = opts.profile || (profilesDoc ? getProfile(profilesDoc, profileKey) : {});
+  if (profilesDoc && profilesDoc.profiles && !profilesDoc.profiles[profileKey]) {
+    errors.push(v2Error('SCALE_GENRE_PROFILE', {
+      path: 'genre_profile',
+      message: '题材 profile 不存在：' + profileKey,
+      expected: Object.keys(profilesDoc.profiles).join(' / '),
+      actual: profileKey,
+      contract: '10-scale/README.md#genre-profile',
+    }));
+  }
+  if (!scale.formula_version) {
+    warnings.push(v2Error('SCALE_FORMULA_VERSION', {
+      path: 'formula_version', severity: 'warning',
+      message: '缺少 formula_version，将按默认 2.1 处理',
+      contract: '10-scale/README.md#formula-version',
+    }));
+  }
+  const c = scale.capacity || {};
+  const T = Number(c.target_chapters);
+  const words = Number(c.target_words);
+  if (!Number.isInteger(T) || T <= 0) {
+    errors.push(v2Error('SCALE_CAPACITY', { path: 'capacity.target_chapters', message: '必须是正整数', expected: '>0', actual: c.target_chapters, contract: '10-scale/README.md#capacity' }));
+  }
+  if (!Number.isInteger(words) || words <= 0) {
+    errors.push(v2Error('SCALE_CAPACITY', { path: 'capacity.target_words', message: '必须是正整数', expected: '>0', actual: c.target_words, contract: '10-scale/README.md#capacity' }));
+  }
+  if (Number.isInteger(T) && Number.isInteger(words)) {
+    const avg = Math.round(words / T);
+    if (Number(c.avg_words_per_chapter) !== avg) {
+      errors.push(v2Error('SCALE_CAPACITY_MISMATCH', {
+        path: 'capacity.avg_words_per_chapter',
+        message: '平均每章字数必须等于 round(target_words / target_chapters)',
+        expected: avg, actual: c.avg_words_per_chapter,
+        contract: '10-scale/README.md#capacity',
+      }));
+    }
+  }
+
+  if (c.base_words_per_chapter !== undefined && (!Number.isFinite(Number(c.base_words_per_chapter)) || Number(c.base_words_per_chapter) <= 0)) {
+    errors.push(v2Error('SCALE_BASE_WORDS', { path: 'capacity.base_words_per_chapter', message: 'base_words_per_chapter 必须是正数', actual: c.base_words_per_chapter, contract: '10-scale/README.md#capacity' }));
+  }
+  if (Number.isInteger(T) && Number.isInteger(words)) {
+    const avg = Math.round(words / T);
+    const base = Number(c.base_words_per_chapter || 2000);
+    const expectedScale = avg > 0 ? Number((base / avg).toFixed(4)) : null;
+    if (c.chapter_scale !== undefined && Number(c.chapter_scale) !== expectedScale) {
+      warnings.push(v2Error('SCALE_CHAPTER_SCALE', { path: 'capacity.chapter_scale', severity: 'warning', message: 'chapter_scale 与 base_words_per_chapter / avg_words_per_chapter 不一致', expected: expectedScale, actual: c.chapter_scale, contract: '10-scale/README.md#capacity' }));
+    }
+  }
+
+  const s = scale.structure || {};
+  const vCount = Number(s.volume_count);
+  const volumes = asArray(s.volumes);
+  const acts = asArray(s.acts);
+  if (!Number.isInteger(vCount) || vCount <= 0) {
+    errors.push(v2Error('SCALE_STRUCTURE', { path: 'structure.volume_count', message: '卷数必须是正整数', contract: '10-scale/README.md#structure' }));
+  }
+  if (vCount !== volumes.length) {
+    errors.push(v2Error('SCALE_VOLUME_COUNT', {
+      path: 'structure.volume_count',
+      message: 'volume_count 必须等于 volumes 数组长度',
+      expected: volumes.length, actual: vCount,
+      contract: '10-scale/README.md#structure',
+    }));
+  }
+  let chapterSum = 0;
+  let ratioSum = 0;
+  let expectedStart = 1;
+  const volumeIds = new Set();
+  for (let i = 0; i < volumes.length; i += 1) {
+    const v = volumes[i] || {};
+    const id = v.volume_id || v.id;
+    if (!id) errors.push(v2Error('SCALE_VOLUME_ID', { path: 'structure.volumes[' + i + '].volume_id', message: '缺少卷 ID', contract: '10-scale/README.md#structure' }));
+    else if (volumeIds.has(id)) errors.push(v2Error('SCALE_VOLUME_ID_DUP', { path: 'structure.volumes[' + i + '].volume_id', message: '卷 ID 重复：' + id, contract: '10-scale/README.md#structure' }));
+    else volumeIds.add(id);
+    const chapters = Number(v.chapters);
+    if (!Number.isInteger(chapters) || chapters <= 0) {
+      errors.push(v2Error('SCALE_VOLUME_CHAPTERS', { path: 'structure.volumes[' + i + '].chapters', message: '每卷章数必须是正整数', contract: '10-scale/README.md#structure' }));
+    } else {
+      chapterSum += chapters;
+    }
+    if (Number(v.chapter_start) !== expectedStart) {
+      errors.push(v2Error('SCALE_VOLUME_RANGE', {
+        path: 'structure.volumes[' + i + '].chapter_start',
+        message: '卷章节区间必须连续且从 1 开始',
+        expected: expectedStart, actual: v.chapter_start,
+        contract: '10-scale/README.md#structure',
+      }));
+    }
+    expectedStart = Number(v.chapter_start || expectedStart) + Number(v.chapters || 0);
+    if (Number(v.chapter_end) !== expectedStart - 1) {
+      errors.push(v2Error('SCALE_VOLUME_RANGE', {
+        path: 'structure.volumes[' + i + '].chapter_end',
+        message: 'chapter_end 必须等于 chapter_start + chapters - 1',
+        expected: expectedStart - 1, actual: v.chapter_end,
+        contract: '10-scale/README.md#structure',
+      }));
+    }
+    ratioSum += Number(v.ratio || 0);
+    const localActs = asArray(v.acts);
+    const actChapters = localActs.reduce((sum, a) => sum + Number(a.chapters || 0), 0);
+    if (localActs.length && actChapters !== chapters) {
+      errors.push(v2Error('SCALE_ACT_CHAPTER_SUM', {
+        path: 'structure.volumes[' + i + '].acts',
+        message: '本卷各幕章数之和必须等于本卷章数',
+        expected: chapters, actual: actChapters,
+        contract: '10-scale/README.md#structure',
+      }));
+    }
+    if (!localActs.length) {
+      errors.push(v2Error('SCALE_ACTS_MISSING', { path: 'structure.volumes[' + i + '].acts', message: '每卷至少要有 1 幕', contract: '10-scale/README.md#structure' }));
+    }
+  }
+  if (Number.isInteger(T) && chapterSum !== T) {
+    errors.push(v2Error('SCALE_CHAPTER_SUM', {
+      path: 'structure.volumes',
+      message: '各卷章数之和必须等于 capacity.target_chapters',
+      expected: T, actual: chapterSum,
+      hint: '检查 structure.volumes[*].chapters',
+      contract: '10-scale/README.md#structure',
+    }));
+  }
+  if (Math.abs(ratioSum - 1) > 0.00001) {
+    errors.push(v2Error('SCALE_RATIO_SUM', {
+      path: 'structure.volumes',
+      message: '各卷 ratio 之和必须等于 1',
+      expected: 1, actual: Number(ratioSum.toFixed(6)),
+      contract: '10-scale/README.md#structure',
+    }));
+  }
+  if (acts.length !== volumes.reduce((sum, v) => sum + asArray(v.acts).length, 0)) {
+    errors.push(v2Error('SCALE_ACTS_FLAT_MISMATCH', { path: 'structure.acts', message: 'structure.acts 必须包含所有卷的全部幕', contract: '10-scale/README.md#structure' }));
+  }
+  if (Number(s.total_acts) !== acts.length) {
+    errors.push(v2Error('SCALE_TOTAL_ACTS', {
+      path: 'structure.total_acts',
+      message: 'total_acts 必须等于 structure.acts 数量',
+      expected: acts.length, actual: s.total_acts,
+      contract: '10-scale/README.md#structure',
+    }));
+  }
+  const actIds = new Set();
+  for (let i = 0; i < acts.length; i += 1) {
+    const a = acts[i] || {};
+    if (!a.act_id) errors.push(v2Error('SCALE_ACT_ID', { path: 'structure.acts[' + i + '].act_id', message: '缺少 act_id', contract: '10-scale/README.md#structure' }));
+    else if (actIds.has(a.act_id)) errors.push(v2Error('SCALE_ACT_ID_DUP', { path: 'structure.acts[' + i + '].act_id', message: 'act_id 重复：' + a.act_id, contract: '10-scale/README.md#structure' }));
+    else actIds.add(a.act_id);
+    if (a.volume_id && !volumeIds.has(a.volume_id)) {
+      errors.push(v2Error('SCALE_ACT_VOLUME', { path: 'structure.acts[' + i + '].volume_id', message: '幕引用了不存在的卷：' + a.volume_id, contract: '10-scale/README.md#structure' }));
+    }
+  }
+
+  // 配额：所有叶子必须是非负整数
+  const q = scale.quotas || {};
+  const quotaLeaves = [];
+  const walk = (obj, prefix) => {
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+      for (const [k, v] of Object.entries(obj)) walk(v, prefix ? prefix + '.' + k : k);
+    } else {
+      quotaLeaves.push([prefix, obj]);
+    }
+  };
+  walk(q, 'quotas');
+  for (const [p, v] of quotaLeaves) {
+    if (!Number.isInteger(Number(v)) || Number(v) < 0) {
+      errors.push(v2Error('SCALE_QUOTA', {
+        path: p, message: '配额必须是非负整数', actual: v,
+        contract: '10-scale/README.md#quotas',
+      }));
+    }
+  }
+
+  // 公式
+  finalizeScale(scale, formulasDoc, { profile, genreProfileKey: profileKey, profilesDoc });
+  for (const [key, f] of Object.entries(scale.formulas || {})) {
+    if (!f.field) continue;
+    const value = Number(f.value);
+    const low = Number(f.range_low);
+    const high = Number(f.range_high);
+    if (!Number.isFinite(value) || !Number.isFinite(low) || !Number.isFinite(high)) continue;
+    if (value < low || value > high) {
+      const reason = String(f.deviation_reason || '').trim();
+      const item = {
+        code: 'SCALE_FORMULA_RANGE',
+        path: f.field,
+        message: '数量不在公式区间内：' + key,
+        expected: low + ' ~ ' + high,
+        actual: value,
+        hint: reason ? '已填写 deviation_reason：' + reason : '改为区间内的值（区间已按题材倍率调整），或在 derivation_reasons 里用 `' + key + '` 或 `' + (f.field || '') + '` 写偏离原因',
+        contract: '10-scale/README.md#formulas',
+      };
+      if (reason) warnings.push(item);
+      else errors.push(item);
+    }
+  }
+
+  // 分布必须与卷一致
+  const dist = scale.distribution || {};
+  for (const v of volumes) {
+    const id = v.volume_id || v.id;
+    if (!id) continue;
+    const d = dist[id];
+    if (!d) {
+      warnings.push(v2Error('SCALE_DISTRIBUTION_MISSING', {
+        path: 'distribution.' + id, message: '缺少本卷的数量分布', severity: 'warning', contract: '10-scale/README.md#distribution',
+      }));
+      continue;
+    }
+    if (Number(d.chapters) !== Number(v.chapters)) {
+      errors.push(v2Error('SCALE_DISTRIBUTION_CHAPTERS', {
+        path: 'distribution.' + id + '.chapters',
+        message: '分布里的章数必须等于卷章数', expected: v.chapters, actual: d.chapters,
+        contract: '10-scale/README.md#distribution',
+      }));
+    }
+  }
+  const distExtra = Object.keys(dist).filter((id) => !volumeIds.has(id));
+  if (distExtra.length) {
+    warnings.push(v2Error('SCALE_DISTRIBUTION_EXTRA', {
+      path: 'distribution', message: '分布里有不存在的卷：' + distExtra.join('、'), severity: 'warning', contract: '10-scale/README.md#distribution',
+    }));
+  }
+
+  // 不允许内容字段
+  const scanContent = (value, prefix) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => scanContent(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 (CONTENT_KEYS.has(key) && typeof val === 'string' && val.trim()) {
+        errors.push(v2Error('SCALE_CONTENT_FIELD', {
+          path: p,
+          message: '数量阶段不允许出现内容字段（人名/标题/剧情等）',
+          actual: val.slice(0, 40),
+          hint: '把内容留到 20-macro 或 30-cast；本文件只写数字',
+          contract: '10-scale/README.md#forbidden',
+        }));
+      }
+      if (key === 'formulas') continue;
+      scanContent(val, p);
+    }
+  };
+  scanContent(scale, '');
+
+  return { ok: errors.length === 0, errors, warnings, data: scale };
+}
+
+/** 内容哈希（供 manifest 使用）。 */
+export function scaleHash(scale) {
+  return contentHash(scale);
+}
+
+export const SCALE_STAGE = V2_STAGE_BY_ID['10-scale'];