@cloud411716/fancy-webnovel 1.0.45 → 2.2.0

package/plugins/fancy-story-builder/scripts/semantic-lint.js

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+/**
+ * semantic-lint.js —— 血肉阶段的语义检查（LLM 层）
+ *
+ * 对照 llm_wiki 的实现（src/lib/lint.ts）：
+ *   runStructuralLint  → fancy-story-builder 的 flesh-validate.js（确定性检查）
+ *   runSemanticLint    → 本文件（LLM 检查，可选开启）
+ *
+ * 为什么要有这一层：
+ *   flesh-validate 的 37 个错误码全是**结构**检查 —— id 在不在、名字对不对、
+ *   枚举合不合法、配额对不对得上、关系有没有声明。都是能用脚本判死的问题。
+ *   "内容咬不咬合"没人查：同一个角色的两段描述对不对得上、
+ *   伏笔的埋设和回收是不是同一件事、关系类型和描述里的态度是不是矛盾。
+ *   这类问题只有 LLM 能查。
+ *
+ * 关键设计（都是照 llm_wiki 抄的，因为它踩过坑）：
+ *   1. **LLM 报的"缺失"必须本地复核**（对应 lint.ts:73 missingPageAlreadyExists）
+ *      LLM 不可靠地交叉引用实体列表，会把已经存在的实体报成缺失。
+ *      本地用实体表复核一遍，报错的直接丢弃。
+ *   2. **输出协议严格**（对应 lint.ts:202 LINT_BLOCK_REGEX）
+ *      ---LINT: type | severity | 标题--- ... ---END LINT---
+ *      只接受白名单里的 type / severity，其余归一到 default。
+ *   3. **"没有就不输出"**（对应 ingest.ts 的 review 提示词）
+ *      提示词里明确要求：没有值得报的就不要输出任何内容。
+ *      不然 LLM 会为了满足格式而编造问题。
+ *   4. **PAGES 指向的实体要核对**（对应 lint.ts:73 的思路，但方向相反）
+ *      LLM 可能报一个不存在的实体名，这类 finding 丢掉。
+ *
+ * 这个模块**不调 LLM**：它只负责
+ *   - 生成提示词（buildSemanticLintPrompt）
+ *   - 解析 LLM 的输出（parseLintBlocks）
+ *   - 本地复核（reviewLintFindings）
+ * 调 LLM 由插件侧（index.js）用会话模型做，跟写作阶段一个套路。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ============================================================
+// 协议
+// ============================================================
+
+// LLM 只允许报这几种类型；别的归一到 default
+export const LINT_TYPES = ['contradiction', 'missing-detail', 'stale', 'suggestion'];
+export const LINT_TYPE_DEFAULT = 'suggestion';
+
+// 严重度：error 会阻断，warning 要人看一眼，info 只是知道
+export const LINT_SEVERITIES = ['error', 'warning', 'info'];
+export const LINT_SEVERITY_DEFAULT = 'warning';
+
+/**
+ * LINT 块的解析正则。
+ *
+ * 2026-10-27 修：标题部分原来是 `([^-\n]+?)` —— **不允许出现连字符**。
+ * 于是"C001-C004 的师徒关系前后矛盾"这种完全正常的标题匹配不上，
+ * 整条 finding 被静默丢掉（模型觉得自己报过了，其实没人看到）。
+ * 现在标题允许连字符，只是不允许换行。
+ */
+const LINT_BLOCK_REGEX = /---LINT:\s*(\w[\w-]*)\s*\|\s*(\w+)\s*\|\s*([^\n]+?)\s*---\n([\s\S]*?)---END LINT---/g;
+
+/**
+ * 解析 LLM 输出的 LINT 块。
+ *
+ * 形如：
+ *   ---LINT: contradiction | warning | C001 与 C004 的师徒关系前后矛盾---
+ *   描述…
+ *   PAGES: 角色.json#C001, 角色.json#C004
+ *   ---END LINT---
+ *
+ * @returns {Array<{type,severity,title,description,pages,options,raw}>}
+ */
+export function parseLintBlocks(text) {
+  const out = [];
+  if (!text || typeof text !== 'string') return out;
+  const matches = text.matchAll(LINT_BLOCK_REGEX);
+  for (const m of matches) {
+    const rawType = m[1].trim().toLowerCase();
+    const rawSeverity = m[2].trim().toLowerCase();
+    const title = m[3].trim();
+    const body = m[4] || '';
+
+    const type = LINT_TYPES.includes(rawType) ? rawType : LINT_TYPE_DEFAULT;
+    const severity = LINT_SEVERITIES.includes(rawSeverity) ? rawSeverity : LINT_SEVERITY_DEFAULT;
+
+    const pagesMatch = body.match(/^PAGES:\s*(.+)$/m);
+    const pages = pagesMatch
+      ? pagesMatch[1].split(',').map((p) => p.trim()).filter(Boolean)
+      : [];
+    const optionsMatch = body.match(/^OPTIONS:\s*(.+)$/m);
+    const options = optionsMatch
+      ? optionsMatch[1].split('|').map((o) => o.trim()).filter(Boolean)
+      : [];
+    const description = body
+      .replace(/^PAGES:.*$/m, '')
+      .replace(/^OPTIONS:.*$/m, '')
+      .trim();
+
+    out.push({
+      type: type,
+      severity: severity,
+      title: title,
+      description: description,
+      pages: pages,
+      options: options,
+      raw: m[0]
+    });
+  }
+  return out;
+}
+
+// ============================================================
+// 本地复核
+// ============================================================
+
+/**
+ * 复核 LLM 报出来的 finding，丢掉不可信的。
+ *
+ * 丢弃规则：
+ *   1. type 是 missing-detail，但被指认的实体**已经存在** → 丢
+ *      （LLM 不可靠地交叉引用实体列表，会把已存在的报成缺失 —— llm_wiki lint.ts:73 同款）
+ *   2. PAGES 里指的实体**全都不存在** → 丢（LLM 报了不存在的实体）
+ *   3. 标题或描述为空 → 丢（没有信息量的 finding）
+ *
+ * @param {Array} findings parseLintBlocks 的结果
+ * @param {object} ctx { entityIds: Set<string>, entityNames: Set<string> }
+ * @returns {{ kept: Array, dropped: Array }}
+ */
+export function reviewLintFindings(findings, ctx) {
+  const context = ctx || {};
+  const entityIds = context.entityIds || new Set();
+  const entityNames = context.entityNames || new Set();
+  const kept = [];
+  const dropped = [];
+
+  for (const f of findings) {
+    if (!f.title || !f.description) {
+      dropped.push({ finding: f, reason: '标题或描述为空' });
+      continue;
+    }
+
+    // 1. missing-detail 复核：被指认的实体在不在
+    //
+    // "实体都存在 → 丢"是**刻意设计**，不是 bug：
+    // LLM 不可靠地交叉引用实体列表，会把已存在的实体报成"缺失"，
+    // 所以这里把这种情况整个丢掉（与 llm_wiki lint.ts:73 同款）。
+    // 代价是"实体存在但缺关键信息"这类 finding 也被一并丢掉 ——
+    // 2026-10-27 复核后确认：这是跨项目一致的取舍，不改。
+    if (f.type === 'missing-detail' && f.pages.length) {
+      const allExist = f.pages.every((p) => {
+        const key = pageKey(p);
+        return entityIds.has(key) || entityNames.has(key);
+      });
+      if (allExist) {
+        dropped.push({ finding: f, reason: 'missing-detail 指向的实体都存在，判定有误' });
+        continue;
+      }
+    }
+
+    // 2. PAGES 指向的实体得存在（至少一个）
+    if (f.pages.length) {
+      const anyExist = f.pages.some((p) => {
+        const key = pageKey(p);
+        return entityIds.has(key) || entityNames.has(key);
+      });
+      if (!anyExist) {
+        dropped.push({ finding: f, reason: 'PAGES 指向的实体都不存在' });
+        continue;
+      }
+    }
+
+    kept.push(f);
+  }
+  return { kept, dropped };
+}
+
+/** 把 "角色.json#C001" 或 "C001" 统一成实体标识 */
+function pageKey(p) {
+  if (!p) return '';
+  const s = String(p).trim();
+  const hash = s.indexOf('#');
+  return hash >= 0 ? s.slice(hash + 1).trim() : s;
+}
+
+// ============================================================
+// 提示词
+// ============================================================
+
+// 每个实体摘要里截多长。llm_wiki 取的是 frontmatter + 前 500 字符，这里取 300。
+const SUMMARY_CHARS = 300;
+
+/**
+ * 把一个血肉实体的关键字段压成一段摘要。
+ * 只取"有信息量"的字段：描述、目标、矛盾、关系等，长文本截断。
+ */
+function summarizeEntity(item, idKeys) {
+  const parts = [];
+  const textFields = [];
+  const collect = (v, prefix) => {
+    if (typeof v === 'string') {
+      if (v.trim()) textFields.push(prefix + '：' + v.trim().slice(0, SUMMARY_CHARS));
+    } else if (Array.isArray(v)) {
+      for (const x of v) collect(x, prefix);
+    } else if (v && typeof v === 'object') {
+      for (const [k, x] of Object.entries(v)) {
+        if (idKeys.has(k)) continue;
+        collect(x, prefix ? prefix + '.' + k : k);
+      }
+    }
+  };
+  for (const [k, v] of Object.entries(item)) {
+    if (k === 'id' || k === 'name') continue;
+    collect(v, k);
+  }
+  parts.push(textFields.join('；'));
+  return parts.join('');
+}
+
+/**
+ * 生成语义检查的提示词。
+ *
+ * @param {object} ctx
+ *   fleshEntities: [{ file, key, index, id, name, item }]  血肉实体
+ *   skeletonRelations: Array<{from,to,kind}>              骨架关系（id 级）
+ *   entityIds: Set<string>  entityNames: Set<string>
+ */
+export function buildSemanticLintPrompt(ctx) {
+  const context = ctx || {};
+  const fleshEntities = context.fleshEntities || [];
+  const skeletonRelations = context.skeletonRelations || [];
+  const idKeys = new Set(['id', 'name']);
+
+  const lines = [];
+  lines.push('## 血肉实体清单');
+  lines.push('');
+  for (const e of fleshEntities) {
+    const summary = summarizeEntity(e.item, idKeys);
+    lines.push('- [' + e.file + '#' + (e.id || e.name) + '] ' + e.name + (summary ? ' —— ' + summary : ''));
+  }
+
+  let relText = '';
+  if (skeletonRelations.length) {
+    const relLines = skeletonRelations.slice(0, 200).map((r) => '- ' + r.from + ' → ' + r.to + '（' + r.kind + '）');
+    relText = '\n\n## 骨架已确定的关系（不得与之矛盾）\n\n' + relLines.join('\n');
+    if (skeletonRelations.length > 200) {
+      relText += '\n- …… 其余 ' + (skeletonRelations.length - 200) + ' 条省略';
+    }
+  }
+
+  const prompt = [
+    '你是设定审校。给你一份小说血肉阶段的实体清单（来自骨架与血肉的 JSON 产物），请找出**真正的语义问题**。',
+    '',
+    '## 只报这四类问题',
+    '',
+    '- contradiction：两处描述互相矛盾（同一角色的两段说法对不上、同一件事有两种互相排斥的记述）',
+    '- missing-detail：该写但没写、导致这个实体立不住的关键信息（只报**真的缺失**，不是"可以更详细"）',
+    '- stale：内容与骨架已确定的事实冲突（骨架里角色是 X，血肉里写成 Y）',
+    '- suggestion：会实质性改善设定的建议',
+    '',
+    '## 不要报什么',
+    '',
+    '- 不要报"可以更详细""建议加强描写"这类空泛意见',
+    '- 不要报你自己不确定是不是问题的东西',
+    '- 不要重复报同一个问题',
+    '- 骨架与血肉的 id、名字、枚举、配额**已经由确定性脚本校验过了**，不要重复报这些',
+    '',
+    '## 输出格式（严格）',
+    '',
+    '每条问题一个块，块之间空行，不要输出任何其它文字：',
+    '',
+    '---LINT: <contradiction|missing-detail|stale|suggestion> | <error|warning|info> | <一句话标题>---',
+    '<两三句话说清楚：哪里矛盾 / 缺什么 / 冲突在哪，给出具体引用（写清是哪几个实体的哪句话）',
+    'PAGES: <文件名#实体id>, <文件名#实体id>',
+    '---END LINT---',
+    '',
+    '要求：',
+    '- 最多 8 条，优先高信号问题',
+    '- **如果没有值得报的问题，就不要输出任何内容**（不要为了凑数硬编）',
+    '- PAGES 里的实体 id 必须来自上面的清单',
+    '- severity：error=设定自相矛盾必须改，warning=大概率要改，info=可以斟酌',
+    '',
+    '## 待审实体清单',
+    '',
+    lines.join('\n') + relText
+  ].join('\n');
+
+  return prompt;
+}
+
+// ============================================================
+// 工具
+// ============================================================
+
+/** 从血肉目录读出实体清单（给提示词和复核用） */
+export function collectFleshEntities(fleshDir) {
+  const FILES = {
+    '角色.json': ['characters'],
+    '冲突.json': ['conflicts'],
+    '势力.json': ['factions'],
+    '剧情.json': ['main_lines', 'branches'],
+    '地点.json': ['locations'],
+    '结局.json': ['endings'],
+    '世界观规则.json': ['core_rules', 'information_rules', 'social_rules'],
+    '关键道具.json': ['core_items', 'branch_items', 'symbolic_items', 'details']
+  };
+  const entities = [];
+  for (const [file, keys] of Object.entries(FILES)) {
+    const p = path.join(fleshDir, file);
+    if (!fs.existsSync(p)) continue;
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+      continue;
+    }
+    for (const key of keys) {
+      const list = data[key];
+      if (!Array.isArray(list)) continue;
+      for (const [index, item] of list.entries()) {
+        if (!item || typeof item !== 'object') continue;
+        entities.push({
+          file: file,
+          key: key,
+          index: index,
+          id: item.id ? String(item.id) : '',
+          name: item.name ? String(item.name) : '',
+          item: item
+        });
+      }
+    }
+  }
+  return entities;
+}
+
+/** 从骨架关系表读出 id 级关系（给提示词当"不得矛盾"的事实） */
+export function collectSkeletonRelations(skeletonDir) {
+  const p = path.join(skeletonDir, '关系.json');
+  if (!fs.existsSync(p)) return [];
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const r of (data.character_relations || [])) {
+    if (r && r.from && r.to) out.push({ from: r.from, to: r.to, kind: r.relation_kind || '' });
+  }
+  for (const r of (data.faction_relations || [])) {
+    if (r && r.from && r.to) out.push({ from: r.from, to: r.to, kind: r.relation_type || '' });
+  }
+  for (const r of (data.faction_membership || [])) {
+    if (r && r.character && r.faction) out.push({ from: r.character, to: r.faction, kind: r.member_relation || '' });
+  }
+  return out;
+}
+
+/** 从骨架实体表建 id / name 集合（给本地复核用） */
+export function collectEntityKeys(skeletonDir) {
+  const p = path.join(skeletonDir, '实体.json');
+  const entityIds = new Set();
+  const entityNames = new Set();
+  if (!fs.existsSync(p)) return { entityIds, entityNames };
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return { entityIds, entityNames };
+  }
+  for (const list of Object.values(data)) {
+    if (!Array.isArray(list)) continue;
+    for (const item of list) {
+      if (!item || typeof item !== 'object') continue;
+      if (item.id) entityIds.add(String(item.id));
+      if (item.name) entityNames.add(String(item.name));
+    }
+  }
+  return { entityIds, entityNames };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * skeleton-quota.js —— 骨架阶段「配额 ↔ 实体数组」的映射（校验器与插件共用）
+ *
+ * 为什么要有这个模块：
+ *   骨架的 `框架.json.quota` 声明"每类要多少个实体"，
+ *   校验器按这张映射表核对 `quota` 与 `实体.json` 的实际条数（QUOTA_MISMATCH）。
+ *   插件要用同一张表做两件事：
+ *     1. 算每个实体数组该写几条 —— 批次规模与提示词里的条数都靠它
+ *     2. 把 `quota.xxx` 形态的错误归因回**对应实体数组**的批次
+ *        （错误 path 指向框架，但根因常常是实体写少了）
+ *
+ * 放在这里而不是让插件自己抄一份：
+ *   两边各抄一份的话，校验器改了口径插件不会跟着改，
+ *   归因就会指错地方（模型被派去改一个没问题的批次）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * quota 路径 → 实体数组 + 过滤条件。
+ *
+ * 过滤条件是"按类型/类别/量级统计"，例如
+ *   quota.character_counts.protagonist = 实际 characters 里 type==='主角' 的条数
+ */
+export const QUOTA_MAP = {
+  'character_counts.protagonist': { arr: 'characters', filter: c => c.type === '主角' },
+  'character_counts.core_supporting': { arr: 'characters', filter: c => c.type === '贯穿级核心配角' },
+  'character_counts.volume_supporting': { arr: 'characters', filter: c => c.type === '卷级重要配角' },
+  'character_counts.core_antagonist': { arr: 'characters', filter: c => c.type === '贯穿级核心反派' },
+  'character_counts.volume_antagonist': { arr: 'characters', filter: c => c.type === '卷级反派' },
+  'conflict_counts.core': { arr: 'conflicts', filter: c => c.type === '核心' },
+  'conflict_counts.phase': { arr: 'conflicts', filter: c => c.type === '阶段' },
+  'conflict_counts.branch': { arr: 'conflicts', filter: c => c.type === '交织' },
+  'faction_count': { arr: 'factions', filter: () => true },
+  'location_count': { arr: 'locations', filter: () => true },
+  'ending_count': { arr: 'endings', filter: () => true },
+  'main_line_count': { arr: 'main_lines', filter: () => true },
+  'branch_count': { arr: 'branches', filter: () => true },
+  'foreshadow_counts.small': { arr: 'foreshadows', filter: c => c.type === '小伏笔' },
+  'foreshadow_counts.medium': { arr: 'foreshadows', filter: c => c.type === '中伏笔' },
+  'foreshadow_counts.large': { arr: 'foreshadows', filter: c => c.type === '大伏笔' },
+  'climax_counts.small': { arr: 'climaxes', filter: c => c.type === '小高潮' },
+  'climax_counts.medium': { arr: 'climaxes', filter: c => c.type === '中高潮' },
+  'climax_counts.large': { arr: 'climaxes', filter: c => c.type === '大高潮' },
+  'pleasure_counts.small': { arr: 'pleasures', filter: c => c.scale === '小爽点' },
+  'pleasure_counts.medium': { arr: 'pleasures', filter: c => c.scale === '中爽点' },
+  'pleasure_counts.large': { arr: 'pleasures', filter: c => c.scale === '大爽点' },
+  'item_counts.core': { arr: 'items', filter: c => c.category === '核心道具' },
+  'item_counts.branch': { arr: 'items', filter: c => c.category === '支线道具' },
+  'item_counts.symbolic': { arr: 'items', filter: c => c.category === '象征道具' },
+  'world_rule_counts.core': { arr: 'world_rules', filter: c => c.category === '核心规则' },
+  'world_rule_counts.information': { arr: 'world_rules', filter: c => c.category === '信息规则' },
+  'world_rule_counts.social': { arr: 'world_rules', filter: c => c.category === '社会规则' }
+};
+
+/**
+ * 配额路径 → 实体数组名。
+ * 归因用：错误的 path 形如 "quota.character_counts.protagonist"，
+ * 要落到 characters 数组对应的批次上。
+ */
+const QUOTA_PATH_TO_ARRAY = {};
+for (const quotaPath of Object.keys(QUOTA_MAP)) {
+  QUOTA_PATH_TO_ARRAY[quotaPath] = QUOTA_MAP[quotaPath].arr;
+}
+
+/**
+ * 读嵌套值（支持 "a.b.c" 形态）。
+ */
+export function getNested(obj, dotted) {
+  if (!obj || typeof obj !== 'object') return undefined;
+  const parts = String(dotted).split('.');
+  let cur = obj;
+  for (const p of parts) {
+    if (!cur || typeof cur !== 'object') return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+/**
+ * 把 quota 展开成「每个实体数组的分项配额」。
+ *
+ * @param {Object} quota  框架.json 的 quota 对象
+ * @returns {Object} { characters: { protagonist: 2, core_supporting: 8 }, ... }
+ *   只包含 quota 里确实是数字的项（模型还没填的项直接不出现）
+ */
+export function quotaCountsByArray(quota) {
+  const out = {};
+  if (!quota || typeof quota !== 'object') return out;
+  for (const quotaPath of Object.keys(QUOTA_MAP)) {
+    const v = getNested(quota, quotaPath);
+    if (typeof v !== 'number' || !isFinite(v)) continue;
+    const arr = QUOTA_MAP[quotaPath].arr;
+    if (!out[arr]) out[arr] = {};
+    // 分项名取路径最后一段（character_counts.protagonist → protagonist）
+    const key = quotaPath.indexOf('.') >= 0 ? quotaPath.slice(quotaPath.lastIndexOf('.') + 1) : quotaPath;
+    out[arr][key] = v;
+  }
+  return out;
+}
+
+/**
+ * 每个实体数组的配额总数。
+ *
+ * @param {Object} quota 框架.json 的 quota 对象
+ * @returns {Object} { characters: 40, conflicts: 29, ... }
+ */
+export function quotaArrayTotals(quota) {
+  const byArray = quotaCountsByArray(quota);
+  const out = {};
+  for (const arr of Object.keys(byArray)) {
+    let n = 0;
+    for (const k of Object.keys(byArray[arr])) n += byArray[arr][k];
+    out[arr] = n;
+  }
+  return out;
+}
+
+/**
+ * 某个配额路径属于哪个实体数组（归因用）。
+ * @returns {string|null}
+ */
+export function quotaPathToArray(quotaPath) {
+  if (!quotaPath) return null;
+  return QUOTA_PATH_TO_ARRAY[quotaPath] || null;
+}
+
+/**
+ * 从框架.json 读 quota。
+ * @returns {Object} quota（读不到返回空对象）
+ */
+export function readQuota(stageDir) {
+  const data = readJsonSafe(path.join(stageDir, '框架.json'));
+  if (!data || typeof data !== 'object') return {};
+  return (data.quota && typeof data.quota === 'object') ? data.quota : {};
+}
+
+function readJsonSafe(p) {
+  try {
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}