@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/plugins/fancy-story-builder/scripts/graph-utils.js

@@ -0,0 +1,1385 @@
+/**
+ * graph-utils.js  v1.4
+ * 通用图工具库 + glossary 解析公共函数。
+ * 源码中零反引号，避免 markdown 渲染问题。
+ *
+ * v1.4 变更（修复 v1.3 的反引号遗漏）：
+ * - 头注释与 P0-1 说明中不再出现字面反引号字符
+ * - stripTicks 用 String.fromCharCode(96) 生成反引号字符与全局正则
+ *   （v1.3 用了正则字面量中含反引号，导致源码出现字面反引号，
+ *    违反本文件零反引号约定，并可能破坏 markdown 渲染）
+ *
+ * v1.3 变更（修复批次 P0-1 / P2-7）：
+ * - P0-1：parseGlossaryFromMd 剥离字段名与类型列的反引号
+ *   （原版未剥离，导致 chapterScalarFields 里存的是带反引号字符的
+ *    chapter 而非 chapter，骨架/血肉的 SKELETON_CHAPTER_FORBIDDEN /
+ *    FLESH_CHAPTER_FORBIDDEN 与节奏的 RHYTHM_CHAP_RANGE 全部失效）
+ * - P2-7：fieldType 为 计数 时不加入 chapterScalarFields
+ *   （chapter_count 是计数不是章节号）
+ *
+ * 导出：
+ * - SimpleGraph
+ * - getIsolatedNodes
+ * - getDisconnectedCoreNodes
+ * - checkBidirectionalSymmetry
+ * - RELATION_KIND_META
+ * - relationKindCompatible
+ * - assertRelationKindMeta
+ * - parseGlossaryFromMd
+ */
+
+// ============================================================
+// SimpleGraph
+// ============================================================
+export class SimpleGraph {
+  constructor() {
+    this._nodes = new Map();
+    this._out = new Map();
+    this._in = new Map();
+    this._edges = new Map();
+  }
+  addNode(key, attrs = {}) {
+    if (this._nodes.has(key)) return;
+    this._nodes.set(key, attrs);
+    this._out.set(key, new Set());
+    this._in.set(key, new Set());
+  }
+  addEdgeWithKey(edgeKey, source, target, attrs = {}) {
+    if (!this._nodes.has(source) || !this._nodes.has(target)) return;
+    if (this._edges.has(edgeKey)) return;
+    this._edges.set(edgeKey, { source, target, attrs });
+    this._out.get(source).add(edgeKey);
+    this._in.get(target).add(edgeKey);
+  }
+  hasNode(key) { return this._nodes.has(key); }
+  getNodeAttribute(key, name) { return (this._nodes.get(key) || {})[name]; }
+  getNodeAttributes(key) { return this._nodes.get(key) || {}; }
+  degree(key) {
+    return (this._out.get(key)?.size || 0) + (this._in.get(key)?.size || 0);
+  }
+  inDegree(key) { return this._in.get(key)?.size || 0; }
+  outDegree(key) { return this._out.get(key)?.size || 0; }
+  neighbors(key) {
+    const set = new Set();
+    for (const e of this._out.get(key) || []) {
+      const t = this._edges.get(e).target;
+      if (t !== key) set.add(t);
+    }
+    for (const e of this._in.get(key) || []) {
+      const s = this._edges.get(e).source;
+      if (s !== key) set.add(s);
+    }
+    return [...set];
+  }
+  forEachEdge(cb) {
+    for (const [k, e] of this._edges) cb(k, e.attrs, e.source, e.target);
+  }
+  forEachNode(cb) {
+    for (const [k, a] of this._nodes) cb(k, a);
+  }
+  nodes() { return [...this._nodes.keys()]; }
+  edges() { return [...this._edges.values()]; }
+  get order() { return this._nodes.size; }
+  get size() { return this._edges.size; }
+}
+
+// ============================================================
+// getIsolatedNodes
+// ============================================================
+export function getIsolatedNodes(graph, excludeTypes = []) {
+  const excluded = new Set(excludeTypes);
+  const result = [];
+  for (const key of graph.nodes()) {
+    const type = graph.getNodeAttribute(key, 'type');
+    if (excluded.has(type)) continue;
+    if (graph.degree(key) === 0) {
+      result.push({ key: key, type: type });
+    }
+  }
+  return result;
+}
+
+// ============================================================
+// getDisconnectedCoreNodes
+// ============================================================
+export function getDisconnectedCoreNodes(graph, coreTypes) {
+  const coreSet = new Set(coreTypes);
+  const coreNodes = graph.nodes().filter(k => coreSet.has(graph.getNodeAttribute(k, 'type')));
+  if (coreNodes.length <= 1) return [];
+  const visited = new Set([coreNodes[0]]);
+  const queue = [coreNodes[0]];
+  while (queue.length) {
+    const cur = queue.shift();
+    for (const nb of graph.neighbors(cur)) {
+      if (visited.has(nb)) continue;
+      if (coreSet.has(graph.getNodeAttribute(nb, 'type'))) {
+        visited.add(nb);
+        queue.push(nb);
+      }
+    }
+  }
+  return coreNodes.filter(k => !visited.has(k));
+}
+
+// ============================================================
+// checkBidirectionalSymmetry
+// ============================================================
+export function checkBidirectionalSymmetry(relations, opts = {}) {
+  const fromKey = opts.fromKey || 'from';
+  const toKey = opts.toKey || 'to';
+  const typeKey = opts.typeKey || 'type';
+  const mustBi = new Set(opts.mustBeBidirectionalTypes || []);
+
+  const relMap = new Map();
+  for (const r of relations) {
+    if (!r[fromKey] || !r[toKey]) continue;
+    relMap.set(r[fromKey] + '→' + r[toKey], r[typeKey]);
+  }
+
+  const oneWay = [];
+  const asymmetric = [];
+
+  for (const [k, type] of relMap) {
+    const parts = k.split('→');
+    const a = parts[0];
+    const b = parts[1];
+    const rev = b + '→' + a;
+    if (!relMap.has(rev)) {
+      if (mustBi.has(type)) {
+        oneWay.push({ from: a, to: b, type: type });
+      }
+    } else if (mustBi.has(type) && relMap.get(rev) !== type) {
+      asymmetric.push({ from: a, to: b, type: type, reverseType: relMap.get(rev) });
+    }
+  }
+
+  return { oneWay: oneWay, asymmetric: asymmetric };
+}
+
+// ============================================================
+// 角色关系类型元数据（relation_kind 词表）
+// ============================================================
+// 词表的值集合以 references/glossary.md 的 relation_kind 小节为唯一真源，
+// 模板通过 enumRef 引用它。本表只补充"机器判定所需"的两条语义：
+//   direction：对称（symmetric）还是有向（directed）
+//   group：关系维度。同一维度内的一对角色只能有一种关系；跨维度可共存。
+//
+// 维度划分：
+//   identity  结构性身份（血缘/师徒/雇佣）—— 与任何态度关系都可同时成立
+//   stance    地位姿态（服从/提携）—— 有向，描述上下位
+//   attitude  立场态度（合作/利益交换/利用/对立/敌对/竞争/中立）—— 一对角色只能有一种
+//
+// 同步保障：assertRelationKindMeta 在每次校验时比对本表与 glossary 的值集合，
+// 词表新增/删改而本表未同步时立刻报 REL_KIND_META_DRIFT，不会静默漏判。
+export const RELATION_KIND_META = {
+  '血缘': { direction: 'symmetric', group: 'identity' },
+  '师徒': { direction: 'directed', group: 'identity' },
+  '雇佣': { direction: 'directed', group: 'identity' },
+  '服从': { direction: 'directed', group: 'stance' },
+  '提携': { direction: 'directed', group: 'stance' },
+  '合作': { direction: 'symmetric', group: 'attitude' },
+  '利益交换': { direction: 'symmetric', group: 'attitude' },
+  '利用': { direction: 'directed', group: 'attitude' },
+  '对立': { direction: 'symmetric', group: 'attitude' },
+  '敌对': { direction: 'symmetric', group: 'attitude' },
+  '竞争': { direction: 'symmetric', group: 'attitude' },
+  '中立': { direction: 'symmetric', group: 'attitude' }
+};
+
+// 有向关系：同一对角色上双向互指同一个值即自相矛盾（互相服从/互相提携/互为师徒）
+// 对称关系：双向声明同一个值是正常的（如双方都写"合作"）
+const RELATION_KIND_DIRECTED = 'directed';
+
+/**
+ * 判定"同一对角色的两个方向声明"是否相容。
+ *
+ * kindAB：A→B 声明的关系类型
+ * kindBA：B→A 声明的关系类型
+ *
+ * 返回 { ok, reason }。reason 仅在 ok=false 时非空。
+ *
+ * 规则（只做增量判定：两个方向都声明了才比较）：
+ *   1. 维度不同 → 相容（血缘 + 合作、师徒 + 服从 可以同时成立）
+ *   2. 同维度且是有向关系且值相同 → 不相容（互相服从/互为师徒/互相雇佣）
+ *   3. 同属立场维度且值不同 → 不相容（同一对角色不可能既合作又对立）
+ *   4. 其余 → 相容
+ *
+ * 未知值返回 ok=true，交给 ENUM 检查报错，避免重复报同一个问题。
+ */
+export function relationKindCompatible(kindAB, kindBA) {
+  const a = RELATION_KIND_META[kindAB];
+  const b = RELATION_KIND_META[kindBA];
+  if (!a || !b) return { ok: true, reason: null };
+
+  if (a.group !== b.group) return { ok: true, reason: null };
+
+  if (a.direction === RELATION_KIND_DIRECTED && kindAB === kindBA) {
+    return {
+      ok: false,
+      reason: '有向关系「' + kindAB + '」在同一对角色上双向互指，自相矛盾'
+    };
+  }
+
+  if (a.group === 'attitude' && kindAB !== kindBA) {
+    return {
+      ok: false,
+      reason: '同一对角色只能有一种立场关系，不能既是「' + kindAB + '」又是「' + kindBA + '」'
+    };
+  }
+
+  return { ok: true, reason: null };
+}
+
+/**
+ * 校验 RELATION_KIND_META 与 glossary 词表是否同步。
+ *
+ * 返回 null 表示同步；否则返回错误对象（code / message / hint）。
+ * 这是词表与元数据之间的唯一防漂移闸门。
+ */
+export function assertRelationKindMeta(enums) {
+  const allowed = enums && enums.relation_kind;
+  if (!Array.isArray(allowed) || allowed.length === 0) {
+    return {
+      code: 'REL_KIND_META_DRIFT',
+      message: 'glossary.md 缺少 relation_kind 枚举（或解析为空），关系类型词表不可用',
+      hint: '在 references/glossary.md 的「五、枚举值总表」中补回 relation_kind 小节'
+    };
+  }
+  const metaKeys = Object.keys(RELATION_KIND_META);
+  const missingMeta = allowed.filter((k) => !RELATION_KIND_META[k]);
+  const missingEnum = metaKeys.filter((k) => !allowed.includes(k));
+  if (missingMeta.length === 0 && missingEnum.length === 0) return null;
+
+  const parts = [];
+  if (missingMeta.length > 0) {
+    parts.push('词表中有但元数据缺失：' + missingMeta.join(' / '));
+  }
+  if (missingEnum.length > 0) {
+    parts.push('元数据中有但词表缺失：' + missingEnum.join(' / '));
+  }
+  return {
+    code: 'REL_KIND_META_DRIFT',
+    message: 'relation_kind 词表与关系类型元数据不同步：' + parts.join('；'),
+    hint: '同步 references/glossary.md 的 relation_kind 小节与 scripts/graph-utils.js 的 RELATION_KIND_META'
+  };
+}
+
+// ============================================================
+// parseGlossaryFromMd  v1.4
+// ============================================================
+/**
+ * 从 glossary.md 文本解析：
+ *   - enums：所有枚举
+ *   - chapterScalarFields：章节号"标量"字段
+ *   - chapterContainerFields：章节号"容器"字段
+ *
+ * v1.4 变更：
+ *   - stripTicks 用 String.fromCharCode(96) 生成反引号字符与全局正则
+ *     （v1.3 用了含反引号的正则字面量，违反本文件零反引号约定）
+ * v1.3 变更：
+ *   - P0-1：fieldName / fieldType 统一剥离反引号（原版未剥离，章节号拦截全失效）
+ *   - P2-7：fieldType 为 计数 时不加入 chapterScalarFields
+ *   - 枚举标题正则保留 u 标志 + 中文支持
+ */
+export function parseGlossaryFromMd(mdText) {
+  const enums = {};
+  const chapterScalarFields = new Set();
+  const chapterContainerFields = new Set();
+
+  const lines = mdText.split('\n');
+  let currentEnum = null;
+  let inChapterSection = false;
+
+  // 零反引号：用 fromCharCode 生成反引号字符与全局正则
+  // BT_CHAR 是反引号字符，BT_RE 是全局匹配反引号的正则
+  const BT_CHAR = String.fromCharCode(96);
+  const BT_RE = new RegExp(BT_CHAR, 'g');
+  const stripTicks = (s) => (s || '').replace(BT_RE, '').trim();
+
+  for (const line of lines) {
+    if (line.startsWith('## 六、')) {
+      inChapterSection = true;
+      currentEnum = null;
+      continue;
+    }
+    if (line.startsWith('## 七、')) {
+      inChapterSection = false;
+      continue;
+    }
+
+    if (inChapterSection) {
+      if (line.trim().startsWith('|')) {
+        const cells = line.split('|').map(c => c.trim());
+        if (cells.length < 4) continue;
+        // P0-1：剥离反引号
+        const fieldName = stripTicks(cells[1]);
+        const fieldType = stripTicks(cells[2]);
+        if (!fieldName || fieldName === '字段名' || /^[-:]+$/.test(fieldName)) continue;
+        const leaf = fieldName.split('.').pop().replace(/\[\]$/, '').trim();
+        if (!leaf) continue;
+        if (fieldType === '区间') {
+          chapterContainerFields.add(leaf);
+        } else if (fieldType === '计数') {
+          // P2-7：计数是章数不是第几章，不加入标量检查
+          continue;
+        } else {
+          chapterScalarFields.add(leaf);
+        }
+      }
+      continue;
+    }
+
+    // 枚举标题：支持英文名 + 中文括注，也支持纯中文
+    const headerMatch = line.match(/^####\s+([\w\u4e00-\u9fa5]+)/u);
+    if (headerMatch) {
+      currentEnum = headerMatch[1];
+      enums[currentEnum] = [];
+      continue;
+    }
+    if (line.startsWith('## ') || line.startsWith('### ')) {
+      currentEnum = null;
+      continue;
+    }
+    if (!currentEnum) continue;
+    if (line.trim().startsWith('|')) {
+      const cells = line.split('|').map(c => c.trim());
+      if (cells.length < 3) continue;
+      const val = cells[1];
+      if (!val || val === '值' || /^[-:]+$/.test(val)) continue;
+      enums[currentEnum].push(val);
+    }
+  }
+
+  for (const k of Object.keys(enums)) {
+    enums[k] = [...new Set(enums[k])];
+  }
+
+  return {
+    enums: enums,
+    chapterScalarFields: [...chapterScalarFields],
+    chapterContainerFields: [...chapterContainerFields]
+  };
+}
+
+/**
+ * 解析词表并校验解析结果可用。
+ *
+ * 章节号字段集是靠匹配 glossary.md 的 `## 六、` / `## 七、` 字面前缀 +
+ * "区间"/"计数" 精确类型串提取的。一旦词表标题被改动、表格列数变化，
+ * 字段集会静默变成空集 —— 所有 *_CHAPTER_FORBIDDEN 检查随之失效，
+ * 而脚本不会报任何错。这里显式兜底，避免"检查被静默禁用"。
+ */
+export function parseGlossaryChecked(mdText) {
+  const parsed = parseGlossaryFromMd(mdText);
+  if (parsed.chapterScalarFields.length === 0 && parsed.chapterContainerFields.length === 0) {
+    return {
+      error: '章节号字段清单解析为空：glossary.md 的「六、章节号字段清单」小节标题或表格列数可能已变更，' +
+             '导致 SKELETON_CHAPTER_FORBIDDEN / FLESH_CHAPTER_FORBIDDEN / RHYTHM_CHAP_RANGE 检查失效。' +
+             '请恢复该小节（表头需为：| 字段名 | 类型 | 含义 |，类型列取值为"单章号"/"区间"/"计数"）。'
+    };
+  }
+  if (Object.keys(parsed.enums).length === 0) {
+    return { error: '枚举表解析为空：glossary.md 的枚举小节（#### 开头）可能已变更，导致 ENUM 校验失效。' };
+  }
+  return parsed;
+}
+
+// ============================================================
+// 结构化 markdown 生成（零反引号，共享给 skeleton/flesh/rhythm）
+// ============================================================
+const BT = String.fromCharCode(96);
+const BT3 = BT + BT + BT;
+
+// 英文字段名 → 中文标签（用于 flesh/rhythm/writing JSON，这些阶段字段名是英文 ID 而非中文）
+// 设计：尽量保留原 key，输出一份中英对照，方便用户对照 JSON 源理解。
+//
+// 维护约定：本表必须覆盖 templates/{骨架,血肉,节奏}/*.json 里 structure.properties
+// 出现的每一个字段名。scripts/label-coverage.js 会逐个核对，漏一个就报错
+// （2026-10 血肉阶段产物复查时发现 283 个模板字段里有 103 个没有中文标签，
+//   产物 md 直接显示 goal / suppression_method 之类的英文 key）。
+export const FIELD_CN = {
+  // 通用（跨阶段通用）
+  id: 'ID', name: '名称', description: '描述', type: '类型', notes: '备注', meta: '元数据',
+  kind: '种类', level: '层级', scale: '范围', pattern: '正则',
+  // 选题输入（input_snapshot）
+  book_name: '书名', genre: '题材', core_summary: '一句话故事', core_conflict: '核心冲突',
+  hard_constraints: '硬门禁', anti_tropes: '反套路',
+  // 容量（capacity）
+  target_chapters: '目标章节', target_words: '目标字数', avg_words_per_chapter: '平均每章字数',
+  // 角色数量（character_counts）
+  protagonist: '主角数', core_supporting: '核心配角数', volume_supporting: '卷级配角数',
+  core_antagonist: '核心反派数', volume_antagonist: '卷级反派数',
+  // 冲突数量（conflict_counts）
+  core: '核心冲突数', phase: '阶段冲突数', branch: '交织冲突数',
+  // 伏笔/爽点/高潮 size
+  small: '小', medium: '中', large: '大',
+  // 世界观规则计数
+  information: '信息规则数', social: '社会规则数',
+  // 配额（quota）
+  volume_count: '卷数', branch_count: '支线数', main_line_count: '主线数',
+  faction_count: '势力数', faction_relation_count: '势力关系对数',
+  location_count: '地点数', ending_count: '结局数',
+  protagonist_count: '主角数', core_supporting_count: '核心配角数',
+  volume_supporting_count: '卷级配角数', core_antagonist_count: '核心反派数',
+  volume_antagonist_count: '卷级反派数', core_conflict_count: '核心冲突数',
+  phase_conflict_count: '阶段冲突数', branch_conflict_count: '交织冲突数',
+  small_foreshadow_count: '小伏笔数', medium_foreshadow_count: '中伏笔数',
+  large_foreshadow_count: '大伏笔数',
+  small_climax_count: '小高潮数', medium_climax_count: '中高潮数', large_climax_count: '大高潮数',
+  small_pleasure_count: '小爽点数', medium_pleasure_count: '中爽点数', large_pleasure_count: '大爽点数',
+  core_item_count: '核心道具数', branch_item_count: '支线道具数', symbolic_item_count: '象征道具数',
+  key_location_count: '关键地点数',
+  // 公式推导
+  formula: '公式', range_low: '区间下界', range_high: '区间上界', note: '备注',
+  // 卷比例
+  volume_id: '对应卷', chapter_ratio: '章节比例',
+  // 节奏参数
+  chapter_hook_rate: '钩子率', rate: '比例', is_minimum: '是否强制下限',
+  // 时序映射字段（key_nodes、appear_start/end 等）
+  node_type: '节点类型', stage_name: '阶段名', event_ref: '事件引用',
+  appear_start: '出场开始章', appear_end: '出场结束章',
+  // 通用 ID
+  char_id: '角色 ID', conflict_id: '冲突 ID', fs_id: '伏笔 ID',
+  climax_id: '高潮 ID', pleasure_id: '爽点 ID', main_id: '主线 ID',
+  branch_id: '支线 ID', loc_id: '地点 ID', item_id: '道具 ID', ending_id: '结局 ID',
+  hook_id: '钩子 ID',
+  // 关系节点
+  main_antagonist_side: '主要对手阵营',
+  // 通用字段（跨阶段）
+  age_group: '年龄段', gender: '性别', category: '类别',
+  scale: '范围', level: '层级', rule_conflict_plan: '规则冲突预案',
+  // 角色相关
+  characters: '角色', gender: '性别', age_group: '年龄段',
+  goals: '目标', short_term: '短期', medium_term: '中期', long_term: '长期',
+  core_flaw: '核心缺陷', golden_finger: '金手指',
+  information_state: '信息状态', known_secrets: '已知秘密', unknown_secrets: '未知秘密', false_beliefs: '错误信念',
+  arc_type: '弧光类型', arc_stages: '弧光阶段数', arc_change_descriptions: '弧光变化描述',
+  language_profile: '语言档案', catchphrases: '口头禅', sentence_style: '句式风格',
+  vocabulary_preference: '用词偏好', dialogue_examples: '对话示例',
+  relationships: '关系', exit_chapter_estimate: '退场章节预估', appearance_plan: '出场计划',
+  // 冲突相关
+  conflicts: '冲突', protagonist_side: '主角阵营', main_antagonist: '主要对手',
+  secondary_antagonist: '次要对手', third_party: '第三方',
+  // 冲突参与者下的 conflict 字段（ID 引用）
+  conflict: '所属冲突',
+  participating_characters: '参与角色', conflict_type: '冲突类型',
+  escalation_path: '升级路径', termination: '收束方法', related_information_gaps: '相关信息差',
+  // 势力相关
+  factions: '势力', faction_goal: '势力目标', resources: '资源',
+  internal_structure: '内部结构', suppression_methods: '压制手段', members: '成员',
+  member_name: '成员名', position: '职位', loyalty: '忠诚度',
+  // 剧情相关
+  plot: '剧情', main_drive: '主线驱动', branch_goals: '支线目标',
+  // 地点相关
+  locations: '地点', spatial_features: '空间特征', key_events: '关键事件',
+  narrative_function: '叙事作用', atmosphere: '氛围',
+  // 结局相关
+  endings: '结局', ending_type: '结局类型', conflict_resolution: '冲突解决',
+  anti_trope_notes: '反套路说明', linger: '余韵', chapter_design: '章节设计',
+  foreshadow_recovery_plan: '伏笔回收计划',
+  // 世界观规则
+  world_rules: '世界观规则', rule_content: '规则内容', scope: '适用范围',
+  exceptions: '例外情况', protagonist_impact: '对主角影响',
+  information_rules: '信息规则', social_rules: '社会规则',
+  cost: '代价', info_source: '信息来源', interruptibility: '可干扰性',
+  // 关键道具
+  items: '道具', symbolism: '象征意义', usage_scenes: '使用场景',
+  appearance: '外观', origin: '来历', functional_detail: '功能详情',
+  limit_cost: '限制/代价', related_characters: '涉及角色', related_conflict: '涉及冲突',
+  item_type: '道具类型', category: '类别',
+  // 节奏相关（rhythm）
+  hook: '钩子', rising_action: '上升动作', climax: '高潮', falling_action: '下降动作',
+  resolution: '收尾', chapter_hook_type: '钩子类型', pleasure_type: '爽点类型',
+  recovery_point: '回收点', foreshadow_id: '伏笔 ID', pleasure_id: '爽点 ID',
+  climax_id: '高潮 ID', hook_id: '钩子 ID', chapter_id: '章节 ID',
+  // 元数据
+  capacity: '容量', input_snapshot: '输入快照', quota: '配额',
+  derivations: '推导记录', volume_ratio: '卷比例',
+  branches: '支线', foreshadows: '伏笔', climaxes: '高潮', pleasures: '爽点',
+  // 节奏文件特殊字段
+  main_lines: '主线', main_progress: '主线进度', branch_progress: '支线进度',
+  interweave_chapters: '交织章节', branch_chapter_total: '支线章节总数',
+  main_progress_chapter_count: '主线节点章节数', overlap_chapter_count: '重叠章节数',
+  // 关系字段（骨架关系.json）
+  from: '起点', to: '终点', relation_kind: '关系类型', relation_type: '关系类型',
+  member_relation: '成员关系', position_level: '职位层级',
+  conflicts_with: '涉及冲突', owner_kind: '归属类型', owner_id: '归属 ID',
+  volume_ratio_target: '卷比例目标', location: '地点', item: '道具',
+  ending: '结局', main_line: '主线',
+  character: '角色', faction: '势力', chapter: '章节', theme_short: '主题简述',
+  act_index: '幕索引', arc_id: '弧光 ID', chapter_range: '章节范围',
+  // 血肉角色弧光
+  arc_changes: '弧光变化', end: '终态', changes: '变化列表', exit: '退场',
+  expected_volume: '预期卷', experience_count: '经历次数',
+  appearance: '出场', behavior_repeat_points: '行为重复要点',
+  catchphrase: '口头禅', exclusive_needs: '排他需求',
+  identity_wording: '身份措辞', info_preference: '信息偏好',
+  memory_points: '记忆要点', behavior_repeat_logic: '行为重复逻辑',
+  emotional_baseline: '情绪基线', motivation_logic: '动机逻辑',
+  speech_samples: '话语样例', taboos: '禁忌', beats: '节拍',
+  // 血肉冲突/势力/剧情/地点/结局/世界观/道具补充
+  protagonist_paradox: '主角悖论', paradox: '悖论',
+  trigger_chapter: '触发章节', resolution_chapter: '解决章节',
+  related_factions: '相关势力', entry_pressure: '进入压制',
+  exit_pressure: '退出压制', leader: '领袖', deputy: '副手',
+  financial: '财务', territory: '地盘', recruitment: '招募',
+  decision_making: '决策机制', intel_network: '情报网',
+  economy: '经济来源', resource_composition: '资源构成',
+  event_log: '事件日志', geostrategic: '地缘战略',
+  branches_anchored: '支线锚点', branch_goals_summary: '支线目标摘要',
+  // 节奏
+  chapter_appearances: '章节出场', arc_id_linked: '关联弧光 ID',
+  chapter_id_start: '起始章节', chapter_id_end: '结束章节',
+  // 节奏参数/时序映射/细纲
+  branch_chapter_total: '支线章节总数', main_progress_chapter_count: '主线节点章节数',
+  overlap_chapter_count: '重叠章节数', branch_chapter_feasible: '支线章节可行约束',
+  branch_chapter_ratio: '支线占比约束', overlap_le_branch: '重叠 <= 支线',
+  overlap_le_main: '重叠 <= 主线', main_progress_ge_1: '主线节点 ≥ 1',
+  main_progress_consistency: '主线节点一致', main_progress_le_T: '主线节点 ≤ T',
+  chapter_volume: '章节-卷对应', chapter_act: '章节-幕对应',
+  main_progress: '主线进度', branch_progress: '支线进度',
+  hook_chapter: '钩子章节', foreshadow_chapter: '伏笔章节',
+  pleasure_chapter: '爽点章节', climax_chapter: '高潮章节',
+  ending_chapter: '结局章节', volume_summary: '卷汇总',
+  // 章节细纲特有
+  function_main: '主要功能', function_aux: '辅助功能', emotion_value: '情绪值',
+  emotion_phase: '情绪阶段', satisfaction_type: '爽点类型', satisfaction_scale: '爽点规模',
+  satisfaction_audience: '爽点受众', foreshadow_action: '伏笔动作',
+  faction_appearance: '势力出场', hook_head: '章首钩', hook_tail: '章尾钩',
+  hook_strength: '钩子强度', word_target: '目标字数',
+  // 节奏章节
+  scene_focus: '场景焦点', ch: '章节号', act: '幕',
+  // 顶层计数桶（用作 key 时）
+  character_counts: '角色数量', conflict_counts: '冲突数量', foreshadow_counts: '伏笔数量',
+  climax_counts: '高潮数量', pleasure_counts: '爽点数量', world_rule_counts: '世界观规则数量',
+  item_counts: '道具数量', symbolic: '象征',
+  // relations 9 类顶层
+  character_relations: '角色关系', faction_membership: '势力成员', conflict_participants: '冲突参与',
+  branch_protagonist: '支线主角', item_owner: '道具归属', location_conflict: '地点冲突',
+  ending_character: '结局角色', main_line_branch_relation: '主线支线交织',
+  main_line_span: '主线卷分布', branch_span: '支线卷分布', acts: '幕',
+  // ---- 模板字段全集补齐（2026-10 血肉阶段产物复查）----
+  // 以下 key 全部来自 templates/{骨架,血肉,节奏}/*.json 的 structure.properties，
+  // 此前遗漏，产物 md 里会直接显示英文 key。scripts/label-coverage.js 守住不再回退。
+  // 血肉 · 世界观规则
+  content: '规则内容', applicable_scope: '适用范围', exception: '例外情况',
+  impact_on_protagonist: '对主角影响', violation_consequence: '违规后果',
+  impact_on_plot: '对剧情影响', contradiction: '矛盾点', solution: '解决方案',
+  core_rules: '核心规则',
+  // 血肉 · 关键道具
+  function: '功能', relation: '关联', core_items: '核心道具', branch_items: '支线道具',
+  symbolic_items: '象征道具', symbolic_meaning: '象征意义', usage_scenario: '使用场景',
+  details: '道具详情', limit: '限制',
+  // 血肉 · 冲突
+  core_goal: '核心目标', influence_scope: '影响范围', focus_points: '焦点',
+  surface_contradiction: '表层矛盾', deep_contradiction: '深层矛盾',
+  ultimate_contradiction: '终极矛盾', resolution_plan: '收束方案', method: '方式',
+  residual_impact: '余波影响', information_gaps: '信息差', info_name: '信息差名称',
+  who_knows: '谁知道', who_does_not_know: '谁不知道', resolution_method: '解决方式',
+  // 血肉 · 剧情
+  goal: '目标', main_relation: '主线关系', expected_outcome: '预期结果',
+  // 血肉 · 势力
+  suppression_method: '压制手段', resource_seizure_path: '资源夺取路径',
+  main_line_connection: '与主线的关系', position_description: '职位描述',
+  relation_description: '关系描述', relations: '势力关系', target_name: '对象名称',
+  // 血肉 · 地点
+  features: '特征', layout: '布局', key_elements: '关键要素',
+  key_event_descriptions: '关键事件描述', narrative_role_description: '叙事作用描述',
+  // 血肉 · 结局
+  conflict_summary: '冲突概述', anti_trope_design: '反套路设计', aftermath: '余波',
+  special_remaining: '特别留白', character_destinations: '角色去向',
+  suspense_blanks: '悬念留白', emotion_trajectory: '情绪轨迹', core_emotion: '核心情绪',
+  final_point: '最终落点', climax_design: '高潮设计', turning_design: '转折设计',
+  cost_design: '代价设计', resolution_design: '收尾设计', memorable_scenes: '难忘场景',
+  epilogue_hints: '尾声伏笔',
+  // 血肉 · 角色
+  start: '起始', turning: '转折', midpoint: '中段', speech_rhythm: '语速节奏',
+  stance: '立场', personality_tone: '性格基调', relationship_stage_tone: '关系阶段语气',
+  mirror_type: '镜像类型', stage: '阶段', personality: '性格',
+  presentation_method: '呈现方式',
+  // 骨架 · 层级
+  volumes: '卷列表',
+  // 节奏 · 时序映射
+  character_timeline: '角色时序', conflict_timeline: '冲突时序',
+  foreshadow_timeline: '伏笔时序', climax_timeline: '高潮时序',
+  pleasure_timeline: '爽点时序', hook_timeline: '钩子时序',
+  main_line_timeline: '主线时序', branch_timeline: '支线时序',
+  location_timeline: '地点时序', item_timeline: '道具时序', ending_timeline: '结局时序',
+  exit_chapter: '退场章节', escalation_nodes: '升级节点', created: '埋设章节',
+  resolved: '解决章节', buried_chapter: '埋设章节', recovered_chapter: '回收章节',
+  key_nodes: '关键节点', interweaves: '交织', foreshadow_recovery: '伏笔回收',
+  // 节奏 · 章节规划 / 章节细纲
+  chapters: '章节数组', outlines: '章节细纲',
+  // 模板字段名与旧表拼写不一致的"孪生键"（手维护表漂移出来的，2026-10 补齐）
+  conflict_solution: '冲突解决',   // 旧键名 conflict_resolution
+  core_drive: '主线驱动',           // 旧键名 main_drive
+  faction_relations: '势力关系',
+  function_detail: '功能详情',      // 旧键名 functional_detail
+  info_gaps: '信息差',              // 旧键名 information_gaps
+  related_conflicts: '涉及冲突'     // 旧键名 related_conflict
+};
+
+// 上下文相关的 key→label（不同父 key 同一字段名有不同语义）
+export const CONTEXTUAL_LABEL = {
+  'derivations': { formula: '公式', range_low: '区间下界', range_high: '区间上界', note: '备注' },
+  'conflict_counts': { core: '核心冲突数', branch: '交织冲突数' },
+  'foreshadow_counts': { small: '小伏笔数', medium: '中伏笔数', large: '大伏笔数' },
+  'climax_counts': { small: '小高潮数', medium: '中高潮数', large: '大高潮数' },
+  'pleasure_counts': { small: '小爽点数', medium: '中爽点数', large: '大爽点数' },
+  'item_counts': { core: '核心道具数', branch: '支线道具数', symbolic: '象征道具数' },
+  'world_rule_counts': { core: '核心规则数', information: '信息规则数', social: '社会规则数' },
+  'character_counts': { protagonist: '主角', core_supporting: '核心配角', volume_supporting: '卷级配角',
+    core_antagonist: '核心反派', volume_antagonist: '卷级反派' },
+  // 节奏章节中的 volume 字段（章节归属卷）
+  'chapters': { volume: '归属卷', act: '归属幕', scene_focus: '场景焦点' },
+  // 关系中的 character/faction 字段（关系对象引用）
+  'character_relations': { from: '起点角色', to: '终点角色' },
+  'faction_membership': { character: '成员角色', member_relation: '意义', position_level: '职位' },
+  'conflict_participants': { conflict: '所属冲突' },
+  'branch_protagonist': { branch: '所属支线', character: '支线主角' },
+  'item_owner': { item: '所属道具', owner_id: '归属 ID', owner_kind: '归属类型' },
+  'location_conflict': { location: '所属地点' },
+  'ending_character': { ending: '所属结局', character: '角色' },
+  'main_line_branch_relation': { main_line: '主线', branch: '支线' },
+  // 层级中的卷字段
+  'main_line_span': { volume: '归属卷', main_line: '主线', chapter_ratio: '章节占比' },
+  'branch_span': { volume: '归属卷', branch: '支线', chapter_ratio: '章节占比' },
+  'acts': { volume: '归属卷', act_index: '幕索引', theme_short: '主题简述' },
+  'volumes': { id: 'ID', name: '卷名称', theme_short: '主题简述' },
+  // 同名不同义：goal 在势力里是"势力目标"，在支线里是"支线目标"
+  'factions': { goal: '势力目标', relations: '势力关系' },
+  'branches': { goal: '支线目标' },
+  'main_lines': { goal: '主线目标' },
+  // 势力成员 / 势力关系（血肉阶段人读描述层）
+  'members': { name: '姓名', position_description: '职位描述', relation_description: '关系描述' },
+  'relations': { target_name: '对象名称', description: '关系描述' },
+  // 角色关系（血肉阶段人读描述层）
+  'relationships': { target_name: '关系对象', relationship_type: '关系类型', description: '关系描述' },
+  // 关系里 conflicts 指"该实体涉及的冲突"，与冲突档案顶层的 conflicts 不同义
+  'item_owner': { item: '所属道具', owner_id: '归属 ID', owner_kind: '归属类型', conflicts: '涉及冲突' },
+  'location_conflict': { location: '所属地点', conflicts: '涉及冲突' },
+  // 收束方法在两条路径下语义不同
+  'escalation_path': { method: '收束方法' },
+  'memorable_scenes': { method: '实现方式' }
+};
+
+// 上下文感知的 cnLabel：传入父 key 返回更精确的中文标签
+export function cnLabelCtx(key, parentKey) {
+  if (parentKey && CONTEXTUAL_LABEL[parentKey] && CONTEXTUAL_LABEL[parentKey][key]) {
+    return CONTEXTUAL_LABEL[parentKey][key];
+  }
+  return FIELD_CN[key] || key;
+}
+
+// 把英文 key 翻译为中文（如果映射表里有）。
+// cnLabelCtx(key, parentKey) —— 第一个参数是字段名，第二个是父级 key（用于上下文相关翻译）。
+function cnLabel(key) {
+  return FIELD_CN[key] || key;
+}
+
+/**
+ * 在一组候选名里找"最可能是想写的那个"。
+ *
+ * 借鉴 llm_wiki 的 lint 建议算法（src/lib/lint-structural-core.ts）：
+ * 编辑距离 + 中文单字修正。中文实体名普遍 2-5 字，单个汉字区分度太低
+ * （"人"能匹配任何含"人"的页），所以单字名一律不参与匹配。
+ *
+ * 判定刻意保守 —— 宁可不给建议，也不要给错建议：
+ *   - 候选名与目标等长：差 1 个字才算疑似
+ *   - 长度差 1：最多差 2 个字才算
+ *   - 长度差 >= 2：不算
+ *   - 候选名是单字：不算
+ *
+ * @param {string} value 写错的名字
+ * @param {Iterable<string>} candidates 候选名集合
+ * @returns {{name: string, distance: number}|null}
+ */
+export function suggestClosestName(value, candidates) {
+  if (!value || typeof value !== 'string') return null;
+  const target = value.trim();
+  if (target.length <= 1) return null;
+  let best = null;
+  for (const cand of candidates) {
+    if (!cand || typeof cand !== 'string') continue;
+    const name = cand.trim();
+    if (!name || name === target) continue;
+    if (name.length <= 1) continue;
+    const diff = Math.abs(name.length - target.length);
+    if (diff > 1) continue;
+    const d = levenshtein(target, name);
+    const ok = diff === 0 ? d === 1 : d <= 2;
+    if (!ok) continue;
+    if (!best || d < best.distance || (d === best.distance && name.length > best.name.length)) {
+      best = { name: name, distance: d };
+    }
+  }
+  return best;
+}
+
+/** 编辑距离（Levenshtein） */
+export function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let cur = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    const tmp = prev;
+    prev = cur;
+    cur = tmp;
+  }
+  return prev[n];
+}
+
+// 安全转义：避免字段值含 markdown 控制符破坏渲染
+export function mdEscape(s) {
+  if (s === null || s === undefined) return '';
+  const str = String(s);
+  return str.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+// 判断"纯对象"（非 null、非数组的对象）
+function isPlainObject(x) {
+  return x !== null && typeof x === 'object' && !Array.isArray(x);
+}
+
+/**
+ * 单个值的行内文本。
+ *
+ * 铁律：对象绝不能直接 String()。String(obj) 出来是 "[object Object]"，
+ * 2026-10 的血肉产物 md 里 members / relations / details 全是这个。
+ * 这里给对象一个兜底的可读身份（name / id / title / label），
+ * 连身份都没有时列出字段名，保证产物里永远不出现 [object Object]。
+ */
+function inlineValue(x) {
+  if (Array.isArray(x)) return x.map(inlineValue).join('、');
+  if (isPlainObject(x)) {
+    const ident = x.name || x.id || x.title || x.label || x.key;
+    if (ident) return mdEscape(ident);
+    const keys = Object.keys(x);
+    return keys.length ? '{' + keys.join('、') + '}' : '{}';
+  }
+  return mdEscape(x);
+}
+
+/**
+ * 渲染"数组值"（某个字段的值是数组时的统一处理）。
+ *
+ * 规则：
+ *   - 全标量 → 顿号分隔的一行
+ *   - 含对象   → 对象元素展开成缩进子条目（父字段是条目，子元素是子弹条，层级不塌）
+ *   - 混合     → 标量行内 + 对象展开成缩进子条目
+ */
+export function renderArrayValue(arr, indent, key, label) {
+  if (!Array.isArray(arr)) return '';
+  const pad = ' '.repeat(indent);
+  const head = '- **' + label + '**（' + key + '）';
+  if (arr.length === 0) return pad + head + ': _(空数组)_\n';
+  const objs = arr.filter(isPlainObject);
+  const scalars = arr.filter(x => !isPlainObject(x));
+  if (objs.length === 0) {
+    return pad + head + ': ' + scalars.map(inlineValue).join('、') + '\n';
+  }
+  // 父字段必须始终保留一条标题行：否则对象元素会直接挂到上一个字段下面，
+  // 从属关系就丢了（2026-10 血肉产物复查时发现 members 标题整个消失）。
+  let out = pad + head;
+  if (scalars.length) out += ': ' + scalars.map(inlineValue).join('、');
+  out += '\n';
+  // indexOffset：混合数组里对象元素的下标要跟原数组对齐（"#N" 兜底名才不会错位）
+  const firstObjIdx = arr.findIndex(isPlainObject);
+  out += renderArrayItems(objs, indent + 2, key, firstObjIdx);
+  return out;
+}
+
+// 渲染一个对象（用缩进的子项列表）。
+// parentKey 是当前对象所在父字段的 key；用于上下文相关字段标签（如 conflict_counts.core vs item_counts.core）。
+export function renderObject(obj, indent, parentKey) {
+  if (obj === null || obj === undefined || typeof obj !== 'object') return '';
+  const pad = ' '.repeat(indent);
+  let out = '';
+  for (const [k, v] of Object.entries(obj)) {
+    const label = cnLabelCtx(k, parentKey);
+    if (Array.isArray(v)) {
+      out += renderArrayValue(v, indent, k, label);
+    } else if (typeof v === 'object' && v !== null) {
+      out += pad + '- **' + label + '**（' + k + '）\n' + renderObject(v, indent + 2, k);
+    } else {
+      out += pad + '- **' + label + '**（' + k + '）: ' + mdEscape(v) + '\n';
+    }
+  }
+  return out;
+}
+
+/**
+ * 取数组元素的"身份"：优先 id，其次 name，再次 from→to 关系对，
+ * 再到各阶段特有的外键（ch / character / faction / item / location / ending / main_line / branch / volume_id），
+ * 最后退化成数组序号。
+ */
+function arrayItemIdentity(item, index, indexOffset) {
+  let id = item.id;
+  let idDesc = '';
+  if (!id && item.name) id = item.name;
+  if (!id && item.from && item.to) { id = item.from + '→' + item.to; idDesc = item.relation_kind || item.relation_type || item.member_relation || ''; }
+  if (!id && item.ch !== undefined && typeof item.ch === 'number') id = '第' + String(item.ch).padStart(3, '0') + '章';
+  if (!id && item.character) id = item.character;
+  if (!id && item.faction) id = item.faction;
+  if (!id && item.item) id = item.item;
+  if (!id && item.location) id = item.location;
+  if (!id && item.ending) id = item.ending;
+  if (!id && item.main_line) id = item.main_line + '×' + item.branch;
+  if (!id && item.branch) id = item.branch;
+  if (!id && item.volume_id) id = item.volume_id;  // 卷比例数组
+  if (!id) id = '#' + (index + 1 + indexOffset);
+  return { id: String(id), idDesc: idDesc, name: item.name };
+}
+
+// 渲染数组元素内部的字段（不含元素自身的标题行）
+function renderArrayItemBody(item, indent, parentKey) {
+  const pad = ' '.repeat(indent);
+  let out = '';
+  const fields = Object.entries(item).filter(([k]) => k !== 'id' && k !== 'name');
+  for (const [k, v] of fields) {
+    const label = cnLabelCtx(k, parentKey);
+    if (Array.isArray(v)) {
+      out += renderArrayValue(v, indent, k, label);
+    } else if (typeof v === 'object' && v !== null) {
+      out += pad + '- **' + label + '**（' + k + '）\n';
+      out += renderObject(v, indent + 2, k);
+    } else {
+      out += pad + '- **' + label + '**（' + k + '）: ' + mdEscape(v) + '\n';
+    }
+  }
+  return out;
+}
+
+/**
+ * 嵌套数组的元素：渲染成缩进子弹条（而不是 H4 标题）。
+ *
+ * 为什么不用 H4：字段标题本身已经是一条 bullet，如果元素也是 H4，
+ * 两级就塌成同级，markdown 里 "#### 成员" 和 "#### 柳砚屏" 变成兄弟节点，
+ * 人读和 LLM 读都会丢掉从属关系。
+ */
+export function renderArrayItems(arr, indent, parentKey, indexOffset = 0) {
+  if (!Array.isArray(arr) || arr.length === 0) return '';
+  const pad = ' '.repeat(indent);
+  let out = '';
+  for (const [i, item] of arr.entries()) {
+    if (!isPlainObject(item)) continue;
+    const ident = arrayItemIdentity(item, i, indexOffset);
+    out += pad + '- **' + mdEscape(ident.id) + '**';
+    if (ident.idDesc) out += '（' + ident.idDesc + '）';
+    if (ident.name && ident.name !== ident.id) out += ' — ' + mdEscape(ident.name);
+    out += '\n';
+    out += renderArrayItemBody(item, indent + 2, parentKey);
+  }
+  return out;
+}
+
+// 渲染一个数组：元素为对象时用 H4 详情展开；标量数组用 inline list
+// 顶层数组走这里（元素是 H4）；嵌套数组走 renderArrayItems（元素是子弹条）。
+export function renderArray(arr, indent, parentKey, indexOffset = 0) {
+  if (!Array.isArray(arr) || arr.length === 0) return '';
+  const pad = ' '.repeat(indent);
+  let out = '';
+  const objs = arr.filter(isPlainObject);
+  const scalars = arr.filter(x => !isPlainObject(x));
+  // 标量元素行内一行（混合数组时对象元素另行展开，标量不能被 String(obj) 毁掉）
+  if (scalars.length) {
+    out += pad + scalars.map(inlineValue).join('、') + '\n';
+  }
+  if (objs.length === 0) return out;
+  for (const [i, item] of arr.entries()) {
+    if (!isPlainObject(item)) continue;
+    const ident = arrayItemIdentity(item, i, indexOffset);
+    out += pad + '#### ' + ident.id;
+    if (ident.idDesc) out += ' （' + ident.idDesc + '）';
+    if (ident.name && ident.name !== ident.id) out += ' — ' + mdEscape(ident.name);
+    out += '\n\n';
+    out += renderArrayItemBody(item, indent, parentKey);
+    out += '\n';
+  }
+  return out;
+}
+
+// ============================================================
+// flesh / rhythm 阶段的 dispatcher：把单文件 JSON 按"已知顶层数组"切分 H2 分组
+// ============================================================
+
+// 血肉文件 → 顶层数组配置（用于血肉 .json dispatcher）
+// key 是文件名（模板/血肉/<名字>模板.json），value 是该文件里真实的顶层数组字段。
+// 两者必须与模板严格一致，否则该文件会整份落到"其他字段"兜底渲染里，结构分组全丢。
+// （历史缺陷：势力的 faction_relations 并不存在；世界观规则漏了 rule_conflict_plan。）
+export const FLESH_DISPATCH = {
+  '角色': ['characters'],
+  '冲突': ['conflicts'],
+  '势力': ['factions'],
+  '剧情': ['main_lines', 'branches'],
+  '地点': ['locations'],
+  '结局': ['endings'],
+  '世界观规则': ['core_rules', 'information_rules', 'social_rules', 'rule_conflict_plan'],
+  '关键道具': ['core_items', 'branch_items', 'symbolic_items', 'details']
+};
+
+// 节奏文件 → 顶层数组配置
+// 节奏参数.json 里全是标量与对象（没有数组），留空数组 → 走通用渲染。
+// （历史缺陷：metrics / feasibility / coverage 三个字段在模板里根本不存在，
+//   时序映射的 11 个字段名也全是旧的，真实字段是 *_timeline。）
+export const RHYTHM_DISPATCH = {
+  '章节规划': ['chapters'],
+  '节奏参数': [],
+  '时序映射': ['character_timeline', 'conflict_timeline', 'foreshadow_timeline',
+              'climax_timeline', 'pleasure_timeline', 'hook_timeline',
+              'main_line_timeline', 'branch_timeline', 'location_timeline',
+              'item_timeline', 'ending_timeline'],
+  '章节细纲': ['outlines']
+};
+
+// 数组 → 中文 H2 标题映射
+const ARR_CN = {
+  characters: '角色档案', conflicts: '冲突档案', factions: '势力档案', faction_relations: '势力关系（血肉）',
+  main_lines: '主线', branches: '支线',
+  locations: '地点档案', endings: '结局档案',
+  core_rules: '核心规则', information_rules: '信息规则', social_rules: '社会规则',
+  core_items: '核心道具', branch_items: '支线道具', symbolic_items: '象征道具', details: '道具详情',
+  chapters: '章节数组', metrics: '节奏指标', feasibility: '可行性约束', coverage: '覆盖校验',
+  outlines: '章节细纲',
+  character_timeline: '角色时序', conflict_timeline: '冲突时序',
+  foreshadow_timeline: '伏笔时序', climax_timeline: '高潮时序',
+  pleasure_timeline: '爽点时序', hook_timeline: '钩子时序',
+  main_line_timeline: '主线时序', branch_timeline: '支线时序',
+  location_timeline: '地点时序', item_timeline: '道具时序', ending_timeline: '结局时序',
+  rule_conflict_plan: '规则冲突方案',
+  chapter_volume: '章节归属卷', chapter_act: '章节归属幕',
+  hook_chapter: '钩子章节映射', foreshadow_chapter: '伏笔章节映射',
+  pleasure_chapter: '爽点章节映射', climax_chapter: '高潮章节映射', ending_chapter: '结局章节映射',
+  volume_summary: '卷汇总'
+};
+
+// 渲染血肉/节奏文件：按文件类型 → 顶层 H2 → 数组元素 H4
+export function renderByFileType(data, fileType, dispatchMap) {
+  const arrKeys = dispatchMap[fileType] || [];
+  if (arrKeys.length === 0) {
+    // 未识别文件类型，走通用渲染
+    return renderObject(data, 0);
+  }
+  let out = '';
+  for (const key of arrKeys) {
+    const arr = data[key];
+    if (!Array.isArray(arr) || arr.length === 0) continue;
+    const label = ARR_CN[key] || cnLabelCtx(key, null);
+    out += '## ' + label + '（' + arr.length + ' 项）\n\n';
+    out += renderArray(arr, 0, key) + '\n';
+  }
+  // 残留字段（如有）
+  const extraKeys = Object.keys(data).filter(k => !arrKeys.includes(k));
+  if (extraKeys.length > 0) {
+    out += '## 其他字段\n\n' + renderObject(Object.fromEntries(extraKeys.map(k => [k, data[k]])), 0) + '\n';
+  }
+  return out;
+}
+
+export function renderFleshByFileType(data, fileType) {
+  return renderByFileType(data, fileType, FLESH_DISPATCH);
+}
+
+export function renderRhythmByFileType(data, fileType) {
+  return renderByFileType(data, fileType, RHYTHM_DISPATCH);
+}
+
+// ============================================================
+// 摘要生成：把上游 JSON 压缩成"id+name"列表注入 prompt
+// ============================================================
+import { readFileSync as _readFileSync, existsSync as _existsSync } from 'node:fs';
+import { join as _join } from 'node:path';
+
+/**
+ * 从阶段目录里的 JSON 文件提取所有 id+name 对，每行一类。
+ * 用法：summarizeStage(阶段目录) → "角色（3）：C001 陆子仲，C002 老王..."
+ */
+export function summarizeStage(stageDir) {
+  if (!_existsSync(stageDir)) return '(阶段目录不存在)';
+
+  const fileMap = {
+    '框架': ['框架.json'],
+    '实体': ['实体.json'],
+    '关系': ['关系.json'],
+    '层级': ['层级.json'],
+    '角色': ['角色.json'],
+    '冲突': ['冲突.json'],
+    '势力': ['势力.json'],
+    '剧情': ['剧情.json'],
+    '地点': ['地点.json'],
+    '结局': ['结局.json'],
+    '世界观规则': ['世界观规则.json'],
+    '关键道具': ['关键道具.json'],
+    '章节规划': ['章节规划.json'],
+    '节奏参数': ['节奏参数.json'],
+    '时序映射': ['时序映射.json'],
+    '章节细纲': ['章节细纲.json']
+  };
+
+  let out = '';
+  for (const [label, filenames] of Object.entries(fileMap)) {
+    for (const fn of filenames) {
+      const fp = _join(stageDir, fn);
+      if (!_existsSync(fp)) continue;
+      try {
+        const data = JSON.parse(_readFileSync(fp, 'utf-8'));
+        const lines = summarizeObject(data);
+        if (lines) out += lines + '\n';
+      } catch { /* ignore */ }
+    }
+  }
+  return out || '(没有可摘要的字段)';
+}
+
+/**
+ * 包装一个检查函数，把内部异常转成结构化错误。
+ *
+ * 专用检查假定数据已通过模板校验（类型正确），但模板校验收集到的 TYPE 错误
+ * 并不会阻止专用检查继续跑；一旦数据结构不符（例如数组被写成对象），
+ * 专用检查就会抛未捕获异常，整个脚本没有 JSON 输出、只剩 Node 堆栈。
+ * 这里统一兜底，保证任何畸形输入都得到可解析的结构化结果。
+ */
+export function safeCheck(name, fn, errors) {
+  try {
+    fn();
+    return true;
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    errors.push({
+      code: 'CHECK_CRASHED',
+      path: name,
+      message: '检查项 ' + name + ' 执行异常：' + msg,
+      hint: '通常是数据字段类型与模板不符（先看本批的 TYPE 错误）'
+    });
+    return false;
+  }
+}
+
+/**
+ * 读取阶段目录的 .stage-status.json，判断该阶段是否已通过全量校验。
+ *
+ * 阶段门禁的机器可判定部分。此前这个判定只写在提示词里，脚本从不读取上游状态，
+ * 导致"上游没通过全量校验"照样能往下跑。
+ *
+ * 返回 { ok, reason, status }：
+ *   ok=false 时 reason 说明具体原因（可直接作为错误信息）
+ */
+export function readStageGate(stageDir) {
+  const p = _join(stageDir, '.stage-status.json');
+  if (!_existsSync(p)) {
+    return { ok: false, reason: '缺少 .stage-status.json（该阶段还没跑过校验）', status: null };
+  }
+  let s;
+  try {
+    s = JSON.parse(_readFileSync(p, 'utf-8'));
+  } catch (e) {
+    return { ok: false, reason: '.stage-status.json 解析失败：' + e.message, status: null };
+  }
+  if (!s || typeof s !== 'object') {
+    return { ok: false, reason: '.stage-status.json 内容不是对象', status: null };
+  }
+  const all = s.all_check;
+  if (!all || typeof all !== 'object') {
+    return { ok: false, reason: '.stage-status.json 缺 all_check（未做全量校验）', status: s };
+  }
+  if (all.status !== 'PASSED') {
+    return {
+      ok: false,
+      reason: '上游阶段未通过全量校验（all_check.status=' + (all.status || '缺失') + '）',
+      status: s
+    };
+  }
+  return { ok: true, reason: null, status: s };
+}
+
+/**
+ * 在一批上游目录里找出阶段目录（含 .stage-status.json 的那个）。
+ * 血肉阶段的 --upstream 指向骨架目录，节奏阶段指向骨架+血肉两个目录。
+ */
+export function findStageDirWithStatus(dirs, stageName) {
+  for (const d of dirs || []) {
+    if (_existsSync(_join(d, '.stage-status.json'))) return d;
+  }
+  return null;
+}
+
+export function summarizeSkeleton(skeletonDir) {
+  return summarizeStage(skeletonDir);
+}
+
+export function summarizeFlesh(fleshDir) {
+  return summarizeStage(fleshDir);
+}
+
+export function summarizeRhythm(rhythmDir) {
+  return summarizeStage(rhythmDir);
+}
+
+// ============================================================
+// 任务输入快照（血肉 / 节奏阶段的「一、任务输入」数据源）
+// ============================================================
+
+/**
+ * 读取骨架阶段的 input_snapshot（任务输入快照）。
+ *
+ * 为什么不用会话参数拼：
+ *   骨架阶段已经把用户给的任务输入固化成了 框架.json 里的一份可校验快照
+ *   （骨架校验器会检查它跟骨架模板一致），血肉/节奏阶段直接读这份快照，
+ *   比在提示词里另拼一份更权威，也不会出现"两边字段数对不上"。
+ *   2026-10 之前血肉提示词只注入了书名/题材/目标章节/一句话故事 4 项，
+ *   硬门禁、反套路、核心冲突全丢给 LLM 猜。
+ *
+ * 返回 null 表示"骨架还没产出框架.json 或没有 input_snapshot"，
+ * 调用方需要自己决定兜底策略（不能静默当成空输入）。
+ */
+export function readInputSnapshot(skeletonDir) {
+  const p = _join(skeletonDir, '框架.json');
+  if (!_existsSync(p)) return null;
+  let data;
+  try {
+    data = JSON.parse(_readFileSync(p, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+  if (!data || typeof data !== 'object') return null;
+  const snap = data.input_snapshot;
+  if (!snap || typeof snap !== 'object' || Array.isArray(snap)) return null;
+  const cap = (data.capacity && typeof data.capacity === 'object') ? data.capacity : {};
+  return {
+    book_name: snap.book_name,
+    genre: snap.genre,
+    core_summary: snap.core_summary,
+    core_conflict: snap.core_conflict,
+    hard_constraints: Array.isArray(snap.hard_constraints) ? snap.hard_constraints : [],
+    anti_tropes: Array.isArray(snap.anti_tropes) ? snap.anti_tropes : [],
+    target_chapters: cap.target_chapters,
+    target_words: cap.target_words
+  };
+}
+
+// 任务输入里各字段的中文名（渲染成提示词里的清单）
+const INPUT_FIELD_CN = {
+  book_name: '书名', genre: '题材', core_summary: '一句话故事', core_conflict: '核心冲突',
+  target_chapters: '目标章节', target_words: '目标字数'
+};
+// 列表型字段（渲染成编号清单）
+const INPUT_LIST_CN = {
+  hard_constraints: '硬门禁',
+  anti_tropes: '反套路'
+};
+
+/**
+ * 把任务输入快照渲染成提示词里的一节 markdown。
+ *
+ * 输出形如：
+ *   - 书名：XXX
+ *   - 题材：XXX
+ *   - 目标章节：800
+ *   - 目标字数：2400000
+ *   - 一句话故事：XXX
+ *   - 核心冲突：XXX
+ *   - 硬门禁：
+ *     1. ...
+ *   - 反套路：
+ *     1. ...
+ */
+export function renderInputSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return '_(任务输入快照缺失)_\n';
+  const lines = [];
+  for (const [k, label] of Object.entries(INPUT_FIELD_CN)) {
+    const v = snapshot[k];
+    if (v === undefined || v === null || v === '') continue;
+    lines.push('- ' + label + '：' + String(v).replace(/\n/g, ' '));
+  }
+  for (const [k, label] of Object.entries(INPUT_LIST_CN)) {
+    const v = snapshot[k];
+    if (!Array.isArray(v) || v.length === 0) continue;
+    lines.push('- ' + label + '：');
+    v.forEach((item, i) => {
+      lines.push('  ' + (i + 1) + '. ' + String(item).replace(/\n/g, ' '));
+    });
+  }
+  return lines.length ? lines.join('\n') + '\n' : '_(任务输入快照为空)_\n';
+}
+
+// 摘要里单个数组的最大条目数（防御性上限；正常数据远小于此值，
+// T=1000 的极限骨架全量 id+name 约 8.7KB，不会触顶）
+const SUMMARY_MAX_ITEMS = 2000;
+
+// id+name 列表的分隔符。
+// 2026-10 之前用中文逗号，但实体名本身经常带逗号（"断口对上的那一刻，第二次"），
+// 分隔符和内容混在一起，LLM 根本分不清哪段是名字、哪段是下一个条目。
+// 竖线在中文标题里几乎不会出现，用它做分隔能一眼切开。
+const SUMMARY_ITEM_SEP = ' | ';
+
+// 关系型行的外键字段（按固定顺序拼接成 "A→B" 形式，保留关系两端）
+const RELATION_ID_KEYS = [
+  'main_line', 'branch', 'character', 'faction', 'conflict',
+  'item', 'location', 'ending', 'volume', 'owner_id'
+];
+
+/**
+ * 从一个数组元素里提取可读身份。
+ * 优先级：id → ch → 关系对(from→to) → 专用外键（main_line/branch/...）
+ * 覆盖骨架 4 个文件与血肉/节奏各文件里全部已知的行结构，
+ * 避免"文件里明明有数据、摘要里却整段丢失"的情况。
+ */
+function identityOf(it) {
+  if (it.id !== undefined && it.id !== null && it.id !== '') {
+    return { id: String(it.id), chSuffix: '' };
+  }
+  if (it.ch !== undefined && it.ch !== null) {
+    return { id: String(it.ch), chSuffix: '章' };
+  }
+  if (it.from && it.to) {
+    const rel = it.relation_kind || it.relation_type || it.member_relation || it.relation || '';
+    return { id: it.from + '→' + it.to + (rel ? '(' + rel + ')' : ''), chSuffix: '' };
+  }
+  const parts = [];
+  for (const k of RELATION_ID_KEYS) {
+    if (it[k] !== undefined && it[k] !== null && it[k] !== '') parts.push(String(it[k]));
+  }
+  if (parts.length) {
+    const extra = it.act_index !== undefined && it.act_index !== null ? '#' + it.act_index : '';
+    return { id: parts.join('→') + extra, chSuffix: '' };
+  }
+  return null;
+}
+
+/**
+ * 提取可读名称。没有 name 字段的行结构按语义补一个极简标识，
+ * 让 LLM 至少能从摘要看出"这一行大概是什么"。
+ */
+function nameOf(it, key) {
+  if (it.name) return it.name;
+  if (key === 'chapters') {
+    const parts = [];
+    if (it.volume) parts.push(it.volume);
+    if (it.act !== undefined && it.act !== null) parts.push('幕' + it.act);
+    if (it.scene_focus) parts.push(it.scene_focus);
+    return parts.join(' ');
+  }
+  if (key === 'outlines') {
+    const parts = [];
+    if (it.function_main) parts.push(it.function_main);
+    if (it.satisfaction_type) parts.push(it.satisfaction_type);
+    if (it.hook_head) parts.push(it.hook_head);
+    return parts.join('/');
+  }
+  if (it.scene_focus) return it.scene_focus;
+  if (it.theme_short) return it.theme_short;
+  if (it.role) return it.role;
+  if (it.title) return it.title;
+  return '';
+}
+
+/**
+ * quota 的分组标签。
+ *
+ * 2026-10 之前 quota 被 walk() 扁平化成 "volume_count=8，main_line_count=1，……"
+ * 一长串英文 key 挤在一行，注入 prompt 后 LLM 很难一眼读出"有多少角色/多少高潮"。
+ * 现在按"顶层标量 / 计数桶"分组，每组一行，标签用中文。
+ */
+const QUOTA_GROUP_CN = {
+  character_counts: '角色',
+  conflict_counts: '冲突',
+  foreshadow_counts: '伏笔',
+  climax_counts: '高潮',
+  pleasure_counts: '爽点',
+  item_counts: '道具',
+  world_rule_counts: '世界观规则'
+};
+
+// 各计数桶内部的成员名（比 FIELD_CN 更短，桶名已经说明了"数"，不需要再写一遍）
+const QUOTA_ITEM_CN = {
+  character_counts: {
+    protagonist: '主角', core_supporting: '核心配角', volume_supporting: '卷级配角',
+    core_antagonist: '核心反派', volume_antagonist: '卷级反派'
+  },
+  conflict_counts: { core: '核心', phase: '阶段', branch: '交织' },
+  foreshadow_counts: { small: '小', medium: '中', large: '大' },
+  climax_counts: { small: '小', medium: '中', large: '大' },
+  pleasure_counts: { small: '小', medium: '中', large: '大' },
+  item_counts: { core: '核心', branch: '支线', symbolic: '象征' },
+  world_rule_counts: { core: '核心', information: '信息', social: '社会' }
+};
+
+/**
+ * 骨架/框架里的非数组标量（capacity / quota）也要进摘要：
+ * 写作阶段需要 T、V、章均字数；节奏阶段需要各实体配额。
+ */
+function summarizeScalars(data) {
+  const lines = [];
+  const cap = data.capacity;
+  if (cap && typeof cap === 'object') {
+    const parts = [];
+    if (cap.target_chapters != null) parts.push('T=' + cap.target_chapters);
+    if (cap.target_words != null) parts.push('总字数=' + cap.target_words);
+    if (cap.avg_words_per_chapter != null) parts.push('章均字数=' + cap.avg_words_per_chapter);
+    if (parts.length) lines.push('capacity: ' + parts.join('，'));
+  }
+  const quota = data.quota;
+  if (quota && typeof quota === 'object') {
+    // 顶层标量配额（卷数、主线数、支线数……）单独一行
+    const flat = [];
+    const groups = [];
+    for (const [k, v] of Object.entries(quota)) {
+      if (v && typeof v === 'object' && !Array.isArray(v)) {
+        groups.push([k, v]);
+      } else if (typeof v === 'number') {
+        flat.push((FIELD_CN[k] || k) + '=' + v);
+      }
+    }
+    if (flat.length) lines.push('quota 规模: ' + flat.join('、'));
+    for (const [gk, gv] of groups) {
+      const items = [];
+      for (const [k, v] of Object.entries(gv)) {
+        if (typeof v !== 'number') continue;
+        const label = (QUOTA_ITEM_CN[gk] && QUOTA_ITEM_CN[gk][k]) || FIELD_CN[k] || k;
+        items.push(label + '=' + v);
+      }
+      if (!items.length) continue;
+      lines.push('quota ' + (QUOTA_GROUP_CN[gk] || FIELD_CN[gk] || gk) + ': ' + items.join('、'));
+    }
+  }
+  return lines;
+}
+
+function summarizeObject(data, depth = 0) {
+  // 顶层是 dict，含若干数组
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return '';
+  const lines = summarizeScalars(data);
+  for (const [key, val] of Object.entries(data)) {
+    if (!Array.isArray(val)) continue;
+    // 数组
+    const items = val.filter(x => x && typeof x === 'object');
+    if (items.length === 0) continue;
+
+    // 提取每个元素的 id+name 缩略
+    const summaries = [];
+    for (const it of items) {
+      const ident = identityOf(it);
+      if (!ident) continue;
+      const nm = nameOf(it, key);
+      summaries.push(`${ident.id}${nm ? ' ' + nm : ''}${ident.chSuffix}`);
+      if (summaries.length >= SUMMARY_MAX_ITEMS) break;
+    }
+
+    if (summaries.length === 0) continue;
+    const truncated = items.length > summaries.length;
+    lines.push(
+      `${key}（${items.length}）: ${summaries.join(SUMMARY_ITEM_SEP)}` +
+      (truncated ? `...（仅列出前 ${summaries.length} 条）` : '')
+    );
+  }
+  return lines.join('\n');
+}