@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/storydb/driver.js

@@ -0,0 +1,106 @@
+/**
+ * Stage driver for the storydb-native flow.
+ *
+ * The plugin sends a prompt; the LLM works through the storydb CLI; the driver
+ * waits for the turn to finish, then runs `stageCheck`. If the stage is not
+ * complete, it sends a repair prompt with the exact DB errors.
+ *
+ * The database connection must be closed before sending a prompt: the CLI is
+ * embedded and takes an exclusive file lock.
+ */
+
+import { lastTurnFailure } from '../writing-driver.js';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForTurn(invocation, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 90 * 60 * 1000;
+  const idleGraceMs = opts.idleGraceMs || 60 * 1000;
+  const pollMs = opts.pollMs || 500;
+  const signal = opts.signal || null;
+  const agent = invocation && invocation.agent;
+  if (!agent || typeof agent.status !== 'string') {
+    return { ok: false, code: 'NO_AGENT', reason: '当前运行时没有暴露 agent，无法等待 LLM 完成本轮' };
+  }
+  const session = agent.session || null;
+  const sinceSeq = session && Array.isArray(session.log) ? session.log.length : undefined;
+  const started = Date.now();
+  let sawRunning = false;
+
+  while (Date.now() - started < timeoutMs) {
+    if (signal && signal.aborted) {
+      return { ok: false, code: 'ABORTED', reason: '已被用户中断' };
+    }
+    if (agent.status === 'running') {
+      sawRunning = true;
+      await sleep(pollMs);
+      continue;
+    }
+    if (sawRunning) {
+      const failure = lastTurnFailure(session, sinceSeq);
+      if (failure) return { ok: false, code: failure.code, reason: failure.reason };
+      return { ok: true };
+    }
+    if (Date.now() - started > idleGraceMs) {
+      return { ok: false, code: 'TIMEOUT', reason: '等待 LLM 响应超时（未观察到本轮启动）' };
+    }
+    await sleep(pollMs);
+  }
+  return { ok: false, code: 'TIMEOUT', reason: '等待 LLM 响应超时' };
+}
+
+/**
+ * Send -> wait -> check -> repair, up to maxRounds.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage
+ * @param {(prompt:string)=>Promise<{ok:boolean,error?:string}>} opts.sendPrompt
+ * @param {(prompt:string)=>Promise<{ok:boolean,code?:string,reason?:string}>} opts.waitTurn
+ * @param {()=>Promise<object>} opts.checkStage
+ * @param {(ctx:object)=>string} opts.buildPrompt
+ * @param {(stage:string,check:object)=>string} opts.buildRepair
+ * @param {object} opts.context
+ * @param {number} [opts.maxRounds]
+ */
+export async function runStageLoop(opts) {
+  const {
+    stage,
+    sendPrompt,
+    waitTurn,
+    checkStage,
+    buildPrompt,
+    buildRepair,
+    context,
+    maxRounds = 3,
+  } = opts;
+
+  let prompt = buildPrompt(context);
+  let lastCheck = null;
+
+  for (let round = 1; round <= maxRounds; round += 1) {
+    const sent = await sendPrompt(prompt);
+    if (!sent || sent.ok !== true) {
+      return { ok: false, stage, round, error: (sent && sent.error) || '提示词投递失败', check: lastCheck };
+    }
+    const wait = await waitTurn();
+    if (!wait || wait.ok !== true) {
+      return {
+        ok: false,
+        stage,
+        round,
+        error: (wait && wait.reason) || '等待 LLM 完成失败',
+        code: wait && wait.code,
+        check: lastCheck,
+      };
+    }
+    lastCheck = await checkStage();
+    if (lastCheck && lastCheck.ok) {
+      return { ok: true, stage, round, check: lastCheck };
+    }
+    prompt = buildRepair(stage, lastCheck);
+  }
+
+  return { ok: false, stage, round: maxRounds, error: '阶段多轮仍未通过', check: lastCheck };
+}

