@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

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

@@ -0,0 +1,1312 @@
+#!/usr/bin/env node
+/**
+ * 血肉阶段校验脚本 v1.2
+ * 源码中零反引号，避免 markdown 渲染问题。
+ *
+ * v1.2 变更（修复批次 P0-3 / P2-10）：
+ * - P0-3：completenessCheck 的 directChecks 用"文件类型"作 fleshData 的 key
+ *   （原版用 'characters' 等数组名作 key，fleshData 里实际是 '角色' 等文件类型，
+ *    导致 5 类直接映射实体的 FLESH_INCOMPLETE 全部误报刷屏）
+ * - P2-10：itemRefCheck 先校验 id 存在于骨架，再加入 fleshItemIds
+ *   （原版先加入后校验，非法 id 会触发多余的 FLESH_DETAILS_ORPHAN）
+ *
+ * 保留 v1.1 的 P2-3 修复：
+ * - FLESH_GROUP_CATEGORY_MISMATCH / FLESH_FREETEXT_CHAPTER_REF / completenessCheck 扩展
+ *
+ * 用法：
+ *   单文件：node flesh-validate.js --input=<json> --template=<模板> --file=<类型> --upstream=<骨架目录>
+ *   全量：  node flesh-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 { parseGlossaryChecked, mdEscape, renderObject, renderArray, renderFleshByFileType, readStageGate, safeCheck, RELATION_KIND_META, suggestClosestName } from './graph-utils.js';
+import { runContentQualityChecks, collectEnumLeaves } from './content-quality.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 加载
+// ============================================================
+function loadGlossary() {
+  const r = readText(path.join(__dirname, 'glossary.md'));
+  if (r.error) return { error: 'glossary.md 读取失败: ' + r.error };
+  return parseGlossaryChecked(r.data);
+}
+
+function loadSkeleton(upstreamDirs) {
+  const result = { entity: null, framework: null, hierarchy: null, relations: null };
+  for (const dir of upstreamDirs) {
+    const entRes = readJson(path.join(dir, '实体.json'));
+    if (entRes.data) result.entity = entRes.data;
+    const fwRes = readJson(path.join(dir, '框架.json'));
+    if (fwRes.data) result.framework = fwRes.data;
+    const hiRes = readJson(path.join(dir, '层级.json'));
+    if (hiRes.data) result.hierarchy = hiRes.data;
+    const relRes = readJson(path.join(dir, '关系.json'));
+    if (relRes.data) result.relations = relRes.data;
+  }
+  return result;
+}
+
+// ============================================================
+// 自环关系检查
+// ============================================================
+// 骨架阶段的 关系.json 有 NO_SELF_RELATION 拦截自环，血肉阶段此前没有对等检查，
+// 于是"角色把自己列成自己的关系对象"可以一路写进角色档案。
+function fleshSelfRelationCheck(data, fileType, errors) {
+  const selfCheck = (ownerName, targetName, path, label) => {
+    if (!targetName || !ownerName) return;
+    if (targetName === ownerName) {
+      errors.push({
+        code: 'FLESH_SELF_RELATION',
+        path: path,
+        message: label + ' "' + ownerName + '" 把自身列为关系对象',
+        hint: '自环关系无意义；角色的自我矛盾请写进 description / core_flaw'
+      });
+    }
+  };
+
+  if (fileType === '角色') {
+    for (const [i, c] of (data.characters || []).entries()) {
+      if (!c) continue;
+      const aliases = new Set([c.id, c.name].filter(Boolean));
+      for (const [j, r] of (c.relationships || []).entries()) {
+        if (!r) continue;
+        if (aliases.has(r.target_name)) {
+          selfCheck(c.name || c.id, r.target_name, 'characters[' + i + '].relationships[' + j + '].target_name', '角色');
+        }
+      }
+    }
+  } else if (fileType === '势力') {
+    for (const [i, f] of (data.factions || []).entries()) {
+      if (!f) continue;
+      const aliases = new Set([f.id, f.name].filter(Boolean));
+      for (const [j, r] of (f.relations || []).entries()) {
+        if (!r) continue;
+        if (aliases.has(r.target_name)) {
+          selfCheck(f.name || f.id, r.target_name, 'factions[' + i + '].relations[' + j + '].target_name', '势力');
+        }
+      }
+    }
+  }
+}
+
+// ============================================================
+// 个性化特征与关系阶段检查
+// ============================================================
+// `traits` 是角色的"独有特征"，不是性格形容词堆砌。
+// 模板只能要求字段存在，数量和重复要靠这里兜住。
+function traitsAndChangesCheck(data, fileType, errors, warnings) {
+  const checkTraits = (item, path, label, min, max) => {
+    if (!item || item.traits === undefined) {
+      if (label === '角色') {
+        errors.push({
+          code: 'FLESH_TRAITS_MISSING',
+          path: path + '.traits',
+          message: '角色缺少 traits（独有特征/习惯）',
+          hint: '写 3-5 条能直接写进场景的具体特征，例如"紧张时反复摸腕环"'
+        });
+      }
+      return;
+    }
+    if (!Array.isArray(item.traits)) return; // TYPE 已报
+    const values = item.traits.map((x) => (typeof x === 'string' ? x.trim() : '')).filter(Boolean);
+    if (values.length < min || values.length > max) {
+      errors.push({
+        code: 'FLESH_TRAITS_COUNT',
+        path: path + '.traits',
+        message: label + '的 traits 应为 ' + min + '-' + max + ' 条，实际 ' + values.length + ' 条',
+        hint: '特征要少而准：每条都能在场景里演出来，不要用"善良""勇敢"这类评价词凑数'
+      });
+    }
+    if (new Set(values).size !== values.length) {
+      errors.push({
+        code: 'FLESH_TRAITS_DUPLICATE',
+        path: path + '.traits',
+        message: label + '的 traits 有重复条目',
+        hint: '删掉重复项，换成不同的习惯/感官锚点'
+      });
+    }
+  };
+
+  const checkChanges = (rel, path, label) => {
+    if (!rel || !Array.isArray(rel.changes) || rel.changes.length === 0) return;
+    for (const [k, ch] of rel.changes.entries()) {
+      if (!ch || typeof ch !== 'object') continue;
+      for (const key of ['stage', 'from', 'to', 'trigger', 'description']) {
+        const v = ch[key];
+        if (typeof v !== 'string' || !v.trim()) {
+          errors.push({
+            code: 'REL_CHANGE_INCOMPLETE',
+            path: path + '.changes[' + k + '].' + key,
+            message: label + '的关系变化缺少 ' + key + '，无法判断这一阶段到底发生了什么',
+            hint: '每条变化至少写清：阶段名、变化前状态、变化后状态、触发事件、变化描述'
+          });
+        }
+      }
+      for (const key of ['stage', 'from', 'to', 'trigger', 'description', 'timing']) {
+        if (typeof ch[key] === 'string' && /第\s*(?:\d+|[一二三四五六七八九十百千万]+)\s*章/.test(ch[key])) {
+          errors.push({
+            code: 'FLESH_FREETEXT_CHAPTER_REF',
+            path: path + '.changes[' + k + '].' + key,
+            message: '关系变化里出现"第 N 章"引用；章节号属于节奏阶段',
+            hint: '这里只写"前期/转折/后期/某卷"或事件本身，章节落点由节奏阶段 relationship_timeline 决定'
+          });
+        }
+      }
+    }
+  };
+
+  if (fileType === '角色') {
+    for (const [i, c] of (data.characters || []).entries()) {
+      if (!c) continue;
+      checkTraits(c, 'characters[' + i + ']', '角色', 3, 5);
+      for (const [j, rel] of (c.relationships || []).entries()) {
+        if (!rel) continue;
+        if (rel.relationship_type === '其他' && !String(rel.relation_label || '').trim()) {
+          errors.push({
+            code: 'REL_LABEL_REQUIRED',
+            path: 'characters[' + i + '].relationships[' + j + '].relation_label',
+            message: 'relationship_type="其他" 时必须填 relation_label，写清具体关系（如 附身/寄生/契约/共生）',
+            hint: 'relation_label 是词表外关系的唯一语义来源'
+          });
+        }
+        checkChanges(rel, 'characters[' + i + '].relationships[' + j + ']', c.name || c.id);
+      }
+    }
+  }
+  if (fileType === '其他实体') {
+    for (const [i, o] of (data.other_entities || []).entries()) {
+      if (!o) continue;
+      checkTraits(o, 'other_entities[' + i + ']', '其他实体', 2, 6);
+    }
+  }
+}
+
+// ============================================================
+// 跨阶段：血肉关系 ↔ 骨架关系一致性
+// ============================================================
+// 骨架 `关系.json` 的 `character_relations` 是「from 对 to 的关系类型」，
+// 血肉 `角色.json` 的 `relationships[]` 是「本角色对 target_name 的关系」，
+// 方向语义与骨架一致。此前两个阶段之间没有任何关系语义的比对，
+// 于是「骨架写 A 服从 B，血肉写 A 与 B 是上下级关系」这类不一致完全逃逸：
+// 实体和边的拓扑都对得上，语义却对不上。
+//
+// 判定规则（有序对 S→T 表示「S 对 T 的关系」）：
+//   1. 骨架有 S→T=K，血肉也声明 S→T=L 且 L≠K        → REL_TYPE_MISMATCH
+//   2. 骨架只有反向 T→S=K，血肉声明 S→T=L：
+//        K 为对称关系且 L=K → 等价表述，放行
+//        K 为对称关系且 L≠K → REL_TYPE_MISMATCH
+//        K 为有向关系         → REL_DIRECTION_FLIP（有向关系被写反了）
+//   3. 骨架正反两个方向都没有，血肉却声明了       → REL_NOT_IN_SKELETON
+//   4. 骨架有 S→T=K，血肉正反两个方向都没声明      → REL_UNDECLARED（warning）
+//
+// 规则 4 只报 warning：血肉阶段允许先铺开主干关系，再补齐其余关系。
+// 其余三条都是 error —— 它们是语义冲突，不是覆盖度问题。
+function skeletonRelationConsistencyCheck(fleshData, sk, errors, warnings, opts) {
+  if (!sk || !sk.entity || !sk.relations) return;
+  const checkCoverage = !opts || opts.checkCoverage !== false;
+
+  // 骨架角色：id → id，name → id
+  const idByKey = new Map();
+  for (const c of (sk.entity.characters || [])) {
+    if (!c) continue;
+    if (c.id) idByKey.set(c.id, c.id);
+    if (c.name) idByKey.set(c.name, c.id);
+  }
+  const resolve = (v) => (v && idByKey.has(v) ? idByKey.get(v) : null);
+
+  // 骨架关系：'A→B' → { kind, label }
+  const skRel = new Map();
+  for (const r of (sk.relations.character_relations || [])) {
+    if (!r || !r.from || !r.to) continue;
+    skRel.set(r.from + '→' + r.to, {
+      kind: r.relation_kind,
+      label: typeof r.relation_label === 'string' ? r.relation_label.trim() : ''
+    });
+  }
+
+  // 血肉关系：有序对 → { kind, path }，并记录血肉已覆盖的无序对
+  const fleshRel = new Map();
+  const coveredPairs = new Set();
+  for (const [i, c] of (fleshData.characters || []).entries()) {
+    if (!c) continue;
+    const srcId = resolve(c.id) || resolve(c.name);
+    for (const [j, r] of (c.relationships || []).entries()) {
+      if (!r) continue;
+      const p = 'characters[' + i + '].relationships[' + j + ']';
+      const tgtId = resolve(r.target_name);
+      if (!srcId || !tgtId) continue;   // 解析不出来由 xrefCheck / entityRefCheck 负责
+      const key = srcId + '→' + tgtId;
+      const pairKey = [srcId, tgtId].sort().join('↔');
+      coveredPairs.add(pairKey);
+      fleshRel.set(key, { kind: r.relationship_type, path: p, target: r.target_name, src: c.name || c.id });
+
+      const fwd = skRel.get(key);
+      if (fwd !== undefined) {
+        if (r.relationship_type !== fwd.kind) {
+          errors.push({
+            code: 'REL_TYPE_MISMATCH',
+            path: p + '.relationship_type',
+            message: '骨架 ' + srcId + '→' + tgtId + ' 的关系类型是 "' + fwd.kind + '"，血肉写的是 "' + r.relationship_type + '"',
+            hint: '血肉阶段的关系类型必须与骨架一致；若语义确实变了，请在 description 里写清"关系在剧情中如何演变"，而不是换掉类型'
+          });
+        }
+        const fleshLabel = typeof r.relation_label === 'string' ? r.relation_label.trim() : '';
+        if (fwd.label && fleshLabel && fwd.label !== fleshLabel) {
+          errors.push({
+            code: 'REL_LABEL_MISMATCH',
+            path: p + '.relation_label',
+            message: '骨架 ' + srcId + '→' + tgtId + ' 的关系标签是 "' + fwd.label + '"，血肉写的是 "' + fleshLabel + '"',
+            hint: '关系标签必须与骨架完全一致'
+          });
+        }
+        if (fwd.kind === '其他' && !fleshLabel) {
+          errors.push({
+            code: 'REL_LABEL_REQUIRED',
+            path: p + '.relation_label',
+            message: '骨架把 ' + srcId + '→' + tgtId + ' 标为"其他"，血肉必须写 relation_label',
+            hint: '照抄骨架的 relation_label，或补齐具体关系名'
+          });
+        }
+        continue;
+      }
+
+      const revRow = skRel.get(tgtId + '→' + srcId);
+      if (revRow === undefined) {
+        errors.push({
+          code: 'REL_NOT_IN_SKELETON',
+          path: p,
+          message: '血肉声明了 ' + (c.name || c.id) + ' → ' + r.target_name + ' 的关系，但骨架没有这一对角色的任何关系',
+          hint: '骨架 `关系.json` 的 `character_relations` 里补上这一对，或删掉血肉里的这条关系'
+        });
+        continue;
+      }
+
+      const rev = revRow.kind;
+      const meta = RELATION_KIND_META[rev];
+      if (meta && meta.direction === 'symmetric') {
+        if (r.relationship_type !== rev) {
+          errors.push({
+            code: 'REL_TYPE_MISMATCH',
+            path: p + '.relationship_type',
+            message: '骨架 ' + tgtId + '→' + srcId + ' 的关系类型是 "' + rev + '"，血肉这边写的是 "' + r.relationship_type + '"',
+            hint: '对称关系写成反方向仍须是同一个类型；请与骨架保持一致'
+          });
+        }
+      } else {
+        errors.push({
+          code: 'REL_DIRECTION_FLIP',
+          path: p,
+          message: '骨架声明的是 ' + tgtId + '→' + srcId + '「' + rev + '」（有向关系），血肉却写成 ' + (c.name || c.id) + ' → ' + r.target_name + '「' + r.relationship_type + '」',
+          hint: '有向关系的方向不能反：该声明写在 ' + tgtId + ' 对应的角色文件里，关系类型与骨架保持一致'
+        });
+      }
+    }
+  }
+
+  // 骨架里声明了、但血肉正反两个方向都没写的关系
+  if (!checkCoverage) return;
+  for (const [key, kind] of skRel) {
+    const parts = key.split('→');
+    const pairKey = [parts[0], parts[1]].sort().join('↔');
+    if (coveredPairs.has(pairKey)) continue;
+    warnings.push({
+      code: 'REL_UNDECLARED',
+      path: '骨架关系 ' + key,
+      message: '骨架 ' + key + '（"' + kind.kind + '"）在血肉阶段没有对应的 relationships 条目',
+      hint: '该对角色的关系尚未血肉化；若刻意留白可忽略'
+    });
+  }
+}
+
+// ============================================================
+// 模板校验
+// ============================================================
+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) {
+  // 这些路径下的同名字段是文本描述，不是章节号
+  // 路径中的字段 segment 可被 `.` 或 `[` 包裹
+  const TEXT_DESCRIPTOR_PATH_REGEXES = [
+    /(?:^|\.|\[)arc_change_descriptions(?:\.|\[|$)/
+  ];
+  const isUnderTextDescriptor = (path) => {
+    if (!path) return false;
+    return TEXT_DESCRIPTOR_PATH_REGEXES.some(re => re.test(path));
+  };
+  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 (!isUnderTextDescriptor(curPath)) {
+        if (containerSet.has(k)) {
+          errors.push({
+            code: 'FLESH_CHAPTER_FORBIDDEN',
+            path: curPath,
+            message: '血肉阶段不允许出现章节容器 "' + k + '"',
+            hint: '章节号属于节奏阶段'
+          });
+          continue;
+        }
+        if (scalarSet.has(k) && typeof v === 'number') {
+          errors.push({
+            code: 'FLESH_CHAPTER_FORBIDDEN',
+            path: curPath,
+            message: '血肉阶段不允许出现章节号字段 "' + k + '"（值 ' + v + '）',
+            hint: '章节号属于节奏阶段'
+          });
+        }
+      }
+      walk(v, curPath);
+    }
+  };
+  walk(data, '');
+}
+
+// ============================================================
+// 自由文本字段的章节号引用检查
+// ============================================================
+const CHAPTER_REF_RE = /第\s*(?:\d+|[一二三四五六七八九十百千万]+)\s*章/;
+
+const FREE_TEXT_FIELDS = new Set([
+  'description', 'content', 'notes', 'note',
+  'function', 'function_detail', 'limit', 'origin', 'appearance',
+  'symbolic_meaning', 'usage_scenario', 'relation',
+  'method', 'residual_impact', 'resolution_method',
+  'goal', 'core_goal', 'influence_scope',
+  'surface_contradiction', 'deep_contradiction', 'ultimate_contradiction',
+  'core_flaw', 'golden_finger', 'known_secrets', 'unknown_secrets', 'false_beliefs',
+  'short_term', 'medium_term', 'long_term',
+  'relationship_type', 'stage', 'main_relation', 'expected_outcome',
+  'layout', 'narrative_role_description',
+  'conflict_summary', 'conflict_solution',
+  'special_remaining', 'emotion_trajectory', 'core_emotion', 'final_point',
+  'climax_design', 'turning_design', 'cost_design', 'resolution_design',
+  'suppression_method', 'resource_seizure_path', 'main_line_connection',
+  'internal_structure', 'position_description', 'relation_description',
+  'core_drive',
+  'applicable_scope', 'exception', 'impact_on_protagonist',
+  'violation_consequence', 'impact_on_plot',
+  'contradiction', 'solution',
+  'catchphrase', 'speech_rhythm', 'info_preference', 'stance',
+  'identity_wording', 'personality_tone', 'relationship_stage_tone',
+  'personality',
+  // 以下字段虽然通常作 ID/枚举，但也可能写"第 N 章"提及，加入警告
+  'name', 'info_name', 'who_knows', 'who_does_not_know',
+  'foreshadow_id', 'related_characters', 'related_conflicts',
+  'target_name', 'from', 'to'
+]);
+
+function freeTextChapterCheck(data, warnings) {
+  const walk = (node, p, fieldName) => {
+    if (typeof node === 'string') {
+      if (fieldName && FREE_TEXT_FIELDS.has(fieldName) && CHAPTER_REF_RE.test(node)) {
+        warnings.push({
+          code: 'FLESH_FREETEXT_CHAPTER_REF',
+          path: p,
+          message: '自由文本中出现"第 N 章"引用，可能语义越界（章节号属于节奏阶段）',
+          hint: '如需表达时间位置，请改为"某阶段/某卷"，或在节奏阶段处理'
+        });
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach((v, i) => walk(v, p + '[' + i + ']', fieldName));
+      return;
+    }
+    if (node && typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) {
+        walk(v, p ? (p + '.' + k) : k, k);
+      }
+    }
+  };
+  walk(data, '', null);
+}
+
+// ============================================================
+// 字符集 / 占位符
+// ============================================================
+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 唯一性
+// ============================================================
+const FLESH_ID_ARRAYS = {
+  '角色': ['characters'],
+  '其他实体': ['other_entities'],
+  '冲突': ['conflicts'],
+  '势力': ['factions'],
+  '剧情': ['main_lines', 'branches'],
+  '地点': ['locations'],
+  '结局': ['endings'],
+  '世界观规则': ['core_rules', 'information_rules', 'social_rules'],
+  // 关键道具：'details' 是每个 summary 数组里道具的详情副本，id 与 summary 故意重复。
+  // 跨数组唯一性只检查 3 个 summary 数组；details 通过 itemRefCheck 单独校验其 id 来自 summary。
+  '关键道具': ['core_items', 'branch_items', 'symbolic_items']
+};
+
+function idUniquenessCheck(data, fileType, errors) {
+  const seen = new Set();
+  for (const key of FLESH_ID_ARRAYS[fileType] || []) {
+    for (const item of data[key] || []) {
+      if (!item.id) continue;
+      if (seen.has(item.id)) {
+        errors.push({ code: 'ID_DUP', path: key + '.' + item.id, message: 'ID ' + item.id + ' 重复', hint: null });
+      }
+      seen.add(item.id);
+    }
+  }
+}
+
+// ============================================================
+// 骨架引用与名称一致性
+// ============================================================
+const FLESH_TO_SKELETON = {
+  '角色': { fleshKey: 'characters', skeletonKey: 'characters' },
+  '其他实体': { fleshKey: 'other_entities', skeletonKey: 'other_entities' },
+  '冲突': { fleshKey: 'conflicts', skeletonKey: 'conflicts' },
+  '势力': { fleshKey: 'factions', skeletonKey: 'factions' },
+  '地点': { fleshKey: 'locations', skeletonKey: 'locations' },
+  '结局': { fleshKey: 'endings', skeletonKey: 'endings' }
+};
+
+function entityRefCheck(data, fileType, skeletonEntity, errors) {
+  const mapping = FLESH_TO_SKELETON[fileType];
+  if (!mapping) return;
+  const skeletonList = skeletonEntity[mapping.skeletonKey] || [];
+  const skMap = new Map(skeletonList.map(e => [e.id, e.name]));
+  for (const [i, item] of (data[mapping.fleshKey] || []).entries()) {
+    if (!item.id) continue;
+    if (!skMap.has(item.id)) {
+      errors.push({
+        code: 'FLESH_REF_MISSING',
+        path: mapping.fleshKey + '[' + i + '].id',
+        message: '血肉 id ' + item.id + ' 不存在于骨架 ' + mapping.skeletonKey,
+        hint: '血肉必须建立在骨架之上'
+      });
+      continue;
+    }
+    if (item.name && skMap.get(item.id) !== item.name) {
+      errors.push({
+        code: 'FLESH_NAME_MISMATCH',
+        path: mapping.fleshKey + '[' + i + '].name',
+        message: 'id ' + item.id + ' 的 name "' + item.name + '" 与骨架 "' + skMap.get(item.id) + '" 不一致',
+        hint: '同一 id 的 name 必须与骨架一致'
+      });
+    }
+  }
+}
+
+/**
+ * 结局的伏笔回收计划：foreshadow_id 必须真的存在于骨架的 foreshadows 里。
+ *
+ * 空白来源（2026-10 复查）：结局模板里 foreshadow_recovery_plan 是必填，
+ * foreshadow_id 有格式约束（^FS\d{3}$），PATTERN 错误码能挡住格式错；
+ * 但"FS047 这个 id 在骨架的 31 条伏笔里到底存不存在"从来没人查过。
+ * 骨架只到 FS031 时，LLM 填一个格式正确但悬空的 FS047，
+ * 后面节奏阶段去回收它就永远对不上。
+ */
+function foreshadowRefCheck(data, skeletonEntity, errors) {
+  const skList = skeletonEntity.foreshadows || [];
+  if (!skList.length) return;
+  const skIds = new Set(skList.map((e) => e && e.id).filter(Boolean));
+  for (const [i, e] of (data.endings || []).entries()) {
+    const plans = e.foreshadow_recovery_plan;
+    if (!Array.isArray(plans)) continue;
+    for (const [j, plan] of plans.entries()) {
+      const fid = plan && plan.foreshadow_id;
+      if (!fid) continue;
+      if (!skIds.has(fid)) {
+        errors.push({
+          code: 'FLESH_FORESHADOW_REF_MISSING',
+          path: 'endings[' + i + '].foreshadow_recovery_plan[' + j + '].foreshadow_id',
+          message: '伏笔 id "' + fid + '" 不存在于骨架的 foreshadows',
+          hint: '伏笔 id 必须来自骨架 实体.json 的 foreshadows（可用 node references/upstream-query.js --stage=骨架 --file=实体 --list 查全部 id 名单）'
+        });
+      }
+    }
+  }
+}
+
+function storyRefCheck(data, skeletonEntity, errors) {
+  const mlMap = new Map((skeletonEntity.main_lines || []).map(e => [e.id, e.name]));
+  const bMap = new Map((skeletonEntity.branches || []).map(e => [e.id, e.name]));
+  for (const [i, item] of (data.main_lines || []).entries()) {
+    if (!item.id) continue;
+    if (!mlMap.has(item.id)) {
+      errors.push({ code: 'FLESH_REF_MISSING', path: 'main_lines[' + i + '].id', message: '主线 id ' + item.id + ' 不存在于骨架', hint: null });
+    } else if (item.name && mlMap.get(item.id) !== item.name) {
+      errors.push({ code: 'FLESH_NAME_MISMATCH', path: 'main_lines[' + i + '].name', message: '主线 id ' + item.id + ' 的 name 不一致', hint: null });
+    }
+  }
+  for (const [i, item] of (data.branches || []).entries()) {
+    if (!item.id) continue;
+    if (!bMap.has(item.id)) {
+      errors.push({ code: 'FLESH_REF_MISSING', path: 'branches[' + i + '].id', message: '支线 id ' + item.id + ' 不存在于骨架', hint: null });
+    } else if (item.name && bMap.get(item.id) !== item.name) {
+      errors.push({ code: 'FLESH_NAME_MISMATCH', path: 'branches[' + i + '].name', message: '支线 id ' + item.id + ' 的 name 不一致', hint: null });
+    }
+  }
+}
+
+// ============================================================
+// 世界观规则：引用 + 前缀 + 分组 category 一致性
+// ============================================================
+const WORLD_RULE_GROUP_MAP = {
+  'core_rules': { prefix: /^R\d{3}$/, category: '核心规则' },
+  'information_rules': { prefix: /^I\d{3}$/, category: '信息规则' },
+  'social_rules': { prefix: /^SR\d{3}$/, category: '社会规则' }
+};
+
+function worldRuleRefCheck(data, skeletonEntity, errors) {
+  const skMap = new Map((skeletonEntity.world_rules || []).map(e => [e.id, e]));
+
+  for (const [key, spec] of Object.entries(WORLD_RULE_GROUP_MAP)) {
+    for (const [i, item] of (data[key] || []).entries()) {
+      if (!item.id) continue;
+
+      if (!spec.prefix.test(item.id)) {
+        errors.push({
+          code: 'FLESH_WORLD_RULE_CATEGORY',
+          path: key + '[' + i + '].id',
+          message: key + ' 的 id 应为 ' + spec.category + ' 对应的前缀，实际 "' + item.id + '"',
+          hint: null
+        });
+      }
+
+      const skItem = skMap.get(item.id);
+      if (!skItem) {
+        errors.push({
+          code: 'FLESH_REF_MISSING',
+          path: key + '[' + i + '].id',
+          message: '规则 id ' + item.id + ' 不存在于骨架 world_rules',
+          hint: null
+        });
+        continue;
+      }
+
+      if (item.name && skItem.name !== item.name) {
+        errors.push({
+          code: 'FLESH_NAME_MISMATCH',
+          path: key + '[' + i + '].name',
+          message: '规则 id ' + item.id + ' 的 name 不一致',
+          hint: null
+        });
+      }
+
+      if (skItem.category && skItem.category !== spec.category) {
+        errors.push({
+          code: 'FLESH_GROUP_CATEGORY_MISMATCH',
+          path: key + '[' + i + '].id',
+          message: '骨架中 ' + item.id + ' 的 category 是 "' + skItem.category + '"，不应放在血肉的 ' + key,
+          hint: '按骨架的 category 把 ' + item.id + ' 移到对应数组'
+        });
+      }
+    }
+  }
+}
+
+// ============================================================
+// 关键道具：引用 + 分组 category 一致性 + details 对应（P2-10 顺序修正）
+// ============================================================
+const ITEM_GROUP_MAP = {
+  'core_items': '核心道具',
+  'branch_items': '支线道具',
+  'symbolic_items': '象征道具'
+};
+
+function itemRefCheck(data, skeletonEntity, errors) {
+  const skMap = new Map((skeletonEntity.items || []).map(e => [e.id, e]));
+  const fleshItemIds = new Set();
+
+  // 道具 id → 它所在的分组数组名（core_items / branch_items / symbolic_items），
+  // 报错定位用。
+  const itemGroup = new Map();
+
+  for (const [key, expectedCategory] of Object.entries(ITEM_GROUP_MAP)) {
+    for (const [i, item] of (data[key] || []).entries()) {
+      if (!item.id) continue;
+      itemGroup.set(item.id, key);
+
+      const skItem = skMap.get(item.id);
+      if (!skItem) {
+        errors.push({ code: 'FLESH_REF_MISSING', path: key + '[' + i + '].id', message: '道具 id ' + item.id + ' 不存在于骨架 items', hint: null });
+        continue;
+      }
+
+      // P2-10：先校验存在，再加入 fleshItemIds
+      fleshItemIds.add(item.id);
+
+      if (item.name && skItem.name !== item.name) {
+        errors.push({ code: 'FLESH_NAME_MISMATCH', path: key + '[' + i + '].name', message: '道具 id ' + item.id + ' 的 name 不一致', hint: null });
+      }
+
+      if (skItem.category && skItem.category !== expectedCategory) {
+        errors.push({
+          code: 'FLESH_GROUP_CATEGORY_MISMATCH',
+          path: key + '[' + i + '].id',
+          message: '骨架中 ' + item.id + ' 的 category 是 "' + skItem.category + '"，不应放在血肉的 ' + key,
+          hint: '按骨架的 category 把 ' + item.id + ' 移到对应数组'
+        });
+      }
+    }
+  }
+
+  const detailIds = new Set();
+  for (const [i, d] of (data.details || []).entries()) {
+    if (!d.id) continue;
+    detailIds.add(d.id);
+    if (!fleshItemIds.has(d.id)) {
+      errors.push({ code: 'FLESH_DETAILS_ORPHAN', path: 'details[' + i + '].id', message: 'details id ' + d.id + ' 没有对应的核心/支线/象征道具', hint: null });
+    }
+  }
+  for (const iid of fleshItemIds) {
+    if (!detailIds.has(iid)) {
+      // path 要指向"少 details 的那个道具条目"所在的**分组数组**：
+      // 之前写的是 'items.' + iid，而血肉的布局里根本没有 items 这个键
+      // （分组数组是 core_items / branch_items / symbolic_items）→
+      // 归因层匹配不上 → 归不到批次 → 整段重跑。
+      errors.push({
+        code: 'FLESH_DETAILS_ORPHAN',
+        path: (itemGroup.get(iid) || 'details') + '.' + iid,
+        message: '道具 ' + iid + ' 缺少对应 details',
+        hint: null
+      });
+    }
+  }
+}
+
+// ============================================================
+// 跨文件名称引用
+// ============================================================
+function xrefCheck(data, fileType, skeletonEntity, errors) {
+  // 血同时收集 id 和 name 两种引用源——LLM 可能写 id (C001) 或 name (陆子仲)
+  const charNames = new Set();
+  for (const c of (skeletonEntity.characters || [])) {
+    if (c.name) charNames.add(c.name);
+    if (c.id) charNames.add(c.id);
+  }
+  const factionNames = new Set();
+  for (const f of (skeletonEntity.factions || [])) {
+    if (f.name) factionNames.add(f.name);
+    if (f.id) factionNames.add(f.id);
+  }
+  const conflictNames = new Set();
+  for (const x of (skeletonEntity.conflicts || [])) {
+    if (x.name) conflictNames.add(x.name);
+    if (x.id) conflictNames.add(x.id);
+  }
+
+  const checkName = (name, set, label, p) => {
+    if (!name) return;
+    if (!set.has(name)) {
+      // 拼错要给正确名字：只说"不存在"的话，LLM 只能靠猜；
+      // 给出最接近的那个，它能直接改对（算法见 graph-utils.js suggestClosestName）
+      const guess = suggestClosestName(name, set);
+      errors.push({
+        code: 'FLESH_XREF_MISSING',
+        path: p,
+        message: '引用' + label + ' "' + name + '" 不存在于骨架',
+        hint: guess
+          ? '疑似拼错：骨架里有 "' + guess.name + '"，请改成它'
+          : '引用必须用骨架里已有的' + label + '名字；可用 node references/upstream-query.js --stage=骨架 --file=实体 --list 查全量名单'
+      });
+    }
+  };
+
+  if (fileType === '角色') {
+    for (const [i, c] of (data.characters || []).entries()) {
+      for (const [j, r] of (c.relationships || []).entries()) {
+        checkName(r.target_name, charNames, '角色', 'characters[' + i + '].relationships[' + j + '].target_name');
+      }
+    }
+  } else if (fileType === '冲突') {
+    for (const [i, x] of (data.conflicts || []).entries()) {
+      for (const [j, g] of (x.information_gaps || []).entries()) {
+        for (const [k, n] of (g.who_knows || []).entries()) {
+          checkName(n, charNames, '角色', 'conflicts[' + i + '].information_gaps[' + j + '].who_knows[' + k + ']');
+        }
+        for (const [k, n] of (g.who_does_not_know || []).entries()) {
+          checkName(n, charNames, '角色', 'conflicts[' + i + '].information_gaps[' + j + '].who_does_not_know[' + k + ']');
+        }
+      }
+    }
+  } else if (fileType === '势力') {
+    for (const [i, f] of (data.factions || []).entries()) {
+      for (const [j, m] of (f.members || []).entries()) {
+        checkName(m.name, charNames, '角色', 'factions[' + i + '].members[' + j + '].name');
+      }
+      for (const [j, r] of (f.relations || []).entries()) {
+        checkName(r.target_name, factionNames, '势力', 'factions[' + i + '].relations[' + j + '].target_name');
+      }
+    }
+  } else if (fileType === '关键道具') {
+    for (const [i, d] of (data.details || []).entries()) {
+      for (const [j, n] of (d.related_characters || []).entries()) {
+        checkName(n, charNames, '角色', 'details[' + i + '].related_characters[' + j + ']');
+      }
+      for (const [j, n] of (d.related_conflicts || []).entries()) {
+        checkName(n, conflictNames, '冲突', 'details[' + i + '].related_conflicts[' + j + ']');
+      }
+    }
+  }
+}
+
+// ============================================================
+// arc_type 与 arc_stages 兼容性 + expected_volume 校验
+// ============================================================
+function arcConsistencyCheck(data, warnings, hierarchy) {
+  const validVolumes = new Set();
+  if (hierarchy && Array.isArray(hierarchy.volumes)) {
+    for (const v of hierarchy.volumes) {
+      if (v && v.id) validVolumes.add(v.id);
+    }
+  }
+  for (const [i, c] of (data.characters || []).entries()) {
+    const t = c.arc_type;
+    const s = c.arc_stages;
+    if (typeof s === 'number') {
+      let minRequired = 0;
+      if (t === '成长型') minRequired = 3;
+      else if (t === '堕落型') minRequired = 2;
+      else if (t === '发现型') minRequired = 2;
+      else if (t === '不变型') minRequired = 1;
+      if (s <= 0) {
+        warnings.push({
+          code: 'FLESH_ARC_STAGES_INVALID',
+          path: 'characters[' + i + '].arc_stages',
+          message: 'arc_stages=' + s + ' 必须 > 0（弧光阶段数）',
+          hint: 'arc_stages 应为正整数'
+        });
+      } else if (minRequired > 0 && s < minRequired) {
+        warnings.push({
+          code: 'FLESH_ARC_INCONSISTENT',
+          path: 'characters[' + i + '].arc_stages',
+          message: 'arc_type="' + t + '" 通常需要至少 ' + minRequired + ' 个阶段，实际 arc_stages=' + s,
+          hint: 'arc_stages 表示弧光阶段数'
+        });
+      }
+    }
+    // expected_volume 必须存在于骨架层级 volumes
+    const ev = c.exclusive_needs && c.exclusive_needs.expected_volume;
+    if (ev && validVolumes.size > 0 && !validVolumes.has(ev)) {
+      warnings.push({
+        code: 'FLESH_EXPECTED_VOLUME_MISSING',
+        path: 'characters[' + i + '].exclusive_needs.expected_volume',
+        message: 'expected_volume "' + ev + '" 不存在于骨架层级 volumes',
+        hint: '改为骨架层级中已存在的卷 id'
+      });
+    }
+  }
+}
+
+// ============================================================
+// 全量：覆盖完整性检查（P0-3：用文件类型 key）
+// ============================================================
+function checkEntityCoverage(skeletonIds, fleshIds, label, errors, warnings) {
+  for (const id of skeletonIds) {
+    if (!fleshIds.has(id)) {
+      warnings.push({ code: 'FLESH_INCOMPLETE', path: label + '.' + id, message: '骨架 ' + label + ' ' + id + ' 未在血肉中出现', hint: '全量写完时应覆盖所有骨架实体' });
+    }
+  }
+  for (const id of fleshIds) {
+    if (!skeletonIds.has(id)) {
+      errors.push({ code: 'FLESH_EXTRA_ENTITY', path: label + '.' + id, message: '血肉 ' + label + ' ' + id + ' 不在骨架中', hint: '本阶段不能自创实体：删掉这条，或把它列进交付说明的「骨架缺口」小节，由用户重新运行骨架阶段补全后再重跑血肉' });
+    }
+  }
+}
+
+// P0-3：数组名 → 文件类型 的映射
+const DIRECT_FILE_TYPE_MAP = {
+  characters: '角色',
+  other_entities: '其他实体',
+  conflicts: '冲突',
+  factions: '势力',
+  locations: '地点',
+  endings: '结局'
+};
+
+function completenessCheck(fleshData, skeletonEntity, errors, warnings) {
+  const directChecks = [
+    { fleshKey: 'characters', skKey: 'characters', label: 'character' },
+    { fleshKey: 'other_entities', skKey: 'other_entities', label: 'other_entity' },
+    { fleshKey: 'conflicts', skKey: 'conflicts', label: 'conflict' },
+    { fleshKey: 'factions', skKey: 'factions', label: 'faction' },
+    { fleshKey: 'locations', skKey: 'locations', label: 'location' },
+    { fleshKey: 'endings', skKey: 'endings', label: 'ending' }
+  ];
+
+  for (const { fleshKey, skKey, label } of directChecks) {
+    const fileType = DIRECT_FILE_TYPE_MAP[fleshKey];
+    const data = fleshData[fileType] ? fleshData[fileType].data : null;
+    const fleshIds = new Set(((data && data[fleshKey]) || []).map(e => e.id).filter(Boolean));
+    const skIds = new Set((skeletonEntity[skKey] || []).map(e => e.id));
+    checkEntityCoverage(skIds, fleshIds, label, errors, warnings);
+  }
+
+  // items
+  {
+    const data = fleshData['关键道具'] ? fleshData['关键道具'].data : null;
+    const fleshIds = new Set();
+    if (data) {
+      for (const key of ['core_items', 'branch_items', 'symbolic_items']) {
+        for (const x of (data[key] || [])) if (x.id) fleshIds.add(x.id);
+      }
+    }
+    const skIds = new Set((skeletonEntity.items || []).map(e => e.id));
+    checkEntityCoverage(skIds, fleshIds, 'item', errors, warnings);
+  }
+
+  // world_rules
+  {
+    const data = fleshData['世界观规则'] ? fleshData['世界观规则'].data : null;
+    const fleshIds = new Set();
+    if (data) {
+      for (const key of ['core_rules', 'information_rules', 'social_rules']) {
+        for (const x of (data[key] || [])) if (x.id) fleshIds.add(x.id);
+      }
+    }
+    const skIds = new Set((skeletonEntity.world_rules || []).map(e => e.id));
+    checkEntityCoverage(skIds, fleshIds, 'world_rule', errors, warnings);
+  }
+
+  // main_lines / branches
+  {
+    const data = fleshData['剧情'] ? fleshData['剧情'].data : null;
+    const fleshMlIds = new Set(((data && data.main_lines) || []).map(e => e.id).filter(Boolean));
+    const fleshBrIds = new Set(((data && data.branches) || []).map(e => e.id).filter(Boolean));
+    const skMlIds = new Set((skeletonEntity.main_lines || []).map(e => e.id));
+    const skBrIds = new Set((skeletonEntity.branches || []).map(e => e.id));
+    checkEntityCoverage(skMlIds, fleshMlIds, 'main_line', errors, warnings);
+    checkEntityCoverage(skBrIds, fleshBrIds, 'branch', errors, warnings);
+  }
+
+  // 说明：foreshadows / climaxes / pleasures 在血肉阶段无独立档案，不检查。
+}
+
+// ============================================================
+// md 生成 + stage-status（结构化 markdown，零反引号）
+// ============================================================
+const BT = String.fromCharCode(96);
+const BT3 = BT + BT + BT;
+
+function jsonToMd(data, fileType) {
+  // flesh 阶段：按 FLESH_DISPATCH 把顶层数组分别渲染为 H2 分组（renderFleshByFileType）
+  const body = renderFleshByFileType(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 validateSingle(args) {
+  const input = args.input;
+  const template = args.template;
+  const file = args.file;
+  const errors = [];
+  const warnings = [];
+
+  if (!args.upstream || args.upstream.length === 0) {
+    return emit(2, file, [{ code: 'UPSTREAM_MISSING', path: '', message: '血肉阶段必须提供 --upstream=<骨架目录>', hint: null }], []);
+  }
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, file, [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+
+  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 }], []);
+
+  const sk = loadSkeleton(args.upstream);
+  if (!sk.entity) {
+    return emit(2, file, [{ code: 'UPSTREAM_NOT_READY', path: '', message: '骨架 实体.json 读不到', hint: '请先完成骨架阶段' }], []);
+  }
+
+  // 阶段门禁：上游必须已通过全量校验（此前只在提示词里约定，脚本不校验）
+  const gate = readStageGate(args.upstream[0]);
+  if (!gate.ok) {
+    return emit(2, file, [{ code: 'UPSTREAM_NOT_PASSED', path: '', message: gate.reason, hint: '请先对骨架阶段执行全量校验并通过' }], []);
+  }
+
+  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('freeTextChapterCheck', () => freeTextChapterCheck(data, warnings), errors);
+  safeCheck('idUniquenessCheck', () => idUniquenessCheck(data, file, errors), errors);
+
+  if (file === '角色' || file === '其他实体' || file === '冲突' || file === '势力' || file === '地点' || file === '结局') {
+    safeCheck('entityRefCheck', () => entityRefCheck(data, file, sk.entity, errors), errors);
+  } else if (file === '剧情') {
+    safeCheck('storyRefCheck', () => storyRefCheck(data, sk.entity, errors), errors);
+  } else if (file === '世界观规则') {
+    safeCheck('worldRuleRefCheck', () => worldRuleRefCheck(data, sk.entity, errors), errors);
+  } else if (file === '关键道具') {
+    safeCheck('itemRefCheck', () => itemRefCheck(data, sk.entity, errors), errors);
+  }
+
+  // 结局的伏笔回收计划：foreshadow_id 要真的在骨架里
+  if (file === '结局') {
+    safeCheck('foreshadowRefCheck', () => foreshadowRefCheck(data, sk.entity, errors), errors);
+  }
+
+  safeCheck('xrefCheck', () => xrefCheck(data, file, sk.entity, errors), errors);
+  safeCheck('fleshSelfRelationCheck', () => fleshSelfRelationCheck(data, file, errors), errors);
+  safeCheck('contentQualityCheck', () => runContentQualityChecks(data, errors, { enumLeaves: collectEnumLeaves(tplRes.data.structure) }), errors);
+  safeCheck('traitsAndChangesCheck', () => traitsAndChangesCheck(data, file, errors, warnings), errors);
+
+  if (file === '角色') {
+    safeCheck('arcConsistencyCheck', () => arcConsistencyCheck(data, warnings, sk.hierarchy), errors);
+    // 单文件模式看不到血肉全貌，只做语义比对，不做覆盖度比对
+    safeCheck('skeletonRelationConsistencyCheck',
+      () => skeletonRelationConsistencyCheck(data, sk, errors, warnings, { checkCoverage: false }), 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'];
+  const errors = [];
+  const warnings = [];
+
+  if (!args.upstream || args.upstream.length === 0) {
+    return emit(2, 'ALL', [{ code: 'UPSTREAM_MISSING', path: '', message: '血肉阶段必须提供 --upstream=<骨架目录>', hint: null }], []);
+  }
+
+  const gl = loadGlossary();
+  if (gl.error) return emit(2, 'ALL', [{ code: 'GLOSSARY_LOAD', path: '', message: gl.error, hint: null }], []);
+
+  if (!fs.existsSync(stageDir)) {
+    return emit(2, 'ALL', [{ code: 'ARG', path: stageDir, message: '阶段目录不存在', hint: null }], []);
+  }
+
+  const sk = loadSkeleton(args.upstream);
+  if (!sk.entity) {
+    return emit(2, 'ALL', [{ code: 'UPSTREAM_NOT_READY', path: '', message: '骨架 实体.json 读不到', hint: null }], []);
+  }
+
+  // 阶段门禁：上游必须已通过全量校验（此前只在提示词里约定，脚本不校验）
+  const gate = readStageGate(args.upstream[0]);
+  if (!gate.ok) {
+    return emit(2, 'ALL', [{ code: 'UPSTREAM_NOT_PASSED', path: '', message: gate.reason, hint: '请先对骨架阶段执行全量校验并通过' }], []);
+  }
+
+  const otherEntityCount = Array.isArray(sk.entity.other_entities) ? sk.entity.other_entities.length : 0;
+  const FILES = [
+    { type: '角色', name: '角色.json', tpl: '角色模板.json' },
+    { type: '冲突', name: '冲突.json', tpl: '冲突模板.json' },
+    { type: '势力', name: '势力.json', tpl: '势力模板.json' },
+    { type: '剧情', name: '剧情.json', tpl: '剧情模板.json' },
+    { type: '地点', name: '地点.json', tpl: '地点模板.json' },
+    { type: '结局', name: '结局.json', tpl: '结局模板.json' },
+    { type: '世界观规则', name: '世界观规则.json', tpl: '世界观规则模板.json' },
+    { type: '关键道具', name: '关键道具.json', tpl: '关键道具模板.json' },
+    ...(otherEntityCount > 0 || fs.existsSync(path.join(stageDir, '其他实体.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] = { data: inputRes.data, tpl: tplRes.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('freeTextChapterCheck', () => freeTextChapterCheck(data, warnings), errors);
+    safeCheck('idUniquenessCheck', () => idUniquenessCheck(data, f.type, errors), errors);
+
+    if (f.type === '角色' || f.type === '其他实体' || f.type === '冲突' || f.type === '势力' || f.type === '地点' || f.type === '结局') {
+      safeCheck('entityRefCheck', () => entityRefCheck(data, f.type, sk.entity, errors), errors);
+    } else if (f.type === '剧情') {
+      safeCheck('storyRefCheck', () => storyRefCheck(data, sk.entity, errors), errors);
+    } else if (f.type === '世界观规则') {
+      safeCheck('worldRuleRefCheck', () => worldRuleRefCheck(data, sk.entity, errors), errors);
+    } else if (f.type === '关键道具') {
+      safeCheck('itemRefCheck', () => itemRefCheck(data, sk.entity, errors), errors);
+    }
+
+    // 结局的伏笔回收计划：foreshadow_id 要真的在骨架里
+    if (f.type === '结局') {
+      safeCheck('foreshadowRefCheck', () => foreshadowRefCheck(data, sk.entity, errors), errors);
+    }
+
+    safeCheck('xrefCheck', () => xrefCheck(data, f.type, sk.entity, errors), errors);
+    safeCheck('fleshSelfRelationCheck', () => fleshSelfRelationCheck(data, f.type, errors), errors);
+    safeCheck('contentQualityCheck', () => runContentQualityChecks(data, errors, { enumLeaves: collectEnumLeaves(tplRes.data.structure) }), errors);
+    safeCheck('traitsAndChangesCheck', () => traitsAndChangesCheck(data, f.type, errors, warnings), errors);
+
+    if (f.type === '角色') safeCheck('arcConsistencyCheck', () => arcConsistencyCheck(data, warnings, sk.hierarchy), errors);
+  }
+
+  safeCheck('completenessCheck', () => completenessCheck(loaded, sk.entity, errors, warnings), errors);
+
+  if (loaded['角色']) {
+    safeCheck('skeletonRelationConsistencyCheck',
+      () => skeletonRelationConsistencyCheck(loaded['角色'].data, sk, errors, warnings, { checkCoverage: true }), 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();