@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-story-builder/scripts/v2/genre.js

@@ -0,0 +1,195 @@
+/**
+ * v2/genre.js —— 题材 profile：结构、倍率、卷级分配权重、质量阈值。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_FILE = path.join(__dirname, '..', '..', 'references', 'genre-profiles.json');
+
+export const PROFILE_ALIASES = {
+  '玄幻': 'upgrade', '仙侠': 'upgrade', '升级流': 'upgrade',
+  '都市': 'urban', '都市爽文': 'urban',
+  '悬疑': 'suspense', '推理': 'suspense', '规则怪谈': 'suspense',
+  '言情': 'romance', '情感': 'romance',
+  '群像': 'ensemble', '正剧': 'ensemble',
+  '无限流': 'infinite', '副本': 'infinite',
+  '历史': 'history', '军事': 'history',
+  '末世': 'apocalypse', '科幻': 'apocalypse',
+};
+
+const MULTIPLIER_BY_FORMULA = {
+  'character_elements.volume_supporting_count': 'volume_supporting',
+  'character_elements.volume_antagonist_count': 'volume_antagonist',
+  'conflict_elements.phase_conflict_count': 'conflicts',
+  'conflict_elements.branch_conflict_count': 'conflicts',
+  'faction_elements.faction_count': 'factions',
+  'faction_elements.faction_relation_count': 'faction_relations',
+  'location_elements.key_location_count': 'locations',
+  'foreshadow_elements.small_foreshadow_count': 'foreshadows',
+  'foreshadow_elements.medium_foreshadow_count': 'foreshadows',
+  'foreshadow_elements.large_foreshadow_count': 'foreshadows',
+  'climax_elements.small_climax_count': 'climaxes',
+  'climax_elements.medium_climax_count': 'climaxes',
+  'climax_elements.large_climax_count': 'climaxes',
+  'pleasure_elements.small_pleasure_count': 'pleasures',
+  'pleasure_elements.medium_pleasure_count': 'pleasures',
+  'pleasure_elements.large_pleasure_count': 'pleasures',
+  'item_elements.core_item_count': 'items',
+  'item_elements.branch_item_count': 'items',
+  'item_elements.symbolic_item_count': 'items',
+  'world_rule_counts.core': 'world_rules',
+  'world_rule_counts.information': 'world_rules',
+  'world_rule_counts.social': 'world_rules',
+  'fixed.character_elements.protagonist_count': 'protagonist',
+  'fixed.character_elements.core_supporting_count': 'core_supporting',
+  'fixed.character_elements.core_antagonist_count': 'core_antagonist',
+  'fixed.conflict_elements.core_conflict_count': 'conflicts',
+};
+
+export function loadGenreProfiles(projectRoot) {
+  const candidates = [];
+  if (projectRoot) candidates.push(path.join(projectRoot, 'references', 'genre-profiles.json'));
+  if (projectRoot) candidates.push(path.join(projectRoot, '设定', '00-baseline', 'genre-profiles.json'));
+  candidates.push(PLUGIN_FILE);
+  for (const file of candidates) {
+    try {
+      const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      if (data && data.profiles) {
+        const base = data.base_overrides || {};
+        for (const profile of Object.values(data.profiles)) {
+          profile.overrides = { ...base, ...(profile.overrides || {}) };
+        }
+        return data;
+      }
+    } catch {
+      // try next
+    }
+  }
+  return {
+    version: '2.1',
+    base_words_per_chapter: 2000,
+    default_profile: 'default',
+    profiles: {
+      default: {
+        label: '通用',
+        structure: { type: 'serial', volume_chapters: [40, 120], preferred_chapters_per_volume: 80, acts: { lt10: 1, '10_25': 2, gt25: 3 } },
+        multipliers: {},
+        distribution_weights: {},
+        quality: {},
+      },
+    },
+  };
+}
+
+export function detectProfileKey(topicData, profilesDoc) {
+  const profiles = (profilesDoc && profilesDoc.profiles) || {};
+  const explicit = topicData && (topicData.genre_profile || topicData.genreProfile);
+  if (explicit && profiles[explicit]) return explicit;
+  const genre = String(topicData && (topicData.genre || topicData.category) || '');
+  if (genre && profiles[genre]) return genre;
+  for (const [key, val] of Object.entries(profiles)) {
+    const aliases = (val && val.aliases) || [];
+    if (aliases.some((alias) => alias && genre.includes(alias))) return key;
+  }
+  for (const [key, val] of Object.entries(profiles)) {
+    if (val && val.label && genre.includes(val.label)) return key;
+  }
+  for (const [alias, key] of Object.entries(PROFILE_ALIASES)) {
+    if (genre.includes(alias) && profiles[key]) return key;
+  }
+  const keys = Object.keys(profiles);
+  return profiles.default ? 'default' : (keys[0] || 'default');
+}
+
+export function getProfile(profilesDoc, key) {
+  const profiles = (profilesDoc && profilesDoc.profiles) || {};
+  const base = (profilesDoc && profilesDoc.base_overrides) || {};
+  const profile = profiles[key] || profiles.default || profiles[Object.keys(profiles)[0]] || {
+    label: '通用', structure: {}, multipliers: {}, distribution_weights: {}, quality: {},
+  };
+  return { ...profile, overrides: { ...base, ...(profile.overrides || {}) } };
+}
+
+export function multiplierForFormula(key, profile) {
+  const cat = MULTIPLIER_BY_FORMULA[key];
+  if (!cat) return 1;
+  const value = profile && profile.multipliers && profile.multipliers[cat];
+  return Number.isFinite(Number(value)) ? Number(value) : 1;
+}
+
+export function multiplierForCategory(category, profile) {
+  const value = profile && profile.multipliers && profile.multipliers[category];
+  return Number.isFinite(Number(value)) ? Number(value) : 1;
+}
+
+/**
+ * 把倍率作用到区间。低值向上取整，高值向下取整；
+ * 区间为空时以低值为准，保证 LLM 始终有合法值可选。
+ */
+export function applyMultiplier(low, high, multiplier, opts = {}) {
+  const m = Number.isFinite(Number(multiplier)) && Number(multiplier) > 0 ? Number(multiplier) : 1;
+  const allowZero = Boolean(opts.allowZero);
+  const rawLow = Number(low);
+  const rawHigh = Number(high);
+  let nextLow = Math.ceil(rawLow * m);
+  let nextHigh = Math.floor(rawHigh * m);
+  if (!allowZero && rawLow > 0) nextLow = Math.max(1, nextLow);
+  if (nextHigh < nextLow) nextHigh = nextLow;
+  return { low: nextLow, high: nextHigh, multiplier: m };
+}
+
+export function structureVolumeRange(T, profile) {
+  const total = Number(T) || 0;
+  const cfg = profile && profile.structure && profile.structure.volume_chapters;
+  const minCh = cfg && Number(cfg[0]) > 0 ? Number(cfg[0]) : 40;
+  const maxCh = cfg && Number(cfg[1]) >= minCh ? Number(cfg[1]) : 120;
+  const low = Math.max(1, Math.ceil(total / maxCh));
+  const high = Math.max(low, Math.min(Math.max(1, Math.ceil(total / minCh)), 30));
+  return { low, high };
+}
+
+export function preferredVolumeCount(T, profile, low, high) {
+  const pref = Number(profile && profile.structure && profile.structure.preferred_chapters_per_volume);
+  const p = Number.isFinite(pref) && pref > 0 ? pref : 80;
+  return Math.min(high, Math.max(low, Math.round((Number(T) || 0) / p)));
+}
+
+export function actCountForChapters(chapters, profile) {
+  const n = Number(chapters) || 0;
+  const acts = (profile && profile.structure && profile.structure.acts) || {};
+  if (n < 10) return Number(acts.lt10) || 1;
+  if (n <= 25) return Number(acts['10_25']) || 2;
+  return Number(acts.gt25) || 3;
+}
+
+export function formulaOverrides(profile) {
+  return (profile && profile.overrides) || {};
+}
+
+/**
+ * 按卷位置生成权重。V=1 全是 1；V=2 用 first/last；
+ * V>=3 用 first + middle... + climax + last。
+ */
+export function distributionWeights(profile, type, V) {
+  const n = Math.max(1, Number(V) || 1);
+  const cfg = (profile && profile.distribution_weights && profile.distribution_weights[type]) || {};
+  const first = Number.isFinite(Number(cfg.first)) ? Number(cfg.first) : 1;
+  const middle = Number.isFinite(Number(cfg.middle)) ? Number(cfg.middle) : 1;
+  const climax = Number.isFinite(Number(cfg.climax)) ? Number(cfg.climax) : middle;
+  const last = Number.isFinite(Number(cfg.last)) ? Number(cfg.last) : middle;
+  if (n === 1) return [1];
+  if (n === 2) return [first, last];
+  const out = [first];
+  for (let i = 1; i < n - 2; i += 1) out.push(middle);
+  out.push(climax);
+  out.push(last);
+  return out.slice(0, n);
+}
+
+export function qualityOf(profile, key, fallback) {
+  const q = (profile && profile.quality) || {};
+  const value = q[key];
+  return value === undefined ? fallback : value;
+}

