@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-story-builder/scripts/skeleton-validate.js

@@ -0,0 +1,1973 @@
+#!/usr/bin/env node
+/**
+ * 骨架阶段校验脚本 v2.5
+ * 源码中零反引号（所有字符串使用单/双引号或拼接），避免 markdown 渲染问题。
+ *
+ * v2.5 变更：
+ * - 新增 NAME_ALIAS_SUSPECT：名称归一化（去括号/标点/常见机构后缀）后
+ *   相同，但字面不同 → warning，提示可能是同一实体的全称/简称/别名。
+ * - CROSS_TYPE_NAME_DUP 改用同一套归一化口径，能抓「企鹅集团 vs 企鹅」
+ *   这种跨类型软重复。
+ *
+ * v2.4 变更（修复批次 P0-2 / P2-4 / P2-8）：
+ * - P0-2：evalExpr 正则允许 = < > ! & | ? :（原版不允许，导致
+ *   formulas-skeleton.json 的 ending_elements.ending_count 的 expr_low/expr_high
+ *   含 === 和三元运算符，求值必失败，DERIVATION_EVAL 阻断骨架全量校验）
+ * - P2-4：新增 faction_relation_count 的 QUOTA 一致性检查（需要关系.json）
+ * - P2-8：buildGraph 删除无效的 volumes 循环（实体.json 无 volumes 字段）
+ *
+ * 保留 v2.3 的 P3-4b 修复：
+ * - NO_SELF_RELATION / EMPTY_HARD_CONSTRAINTS / CROSS_TYPE_NAME_DUP
+ * 保留 v2.2 的 P0-2 / P2-2 修复：
+ * - QUOTA_MISMATCH / BOOK_ENDING_COUNT / VOLUME_COUNT_MISMATCH / ACT_INDEX_DUP
+ * - SPAN_RATIO_RANGE / 关系组合重复检查
+ *
+ * 用法：
+ *   单文件：node skeleton-validate.js --input=<json> --template=<模板> --file=<类型> [--upstream=<目录>]
+ *   全量：  node skeleton-validate.js --stage-dir=<目录> --template-dir=<目录> --all
+ * 退出码：0=通过  1=内容错误  2=脚本异常
+ */
+
+import { evalExpr, buildFormulaContext, formulaRange } from './formula-engine.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  safeCheck,
+  SimpleGraph,
+  getIsolatedNodes,
+  getDisconnectedCoreNodes,
+  checkBidirectionalSymmetry,
+  parseGlossaryChecked,
+  mdEscape,
+  cnLabelCtx,
+  renderObject,
+  renderArray,
+  relationKindCompatible,
+  assertRelationKindMeta
+} from './graph-utils.js';
+import { runContentQualityChecks, collectEnumLeaves } from './content-quality.js';
+import { QUOTA_MAP } from './skeleton-quota.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ============================================================
+// 参数解析
+// ============================================================
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = { upstream: [] };
+  for (const arg of args) {
+    const m = arg.match(/^--([\w-]+)=(.+)$/);
+    if (m) {
+      if (m[1] === 'upstream') {
+        result.upstream.push(...m[2].split(',').map(s => s.trim()).filter(Boolean));
+      } else {
+        result[m[1]] = m[2];
+      }
+    } else if (arg === '--all') {
+      result.all = true;
+    }
+  }
+  return result;
+}
+
+// ============================================================
+// IO
+// ============================================================
+function readJson(p) {
+  if (!fs.existsSync(p)) return { error: '文件不存在: ' + p };
+  try {
+    return { data: JSON.parse(fs.readFileSync(p, 'utf-8')) };
+  } catch (err) {
+    return { error: 'JSON 解析失败: ' + err.message };
+  }
+}
+
+function readText(p) {
+  if (!fs.existsSync(p)) return { error: '文件不存在: ' + p };
+  try {
+    return { data: fs.readFileSync(p, 'utf-8') };
+  } catch (err) {
+    return { error: '读取失败: ' + err.message };
+  }
+}
+
+// ============================================================
+// glossary / formulas 加载
+// ============================================================
+function loadGlossary() {
+  const r = readText(path.join(__dirname, 'glossary.md'));
+  if (r.error) return { error: 'glossary.md 读取失败: ' + r.error };
+  return parseGlossaryChecked(r.data);
+}
+
+function loadFormulas() {
+  const r = readJson(path.join(__dirname, 'formulas-skeleton.json'));
+  if (r.error) return { error: 'formulas-skeleton.json 读取失败: ' + r.error };
+  return { formulas: r.data.formulas || {} };
+}
+
+// ============================================================
+// 模板校验
+// ============================================================
+function validateNode(data, spec, p, enums, errors) {
+  if (typeof spec === 'string') spec = { type: spec };
+  if (spec.required && (data === undefined || data === null || data === '')) {
+    errors.push({ code: 'REQUIRED', path: p, message: '必填字段不得为空', hint: null });
+    return;
+  }
+  if (data === undefined || data === null) return;
+
+  const actualType = Array.isArray(data) ? 'array' : typeof data;
+  if (spec.type === 'array' && !Array.isArray(data)) {
+    errors.push({ code: 'TYPE', path: p, message: '应为 array，实际为 ' + actualType, hint: null });
+  } else if (spec.type === 'object' && (typeof data !== 'object' || Array.isArray(data))) {
+    errors.push({ code: 'TYPE', path: p, message: '应为 object，实际为 ' + actualType, hint: null });
+  } else if (spec.type === 'string' && typeof data !== 'string') {
+    errors.push({ code: 'TYPE', path: p, message: '应为 string，实际为 ' + actualType, hint: null });
+  } else if (spec.type === 'number' && typeof data !== 'number') {
+    errors.push({ code: 'TYPE', path: p, message: '应为 number，实际为 ' + actualType, hint: null });
+  } else if (spec.type === 'boolean' && typeof data !== 'boolean') {
+    errors.push({ code: 'TYPE', path: p, message: '应为 boolean，实际为 ' + actualType, hint: null });
+  }
+
+  if (spec.pattern && typeof data === 'string') {
+    try {
+      if (!new RegExp(spec.pattern).test(data)) {
+        errors.push({ code: 'PATTERN', path: p, message: '不匹配正则 ' + spec.pattern, hint: null });
+      }
+    } catch (e) {}
+  }
+
+  if (spec.enumRef) {
+    const allowed = enums[spec.enumRef];
+    if (!allowed) {
+      errors.push({ code: 'ENUM_MISSING', path: p, message: '枚举引用 ' + spec.enumRef + ' 未在 glossary 中定义', hint: null });
+    } else if (!allowed.includes(data)) {
+      errors.push({ code: 'ENUM', path: p, message: '值 "' + data + '" 不在允许的枚举范围内', hint: allowed.join(' / ') });
+    }
+  }
+
+  if (spec.properties && typeof data === 'object' && !Array.isArray(data)) {
+    const allowed = new Set(Object.keys(spec.properties));
+    for (const key of Object.keys(data)) {
+      if (!allowed.has(key)) {
+        errors.push({
+          code: 'EXTRA_FIELD',
+          path: p ? (p + '.' + key) : key,
+          message: '字段 "' + key + '" 不在模板中',
+          hint: '数据文件不得出现模板 properties 之外的字段'
+        });
+      }
+    }
+    for (const [k, child] of Object.entries(spec.properties)) {
+      validateNode(data[k], child, p ? (p + '.' + k) : k, enums, errors);
+    }
+  }
+
+  if (spec.type === 'array' && spec.items && Array.isArray(data)) {
+    data.forEach((item, i) => validateNode(item, spec.items, p + '[' + i + ']', enums, errors));
+  }
+}
+
+// ============================================================
+// 章节号越界检查
+// ============================================================
+function checkChapterForbidden(data, scalarSet, containerSet, errors) {
+  const walk = (node, p) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      node.forEach((v, i) => walk(v, p + '[' + i + ']'));
+      return;
+    }
+    for (const [k, v] of Object.entries(node)) {
+      const curPath = p ? (p + '.' + k) : k;
+      if (containerSet.has(k)) {
+        errors.push({
+          code: 'SKELETON_CHAPTER_FORBIDDEN',
+          path: curPath,
+          message: '骨架阶段不允许出现章节容器 "' + k + '"',
+          hint: '章节号属于节奏阶段'
+        });
+        continue;
+      }
+      if (scalarSet.has(k) && typeof v === 'number') {
+        errors.push({
+          code: 'SKELETON_CHAPTER_FORBIDDEN',
+          path: curPath,
+          message: '骨架阶段不允许出现章节号字段 "' + k + '"（值 ' + v + '）',
+          hint: '章节号属于节奏阶段'
+        });
+      }
+      walk(v, curPath);
+    }
+  };
+  walk(data, '');
+}
+
+// ============================================================
+// 字符集 / 占位符
+// ============================================================
+const KOREAN_RE = /[\uAC00-\uD7A3\u1100-\u11FF\u3130-\u318F]/;
+const KANA_RE = /[\u3040-\u309F\u30A0-\u30FF]/;
+const PLACEHOLDER_RE = /\[[XYZW]\]|待确认|待定|N\/A/;
+
+function charsetAndForbiddenCheck(data, errors) {
+  const walk = (node, p) => {
+    if (typeof node === 'string') {
+      if (KOREAN_RE.test(node)) {
+        errors.push({ code: 'CHARSET_KO', path: p, message: '含韩文: "' + node.slice(0, 30) + '"', hint: null });
+      }
+      if (KANA_RE.test(node)) {
+        errors.push({ code: 'CHARSET_JP', path: p, message: '含日文假名: "' + node.slice(0, 30) + '"', hint: null });
+      }
+      if (PLACEHOLDER_RE.test(node)) {
+        errors.push({ code: 'PLACEHOLDER', path: p, message: '含占位符: "' + node.slice(0, 30) + '"', hint: null });
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach((v, i) => walk(v, p + '[' + i + ']'));
+      return;
+    }
+    if (node && typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) walk(v, p ? (p + '.' + k) : k);
+    }
+  };
+  walk(data, '');
+}
+
+// ============================================================
+// ID / 名称唯一性
+// ============================================================
+function idUniquenessCheck(data, fileType, errors) {
+  const ID_ARRAYS = {
+    '实体': ['characters', 'other_entities', 'conflicts', 'factions', 'locations', 'items', 'endings', 'foreshadows', 'climaxes', 'pleasures', 'world_rules', 'main_lines', 'branches'],
+    '层级': ['volumes']
+  };
+  // 记出现次数：光说"重复"模型不知道该删几条
+  const seen = new Map();
+  for (const key of ID_ARRAYS[fileType] || []) {
+    for (const item of data[key] || []) {
+      if (!item.id) continue;
+      const n = (seen.get(item.id) || 0) + 1;
+      seen.set(item.id, n);
+      if (n > 1) {
+        errors.push({
+          code: 'ID_DUP',
+          path: key + '.' + item.id,
+          message: 'ID ' + item.id + ' 重复（出现 ' + n + ' 次）',
+          hint: 'ID 必须唯一：' + item.id + ' 在本文件里出现了 ' + n + ' 次，'
+            + '请只保留一条（其余的删掉或改成别的 id）'
+        });
+      }
+    }
+  }
+}
+
+const NAME_ARRAYS_BY_FILE = {
+  '实体': ['characters', 'other_entities', 'conflicts', 'factions', 'locations', 'items', 'endings', 'foreshadows', 'climaxes', 'pleasures', 'world_rules', 'main_lines', 'branches'],
+  '层级': ['volumes']
+};
+
+/**
+ * 归一化实体名，用于发现“同一实体换了写法”：
+ *   - 去空白 / 标点 / 括号注释；
+ *   - 去常见机构后缀（集团/公司/大学/协会…），
+ *     这样「企鹅集团」和「企鹅」会落到同一个 key；
+ *   - 不做拼音/翻译，跨语言别名仍交给 LLM 审计。
+ */
+const GENERIC_NAME_SUFFIXES = [
+  '股份有限公司', '有限公司', '集团', '公司', '大学', '学院', '学校',
+  '医院', '银行', '协会', '商会', '联盟', '家族', '世家', '王朝',
+  '帝国', '组织', '机构', '政府', '部门'
+];
+
+function normalizeEntityName(name) {
+  let s = String(name || '').trim().toLowerCase();
+  s = s.replace(/[（(][^）)]*[）)]/g, '');
+  s = s.replace(/[\s·・,，。.、:：;；!！?？'"“”‘’《》<>【】\[\]（）()\-—_/\\|]/g, '');
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const suffix of GENERIC_NAME_SUFFIXES) {
+      if (s.length > suffix.length + 1 && s.endsWith(suffix)) {
+        s = s.slice(0, -suffix.length);
+        changed = true;
+      }
+    }
+  }
+  return s;
+}
+
+function nameUniquenessCheck(data, fileType, errors) {
+  for (const key of NAME_ARRAYS_BY_FILE[fileType] || []) {
+    const seen = new Map();
+    for (const item of data[key] || []) {
+      const n = item.name;
+      if (!n) continue;
+      if (seen.has(n)) {
+        errors.push({ code: 'NAME_DUP', path: key + '.' + n, message: '名称 "' + n + '" 重复', hint: null });
+      } else {
+        seen.set(n, item.id);
+      }
+    }
+  }
+}
+
+/**
+ * 软重复检查：名称归一化后相同，但字面不同。
+ * 只报 warning，不自动合并 —— 可能是同一实体，也可能是“阳城”与“阳城大学”
+ * 这种上下位关系，必须让作者/模型确认。
+ */
+function nameAliasCheck(data, fileType, warnings) {
+  for (const key of NAME_ARRAYS_BY_FILE[fileType] || []) {
+    const byNormalized = new Map();
+    for (const item of data[key] || []) {
+      if (!item.name) continue;
+      const normalized = normalizeEntityName(item.name);
+      if (!normalized) continue;
+      if (!byNormalized.has(normalized)) byNormalized.set(normalized, []);
+      byNormalized.get(normalized).push({ id: item.id, name: String(item.name) });
+    }
+    for (const [normalized, entries] of byNormalized) {
+      const distinctNames = [...new Set(entries.map((e) => e.name))];
+      if (distinctNames.length <= 1) continue;
+      warnings.push({
+        code: 'NAME_ALIAS_SUSPECT',
+        path: key + '.' + distinctNames.join(' / '),
+        message: '名称 ' + distinctNames.map((n) => '"' + n + '"').join('、') +
+          ' 归一化后相同（' + normalized + '），可能是同一实体的全称/简称/别名',
+        hint: '确认是同一实体时只保留一个正式名，把另一个的设定合并过去；不要把称呼、简称、集团/公司后缀单独建成新实体'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 自环关系检查
+// ============================================================
+function selfRelationCheck(data, errors) {
+  for (let i = 0; i < (data.character_relations || []).length; i++) {
+    const r = data.character_relations[i];
+    if (r.from && r.to && r.from === r.to) {
+      errors.push({
+        code: 'NO_SELF_RELATION',
+        path: 'character_relations[' + i + ']',
+        message: '角色关系 from 和 to 不能相同（' + r.from + '）',
+        hint: '自环关系无意义。如果是要表达角色的自我矛盾，用角色档案的 description / core_flaw 表达'
+      });
+    }
+  }
+  for (let i = 0; i < (data.other_relations || []).length; i++) {
+    const r = data.other_relations[i];
+    if (r.from && r.to && r.from === r.to) {
+      errors.push({
+        code: 'NO_SELF_RELATION',
+        path: 'other_relations[' + i + ']',
+        message: '其他实体关系 from 和 to 不能相同（' + r.from + '）',
+        hint: '自环关系无意义；改为指向人物或另一个实体'
+      });
+    }
+  }
+  for (let i = 0; i < (data.faction_relations || []).length; i++) {
+    const r = data.faction_relations[i];
+    if (r.from && r.to && r.from === r.to) {
+      errors.push({
+        code: 'NO_SELF_RELATION',
+        path: 'faction_relations[' + i + ']',
+        message: '势力关系 from 和 to 不能相同（' + r.from + '）',
+        hint: '势力不能与自己对立/合作'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 扩展关系标签检查
+// ============================================================
+// `其他` 是词表外的扩展出口。只写"其他"等于没写关系；
+// 必须用 relation_label 说清是附身、寄生、契约还是别的。
+function relationLabelCheck(data, errors) {
+  for (const [i, r] of (data.character_relations || []).entries()) {
+    if (!r || r.relation_kind !== '其他') continue;
+    const label = typeof r.relation_label === 'string' ? r.relation_label.trim() : '';
+    if (!label) {
+      errors.push({
+        code: 'REL_LABEL_REQUIRED',
+        path: 'character_relations[' + i + '].relation_label',
+        message: 'relation_kind="其他" 时必须填 relation_label，写清具体关系（如 附身/寄生/契约/共生）',
+        hint: 'relation_label 是词表外关系的唯一语义来源；只写"其他"下游无法判断该怎么写'
+      });
+    }
+  }
+  for (const [i, r] of (data.other_relations || []).entries()) {
+    if (!r || typeof r.relation_label !== 'string' || !r.relation_label.trim()) {
+      errors.push({
+        code: 'REL_LABEL_REQUIRED',
+        path: 'other_relations[' + i + '].relation_label',
+        message: 'other_relations 必须填 relation_label，写清具体关系（如 附身/寄宿/共生/镇压）',
+        hint: '非人物实体的关系没有词表可依，relation_label 是唯一语义来源'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 关系数组组合重复检查（7 类）
+// ============================================================
+function relationDupCheck(data, errors) {
+  const crSet = new Map();
+  for (const r of (data.character_relations || [])) {
+    const k = r.from + '→' + r.to;
+    if (crSet.has(k)) {
+      const prev = crSet.get(k);
+      if (prev !== r.relation_kind) {
+        // 同一有序对写了两种互斥的关系类型：这不是"重复"，是关系语义冲突，
+        // 用独立错误码让调用方能区分"删一条"和"改一条"。
+        errors.push({
+          code: 'REL_KIND_CONFLICT',
+          path: 'character_relations.' + k,
+          message: '角色关系 ' + k + ' 同时声明了「' + prev + '」与「' + r.relation_kind + '」两种关系类型',
+          hint: '同一有序对只能保留一种关系类型；另一种关系请在血肉阶段该角色的 relationships[].description 中展开'
+        });
+      } else {
+        errors.push({
+          code: 'ID_DUP',
+          path: 'character_relations.' + k,
+          message: '角色关系 ' + k + ' 重复',
+          // 不写清楚模型只能猜：tt5 实测这条反复出现 5 次都没改对。
+          hint: '同一对角色只能有一条关系记录（' + k + ' 与反向的 '
+            + r.from + '→' + r.to + ' 算**同一对**，算重复）：'
+            + '请删掉其中一条，不要两条都留'
+        });
+      }
+    }
+    crSet.set(k, r.relation_kind);
+  }
+
+  const orSet = new Set();
+  for (const r of (data.other_relations || [])) {
+    const k = r.from + '→' + r.to;
+    if (orSet.has(k)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'other_relations.' + k,
+        message: '其他实体关系 ' + k + ' 重复',
+        hint: '同一对存在只能保留一条关系；不同关系请用 relation_label 写清，不要重复建行'
+      });
+    }
+    orSet.add(k);
+  }
+
+  const frSet = new Set();
+  for (const r of (data.faction_relations || [])) {
+    const k = r.from + '→' + r.to;
+    if (frSet.has(k)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'faction_relations.' + k,
+        message: '势力关系 ' + k + ' 重复',
+        hint: '同一对势力只能有一条关系记录（' + k + ' 与反向的 '
+          + r.from + '→' + r.to + ' 算**同一对**，算重复）：请删掉其中一条'
+      });
+    }
+    frSet.add(k);
+  }
+
+  const fmSet = new Set();
+  for (const r of (data.faction_membership || [])) {
+    const k = r.character + '@' + r.faction;
+    if (fmSet.has(k)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'faction_membership.' + k,
+        message: '势力成员关系 ' + k + ' 重复',
+        hint: '同一个角色在同一个势力里只能有一条成员关系（' + k + ' 重复）：请删掉其中一条'
+      });
+    }
+    fmSet.add(k);
+  }
+
+  const cpSet = new Set();
+  for (const r of (data.conflict_participants || [])) {
+    if (!r.conflict) continue;
+    if (cpSet.has(r.conflict)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'conflict_participants.' + r.conflict,
+        message: '冲突 ' + r.conflict + ' 的参与方重复声明',
+        hint: '一个冲突只能有一条 conflict_participants 记录'
+      });
+    }
+    cpSet.add(r.conflict);
+  }
+
+  const bpSet = new Set();
+  for (const r of (data.branch_protagonist || [])) {
+    if (!r.branch) continue;
+    if (bpSet.has(r.branch)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'branch_protagonist.' + r.branch,
+        message: '支线 ' + r.branch + ' 的主角重复声明',
+        hint: '每条支线只能有一个主角（' + r.branch + ' 重复声明）：请删掉其中一条'
+      });
+    }
+    bpSet.add(r.branch);
+  }
+
+  const ioSet = new Set();
+  for (const r of (data.item_owner || [])) {
+    if (!r.item) continue;
+    if (ioSet.has(r.item)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'item_owner.' + r.item,
+        message: '道具 ' + r.item + ' 的归属重复声明',
+        hint: '每个道具只能有一个归属（' + r.item + ' 重复声明）：请删掉其中一条'
+      });
+    }
+    ioSet.add(r.item);
+  }
+
+  const lcSet = new Set();
+  for (const r of (data.location_conflict || [])) {
+    if (!r.location) continue;
+    if (lcSet.has(r.location)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'location_conflict.' + r.location,
+        message: '地点 ' + r.location + ' 的冲突关联重复声明',
+        hint: '每个地点只能关联一条冲突（' + r.location + ' 重复声明）：请删掉其中一条'
+      });
+    }
+    lcSet.add(r.location);
+  }
+}
+
+// ============================================================
+// 公式求值
+// ============================================================
+// 求值器搬到 scripts/formula-engine.js：导入阶段从旧稿反推 quota 时
+// 要用**同一套**公式与区间，否则导入出来的 quota 会掉出本校验器的
+// 合法区间 —— 表现为"导入完立刻校验失败"，而错在 quota 上，看不出根因。
+
+
+// ============================================================
+// derivations 检查
+// ============================================================
+function derivationCheck(data, formulas, errors, warnings) {
+  const der = data.derivations || {};
+  // v2 的 custom.* 公式只用于 10-scale 的 scale.json；旧骨架阶段不消费它们。
+  const formulaKeys = new Set(Object.keys(formulas).filter((k) => !k.startsWith('custom.')));
+  const derKeys = new Set(Object.keys(der));
+
+  for (const k of formulaKeys) {
+    if (!derKeys.has(k)) {
+      errors.push({
+        code: 'DERIVATION_MISSING',
+        path: 'derivations.' + k,
+        message: '缺少推导记录',
+        hint: '公式: ' + formulas[k].formula
+      });
+    }
+  }
+
+  for (const k of derKeys) {
+    if (!formulaKeys.has(k)) {
+      errors.push({
+        code: 'DERIVATION_EXTRA',
+        path: 'derivations.' + k,
+        message: '多余的推导记录（formulas-skeleton.json 中不存在 ' + k + '）',
+        hint: '删除该 key 或检查 formulas-skeleton.json'
+      });
+    }
+  }
+
+  const ctx = buildFormulaContext(data);
+  for (const [k, spec] of Object.entries(formulas)) {
+    if (k.startsWith('custom.')) continue;
+    const d = der[k];
+    if (!d) continue;
+    let realLow, realHigh;
+    try {
+      realLow = evalExpr(spec.expr_low, ctx);
+      realHigh = evalExpr(spec.expr_high, ctx);
+    } catch (e) {
+      errors.push({
+        code: 'DERIVATION_EVAL',
+        path: 'derivations.' + k,
+        message: '公式求值失败: ' + e.message,
+        hint: null
+      });
+      continue;
+    }
+    // 区间为空（下界 > 上界）时**先说清楚是"没有合法解"**：
+    // 光说 "range 应为 [16, 15]" 模型看不懂，只知道"填什么都不对"，
+    // 于是反复乱改 —— 这一条就足以把重投次数耗尽。
+    if (realLow > realHigh) {
+      errors.push({
+        code: 'DERIVATION_RANGE_MISMATCH',
+        path: 'derivations.' + k,
+        message: '公式区间为空（[' + realLow + ', ' + realHigh + ']，下界 > 上界）：当前 quota 取值下这条公式没有合法解',
+        hint: '公式: ' + spec.formula + ' —— 说明当前的卷数/支线数与这条公式互相矛盾，请先调 quota 里相关的字段再重算'
+      });
+      continue;
+    }
+    if (d.range_low !== realLow || d.range_high !== realHigh) {
+      errors.push({
+        code: 'DERIVATION_RANGE_MISMATCH',
+        path: 'derivations.' + k,
+        message: 'range 应为 [' + realLow + ', ' + realHigh + ']，实际 [' + d.range_low + ', ' + d.range_high + ']',
+        hint: '公式: ' + spec.formula
+      });
+    }
+    if (typeof d.formula !== 'string' || d.formula !== spec.formula) {
+      warnings.push({
+        code: 'DERIVATION_FORMULA_TEXT',
+        path: 'derivations.' + k + '.formula',
+        message: 'formula 文本与标准不一致',
+        hint: '标准: ' + spec.formula
+      });
+    }
+    const actualPath = spec.applies_to_field;
+    const actual = getNested(data, actualPath);
+    if (typeof actual === 'number') {
+      if (actual < realLow || actual > realHigh) {
+        warnings.push({
+          code: 'QUANTITY_MISMATCH',
+          path: actualPath,
+          message: actualPath + '=' + actual + ' 不在区间 [' + realLow + ', ' + realHigh + '] 内',
+          hint: spec.note || ''
+        });
+      }
+    }
+  }
+}
+
+function getNested(obj, p) {
+  if (!p) return obj;
+  return p.split('.').reduce((o, k) => {
+    if (o === undefined || o === null) return undefined;
+    return o[k];
+  }, obj);
+}
+
+// ============================================================
+// 框架.json 专项检查
+// ============================================================
+function frameworkSpecificCheck(data, errors, warnings) {
+  const quota = data.quota || {};
+  const T = data.capacity?.target_chapters;
+  const V = quota.volume_count;
+
+  if (typeof T === 'number' && T > 0 &&
+      typeof data.capacity?.target_words === 'number' &&
+      typeof data.capacity?.avg_words_per_chapter === 'number') {
+    const expected = Math.round(data.capacity.target_words / T);
+    if (Math.abs(data.capacity.avg_words_per_chapter - expected) > 1) {
+      errors.push({
+        code: 'CAPACITY_MISMATCH',
+        path: 'capacity.avg_words_per_chapter',
+        message: 'avg_words_per_chapter=' + data.capacity.avg_words_per_chapter + '，期望 ' + expected,
+        hint: 'avg_words_per_chapter 应等于 round(target_words / target_chapters)'
+      });
+    }
+  }
+
+  const vr = data.volume_ratio || [];
+  if (typeof V === 'number' && vr.length !== V) {
+    errors.push({
+      code: 'VOLUME_RATIO_LENGTH',
+      path: 'volume_ratio',
+      message: 'volume_ratio 长度 ' + vr.length + ' ≠ quota.volume_count ' + V,
+      hint: null
+    });
+  }
+  const sum = vr.reduce((s, x) => s + (typeof x.chapter_ratio === 'number' ? x.chapter_ratio : 0), 0);
+  if (vr.length > 0 && Math.abs(sum - 1.0) > 0.01) {
+    errors.push({
+      code: 'VOLUME_RATIO_SUM',
+      path: 'volume_ratio',
+      message: 'volume_ratio 之和 ' + sum + ' ≠ 1.0（容差 0.01）',
+      hint: null
+    });
+  }
+
+  const vrIds = new Set();
+  for (const x of vr) {
+    if (!x.volume_id) continue;
+    if (vrIds.has(x.volume_id)) {
+      errors.push({
+        code: 'ID_DUP',
+        path: 'volume_ratio.' + x.volume_id,
+        message: 'volume_id ' + x.volume_id + ' 重复',
+        hint: 'volume_id 必须唯一（' + x.volume_id + ' 重复）：请只保留一条'
+      });
+    }
+    vrIds.add(x.volume_id);
+  }
+
+  // 每项比例必须在 [0,1]。
+  //
+  // 只查"总和 = 1"是**不够**的：负数项也能凑出总和 1
+  // （导入侧旧实现就是"最后一项吃差额"，把差额吃成负数）。
+  // 负比例会让节奏阶段算出"期望约 -2 章"，一路传下去很难查。
+  for (const x of vr) {
+    const r = x && x.chapter_ratio;
+    if (typeof r !== 'number' || !isFinite(r)) continue;
+    if (r < 0 || r > 1) {
+      errors.push({
+        code: 'VOLUME_RATIO_RANGE',
+        path: 'volume_ratio.' + (x.volume_id || '(无 id)'),
+        message: 'chapter_ratio=' + r + ' 不在 [0, 1] 内',
+        hint: '每卷占的章数比例必须在 0~1 之间：负数会让节奏阶段算出负的期望章数，' +
+          '大于 1 说明这一卷比全书还长。请按各卷实际章数重新分配比例（各项加起来要等于 1）'
+      });
+    }
+  }
+
+  if (data.input_snapshot) {
+    const hc = data.input_snapshot.hard_constraints;
+    const at = data.input_snapshot.anti_tropes;
+    if (!Array.isArray(hc) || hc.length === 0) {
+      warnings.push({
+        code: 'EMPTY_HARD_CONSTRAINTS',
+        path: 'input_snapshot.hard_constraints',
+        message: '硬门禁列表为空。如果不适用，建议至少写一条（如"无"），避免下游无法确认硬约束',
+        hint: null
+      });
+    }
+    if (!Array.isArray(at) || at.length === 0) {
+      warnings.push({
+        code: 'EMPTY_HARD_CONSTRAINTS',
+        path: 'input_snapshot.anti_tropes',
+        message: '反套路列表为空。如果不适用，建议至少写一条（如"无"）',
+        hint: null
+      });
+    }
+  }
+}
+
+// ============================================================
+// 关系.json 引用完整性
+// ============================================================
+function relationRefCheck(data, entityData, errors) {
+  if (!entityData) return;
+  const ids = {
+    characters: new Set((entityData.characters || []).map(c => c.id)),
+    conflicts: new Set((entityData.conflicts || []).map(c => c.id)),
+    factions: new Set((entityData.factions || []).map(f => f.id)),
+    locations: new Set((entityData.locations || []).map(l => l.id)),
+    items: new Set((entityData.items || []).map(i => i.id)),
+    endings: new Set((entityData.endings || []).map(e => e.id)),
+    branches: new Set((entityData.branches || []).map(b => b.id)),
+    main_lines: new Set((entityData.main_lines || []).map(m => m.id)),
+    other_entities: new Set((entityData.other_entities || []).map(o => o.id))
+  };
+
+  const ref = (val, set, label, pathStr) => {
+    if (!val) return;
+    if (!set.has(val)) {
+      errors.push({
+        code: 'SKELETON_REF_MISSING',
+        path: pathStr,
+        message: '引用 ' + label + ' "' + val + '" 不存在于 实体.json',
+        hint: null
+      });
+    }
+  };
+
+  for (const [i, r] of (data.character_relations || []).entries()) {
+    ref(r.from, ids.characters, '角色', 'character_relations[' + i + '].from');
+    ref(r.to, ids.characters, '角色', 'character_relations[' + i + '].to');
+  }
+  for (const [i, r] of (data.other_relations || []).entries()) {
+    ref(r.from, ids.other_entities, '其他实体', 'other_relations[' + i + '].from');
+    if (String(r.to || '').startsWith('C')) ref(r.to, ids.characters, '角色', 'other_relations[' + i + '].to');
+    else ref(r.to, ids.other_entities, '其他实体', 'other_relations[' + i + '].to');
+  }
+  for (const [i, r] of (data.faction_membership || []).entries()) {
+    ref(r.character, ids.characters, '角色', 'faction_membership[' + i + '].character');
+    ref(r.faction, ids.factions, '势力', 'faction_membership[' + i + '].faction');
+  }
+  for (const [i, r] of (data.faction_relations || []).entries()) {
+    ref(r.from, ids.factions, '势力', 'faction_relations[' + i + '].from');
+    ref(r.to, ids.factions, '势力', 'faction_relations[' + i + '].to');
+  }
+  for (const [i, r] of (data.conflict_participants || []).entries()) {
+    ref(r.conflict, ids.conflicts, '冲突', 'conflict_participants[' + i + '].conflict');
+    for (const c of (r.protagonist_side || [])) ref(c, ids.characters, '角色', 'conflict_participants[' + i + '].protagonist_side');
+    ref(r.main_antagonist, ids.characters, '角色', 'conflict_participants[' + i + '].main_antagonist');
+    for (const c of (r.secondary_antagonist || [])) ref(c, ids.characters, '角色', 'conflict_participants[' + i + '].secondary_antagonist');
+    for (const c of (r.third_party || [])) ref(c, ids.characters, '角色', 'conflict_participants[' + i + '].third_party');
+  }
+  for (const [i, r] of (data.branch_protagonist || []).entries()) {
+    ref(r.branch, ids.branches, '支线', 'branch_protagonist[' + i + '].branch');
+    ref(r.character, ids.characters, '角色', 'branch_protagonist[' + i + '].character');
+  }
+  for (const [i, r] of (data.item_owner || []).entries()) {
+    ref(r.item, ids.items, '道具', 'item_owner[' + i + '].item');
+    if (r.owner_kind === 'character') ref(r.owner_id, ids.characters, '角色', 'item_owner[' + i + '].owner_id');
+    else if (r.owner_kind === 'faction') ref(r.owner_id, ids.factions, '势力', 'item_owner[' + i + '].owner_id');
+  }
+  for (const [i, r] of (data.location_conflict || []).entries()) {
+    ref(r.location, ids.locations, '地点', 'location_conflict[' + i + '].location');
+    for (const c of (r.conflicts || [])) ref(c, ids.conflicts, '冲突', 'location_conflict[' + i + '].conflicts');
+  }
+  for (const [i, r] of (data.ending_character || []).entries()) {
+    ref(r.ending, ids.endings, '结局', 'ending_character[' + i + '].ending');
+    ref(r.character, ids.characters, '角色', 'ending_character[' + i + '].character');
+  }
+  for (const [i, r] of (data.main_line_branch_relation || []).entries()) {
+    ref(r.main_line, ids.main_lines, '主线', 'main_line_branch_relation[' + i + '].main_line');
+    ref(r.branch, ids.branches, '支线', 'main_line_branch_relation[' + i + '].branch');
+  }
+}
+
+// ============================================================
+// 支线挂主线的覆盖度
+// ============================================================
+
+/**
+ * 支线必须挂到主线上（覆盖度检查，不是引用完整性）。
+ *
+ * 为什么必须查（tt5 实测的真实缺陷）：
+ *   `main_line_branch_relation` 之前只查"main_line / branch 这两个 id 存不存在"，
+ *   不查"每条支线有没有被挂上去"。结果模型只写 1 行（M001→B003），
+ *   10 条支线里 9 条一条关系都没有 —— 校验器照样 PASSED，
+ *   产物带着 9 条孤儿支线一路流到血肉/节奏阶段，下游才发现结构是断的。
+ *
+ * 口径：
+ *   · 每条支线至少挂到一条主线上（BRANCH_MAINLINE_UNLINKED）
+ *   · 每条主线至少挂到一条支线上（MAINLINE_BRANCH_UNLINKED）
+ *     —— 支线数为 0 时不查这一条（没有支线的主线不算错）
+ */
+function checkBranchMainLineCoverage(entityData, relationData, errors) {
+  if (!entityData || !relationData) return;
+  const branches = Array.isArray(entityData.branches) ? entityData.branches : [];
+  const mainLines = Array.isArray(entityData.main_lines) ? entityData.main_lines : [];
+  if (!branches.length && !mainLines.length) return;
+  const rows = Array.isArray(relationData.main_line_branch_relation)
+    ? relationData.main_line_branch_relation
+    : [];
+
+  const linkedBranches = new Set();
+  const usedMainLines = new Set();
+  for (const r of rows) {
+    if (!r || typeof r !== 'object') continue;
+    if (typeof r.branch === 'string' && r.branch) linkedBranches.add(r.branch);
+    if (typeof r.main_line === 'string' && r.main_line) usedMainLines.add(r.main_line);
+  }
+
+  const missingBranches = branches
+    .filter((b) => b && b.id && !linkedBranches.has(b.id))
+    .map((b) => b.id);
+  if (missingBranches.length) {
+    errors.push({
+      code: 'BRANCH_MAINLINE_UNLINKED',
+      path: 'main_line_branch_relation',
+      message: '有 ' + missingBranches.length + ' 条支线没有挂到任何主线：' + missingBranches.join('、'),
+      hint: 'main_line_branch_relation 一行代表"一条支线挂到主线上"，每条支线都要有一行'
+    });
+  }
+
+  // 反向：主线一条支线都没挂。没有支线时不查（支线为 0 是合法配置）
+  if (branches.length) {
+    const deadMainLines = mainLines
+      .filter((m) => m && m.id && !usedMainLines.has(m.id))
+      .map((m) => m.id);
+    if (deadMainLines.length) {
+      errors.push({
+        code: 'MAINLINE_BRANCH_UNLINKED',
+        path: 'main_line_branch_relation',
+        message: '有 ' + deadMainLines.length + ' 条主线没有挂任何支线：' + deadMainLines.join('、'),
+        hint: '每条主线都要有支线挂上来，否则这条主线在结构上是空的'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 层级.json 引用完整性
+// ============================================================
+function hierarchyRefCheck(data, entityData, frameworkData, errors) {
+  const volumeCount = frameworkData?.quota?.volume_count;
+  const validVolumes = new Set((frameworkData?.volume_ratio || []).map(x => x.volume_id));
+
+  if (typeof volumeCount === 'number' && (data.volumes || []).length !== volumeCount) {
+    errors.push({
+      code: 'VOLUME_COUNT_MISMATCH',
+      path: 'volumes',
+      message: 'volumes 长度 ' + (data.volumes || []).length + ' ≠ quota.volume_count ' + volumeCount,
+      hint: null
+    });
+  }
+
+  for (const [i, v] of (data.volumes || []).entries()) {
+    if (v.id && validVolumes.size > 0 && !validVolumes.has(v.id)) {
+      errors.push({
+        code: 'SKELETON_REF_MISSING',
+        path: 'volumes[' + i + '].id',
+        message: '卷 ' + v.id + ' 不在框架 volume_ratio 中',
+        hint: null
+      });
+    }
+  }
+
+  const volIds = new Set((data.volumes || []).map(v => v.id));
+  for (const [i, a] of (data.acts || []).entries()) {
+    if (a.volume && !volIds.has(a.volume)) {
+      errors.push({
+        code: 'SKELETON_REF_MISSING',
+        path: 'acts[' + i + '].volume',
+        message: '幕引用的卷 ' + a.volume + ' 不存在于 volumes',
+        hint: null
+      });
+    }
+  }
+
+  const actSeen = new Map();
+  for (const [i, a] of (data.acts || []).entries()) {
+    if (!a.volume || typeof a.act_index !== 'number') continue;
+    const key = a.volume + '#' + a.act_index;
+    if (actSeen.has(key)) {
+      errors.push({
+        code: 'ACT_INDEX_DUP',
+        path: 'acts[' + i + '].act_index',
+        message: '卷 ' + a.volume + ' 的 act_index=' + a.act_index + ' 重复',
+        hint: null
+      });
+    }
+    actSeen.set(key, i);
+  }
+
+  if (typeof volumeCount === 'number') {
+    for (const [i, s] of (data.main_line_span || []).entries()) {
+      if ((s.volume_ratio || []).length !== volumeCount) {
+        errors.push({
+          code: 'SPAN_LENGTH_MISMATCH',
+          path: 'main_line_span[' + i + '].volume_ratio',
+          message: '长度 ' + (s.volume_ratio || []).length + ' ≠ volume_count ' + volumeCount,
+          hint: null
+        });
+      }
+      for (const [j, v] of (s.volume_ratio || []).entries()) {
+        if (typeof v !== 'number' || v < 0 || v > 1) {
+          errors.push({
+            code: 'SPAN_RATIO_RANGE',
+            path: 'main_line_span[' + i + '].volume_ratio[' + j + ']',
+            message: 'volume_ratio 元素 ' + v + ' 不在 [0, 1] 内',
+            hint: null
+          });
+        }
+      }
+    }
+    for (const [i, s] of (data.branch_span || []).entries()) {
+      if ((s.volume_ratio || []).length !== volumeCount) {
+        errors.push({
+          code: 'SPAN_LENGTH_MISMATCH',
+          path: 'branch_span[' + i + '].volume_ratio',
+          message: '长度 ' + (s.volume_ratio || []).length + ' ≠ volume_count ' + volumeCount,
+          hint: null
+        });
+      }
+      for (const [j, v] of (s.volume_ratio || []).entries()) {
+        if (typeof v !== 'number' || v < 0 || v > 1) {
+          errors.push({
+            code: 'SPAN_RATIO_RANGE',
+            path: 'branch_span[' + i + '].volume_ratio[' + j + ']',
+            message: 'volume_ratio 元素 ' + v + ' 不在 [0, 1] 内',
+            hint: null
+          });
+        }
+      }
+    }
+  }
+
+  if (entityData) {
+    const mlIds = new Set((entityData.main_lines || []).map(m => m.id));
+    const bIds = new Set((entityData.branches || []).map(b => b.id));
+    for (const [i, s] of (data.main_line_span || []).entries()) {
+      if (s.main_line && !mlIds.has(s.main_line)) {
+        errors.push({ code: 'SKELETON_REF_MISSING', path: 'main_line_span[' + i + '].main_line', message: '主线 ' + s.main_line + ' 不存在于 实体.json', hint: null });
+      }
+    }
+    for (const [i, s] of (data.branch_span || []).entries()) {
+      if (s.branch && !bIds.has(s.branch)) {
+        errors.push({ code: 'SKELETON_REF_MISSING', path: 'branch_span[' + i + '].branch', message: '支线 ' + s.branch + ' 不存在于 实体.json', hint: null });
+      }
+    }
+  }
+}
+
+// ============================================================
+// 全量：quota 一致性检查（P2-4：加 faction_relation_count）
+// ============================================================
+
+function checkQuotaConsistency(frameworkData, entityData, hierarchyData, relationData, errors, formulas) {
+  if (!frameworkData || !entityData) return;
+  const quota = frameworkData.quota || {};
+
+  for (const [quotaPath, spec] of Object.entries(QUOTA_MAP)) {
+    const expected = getNested(quota, quotaPath);
+    if (typeof expected !== 'number') continue;
+    const arr = entityData[spec.arr] || [];
+    const actual = arr.filter(spec.filter).length;
+    if (expected !== actual) {
+      errors.push({
+        code: 'QUOTA_MISMATCH',
+        path: 'quota.' + quotaPath,
+        message: 'quota.' + quotaPath + '=' + expected + '，实际 ' + actual + '（数组 ' + spec.arr + ' 过滤后）',
+        hint: '调整 quota 声明值或实体数量'
+      });
+    }
+  }
+
+  if (hierarchyData && typeof quota.volume_count === 'number') {
+    const actualVolumes = (hierarchyData.volumes || []).length;
+    if (actualVolumes !== quota.volume_count) {
+      errors.push({
+        code: 'QUOTA_MISMATCH',
+        path: 'quota.volume_count',
+        message: 'quota.volume_count=' + quota.volume_count + '，层级.json volumes.length=' + actualVolumes,
+        hint: null
+      });
+    }
+  }
+
+  // P2-4：faction_relation_count 特判（数据在关系.json，不在实体.json）
+  checkFactionRelationRowCount(frameworkData, relationData, errors, formulas);
+}
+
+/**
+ * `quota.faction_relation_count` 与 `faction_relations` 实际行数的对账。
+ *
+ * 注意：quota 含义是"无向关系对数"（按 faction_relation_count 公式 max(1,n-1) ~ n*(n-1)/2），
+ * 但 关系.json 实际存储是双向行（A→B + B→A 两条）。所以实际行数应为 2 * quota。
+ * 兼容历史数据：如果 quota*2 != actual 且 quota != actual，则按 quota*2 检查。
+ *
+ * 单独抽出来是为了让**局部校验模式**（--arrays）也能跑这一条 ——
+ * 中途校验时文件还没写完，但"势力关系行数对不对"当场就能判。
+ */
+function checkFactionRelationRowCount(frameworkData, relationData, errors, formulas) {
+  if (!frameworkData || !relationData) return;
+  const quota = frameworkData.quota || {};
+  const expectedFR = getNested(quota, 'faction_relation_count');
+  if (typeof expectedFR !== 'number') return;
+  const actualFR = (relationData.faction_relations || []).length;
+  const expectedRows = expectedFR * 2;
+  if (expectedFR === actualFR || expectedRows === actualFR) return;
+  errors.push({
+    code: 'QUOTA_MISMATCH',
+    path: 'quota.faction_relation_count',
+    message: 'quota.faction_relation_count=' + expectedFR + '（无向关系对数），关系.json 实际 ' + actualFR + ' 行（双向行应为 ' + expectedRows + '）',
+    hint: factionRelationHint(frameworkData, formulas, expectedFR, actualFR, expectedRows)
+  });
+}
+
+/**
+ * `quota.faction_relation_count` 对不上时的修复建议。
+ *
+ * 以前只有一个笼统的 hint："要么把 quota 改为 X，要么把 faction_relations 改为 N 行"。
+ * 其中"改 quota"那个分支是**陷阱**（tt5 实测）：quota 的合法区间由公式决定
+ * （`max(1, n-1) ~ n*(n-1)/2`），而实际行数反推出来的对数常常落在区间外
+ * （tt5：8 个势力 → 合法区间 [7, 28]，反推出 4 —— 改 quota 只会换来一个
+ * `QUANTITY_MISMATCH` warning，而且结构上是错的）。
+ *
+ * 所以这里只给**一定可行**的改法：把行数改成 quota 声明的行数；
+ * 只有当反推出的 quota 值确实落在公式区间内时，才把"改 quota"也列出来。
+ */
+function factionRelationHint(frameworkData, formulas, expectedFR, actualFR, expectedRows) {
+  // **只给"改关系行数"这一条路**，永远不建议改 quota。
+  //
+  // quota 是 框架.json 里的**定稿内容**（框架段早已 PASSED）：
+  //   · 改它等于篡改上游产物 —— 提示词明确要求模型只写分片文件；
+  //   · 下一轮合并分片会把它覆盖回去，改了也白改；
+  //   · quota 与 derivations、其它配额互相约束，改一个数会引出一串新错。
+  // tt5 实测（2026-10-25 09:xx）：这里原本在"反推值落在公式区间内"时
+  // 会给出"或者把 quota 改成 X"，模型照着把 框架.json 的
+  // faction_relation_count 从 14 改成 28，错误从 3 条涨到 126 条，
+  // 重投到上限，关系段 18 个分片没生成。
+  //
+  // 公式区间只用来**说明为什么不能靠改 quota 绕过去**，不给第二条路。
+  const parts = [];
+  parts.push('把 faction_relations 改为 ' + expectedRows + ' 行（A→B 与 B→A 各一）');
+  const range = factionRelationQuotaRange(frameworkData, formulas);
+  const altQuota = Math.ceil(actualFR / 2);
+  if (range) {
+    if (altQuota >= range.low && altQuota <= range.high) {
+      parts.push('不要改 quota（quota 是框架.json 里已定稿的值，改了会被分片覆盖回来，'
+        + '而且会引出新的错）：要改的是 faction_relations 的行数');
+    } else {
+      parts.push('不要改 quota（改成 ' + altQuota + ' 会掉出公式区间 ['
+        + range.low + ', ' + range.high + ']，只会换一个错）：要改的是 faction_relations 的行数');
+    }
+  }
+  return parts.join('；');
+}
+
+/**
+ * `quota.faction_relation_count` 的合法区间（按公式算）。
+ * 拿不到公式就返回 null（此时不给"改 quota"的建议）。
+ */
+function factionRelationQuotaRange(frameworkData, formulas) {
+  const spec = formulas && formulas['faction_elements.faction_relation_count'];
+  if (!spec) return null;
+  try {
+    const ctx = buildFormulaContext(frameworkData);
+    const low = evalExpr(spec.expr_low, ctx);
+    const high = evalExpr(spec.expr_high, ctx);
+    if (typeof low !== 'number' || typeof high !== 'number') return null;
+    if (!isFinite(low) || !isFinite(high)) return null;
+    return { low: low, high: high };
+  } catch (e) {
+    return null;
+  }
+}
+
+// ============================================================
+// 全书级结局数量检查
+// ============================================================
+function checkBookEndingLevel(entityData, errors) {
+  if (!entityData) return;
+  const endings = entityData.endings || [];
+  const bookLevel = endings.filter(e => e.level === '全书级');
+  if (bookLevel.length !== 1) {
+    errors.push({
+      code: 'BOOK_ENDING_COUNT',
+      path: 'endings',
+      message: '全书级结局（level="全书级"）数量为 ' + bookLevel.length + '，必须恰好 1 个',
+      hint: '每本书必须有且仅有 1 个 level="全书级" 的结局；单卷作品不应有卷级结局'
+    });
+  }
+}
+
+// ============================================================
+// 跨阶段骨架参数矛盾检查
+// 检查节奏阶段的 branch_chapter_total 区间是否可行
+// 公式：lower = max(BC*3, floor(T*0.3)), upper = min(BC*30, ceil(T*0.5))
+// 若 lower > upper，说明骨架阶段 T/BC 选值不合理
+// ============================================================
+function checkRhythmFeasibility(frameworkData, errors, formulas) {
+  if (!frameworkData || !frameworkData.capacity) return;
+  const T = frameworkData.capacity.target_chapters;
+  const quota = frameworkData.quota || {};
+  const BC = quota.branch_count;
+  if (typeof T !== 'number' || typeof BC !== 'number') return;
+  const lower = Math.max(BC * 3, Math.floor(T * 0.3));
+  const upper = Math.min(BC * 30, Math.ceil(T * 0.5));
+  if (lower > upper) {
+    // 两个区间必须相交，否则节奏阶段无解：
+    //   [BC*3, BC*30]          —— 每条支线 3~30 章
+    //   [floor(T*0.3), ceil(T*0.5)] —— 支线总章数占全书 30%~50%
+    //
+    // 不相交有**两种原因，调整方向相反**，必须分开说：
+    // tt5 实测（2026-10-24 22:00）原来只写"一般 T 小而 BC 大时出现"，
+    // 模型撞的却是相反的那种（T=800、BC=6），于是把 BC 6→4 越改越错，
+    // 3 轮重投用尽，阶段失败。
+    const floor03 = Math.floor(T * 0.3);
+    const ceil05 = Math.ceil(T * 0.5);
+    const bcCeiling = Math.floor(ceil05 / 3);   // 节奏侧允许的最大 BC
+
+    // 书太短：连 1 条支线都放不下（每条支线至少 3 章）。
+    // 这时"把 branch_count 调小"是**无效建议** —— BC 最小就是 1。
+    // 必须明说"这本书装不下支线"，否则模型会照着调成 0 然后继续失败。
+    if (bcCeiling < 1) {
+      errors.push({
+        code: 'RHYTHM_INFEASIBLE_PRECHECK',
+        path: 'quota.branch_count',
+        message: '骨架参数矛盾：全书只有 ' + T + ' 章，装不下一条支线' +
+          '（每条支线至少 3 章，而支线总章数只能落在 ' + floor03 + ' ~ ' + ceil05 + ' 之间）',
+        hint: '支线数最少也是 1 条，而 1 条支线至少占 3 章，超过全书上限 ' + ceil05 + ' 章。' +
+          '这不是调 branch_count 能解决的：请把 capacity.target_chapters 提到 5 章以上' +
+          '（按每卷 40~120 章排卷，一本这么短的书实际建议至少 20 章），' +
+          '或改用 /fancy-story-builder 从骨架重新起稿。'
+      });
+      return;
+    }
+
+    const tooMany = BC * 3 > ceil05;   // 支线太多：支线最少要占的章数超了上限
+    const need = Math.ceil(floor03 / 30);  // 支线太少时，BC 至少要这么多才铺得满
+    // 提示里的可行区间必须来自**公式本身**（formulas-skeleton.json 的
+    // structure.branch_count），不能自己算一套上限：
+    // 手算的 maxBc = floor(ceil(T*0.5)/3) 只管节奏侧，不管公式侧
+    // （公式还有 min(V*3, 15) 这层约束）→ 提示说"调大到 3~50"，
+    // 模型照着填 50 会撞 QUANTITY_MISMATCH，白烧一轮重投。
+    const range = formulas
+      ? formulaRange(formulas, 'quota.branch_count', buildFormulaContext(frameworkData))
+      : null;
+    const fLow = range ? range.low : need;
+    const fHigh = range ? range.high : bcCeiling;
+    errors.push({
+      code: 'RHYTHM_INFEASIBLE_PRECHECK',
+      path: 'quota.branch_count',
+      message: '骨架参数矛盾：节奏阶段支线章数区间不可行（[' + lower + ', ' + upper + ']，下界 > 上界）',
+      hint: tooMany
+        ? '支线数太多：每条支线至少 3 章，' + BC + ' 条支线至少要占 ' + (BC * 3) +
+          ' 章，超过全书上限 ' + ceil05 + ' 章。请把 branch_count 调小到 ' +
+          Math.min(bcCeiling, fHigh) + ' 以内（公式允许的上限是 ' + fHigh + '）。'
+        : '支线数太少：支线总章数至少要 floor(T×0.3)=' + floor03 +
+          ' 章，每条支线最多 30 章，所以 branch_count 至少要 ' + need +
+          '（当前 ' + BC + '）。请把 branch_count 调大到 ' + fLow + '~' + fHigh + ' 之间' +
+          (fLow > fHigh ? '（这两个值已经倒挂了：公式本身在当前卷数下无解，得先调 volume_count 或 target_chapters）' : '。')
+    });
+  }
+}
+
+// ============================================================
+// 世界观规则 id 前缀与 category 一致性
+// R 前缀 → 核心规则；I 前缀 → 信息规则；SR 前缀 → 社会规则
+// ============================================================
+const WORLD_RULE_CATEGORY_BY_PREFIX = [
+  { prefix: /^R\d{3}$/, category: '核心规则' },
+  { prefix: /^I\d{3}$/, category: '信息规则' },
+  { prefix: /^SR\d{3}$/, category: '社会规则' }
+];
+
+function checkWorldRuleCategory(entityData, errors) {
+  if (!entityData) return;
+  const rules = entityData.world_rules || [];
+  for (const [i, r] of rules.entries()) {
+    if (!r.id || !r.category) continue;
+    const match = WORLD_RULE_CATEGORY_BY_PREFIX.find(m => m.prefix.test(r.id));
+    if (!match) continue;  // 模式未匹配已在骨架模板 PATTERN 检查中拦截
+    if (match.category !== r.category) {
+      errors.push({
+        code: 'WORLD_RULE_CATEGORY_MISMATCH',
+        path: 'world_rules[' + i + ']',
+        message: 'id "' + r.id + '" 的前缀应对应 ' + match.category + '，实际 category 是 "' + r.category + '"',
+        hint: 'R 前缀 → 核心规则；I 前缀 → 信息规则；SR 前缀 → 社会规则'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 跨实体类型同名检查
+// ============================================================
+function crossTypeNameDupCheck(entityData, warnings) {
+  if (!entityData) return;
+  const types = ['characters', 'other_entities', 'factions', 'conflicts', 'locations'];
+  const typeLabels = { characters: '角色', other_entities: '其他实体', factions: '势力', conflicts: '冲突', locations: '地点' };
+  const nameMap = new Map();
+  for (const t of types) {
+    for (const item of (entityData[t] || [])) {
+      if (!item.name) continue;
+      const key = normalizeEntityName(item.name);
+      if (!key) continue;
+      if (!nameMap.has(key)) nameMap.set(key, []);
+      nameMap.get(key).push({ type: t, id: item.id, name: String(item.name) });
+    }
+  }
+  for (const [normalized, entries] of nameMap) {
+    if (entries.length <= 1) continue;
+    const typeSet = new Set(entries.map(e => e.type));
+    if (typeSet.size <= 1) continue;
+    const typesInvolved = [...typeSet].map(t => typeLabels[t]).join(' / ');
+    const names = [...new Set(entries.map((e) => e.name))];
+    warnings.push({
+      code: 'CROSS_TYPE_NAME_DUP',
+      path: 'name: ' + names.join(' / '),
+      message: '名称 ' + names.map((n) => '"' + n + '"').join('、') +
+        ' 在多个实体类型中重复出现（' + typesInvolved + '；归一化 key=' + normalized + '）',
+      hint: '不同类型同名可能导致引用歧义（如 faction.members[].name 与 faction.relations[].target_name 无法靠名字区分），建议改名'
+    });
+  }
+}
+
+// ============================================================
+// 图构建（P2-8：删除无效的 volumes 循环）
+// ============================================================
+function buildGraph(entityData, relationData, errors, warnings) {
+  const graph = new SimpleGraph();
+  if (!entityData) return;
+
+  for (const [arr, type] of [
+    ['characters', 'character'], ['conflicts', 'conflict'], ['factions', 'faction'],
+    ['locations', 'location'], ['items', 'item'], ['endings', 'ending'],
+    ['foreshadows', 'foreshadow'], ['climaxes', 'climax'], ['pleasures', 'pleasure'],
+    ['main_lines', 'main_line'], ['branches', 'branch'],
+    ['world_rules', 'world_rule'], ['other_entities', 'other_entity']
+  ]) {
+    for (const x of (entityData[arr] || [])) {
+      graph.addNode(x.id, { type: type, name: x.name });
+    }
+  }
+  // P2-8：删除原 v2.x 中无效的 volumes 循环
+  // （实体.json 无 volumes 字段，volumes 在层级.json，本函数不读层级.json）
+
+  if (!relationData) return;
+
+  const addEdge = (from, to, rel) => {
+    if (!graph.hasNode(from) || !graph.hasNode(to)) return;
+    graph.addEdgeWithKey(from + '--' + rel + '--' + to, from, to, { relation: rel });
+  };
+
+  for (const r of (relationData.character_relations || [])) addEdge(r.from, r.to, 'related_to');
+  for (const r of (relationData.other_relations || [])) addEdge(r.from, r.to, r.relation_label || 'related_to');
+  for (const r of (relationData.faction_membership || [])) addEdge(r.character, r.faction, 'member_of');
+  for (const r of (relationData.faction_relations || [])) addEdge(r.from, r.to, 'faction_related');
+  for (const r of (relationData.conflict_participants || [])) {
+    for (const c of (r.protagonist_side || [])) addEdge(c, r.conflict, 'participates_in');
+    if (r.main_antagonist) addEdge(r.main_antagonist, r.conflict, 'antagonist_of');
+    for (const c of (r.secondary_antagonist || [])) addEdge(c, r.conflict, 'participates_in');
+    for (const c of (r.third_party || [])) addEdge(c, r.conflict, 'participates_in');
+  }
+  for (const r of (relationData.branch_protagonist || [])) addEdge(r.character, r.branch, 'protagonist_of');
+  for (const r of (relationData.item_owner || [])) addEdge(r.item, r.owner_id, 'owned_by');
+  for (const r of (relationData.location_conflict || [])) {
+    for (const c of (r.conflicts || [])) addEdge(r.location, c, 'hosts');
+  }
+  for (const r of (relationData.ending_character || [])) addEdge(r.character, r.ending, 'destined_in');
+  for (const r of (relationData.main_line_branch_relation || [])) addEdge(r.main_line, r.branch, 'interweaves');
+
+  // 骨架阶段：foreshadow/climax/pleasure/world_rule 实体在 关系.json
+  // 模板中没有引用数组，无法建立边。它们的实体间关系在血肉阶段才补齐，
+  // 因此骨架阶段豁免这四类 + volume 的孤立节点检查。
+  const isolated = getIsolatedNodes(graph, ['volume', 'foreshadow', 'climax', 'pleasure', 'world_rule']);
+  for (const n of isolated) {
+    errors.push({
+      code: 'G_ISOLATED',
+      path: n.key,
+      message: '节点 ' + n.key + '（' + n.type + '）没有任何入边或出边（孤立节点）',
+      hint: '该实体没有被任何关系引用，也没有引用任何实体'
+    });
+  }
+
+  const disconnected = getDisconnectedCoreNodes(graph, ['character', 'conflict', 'faction']);
+  if (disconnected.length > 0) {
+    warnings.push({
+      code: 'G_DISCONNECTED',
+      path: 'core-subgraph',
+      message: '核心子图（character+conflict+faction）不连通，' + disconnected.length + ' 个节点不在主连通分量中',
+      hint: '孤立节点：' + disconnected.join(', ')
+    });
+  }
+}
+
+// ============================================================
+// 内容质量检查
+// ============================================================
+// 此前骨架阶段只校验结构，"实体名是「主角1」""描述只有四个字"这类空内容一律放行。
+// 这里按文件分派：框架.json 只查 input_snapshot（derivations 里是公式字符串，
+// 不是叙述内容，不能按文本长度判）；其余文件整体检查。
+function contentQualityCheck(fileType, data, errors, structure) {
+  const enumLeaves = collectEnumLeaves(structure);
+  if (fileType === '框架') {
+    if (data && data.input_snapshot && typeof data.input_snapshot === 'object') {
+      runContentQualityChecks(data.input_snapshot, errors, { enumLeaves });
+    }
+    return;
+  }
+  if (fileType === '关系') return;   // 纯 ID 关系表，无叙述内容
+  runContentQualityChecks(data, errors, { enumLeaves });
+}
+
+// ============================================================
+// 势力关系对称性
+// ============================================================
+function factionRelationSymmetryCheck(relationData, errors) {
+  const result = checkBidirectionalSymmetry(relationData.faction_relations || [], {
+    fromKey: 'from',
+    toKey: 'to',
+    typeKey: 'relation_type',
+    mustBeBidirectionalTypes: ['对立']
+  });
+
+  // path 用 `faction_relations.<from>→<to>` 格式：
+  // 之前写的是"势力关系 F001 → F002"，既没有数组名也没有结构化分隔，
+  // 归因层一个形态都匹配不上 → 这条错永远归不到批次 →
+  // 只能整段重跑（把同一份错发给所有批次，白烧额度）。
+  // 现在顶层键是 faction_relations，归因层能退化到"负责该数组的批次"。
+  for (const r of result.oneWay) {
+    errors.push({
+      code: 'G_REL_ONE_WAY',
+      path: 'faction_relations.' + r.from + '→' + r.to,
+      message: r.from + '→' + r.to + ' 为"对立"，但 ' + r.to + '→' + r.from + ' 未声明',
+      hint: '对立关系必须双向声明'
+    });
+  }
+  for (const r of result.asymmetric) {
+    errors.push({
+      code: 'G_REL_ASYMMETRIC',
+      path: 'faction_relations.' + r.from + '→' + r.to,
+      message: r.from + '→' + r.to + ' 是 "' + r.type + '"，但反向是 "' + r.reverseType + '"',
+      hint: '"对立"关系必须双向一致'
+    });
+  }
+}
+
+// ============================================================
+// 角色关系双向相容性
+// ============================================================
+// 背景：骨架 `character_relations` 是有向的（from 对 to），同一有序对只能有一条，
+// 但正反两个方向可以同时存在。此前没有任何检查比对这两个方向的关系类型，
+// 于是"骨架写 A 服从 B，血肉写 A 与 B 是上下级关系"这类语义不一致完全逃逸。
+//
+// 判定范围严格限定为增量：只有正反两个方向都声明了才比较，
+// 不强制"无向关系必须双向声明"，因此不改变合法骨架的数据结构边界。
+// 相容性规则见 graph-utils.js 的 relationKindCompatible。
+function characterRelationSymmetryCheck(relationData, errors) {
+  const rels = relationData.character_relations || [];
+  const forward = new Map();
+  for (const r of rels) {
+    if (!r || !r.from || !r.to) continue;
+    forward.set(r.from + '→' + r.to, r.relation_kind);
+  }
+
+  const reported = new Set();
+  for (const r of rels) {
+    if (!r || !r.from || !r.to) continue;
+    const revKey = r.to + '→' + r.from;
+    if (!forward.has(revKey)) continue;   // 单向声明不比较
+    // 同一对角色的正反两个方向都会命中，用无序对去重，保证每对只报一次
+    const pairKey = [r.from, r.to].sort().join('↔');
+    if (reported.has(pairKey)) continue;
+    reported.add(pairKey);
+    const revKind = forward.get(revKey);
+    const verdict = relationKindCompatible(r.relation_kind, revKind);
+    if (verdict.ok) continue;
+    errors.push({
+      code: 'REL_ASYMMETRIC_INCOMPATIBLE',
+      path: '角色关系 ' + r.from + ' → ' + r.to,
+      message: r.from + '→' + r.to + ' 是 "' + r.relation_kind + '"，但 ' + r.to + '→' + r.from + ' 是 "' + revKind + '"：' + verdict.reason,
+      hint: '同一对角色的正反两个方向的关系类型必须语义相容；请统一为一个意思，或改用词表内语义正确的类型'
+    });
+  }
+}
+
+// ============================================================
+// 关系类型词表与元数据同步检查
+// ============================================================
+// 词表（glossary.md 的 relation_kind）与机器判定元数据（RELATION_KIND_META）
+// 分处两处，必须有闸门防漂移，否则新加的词表值会被静默漏判。
+function relationKindMetaCheck(enums, errors) {
+  const drift = assertRelationKindMeta(enums);
+  if (!drift) return;
+  errors.push({
+    code: drift.code,
+    path: '',
+    message: drift.message,
+    hint: drift.hint
+  });
+}
+
+// ============================================================
+// md 生成（结构化 markdown，零反引号）— 渲染函数从 graph-utils 导入
+// ============================================================
+const BT = String.fromCharCode(96);
+const BT3 = BT + BT + BT;
+
+// 通用 markdown 渲染（骨架阶段的 dispatcher）
+
+// 框架文件的特殊渲染（顶层是 capacity / input_snapshot / quota / volume_ratio / derivations）
+function renderFramework(data) {
+  let out = '## 容量\n\n' + renderObject(data.capacity, 0) + '\n';
+  out += '## 输入快照\n\n' + renderObject(data.input_snapshot, 0) + '\n';
+  out += '## 数量配额\n\n' + renderObject(data.quota, 0) + '\n';
+  out += '## 卷比例\n\n';
+  if (Array.isArray(data.volume_ratio) && data.volume_ratio.length > 0) {
+    out += renderArray(data.volume_ratio, 0) + '\n';
+  } else {
+    out += '_(无)_\n';
+  }
+  out += '## 公式推导\n\n';
+  if (data.derivations && typeof data.derivations === 'object') {
+    // derivations 是 key→obj 字典：key 为公式名；用 H3 分组（每条公式一节）
+    const entries = Object.entries(data.derivations);
+    for (const [k, v] of entries) {
+      out += '### ' + k + '\n\n';
+      if (v && typeof v === 'object') {
+        // 子字段走 cnLabelCtx（公式推导是 derivations.* 下的字段）
+        for (const [vk, vv] of Object.entries(v)) {
+          const label = (typeof cnLabelCtx === 'function' ? cnLabelCtx(vk, 'derivations') : vk);
+          out += '- **' + label + '**（' + vk + '）: ' + mdEscape(vv) + '\n';
+        }
+      } else {
+        out += '- ' + mdEscape(v) + '\n';
+      }
+      out += '\n';
+    }
+  } else {
+    out += '_(无)_\n';
+  }
+  return out;
+}
+
+// 实体文件的渲染（12 类实体数组）
+const ENTITY_ARRAYS = [
+  ['characters', '角色'],
+  ['other_entities', '其他实体'],
+  ['conflicts', '冲突'],
+  ['factions', '势力'],
+  ['locations', '地点'],
+  ['items', '道具'],
+  ['endings', '结局'],
+  ['foreshadows', '伏笔'],
+  ['climaxes', '高潮'],
+  ['pleasures', '爽点'],
+  ['world_rules', '世界观规则'],
+  ['main_lines', '主线'],
+  ['branches', '支线']
+];
+
+function renderEntity(data) {
+  let out = '';
+  for (const [key, label] of ENTITY_ARRAYS) {
+    const arr = data[key];
+    if (!Array.isArray(arr) || arr.length === 0) continue;
+    out += '## ' + label + '（' + arr.length + ' 项）\n\n';
+    out += renderArray(arr, 0, key) + '\n';
+  }
+  return out;
+}
+
+// 关系文件的渲染（9 类关系数组）
+const RELATION_ARRAYS = [
+  ['character_relations', '角色关系'],
+  ['other_relations', '其他关系'],
+  ['faction_membership', '势力成员'],
+  ['faction_relations', '势力关系'],
+  ['conflict_participants', '冲突参与'],
+  ['branch_protagonist', '支线主角'],
+  ['item_owner', '道具归属'],
+  ['location_conflict', '地点冲突'],
+  ['ending_character', '结局角色'],
+  ['main_line_branch_relation', '主线-支线关系']
+];
+
+function renderRelation(data) {
+  let out = '';
+  for (const [key, label] of RELATION_ARRAYS) {
+    const arr = data[key];
+    if (!Array.isArray(arr) || arr.length === 0) continue;
+    out += '## ' + label + '（' + arr.length + ' 条）\n\n';
+    out += renderArray(arr, 0, key) + '\n';
+  }
+  return out;
+}
+
+// 层级文件的渲染（volumes / acts / main_line_span / branch_span）
+function renderHierarchy(data) {
+  let out = '';
+  if (Array.isArray(data.volumes) && data.volumes.length > 0) {
+    out += '## 卷（' + data.volumes.length + ' 个）\n\n';
+    out += renderArray(data.volumes, 0, 'volumes') + '\n';
+  }
+  if (Array.isArray(data.acts) && data.acts.length > 0) {
+    out += '## 幕（' + data.acts.length + ' 个）\n\n';
+    out += renderArray(data.acts, 0, 'acts') + '\n';
+  }
+  if (Array.isArray(data.main_line_span) && data.main_line_span.length > 0) {
+    out += '## 主线卷分布（' + data.main_line_span.length + ' 条）\n\n';
+    out += renderArray(data.main_line_span, 0, 'main_line_span') + '\n';
+  }
+  if (Array.isArray(data.branch_span) && data.branch_span.length > 0) {
+    out += '## 支线卷分布（' + data.branch_span.length + ' 条）\n\n';
+    out += renderArray(data.branch_span, 0, 'branch_span') + '\n';
+  }
+  return out;
+}
+
+// 骨架阶段 4 类文件的 dispatcher
+function jsonToMd(data, fileType) {
+  let body = '';
+  if (fileType === '框架') body = renderFramework(data);
+  else if (fileType === '实体') body = renderEntity(data);
+  else if (fileType === '关系') body = renderRelation(data);
+  else if (fileType === '层级') body = renderHierarchy(data);
+  else body = renderObject(data, 0);  // 兜底：通用对象渲染
+  return '# ' + fileType + '\n\n> 自动生成于 ' + new Date().toISOString() +
+    '\n\n' + body + '\n---\n\n## 源数据\n\n' +
+    BT3 + 'json\n' + JSON.stringify(data, null, 2) + '\n' + BT3 + '\n';
+}
+
+function regenerateMd(stageDir) {
+  if (!fs.existsSync(stageDir)) return;
+  // 排除 .stage-status.json：它是校验状态记账文件，不是业务数据，
+  // 不应该被渲染成 Markdown（此前会多出一个 .stage-status.md）
+  const files = fs.readdirSync(stageDir).filter(f => f.endsWith('.json') && !f.startsWith('.'));
+  for (const f of files) {
+    const jsonPath = path.join(stageDir, f);
+    const mdPath = jsonPath.replace(/\.json$/, '.md');
+    try {
+      const data = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+      const fileType = f.replace(/\.json$/, '');
+      fs.writeFileSync(mdPath, jsonToMd(data, fileType), 'utf-8');
+    } catch (e) {}
+  }
+}
+
+function updateStageStatus(stageDir, fileType, status, passedTypes) {
+  const statusPath = path.join(stageDir, '.stage-status.json');
+  let s = { stage: '骨架', last_check: null, files: {}, all_check: { status: 'PENDING', rounds: 0 } };
+  if (fs.existsSync(statusPath)) {
+    try { s = JSON.parse(fs.readFileSync(statusPath, 'utf-8')); } catch (e) {}
+  }
+  // 兜底：旧 status 文件可能缺 files / all_check 字段
+  s.stage = s.stage || '骨架';
+  s.files = s.files || {};
+  s.all_check = s.all_check || { status: 'PENDING', rounds: 0 };
+  s.last_check = new Date().toISOString();
+  if (fileType === 'ALL') {
+    s.all_check = { status: status === 0 ? 'PASSED' : 'FAILED', rounds: (s.all_check.rounds || 0) + 1 };
+    // 全量通过时，把每个文件也登记成 PASSED。
+    //
+    // 为什么需要：续跑的判据是 readSkeletonSettledFiles 读 .stage-status.json 的
+    // files[type].status（skeleton-output.js:105-109）。而骨架段三（关系+层级）
+    // 只跑 --all，不跑单文件校验 → files['关系'] / files['层级'] 永远不会被写 →
+    // 这两个文件永远判不了"已定稿" → 重跑骨架阶段时关系 27 批 + 层级 4 批
+    // 全部重派（tt5 实测骨架一次 40+ 批），正是续跑机制要避免的。
+    //
+    // 为什么 --all 通过就能登记：validateAll 跑的是**单文件检查的超集**——
+    // 四个文件的通用检查 + 各自的专属检查一个不缺，还多跑了跨文件检查，
+    // 而且它自己就加载了实体/框架做上游（loaded['实体'] / loaded['框架']），
+    // 不依赖 --upstream 参数。所以 --all 过 = 每个文件都过了自己的检查。
+    //
+    // --all 失败时不登记：失败无法定位到具体文件，保守起见不动已有的单文件
+    // 记录（那个文件重做，已通过的文件照样定稿）。
+    if (status === 0 && Array.isArray(passedTypes)) {
+      for (const t of passedTypes) {
+        const prev = s.files[t] || { retries: 0 };
+        s.files[t] = { status: 'PASSED', retries: prev.retries || 0, last_check: s.last_check };
+      }
+    }
+  } else {
+    const prev = s.files[fileType] || { retries: 0 };
+    s.files[fileType] = { status: status === 0 ? 'PASSED' : 'FAILED', retries: (prev.retries || 0) + (status === 1 ? 1 : 0), last_check: new Date().toISOString() };
+    // 单文件一旦被改动/失败，之前的全量结论就不再可信（全量含跨文件检查：
+    // 配额一致性、图连通性、引用完整性等），必须作废，等重新跑 --all。
+    if (s.all_check && s.all_check.status === 'PASSED') {
+      s.all_check = {
+        status: 'STALE',
+        rounds: s.all_check.rounds || 0,
+        stale_reason: '文件 ' + fileType + ' 在 ' + s.last_check + ' 被单文件校验改动，全量结论已作废，请重新执行全量校验',
+        stale_at: s.last_check
+      };
+    }
+  }
+  try { fs.writeFileSync(statusPath, JSON.stringify(s, null, 2), 'utf-8'); } catch (e) {}
+}
+
+function emit(status, file, errors, warnings) {
+  const payload = { status: status, file: file, errors: errors, warnings: warnings };
+  process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  process.exitCode = status;
+  // 返回载荷对象：调用方可能用返回值做守卫（如 `if (err) return err;`），
+  // 返回 undefined 会让守卫失效导致继续执行并二次输出。
+  return payload;
+}
+
+// ============================================================
+// 单文件模式
+// ============================================================
+function validateSingle(args) {
+  const input = args.input;
+  const template = args.template;
+  const file = args.file;
+  const errors = [];
+  const warnings = [];
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, file, [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+  const fm = loadFormulas();
+  if (fm.error) return emit(2, file, [{ code: 'FORMULAS_LOAD', path: '', message: fm.error, hint: null }], []);
+
+  safeCheck('relationKindMetaCheck', () => relationKindMetaCheck(gl.enums, errors), errors);
+
+  const inputRes = readJson(input);
+  if (inputRes.error) return emit(2, file, [{ code: 'READ', path: input, message: inputRes.error, hint: null }], []);
+  const data = inputRes.data;
+
+  const tplRes = readJson(template);
+  if (tplRes.error) return emit(2, file, [{ code: 'TEMPLATE', path: template, message: tplRes.error, hint: null }], []);
+
+  let upstreamEntities = null;
+  let upstreamFramework = null;
+  if (args.upstream && args.upstream.length > 0) {
+    for (const upDir of args.upstream) {
+      const entRes = readJson(path.join(upDir, '实体.json'));
+      if (entRes.data) upstreamEntities = entRes.data;
+      const fwRes = readJson(path.join(upDir, '框架.json'));
+      if (fwRes.data) upstreamFramework = fwRes.data;
+    }
+  }
+
+  const scalarSet = new Set(gl.chapterScalarFields);
+  const containerSet = new Set(gl.chapterContainerFields);
+
+  safeCheck('checkChapterForbidden', () => checkChapterForbidden(data, scalarSet, containerSet, errors), errors);
+  safeCheck('validateNode', () => validateNode(data, tplRes.data.structure || {}, '', gl.enums, errors), errors);
+  safeCheck('charsetAndForbiddenCheck', () => charsetAndForbiddenCheck(data, errors), errors);
+  safeCheck('idUniquenessCheck', () => idUniquenessCheck(data, file, errors), errors);
+  safeCheck('nameUniquenessCheck', () => nameUniquenessCheck(data, file, errors), errors);
+  safeCheck('nameAliasCheck', () => nameAliasCheck(data, file, warnings), errors);
+
+  if (file === '框架') {
+    safeCheck('frameworkSpecificCheck', () => frameworkSpecificCheck(data, errors, warnings), errors);
+    safeCheck('derivationCheck', () => derivationCheck(data, fm.formulas, errors, warnings), errors);
+    safeCheck('checkRhythmFeasibility', () => checkRhythmFeasibility(data, errors, fm.formulas), errors);
+  } else if (file === '关系') {
+    safeCheck('selfRelationCheck', () => selfRelationCheck(data, errors), errors);
+    safeCheck('relationDupCheck', () => relationDupCheck(data, errors), errors);
+    safeCheck('relationLabelCheck', () => relationLabelCheck(data, errors), errors);
+    safeCheck('relationRefCheck', () => relationRefCheck(data, upstreamEntities, errors), errors);
+    // 支线挂主线的覆盖度：关系文件对着实体清单查（tt5 实测的静默缺失）
+    safeCheck('checkBranchMainLineCoverage', () => checkBranchMainLineCoverage(upstreamEntities, data, errors), errors);
+    safeCheck('characterRelationSymmetryCheck', () => characterRelationSymmetryCheck(data, errors), errors);
+  } else if (file === '层级') {
+    safeCheck('hierarchyRefCheck', () => hierarchyRefCheck(data, upstreamEntities, upstreamFramework, errors), errors);
+  } else if (file === '实体') {
+    safeCheck('checkBookEndingLevel', () => checkBookEndingLevel(data, errors), errors);
+    safeCheck('checkWorldRuleCategory', () => checkWorldRuleCategory(data, errors), errors);
+  }
+
+  safeCheck('contentQualityCheck', () => contentQualityCheck(file, data, errors, tplRes.data.structure), errors);
+
+  const stageDir = path.dirname(input);
+  updateStageStatus(stageDir, file, errors.length === 0 ? 0 : 1);
+  regenerateMd(stageDir);
+
+  // 单文件模式不做跨文件检查（配额一致性/图连通性/跨文件引用等），
+  // 必须在本阶段全部文件单检完成后跑一次 --all 才算通过。提醒一下。
+  if (errors.length === 0) {
+    warnings.push({
+      code: 'NEED_ALL_CHECK',
+      path: '',
+      message: '本文件单检通过；跨文件一致性检查在 --all 模式下进行，全部文件单检完成后仍需执行一次全量校验（--all）',
+      hint: null
+    });
+  }
+
+  emit(errors.length === 0 ? 0 : 1, file, errors, warnings);
+}
+
+// ============================================================
+// 局部模式（--arrays）：只校验指定的几个数组
+// ============================================================
+
+/**
+ * 局部校验：只判"这几个数组"上**当场就能判**的错。
+ *
+ * 为什么需要它（tt5 实测）：
+ *   骨架的关系+层级段是 31 个批次**连续派活**，全部写完才跑一次全量校验。
+ *   结果第 8 批（faction_relations）写错了行数，要等 23 批都写完才发现，
+ *   返工时整段重来一遍。模型在没有反馈通道的那 31 轮里，
+ *   自己造了 45 个检查脚本在猜校验器的判据（`_chk2.mjs` … `_chk46.mjs`）。
+ *
+ *   中途插入一次局部校验就能把反馈提前到"第 8 批写完"。
+ *   但**全量校验在半成品上不可判**：文件还缺别的数组（REQUIRED 会误报）、
+ *   图还不连通（G_ISOLATED 会误报）。所以中途校验必须是"局部口径"。
+ *
+ * 局部模式判这些（都只依赖指定数组本身 + 上游实体清单）：
+ *   · 模板子树：类型 / 枚举 / 模板外字段
+ *   · 引用完整性：引用的 id 在实体清单里存不存在
+ *   · 重复 / 自环 / 正反对称性
+ *   · 行数对账：faction_relations 的行数 vs quota
+ *
+ * 局部模式**不判**（要等文件写完才有意义）：
+ *   · REQUIRED（别的数组还没写）
+ *   · 图连通性 / 孤立节点（关系网还不完整）
+ *   · 支线挂主线的覆盖度（别的支线还没写）
+ *
+ * 用法：
+ *   node skeleton-validate.js --input=关系.json --template=关系模板.json \
+ *        --file=关系 --upstream=<骨架目录> --arrays=faction_relations,faction_membership
+ *
+ * 局部模式**不改 .stage-status.json、不重新生成 .md** ——
+ * 它是中途的一脚，不是阶段结论。
+ */
+function validatePartial(args) {
+  const input = args.input;
+  const template = args.template;
+  const file = args.file;
+  const arrays = String(args.arrays || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const errors = [];
+  const warnings = [];
+
+  if (!arrays.length) {
+    return emit(2, file, [{ code: 'ARG', path: '--arrays', message: '局部模式需要 --arrays（逗号分隔的数组名）', hint: null }], []);
+  }
+  if (!input || !template || !file) {
+    return emit(2, file || 'UNKNOWN', [{ code: 'ARG', path: '', message: '局部模式需要 --input 和 --template 和 --file', hint: null }], []);
+  }
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, file, [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+  const fm = loadFormulas();
+  if (fm.error) return emit(2, file, [{ code: 'FORMULAS_LOAD', path: '', message: fm.error, hint: null }], []);
+
+  safeCheck('relationKindMetaCheck', () => relationKindMetaCheck(gl.enums, errors), errors);
+
+  const inputRes = readJson(input);
+  if (inputRes.error) return emit(2, file, [{ code: 'READ', path: input, message: inputRes.error, hint: null }], []);
+  const data = inputRes.data || {};
+
+  const tplRes = readJson(template);
+  if (tplRes.error) return emit(2, file, [{ code: 'TEMPLATE', path: template, message: tplRes.error, hint: null }], []);
+
+  let upstreamEntities = null;
+  let upstreamFramework = null;
+  for (const upDir of (args.upstream || [])) {
+    const entRes = readJson(path.join(upDir, '实体.json'));
+    if (entRes.data) upstreamEntities = entRes.data;
+    const fwRes = readJson(path.join(upDir, '框架.json'));
+    if (fwRes.data) upstreamFramework = fwRes.data;
+  }
+
+  // 只保留被点名的数组：现有检查函数按数组名取数据，裁剪后的视图能直接复用它们
+  const scoped = {};
+  for (const k of arrays) {
+    scoped[k] = Array.isArray(data[k]) ? data[k] : [];
+  }
+
+  const props = (tplRes.data.structure || {}).properties || {};
+  for (const k of arrays) {
+    if (!props[k]) {
+      errors.push({ code: 'ARG', path: k, message: '模板里没有这个数组：' + k, hint: null });
+      continue;
+    }
+    // 逐数组走模板子树：只查类型/枚举/模板外字段，不查顶层 REQUIRED
+    safeCheck('validateNode:' + k, () => validateNode(scoped[k], props[k], k, gl.enums, errors), errors);
+  }
+
+  if (file === '关系') {
+    safeCheck('selfRelationCheck', () => selfRelationCheck(scoped, errors), errors);
+    safeCheck('relationDupCheck', () => relationDupCheck(scoped, errors), errors);
+    safeCheck('relationLabelCheck', () => relationLabelCheck(scoped, errors), errors);
+    safeCheck('relationRefCheck', () => relationRefCheck(scoped, upstreamEntities, errors), errors);
+    safeCheck('characterRelationSymmetryCheck', () => characterRelationSymmetryCheck(scoped, errors), errors);
+    safeCheck('factionRelationSymmetryCheck', () => factionRelationSymmetryCheck(scoped, errors), errors);
+    // 行数对账：势力关系写了几行，当场就能判
+    safeCheck('checkFactionRelationRowCount', () => {
+      if (arrays.indexOf('faction_relations') < 0) return;
+      checkFactionRelationRowCount(upstreamFramework, scoped, errors, fm.formulas);
+    }, errors);
+  }
+
+  emit(errors.length === 0 ? 0 : 1, file, errors, warnings);
+}
+
+// ============================================================
+// 全量模式
+// ============================================================
+function validateAll(args) {
+  const stageDir = args['stage-dir'];
+  const templateDir = args['template-dir'];
+  const errors = [];
+  const warnings = [];
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, 'ALL', [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+  const fm = loadFormulas();
+  if (fm.error) return emit(2, 'ALL', [{ code: 'FORMULAS_LOAD', path: '', message: fm.error, hint: null }], []);
+
+  safeCheck('relationKindMetaCheck', () => relationKindMetaCheck(gl.enums, errors), errors);
+
+  if (!fs.existsSync(stageDir)) {
+    return emit(2, 'ALL', [{ code: 'ARG', path: stageDir, message: '阶段目录不存在', hint: null }], []);
+  }
+
+  const FILES = [
+    { type: '框架', name: '框架.json', tpl: '框架模板.json' },
+    { type: '实体', name: '实体.json', tpl: '实体模板.json' },
+    { type: '关系', name: '关系.json', tpl: '关系模板.json' },
+    { type: '层级', name: '层级.json', tpl: '层级模板.json' }
+  ];
+
+  const loaded = {};
+  const scalarSet = new Set(gl.chapterScalarFields);
+  const containerSet = new Set(gl.chapterContainerFields);
+
+  for (const f of FILES) {
+    const dataPath = path.join(stageDir, f.name);
+    const tplPath = path.join(templateDir, f.tpl);
+    const inputRes = readJson(dataPath);
+    if (inputRes.error) {
+      errors.push({ code: 'READ', path: dataPath, message: inputRes.error, hint: null });
+      continue;
+    }
+    const tplRes = readJson(tplPath);
+    if (tplRes.error) {
+      errors.push({ code: 'TEMPLATE', path: tplPath, message: tplRes.error, hint: null });
+      continue;
+    }
+    loaded[f.type] = inputRes.data;
+    const data = inputRes.data;
+
+    safeCheck('checkChapterForbidden', () => checkChapterForbidden(data, scalarSet, containerSet, errors), errors);
+    safeCheck('validateNode', () => validateNode(data, tplRes.data.structure || {}, '', gl.enums, errors), errors);
+    safeCheck('charsetAndForbiddenCheck', () => charsetAndForbiddenCheck(data, errors), errors);
+    safeCheck('idUniquenessCheck', () => idUniquenessCheck(data, f.type, errors), errors);
+    safeCheck('nameUniquenessCheck', () => nameUniquenessCheck(data, f.type, errors), errors);
+    safeCheck('nameAliasCheck', () => nameAliasCheck(data, f.type, warnings), errors);
+
+    if (f.type === '框架') {
+      safeCheck('frameworkSpecificCheck', () => frameworkSpecificCheck(data, errors, warnings), errors);
+      safeCheck('derivationCheck', () => derivationCheck(data, fm.formulas, errors, warnings), errors);
+    } else if (f.type === '关系') {
+      safeCheck('selfRelationCheck', () => selfRelationCheck(data, errors), errors);
+      safeCheck('relationDupCheck', () => relationDupCheck(data, errors), errors);
+      safeCheck('relationLabelCheck', () => relationLabelCheck(data, errors), errors);
+      safeCheck('relationRefCheck', () => relationRefCheck(data, loaded['实体'], errors), errors);
+      // 支线挂主线的覆盖度（tt5 实测：只写 1 行也 PASSED，9 条支线静默孤儿）
+      safeCheck('checkBranchMainLineCoverage', () => checkBranchMainLineCoverage(loaded['实体'], data, errors), errors);
+    } else if (f.type === '层级') {
+      safeCheck('hierarchyRefCheck', () => hierarchyRefCheck(data, loaded['实体'], loaded['框架'], errors), errors);
+    }
+
+    safeCheck('contentQualityCheck', () => contentQualityCheck(f.type, data, errors, tplRes.data.structure), errors);
+  }
+
+  if (loaded['实体'] && loaded['关系']) {
+    safeCheck('buildGraph', () => buildGraph(loaded['实体'], loaded['关系'], errors, warnings), errors);
+    safeCheck('factionRelationSymmetryCheck', () => factionRelationSymmetryCheck(loaded['关系'], errors), errors);
+    safeCheck('characterRelationSymmetryCheck', () => characterRelationSymmetryCheck(loaded['关系'], errors), errors);
+  }
+
+  // P2-4：传入 loaded['关系'] 供 faction_relation_count 检查
+  safeCheck('checkQuotaConsistency', () => checkQuotaConsistency(loaded['框架'], loaded['实体'], loaded['层级'], loaded['关系'], errors, fm.formulas), errors);
+  safeCheck('checkBookEndingLevel', () => checkBookEndingLevel(loaded['实体'], errors), errors);
+  safeCheck('checkWorldRuleCategory', () => checkWorldRuleCategory(loaded['实体'], errors), errors);
+  safeCheck('checkRhythmFeasibility', () => checkRhythmFeasibility(loaded['框架'], errors, fm.formulas), errors);
+  safeCheck('crossTypeNameDupCheck', () => crossTypeNameDupCheck(loaded['实体'], warnings), errors);
+
+  updateStageStatus(stageDir, 'ALL', errors.length === 0 ? 0 : 1, FILES.map((f) => f.type));
+  regenerateMd(stageDir);
+  emit(errors.length === 0 ? 0 : 1, 'ALL', errors, warnings);
+}
+
+// ============================================================
+// 入口
+// ============================================================
+function main() {
+  const args = parseArgs();
+
+  if (args.all) {
+    if (!args['stage-dir'] || !args['template-dir']) {
+      return emit(2, 'ALL', [{ code: 'ARG', path: '', message: '全量模式需要 --stage-dir 和 --template-dir', hint: null }], []);
+    }
+    return validateAll(args);
+  }
+
+  if (args.input) {
+    if (args.arrays) {
+      // 局部模式：只判指定数组（中途校验用，不改 .stage-status.json）
+      return validatePartial(args);
+    }
+    if (!args.template || !args.file) {
+      return emit(2, args.file || 'UNKNOWN', [{ code: 'ARG', path: '', message: '单文件模式需要 --template 和 --file', hint: null }], []);
+    }
+    return validateSingle(args);
+  }
+
+  return emit(2, 'UNKNOWN', [{ code: 'ARG', path: '', message: '需要 --input 或 --all', hint: null }], []);
+}
+
+main();