@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/db/project.js

@@ -0,0 +1,299 @@
+/**
+ * SurrealDB -> stage JSON projection.
+ *
+ * The generation prompts still speak in stage JSON. This module writes a
+ * read-only projection of the database back into `设定/...` before a stage
+ * runs, so the prompt builders and validators keep working unchanged.
+ *
+ * Nothing here is a source of truth: the projection is overwritten on the
+ * next command and can be deleted without losing story data.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { dbErrorMessage, StoryDbError } from './client.js';
+
+const STORY = 'story:main';
+const STAGE_DIR = {
+  '10-scale': '10-scale',
+  '20-macro': '20-macro',
+  '30-cast': '30-cast',
+  '40-rhythm': '40-rhythm',
+  '50-writing': '50-writing',
+};
+
+const ORDER = ['10-scale', '20-macro', '30-cast', '40-rhythm', 'outline', '50-writing'];
+
+function dirOf(projectRoot, stageId, sub = '') {
+  return path.join(projectRoot, '设定', STAGE_DIR[stageId] || stageId, sub);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeJson(file, value) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+}
+
+function writeText(file, value) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, value, 'utf8');
+}
+
+function meta(stage, nodeId) {
+  return {
+    schema_version: '2.1',
+    node_id: nodeId,
+    stage,
+    generated_at: new Date().toISOString(),
+  };
+}
+
+function payloadOf(row, fallback = {}) {
+  return row && row.payload && typeof row.payload === 'object' ? row.payload : fallback;
+}
+
+function mapPayload(rows) {
+  return rows.map((row) => payloadOf(row, { id: row.entity_id, name: row.name }));
+}
+
+async function count(sdb, sql, vars) {
+  const rows = await sdb.rows(sql, vars);
+  return Number(rows[0] && rows[0].count) || 0;
+}
+
+export async function stageHasData(sdb, stageId) {
+  switch (stageId) {
+    case '10-scale': return (await count(sdb, `SELECT count() FROM scale WHERE story = ${STORY} GROUP ALL;`)) > 0;
+    case '20-macro': return (await count(sdb, `SELECT count() FROM stage_doc WHERE story = ${STORY} AND stage = '20-macro' GROUP ALL;`)) > 0;
+    case '30-cast': return (await count(sdb, `SELECT count() FROM character WHERE story = ${STORY} GROUP ALL;`)) > 0
+      || (await count(sdb, `SELECT count() FROM faction WHERE story = ${STORY} GROUP ALL;`)) > 0;
+    case '40-rhythm': return (await count(sdb, `SELECT count() FROM chapter WHERE story = ${STORY} GROUP ALL;`)) > 0;
+    case 'outline': return (await count(sdb, `SELECT count() FROM outline WHERE story = ${STORY} GROUP ALL;`)) > 0;
+    case '50-writing': return (await count(sdb, `SELECT count() FROM chapter_text WHERE story = ${STORY} GROUP ALL;`)) > 0;
+    default: return false;
+  }
+}
+
+async function projectScale(sdb, projectRoot) {
+  const scale = await sdb.one(`SELECT * FROM scale:main;`);
+  if (!scale || !scale.payload) return false;
+  writeJson(dirOf(projectRoot, '10-scale', 'scale.json'), scale.payload);
+  return true;
+}
+
+const MACRO_FILES = ['world', 'story', 'volumes', 'lines', 'endings', 'emotion', 'roles'];
+
+async function projectMacro(sdb, projectRoot) {
+  const rows = await sdb.rows(
+    `SELECT * FROM stage_doc WHERE story = ${STORY} AND stage = '20-macro';`,
+  );
+  if (!rows.length) return false;
+  const byName = new Map(rows.map((row) => [row.name, row.payload]));
+  let wrote = false;
+  for (const name of MACRO_FILES) {
+    if (byName.has(name)) {
+      writeJson(dirOf(projectRoot, '20-macro', name + '.json'), byName.get(name));
+      wrote = true;
+    }
+  }
+  return wrote;
+}
+
+async function projectCast(sdb, projectRoot) {
+  const characters = await sdb.rows(`SELECT * FROM character WHERE story = ${STORY} ORDER BY entity_id;`);
+  if (!characters.length) return false;
+
+  const files = [
+    ['characters', 'character'],
+    ['factions', 'faction'],
+    ['locations', 'location'],
+    ['items', 'item'],
+    ['conflicts', 'conflict'],
+    ['foreshadows', 'foreshadow'],
+    ['climaxes', 'climax'],
+    ['payoffs', 'payoff'],
+  ];
+  for (const [fileKey, table] of files) {
+    const rows = await sdb.rows(`SELECT * FROM ${table} WHERE story = ${STORY} ORDER BY entity_id;`);
+    writeJson(dirOf(projectRoot, '30-cast', fileKey + '.json'), {
+      [fileKey]: mapPayload(rows),
+      _meta: meta('30-cast', '30-cast.' + fileKey),
+    });
+  }
+
+  const gaps = await sdb.rows(`SELECT * FROM information WHERE story = ${STORY} ORDER BY entity_id;`);
+  writeJson(dirOf(projectRoot, '30-cast', 'information.json'), {
+    information_gaps: mapPayload(gaps),
+    _meta: meta('30-cast', '30-cast.information'),
+  });
+
+  const rels = await sdb.rows(`SELECT * FROM relation WHERE story = ${STORY};`);
+  const factionRels = await sdb.rows(`SELECT * FROM faction_relation WHERE story = ${STORY};`);
+  const memberships = await sdb.rows(`SELECT * FROM membership WHERE story = ${STORY};`);
+  writeJson(dirOf(projectRoot, '30-cast', 'relations.json'), {
+    character_relations: rels.map((row) => {
+      const p = payloadOf(row);
+      return {
+        ...p,
+        id: p.id || row.id,
+        from: p.from || row.from_id,
+        to: p.to || row.to_id,
+        kind: p.kind || row.kind,
+        initial_state: p.initial_state !== undefined ? p.initial_state : row.initial_state,
+        changes: p.changes !== undefined ? p.changes : (row.changes || []),
+      };
+    }),
+    faction_relations: factionRels.map((row) => {
+      const p = payloadOf(row);
+      return {
+        ...p,
+        id: p.id || row.id,
+        from: p.from || row.from_id,
+        to: p.to || row.to_id,
+        kind: p.kind || row.kind,
+        initial_state: p.initial_state !== undefined ? p.initial_state : row.initial_state,
+        changes: p.changes !== undefined ? p.changes : (row.changes || []),
+      };
+    }),
+    memberships: memberships.map((row) => {
+      const p = payloadOf(row);
+      const fromRecord = p.character || String(row.in || '').split(':').pop().replace(/[⟨⟩]/g, '');
+      const toRecord = p.faction || String(row.out || '').split(':').pop().replace(/[⟨⟩]/g, '');
+      return {
+        ...p,
+        character: fromRecord,
+        faction: toRecord,
+        role: p.role || row.role,
+      };
+    }),
+    _meta: meta('30-cast', '30-cast.relations'),
+  });
+
+  return true;
+}
+
+async function projectRhythm(sdb, projectRoot, opts = {}) {
+  const chapters = await sdb.rows(
+    `SELECT * FROM chapter WHERE story = ${STORY} ORDER BY display_no;`,
+  );
+  if (!chapters.length) return false;
+
+  if (!opts.outlinesOnly) {
+    // Remove stale chunk shards; seedChunksFromChapterMap will split the
+    // merged map again for the generation loop.
+    const shardDir = dirOf(projectRoot, '40-rhythm', '.chapter-map');
+    try { fs.rmSync(shardDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    writeJson(dirOf(projectRoot, '40-rhythm', 'chapter_map.json'), {
+      _meta: meta('40-rhythm', '40-rhythm.chapter_map'),
+      chapters: chapters.map((row) => payloadOf(row)),
+    });
+  }
+
+  const outlines = await sdb.rows(
+    `SELECT * FROM outline WHERE story = ${STORY} ORDER BY chapter_id;`,
+  );
+  if (outlines.length) {
+    const outDir = dirOf(projectRoot, '40-rhythm', 'outlines');
+    ensureDir(outDir);
+    const existing = new Set(fs.readdirSync(outDir).filter((name) => name.endsWith('.json')));
+    for (const row of outlines) {
+      const chapterId = row.chapter_id;
+      writeJson(path.join(outDir, chapterId + '.json'), payloadOf(row));
+      existing.delete(chapterId + '.json');
+    }
+    for (const stale of existing) {
+      try { fs.unlinkSync(path.join(outDir, stale)); } catch { /* ignore */ }
+    }
+  }
+  return true;
+}
+
+async function projectWriting(sdb, projectRoot) {
+  const texts = await sdb.rows(
+    `SELECT * FROM chapter_text WHERE story = ${STORY} ORDER BY display_no;`,
+  );
+  if (!texts.length) return false;
+  const chapDir = dirOf(projectRoot, '50-writing', 'chapters');
+  ensureDir(chapDir);
+  const keep = new Set();
+  for (const row of texts) {
+    const name = '第' + String(row.display_no).padStart(3, '0') + '章.md';
+    keep.add(name);
+    writeText(path.join(chapDir, name), row.content);
+  }
+  for (const name of fs.readdirSync(chapDir)) {
+    if (name.endsWith('.md') && !keep.has(name)) {
+      try { fs.unlinkSync(path.join(chapDir, name)); } catch { /* ignore */ }
+    }
+  }
+
+  const ledger = await sdb.rows(`SELECT * FROM ledger_entry WHERE story = ${STORY};`);
+  if (ledger.length) {
+    writeJson(dirOf(projectRoot, '50-writing', 'ledger.json'), {
+      _meta: meta('50-writing', '50-writing.ledger'),
+      chapters: ledger.map((row) => payloadOf(row)),
+    });
+  }
+  return true;
+}
+
+async function writeStageStatus(sdb, projectRoot, stageId) {
+  const state = await sdb.one(
+    `SELECT * FROM stage_state WHERE story = ${STORY} AND stage = $stage LIMIT 1;`,
+    { stage: stageId },
+  );
+  if (!state) return;
+  const dir = dirOf(projectRoot, stageId);
+  if (!fs.existsSync(dir)) return;
+  writeJson(path.join(dir, '.stage-status.json'), {
+    schema_version: '2.1',
+    stage: stageId,
+    status: state.status,
+    checked_at: state.checked_at,
+    files: {},
+    errors: state.errors || [],
+    warnings: state.warnings || [],
+  });
+}
+
+/** Project every stage that exists in the DB. Used by `tools export`. */
+export async function projectAll(sdb, projectRoot) {
+  const written = {};
+  for (const stageId of ORDER) {
+    written[stageId] = await projectOne(sdb, stageId, projectRoot);
+  }
+  return written;
+}
+
+/** Project the stages needed by `targetStage`, in dependency order. */
+export async function projectForStage(sdb, targetStage, projectRoot) {
+  const idx = ORDER.indexOf(targetStage);
+  const stages = idx >= 0 ? ORDER.slice(0, idx + 1) : ORDER;
+  const written = {};
+  for (const stageId of stages) {
+    written[stageId] = await projectOne(sdb, stageId, projectRoot);
+  }
+  return written;
+}
+
+async function projectOne(sdb, stageId, projectRoot) {
+  let written = false;
+  switch (stageId) {
+    case '10-scale': written = await projectScale(sdb, projectRoot); break;
+    case '20-macro': written = await projectMacro(sdb, projectRoot); break;
+    case '30-cast': written = await projectCast(sdb, projectRoot); break;
+    case '40-rhythm': written = await projectRhythm(sdb, projectRoot); break;
+    case 'outline': written = await projectRhythm(sdb, projectRoot, { outlinesOnly: true }); break;
+    case '50-writing': written = await projectWriting(sdb, projectRoot); break;
+    default: written = false;
+  }
+  if (written && stageId !== 'outline') {
+    await writeStageStatus(sdb, projectRoot, stageId);
+  }
+  return written;
+}
+
+export { writeStageStatus };

