@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

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

@@ -0,0 +1,798 @@
+/**
+ * Stage JSON -> SurrealDB.
+ *
+ * The LLM still writes JSON as its generation output, but that JSON is only a
+ * transport buffer. This module is the only place that turns it into story
+ * data; after a successful import the database is the source of truth.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { dbErrorMessage, StoryDbError } from './client.js';
+import { surrealString, recordLiteral } from './ids.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',
+};
+
+export function stageDir(projectRoot, stageId, sub) {
+  return path.join(projectRoot, '设定', STAGE_DIR[stageId] || stageId, sub || '');
+}
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function withoutMeta(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  const copy = { ...obj };
+  delete copy._meta;
+  return copy;
+}
+
+function compact(fields) {
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+async function upsert(sdb, table, id, fields) {
+  const clean = compact(fields);
+  delete clean.story; // always the literal story:main, never a bound string
+  const keys = Object.keys(clean);
+  const sets = ['story = story:main', ...keys.map((key) => key + ' = $' + key)].join(', ');
+  await sdb.query(
+    `UPSERT type::record(${surrealString(table)}, $id) SET ${sets};`,
+    { id: String(id), ...clean },
+  );
+}
+
+async function upsertStageDoc(sdb, stage, name, payload) {
+  await sdb.query(
+    `UPSERT stage_doc SET story = ${STORY}, stage = $stage, name = $name, payload = $payload
+     WHERE story = ${STORY} AND stage = $stage AND name = $name;`,
+    { stage, name, payload },
+  );
+}
+
+async function deleteNotIn(sdb, table, ids) {
+  if (!Array.isArray(ids) || !ids.length) return;
+  await sdb.query(
+    `DELETE ${table} WHERE story = ${STORY} AND entity_id NOT IN $ids;`,
+    { ids: ids.map(String) },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// scale
+// ---------------------------------------------------------------------------
+
+export async function importScale(sdb, projectRoot) {
+  const file = stageDir(projectRoot, '10-scale', 'scale.json');
+  const scale = readJson(file, null);
+  if (!scale) throw new StoryDbError('STORYDB_IMPORT', '缺少 10-scale/scale.json');
+
+  await sdb.query(
+    `UPSERT scale:main SET
+       story = ${STORY},
+       capacity = $capacity,
+       quotas = $quotas,
+       rhythm_budget = $rhythm_budget,
+       distribution = $distribution,
+       constraints = $constraints,
+       formulas = $formulas,
+       derivations = $derivations,
+       genre_profile = $genre_profile,
+       formula_version = $formula_version,
+       payload = $payload;`,
+    {
+      capacity: scale.capacity || {},
+      quotas: scale.quotas || {},
+      rhythm_budget: scale.rhythm_budget || {},
+      distribution: scale.distribution || {},
+      constraints: scale.constraints || [],
+      formulas: scale.formulas || {},
+      derivations: scale.derivations || {},
+      genre_profile: scale.genre_profile || undefined,
+      formula_version: scale.formula_version || undefined,
+      payload: scale,
+    },
+  );
+
+  await sdb.query(`DELETE volume WHERE story = ${STORY};`);
+  await sdb.query(`DELETE act WHERE story = ${STORY};`);
+
+  const volumes = asArray(scale.structure && scale.structure.volumes);
+  for (const volume of volumes) {
+    await upsert(sdb, 'volume', volume.volume_id || volume.id, {
+      story: STORY,
+      volume_id: volume.volume_id || volume.id,
+      title: volume.title || undefined,
+      chapter_start: Number(volume.chapter_start) || 0,
+      chapter_end: Number(volume.chapter_end) || 0,
+      goal: volume.goal || undefined,
+      core_conflict: volume.core_conflict || undefined,
+      emotional_arc: volume.emotional_arc || undefined,
+      ending_hook: volume.ending_hook || undefined,
+      payload: withoutMeta(volume),
+    });
+    for (const act of asArray(volume.acts)) {
+      await upsert(sdb, 'act', act.act_id || act.id, {
+        story: STORY,
+        act_id: act.act_id || act.id,
+        volume_id: volume.volume_id || volume.id,
+        act_index: Number(act.act_index) || 0,
+        chapter_start: Number(act.chapter_start) || 0,
+        chapter_end: Number(act.chapter_end) || 0,
+        goal: act.goal || undefined,
+        payload: withoutMeta(act),
+      });
+    }
+  }
+  for (const act of asArray(scale.structure && scale.structure.acts)) {
+    await upsert(sdb, 'act', act.act_id || act.id, {
+      story: STORY,
+      act_id: act.act_id || act.id,
+      volume_id: act.volume_id || '',
+      act_index: Number(act.act_index) || 0,
+      chapter_start: Number(act.chapter_start) || 0,
+      chapter_end: Number(act.chapter_end) || 0,
+      goal: act.goal || undefined,
+      payload: withoutMeta(act),
+    });
+  }
+
+  await upsertStageDoc(sdb, '10-scale', 'scale', scale);
+  return { stage: '10-scale', ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// macro
+// ---------------------------------------------------------------------------
+
+const MACRO_FILES = ['world', 'story', 'volumes', 'lines', 'endings', 'emotion', 'roles'];
+
+export async function importMacro(sdb, projectRoot) {
+  const docs = {};
+  for (const name of MACRO_FILES) {
+    const doc = readJson(stageDir(projectRoot, '20-macro', name + '.json'), null);
+    if (!doc) throw new StoryDbError('STORYDB_IMPORT', '缺少 20-macro/' + name + '.json');
+    docs[name] = doc;
+    await upsertStageDoc(sdb, '20-macro', name, doc);
+  }
+
+  // volumes / acts: enrich the scale skeleton with macro details.
+  for (const volume of asArray(docs.volumes.volumes)) {
+    await sdb.query(
+      `UPSERT volume SET
+         story = ${STORY}, volume_id = $volume_id, title = $title,
+         chapter_start = $chapter_start, chapter_end = $chapter_end,
+         goal = $goal, core_conflict = $core_conflict,
+         emotional_arc = $emotional_arc, ending_hook = $ending_hook,
+         payload = $payload
+       WHERE story = ${STORY} AND volume_id = $volume_id;`,
+      {
+        volume_id: volume.id || volume.volume_id,
+        title: volume.title || undefined,
+        chapter_start: Number(volume.chapter_start) || 0,
+        chapter_end: Number(volume.chapter_end) || 0,
+        goal: volume.goal || undefined,
+        core_conflict: volume.core_conflict || undefined,
+        emotional_arc: volume.emotional_arc || undefined,
+        ending_hook: volume.ending_hook || undefined,
+        payload: withoutMeta(volume),
+      },
+    );
+    for (const act of asArray(volume.acts)) {
+      await sdb.query(
+        `UPSERT act SET
+           story = ${STORY}, act_id = $act_id, volume_id = $volume_id,
+           act_index = $act_index, chapter_start = $chapter_start,
+           chapter_end = $chapter_end, goal = $goal, payload = $payload
+         WHERE story = ${STORY} AND act_id = $act_id;`,
+        {
+          act_id: act.act_id || act.id,
+          volume_id: volume.id || volume.volume_id,
+          act_index: Number(act.act_index) || 0,
+          chapter_start: Number(act.chapter_start) || 0,
+          chapter_end: Number(act.chapter_end) || 0,
+          goal: act.goal || undefined,
+          payload: withoutMeta(act),
+        },
+      );
+    }
+  }
+
+  // lines / nodes
+  await sdb.query(`DELETE line_node WHERE story = ${STORY};`);
+  await sdb.query(`DELETE line WHERE story = ${STORY};`);
+  const main = docs.lines.main_line || {};
+  if (main.id || main.name) {
+    await upsert(sdb, 'line', main.id || 'M001', {
+      story: STORY,
+      line_id: main.id || 'M001',
+      kind: 'main',
+      name: main.name || '主线',
+      payload: withoutMeta(main),
+    });
+  }
+  for (const node of asArray(main.nodes)) {
+    await upsert(sdb, 'line_node', node.id, {
+      story: STORY,
+      node_id: node.id,
+      line_id: main.id || 'M001',
+      volume: node.volume || undefined,
+      act: node.act || undefined,
+      goal: node.goal || undefined,
+      turn: node.turn || undefined,
+      payload: withoutMeta(node),
+    });
+  }
+  for (const branch of asArray(docs.lines.branches)) {
+    await upsert(sdb, 'line', branch.id, {
+      story: STORY,
+      line_id: branch.id,
+      kind: 'branch',
+      name: branch.name || branch.id,
+      payload: withoutMeta(branch),
+    });
+    for (const nodeId of asArray(branch.interweaves)) {
+      await upsert(sdb, 'line_node', nodeId, {
+        story: STORY,
+        node_id: nodeId,
+        line_id: branch.id,
+        payload: { id: nodeId },
+      });
+    }
+  }
+
+  // endings
+  await sdb.query(`DELETE ending WHERE story = ${STORY};`);
+  for (const ending of asArray(docs.endings.endings)) {
+    await upsert(sdb, 'ending', ending.id, {
+      story: STORY,
+      ending_id: ending.id,
+      level: ending.level || undefined,
+      type: ending.type || undefined,
+      direction: ending.direction || undefined,
+      payload: withoutMeta(ending),
+    });
+  }
+
+  return { stage: '20-macro', ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// cast
+// ---------------------------------------------------------------------------
+
+const ENTITY_SPECS = {
+  characters: {
+    table: 'character',
+    list: 'characters',
+    fields: ['role_slot', 'faction', 'description', 'goal', 'flaw', 'arc', 'traits'],
+  },
+  factions: {
+    table: 'faction',
+    list: 'factions',
+    fields: ['description', 'goal', 'resources', 'territory', 'internal_conflict'],
+  },
+  locations: {
+    table: 'location',
+    list: 'locations',
+    fields: ['description', 'narrative_function', 'rules'],
+  },
+  items: {
+    table: 'item',
+    list: 'items',
+    fields: ['category', 'description', 'item_function', 'owner', 'limit'],
+  },
+  conflicts: {
+    table: 'conflict',
+    list: 'conflicts',
+    fields: ['description', 'core_goal', 'stakes', 'escalation_path', 'resolution_plan', 'participants'],
+  },
+  foreshadows: {
+    table: 'foreshadow',
+    list: 'foreshadows',
+    fields: ['setup', 'clues', 'payoff_target', 'recovery_requirement', 'red_herrings', 'scope', 'initial_knowledge'],
+  },
+  payoffs: {
+    table: 'payoff',
+    list: 'payoffs',
+    fields: ['scale', 'setup', 'payoff', 'emotional_effect', 'required_setup'],
+  },
+  climaxes: {
+    table: 'climax',
+    list: 'climaxes',
+    fields: ['description', 'payoff', 'participants'],
+  },
+};
+
+export async function importCast(sdb, projectRoot) {
+  const files = {};
+  for (const name of [...Object.keys(ENTITY_SPECS), 'relations', 'information']) {
+    const doc = readJson(stageDir(projectRoot, '30-cast', name + '.json'), null);
+    if (!doc) throw new StoryDbError('STORYDB_IMPORT', '缺少 30-cast/' + name + '.json');
+    files[name] = doc;
+  }
+
+  for (const [fileKey, spec] of Object.entries(ENTITY_SPECS)) {
+    const rows = asArray(files[fileKey][spec.list]);
+    const ids = rows.map((row) => String(row.id));
+    for (const row of rows) {
+      const fields = {
+        story: STORY,
+        entity_id: String(row.id),
+        name: row.name || row.id,
+        type: row.type || undefined,
+        payload: withoutMeta(row),
+      };
+      for (const key of spec.fields) {
+        if (row[key] !== undefined) fields[key] = row[key];
+      }
+      await upsert(sdb, spec.table, row.id, fields);
+    }
+    await deleteNotIn(sdb, spec.table, ids);
+  }
+
+  const gaps = asArray(files.information.information_gaps);
+  for (const gap of gaps) {
+    await upsert(sdb, 'information', gap.id, {
+      story: STORY,
+      entity_id: String(gap.id),
+      info_name: gap.info_name || gap.name || gap.id,
+      conflict: gap.conflict || undefined,
+      who_knows: gap.who_knows || [],
+      who_does_not_know: gap.who_does_not_know || [],
+      resolution_method: gap.resolution_method || undefined,
+      writing_ban: gap.writing_ban || undefined,
+      initial_knowledge: gap.initial_knowledge || [],
+      payload: withoutMeta(gap),
+    });
+  }
+  await deleteNotIn(sdb, 'information', gaps.map((gap) => String(gap.id)));
+
+  // Rebuild all cast edges from scratch; they are derived from the documents.
+  for (const table of ['relation', 'faction_relation', 'membership', 'conflict_participant', 'climax_participant', 'foreshadow_payoff']) {
+    await sdb.query(`DELETE ${table} WHERE story = ${STORY};`);
+  }
+
+  const rels = files.relations;
+  for (const rel of asArray(rels.character_relations)) {
+    const from = rel.from || rel.from_id;
+    const to = rel.to || rel.to_id;
+    if (!from || !to) continue;
+    await sdb.query(
+      `RELATE ${recordLiteral('character', from)}->relation->${recordLiteral('character', to)} SET
+         story = ${STORY}, from_id = $from, to_id = $to,
+         kind = $kind, initial_state = $initial_state, changes = $changes, payload = $payload;`,
+      {
+        from: String(from),
+        to: String(to),
+        kind: rel.kind || rel.type || '未知',
+        initial_state: rel.initial_state || undefined,
+        changes: rel.changes || [],
+        payload: withoutMeta(rel),
+      },
+    );
+  }
+
+  for (const rel of asArray(rels.faction_relations)) {
+    const from = rel.from || rel.from_id;
+    const to = rel.to || rel.to_id;
+    if (!from || !to) continue;
+    await sdb.query(
+      `RELATE ${recordLiteral('faction', from)}->faction_relation->${recordLiteral('faction', to)} SET
+         story = ${STORY}, from_id = $from, to_id = $to, kind = $kind, payload = $payload;`,
+      {
+        from: String(from),
+        to: String(to),
+        kind: rel.kind || rel.type || '未知',
+        payload: withoutMeta(rel),
+      },
+    );
+  }
+
+  for (const member of asArray(rels.memberships)) {
+    const character = member.character || member.from || member.character_id;
+    const faction = member.faction || member.to || member.faction_id;
+    if (!character || !faction) continue;
+    await sdb.query(
+      `RELATE ${recordLiteral('character', character)}->membership->${recordLiteral('faction', faction)} SET
+         story = ${STORY}, role = $role, payload = $payload;`,
+      {
+        character: String(character),
+        faction: String(faction),
+        role: member.role || undefined,
+        payload: withoutMeta(member),
+      },
+    );
+  }
+
+  for (const conflict of asArray(files.conflicts.conflicts)) {
+    for (const participant of asArray(conflict.participants)) {
+      await sdb.query(
+        `RELATE ${recordLiteral('conflict', conflict.id)}->conflict_participant->${recordLiteral('character', participant)} SET story = ${STORY};`,
+        { conflict: String(conflict.id), character: String(participant) },
+      );
+    }
+  }
+
+  for (const climax of asArray(files.climaxes.climaxes)) {
+    for (const participant of asArray(climax.participants)) {
+      await sdb.query(
+        `RELATE ${recordLiteral('climax', climax.id)}->climax_participant->${recordLiteral('character', participant)} SET story = ${STORY};`,
+        { climax: String(climax.id), character: String(participant) },
+      );
+    }
+  }
+
+  const payoffIds = new Set(asArray(files.payoffs.payoffs).map((row) => String(row.id)));
+  for (const fs of asArray(files.foreshadows.foreshadows)) {
+    if (fs.payoff_target && payoffIds.has(String(fs.payoff_target))) {
+      await sdb.query(
+        `RELATE ${recordLiteral('foreshadow', fs.id)}->foreshadow_payoff->${recordLiteral('payoff', fs.payoff_target)} SET story = ${STORY}, relation = $relation;`,
+        { fs: String(fs.id), payoff: String(fs.payoff_target), relation: fs.recovery_requirement || undefined },
+      );
+    }
+  }
+
+  return { stage: '30-cast', ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// rhythm
+// ---------------------------------------------------------------------------
+
+function actionState(value, fallback) {
+  return value || fallback;
+}
+
+export async function importRhythm(sdb, projectRoot) {
+  const doc = readJson(stageDir(projectRoot, '40-rhythm', 'chapter_map.json'), null);
+  if (!doc || !Array.isArray(doc.chapters)) {
+    throw new StoryDbError('STORYDB_IMPORT', '缺少 40-rhythm/chapter_map.json');
+  }
+  const chapters = [...doc.chapters].sort((a, b) => Number(a.display_no) - Number(b.display_no));
+
+  // Rebuild the timeline from scratch so the knowledge replay is deterministic.
+  await sdb.query(`DELETE knowledge_event WHERE story = ${STORY};`);
+  await sdb.query(`DELETE knowledge_state WHERE story = ${STORY};`);
+  for (const table of ['chapter_cast', 'chapter_location', 'foreshadow_action', 'payoff_action', 'info_action', 'ending_action']) {
+    await sdb.query(`DELETE ${table} WHERE story = ${STORY};`);
+  }
+  await sdb.query(`DELETE chapter_metric WHERE story = ${STORY};`);
+
+  const chapterIds = chapters.map((c) => String(c.chapter_id));
+  // Remove chapters that no longer exist, together with their dependents.
+  const old = await sdb.rows(`SELECT chapter_id FROM chapter WHERE story = ${STORY};`);
+  for (const row of old) {
+    if (!chapterIds.includes(String(row.chapter_id))) {
+      await sdb.query(`DELETE outline WHERE story = ${STORY} AND chapter_id = $id;`, { id: row.chapter_id });
+      await sdb.query(`DELETE chapter_text WHERE story = ${STORY} AND chapter_id = $id;`, { id: row.chapter_id });
+      await sdb.query(`DELETE ledger_entry WHERE story = ${STORY} AND chapter_id = $id;`, { id: row.chapter_id });
+      await sdb.query(`DELETE chapter WHERE story = ${STORY} AND chapter_id = $id;`, { id: row.chapter_id });
+    }
+  }
+
+  for (const chapter of chapters) {
+    const displayNo = Number(chapter.display_no);
+    await sdb.query(
+      `UPSERT type::record('chapter', $chapter_id) SET
+         story = ${STORY}, chapter_id = $chapter_id, display_no = $display_no,
+         title = $title, volume = $volume, act = $act, pov = $pov,
+         word_target = $word_target,
+         emotion_value = $emotion_value, hook_type = $hook_type, hook_strength = $hook_strength,
+         time = $time, why = $why, how = $how, emotion = $emotion, hook = $hook,
+         payload = $payload;`,
+      {
+        chapter_id: String(chapter.chapter_id),
+        display_no: displayNo,
+        title: chapter.title || '第 ' + displayNo + ' 章',
+        volume: chapter.volume || '',
+        act: chapter.act || '',
+        pov: chapter.pov || undefined,
+        word_target: Number(chapter.word_target) || 0,
+        emotion_value: Number(chapter.emotion && chapter.emotion.value) || undefined,
+        hook_type: chapter.hook && chapter.hook.type || undefined,
+        hook_strength: chapter.hook && chapter.hook.strength || undefined,
+        time: chapter.time || {},
+        why: chapter.why || {},
+        how: chapter.how || {},
+        emotion: chapter.emotion || {},
+        hook: chapter.hook || {},
+        payload: withoutMeta(chapter),
+      },
+    );
+
+    const chapThing = `type::record('chapter', ${surrealString(String(chapter.chapter_id))})`;
+    const chapRec = recordLiteral('chapter', chapter.chapter_id);
+
+    const cast = [...new Set(asArray(chapter.cast).map(String))];
+    for (const character of cast) {
+      const role = chapter.pov && String(chapter.pov) === character ? 'pov' : 'cast';
+      await sdb.query(
+        `RELATE ${chapRec}->chapter_cast->${recordLiteral('character', character)} SET story = ${STORY}, role = $role;`,
+        { character, role },
+      );
+    }
+    if (chapter.pov && !cast.includes(String(chapter.pov))) {
+      await sdb.query(
+        `RELATE ${chapRec}->chapter_cast->${recordLiteral('character', chapter.pov)} SET story = ${STORY}, role = 'pov';`,
+        { character: String(chapter.pov) },
+      );
+    }
+    for (const character of asArray(chapter.mentioned).map(String)) {
+      await sdb.query(
+        `RELATE ${chapRec}->chapter_cast->${recordLiteral('character', character)} SET story = ${STORY}, role = 'mentioned';`,
+        { character },
+      );
+    }
+
+    for (const location of [...new Set(asArray(chapter.locations).map(String))]) {
+      await sdb.query(
+        `RELATE ${chapRec}->chapter_location->${recordLiteral('location', location)} SET story = ${STORY};`,
+        { location },
+      );
+    }
+
+    for (const action of asArray(chapter.foreshadow_actions)) {
+      if (!action || !action.id) continue;
+      await sdb.query(
+        `RELATE ${chapRec}->foreshadow_action->${recordLiteral('foreshadow', action.id)} SET
+           story = ${STORY}, chapter_no = $chapter_no, foreshadow_id = $id,
+           action = $action, detail = $detail, payload = $payload;`,
+        {
+          id: String(action.id),
+          chapter_no: displayNo,
+          action: action.action || '埋设',
+          detail: action.detail || undefined,
+          payload: action,
+        },
+      );
+    }
+
+    for (const action of asArray(chapter.payoff_actions)) {
+      if (!action || !action.id) continue;
+      await sdb.query(
+        `RELATE ${chapRec}->payoff_action->${recordLiteral('payoff', action.id)} SET
+           story = ${STORY}, chapter_no = $chapter_no, payoff_id = $id,
+           action = $action, detail = $detail, payload = $payload;`,
+        {
+          id: String(action.id),
+          chapter_no: displayNo,
+          action: action.action || '铺垫',
+          detail: action.detail || undefined,
+          payload: action,
+        },
+      );
+    }
+
+    for (const gap of asArray(chapter.information_gaps)) {
+      if (!gap || !gap.id) continue;
+      await sdb.query(
+        `RELATE ${chapRec}->info_action->${recordLiteral('information', gap.id)} SET
+           story = ${STORY}, chapter_no = $chapter_no, info_id = $id,
+           state = $state, detail = $detail, payload = $payload;`,
+        {
+          id: String(gap.id),
+          chapter_no: displayNo,
+          state: actionState(gap.state, 'progressed'),
+          detail: gap.detail || undefined,
+          payload: gap,
+        },
+      );
+    }
+
+    for (const action of asArray(chapter.ending_actions)) {
+      if (!action || !action.id) continue;
+      await sdb.query(
+        `RELATE ${chapRec}->ending_action->${recordLiteral('ending', action.id)} SET
+           story = ${STORY}, chapter_no = $chapter_no, ending_id = $id,
+           action = $action, detail = $detail, payload = $payload;`,
+        {
+          id: String(action.id),
+          chapter_no: displayNo,
+          action: action.action || '收束',
+          detail: action.detail || undefined,
+          payload: action,
+        },
+      );
+    }
+
+    await sdb.query(
+      `UPSERT chapter_metric SET
+         story = ${STORY}, chapter = ${chapThing}, chapter_no = $chapter_no,
+         emotion_value = $emotion_value, hook_strength = $hook_strength,
+         word_target = $word_target
+       WHERE story = ${STORY} AND chapter_no = $chapter_no;`,
+      {
+        chapter_no: displayNo,
+        emotion_value: Number(chapter.emotion && chapter.emotion.value) || undefined,
+        hook_strength: chapter.hook && chapter.hook.strength || undefined,
+        word_target: Number(chapter.word_target) || 0,
+      },
+    );
+
+    // Knowledge events are inserted in chapter/array order. The DB event
+    // replays them against knowledge_state and rejects contradictions.
+    for (const event of asArray(chapter.knowledge_events)) {
+      if (!event || !event.subject_id || !event.character) continue;
+      const characterId = String(event.character);
+      const sourceId = event.source_character ? String(event.source_character) : undefined;
+      await sdb.query(
+        `CREATE knowledge_event SET
+           story = ${STORY},
+           chapter = ${chapThing},
+           chapter_no = $chapter_no,
+           subject_type = $subject_type,
+           subject_id = $subject_id,
+           character = type::record('character', $character_id),
+           character_id = $character_id,
+           change = $change,
+           coverage = $coverage,
+           knowledge = $knowledge,
+           how = $how,
+           source_character = IF $source_id = NONE THEN NONE ELSE type::record('character', $source_id) END,
+           scene = $scene,
+           evidence = $evidence,
+           payload = $payload;`,
+        {
+          chapter_no: displayNo,
+          subject_type: event.subject_type || 'information',
+          subject_id: String(event.subject_id),
+          character_id: characterId,
+          change: event.change || 'learns',
+          coverage: event.coverage || 'partial',
+          knowledge: event.knowledge || '',
+          how: event.how || 'other',
+          source_id: sourceId || undefined,
+          scene: event.scene || '',
+          evidence: event.evidence || '',
+          payload: event,
+        },
+      );
+    }
+  }
+
+  await upsertStageDoc(sdb, '40-rhythm', 'chapter_map', doc);
+  return { stage: '40-rhythm', ok: true, chapters: chapters.length };
+}
+
+// ---------------------------------------------------------------------------
+// outlines
+// ---------------------------------------------------------------------------
+
+export async function importOutlines(sdb, projectRoot) {
+  const dir = stageDir(projectRoot, '40-rhythm', 'outlines');
+  if (!fs.existsSync(dir)) throw new StoryDbError('STORYDB_IMPORT', '缺少 40-rhythm/outlines/');
+  const names = fs.readdirSync(dir).filter((name) => name.endsWith('.json'));
+  if (!names.length) throw new StoryDbError('STORYDB_IMPORT', '40-rhythm/outlines/ 为空');
+
+  for (const name of names) {
+    const outline = readJson(path.join(dir, name), null);
+    if (!outline) continue;
+    const chapterId = outline.chapter_id || path.basename(name, '.json');
+    const chapter = await sdb.one(
+      `SELECT * FROM chapter WHERE story = ${STORY} AND chapter_id = $chapter_id LIMIT 1;`,
+      { chapter_id: chapterId },
+    );
+    if (!chapter) {
+      throw new StoryDbError('STORYDB_IMPORT', '细纲引用了不存在的章节：' + chapterId);
+    }
+    await sdb.query(
+      `UPSERT outline SET
+         story = ${STORY}, chapter = type::record('chapter', $chapter_id),
+         chapter_id = $chapter_id, payload = $payload
+       WHERE story = ${STORY} AND chapter_id = $chapter_id;`,
+      { chapter_id: chapterId, payload: withoutMeta(outline) },
+    );
+  }
+  return { stage: 'outline', ok: true, outlines: names.length };
+}
+
+// ---------------------------------------------------------------------------
+// writing
+// ---------------------------------------------------------------------------
+
+function chapterFileName(displayNo) {
+  return '第' + String(displayNo).padStart(3, '0') + '章.md';
+}
+
+export async function importWriting(sdb, projectRoot) {
+  const dir = stageDir(projectRoot, '50-writing');
+  const ledger = readJson(path.join(dir, 'ledger.json'), { chapters: [] });
+  const rows = asArray(ledger.chapters);
+  for (const row of rows) {
+    const chapterId = row.chapter_id || ('CH' + String(row.ch).padStart(3, '0'));
+    const chapter = await sdb.one(
+      `SELECT * FROM chapter WHERE story = ${STORY} AND chapter_id = $chapter_id LIMIT 1;`,
+      { chapter_id: chapterId },
+    );
+    if (!chapter) continue;
+    await sdb.query(
+      `UPSERT ledger_entry SET
+         story = ${STORY}, chapter = type::record('chapter', $chapter_id),
+         chapter_id = $chapter_id, payload = $payload
+       WHERE story = ${STORY} AND chapter_id = $chapter_id;`,
+      { chapter_id: chapterId, payload: withoutMeta(row) },
+    );
+  }
+
+  const chaptersDir = path.join(dir, 'chapters');
+  const names = fs.existsSync(chaptersDir)
+    ? fs.readdirSync(chaptersDir).filter((name) => name.endsWith('.md'))
+    : [];
+  for (const name of names) {
+    const match = /第(\d+)章\.md$/.exec(name);
+    if (!match) continue;
+    const displayNo = Number(match[1]);
+    const chapter = await sdb.one(
+      `SELECT * FROM chapter WHERE story = ${STORY} AND display_no = $display_no LIMIT 1;`,
+      { display_no: displayNo },
+    );
+    if (!chapter) continue;
+    const content = fs.readFileSync(path.join(chaptersDir, name), 'utf8');
+    const wordCount = content.replace(/\s/g, '').length;
+    await sdb.query(
+      `UPSERT chapter_text SET
+         story = ${STORY}, chapter = type::record('chapter', $chapter_id),
+         chapter_id = $chapter_id, display_no = $display_no,
+         content = $content, word_count = $word_count
+       WHERE story = ${STORY} AND chapter_id = $chapter_id;`,
+      {
+        chapter_id: chapter.chapter_id,
+        display_no: displayNo,
+        content,
+        word_count: wordCount,
+      },
+    );
+    await sdb.query(
+      `UPDATE chapter_metric SET word_count = $word_count WHERE story = ${STORY} AND chapter_no = $display_no;`,
+      { word_count: wordCount, display_no: displayNo },
+    );
+  }
+
+  return { stage: '50-writing', ok: true, chapters: names.length };
+}
+
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+
+export async function importStage(sdb, stageId, projectRoot, opts = {}) {
+  try {
+    switch (stageId) {
+      case '10-scale': return await importScale(sdb, projectRoot);
+      case '20-macro': return await importMacro(sdb, projectRoot);
+      case '30-cast': return await importCast(sdb, projectRoot);
+      case '40-rhythm': return await importRhythm(sdb, projectRoot);
+      case 'outline': return await importOutlines(sdb, projectRoot);
+      case '50-writing': return await importWriting(sdb, projectRoot);
+      default: return { stage: stageId, ok: true, skipped: true };
+    }
+  } catch (err) {
+    if (err instanceof StoryDbError) throw err;
+    throw new StoryDbError('STORYDB_IMPORT', '写入故事数据库失败：' + dbErrorMessage(err), {
+      stage: stageId,
+      cause: dbErrorMessage(err),
+    });
+  }
+}