package/plugins/fancy-story-builder/scripts/v2/knowledge.js

@@ -0,0 +1,321 @@
+/**
+ * v2/knowledge.js —— 角色知识时间线。
+ *
+ * 设计原则：知识不是“某一章谁在谁不在”的静态名单，而是一条可回放的事件流：
+ *
+ *   subject_type + subject_id + character + chapter
+ *   + change（获知/部分获知/确认/纠正/遗忘/误信）
+ *   + coverage（unknown/partial/full/false）
+ *   + knowledge（具体知道了什么）
+ *   + how（亲眼看到/他人告知/推断/文书/传闻/亲身经历/其他）
+ *   + source_character / scene / evidence
+ *
+ * 只要按章节顺序回放事件，就能知道每个角色在任意章节结束时到底知道什么。
+ * 这样“第 10 章已经知道，第 20 章又写不知道”会在结构化数据层直接报错。
+ */
+import { asArray } from './core.js';
+
+export const KNOWLEDGE_SUBJECT_TYPES = ['information', 'foreshadow'];
+export const KNOWLEDGE_STATES = ['unknown', 'partial', 'full', 'false'];
+export const KNOWLEDGE_CHANGES = ['learns', 'partially_learns', 'confirms', 'corrects', 'forgets', 'misinforms'];
+export const KNOWLEDGE_HOWS = ['witnessed', 'told', 'inferred', 'document', 'rumor', 'experience', 'other', 'none'];
+
+export function knowledgeKey(subjectType, subjectId, character) {
+  return [subjectType, subjectId, character].map(String).join('|');
+}
+
+export function eventKey(event) {
+  return [event && event.subject_type, event && event.subject_id, event && event.character, event && event.change, event && event.coverage].map(String).join('|');
+}
+
+export function stateAfterChange(change, coverage) {
+  if (coverage) return coverage;
+  if (change === 'forgets') return 'unknown';
+  if (change === 'misinforms') return 'false';
+  if (change === 'confirms') return 'full';
+  if (change === 'partially_learns') return 'partial';
+  return 'full';
+}
+
+function infoIds(cast) {
+  return new Set(asArray(cast && cast.information && cast.information.information_gaps).map((g) => g && g.id).filter(Boolean));
+}
+
+function foreshadowIds(cast) {
+  return new Set(asArray(cast && cast.foreshadows && cast.foreshadows.foreshadows).map((g) => g && g.id).filter(Boolean));
+}
+
+function charIds(cast) {
+  return new Set(asArray(cast && cast.characters && cast.characters.characters).map((c) => c && c.id).filter(Boolean));
+}
+
+function knownCharacters(value) {
+  return new Set(asArray(value).map(String));
+}
+
+/** 从 30-cast 的初始知识/旧版 who_knows 生成时间线起点。 */
+export function initialKnowledgeStates(cast) {
+  const states = new Map();
+  for (const gap of asArray(cast && cast.information && cast.information.information_gaps)) {
+    if (!gap || !gap.id) continue;
+    const rows = asArray(gap.initial_knowledge);
+    if (rows.length) {
+      for (const row of rows) {
+        if (!row || !row.character) continue;
+        states.set(knowledgeKey('information', gap.id, row.character), {
+          state: KNOWLEDGE_STATES.includes(row.state) ? row.state : 'unknown',
+          coverage: KNOWLEDGE_STATES.includes(row.coverage) ? row.coverage : (row.state || 'unknown'),
+          knowledge: row.knowledge || '',
+          how: row.how || 'none',
+          source_character: row.source_character || null,
+          scene: row.scene || '',
+          evidence: row.evidence || '',
+          chapter: 0,
+        });
+      }
+      continue;
+    }
+    // 旧版字段的语义：who_knows = 开篇已完全知道；who_does_not_know = 不知道。
+    for (const character of knownCharacters(gap.who_knows)) {
+      states.set(knowledgeKey('information', gap.id, character), {
+        state: 'full', coverage: 'full', knowledge: gap.info_name || '', how: 'none',
+        source_character: null, scene: '', evidence: '', chapter: 0,
+      });
+    }
+    for (const character of knownCharacters(gap.who_does_not_know)) {
+      const key = knowledgeKey('information', gap.id, character);
+      if (!states.has(key)) {
+        states.set(key, {
+          state: 'unknown', coverage: 'unknown', knowledge: '不知道这条信息', how: 'none',
+          source_character: null, scene: '', evidence: '', chapter: 0,
+        });
+      }
+    }
+  }
+  for (const fs of asArray(cast && cast.foreshadows && cast.foreshadows.foreshadows)) {
+    if (!fs || !fs.id) continue;
+    for (const row of asArray(fs.initial_knowledge)) {
+      if (!row || !row.character) continue;
+      states.set(knowledgeKey('foreshadow', fs.id, row.character), {
+        state: KNOWLEDGE_STATES.includes(row.state) ? row.state : 'unknown',
+        coverage: KNOWLEDGE_STATES.includes(row.coverage) ? row.coverage : (row.state || 'unknown'),
+        knowledge: row.knowledge || '',
+        how: row.how || 'none',
+        source_character: row.source_character || null,
+        scene: row.scene || '',
+        evidence: row.evidence || '',
+        chapter: 0,
+      });
+    }
+  }
+  return states;
+}
+
+export function validateInitialKnowledge(rows, ctx = {}) {
+  const errors = [];
+  const warnings = [];
+  const characters = charIds(ctx.cast);
+  const seen = new Set();
+  asArray(rows).forEach((row, index) => {
+    const p = (ctx.path || 'initial_knowledge') + '[' + index + ']';
+    if (!row || !row.character) {
+      errors.push({ code: 'KNOWLEDGE_INITIAL_CHARACTER', path: p + '.character', message: '初始知识必须写人物' });
+      return;
+    }
+    if (!characters.has(row.character)) {
+      errors.push({ code: 'KNOWLEDGE_INITIAL_CHARACTER_REF', path: p + '.character', message: '初始知识引用了不存在的人物：' + row.character });
+    }
+    const key = String(row.character);
+    if (seen.has(key)) errors.push({ code: 'KNOWLEDGE_INITIAL_DUP', path: p + '.character', message: '同一人物重复登记初始知识：' + row.character });
+    seen.add(key);
+    if (!KNOWLEDGE_STATES.includes(row.state)) {
+      errors.push({ code: 'KNOWLEDGE_INITIAL_STATE', path: p + '.state', message: '初始知识状态必须是 unknown/partial/full/false', actual: row.state });
+    }
+    if (!KNOWLEDGE_HOWS.includes(row.how || 'none')) {
+      errors.push({ code: 'KNOWLEDGE_INITIAL_HOW', path: p + '.how', message: '初始知识的来源方式不合法', actual: row.how });
+    }
+    if ((row.how === 'told') && !row.source_character) {
+      errors.push({ code: 'KNOWLEDGE_INITIAL_SOURCE', path: p + '.source_character', message: 'how=told 时必须写 source_character' });
+    }
+    if (row.source_character && !characters.has(row.source_character)) {
+      errors.push({ code: 'KNOWLEDGE_INITIAL_SOURCE_REF', path: p + '.source_character', message: '初始知识来源人物不存在：' + row.source_character });
+    }
+    if (!row.knowledge || !String(row.knowledge).trim()) {
+      warnings.push({ code: 'KNOWLEDGE_INITIAL_EMPTY', path: p + '.knowledge', message: '初始知识没有写具体知道/不知道什么' });
+    }
+  });
+  return { errors, warnings };
+}
+
+/** 单条知识事件的结构校验。 */
+export function validateKnowledgeEvent(event, ctx = {}) {
+  const errors = [];
+  const warnings = [];
+  const p = ctx.path || 'knowledge_events';
+  if (!event || typeof event !== 'object') {
+    errors.push({ code: 'KNOWLEDGE_EVENT_OBJECT', path: p, message: '知识事件必须是对象' });
+    return { errors, warnings };
+  }
+  if (!KNOWLEDGE_SUBJECT_TYPES.includes(event.subject_type)) {
+    errors.push({ code: 'KNOWLEDGE_SUBJECT_TYPE', path: p + '.subject_type', message: 'subject_type 必须是 information/foreshadow', actual: event.subject_type });
+  }
+  const subjectSet = event.subject_type === 'information' ? infoIds(ctx.cast) : foreshadowIds(ctx.cast);
+  if (!event.subject_id || !subjectSet.has(event.subject_id)) {
+    errors.push({ code: 'KNOWLEDGE_SUBJECT_REF', path: p + '.subject_id', message: '知识事件引用了不存在的对象：' + event.subject_id });
+  }
+  if (!event.character || !charIds(ctx.cast).has(event.character)) {
+    errors.push({ code: 'KNOWLEDGE_CHARACTER_REF', path: p + '.character', message: '知识事件引用了不存在的人物：' + event.character });
+  }
+  if (!KNOWLEDGE_CHANGES.includes(event.change)) {
+    errors.push({ code: 'KNOWLEDGE_CHANGE', path: p + '.change', message: 'change 必须是 learns/partially_learns/confirms/corrects/forgets/misinforms', actual: event.change });
+  }
+  if (!KNOWLEDGE_STATES.includes(event.coverage)) {
+    errors.push({ code: 'KNOWLEDGE_COVERAGE', path: p + '.coverage', message: 'coverage 必须是 unknown/partial/full/false', actual: event.coverage });
+  } else {
+    const expected = {
+      learns: ['partial', 'full'],
+      partially_learns: ['partial'],
+      confirms: ['full'],
+      corrects: ['partial', 'full'],
+      forgets: ['unknown'],
+      misinforms: ['false'],
+    }[event.change] || [];
+    if (expected.length && !expected.includes(event.coverage)) {
+      errors.push({ code: 'KNOWLEDGE_COVERAGE_CHANGE', path: p + '.coverage', message: 'change 与 coverage 不匹配', expected: expected.join('/'), actual: event.coverage });
+    }
+  }
+  if (!KNOWLEDGE_HOWS.includes(event.how)) {
+    errors.push({ code: 'KNOWLEDGE_HOW', path: p + '.how', message: 'how 必须是 witnessed/told/inferred/document/rumor/experience/other', actual: event.how });
+  }
+  if (event.how === 'told' && !event.source_character) {
+    errors.push({ code: 'KNOWLEDGE_SOURCE', path: p + '.source_character', message: 'how=told 时必须写 source_character' });
+  }
+  if (event.source_character && !charIds(ctx.cast).has(event.source_character)) {
+    errors.push({ code: 'KNOWLEDGE_SOURCE_REF', path: p + '.source_character', message: '来源人物不存在：' + event.source_character });
+  }
+  if (event.source_character && event.source_character === event.character) {
+    errors.push({ code: 'KNOWLEDGE_SOURCE_SELF', path: p + '.source_character', message: '来源人物不能是自己' });
+  }
+  if (!event.knowledge || !String(event.knowledge).trim()) {
+    errors.push({ code: 'KNOWLEDGE_WHAT', path: p + '.knowledge', message: '必须写清楚角色具体知道了什么' });
+  }
+  if (!event.scene || !String(event.scene).trim()) {
+    warnings.push({ code: 'KNOWLEDGE_SCENE', path: p + '.scene', message: '建议写清楚在什么场景/地点知道' });
+  }
+  if (!event.evidence || !String(event.evidence).trim()) {
+    warnings.push({ code: 'KNOWLEDGE_EVIDENCE', path: p + '.evidence', message: '建议写清楚依据/看到/听到了什么' });
+  }
+  if (ctx.chapter && event.character && ctx.chapter.cast && !asArray(ctx.chapter.cast).map(String).includes(String(event.character))
+    && !asArray(ctx.chapter.mentioned).map(String).includes(String(event.character))) {
+    warnings.push({ code: 'KNOWLEDGE_CHARACTER_NOT_PRESENT', path: p + '.character', message: '人物既不在本章出场也不在提及列表里' });
+  }
+  return { errors, warnings };
+}
+
+/** 回放全书知识事件，返回每个章节结束时的知识快照。 */
+export function replayKnowledge(chapters, cast) {
+  const states = initialKnowledgeStates(cast);
+  const snapshots = new Map();
+  const events = [];
+  const errors = [];
+  const warnings = [];
+  const sorted = [...asArray(chapters)].sort((a, b) => Number(a.display_no) - Number(b.display_no));
+  for (const chapter of sorted) {
+    const displayNo = Number(chapter.display_no);
+    for (const event of asArray(chapter.knowledge_events)) {
+      const checked = validateKnowledgeEvent(event, { cast, chapter, path: 'chapter_map.chapters[' + (displayNo - 1) + '].knowledge_events' });
+      errors.push(...checked.errors);
+      warnings.push(...checked.warnings);
+      const key = knowledgeKey(event.subject_type, event.subject_id, event.character);
+      const previous = states.get(key) || { state: 'unknown', coverage: 'unknown' };
+      const nextState = stateAfterChange(event.change, event.coverage);
+      const basePath = 'chapter_map.chapters[' + (displayNo - 1) + '].knowledge_events';
+      if (previous.state === 'full' && ['learns', 'partially_learns', 'misinforms'].includes(event.change)) {
+        errors.push({
+          code: 'KNOWLEDGE_ORDER',
+          path: basePath,
+          message: '第 ' + displayNo + ' 章：' + event.character + ' 已经知道 ' + event.subject_id + '，不能再次写成“' + event.change + '”',
+          expected: '已知道 full',
+          actual: previous.state + ' -> ' + nextState,
+        });
+      }
+      if (previous.state === 'false' && ['learns', 'partially_learns', 'confirms'].includes(event.change)) {
+        errors.push({
+          code: 'KNOWLEDGE_ORDER',
+          path: basePath,
+          message: '第 ' + displayNo + ' 章：' + event.character + ' 对 ' + event.subject_id + ' 之前是误信，必须先 corrects 才能写成 ' + event.change,
+          expected: 'corrects',
+          actual: previous.state + ' -> ' + nextState,
+        });
+      }
+      if (previous.state === 'unknown' && event.change === 'confirms') {
+        errors.push({
+          code: 'KNOWLEDGE_ORDER',
+          path: basePath,
+          message: '第 ' + displayNo + ' 章：' + event.character + ' 尚未学会 ' + event.subject_id + '，不能直接 confirm',
+          expected: 'learns/partially_learns',
+          actual: 'unknown -> full',
+        });
+      }
+      if (previous.state === 'unknown' && event.change === 'forgets') {
+        warnings.push({
+          code: 'KNOWLEDGE_FORGET_UNKNOWN',
+          path: basePath,
+          message: '第 ' + displayNo + ' 章：' + event.character + ' 本来不知道 ' + event.subject_id + '，forgets 没有实际变化',
+        });
+      }
+      if (previous.state === 'full' && event.change === 'confirms') {
+        warnings.push({
+          code: 'KNOWLEDGE_REDUNDANT',
+          path: basePath,
+          message: '第 ' + displayNo + ' 章：' + event.character + ' 已完全知道 ' + event.subject_id + '，重复 confirm',
+        });
+      }
+      const next = {
+        state: nextState,
+        coverage: event.coverage || nextState,
+        knowledge: event.knowledge || '',
+        how: event.how || 'other',
+        source_character: event.source_character || null,
+        scene: event.scene || '',
+        evidence: event.evidence || '',
+        chapter: displayNo,
+      };
+      states.set(key, next);
+      events.push({ ...event, chapter: displayNo, before: previous.state, after: next.state });
+    }
+    snapshots.set(displayNo, new Map(states));
+  }
+  return { states, snapshots, events, errors, warnings };
+}
+
+/** 校验细纲/台账里的知识快照是否与章节地图回放一致。 */
+export function validateKnowledgeSnapshot(rows, expectedStates, ctx = {}) {
+  const errors = [];
+  const warnings = [];
+  asArray(rows).forEach((row, index) => {
+    if (!row || typeof row !== 'object') return;
+    const p = (ctx.path || 'knowledge') + '[' + index + ']';
+    if (!row.subject_type || !row.subject_id || !row.character) {
+      errors.push({ code: 'KNOWLEDGE_SNAPSHOT_FIELDS', path: p, message: '知识快照必须写 subject_type、subject_id、character' });
+      return;
+    }
+    const key = knowledgeKey(row.subject_type, row.subject_id, row.character);
+    const expected = expectedStates.get(key);
+    const state = row.state || row.coverage;
+    if (!expected) {
+      warnings.push({ code: 'KNOWLEDGE_SNAPSHOT_UNKNOWN', path: p, message: '章节地图没有登记这条知识：' + key });
+      return;
+    }
+    if (state && state !== expected.state) {
+      errors.push({
+        code: 'KNOWLEDGE_CONFLICT',
+        path: p + '.state',
+        message: '第 ' + (ctx.chapterNo || '?') + ' 章：' + row.character + ' 对 ' + row.subject_id + ' 的状态与章节地图冲突',
+        expected: expected.state,
+        actual: state,
+      });
+    }
+  });
+  return { errors, warnings };
+}