@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

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

@@ -0,0 +1,1216 @@
+#!/usr/bin/env node
+/**
+ * 节奏阶段校验脚本 v1.2
+ * 源码中零反引号，避免 markdown 渲染问题。
+ *
+ * v1.2 变更（修复批次 P2-6）：
+ * - P2-6：单文件与全量模式都强制要求 --upstream 至少包含两个目录
+ *   （骨架 + 血肉）。原版只检查 length === 0，只提供骨架目录也能跑，
+ *   与 03-rhythm-prompt.md 的"必须同时指定骨架和血肉两个目录"不一致。
+ *   现在 length < 2 直接 status:2 + UPSTREAM_MISSING。
+ *
+ * 保留 v1.1 的 P2-4 修复：
+ * - 章节号字段清单从 glossary 读
+ * - LARGE_FORESHADOW_TYPE / BOOK_ENDING_LEVEL 启动时校验 glossary
+ * - parseGlossaryFromMd import
+ * - act 有效性检查（RHYTHM_ACT_INVALID）
+ * - keyNodes 空时 RHYTHM_COVERAGE_SKIPPED warning
+ *
+ * 用法：
+ *   单文件：node rhythm-validate.js --input=<json> --template=<模板> --file=<类型> --upstream=<骨架目录>,<血肉目录>
+ *   全量：  node rhythm-validate.js --stage-dir=<节奏目录> --template-dir=<模板/节奏> --upstream=<骨架目录>,<血肉目录> --all
+ * 退出码：0=通过  1=内容错误  2=脚本异常
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SimpleGraph, getIsolatedNodes, parseGlossaryChecked, mdEscape, renderObject, renderArray, renderRhythmByFileType, readStageGate, safeCheck } from './graph-utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ============================================================
+// 业务常量（依赖 glossary 的枚举值）
+// ============================================================
+const LARGE_FORESHADOW_TYPE = '大伏笔';
+const BOOK_ENDING_LEVEL = '全书级';
+
+// P2-6：节奏阶段必须双上游
+const MIN_UPSTREAM_COUNT = 2;
+
+// ============================================================
+// 参数解析
+// ============================================================
+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-rhythm.json'));
+  if (r.error) return { error: 'formulas-rhythm.json 读取失败: ' + r.error };
+  return { constraints: r.data.constraints || {} };
+}
+
+// ============================================================
+// 启动时校验业务常量是否仍在 glossary 中
+// ============================================================
+function assertBusinessConstants(gl, warnings) {
+  const check = (enumName, value) => {
+    const values = gl.enums[enumName];
+    if (!values) {
+      warnings.push({
+        code: 'ENUM_MISSING',
+        path: 'glossary.' + enumName,
+        message: 'glossary 缺少枚举 ' + enumName + '，coverage 检查可能失效',
+        hint: null
+      });
+      return;
+    }
+    if (!values.includes(value)) {
+      warnings.push({
+        code: 'ENUM_VALUE_MISSING',
+        path: 'glossary.' + enumName,
+        message: 'glossary.' + enumName + ' 中不含值 "' + value + '"，coverage 检查可能失效',
+        hint: '如 glossary 已改名，请同步更新 rhythm-validate.js 的 LARGE_FORESHADOW_TYPE / BOOK_ENDING_LEVEL 常量'
+      });
+    }
+  };
+  check('foreshadow_type', LARGE_FORESHADOW_TYPE);
+  check('ending_level', BOOK_ENDING_LEVEL);
+}
+
+// ============================================================
+// 模板校验
+// ============================================================
+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));
+  }
+}
+
+// ============================================================
+// 字符集 / 占位符
+// ============================================================
+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, '');
+}
+
+// ============================================================
+// 时序映射条目的定位串
+// ============================================================
+//
+// 为什么不用数组下标：
+//   时序映射的 character_timeline 等数组合并后有几十条，
+//   校验器报的 `character_timeline[3]` 里的 3 是**合并后的下标**——
+//   模型不知道第 3 条是哪个角色，拿到错误定位不到，改的可能是别的条目。
+//   业务键（char_id / conflict_id / …）模型一眼能对上，改得动。
+//
+//   归因层那边加了「key[标识]」形态来接这种 path（见 stage-batches.js）。
+const TIMELINE_KEY_FIELD = {
+  character_timeline: 'char_id',
+  conflict_timeline: 'conflict_id',
+  foreshadow_timeline: 'fs_id',
+  climax_timeline: 'climax_id',
+  pleasure_timeline: 'pleasure_id',
+  hook_timeline: 'ch',
+  main_line_timeline: 'main_id',
+  branch_timeline: 'branch_id',
+  location_timeline: 'loc_id',
+  item_timeline: 'item_id',
+  ending_timeline: 'ending_id'
+};
+
+/**
+ * 条目定位串：`arrName[业务键]`。
+ * 条目缺业务键时退回下标（总比没有 path 好）。
+ *
+ * @param {string} arrName 数组名
+ * @param {Object} entry 该条目
+ * @param {number} index 该条目在数组里的下标
+ * @returns {string}
+ */
+function itemPath(arrName, entry, index) {
+  const field = TIMELINE_KEY_FIELD[arrName];
+  const key = entry && field ? entry[field] : undefined;
+  if (key === undefined || key === null || key === '') return arrName + '[' + index + ']';
+  return arrName + '[' + key + ']';
+}
+
+// ============================================================
+// 章节号越界检查
+// ============================================================
+function checkChapterRanges(data, T, chapterScalarFields, errors) {
+  const scalarSet = new Set(chapterScalarFields);
+  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 (scalarSet.has(k) && typeof v === 'number') {
+        if (v < 1 || v > T) {
+          errors.push({
+            code: 'RHYTHM_CHAP_RANGE',
+            path: curPath,
+            message: '章节号 ' + v + ' 越界 [1, ' + T + ']',
+            hint: null
+          });
+        }
+      }
+      walk(v, curPath);
+    }
+  };
+  walk(data, '');
+}
+
+// ============================================================
+// 联合可行性约束
+// ============================================================
+function evalConstraint(expr, ctx) {
+  if (typeof expr !== 'string' || expr.length === 0) throw new Error('表达式为空');
+  // 与骨架阶段 evalExpr 一致的安全白名单：只允许算术/比较/逻辑运算符、属性访问，
+  // 以及约束里用到的中文标识符（骨架 / 节奏参数）。此前此处无白名单，
+  // 与 evalExpr 信任级别不对称。
+  if (!/^[0-9a-zA-Z_\u4e00-\u9fa5.\[\]()+\-*/%,\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]));
+}
+
+function checkRhythmInfeasible(rhythmData, frameworkData, constraints, errors) {
+  const ctx = {
+    Math: Math,
+    骨架: {
+      capacity: { target_chapters: frameworkData?.capacity?.target_chapters },
+      quota: {
+        branch_count: frameworkData?.quota?.branch_count,
+        volume_count: frameworkData?.quota?.volume_count
+      }
+    },
+    节奏参数: {
+      branch_chapter_total: rhythmData.branch_chapter_total,
+      overlap_chapter_count: rhythmData.overlap_chapter_count,
+      main_progress_chapter_count: rhythmData.main_progress_chapter_count
+    }
+  };
+
+  for (const [name, spec] of Object.entries(constraints)) {
+    let result;
+    try {
+      result = evalConstraint(spec.expr, ctx);
+    } catch (e) {
+      errors.push({
+        code: 'RHYTHM_CONSTRAINT_EVAL',
+        path: '节奏参数.' + (spec.applies_to_field || 'root'),
+        message: '约束 ' + name + ' 求值失败：' + e.message,
+        hint: spec.expr
+      });
+      continue;
+    }
+    if (result !== true) {
+      errors.push({
+        code: 'RHYTHM_INFEASIBLE',
+        path: '节奏参数.' + (spec.applies_to_field || 'root'),
+        message: spec.message || ('约束 ' + name + ' 不满足'),
+        hint: spec.expr
+      });
+    }
+  }
+}
+
+// ============================================================
+// 实体 id 集合构建
+// ============================================================
+function buildIdSets(skeleton, flesh) {
+  const idSets = {
+    char: new Set(), conflict: new Set(), faction: new Set(),
+    location: new Set(), item: new Set(), ending: new Set(),
+    foreshadow: new Set(), climax: new Set(), pleasure: new Set(),
+    main_line: new Set(), branch: new Set(), world_rule: new Set(), volume: new Set()
+  };
+  const sk = skeleton.entity || {};
+  const addAll = (arr, key) => { for (const x of arr || []) if (x.id) idSets[key].add(x.id); };
+  addAll(sk.characters, 'char');
+  addAll(sk.conflicts, 'conflict');
+  addAll(sk.factions, 'faction');
+  addAll(sk.locations, 'location');
+  addAll(sk.items, 'item');
+  addAll(sk.endings, 'ending');
+  addAll(sk.foreshadows, 'foreshadow');
+  addAll(sk.climaxes, 'climax');
+  addAll(sk.pleasures, 'pleasure');
+  addAll(sk.main_lines, 'main_line');
+  addAll(sk.branches, 'branch');
+  addAll(sk.world_rules, 'world_rule');
+  if (skeleton.hierarchy) addAll(skeleton.hierarchy.volumes, 'volume');
+  if (flesh.characters) addAll(flesh.characters.characters, 'char');
+  if (flesh.conflicts) addAll(flesh.conflicts.conflicts, 'conflict');
+  if (flesh.factions) addAll(flesh.factions.factions, 'faction');
+  if (flesh.locations) addAll(flesh.locations.locations, 'location');
+  if (flesh.endings) addAll(flesh.endings.endings, 'ending');
+  if (flesh.items) {
+    addAll(flesh.items.core_items, 'item');
+    addAll(flesh.items.branch_items, 'item');
+    addAll(flesh.items.symbolic_items, 'item');
+  }
+  if (flesh.plot) {
+    addAll(flesh.plot.main_lines, 'main_line');
+    addAll(flesh.plot.branches, 'branch');
+  }
+  return idSets;
+}
+
+// ============================================================
+// 时序映射完整性
+// ============================================================
+function checkTimelineIntegrity(timeline, idSets, errors) {
+  const check = (id, set, label, p) => {
+    if (!id) return;
+    if (!set.has(id)) {
+      errors.push({ code: 'RHYTHM_REF_MISSING', path: p, message: '引用 ' + label + ' "' + id + '" 不存在于骨架/血肉', hint: null });
+    }
+  };
+
+  for (const [i, r] of (timeline.character_timeline || []).entries()) {
+    check(r.char_id, idSets.char, '角色', 'character_timeline[' + i + '].char_id');
+    if (typeof r.appear_start === 'number' && typeof r.appear_end === 'number' && r.appear_start > r.appear_end) {
+      errors.push({ code: 'RHYTHM_CHAP_ORDER', path: itemPath('character_timeline', r, i), message: 'appear_start(' + r.appear_start + ') > appear_end(' + r.appear_end + ')', hint: null });
+    }
+    if (typeof r.exit_chapter === 'number' && typeof r.appear_start === 'number' && typeof r.appear_end === 'number') {
+      if (r.exit_chapter < r.appear_start || r.exit_chapter > r.appear_end) {
+        errors.push({ code: 'RHYTHM_EXIT_IN_SPAN', path: itemPath('character_timeline', r, i) + '.exit_chapter', message: '退场章 ' + r.exit_chapter + ' 不在出场区间 [' + r.appear_start + ', ' + r.appear_end + ']', hint: null });
+      }
+    }
+    for (const [j, s] of (r.arc_stages || []).entries()) {
+      if (typeof s.chapter === 'number' && typeof r.appear_start === 'number') {
+        const maxCh = typeof r.exit_chapter === 'number' ? r.exit_chapter : r.appear_end;
+        if (s.chapter < r.appear_start || (typeof maxCh === 'number' && s.chapter > maxCh)) {
+          errors.push({ code: 'RHYTHM_ARC_OUT_OF_SPAN', path: itemPath('character_timeline', r, i) + '.arc_stages[' + j + '].chapter', message: '弧光章 ' + s.chapter + ' 不在出场区间 [' + r.appear_start + ', ' + maxCh + ']', hint: null });
+        }
+      }
+    }
+    const arcs = (r.arc_stages || []).map(s => s.chapter).filter(n => typeof n === 'number');
+    for (let k = 1; k < arcs.length; k++) {
+      if (arcs[k] < arcs[k - 1]) {
+        errors.push({ code: 'RHYTHM_TIMING', path: itemPath('character_timeline', r, i) + '.arc_stages', message: '弧光阶段章节顺序错乱：' + arcs.join(' → '), hint: null });
+        break;
+      }
+    }
+  }
+
+  for (const [i, r] of (timeline.conflict_timeline || []).entries()) {
+    check(r.conflict_id, idSets.conflict, '冲突', 'conflict_timeline[' + i + '].conflict_id');
+    const escs = (r.escalation_nodes || []).map(n => n.chapter).filter(n => typeof n === 'number');
+    for (let k = 1; k < escs.length; k++) {
+      if (escs[k] < escs[k - 1]) {
+        errors.push({ code: 'RHYTHM_TIMING', path: itemPath('conflict_timeline', r, i) + '.escalation_nodes', message: '冲突升级节点章节应递增：' + escs.join(' → '), hint: null });
+        break;
+      }
+    }
+    if (escs.length && typeof r.resolution_chapter === 'number') {
+      if (r.resolution_chapter < escs[escs.length - 1]) {
+        errors.push({ code: 'RHYTHM_TIMING', path: itemPath('conflict_timeline', r, i) + '.resolution_chapter', message: '收束章 ' + r.resolution_chapter + ' 早于最后升级节点 ' + escs[escs.length - 1], hint: null });
+      }
+    }
+    for (const [j, g] of (r.info_gaps || []).entries()) {
+      if (typeof g.created === 'number' && typeof g.resolved === 'number' && g.created >= g.resolved) {
+        errors.push({ code: 'RHYTHM_TIMING', path: itemPath('conflict_timeline', r, i) + '.info_gaps[' + j + ']', message: '信息差产生章 ' + g.created + ' 应早于消除章 ' + g.resolved, hint: null });
+      }
+    }
+  }
+
+  for (const [i, r] of (timeline.foreshadow_timeline || []).entries()) {
+    check(r.fs_id, idSets.foreshadow, '伏笔', 'foreshadow_timeline[' + i + '].fs_id');
+    if (typeof r.buried_chapter === 'number' && typeof r.recovered_chapter === 'number' && r.buried_chapter >= r.recovered_chapter) {
+      errors.push({ code: 'RHYTHM_TIMING', path: itemPath('foreshadow_timeline', r, i), message: '埋设章 ' + r.buried_chapter + ' 应早于回收章 ' + r.recovered_chapter, hint: null });
+    }
+  }
+
+  for (const [i, r] of (timeline.climax_timeline || []).entries()) {
+    check(r.climax_id, idSets.climax, '高潮', 'climax_timeline[' + i + '].climax_id');
+  }
+
+  for (const [i, r] of (timeline.pleasure_timeline || []).entries()) {
+    check(r.pleasure_id, idSets.pleasure, '爽点', 'pleasure_timeline[' + i + '].pleasure_id');
+  }
+
+  for (const [i, r] of (timeline.main_line_timeline || []).entries()) {
+    check(r.main_id, idSets.main_line, '主线', 'main_line_timeline[' + i + '].main_id');
+  }
+
+  for (const [i, r] of (timeline.branch_timeline || []).entries()) {
+    check(r.branch_id, idSets.branch, '支线', 'branch_timeline[' + i + '].branch_id');
+    if (typeof r.start === 'number' && typeof r.turning === 'number' && typeof r.resolution === 'number') {
+      if (!(r.start <= r.turning && r.turning <= r.resolution)) {
+        errors.push({ code: 'RHYTHM_TIMING', path: itemPath('branch_timeline', r, i), message: '支线章节顺序错乱：start=' + r.start + ', turning=' + r.turning + ', resolution=' + r.resolution, hint: null });
+      }
+    }
+    for (const [j, iw] of (r.interweaves || []).entries()) {
+      if (typeof iw.chapter === 'number' && typeof r.start === 'number' && typeof r.resolution === 'number') {
+        if (iw.chapter < r.start || iw.chapter > r.resolution) {
+          errors.push({ code: 'RHYTHM_TIMING', path: itemPath('branch_timeline', r, i) + '.interweaves[' + j + '].chapter', message: '交织点章 ' + iw.chapter + ' 不在支线区间 [' + r.start + ', ' + r.resolution + ']', hint: null });
+        }
+      }
+    }
+  }
+
+  for (const [i, r] of (timeline.location_timeline || []).entries()) {
+    check(r.loc_id, idSets.location, '地点', 'location_timeline[' + i + '].loc_id');
+    if (typeof r.appear_start === 'number' && typeof r.appear_end === 'number' && r.appear_start > r.appear_end) {
+      errors.push({ code: 'RHYTHM_CHAP_ORDER', path: itemPath('location_timeline', r, i), message: 'appear_start(' + r.appear_start + ') > appear_end(' + r.appear_end + ')', hint: null });
+    }
+  }
+
+  for (const [i, r] of (timeline.item_timeline || []).entries()) {
+    check(r.item_id, idSets.item, '道具', 'item_timeline[' + i + '].item_id');
+    if (typeof r.appear_start === 'number' && typeof r.appear_end === 'number' && r.appear_start > r.appear_end) {
+      errors.push({ code: 'RHYTHM_CHAP_ORDER', path: itemPath('item_timeline', r, i), message: 'appear_start(' + r.appear_start + ') > appear_end(' + r.appear_end + ')', hint: null });
+    }
+  }
+
+  for (const [i, r] of (timeline.ending_timeline || []).entries()) {
+    check(r.ending_id, idSets.ending, '结局', 'ending_timeline[' + i + '].ending_id');
+    for (const [j, fr] of (r.foreshadow_recovery || []).entries()) {
+      check(fr.fs_id, idSets.foreshadow, '伏笔', 'ending_timeline[' + i + '].foreshadow_recovery[' + j + '].fs_id');
+    }
+  }
+}
+
+// ============================================================
+// 章节规划一致性
+// ============================================================
+function checkChapterPlan(chapters, T, hierarchy, volumeRatios, errors, warnings) {
+  const chs = (chapters || []).map(c => c.ch);
+  const seen = new Set();
+  const dup = [];
+  for (const ch of chs) {
+    if (seen.has(ch)) dup.push(ch);
+    seen.add(ch);
+  }
+  if (dup.length) {
+    errors.push({ code: 'RHYTHM_CHAPTER_DUP', path: 'chapters', message: '章节号重复：' + [...new Set(dup)].join(', '), hint: null });
+  }
+
+  const missing = [];
+  for (let ch = 1; ch <= T; ch++) {
+    if (!seen.has(ch)) missing.push(ch);
+  }
+  if (missing.length) {
+    errors.push({
+      code: 'RHYTHM_CHAPTER_MISSING',
+      path: 'chapters',
+      message: '缺少章节：' + missing.slice(0, 20).join(', ') + (missing.length > 20 ? ' 等 ' + missing.length + ' 章' : ''),
+      hint: null
+    });
+  }
+
+  const validVols = new Set((hierarchy?.volumes || []).map(v => v.id));
+  if (volumeRatios && volumeRatios.length) {
+    for (const x of volumeRatios) validVols.add(x.volume_id);
+  }
+  for (const [i, c] of (chapters || []).entries()) {
+    if (c.volume && validVols.size > 0 && !validVols.has(c.volume)) {
+      errors.push({ code: 'RHYTHM_REF_MISSING', path: 'chapters[' + i + '].volume', message: '卷 ' + c.volume + ' 不存在于骨架层级', hint: null });
+    }
+  }
+
+  const volActMap = new Map();
+  for (const a of (hierarchy?.acts || [])) {
+    if (a.volume && typeof a.act_index === 'number') {
+      if (!volActMap.has(a.volume)) volActMap.set(a.volume, new Set());
+      volActMap.get(a.volume).add(a.act_index);
+    }
+  }
+  for (const [i, c] of (chapters || []).entries()) {
+    if (!c.volume || typeof c.act !== 'number') continue;
+    const actsInVol = volActMap.get(c.volume);
+    if (actsInVol && actsInVol.size > 0 && !actsInVol.has(c.act)) {
+      errors.push({
+        code: 'RHYTHM_ACT_INVALID',
+        path: 'chapters[' + i + '].act',
+        message: '第 ' + c.ch + ' 章 act=' + c.act + ' 不在卷 ' + c.volume + ' 的幕集合中（该卷幕为 ' + [...actsInVol].sort((a,b)=>a-b).join(', ') + '）',
+        hint: null
+      });
+    }
+  }
+
+  if (volumeRatios && volumeRatios.length && T > 0) {
+    const byVolume = new Map();
+    for (const c of chapters || []) {
+      if (c.volume) byVolume.set(c.volume, (byVolume.get(c.volume) || 0) + 1);
+    }
+    for (const vr of volumeRatios) {
+      const expected = Math.round(T * vr.chapter_ratio);
+      const actual = byVolume.get(vr.volume_id) || 0;
+      if (Math.abs(actual - expected) > 1) {
+        warnings.push({
+          code: 'RHYTHM_VOLUME_DIST',
+          path: 'chapters',
+          message: '卷 ' + vr.volume_id + ' 期望约 ' + expected + ' 章，实际 ' + actual + ' 章',
+          hint: 'volume_ratio=' + vr.chapter_ratio + '，T=' + T
+        });
+      }
+    }
+  }
+}
+
+// ============================================================
+// 布局吻合度
+// ============================================================
+function checkLayoutMatch(timeline, rhythmData, frameworkData, errors) {
+  const keyNodeChs = new Set();
+  for (const r of timeline.main_line_timeline || []) {
+    for (const n of r.key_nodes || []) {
+      if (typeof n.chapter === 'number') keyNodeChs.add(n.chapter);
+    }
+  }
+  if (typeof rhythmData.main_progress_chapter_count === 'number' && keyNodeChs.size !== rhythmData.main_progress_chapter_count) {
+    errors.push({
+      code: 'RHYTHM_NODES_COUNT',
+      path: 'main_line_timeline',
+      message: '主线 key_nodes 实际章数 ' + keyNodeChs.size + ' ≠ main_progress_chapter_count ' + rhythmData.main_progress_chapter_count,
+      hint: null
+    });
+  }
+
+  let actualBranchTotal = 0;
+  for (const r of timeline.branch_timeline || []) {
+    if (typeof r.start === 'number' && typeof r.resolution === 'number') {
+      actualBranchTotal += r.resolution - r.start + 1;
+    }
+  }
+  if (typeof rhythmData.branch_chapter_total === 'number' && actualBranchTotal !== rhythmData.branch_chapter_total) {
+    errors.push({
+      code: 'RHYTHM_BRANCH_TOTAL',
+      path: 'branch_timeline',
+      message: '支线实际章数之和 ' + actualBranchTotal + ' ≠ branch_chapter_total ' + rhythmData.branch_chapter_total,
+      hint: null
+    });
+  }
+
+  const branchOwner = new Map();
+  for (const r of timeline.branch_timeline || []) {
+    if (typeof r.start !== 'number' || typeof r.resolution !== 'number') continue;
+    for (let ch = r.start; ch <= r.resolution; ch++) {
+      if (branchOwner.has(ch)) {
+        errors.push({
+          code: 'RHYTHM_BRANCH_OVERLAP',
+          path: 'branch_timeline',
+          message: '第 ' + ch + ' 章同时属于支线 ' + branchOwner.get(ch) + ' 和 ' + r.branch_id,
+          hint: '支线章节不得重叠'
+        });
+      } else {
+        branchOwner.set(ch, r.branch_id);
+      }
+    }
+  }
+
+  const branchChs = new Set(branchOwner.keys());
+  const inter = [...branchChs].filter(ch => keyNodeChs.has(ch));
+  if (typeof rhythmData.overlap_chapter_count === 'number' && inter.length !== rhythmData.overlap_chapter_count) {
+    errors.push({
+      code: 'RHYTHM_OVERLAP_COUNT',
+      path: '节奏参数.overlap_chapter_count',
+      message: '实际重叠章数 ' + inter.length + '（支线章集 ∩ 主线 key_node 章集）≠ overlap_chapter_count ' + rhythmData.overlap_chapter_count,
+      hint: null
+    });
+  }
+
+  const dupChs = [];
+  const nodeChList = [];
+  for (const r of timeline.main_line_timeline || []) {
+    for (const n of r.key_nodes || []) {
+      if (typeof n.chapter === 'number') nodeChList.push(n.chapter);
+    }
+  }
+  const nodeSeen = new Set();
+  for (const ch of nodeChList) {
+    if (nodeSeen.has(ch)) dupChs.push(ch);
+    nodeSeen.add(ch);
+  }
+  if (dupChs.length) {
+    errors.push({ code: 'RHYTHM_NODE_DUP', path: 'main_line_timeline', message: '主线 key_node 章节重复：' + [...new Set(dupChs)].join(', '), hint: null });
+  }
+}
+
+// ============================================================
+// 覆盖性
+// ============================================================
+function checkCoverage(timeline, skeleton, errors, warnings) {
+  const keyNodeChs = new Set();
+  for (const r of timeline.main_line_timeline || []) {
+    for (const n of r.key_nodes || []) {
+      if (typeof n.chapter === 'number') keyNodeChs.add(n.chapter);
+    }
+  }
+
+  if (keyNodeChs.size === 0) {
+    warnings.push({
+      code: 'RHYTHM_COVERAGE_SKIPPED',
+      path: 'main_line_timeline',
+      message: '主线 key_nodes 为空，结局覆盖检查跳过（RHYTHM_NODES_COUNT 会报 error）',
+      hint: null
+    });
+    return;
+  }
+
+  for (const r of timeline.ending_timeline || []) {
+    if (typeof r.chapter === 'number' && !keyNodeChs.has(r.chapter)) {
+      errors.push({
+        code: 'RHYTHM_COVERAGE',
+        path: 'ending_timeline.' + r.ending_id + '.chapter',
+        message: '结局 ' + r.ending_id + ' 的章节 ' + r.chapter + ' 不在主线 key_nodes 中',
+        hint: '结局章节必须是主线关键节点中的一章'
+      });
+    }
+  }
+
+  const largeFs = new Set();
+  for (const fsItem of (skeleton.entity?.foreshadows || [])) {
+    if (fsItem.type === LARGE_FORESHADOW_TYPE && fsItem.id) largeFs.add(fsItem.id);
+  }
+  if (largeFs.size === 0) return;
+
+  const bookEndingIds = new Set();
+  for (const e of (skeleton.entity?.endings || [])) {
+    if (e.level === BOOK_ENDING_LEVEL && e.id) bookEndingIds.add(e.id);
+  }
+  if (bookEndingIds.size === 0) return;
+
+  const recovered = new Set();
+  for (const r of timeline.ending_timeline || []) {
+    if (!bookEndingIds.has(r.ending_id)) continue;
+    for (const fr of r.foreshadow_recovery || []) {
+      if (fr.fs_id) recovered.add(fr.fs_id);
+    }
+  }
+  const missing = [...largeFs].filter(id => !recovered.has(id));
+  if (missing.length) {
+    errors.push({
+      code: 'RHYTHM_LARGE_FS_NOT_RECOVERED',
+      path: 'ending_timeline',
+      message: '全书级结局缺少 ' + missing.length + ' 个大伏笔的回收记录：' + missing.join(', '),
+      hint: '所有大伏笔必须在全书级结局的 foreshadow_recovery 中出现'
+    });
+  }
+}
+
+// ============================================================
+// 钩子检查
+// ============================================================
+function checkHooks(timeline, rhythmData, frameworkData, T, outlines, errors, warnings) {
+  const hooks = timeline.hook_timeline || [];
+
+  const isMin = rhythmData.chapter_hook_rate?.is_minimum;
+  const rate = rhythmData.chapter_hook_rate?.rate;
+  if (isMin === true && typeof rate === 'number' && typeof T === 'number') {
+    const minHooks = Math.ceil(T * rate);
+    if (hooks.length < minHooks) {
+      errors.push({
+        code: 'RHYTHM_HOOK_MIN',
+        path: 'hook_timeline',
+        message: '钩子数 ' + hooks.length + ' < 框架下限 ceil(' + T + '×' + rate + ')=' + minHooks,
+        hint: null
+      });
+    }
+  }
+
+  // 高潮期豁免章：emotion_phase='释放' 且 hook_strength='强'
+  // 来自 章节细纲.json 的 outlines
+  const climaxExemptChapters = new Set();
+  if (Array.isArray(outlines)) {
+    for (const o of outlines) {
+      if (typeof o.ch === 'number' && o.emotion_phase === '释放' && o.hook_strength === '强') {
+        climaxExemptChapters.add(o.ch);
+      }
+    }
+  }
+
+  const sorted = [...hooks].sort((a, b) => a.ch - b.ch);
+  let consecutiveSame = 1;
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i].ch === sorted[i - 1].ch + 1 && sorted[i].hook_tail === sorted[i - 1].hook_tail) {
+      // 连续章都是高潮豁免章则跳过 RHYTHM_HOOK_DUP 错误
+      if (!climaxExemptChapters.has(sorted[i].ch) || !climaxExemptChapters.has(sorted[i - 1].ch)) {
+        consecutiveSame++;
+      } else {
+        consecutiveSame = 1;  // 豁免章打断连续计数
+        continue;
+      }
+    } else {
+      consecutiveSame = 1;
+    }
+    if (consecutiveSame === 2) {
+      warnings.push({
+        code: 'RHYTHM_HOOK_DUP_WARN',
+        path: 'hook_timeline.' + sorted[i].ch,
+        message: '第 ' + sorted[i - 1].ch + '-' + sorted[i].ch + ' 章章尾钩子同为 "' + sorted[i].hook_tail + '"',
+        hint: '建议不同式；若高潮期允许同类，请在章节细纲中注明'
+      });
+    } else if (consecutiveSame >= 3) {
+      errors.push({
+        code: 'RHYTHM_HOOK_DUP',
+        path: 'hook_timeline.' + sorted[i].ch,
+        message: '连续 ' + consecutiveSame + ' 章章尾钩子同为 "' + sorted[i].hook_tail + '"',
+        hint: '连续 3 章以上同类钩子读者会疲劳'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 章节细纲字数检查
+// ============================================================
+function checkWordTarget(outlines, frameworkData, warnings) {
+  const avg = frameworkData?.capacity?.avg_words_per_chapter;
+  if (typeof avg !== 'number' || avg <= 0) return;
+  const tolLow = Math.round(avg * 0.8);
+  const tolHigh = Math.round(avg * 1.2);
+  for (const [i, o] of (outlines || []).entries()) {
+    if (typeof o.word_target === 'number' && (o.word_target < tolLow || o.word_target > tolHigh)) {
+      warnings.push({
+        code: 'RHYTHM_WORD_TARGET',
+        // outlines 只装重点章，下标与章号不成比例 → 用章号定位
+        path: 'outlines[ch=' + (o && o.ch !== undefined ? o.ch : i) + '].word_target',
+        message: '章节 ' + o.ch + ' 字数目标 ' + o.word_target + ' 偏离基准 ' + avg + ' 超过 ±20% [' + tolLow + ', ' + tolHigh + ']',
+        hint: null
+      });
+    }
+  }
+}
+
+// ============================================================
+// 图：孤立章节检查
+// ============================================================
+function checkChapterGraph(timeline, T, errors) {
+  const g = new SimpleGraph();
+  for (let ch = 1; ch <= T; ch++) {
+    g.addNode('ch:' + ch, { type: 'chapter' });
+  }
+
+  const addEdge = (fromCh, rel) => {
+    const key = 'ch:' + fromCh;
+    if (g.hasNode(key)) {
+      g.addEdgeWithKey(key + '--' + rel, key, key, { relation: rel });
+    }
+  };
+
+  for (const r of timeline.character_timeline || []) {
+    if (typeof r.appear_start === 'number') addEdge(r.appear_start, 'character_appears');
+    if (typeof r.appear_end === 'number') addEdge(r.appear_end, 'character_appears');
+    for (const s of r.arc_stages || []) if (typeof s.chapter === 'number') addEdge(s.chapter, 'arc');
+  }
+  for (const r of timeline.foreshadow_timeline || []) {
+    if (typeof r.buried_chapter === 'number') addEdge(r.buried_chapter, 'fs_buried');
+    if (typeof r.recovered_chapter === 'number') addEdge(r.recovered_chapter, 'fs_recovered');
+  }
+  for (const r of timeline.conflict_timeline || []) {
+    for (const n of r.escalation_nodes || []) if (typeof n.chapter === 'number') addEdge(n.chapter, 'conflict_esc');
+    if (typeof r.resolution_chapter === 'number') addEdge(r.resolution_chapter, 'conflict_resolved');
+  }
+  for (const r of timeline.climax_timeline || []) if (typeof r.chapter === 'number') addEdge(r.chapter, 'climax');
+  for (const r of timeline.pleasure_timeline || []) if (typeof r.chapter === 'number') addEdge(r.chapter, 'pleasure');
+  for (const r of timeline.main_line_timeline || []) for (const n of r.key_nodes || []) if (typeof n.chapter === 'number') addEdge(n.chapter, 'main_node');
+  for (const r of timeline.branch_timeline || []) {
+    if (typeof r.start === 'number') addEdge(r.start, 'branch_start');
+    if (typeof r.resolution === 'number') addEdge(r.resolution, 'branch_end');
+  }
+  for (const r of timeline.ending_timeline || []) if (typeof r.chapter === 'number') addEdge(r.chapter, 'ending');
+  // 钩子章节也算引用（非重点章可只有钩子无其他引用）
+  for (const h of timeline.hook_timeline || []) {
+    if (typeof h.ch === 'number') addEdge(h.ch, 'hook');
+  }
+
+  const isolated = getIsolatedNodes(g, []);
+  for (const n of isolated) {
+    if (n.type === 'chapter') {
+      const ch = n.key.replace('ch:', '');
+      errors.push({
+        code: 'RHYTHM_CHAPTER_UNREF',
+        path: n.key,
+        message: '第 ' + ch + ' 章没有任何事件/角色/伏笔/钩子引用',
+        hint: null
+      });
+    }
+  }
+}
+
+// ============================================================
+// derivations 检查
+// ============================================================
+function checkRhythmDerivations(rhythmData, constraints, errors, warnings) {
+  const der = rhythmData.derivations || {};
+  const constraintKeys = new Set(Object.keys(constraints));
+  const derKeys = new Set(Object.keys(der));
+
+  for (const k of constraintKeys) {
+    if (!derKeys.has(k)) {
+      warnings.push({
+        code: 'RHYTHM_DERIVATION_MISSING',
+        path: 'derivations.' + k,
+        message: '建议为约束 "' + k + '" 提供 note 说明',
+        hint: null
+      });
+    }
+  }
+
+  for (const k of derKeys) {
+    if (!constraintKeys.has(k)) {
+      warnings.push({
+        code: 'RHYTHM_DERIVATION_EXTRA',
+        path: 'derivations.' + k,
+        message: '多余的推导记录（formulas-rhythm.json 无约束 ' + k + '）',
+        hint: null
+      });
+    }
+  }
+}
+
+// ============================================================
+// md 生成 + stage-status（结构化 markdown，零反引号）
+// ============================================================
+const BT = String.fromCharCode(96);
+const BT3 = BT + BT + BT;
+
+function jsonToMd(data, fileType) {
+  // rhythm 阶段：按 RHYTHM_DISPATCH 把顶层数组分别渲染为 H2 分组
+  const body = renderRhythmByFileType(data, fileType);
+  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;
+  for (const f of fs.readdirSync(stageDir)) {
+    // 排除 .stage-status.json：它是校验状态记账文件，不是业务数据
+    if (!f.endsWith('.json') || f.startsWith('.')) continue;
+    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) {
+  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 };
+  } 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 loadUpstream(upstreamDirs) {
+  const result = { framework: null, entity: null, hierarchy: null, flesh: {} };
+  const tryRead = (dir, name) => {
+    const r = readJson(path.join(dir, name));
+    return r.data || null;
+  };
+  for (const dir of upstreamDirs) {
+    if (!result.framework) result.framework = tryRead(dir, '框架.json');
+    if (!result.entity) result.entity = tryRead(dir, '实体.json');
+    if (!result.hierarchy) result.hierarchy = tryRead(dir, '层级.json');
+    if (!result.flesh.characters) result.flesh.characters = tryRead(dir, '角色.json');
+    if (!result.flesh.conflicts) result.flesh.conflicts = tryRead(dir, '冲突.json');
+    if (!result.flesh.factions) result.flesh.factions = tryRead(dir, '势力.json');
+    if (!result.flesh.locations) result.flesh.locations = tryRead(dir, '地点.json');
+    if (!result.flesh.endings) result.flesh.endings = tryRead(dir, '结局.json');
+    if (!result.flesh.items) result.flesh.items = tryRead(dir, '关键道具.json');
+    if (!result.flesh.plot) result.flesh.plot = tryRead(dir, '剧情.json');
+  }
+  return result;
+}
+
+function checkUpstreamReady(skeleton) {
+  if (!skeleton.framework) return '骨架 框架.json 读不到';
+  if (!skeleton.entity) return '骨架 实体.json 读不到';
+  if (typeof skeleton.framework.capacity?.target_chapters !== 'number') return '骨架 框架.json 缺 capacity.target_chapters';
+  if (skeleton.framework.capacity.target_chapters <= 0) return '骨架 框架.json capacity.target_chapters 必须 > 0';
+  return null;
+}
+
+// 阶段门禁：骨架与血肉两个上游都必须已通过全量校验
+// （此前这个判定只写在提示词里，脚本从不读上游状态）
+function checkUpstreamGates(upstreamDirs) {
+  const dirs = upstreamDirs || [];
+  const skeletonDir = dirs.find(d => fs.existsSync(path.join(d, '实体.json')));
+  const fleshDir = dirs.find(d => fs.existsSync(path.join(d, '角色.json')));
+  for (const pair of [['骨架', skeletonDir], ['血肉', fleshDir]]) {
+    const name = pair[0], dir = pair[1];
+    if (!dir) return name + ' 上游目录未找到（--upstream 需同时包含骨架目录与血肉目录）';
+    const g = readStageGate(dir);
+    if (!g.ok) return name + '：' + g.reason;
+  }
+  return null;
+}
+
+// P2-6：统一的上游数量检查
+function checkUpstreamCount(upstream, file) {
+  if (!upstream || upstream.length < MIN_UPSTREAM_COUNT) {
+    return emit(2, file, [{
+      code: 'UPSTREAM_MISSING',
+      path: '',
+      message: '节奏阶段必须提供 --upstream=<骨架目录>,<血肉目录>（至少 ' + MIN_UPSTREAM_COUNT + ' 个目录）',
+      hint: '实际收到 ' + (upstream ? upstream.length : 0) + ' 个上游目录'
+    }], []);
+  }
+  return null;
+}
+
+// ============================================================
+// 单文件模式
+// ============================================================
+function validateSingle(args) {
+  const input = args.input;
+  const template = args.template;
+  const file = args.file;
+
+  // P2-6
+  const upErr = checkUpstreamCount(args.upstream, file);
+  if (upErr) return upErr;
+
+  const gateErr = checkUpstreamGates(args.upstream);
+  if (gateErr) {
+    return emit(2, file, [{ code: 'UPSTREAM_NOT_PASSED', path: '', message: gateErr, hint: '请先对上游阶段执行全量校验并通过' }], []);
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, file, [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+  assertBusinessConstants(gl, warnings);
+
+  const fm = loadFormulas();
+  if (fm.error) return emit(2, file, [{ code: 'FORMULAS_LOAD', path: '', message: fm.error, hint: null }], []);
+
+  const inputRes = readJson(input);
+  if (inputRes.error) return emit(2, file, [{ code: 'READ', path: input, message: inputRes.error, hint: null }], []);
+
+  const tplRes = readJson(template);
+  if (tplRes.error) return emit(2, file, [{ code: 'TEMPLATE', path: template, message: tplRes.error, hint: null }], []);
+
+  const skeleton = loadUpstream(args.upstream);
+  const notReady = checkUpstreamReady(skeleton);
+  if (notReady) return emit(2, file, [{ code: 'UPSTREAM_NOT_READY', path: '', message: notReady, hint: null }], []);
+
+  const T = skeleton.framework.capacity.target_chapters;
+  const idSets = buildIdSets(skeleton, skeleton.flesh);
+  const data = inputRes.data;
+
+  safeCheck('validateNode', () => validateNode(data, tplRes.data.structure || {}, '', gl.enums, errors), errors);
+  safeCheck('charsetAndForbiddenCheck', () => charsetAndForbiddenCheck(data, errors), errors);
+  safeCheck('checkChapterRanges', () => checkChapterRanges(data, T, gl.chapterScalarFields, errors), errors);
+
+  if (file === '章节规划') {
+    safeCheck('checkChapterPlan', () => checkChapterPlan(data.chapters, T, skeleton.hierarchy, skeleton.framework.volume_ratio, errors, warnings), errors);
+  } else if (file === '时序映射') {
+    safeCheck('checkTimelineIntegrity', () => checkTimelineIntegrity(data, idSets, errors), errors);
+  } else if (file === '节奏参数') {
+    safeCheck('checkRhythmInfeasible', () => checkRhythmInfeasible(data, skeleton.framework, fm.constraints, errors), errors);
+    safeCheck('checkRhythmDerivations', () => checkRhythmDerivations(data, fm.constraints, errors, warnings), errors);
+  } else if (file === '章节细纲') {
+    safeCheck('checkWordTarget', () => checkWordTarget(data.outlines, skeleton.framework, warnings), 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);
+}
+
+// ============================================================
+// 全量模式
+// ============================================================
+function validateAll(args) {
+  const stageDir = args['stage-dir'];
+  const templateDir = args['template-dir'];
+
+  // P2-6
+  const upErr = checkUpstreamCount(args.upstream, 'ALL');
+  if (upErr) return upErr;
+
+  const gateErr = checkUpstreamGates(args.upstream);
+  if (gateErr) {
+    return emit(2, 'ALL', [{ code: 'UPSTREAM_NOT_PASSED', path: '', message: gateErr, hint: '请先对上游阶段执行全量校验并通过' }], []);
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, 'ALL', [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+  assertBusinessConstants(gl, warnings);
+
+  const fm = loadFormulas();
+  if (fm.error) return emit(2, 'ALL', [{ code: 'FORMULAS_LOAD', path: '', message: fm.error, hint: null }], []);
+
+  if (!fs.existsSync(stageDir)) {
+    return emit(2, 'ALL', [{ code: 'ARG', path: stageDir, message: '阶段目录不存在', hint: null }], []);
+  }
+
+  const skeleton = loadUpstream(args.upstream);
+  const notReady = checkUpstreamReady(skeleton);
+  if (notReady) return emit(2, 'ALL', [{ code: 'UPSTREAM_NOT_READY', path: '', message: notReady, hint: null }], []);
+
+  const T = skeleton.framework.capacity.target_chapters;
+  const idSets = buildIdSets(skeleton, skeleton.flesh);
+
+  const FILES = [
+    { type: '章节规划', name: '章节规划.json', tpl: '章节规划模板.json' },
+    { type: '时序映射', name: '时序映射.json', tpl: '时序映射模板.json' },
+    { type: '节奏参数', name: '节奏参数.json', tpl: '节奏参数模板.json' },
+    { type: '章节细纲', name: '章节细纲.json', tpl: '章节细纲模板.json' }
+  ];
+
+  const loaded = {};
+
+  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('validateNode', () => validateNode(data, tplRes.data.structure || {}, '', gl.enums, errors), errors);
+    safeCheck('charsetAndForbiddenCheck', () => charsetAndForbiddenCheck(data, errors), errors);
+    safeCheck('checkChapterRanges', () => checkChapterRanges(data, T, gl.chapterScalarFields, errors), errors);
+
+    if (f.type === '章节规划') {
+      safeCheck('checkChapterPlan', () => checkChapterPlan(data.chapters, T, skeleton.hierarchy, skeleton.framework.volume_ratio, errors, warnings), errors);
+    } else if (f.type === '时序映射') {
+      safeCheck('checkTimelineIntegrity', () => checkTimelineIntegrity(data, idSets, errors), errors);
+    } else if (f.type === '节奏参数') {
+      safeCheck('checkRhythmInfeasible', () => checkRhythmInfeasible(data, skeleton.framework, fm.constraints, errors), errors);
+      safeCheck('checkRhythmDerivations', () => checkRhythmDerivations(data, fm.constraints, errors, warnings), errors);
+    } else if (f.type === '章节细纲') {
+      safeCheck('checkWordTarget', () => checkWordTarget(data.outlines, skeleton.framework, warnings), errors);
+    }
+  }
+
+  if (loaded['时序映射']) {
+    if (loaded['节奏参数']) {
+      safeCheck('checkLayoutMatch', () => checkLayoutMatch(loaded['时序映射'], loaded['节奏参数'], skeleton.framework, errors), errors);
+    }
+    safeCheck('checkCoverage', () => checkCoverage(loaded['时序映射'], skeleton, errors, warnings), errors);
+    if (loaded['节奏参数']) {
+      // 高潮期豁免：读章节细纲的 emotion_phase，emotion_phase='释放' 且 hook_strength='强' 的章视为高潮豁免章
+      const outlines = loaded['章节细纲'] && loaded['章节细纲'].outlines ? loaded['章节细纲'].outlines : null;
+      safeCheck('checkHooks', () => checkHooks(loaded['时序映射'], loaded['节奏参数'], skeleton.framework, T, outlines, errors, warnings), errors);
+    }
+    safeCheck('checkChapterGraph', () => checkChapterGraph(loaded['时序映射'], T, errors), errors);
+  }
+
+  updateStageStatus(stageDir, 'ALL', errors.length === 0 ? 0 : 1);
+  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.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();