@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

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

@@ -0,0 +1,417 @@
+/**
+ * SurrealDB schema for fancy-story-builder.
+ *
+ * Design:
+ *   - relational tables  : story / volume / act / chapter / quota-like summaries
+ *   - document tables    : characters, factions, locations, items, conflicts,
+ *                          foreshadows, payoffs, climaxes, information, outlines,
+ *                          chapter text, ledger rows
+ *   - graph edges        : relations, memberships, chapter_cast, *_action
+ *   - event / timeline   : knowledge_event + knowledge_state (replay)
+ *   - time series        : chapter_metric
+ *   - KV / singleton     : stage_doc
+ *
+ * Every table is SCHEMAFULL where the shape is known. Nested payloads use
+ * `object FLEXIBLE` so a stage can keep fields the query layer does not need
+ * yet without losing them on export.
+ */
+
+function entity(table, extra = []) {
+  return [
+    `DEFINE TABLE IF NOT EXISTS ${table} SCHEMAFULL;`,
+    `DEFINE FIELD IF NOT EXISTS story ON ${table} TYPE record<story>;`,
+    `DEFINE FIELD IF NOT EXISTS entity_id ON ${table} TYPE string;`,
+    `DEFINE FIELD IF NOT EXISTS name ON ${table} TYPE string;`,
+    `DEFINE FIELD IF NOT EXISTS type ON ${table} TYPE option<string>;`,
+    `DEFINE FIELD IF NOT EXISTS payload ON ${table} TYPE object FLEXIBLE;`,
+    `DEFINE INDEX IF NOT EXISTS ${table}_entity ON ${table} FIELDS story, entity_id UNIQUE;`,
+    ...extra,
+  ];
+}
+
+const F = (table, field, type, extra = '') =>
+  `DEFINE FIELD IF NOT EXISTS ${field} ON ${table} TYPE ${type}` +
+  `${type === 'array' && !/DEFAULT/.test(extra) ? ' DEFAULT []' : ''}${extra};`;
+
+export const SCHEMA_STATEMENTS = [
+  // ------------------------------------------------------------------
+  // story / stage bookkeeping
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS story SCHEMAFULL;`,
+  F('story', 'title', 'string'),
+  F('story', 'genre', 'option<string>'),
+  F('story', 'platform', 'option<string>'),
+  F('story', 'target_chapters', 'int'),
+  F('story', 'target_words', 'int'),
+  F('story', 'avg_words_per_chapter', 'int'),
+  F('story', 'created_at', 'datetime', ' VALUE time::now()'),
+  F('story', 'updated_at', 'datetime', ' VALUE time::now()'),
+
+  `DEFINE TABLE IF NOT EXISTS stage_state SCHEMAFULL;`,
+  F('stage_state', 'story', 'record<story>'),
+  F('stage_state', 'stage', 'string'),
+  F('stage_state', 'status', 'string', " ASSERT $value IN ['draft','passed','failed']"),
+  F('stage_state', 'checked_at', 'option<datetime>'),
+  F('stage_state', 'errors', 'array', ' DEFAULT []'),
+  F('stage_state', 'warnings', 'array', ' DEFAULT []'),
+  `DEFINE INDEX IF NOT EXISTS stage_state_stage ON stage_state FIELDS story, stage UNIQUE;`,
+
+  // Generic lossless singleton documents: world / story / emotion / roles /
+  // volumes / lines / endings / scale / relations.
+  `DEFINE TABLE IF NOT EXISTS stage_doc SCHEMAFULL;`,
+  F('stage_doc', 'story', 'record<story>'),
+  F('stage_doc', 'stage', 'string'),
+  F('stage_doc', 'name', 'string'),
+  F('stage_doc', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS stage_doc_key ON stage_doc FIELDS story, stage, name UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // scale: relational skeleton + document payload
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS scale SCHEMAFULL;`,
+  F('scale', 'story', 'record<story>'),
+  F('scale', 'capacity', 'any'),
+  F('scale', 'quotas', 'any'),
+  F('scale', 'rhythm_budget', 'any'),
+  F('scale', 'distribution', 'any'),
+  F('scale', 'constraints', 'any'),
+  F('scale', 'formulas', 'any'),
+  F('scale', 'derivations', 'any'),
+  F('scale', 'genre_profile', 'option<string>'),
+  F('scale', 'formula_version', 'option<string>'),
+  F('scale', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS scale_story ON scale FIELDS story UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS volume SCHEMAFULL;`,
+  F('volume', 'story', 'record<story>'),
+  F('volume', 'volume_id', 'string'),
+  F('volume', 'title', 'option<string>'),
+  F('volume', 'chapter_start', 'int'),
+  F('volume', 'chapter_end', 'int'),
+  F('volume', 'goal', 'option<string>'),
+  F('volume', 'core_conflict', 'option<string>'),
+  F('volume', 'emotional_arc', 'option<string>'),
+  F('volume', 'ending_hook', 'option<string>'),
+  F('volume', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS volume_id ON volume FIELDS story, volume_id UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS act SCHEMAFULL;`,
+  F('act', 'story', 'record<story>'),
+  F('act', 'act_id', 'string'),
+  F('act', 'volume_id', 'string'),
+  F('act', 'act_index', 'int'),
+  F('act', 'chapter_start', 'int'),
+  F('act', 'chapter_end', 'int'),
+  F('act', 'goal', 'option<string>'),
+  F('act', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS act_id ON act FIELDS story, act_id UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // macro: lines / nodes / endings
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS line SCHEMAFULL;`,
+  F('line', 'story', 'record<story>'),
+  F('line', 'line_id', 'string'),
+  F('line', 'kind', 'string', " ASSERT $value IN ['main','branch']"),
+  F('line', 'name', 'string'),
+  F('line', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS line_id ON line FIELDS story, line_id UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS line_node SCHEMAFULL;`,
+  F('line_node', 'story', 'record<story>'),
+  F('line_node', 'node_id', 'string'),
+  F('line_node', 'line_id', 'string'),
+  F('line_node', 'volume', 'option<string>'),
+  F('line_node', 'act', 'option<string>'),
+  F('line_node', 'goal', 'option<string>'),
+  F('line_node', 'turn', 'option<string>'),
+  F('line_node', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS line_node_id ON line_node FIELDS story, node_id UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS ending SCHEMAFULL;`,
+  F('ending', 'story', 'record<story>'),
+  F('ending', 'ending_id', 'string'),
+  F('ending', 'level', 'option<string>'),
+  F('ending', 'type', 'option<string>'),
+  F('ending', 'direction', 'option<string>'),
+  F('ending', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS ending_id ON ending FIELDS story, ending_id UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // cast: entities
+  // ------------------------------------------------------------------
+  ...entity('character', [
+    F('character', 'role_slot', 'option<string>'),
+    F('character', 'faction', 'option<string>'),
+    F('character', 'description', 'option<string>'),
+    F('character', 'goal', 'option<string>'),
+    F('character', 'flaw', 'option<string>'),
+    F('character', 'arc', 'option<string>'),
+    F('character', 'traits', 'array'),
+  ]),
+  ...entity('faction', [
+    F('faction', 'description', 'option<string>'),
+    F('faction', 'goal', 'option<string>'),
+    F('faction', 'resources', 'option<string>'),
+    F('faction', 'territory', 'option<string>'),
+    F('faction', 'internal_conflict', 'option<string>'),
+  ]),
+  ...entity('location', [
+    F('location', 'description', 'option<string>'),
+    F('location', 'narrative_function', 'option<string>'),
+    F('location', 'rules', 'option<string>'),
+  ]),
+  ...entity('item', [
+    F('item', 'category', 'option<string>'),
+    F('item', 'description', 'option<string>'),
+    F('item', 'item_function', 'option<string>'),
+    F('item', 'owner', 'option<string>'),
+    F('item', 'limit', 'option<string>'),
+  ]),
+  ...entity('conflict', [
+    F('conflict', 'description', 'option<string>'),
+    F('conflict', 'core_goal', 'option<string>'),
+    F('conflict', 'stakes', 'option<string>'),
+    F('conflict', 'escalation_path', 'array'),
+    F('conflict', 'resolution_plan', 'option<object>'),
+    F('conflict', 'participants', 'array'),
+  ]),
+  ...entity('foreshadow', [
+    F('foreshadow', 'setup', 'option<string>'),
+    F('foreshadow', 'clues', 'array'),
+    F('foreshadow', 'payoff_target', 'option<string>'),
+    F('foreshadow', 'recovery_requirement', 'option<string>'),
+    F('foreshadow', 'red_herrings', 'array'),
+    F('foreshadow', 'scope', 'option<string>'),
+    F('foreshadow', 'initial_knowledge', 'array'),
+  ]),
+  ...entity('payoff', [
+    F('payoff', 'scale', 'option<string>'),
+    F('payoff', 'setup', 'option<string>'),
+    F('payoff', 'payoff', 'option<string>'),
+    F('payoff', 'emotional_effect', 'option<string>'),
+    F('payoff', 'required_setup', 'array'),
+  ]),
+  ...entity('climax', [
+    F('climax', 'description', 'option<string>'),
+    F('climax', 'payoff', 'option<string>'),
+    F('climax', 'participants', 'array'),
+  ]),
+
+  `DEFINE TABLE IF NOT EXISTS information SCHEMAFULL;`,
+  F('information', 'story', 'record<story>'),
+  F('information', 'entity_id', 'string'),
+  F('information', 'info_name', 'string'),
+  F('information', 'conflict', 'option<string>'),
+  F('information', 'who_knows', 'array'),
+  F('information', 'who_does_not_know', 'array'),
+  F('information', 'resolution_method', 'option<string>'),
+  F('information', 'writing_ban', 'option<string>'),
+  F('information', 'initial_knowledge', 'array'),
+  F('information', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS information_entity ON information FIELDS story, entity_id UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // cast: graph edges
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS relation SCHEMAFULL TYPE RELATION IN character OUT character ENFORCED;`,
+  F('relation', 'story', 'record<story>'),
+  F('relation', 'from_id', 'string'),
+  F('relation', 'to_id', 'string'),
+  F('relation', 'kind', 'string'),
+  F('relation', 'initial_state', 'option<string>'),
+  F('relation', 'changes', 'array'),
+  F('relation', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS faction_relation SCHEMAFULL TYPE RELATION IN faction OUT faction ENFORCED;`,
+  F('faction_relation', 'story', 'record<story>'),
+  F('faction_relation', 'from_id', 'string'),
+  F('faction_relation', 'to_id', 'string'),
+  F('faction_relation', 'kind', 'string'),
+  F('faction_relation', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS membership SCHEMAFULL TYPE RELATION IN character OUT faction ENFORCED;`,
+  F('membership', 'story', 'record<story>'),
+  F('membership', 'role', 'option<string>'),
+  F('membership', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS conflict_participant SCHEMAFULL TYPE RELATION IN conflict OUT character ENFORCED;`,
+  F('conflict_participant', 'story', 'record<story>'),
+
+  `DEFINE TABLE IF NOT EXISTS climax_participant SCHEMAFULL TYPE RELATION IN climax OUT character ENFORCED;`,
+  F('climax_participant', 'story', 'record<story>'),
+
+  `DEFINE TABLE IF NOT EXISTS foreshadow_payoff SCHEMAFULL TYPE RELATION IN foreshadow OUT payoff ENFORCED;`,
+  F('foreshadow_payoff', 'story', 'record<story>'),
+  F('foreshadow_payoff', 'relation', 'option<string>'),
+
+  // ------------------------------------------------------------------
+  // rhythm: chapter + actions
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS chapter SCHEMAFULL;`,
+  F('chapter', 'story', 'record<story>'),
+  F('chapter', 'chapter_id', 'string'),
+  F('chapter', 'display_no', 'int'),
+  F('chapter', 'title', 'string'),
+  F('chapter', 'volume', 'string'),
+  F('chapter', 'act', 'string'),
+  F('chapter', 'pov', 'option<string>'),
+  F('chapter', 'word_target', 'int'),
+  F('chapter', 'emotion_value', 'option<int>'),
+  F('chapter', 'hook_type', 'option<string>'),
+  F('chapter', 'hook_strength', 'option<string>'),
+  F('chapter', 'time', 'object FLEXIBLE'),
+  F('chapter', 'why', 'object FLEXIBLE'),
+  F('chapter', 'how', 'object FLEXIBLE'),
+  F('chapter', 'emotion', 'object FLEXIBLE'),
+  F('chapter', 'hook', 'object FLEXIBLE'),
+  F('chapter', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS chapter_no ON chapter FIELDS story, display_no UNIQUE;`,
+  `DEFINE INDEX IF NOT EXISTS chapter_id ON chapter FIELDS story, chapter_id UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS chapter_cast SCHEMAFULL TYPE RELATION IN chapter OUT character ENFORCED;`,
+  F('chapter_cast', 'story', 'record<story>'),
+  F('chapter_cast', 'role', 'string', " ASSERT $value IN ['pov','cast','mentioned']"),
+
+  `DEFINE TABLE IF NOT EXISTS chapter_location SCHEMAFULL TYPE RELATION IN chapter OUT location ENFORCED;`,
+  F('chapter_location', 'story', 'record<story>'),
+
+  `DEFINE TABLE IF NOT EXISTS foreshadow_action SCHEMAFULL TYPE RELATION IN chapter OUT foreshadow ENFORCED;`,
+  F('foreshadow_action', 'story', 'record<story>'),
+  F('foreshadow_action', 'chapter_no', 'int'),
+  F('foreshadow_action', 'foreshadow_id', 'string'),
+  F('foreshadow_action', 'action', 'string', " ASSERT $value IN ['埋设','回收','推进','强化']"),
+  F('foreshadow_action', 'detail', 'option<string>'),
+  F('foreshadow_action', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS payoff_action SCHEMAFULL TYPE RELATION IN chapter OUT payoff ENFORCED;`,
+  F('payoff_action', 'story', 'record<story>'),
+  F('payoff_action', 'chapter_no', 'int'),
+  F('payoff_action', 'payoff_id', 'string'),
+  F('payoff_action', 'action', 'string', " ASSERT $value IN ['铺垫','兑现','回收']"),
+  F('payoff_action', 'detail', 'option<string>'),
+  F('payoff_action', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS info_action SCHEMAFULL TYPE RELATION IN chapter OUT information ENFORCED;`,
+  F('info_action', 'story', 'record<story>'),
+  F('info_action', 'chapter_no', 'int'),
+  F('info_action', 'info_id', 'string'),
+  F('info_action', 'state', 'string', " ASSERT $value IN ['created','progressed','resolved']"),
+  F('info_action', 'detail', 'option<string>'),
+  F('info_action', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS ending_action SCHEMAFULL TYPE RELATION IN chapter OUT ending ENFORCED;`,
+  F('ending_action', 'story', 'record<story>'),
+  F('ending_action', 'chapter_no', 'int'),
+  F('ending_action', 'ending_id', 'string'),
+  F('ending_action', 'action', 'string', " ASSERT $value IN ['收束']"),
+  F('ending_action', 'detail', 'option<string>'),
+  F('ending_action', 'payload', 'object FLEXIBLE'),
+
+  // ------------------------------------------------------------------
+  // rhythm: knowledge timeline
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS knowledge_event SCHEMAFULL;`,
+  F('knowledge_event', 'story', 'record<story>'),
+  F('knowledge_event', 'chapter', 'record<chapter>'),
+  F('knowledge_event', 'chapter_no', 'int'),
+  F('knowledge_event', 'subject_type', 'string', " ASSERT $value IN ['information','foreshadow']"),
+  F('knowledge_event', 'subject_id', 'string'),
+  F('knowledge_event', 'character', 'record<character>'),
+  F('knowledge_event', 'character_id', 'string'),
+  F('knowledge_event', 'change', 'string', " ASSERT $value IN ['learns','partially_learns','confirms','corrects','forgets','misinforms']"),
+  F('knowledge_event', 'coverage', 'string', " ASSERT $value IN ['unknown','partial','full','false']"),
+  F('knowledge_event', 'knowledge', 'string'),
+  F('knowledge_event', 'how', 'string', " ASSERT $value IN ['witnessed','told','inferred','document','rumor','experience','other']"),
+  F('knowledge_event', 'source_character', 'option<record<character>>'),
+  F('knowledge_event', 'scene', 'string'),
+  F('knowledge_event', 'evidence', 'string'),
+  F('knowledge_event', 'payload', 'object FLEXIBLE'),
+
+  `DEFINE TABLE IF NOT EXISTS knowledge_state SCHEMAFULL;`,
+  F('knowledge_state', 'story', 'record<story>'),
+  F('knowledge_state', 'character', 'record<character>'),
+  F('knowledge_state', 'subject_type', 'string'),
+  F('knowledge_state', 'subject_id', 'string'),
+  F('knowledge_state', 'state', 'string', " ASSERT $value IN ['unknown','partial','full','false']"),
+  `DEFINE INDEX IF NOT EXISTS knowledge_state_key ON knowledge_state FIELDS story, character, subject_type, subject_id UNIQUE;`,
+
+  `DEFINE EVENT OVERWRITE knowledge_rules ON TABLE knowledge_event WHEN $event = 'CREATE' THEN {
+    IF $after.change = 'confirms' AND $after.coverage != 'full' { THROW 'confirms 必须配 coverage=full'; };
+    IF $after.change = 'partially_learns' AND $after.coverage != 'partial' { THROW 'partially_learns 必须配 coverage=partial'; };
+    IF $after.change = 'forgets' AND $after.coverage != 'unknown' { THROW 'forgets 必须配 coverage=unknown'; };
+    IF $after.change = 'misinforms' AND $after.coverage != 'false' { THROW 'misinforms 必须配 coverage=false'; };
+    IF $after.how = 'told' AND $after.source_character = NONE { THROW 'how=told 必须写 source_character'; };
+    IF $after.subject_type = 'information' AND array::len(SELECT VALUE id FROM information WHERE story = $after.story AND entity_id = $after.subject_id LIMIT 1) = 0 { THROW '知识事件引用了不存在的信息差：' + $after.subject_id; };
+    IF $after.subject_type = 'foreshadow' AND array::len(SELECT VALUE id FROM foreshadow WHERE story = $after.story AND entity_id = $after.subject_id LIMIT 1) = 0 { THROW '知识事件引用了不存在的伏笔：' + $after.subject_id; };
+    LET $prev = SELECT VALUE state FROM knowledge_state WHERE story = $after.story AND character = $after.character AND subject_type = $after.subject_type AND subject_id = $after.subject_id LIMIT 1;
+    LET $from = IF array::len($prev) > 0 { $prev[0] } ELSE { 'unknown' };
+    IF $from = 'full' AND $after.change IN ['learns','partially_learns'] { THROW '已 full，不能再写成 learns/partially_learns：' + $after.character_id + ' / ' + $after.subject_id; };
+    IF $from = 'false' AND $after.change IN ['learns','partially_learns','confirms'] { THROW '之前是误信，必须先 corrects：' + $after.character_id + ' / ' + $after.subject_id; };
+    IF $from = 'unknown' AND $after.change = 'confirms' { THROW '尚未学会，不能直接 confirms：' + $after.character_id + ' / ' + $after.subject_id; };
+    UPSERT knowledge_state SET story = $after.story, character = $after.character, subject_type = $after.subject_type, subject_id = $after.subject_id, state = $after.coverage WHERE story = $after.story AND character = $after.character AND subject_type = $after.subject_type AND subject_id = $after.subject_id;
+  };`,
+
+  // ------------------------------------------------------------------
+  // rhythm: time series
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS chapter_metric SCHEMAFULL;`,
+  F('chapter_metric', 'story', 'record<story>'),
+  F('chapter_metric', 'chapter', 'record<chapter>'),
+  F('chapter_metric', 'chapter_no', 'int'),
+  F('chapter_metric', 'emotion_value', 'option<int>'),
+  F('chapter_metric', 'hook_strength', 'option<string>'),
+  F('chapter_metric', 'word_target', 'int'),
+  F('chapter_metric', 'word_count', 'option<int>'),
+  `DEFINE INDEX IF NOT EXISTS chapter_metric_key ON chapter_metric FIELDS story, chapter_no UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // outline / writing
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS outline SCHEMAFULL;`,
+  F('outline', 'story', 'record<story>'),
+  F('outline', 'chapter', 'record<chapter>'),
+  F('outline', 'chapter_id', 'string'),
+  F('outline', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS outline_chapter ON outline FIELDS story, chapter_id UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS chapter_text SCHEMAFULL;`,
+  F('chapter_text', 'story', 'record<story>'),
+  F('chapter_text', 'chapter', 'record<chapter>'),
+  F('chapter_text', 'chapter_id', 'string'),
+  F('chapter_text', 'display_no', 'int'),
+  F('chapter_text', 'content', 'string'),
+  F('chapter_text', 'word_count', 'int'),
+  F('chapter_text', 'updated_at', 'datetime', ' VALUE time::now()'),
+  `DEFINE INDEX IF NOT EXISTS chapter_text_key ON chapter_text FIELDS story, chapter_id UNIQUE;`,
+
+  `DEFINE TABLE IF NOT EXISTS ledger_entry SCHEMAFULL;`,
+  F('ledger_entry', 'story', 'record<story>'),
+  F('ledger_entry', 'chapter', 'record<chapter>'),
+  F('ledger_entry', 'chapter_id', 'string'),
+  F('ledger_entry', 'payload', 'object FLEXIBLE'),
+  `DEFINE INDEX IF NOT EXISTS ledger_entry_key ON ledger_entry FIELDS story, chapter_id UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // audit
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS decision_log SCHEMAFULL;`,
+  F('decision_log', 'story', 'record<story>'),
+  F('decision_log', 'stage', 'string'),
+  F('decision_log', 'scope', 'option<string>'),
+  F('decision_log', 'item', 'option<string>'),
+  F('decision_log', 'text', 'string'),
+  F('decision_log', 'source_path', 'option<string>'),
+  F('decision_log', 'reference', 'option<string>'),
+  F('decision_log', 'reason', 'option<string>'),
+  F('decision_log', 'created_at', 'datetime', ' VALUE time::now()'),
+
+  `DEFINE TABLE IF NOT EXISTS validation_issue SCHEMAFULL;`,
+  F('validation_issue', 'story', 'record<story>'),
+  F('validation_issue', 'stage', 'string'),
+  F('validation_issue', 'code', 'string'),
+  F('validation_issue', 'severity', 'string', " ASSERT $value IN ['error','warning']"),
+  F('validation_issue', 'path', 'option<string>'),
+  F('validation_issue', 'message', 'string'),
+  F('validation_issue', 'created_at', 'datetime', ' VALUE time::now()'),
+];

package/plugins/fancy-story-builder/db/stage-sync.js

@@ -0,0 +1,238 @@
+/**
+ * Stage command wrapper: database is the truth, stage JSON is a projection.
+ *
+ *   1. open the project database
+ *   2. project existing DB data into `设定/...` so prompts/validators see it
+ *   3. run the existing stage handler (the LLM writes JSON)
+ *   4. import the JSON into SurrealDB in one transaction
+ *   5. if the DB rejects it, delete only the offending files and retry
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { notify } from '#infra';
+import {
+  dbErrorMessage,
+  ensureStory,
+  openStoryDb,
+  setStageState,
+  StoryDbError,
+} from './client.js';
+import { importStage } from './import.js';
+import { projectForStage, writeStageStatus } from './project.js';
+
+export function isStoryDbProject(projectRoot) {
+  try {
+    return fs.existsSync(path.join(projectRoot, '.fancy-storydb'));
+  } catch {
+    return false;
+  }
+}
+
+const STAGE_STATE = {
+  '10-scale': '10-scale',
+  '20-macro': '20-macro',
+  '30-cast': '30-cast',
+  '40-rhythm': '40-rhythm',
+  outline: '40-rhythm',
+  '50-writing': '50-writing',
+};
+
+const CAST_FILES = {
+  character: 'characters.json',
+  faction: 'factions.json',
+  location: 'locations.json',
+  item: 'items.json',
+  conflict: 'conflicts.json',
+  foreshadow: 'foreshadows.json',
+  climax: 'climaxes.json',
+  payoff: 'payoffs.json',
+  information: 'information.json',
+  relation: 'relations.json',
+  faction_relation: 'relations.json',
+  membership: 'relations.json',
+};
+
+const MACRO_FILES = ['world', 'story', 'volumes', 'lines', 'endings', 'emotion', 'roles'];
+
+function stageDir(projectRoot, stageId) {
+  return path.join(projectRoot, '设定', stageId === 'outline' ? '40-rhythm' : stageId);
+}
+
+function chapterFromError(message) {
+  const out = [];
+  for (const match of String(message).matchAll(/第\s*(\d+)\s*章/g)) {
+    out.push(Number(match[1]));
+  }
+  for (const match of String(message).matchAll(/chapters\[(\d+)\]/g)) {
+    out.push(Number(match[1]) + 1);
+  }
+  return [...new Set(out)];
+}
+
+function chunkFileForChapter(projectRoot, chapterNo) {
+  const dir = path.join(stageDir(projectRoot, '40-rhythm'), '.chapter-map');
+  if (!fs.existsSync(dir)) return null;
+  for (const name of fs.readdirSync(dir)) {
+    if (!/^V\d{3}-\d{2}\.json$/.test(name)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+      if ((data.chapters || []).some((chapter) => Number(chapter.display_no) === chapterNo)) {
+        return path.join(dir, name);
+      }
+    } catch {
+      // unreadable shard: leave it for the stage validator
+    }
+  }
+  return null;
+}
+
+/**
+ * Remove the smallest set of generated files that can explain a DB rejection.
+ * The existing stage handler regenerates missing files on the next attempt.
+ */
+export function removeBadFiles(err, stageId, projectRoot) {
+  const message = (err && (err.message || '') ) + ' ' + (err && err.detail ? JSON.stringify(err.detail) : '');
+  const removed = [];
+  const drop = (file) => {
+    try {
+      if (file && fs.existsSync(file)) {
+        fs.unlinkSync(file);
+        removed.push(file);
+      }
+    } catch {
+      // best effort
+    }
+  };
+
+  const chapters = chapterFromError(message);
+  if (chapters.length && (stageId === '40-rhythm' || stageId === 'outline')) {
+    for (const chapterNo of chapters) {
+      const chunk = chunkFileForChapter(projectRoot, chapterNo);
+      if (chunk) drop(chunk);
+      const outline = path.join(stageDir(projectRoot, '40-rhythm'), 'outlines', 'CH' + String(chapterNo).padStart(3, '0') + '.json');
+      if (stageId === 'outline') drop(outline);
+    }
+    if (stageId === '40-rhythm') {
+      drop(path.join(stageDir(projectRoot, '40-rhythm'), 'chapter_map.json'));
+    }
+  }
+
+  if (stageId === '30-cast') {
+    for (const [table, file] of Object.entries(CAST_FILES)) {
+      if (new RegExp('\\b' + table + '\\b').test(message)) {
+        drop(path.join(stageDir(projectRoot, '30-cast'), file));
+      }
+    }
+  }
+
+  if (stageId === '20-macro') {
+    for (const name of MACRO_FILES) {
+      if (new RegExp('\\b' + name + '\\b').test(message)) {
+        drop(path.join(stageDir(projectRoot, '20-macro'), name + '.json'));
+      }
+    }
+    if (!removed.length) drop(path.join(stageDir(projectRoot, '20-macro'), 'volumes.json'));
+  }
+
+  if (stageId === '10-scale') {
+    drop(path.join(stageDir(projectRoot, '10-scale'), 'scale.json'));
+  }
+
+  if (stageId === '50-writing') {
+    for (const chapterNo of chapters) {
+      drop(path.join(stageDir(projectRoot, '50-writing'), 'chapters', '第' + String(chapterNo).padStart(3, '0') + '章.md'));
+    }
+    drop(path.join(stageDir(projectRoot, '50-writing'), 'ledger.json'));
+  }
+
+  return [...new Set(removed)];
+}
+
+function storyInfo(topicData) {
+  const topic = topicData || {};
+  return {
+    title: topic.title || topic.book_name || topic.name || undefined,
+    genre: topic.genre || topic.type || undefined,
+    platform: topic.platform || undefined,
+    target_chapters: Number(topic.target_chapters) || undefined,
+    target_words: Number(topic.target_words) || undefined,
+    avg_words_per_chapter: Number(topic.avg_words_per_chapter) || undefined,
+  };
+}
+
+async function markState(sdb, projectRoot, stageId, status, errors = [], warnings = []) {
+  const stateStage = STAGE_STATE[stageId] || stageId;
+  await setStageState(sdb, stateStage, status, errors, warnings);
+  if (stateStage !== 'outline') {
+    await writeStageStatus(sdb, projectRoot, stateStage);
+  }
+}
+
+/**
+ * Run a stage handler against the project database.
+ *
+ * The handler is the existing file-based implementation. It is treated as a
+ * pure "generate files" function; this wrapper owns persistence.
+ */
+export async function runWithStoryDb(opts) {
+  const {
+    session,
+    projectRoot,
+    stageId,
+    topicData,
+    handler,
+    maxAttempts = 2,
+  } = opts || {};
+
+  let sdb;
+  try {
+    sdb = await openStoryDb(projectRoot);
+  } catch (err) {
+    if (err instanceof StoryDbError && err.code === 'STORYDB_LOCKED') {
+      return notify(session, 'error', err.message + '\n\n请先关闭另一个正在使用同一项目的会话。');
+    }
+    return notify(session, 'error', '故事数据库打开失败：' + dbErrorMessage(err));
+  }
+
+  try {
+    await ensureStory(sdb, storyInfo(topicData));
+    await projectForStage(sdb, stageId, projectRoot);
+
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const result = await handler();
+      if (result && result.kind === 'error') {
+        await markState(sdb, projectRoot, stageId, 'failed', [{ code: 'STAGE_FAILED', message: result.text }]);
+        return result;
+      }
+
+      try {
+        await sdb.tx(async () => {
+          await importStage(sdb, stageId, projectRoot);
+        });
+        await markState(sdb, projectRoot, stageId, 'passed');
+        return result;
+      } catch (err) {
+        lastError = err;
+        const message = dbErrorMessage(err);
+        const detail = err && err.detail ? err.detail : null;
+        const removed = removeBadFiles(err, stageId, projectRoot);
+        await markState(sdb, projectRoot, stageId, 'failed', [{
+          code: err && err.code ? err.code : 'STORYDB_IMPORT',
+          message,
+          detail,
+        }]);
+        if (!removed.length || attempt >= maxAttempts) {
+          return notify(session, 'error',
+            '❌ 数据库拒绝了本阶段的产物，已回滚：\n' + message +
+            (removed.length ? '\n\n已删除待重生成的文件：\n- ' + removed.join('\n- ') : '') +
+            '\n\n数据未写入数据库；修复后重新运行本阶段即可。');
+        }
+      }
+    }
+    return notify(session, 'error', '❌ 数据库写入失败：' + dbErrorMessage(lastError));
+  } finally {
+    await sdb.close();
+  }
+}