@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-story-builder/scripts/stage-contract.js

@@ -0,0 +1,429 @@
+/**
+ * stage-contract.js  v1.0
+ * 产物契约的分节抽取 + 骨架相关关系筛选。
+ *
+ * 为什么需要分节：
+ * 血肉提示词原本 38.5KB，是一份"LLM 自己开车"的执行手册。
+ * 改成插件驱动之后，每轮只需要带：总纲 + 任务输入 + 铁律 + 本文件的字段契约
+ * + 质量正反例 + （重试时）错误码速查。按小节抽取能让每轮提示词降到
+ * 十几 KB，同时保留全部质量约束。
+ *
+ * 契约文件里的分节标记形如：<!-- contract:file:角色 -->
+ */
+
+// 分节标记：<!-- contract:名字 -->
+// 名字允许中文（例如 file:角色），所以用"非空白非尖括号"而不是 ASCII 类。
+const MARKER_RE = /<!--\s*contract:([^\s>]+)\s*-->/g;
+
+/**
+ * 把契约文件切成小节。
+ *
+ * @param {string} content 契约文件全文
+ * @returns {Object} { head, order, sections }
+ */
+export function splitContractSections(content) {
+  const text = typeof content === 'string' ? content : '';
+  const order = [];
+  const sections = {};
+  let head = '';
+  let current = null;
+  let buffer = '';
+  let lastIndex = 0;
+
+  const re = new RegExp(MARKER_RE.source, 'g');
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const chunk = text.slice(lastIndex, m.index);
+    if (current === null) head += chunk;
+    else buffer += chunk;
+    if (current !== null) {
+      sections[current] = buffer.trim();
+      buffer = '';
+    }
+    current = m[1];
+    order.push(current);
+    lastIndex = re.lastIndex;
+  }
+  const tail = text.slice(lastIndex);
+  if (current === null) head += tail;
+  else {
+    buffer += tail;
+    sections[current] = buffer.trim();
+  }
+
+  return { head: head.trim(), order: order, sections: sections };
+}
+
+/**
+ * 按名字取若干小节并拼成一段提示词。
+ *
+ * @param {string} content 契约文件全文
+ * @param {string[]} names 小节名，按给定顺序拼接
+ * @returns {Object} { text, missing }
+ */
+export function pickContractSections(content, names) {
+  const split = splitContractSections(content);
+  const parts = [];
+  const missing = [];
+  for (const name of names || []) {
+    const sec = split.sections[name];
+    if (sec === undefined || sec === '') {
+      missing.push(name);
+      continue;
+    }
+    parts.push(sec);
+  }
+  return { text: parts.join('\n\n---\n\n'), missing: missing };
+}
+
+// ============================================================
+// 骨架关系筛选
+// ============================================================
+
+/**
+ * 每张关系表用哪些字段装 id。
+ * match —— 命中任一字段即算"相关"
+ * anchor —— 有 anchor 时，必须命中 anchor 里的某个字段才算相关
+ *   （用于关系方向：character_relations 的 from 是关系发起方，
+ *    只有 from 落在本批里，血肉才需要写这条关系）
+ */
+const RELATION_TABLES = {
+  character_relations: { match: ['from', 'to'], anchor: ['from'] },
+  other_relations: { match: ['from', 'to'], anchor: null },
+  faction_membership: { match: ['character', 'faction'], anchor: null },
+  faction_relations: { match: ['from', 'to'], anchor: ['from'] },
+  conflict_participants: { match: ['conflict', 'protagonist_side', 'main_antagonist', 'secondary_antagonist', 'third_party'], anchor: null },
+  branch_protagonist: { match: ['branch', 'character'], anchor: null },
+  item_owner: { match: ['item', 'owner_id'], anchor: null },
+  location_conflict: { match: ['location', 'conflicts'], anchor: null },
+  ending_character: { match: ['ending', 'character'], anchor: null },
+  main_line_branch_relation: { match: ['main_line', 'branch'], anchor: null }
+};
+
+/**
+ * 从一条关系记录里抽出所有 id 形态的值（字符串或字符串数组）。
+ */
+function relationIds(record, fields) {
+  const out = [];
+  for (const f of fields) {
+    const v = record[f];
+    if (typeof v === 'string' && v) out.push(v);
+    else if (Array.isArray(v)) {
+      for (const x of v) if (typeof x === 'string' && x) out.push(x);
+    }
+  }
+  return out;
+}
+
+/**
+ * 筛出与本批实体相关的关系，并渲染成提示词可读的清单。
+ *
+ * @param {Object} relations  骨架 关系.json 的内容
+ * @param {Object} idToName   id -> name 映射（来自骨架 实体.json）
+ * @param {string[]} ids       本批涉及的 id 集合
+ * @returns {Object} { lines: string[], count: number }
+ */
+export function collectRelevantRelations(relations, idToName, ids) {
+  const idSet = new Set(ids || []);
+  const names = idToName || {};
+  const lines = [];
+
+  if (!relations || typeof relations !== 'object') return { lines: lines, count: 0 };
+
+  for (const table of Object.keys(RELATION_TABLES)) {
+    const spec = RELATION_TABLES[table];
+    if (!spec) continue;
+    const rows = relations[table];
+    if (!Array.isArray(rows)) continue;
+
+    const hits = [];
+    for (const row of rows) {
+      if (!row || typeof row !== 'object') continue;
+      const matchIds = relationIds(row, spec.match);
+      const matched = matchIds.filter((x) => idSet.has(x));
+      if (matched.length === 0) continue;
+      if (spec.anchor) {
+        const anchorIds = relationIds(row, spec.anchor);
+        const anchorHit = anchorIds.some((x) => idSet.has(x));
+        if (!anchorHit) continue;
+      }
+      hits.push({ row: row, ids: matchIds });
+    }
+
+    if (hits.length === 0) continue;
+
+    lines.push('**' + table + '**（' + hits.length + ' 条）');
+    for (const hit of hits) {
+      const parts = [];
+      for (const key of Object.keys(hit.row)) {
+        const v = hit.row[key];
+        if (typeof v === 'string') {
+          parts.push(key + '=' + v + nameSuffix(v, names));
+        } else if (Array.isArray(v)) {
+          parts.push(key + '=[' + v.map((x) => (typeof x === 'string' ? x + nameSuffix(x, names) : String(x))).join(', ') + ']');
+        } else if (v !== null && typeof v === 'object') {
+          parts.push(key + '=' + JSON.stringify(v));
+        } else {
+          parts.push(key + '=' + String(v));
+        }
+      }
+      // 表名写在行内，模型逐行读时不用回头对照上一行的标题
+      lines.push('- [' + table + '] ' + parts.join('；'));
+    }
+  }
+
+  return { lines: lines, count: lines.length };
+}
+
+function nameSuffix(id, names) {
+  if (!names || !names[id]) return '';
+  return '（' + names[id] + '）';
+}
+
+/**
+ * 从骨架 实体.json 里建立 id -> name 映射。
+ */
+export function buildIdToName(skeletonEntities) {
+  const map = {};
+  if (!skeletonEntities || typeof skeletonEntities !== 'object') return map;
+  for (const key of Object.keys(skeletonEntities)) {
+    const list = skeletonEntities[key];
+    if (!Array.isArray(list)) continue;
+    for (const e of list) {
+      if (!e || typeof e !== 'object') continue;
+      if (e.id && e.name) map[e.id] = e.name;
+    }
+  }
+  return map;
+}
+
+// ============================================================
+// 节奏阶段：本批章号的真源信息
+// ============================================================
+
+/**
+ * 把"本批章号在时序映射里的对应信息"渲染成提示词可读的行。
+ *
+ * 为什么必须给：节奏阶段的章节号唯一真源是 `时序映射.json`，
+ * 而 `章节细纲.json` 的 hook_head / hook_tail 必须与 hook_timeline
+ * 中该章的钩子对齐（校验器按章比对）。模型自己编章号 / 编钩子
+ * 必然对不上，只能把真源原样喂给它。
+ *
+ * @param {Object} opts
+ * @param {Object} opts.timeline   已合并的 时序映射.json
+ * @param {number[]} opts.chapters 本批要写的章号
+ * @param {Object} [opts.idToName] id -> name（骨架实体）
+ * @param {Object} [opts.climaxTypes] climax_id -> type（区分"大高潮"）
+ * @returns {Object} { lines: string[], count: number }
+ */
+export function buildRhythmChapterRefs(opts) {
+  const o = opts || {};
+  const timeline = o.timeline && typeof o.timeline === 'object' ? o.timeline : {};
+  const chapters = Array.isArray(o.chapters) ? o.chapters : [];
+  const names = o.idToName || {};
+  const climaxTypes = o.climaxTypes || {};
+  const lines = [];
+
+  const hookByCh = new Map();
+  for (const h of (timeline.hook_timeline || [])) {
+    if (h && typeof h.ch === 'number') hookByCh.set(h.ch, h);
+  }
+  const climaxByCh = new Map();
+  for (const c of (timeline.climax_timeline || [])) {
+    if (c && typeof c.chapter === 'number') {
+      if (!climaxByCh.has(c.chapter)) climaxByCh.set(c.chapter, []);
+      climaxByCh.get(c.chapter).push(c);
+    }
+  }
+  const endingByCh = new Map();
+  for (const e of (timeline.ending_timeline || [])) {
+    if (e && typeof e.chapter === 'number') {
+      if (!endingByCh.has(e.chapter)) endingByCh.set(e.chapter, []);
+      endingByCh.get(e.chapter).push(e);
+    }
+  }
+  const fsByCh = new Map();
+  for (const f of (timeline.foreshadow_timeline || [])) {
+    if (!f || typeof f !== 'object') continue;
+    for (const [ch, kind] of [[f.buried_chapter, '埋'], [f.recovered_chapter, '收']]) {
+      if (typeof ch !== 'number') continue;
+      if (!fsByCh.has(ch)) fsByCh.set(ch, []);
+      fsByCh.get(ch).push(kind + ' ' + f.fs_id + nameOf(f.fs_id, names));
+    }
+  }
+  const mainNodesByCh = new Map();
+  for (const m of (timeline.main_line_timeline || [])) {
+    for (const n of (m && m.key_nodes) || []) {
+      if (!n || typeof n.chapter !== 'number') continue;
+      if (!mainNodesByCh.has(n.chapter)) mainNodesByCh.set(n.chapter, []);
+      mainNodesByCh.get(n.chapter).push({ main_id: m.main_id, event_ref: n.event_ref });
+    }
+  }
+  const relationshipByCh = new Map();
+  for (const r of (timeline.relationship_timeline || [])) {
+    if (!r || typeof r.start_chapter !== 'number') continue;
+    if (!relationshipByCh.has(r.start_chapter)) relationshipByCh.set(r.start_chapter, []);
+    relationshipByCh.get(r.start_chapter).push(r);
+  }
+  const branchByCh = new Map();
+  for (const b of (timeline.branch_timeline || [])) {
+    if (!b || typeof b !== 'object') continue;
+    for (const [ch, kind] of [[b.start, '起'], [b.turning, '转'], [b.resolution, '收']]) {
+      if (typeof ch !== 'number') continue;
+      if (!branchByCh.has(ch)) branchByCh.set(ch, []);
+      branchByCh.get(ch).push(kind + ' ' + b.branch_id + nameOf(b.branch_id, names));
+    }
+  }
+
+  for (const ch of chapters) {
+    const parts = [];
+    const hook = hookByCh.get(ch);
+    if (hook) {
+      parts.push('钩子 头=' + str(hook.hook_head) + ' 尾=' + str(hook.hook_tail) + ' 强度=' + str(hook.hook_strength));
+    }
+    for (const c of (climaxByCh.get(ch) || [])) {
+      const type = climaxTypes[c.climax_id] ? '（' + climaxTypes[c.climax_id] + '）' : '';
+      parts.push('高潮 ' + c.climax_id + nameOf(c.climax_id, names) + type);
+    }
+    for (const e of (endingByCh.get(ch) || [])) {
+      parts.push('结局 ' + e.ending_id + nameOf(e.ending_id, names));
+    }
+    for (const n of (mainNodesByCh.get(ch) || [])) {
+      parts.push('主线节点 ' + n.main_id + nameOf(n.main_id, names) + '：' + str(n.event_ref));
+    }
+    for (const r of (relationshipByCh.get(ch) || [])) {
+      parts.push('关系阶段 ' + r.from + nameOf(r.from, names) + ' → ' + r.to + nameOf(r.to, names) +
+        '：' + str(r.stage) + ' / ' + str(r.state) +
+        (r.trigger_event ? '（触发：' + str(r.trigger_event) + '）' : ''));
+    }
+    for (const b of (branchByCh.get(ch) || [])) {
+      parts.push('支线 ' + b);
+    }
+    for (const f of (fsByCh.get(ch) || [])) {
+      parts.push('伏笔 ' + f);
+    }
+    if (!parts.length) {
+      parts.push('（时序映射里本章没有钩子/高潮/结局/主线节点记录）');
+    }
+    lines.push('- 第 ' + ch + ' 章：' + parts.join('；'));
+  }
+
+  return { lines: lines, count: lines.length };
+}
+
+function str(v) {
+  if (v === null || v === undefined) return '';
+  return String(v);
+}
+
+function nameOf(id, names) {
+  if (!id || !names || !names[id]) return '';
+  return '（' + names[id] + '）';
+}
+
+/**
+ * 渲染"上一批收尾"，让模型接着上一批往下写。
+ *
+ * 章节是按时间推进的：第 N 章要承接第 N-1 章。模型看不到上一批的产物
+ * （分片是各自独立的文件），不给收尾就会写成互不相关的片段。
+ *
+ * @param {Object} opts
+ * @param {Object} [opts.shard] 上一批的分片内容（已解析的 JSON）
+ * @param {string[]} [opts.arrayKeys] 分片里的数组名（按优先级）
+ * @returns {string|null} 收尾描述；取不到返回 null
+ */
+export function buildRhythmPrevTail(opts) {
+  const o = opts || {};
+  const shard = o.shard;
+  if (!shard || typeof shard !== 'object') return null;
+
+  // 收尾只挑"承上启下"用得上的字段
+  const FIELDS = [
+    ['ch', '章'],
+    ['volume', '卷'],
+    ['act', '幕'],
+    ['scene_focus', '场景重点'],
+    ['function_main', '主功能'],
+    ['function_aux', '辅功能'],
+    ['hook_head', '钩子头'],
+    ['hook_tail', '钩子尾'],
+    ['hook_strength', '钩子强度']
+  ];
+
+  let last = null;
+  for (const key of o.arrayKeys || []) {
+    const arr = shard[key];
+    if (Array.isArray(arr) && arr.length) {
+      last = arr[arr.length - 1];
+      break;
+    }
+  }
+  if (!last || typeof last !== 'object') return null;
+
+  const parts = [];
+  for (const [k, label] of FIELDS) {
+    if (last[k] === undefined || last[k] === null || last[k] === '') continue;
+    parts.push(label + '=' + String(last[k]));
+  }
+  if (!parts.length) return null;
+  return '上一批最后一条：' + parts.join('，');
+}
+
+/**
+ * 渲染"卷与幕 + 卷章数配额"。
+ *
+ * 为什么必须给：`章节规划.json` 的每一章都要填 `volume` 与 `act`，
+ * 而这两个值是**受约束的枚举**：
+ *   - volume 必须是骨架 `层级.json` 里的 V001 / V002 …
+ *   - act 必须是该卷 `层级.json` 的 acts 里出现过的幕序号
+ *     （校验器 RHYTHM_ACT_INVALID 逐条查）
+ *   - 每卷章数要接近 `框架.json` 的 volume_ratio（RHYTHM_VOLUME_DIST）
+ * 模型看不到这三张表就只能瞎编，编出来的卷号 100% 触发 RHYTHM_REF_MISSING。
+ *
+ * @param {Object} opts
+ * @param {Object} opts.hierarchy  骨架 层级.json
+ * @param {Object} opts.framework  骨架 框架.json
+ * @returns {Object} { lines: string[], count: number }
+ */
+export function buildRhythmSkeletonOutline(opts) {
+  const o = opts || {};
+  const hierarchy = o.hierarchy && typeof o.hierarchy === 'object' ? o.hierarchy : {};
+  const framework = o.framework && typeof o.framework === 'object' ? o.framework : {};
+  const lines = [];
+
+  // 卷 → 该卷的幕序号集合
+  const actsByVolume = new Map();
+  for (const a of (hierarchy.acts || [])) {
+    if (!a || !a.volume || typeof a.act_index !== 'number') continue;
+    if (!actsByVolume.has(a.volume)) actsByVolume.set(a.volume, new Set());
+    actsByVolume.get(a.volume).add(a.act_index);
+  }
+
+  const volumes = Array.isArray(hierarchy.volumes) ? hierarchy.volumes : [];
+  if (volumes.length) {
+    lines.push('卷与幕（骨架 层级.json，volume 只能取这里的 id，act 只能取该卷的幕序号）：');
+    for (const v of volumes) {
+      if (!v || !v.id) continue;
+      const acts = actsByVolume.get(v.id);
+      const actText = acts && acts.size ? [...acts].sort((a, b) => a - b).join('、') : '（骨架未定义）';
+      lines.push('- ' + v.id + (v.name ? '（' + v.name + '）' : '') + '：幕 ' + actText);
+    }
+  }
+
+  const ratios = Array.isArray(framework.volume_ratio) ? framework.volume_ratio : [];
+  if (ratios.length) {
+    const T = framework.capacity && typeof framework.capacity.target_chapters === 'number'
+      ? framework.capacity.target_chapters
+      : null;
+    lines.push('');
+    lines.push('卷章数配额（骨架 框架.json volume_ratio' + (T ? '，T=' + T : '') + '，实际章数与之相差超过 1 章会报 warning）：');
+    for (const r of ratios) {
+      if (!r || !r.volume_id) continue;
+      const pct = typeof r.chapter_ratio === 'number' ? Math.round(r.chapter_ratio * 100) + '%' : String(r.chapter_ratio);
+      const approx = T ? '（约 ' + Math.round(T * r.chapter_ratio) + ' 章）' : '';
+      lines.push('- ' + r.volume_id + '：' + pct + approx);
+    }
+  }
+
+  return { lines: lines, count: lines.length };
+}