package/plugins/fancy-story-builder/db/query.js

@@ -0,0 +1,361 @@
+/**
+ * Read-only queries used by the `query` and `analyze` commands.
+ *
+ * Everything here reads only SurrealDB. No stage JSON is consulted, so an
+ * agent asking "what does changing this relationship affect?" gets one
+ * consistent answer from one store.
+ */
+
+import { dbErrorMessage, StoryDbError } from './client.js';
+
+const STORY = 'story:main';
+
+function recordOf(table, id) {
+  return `type::record(${JSON.stringify(table)}, ${JSON.stringify(String(id))})`;
+}
+
+async function resolveCharacter(sdb, value) {
+  const q = String(value || '').trim();
+  const rows = await sdb.rows(
+    `SELECT * FROM character WHERE story = ${STORY} AND (entity_id = $q OR name = $q) LIMIT 2;`,
+    { q },
+  );
+  if (!rows.length) throw new StoryDbError('QUERY_NOT_FOUND', '未找到人物：' + q);
+  return rows[0];
+}
+
+async function resolveForeshadow(sdb, value) {
+  const q = String(value || '').trim();
+  const rows = await sdb.rows(
+    `SELECT * FROM foreshadow WHERE story = ${STORY} AND (entity_id = $q OR name = $q) LIMIT 2;`,
+    { q },
+  );
+  if (!rows.length) throw new StoryDbError('QUERY_NOT_FOUND', '未找到伏笔：' + q);
+  return rows[0];
+}
+
+export async function getStatus(sdb) {
+  const tables = [
+    'scale', 'volume', 'act', 'character', 'faction', 'location', 'item',
+    'conflict', 'foreshadow', 'payoff', 'climax', 'information',
+    'relation', 'chapter', 'knowledge_event', 'knowledge_state',
+    'chapter_metric', 'outline', 'chapter_text', 'ledger_entry',
+  ];
+  const counts = {};
+  for (const table of tables) {
+    const rows = await sdb.rows(`SELECT count() FROM ${table} WHERE story = ${STORY} GROUP ALL;`);
+    counts[table] = Number(rows[0] && rows[0].count) || 0;
+  }
+  const stages = await sdb.rows(
+    `SELECT stage, status, checked_at, array::len(errors) AS error_count, array::len(warnings) AS warning_count
+     FROM stage_state WHERE story = ${STORY} ORDER BY stage;`,
+  );
+  const story = await sdb.one('SELECT * FROM story:main;');
+  return {
+    story: story || null,
+    stages,
+    counts,
+  };
+}
+
+export async function getCharacter(sdb, idOrName) {
+  const character = await resolveCharacter(sdb, idOrName);
+  const id = character.entity_id;
+  const record = recordOf('character', id);
+  const [relations, appearances, knowledge, events] = await Promise.all([
+    sdb.rows(
+      `SELECT from_id, to_id, kind, initial_state, changes
+       FROM relation WHERE story = ${STORY} AND (from_id = $id OR to_id = $id);`,
+      { id },
+    ),
+    sdb.rows(
+      `SELECT in.display_no AS chapter, in.title AS title, role
+       FROM chapter_cast WHERE story = ${STORY} AND out = ${record}
+       ORDER BY chapter;`,
+    ),
+    sdb.rows(
+      `SELECT subject_type, subject_id, state
+       FROM knowledge_state WHERE story = ${STORY} AND character = ${record}
+       ORDER BY subject_type, subject_id;`,
+    ),
+    sdb.rows(
+      `SELECT chapter_no, subject_type, subject_id, change, coverage, knowledge, how
+       FROM knowledge_event WHERE story = ${STORY} AND character_id = $id
+       ORDER BY chapter_no;`,
+      { id },
+    ),
+  ]);
+  return {
+    character,
+    relations,
+    appearances,
+    knowledge,
+    knowledge_events: events,
+  };
+}
+
+export async function getForeshadow(sdb, idOrName) {
+  const foreshadow = await resolveForeshadow(sdb, idOrName);
+  const id = foreshadow.entity_id;
+  const record = recordOf('foreshadow', id);
+  const [actions, payoffs, knowledge, states] = await Promise.all([
+    sdb.rows(
+      `SELECT in.display_no AS chapter, in.title AS title, action, detail
+       FROM foreshadow_action WHERE story = ${STORY} AND out = ${record}
+       ORDER BY chapter;`,
+    ),
+    sdb.rows(
+      `SELECT out.entity_id AS payoff, out.name AS name FROM foreshadow_payoff
+       WHERE story = ${STORY} AND in = ${record};`,
+    ),
+    sdb.rows(
+      `SELECT chapter_no, character_id, change, coverage, knowledge, how
+       FROM knowledge_event
+       WHERE story = ${STORY} AND subject_type = 'foreshadow' AND subject_id = $id
+       ORDER BY chapter_no;`,
+      { id },
+    ),
+    sdb.rows(
+      `SELECT character.entity_id AS character, state FROM knowledge_state
+       WHERE story = ${STORY} AND subject_type = 'foreshadow' AND subject_id = $id
+       ORDER BY character;`,
+      { id },
+    ),
+  ]);
+  const requiredBy = await sdb.rows(
+    `SELECT entity_id, name FROM payoff WHERE story = ${STORY} AND $id IN required_setup;`,
+    { id },
+  );
+  return {
+    foreshadow,
+    actions,
+    linked_payoffs: payoffs,
+    required_by_payoffs: requiredBy,
+    knowledge_events: knowledge,
+    knowledge_states: states,
+  };
+}
+
+export async function getChapters(sdb, from, to) {
+  const start = Number(from) || 1;
+  const end = Number(to) || start;
+  const chapters = await sdb.rows(
+    `SELECT chapter_id, display_no, title, volume, act, pov, word_target,
+            emotion_value, hook_type, hook_strength
+     FROM chapter WHERE story = ${STORY} AND display_no >= $start AND display_no <= $end
+     ORDER BY display_no;`,
+    { start, end },
+  );
+  const metrics = await sdb.rows(
+    `SELECT chapter_no, emotion_value, hook_strength, word_target, word_count
+     FROM chapter_metric WHERE story = ${STORY} AND chapter_no >= $start AND chapter_no <= $end
+     ORDER BY chapter_no;`,
+    { start, end },
+  );
+  const texts = await sdb.rows(
+    `SELECT display_no, word_count FROM chapter_text
+     WHERE story = ${STORY} AND display_no >= $start AND display_no <= $end
+     ORDER BY display_no;`,
+    { start, end },
+  );
+  return { range: { from: start, to: end }, chapters, metrics, texts };
+}
+
+export async function getRelations(sdb, idOrName) {
+  const character = await resolveCharacter(sdb, idOrName);
+  const id = character.entity_id;
+  const rows = await sdb.rows(
+    `SELECT from_id, to_id, kind, initial_state, changes
+     FROM relation WHERE story = ${STORY} AND (from_id = $id OR to_id = $id);`,
+    { id },
+  );
+  return { character: { id, name: character.name }, relations: rows };
+}
+
+export async function getKnowledge(sdb, idOrName, chapterNo) {
+  const character = await resolveCharacter(sdb, idOrName);
+  const id = character.entity_id;
+  if (chapterNo === undefined || chapterNo === null) {
+    const rows = await sdb.rows(
+      `SELECT subject_type, subject_id, state FROM knowledge_state
+       WHERE story = ${STORY} AND character = ${recordOf('character', id)}
+       ORDER BY subject_type, subject_id;`,
+    );
+    return { character: { id, name: character.name }, at: 'current', knowledge: rows };
+  }
+  const chapter = Number(chapterNo);
+  const events = await sdb.rows(
+    `SELECT chapter_no, subject_type, subject_id, change, coverage, knowledge, how
+     FROM knowledge_event
+     WHERE story = ${STORY} AND character_id = $id AND chapter_no <= $chapter
+     ORDER BY chapter_no, id;`,
+    { id, chapter },
+  );
+  const latest = new Map();
+  for (const event of events) {
+    latest.set(event.subject_type + ':' + event.subject_id, event);
+  }
+  return {
+    character: { id, name: character.name },
+    at: chapter,
+    knowledge: [...latest.values()].map((event) => ({
+      subject_type: event.subject_type,
+      subject_id: event.subject_id,
+      state: event.coverage,
+      since_chapter: event.chapter_no,
+      change: event.change,
+    })),
+  };
+}
+
+export async function analyzeRelationChange(sdb, aRaw, bRaw, opts = {}) {
+  const a = await resolveCharacter(sdb, aRaw);
+  const b = await resolveCharacter(sdb, bRaw);
+  const aId = a.entity_id;
+  const bId = b.entity_id;
+  const fromChapter = Number(opts.fromChapter) || 1;
+  const newKind = opts.newKind || null;
+
+  const current = await sdb.rows(
+    `SELECT from_id, to_id, kind, initial_state, changes FROM relation
+     WHERE story = ${STORY}
+       AND ((from_id = $a AND to_id = $b) OR (from_id = $b AND to_id = $a));`,
+    { a: aId, b: bId },
+  );
+
+  const chapters = await sdb.rows(
+    `SELECT display_no, chapter_id, title FROM chapter
+     WHERE story = ${STORY} AND display_no >= $from
+       AND $a IN ->chapter_cast->character.entity_id
+       AND $b IN ->chapter_cast->character.entity_id
+     ORDER BY display_no;`,
+    { from: fromChapter, a: aId, b: bId },
+  );
+  const chapterNos = chapters.map((row) => Number(row.display_no));
+
+  const conflicts = await sdb.rows(
+    `SELECT entity_id, name, type FROM conflict
+     WHERE story = ${STORY} AND $a IN participants AND $b IN participants;`,
+    { a: aId, b: bId },
+  );
+
+  const allActions = await sdb.rows(
+    `SELECT out.entity_id AS foreshadow, out.name AS name, in.display_no AS chapter, action, detail
+     FROM foreshadow_action WHERE story = ${STORY} AND in.display_no >= $from
+     ORDER BY chapter;`,
+    { from: fromChapter },
+  );
+  const foreshadows = allActions.filter((row) => chapterNos.includes(Number(row.chapter)));
+
+  const knowledge = await sdb.rows(
+    `SELECT chapter_no, character_id, subject_type, subject_id, change, coverage
+     FROM knowledge_event WHERE story = ${STORY} AND chapter_no >= $from
+       AND character_id IN [$a, $b]
+     ORDER BY chapter_no;`,
+    { from: fromChapter, a: aId, b: bId },
+  );
+
+  const warnings = [];
+  if (!current.length) warnings.push('当前没有找到 ' + aId + ' 与 ' + bId + ' 的关系边');
+  if (!chapters.length) warnings.push('第 ' + fromChapter + ' 章之后没有两人同时出场的章节');
+  if (newKind && current.length && current[0].kind === newKind) warnings.push('新关系与当前关系相同：' + newKind);
+  for (const fs of foreshadows) {
+    if (fs.action === '回收') warnings.push('伏笔 ' + fs.foreshadow + ' 在第 ' + fs.chapter + ' 章回收，依赖当前关系');
+  }
+
+  return {
+    query: 'relation_change',
+    characters: [{ id: aId, name: a.name }, { id: bId, name: b.name }],
+    current_relation: current[0] || null,
+    change: { from_chapter: fromChapter, to_kind: newKind },
+    impact: {
+      chapters,
+      conflicts,
+      foreshadows,
+      knowledge_events: knowledge,
+    },
+    warnings,
+  };
+}
+
+export async function analyzeForeshadowChange(sdb, idOrName, opts = {}) {
+  const foreshadow = await resolveForeshadow(sdb, idOrName);
+  const id = foreshadow.entity_id;
+  const record = recordOf('foreshadow', id);
+  const action = opts.action || null;
+  const chapter = Number(opts.chapter) || null;
+
+  const actions = await sdb.rows(
+    `SELECT in.display_no AS chapter, in.chapter_id AS chapter_id, action, detail
+     FROM foreshadow_action WHERE story = ${STORY} AND out = ${record}
+     ORDER BY chapter;`,
+  );
+  const payoffs = await sdb.rows(
+    `SELECT out.entity_id AS payoff, out.name AS name FROM foreshadow_payoff
+     WHERE story = ${STORY} AND in = ${record};`,
+  );
+  const requiredBy = await sdb.rows(
+    `SELECT entity_id, name FROM payoff WHERE story = ${STORY} AND $id IN required_setup;`,
+    { id },
+  );
+  const knowledge = await sdb.rows(
+    `SELECT chapter_no, character_id, change, coverage
+     FROM knowledge_event
+     WHERE story = ${STORY} AND subject_type = 'foreshadow' AND subject_id = $id
+     ORDER BY chapter_no;`,
+    { id },
+  );
+  const chapters = await sdb.rows(
+    `SELECT display_no, chapter_id, title FROM chapter
+     WHERE story = ${STORY} AND $id IN ->foreshadow_action->foreshadow.entity_id
+     ORDER BY display_no;`,
+    { id },
+  );
+
+  const plant = actions.find((row) => row.action === '埋设');
+  const recover = actions.find((row) => row.action === '回收');
+  const warnings = [];
+  if (!plant) warnings.push('这条伏笔尚未埋设记录');
+  if (action === '回收') {
+    if (recover) warnings.push('这条伏笔已经在第 ' + recover.chapter + ' 章回收');
+    if (chapter && plant && Number(plant.chapter) >= chapter) {
+      warnings.push('回收章（' + chapter + '）必须晚于埋设章（' + plant.chapter + '）');
+    }
+  }
+  if (payoffs.length + requiredBy.length > 0 && !recover) {
+    warnings.push('有 ' + (payoffs.length + requiredBy.length) + ' 个爽点依赖这条伏笔，但尚未回收记录');
+  }
+
+  return {
+    query: 'foreshadow_change',
+    foreshadow,
+    change: { action, chapter },
+    timeline: actions,
+    linked_payoffs: payoffs,
+    required_by_payoffs: requiredBy,
+    knowledge_events: knowledge,
+    affected_chapters: chapters,
+    warnings,
+  };
+}
+
+const READ_ONLY = /^\s*(SELECT|INFO|RETURN|SHOW|DESCRIBE|EXPLAIN)\b/i;
+
+export async function runReadOnlySql(sdb, sql) {
+  const text = String(sql || '').trim().replace(/;+\s*$/, '');
+  if (!text) throw new StoryDbError('QUERY_EMPTY', '查询语句为空');
+  if (!READ_ONLY.test(text)) {
+    throw new StoryDbError('QUERY_NOT_READ_ONLY', '只允许 SELECT / INFO / RETURN / SHOW / DESCRIBE / EXPLAIN 查询');
+  }
+  if (/;\s*(DELETE|CREATE|UPDATE|UPSERT|REMOVE|DEFINE|RELATE|INSERT|ALTER|KILL)\b/i.test(text)) {
+    throw new StoryDbError('QUERY_NOT_READ_ONLY', '查询中不能包含写操作');
+  }
+  try {
+    const out = await sdb.query(text + ';');
+    return Array.isArray(out) && out.length === 1 ? out[0] : out;
+  } catch (err) {
+    throw new StoryDbError('QUERY_FAILED', '查询失败：' + dbErrorMessage(err));
+  }
+}
+
+export { resolveCharacter, resolveForeshadow };