package/plugins/fancy-story-builder/storydb/dsh-tools.js

@@ -0,0 +1,313 @@
+/**
+ * Native DSH tool adapter.
+ *
+ * DSH loads this package as a cordis plugin. Registering the same operations as
+ * native tools means natural-language requests work without requiring the user
+ * to wire `dsh-mcp-client` separately. The MCP server remains available for
+ * Hermes, Claude Desktop, Cursor and other clients.
+ *
+ * Write tools ask for a real UI confirmation through `ctx.userQuestions` before
+ * calling the shared `story_apply` handler, so natural-language writes get the
+ * required second confirmation even when the model is eager.
+ */
+
+import { callTool } from './tools.js';
+
+const json = { type: 'json' };
+const str = (description) => ({ type: 'string', description });
+const int = (description) => ({ type: 'integer', description });
+const bool = (description) => ({ type: 'boolean', description });
+
+function output() {
+  return {
+    schema: json,
+    render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+  };
+}
+
+function projectParam() {
+  return str('项目小说名或 UUID；省略时用当前项目');
+}
+
+function workspaceParam() {
+  return str('工作区路径；省略时从 cwd/FANCY_HOME/全局指针解析');
+}
+
+function summarizePreview(preview) {
+  const p = preview && preview.preview ? preview.preview : preview;
+  if (!p) return '没有预览';
+  return [
+    '项目：' + (preview.project?.name || preview.project?.id || '—'),
+    '操作：' + (p.operations || 0) + ' 条',
+    '决策：' + (p.decisions || 0) + ' 条' + (p.chapters ? '，章节：' + p.chapters + ' 章' : ''),
+    p.errors && p.errors.length ? '错误：' + p.errors.map((e) => e.message).join('；') : '校验：通过',
+  ].join('\n');
+}
+
+async function confirm(ctx, exec, question, options = null) {
+  const answer = await ctx.userQuestions.ask({
+    questions: [{
+      id: 'confirm_fancy_write',
+      header: '确认写入',
+      question,
+      options: options || [
+        { label: '确认写入', description: '按预览执行并提交事务' },
+        { label: '取消', description: '不写入任何数据' },
+      ],
+    }],
+    ...(exec.agent !== undefined ? { agent: exec.agent } : {}),
+    signal: exec.signal,
+  });
+  const selected = answer?.answers?.[0]?.selected?.[0];
+  return selected === '确认写入' || selected === '确认删除';
+}
+
+export async function registerNativeTools(ctx) {
+  let defineTool;
+  try {
+    ({ defineTool } = await import('@deepseek-ai/dsh-tools'));
+  } catch {
+    return;
+  }
+  if (!ctx.tools || typeof ctx.tools.register !== 'function') return;
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_workspace',
+    description: 'fancy-webnovel 工作区与项目管理：status/list/get/create/rename/use/delete/update_topic/init。自然语言里说“列出我的小说项目”“把《X》改名为《Y》”时用这个工具。',
+    parameters: {
+      action: { type: 'string', required: true, enum: ['status', 'list', 'get', 'create', 'rename', 'use', 'delete', 'update_topic', 'init'] },
+      project: projectParam(),
+      query: str('查找关键词'),
+      title: str('小说名 / 新小说名'),
+      topic: json,
+      confirm: bool('删除时必须为 true'),
+      purge: bool('删除时是否同时删除项目目录'),
+      workspace: workspaceParam(),
+      all: bool('init 时是否初始化全部项目库'),
+    },
+    output: output(),
+    async execute(args, exec) {
+      switch (args.action) {
+        case 'status': return callTool('workspace_status', args);
+        case 'list': return callTool('project_list', args);
+        case 'get': return callTool('project_get', args);
+        case 'create': return callTool('project_create', args);
+        case 'rename': return callTool('project_rename', args);
+        case 'use': return callTool('project_use', args);
+        case 'delete': {
+          if (args.confirm !== true) {
+            const approved = await confirm(ctx, exec, '确定删除项目《' + (args.project || '') + '》的数据库吗？\n默认会把项目目录移到 .fancy/trash。', [
+              { label: '确认删除', description: '删除数据库并归档项目目录' },
+              { label: '取消', description: '不删除任何东西' },
+            ]);
+            if (!approved) return { ok: false, code: 'CANCELLED', message: '用户取消了删除' };
+          }
+          return callTool('project_delete', { ...args, confirm: true });
+        }
+        case 'update_topic': return callTool('project_update_topic', args);
+        case 'init': return callTool('db_init', args);
+        default: return { ok: false, error: { code: 'UNKNOWN_ACTION', message: '未知 action：' + args.action } };
+      }
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_db',
+    description: 'SurrealDB 服务与项目库管理：status/start/stop/install/init/list/remove。',
+    parameters: {
+      action: { type: 'string', required: true, enum: ['status', 'start', 'stop', 'install', 'init', 'list', 'remove'] },
+      project: projectParam(),
+      workspace: workspaceParam(),
+      all: bool('init 时是否初始化全部项目库'),
+      confirm: bool('删除时必须为 true'),
+      purge: bool('删除时是否同时删除项目目录'),
+      version: str('安装指定 surreal 版本'),
+    },
+    output: output(),
+    async execute(args, exec) {
+      switch (args.action) {
+        case 'status': return callTool('db_status', args);
+        case 'start': return callTool('db_start', args);
+        case 'stop': return callTool('db_stop', args);
+        case 'install': return callTool('db_install', args);
+        case 'init': return callTool('db_init', args);
+        case 'list': return callTool('project_list', args);
+        case 'remove': {
+          if (args.confirm !== true) {
+            const approved = await confirm(ctx, exec, '确定删除项目《' + (args.project || '') + '》的数据库吗？', [
+              { label: '确认删除', description: '删除数据库并归档项目目录' },
+              { label: '取消', description: '不删除任何东西' },
+            ]);
+            if (!approved) return { ok: false, code: 'CANCELLED', message: '用户取消了删除' };
+          }
+          return callTool('project_delete', { ...args, confirm: true });
+        }
+        default: return { ok: false, error: { code: 'UNKNOWN_ACTION', message: '未知 action：' + args.action } };
+      }
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_story_read',
+    description: '只读故事图工具：status/schema/get/search/query/context/validate/stage_check/next/why/impact。分析人物关系改动、查章节上下文、校验数据库都用这个工具，不会写入。',
+    parameters: {
+      action: { type: 'string', required: true, enum: ['status', 'schema', 'get', 'search', 'query', 'context', 'validate', 'stage_check', 'next', 'why', 'impact'] },
+      project: projectParam(),
+      workspace: workspaceParam(),
+      table: str('表名'),
+      kind: str('实体类型'),
+      id: str('实体 ID'),
+      where: json,
+      limit: int('返回条数'),
+      sql: str('只读 SurrealQL'),
+      chapter: int('章号'),
+      prev: int('前几章'),
+      tail: int('前文截取字数'),
+      search: str('全文检索关键词'),
+      entity: str('实体上下文，例如 foreshadow:FS001'),
+      scope: str('校验范围，例如 chapter:CH001'),
+      stage: str('阶段：scale/macro/cast/rhythm/outline/writing'),
+      chapters: str('章节范围，例如 CH001、1-10、all'),
+      subject: str('决策主体'),
+      a: str('影响分析主体 A / 伏笔 ID'),
+      b: str('影响分析主体 B'),
+      to: str('新关系'),
+      from: int('影响起始章'),
+      impact_action: str('伏笔动作'),
+      impact_chapter: int('伏笔动作章号'),
+    },
+    output: output(),
+    async execute(args) {
+      const base = args;
+      switch (args.action) {
+        case 'status': return callTool('story_status', base);
+        case 'schema': return callTool('story_schema', base);
+        case 'get': return callTool('story_get', base);
+        case 'search': return callTool('story_search', base);
+        case 'query': return callTool('story_query', base);
+        case 'context': return callTool('story_context', base);
+        case 'validate': return callTool('story_validate', base);
+        case 'stage_check': return callTool('story_stage_check', base);
+        case 'next': return callTool('story_next', base);
+        case 'why': return callTool('story_why', base);
+        case 'impact':
+          return callTool('story_impact', {
+            ...base,
+            action: args.impact_action,
+            chapter: args.impact_chapter,
+          });
+        default: return { ok: false, error: { code: 'UNKNOWN_ACTION', message: '未知 action：' + args.action } };
+      }
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_story_preview',
+    description: '预览一次故事图写入，返回 confirmation_token 和影响摘要。写入前先用它，把预览内容告诉用户。',
+    parameters: {
+      action: { type: 'string', enum: ['preview'] },
+      project: projectParam(),
+      workspace: workspaceParam(),
+      workflow: str('工作流名'),
+      summary: str('本次写入摘要'),
+      ops: { type: 'array', items: json },
+      decisions: { type: 'array', items: json },
+      perChapter: bool('按章提交'),
+      chapters: { type: 'array', items: json },
+      replaceChapter: bool('重写某章时替换该章旧边'),
+      chapter: str('单章 ID'),
+      supersedeSubjects: { type: 'array', items: { type: 'string' } },
+      parent: str('父 change_set'),
+    },
+    output: output(),
+    async execute(args) {
+      return callTool('story_preview', args);
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_story_apply',
+    description: '写入故事图。会先显示预览并弹窗要求用户确认，确认后才提交事务。自然语言里用户说“改/写入/创建”时用这个工具，不要直接改文件。',
+    parameters: {
+      action: { type: 'string', enum: ['apply'] },
+      project: projectParam(),
+      workspace: workspaceParam(),
+      workflow: str('工作流名'),
+      summary: str('本次写入摘要'),
+      ops: { type: 'array', items: json },
+      decisions: { type: 'array', items: json },
+      perChapter: bool('按章提交'),
+      chapters: { type: 'array', items: json },
+      replaceChapter: bool('重写某章时替换该章旧边'),
+      chapter: str('单章 ID'),
+      supersedeSubjects: { type: 'array', items: { type: 'string' } },
+      parent: str('父 change_set'),
+    },
+    output: output(),
+    async execute(args, exec) {
+      const preview = await callTool('story_preview', args);
+      if (!preview || preview.ok === false) return preview;
+      const approved = await confirm(ctx, exec, '即将写入故事图：\n\n' + summarizePreview(preview) + '\n\n确认提交吗？');
+      if (!approved) return { ok: false, code: 'CANCELLED', message: '用户取消了写入' };
+      return callTool('story_apply', {
+        ...args,
+        confirmation_token: preview.confirmation_token,
+      });
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_story_apply_batch',
+    description: '仅供 /fancy-build 等用户显式发起的阶段批量写入。不做逐批弹窗；自然语言请求不要用这个工具，改用 fancy_story_apply。',
+    parameters: {
+      action: { type: 'string', enum: ['apply'] },
+      project: projectParam(),
+      workspace: workspaceParam(),
+      workflow: str('工作流名'),
+      summary: str('本次写入摘要'),
+      ops: { type: 'array', items: json },
+      decisions: { type: 'array', items: json },
+      perChapter: bool('按章提交'),
+      chapters: { type: 'array', items: json },
+      replaceChapter: bool('重写某章时替换该章旧边'),
+      chapter: str('单章 ID'),
+      supersedeSubjects: { type: 'array', items: { type: 'string' } },
+      parent: str('父 change_set'),
+    },
+    output: output(),
+    async execute(args) {
+      const preview = await callTool('story_preview', args);
+      if (!preview || preview.ok === false) return preview;
+      return callTool('story_apply', {
+        ...args,
+        confirmation_token: preview.confirmation_token,
+      });
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_story_export',
+    description: '把当前项目导出成中文 Markdown 到项目目录/导出。',
+    parameters: {
+      project: projectParam(),
+      workspace: workspaceParam(),
+    },
+    output: output(),
+    async execute(args) {
+      return callTool('story_export', args);
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'fancy_shared_assets',
+    description: '查看工作区共享的扫榜结果（scan）或对标分析（analyze）文件。',
+    parameters: {
+      action: { type: 'string', required: true, enum: ['scan', 'analyze'] },
+      workspace: workspaceParam(),
+    },
+    output: output(),
+    async execute(args) {
+      return callTool(args.action === 'scan' ? 'scan_list' : 'analyze_list', args);
+    },
+  }));
+}

package/plugins/fancy-story-builder/storydb/export.js

@@ -0,0 +1,175 @@
+/**
+ * Markdown export from the story graph. The database is the source; this file
+ * only renders a readable projection.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const STORY = 'story:main';
+
+const STAGES = ['10-scale', '20-macro', '30-cast', '40-rhythm', '50-writing'];
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function mdTable(headers, rows) {
+  const lines = [];
+  lines.push('| ' + headers.join(' | ') + ' |');
+  lines.push('|' + headers.map(() => '---').join('|') + '|');
+  for (const row of rows) {
+    lines.push('| ' + row.map((cell) => String(cell == null ? '' : cell).replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ') + ' |');
+  }
+  return lines.join('\n');
+}
+
+function json(value) {
+  return '```json\n' + JSON.stringify(value, null, 2) + '\n```';
+}
+
+async function renderScale(sdb) {
+  const scale = await sdb.one('SELECT * FROM scale:main;');
+  const volumes = await sdb.rows(`SELECT * FROM volume WHERE story = ${STORY} ORDER BY chapter_start;`);
+  const acts = await sdb.rows(`SELECT * FROM act WHERE story = ${STORY} ORDER BY chapter_start;`);
+  const lines = ['# 10-scale 规模', ''];
+  if (scale) lines.push('## 容量与配额', json(scale.payload || scale));
+  lines.push('', '## 卷', mdTable(['ID', '标题', '起', '止'], volumes.map((v) => [v.volume_id, v.title, v.chapter_start, v.chapter_end])));
+  lines.push('', '## 幕', mdTable(['ID', '卷', '起', '止', '目标'], acts.map((a) => [a.act_id, a.volume_id, a.chapter_start, a.chapter_end, a.goal])));
+  return lines.join('\n');
+}
+
+async function renderMacro(sdb) {
+  const docs = await sdb.rows(`SELECT * FROM world_doc WHERE story = ${STORY};`);
+  const storyDocs = await sdb.rows(`SELECT * FROM story_doc WHERE story = ${STORY};`);
+  const lines = ['# 20-macro 宏观', ''];
+  for (const doc of docs) lines.push('## 世界观', json(doc.payload || doc));
+  for (const doc of storyDocs) lines.push('## 故事', json(doc.payload || doc));
+  const volumes = await sdb.rows(`SELECT * FROM volume WHERE story = ${STORY} ORDER BY chapter_start;`);
+  lines.push('', '## 卷纲', mdTable(['ID', '标题', '起', '止', '目标'], volumes.map((v) => [v.volume_id, v.title, v.chapter_start, v.chapter_end, v.goal])));
+  const lineRows = await sdb.rows(`SELECT * FROM line WHERE story = ${STORY} ORDER BY kind, line_id;`);
+  for (const line of lineRows) {
+    lines.push('', '### ' + (line.kind === 'main' ? '主线' : '支线') + '：' + line.name);
+    const nodes = await sdb.rows(`SELECT * FROM line_node WHERE story = ${STORY} AND line_id = $id ORDER BY node_id;`, { id: line.line_id });
+    lines.push(mdTable(['节点', '卷', '幕', '目标', '转折'], nodes.map((n) => [n.node_id, n.volume, n.act, n.goal, n.turn])));
+  }
+  const endings = await sdb.rows(`SELECT * FROM ending WHERE story = ${STORY} ORDER BY ending_id;`);
+  lines.push('', '## 结局', mdTable(['ID', '层级', '类型', '方向'], endings.map((e) => [e.ending_id, e.level, e.type, e.direction])));
+  return lines.join('\n');
+}
+
+async function renderCast(sdb) {
+  const lines = ['# 30-cast 实体', ''];
+  const specs = [
+    ['character', '人物', ['entity_id', 'name', 'type', 'role_slot', 'faction']],
+    ['faction', '势力', ['entity_id', 'name', 'type', 'goal']],
+    ['location', '地点', ['entity_id', 'name', 'type', 'narrative_function']],
+    ['item', '道具', ['entity_id', 'name', 'category', 'owner']],
+    ['conflict', '冲突', ['entity_id', 'name', 'type', 'core_goal']],
+    ['foreshadow', '伏笔', ['entity_id', 'name', 'type', 'scope', 'status']],
+    ['payoff', '爽点', ['entity_id', 'name', 'scale', 'status']],
+    ['climax', '高潮', ['entity_id', 'name', 'type', 'status']],
+    ['information', '信息差', ['entity_id', 'info_name', 'conflict', 'status']],
+  ];
+  for (const [table, title, fields] of specs) {
+    const rows = await sdb.rows(`SELECT * FROM ${table} WHERE story = ${STORY} ORDER BY entity_id;`);
+    lines.push('', '## ' + title + '（' + rows.length + '）');
+    lines.push(mdTable(fields, rows.map((row) => fields.map((f) => row[f]))));
+  }
+  const rels = await sdb.rows(`SELECT * FROM relation WHERE story = ${STORY};`);
+  lines.push('', '## 人物关系');
+  lines.push(mdTable(['从', '到', '关系', '初始'], rels.map((r) => [r.from_id, r.to_id, r.kind, r.initial_state])));
+  return lines.join('\n');
+}
+
+async function renderRhythm(sdb) {
+  const chapters = await sdb.rows(`SELECT * FROM chapter WHERE story = ${STORY} ORDER BY display_no;`);
+  const lines = ['# 40-rhythm 章节地图', ''];
+  lines.push(mdTable(
+    ['章', 'ID', '标题', '卷', '幕', 'POV', '情绪', '钩子', '字数', '状态'],
+    chapters.map((c) => [
+      c.display_no, c.chapter_id, c.title, c.volume, c.act, c.pov,
+      c.emotion && c.emotion.value, c.hook && (c.hook.type + '/' + c.hook.strength),
+      c.word_target, c.status,
+    ]),
+  ));
+  const outlines = await sdb.rows(`SELECT * FROM outline WHERE story = ${STORY} ORDER BY chapter_id;`);
+  if (outlines.length) {
+    lines.push('', '## 细纲');
+    for (const outline of outlines) {
+      const p = outline.payload || {};
+      lines.push('', '### ' + outline.chapter_id + ' ' + (p.title || ''));
+      if (p.must_write) lines.push('- 必写：' + p.must_write.join('；'));
+      if (p.must_not_write) lines.push('- 禁写：' + p.must_not_write.join('；'));
+      const scenes = await sdb.rows(`SELECT * FROM scene WHERE story = ${STORY} AND outline_id = $id ORDER BY scene_order;`, { id: outline.chapter_id });
+      if (scenes.length) {
+        lines.push(mdTable(['序', '目标', '障碍', '转折', '结果', '地点'], scenes.map((s) => [s.scene_order, s.goal, s.obstacle, s.turn, s.outcome, s.location])));
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+async function renderWriting(sdb) {
+  const rows = await sdb.rows(`SELECT * FROM chapter_text WHERE story = ${STORY} ORDER BY display_no;`);
+  const lines = ['# 50-writing 正文', ''];
+  if (!rows.length) lines.push('（暂无正文）');
+  for (const row of rows) {
+    lines.push('', '## 第 ' + row.display_no + ' 章', '', row.content);
+    const handoff = await sdb.one(`SELECT * FROM handoff WHERE story = ${STORY} AND chapter_id = $id LIMIT 1;`, { id: row.chapter_id });
+    if (handoff) {
+      lines.push('', '> 章末交接：地点=' + (handoff.end_location || '-') + '；线索=' + (handoff.open_threads || []).join('；'));
+    }
+  }
+  return lines.join('\n');
+}
+
+async function renderDecisions(sdb) {
+  const rows = await sdb.rows(
+    `SELECT * FROM decision WHERE story = story:main AND status = 'active' ORDER BY created_at;`,
+  );
+  const lines = ['# 设计决策（active）', ''];
+  if (!rows.length) {
+    lines.push('（暂无决策）');
+  } else {
+    lines.push(mdTable(
+      ['时间', '范围', '条目', '说明', '来源', '参考', '理由'],
+      rows.map((row) => [
+        row.created_at, row.scope, row.subject, row.text, row.source, row.reference, row.reason,
+      ]),
+    ));
+  }
+  return lines.join('\n');
+}
+
+const RENDERERS = {
+  '10-scale': renderScale,
+  '20-macro': renderMacro,
+  '30-cast': renderCast,
+  '40-rhythm': renderRhythm,
+  '50-writing': renderWriting,
+};
+
+export async function exportMarkdown(sdb, projectRoot, what = 'all') {
+  if (what === 'decisions') {
+    const markdown = await renderDecisions(sdb);
+    const dir = path.join(projectRoot, '设定', 'exports');
+    ensureDir(dir);
+    const file = path.join(dir, 'decisions.md');
+    fs.writeFileSync(file, markdown + '\n', 'utf8');
+    return { exported: [{ stage: 'decisions', file, chars: markdown.length }] };
+  }
+  const stages = what === 'all' ? STAGES : [what];
+  const out = [];
+  for (const stage of stages) {
+    const renderer = RENDERERS[stage];
+    if (!renderer) throw new Error('未知导出阶段：' + stage);
+    const markdown = await renderer(sdb);
+    const dir = path.join(projectRoot, '设定', 'exports', stage);
+    ensureDir(dir);
+    const file = path.join(dir, stage + '.md');
+    fs.writeFileSync(file, markdown + '\n', 'utf8');
+    out.push({ stage, file, chars: markdown.length });
+  }
+  return { exported: out };
+}

package/plugins/fancy-story-builder/storydb/ids.js

@@ -0,0 +1,31 @@
+/**
+ * Record id helpers for storydb.
+ */
+
+export function surrealString(value) {
+  return JSON.stringify(String(value));
+}
+
+export function recordLiteral(table, id) {
+  return table + ':⟨' + String(id).replace(/[⟩]/g, '_') + '⟩';
+}
+
+export function parseRef(value, fallbackTable) {
+  const text = String(value == null ? '' : value).trim();
+  if (!text) return null;
+  const idx = text.indexOf(':');
+  if (idx > 0) {
+    return { table: text.slice(0, idx), id: text.slice(idx + 1) };
+  }
+  return fallbackTable ? { table: fallbackTable, id: text } : null;
+}
+
+export function refString(ref) {
+  return ref.table + ':' + ref.id;
+}
+
+export function uuid() {
+  return globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function'
+    ? globalThis.crypto.randomUUID()
+    : 'id-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10);
+}