@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

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

@@ -0,0 +1,228 @@
+/**
+ * Embedded SurrealDB connection for one project.
+ *
+ * One project = one `surrealkv://` directory under `设定/.storydb`.
+ * The connection is exclusive: a second process opening the same directory
+ * gets a clear STORYDB_LOCKED error instead of a cryptic engine failure.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { Surreal, createRemoteEngines } from 'surrealdb';
+import { createNodeEngines } from '@surrealdb/node';
+import { SCHEMA_STATEMENTS } from './schema.js';
+import { STORY_ID, storyThing } from './ids.js';
+
+export const DB_DIR = '.fancy-storydb';
+export const NAMESPACE = 'fancy';
+export const DATABASE = 'webnovel';
+
+export function dbPath(projectRoot) {
+  return path.join(projectRoot, DB_DIR);
+}
+
+export class StoryDbError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'StoryDbError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+function flattenError(err) {
+  if (!err) return 'unknown error';
+  if (typeof err === 'string') return err;
+  const parts = [];
+  if (err.message) parts.push(err.message);
+  if (err.cause && err.cause.message && err.cause.message !== err.message) parts.push(err.cause.message);
+  if (Array.isArray(err.errors)) {
+    for (const e of err.errors) parts.push(flattenError(e));
+  }
+  return parts.filter(Boolean).join(' | ') || String(err);
+}
+
+export function dbErrorMessage(err) {
+  return flattenError(err);
+}
+
+export async function openStoryDb(projectRoot, opts = {}) {
+  const memory = Boolean(opts.memory);
+  const dir = dbPath(projectRoot);
+  if (!memory) {
+    try {
+      fs.mkdirSync(path.dirname(dir), { recursive: true });
+    } catch {
+      // parent may already exist
+    }
+  }
+
+  const db = new Surreal({
+    engines: {
+      ...createRemoteEngines(),
+      ...createNodeEngines(),
+    },
+  });
+
+  const endpoint = memory ? 'mem://' : 'surrealkv://' + dir;
+  try {
+    await db.connect(endpoint);
+  } catch (err) {
+    const message = dbErrorMessage(err);
+    if (/lock|already|exclusive|open/i.test(message)) {
+      throw new StoryDbError(
+        'STORYDB_LOCKED',
+        '故事数据库正被另一个进程占用：' + dir,
+        message,
+      );
+    }
+    throw new StoryDbError('STORYDB_CONNECT', '无法打开故事数据库：' + dir, message);
+  }
+
+  await db.use({ namespace: NAMESPACE, database: DATABASE });
+  await migrate(db);
+
+  let closed = false;
+  let batch = null;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    try {
+      await db.close();
+    } catch {
+      // closing an in-memory store can race with the last query
+    }
+  };
+
+  const api = {
+    db,
+    dir,
+    memory,
+    close,
+    beginBatch() {
+      batch = [];
+    },
+    cancelBatch() {
+      batch = null;
+    },
+    async commitBatch() {
+      if (!batch) return [];
+      // SurrealDB's transaction API rejects duplicate parameter names across
+      // statements. Prefix every binding with the statement index so the same
+      // $id / $payload can be used by every query in the batch.
+      const queries = batch.map((item, index) => {
+        const prefix = 'q' + index + '_';
+        const sql = String(item.sql).replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) => '$' + prefix + name);
+        const vars = {};
+        for (const [key, value] of Object.entries(item.vars || {})) {
+          vars[prefix + key] = value;
+        }
+        return db.query(sql, vars);
+      });
+      batch = null;
+      try {
+        return await db.transaction(queries);
+      } catch (err) {
+        throw new StoryDbError('STORYDB_TX', dbErrorMessage(err), { queries: queries.length });
+      }
+    },
+    async query(sql, vars) {
+      if (batch) {
+        batch.push({ sql, vars });
+        return [[]];
+      }
+      try {
+        return await db.query(sql, vars);
+      } catch (err) {
+        throw new StoryDbError('STORYDB_QUERY', dbErrorMessage(err), { sql });
+      }
+    },
+    async rows(sql, vars) {
+      const out = await db.query(sql, vars);
+      return Array.isArray(out) && Array.isArray(out[0]) ? out[0] : [];
+    },
+    async one(sql, vars) {
+      const rows = await api.rows(sql, vars);
+      return rows[0] || null;
+    },
+    async tx(fn) {
+      api.beginBatch();
+      try {
+        const result = await fn();
+        await api.commitBatch();
+        return result;
+      } catch (err) {
+        api.cancelBatch();
+        throw err;
+      }
+    },
+  };
+  return api;
+}
+
+export async function migrate(db) {
+  for (const statement of SCHEMA_STATEMENTS) {
+    try {
+      await db.query(statement);
+    } catch (err) {
+      throw new StoryDbError(
+        'STORYDB_MIGRATE',
+        '数据库 schema 初始化失败：' + flattenError(err),
+        { statement: statement.slice(0, 200) },
+      );
+    }
+  }
+}
+
+export async function ensureStory(sdb, info = {}) {
+  const targetChapters = Number(info.target_chapters) || 0;
+  const targetWords = Number(info.target_words) || 0;
+  const avg = Number(info.avg_words_per_chapter)
+    || (targetChapters > 0 ? Math.round(targetWords / targetChapters) : 0);
+
+  const existing = await sdb.one('SELECT * FROM story:main;');
+  const base = {
+    title: info.title || (existing && existing.title) || '未命名故事',
+    target_chapters: targetChapters || (existing && existing.target_chapters) || 0,
+    target_words: targetWords || (existing && existing.target_words) || 0,
+    avg_words_per_chapter: avg || (existing && existing.avg_words_per_chapter) || 0,
+  };
+  if (info.genre) base.genre = info.genre;
+  else if (existing && existing.genre) base.genre = existing.genre;
+  if (info.platform) base.platform = info.platform;
+  else if (existing && existing.platform) base.platform = existing.platform;
+
+  const sets = Object.keys(base).map((key) => key + ' = $' + key).join(', ');
+  if (existing) {
+    await sdb.query(`UPDATE story:main SET ${sets}, updated_at = time::now();`, base);
+  } else {
+    await sdb.query(`CREATE story:main SET ${sets};`, base);
+  }
+  return sdb.one('SELECT * FROM story:main;');
+}
+
+/** Mark a stage status. Used by the wrapper for resume / diagnostics. */
+export async function setStageState(sdb, stage, status, errors = [], warnings = []) {
+  await sdb.query(
+    `UPSERT stage_state SET
+       story = ${storyThing()},
+       stage = $stage,
+       status = $status,
+       checked_at = time::now(),
+       errors = $errors,
+       warnings = $warnings
+     WHERE story = ${storyThing()} AND stage = $stage;`,
+    { stage, status, errors, warnings },
+  );
+}
+
+export async function getStageState(sdb, stage) {
+  return sdb.one(
+    `SELECT * FROM stage_state WHERE story = ${storyThing()} AND stage = $stage LIMIT 1;`,
+    { stage },
+  );
+}
+
+export function storyId() {
+  return STORY_ID;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * `tools query` and `tools analyze` command handlers.
+ *
+ * Both are read-only and return JSON so an agent can pipe the result back
+ * into its reasoning without re-reading stage files.
+ */
+
+import { notify } from '#infra';
+import { openStoryDb } from './client.js';
+import {
+  analyzeForeshadowChange,
+  analyzeRelationChange,
+  getChapters,
+  getCharacter,
+  getForeshadow,
+  getKnowledge,
+  getRelations,
+  getStatus,
+  runReadOnlySql,
+} from './query.js';
+
+function splitArgs(text) {
+  return String(text || '').trim().split(/\s+/).filter(Boolean);
+}
+
+function parseFlags(tokens) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i];
+    if (token.startsWith('--')) {
+      const key = token.slice(2);
+      const next = tokens[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next;
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      args.push(token);
+    }
+  }
+  return { args, flags };
+}
+
+function chapterRange(value) {
+  const text = String(value || '');
+  const match = /^(\d+)(?:\s*[-~]\s*(\d+))?$/.exec(text);
+  if (!match) return null;
+  return { from: Number(match[1]), to: Number(match[2] || match[1]) };
+}
+
+function json(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+async function withDb(projectRoot, fn) {
+  const sdb = await openStoryDb(projectRoot);
+  try {
+    return await fn(sdb);
+  } finally {
+    await sdb.close();
+  }
+}
+
+export async function handleDbQuery(session, projectRoot, rawInput) {
+  const text = String(rawInput || '').replace(/^query\b/i, '').trim();
+  const tokens = splitArgs(text);
+  const head = (tokens[0] || '').toLowerCase();
+  try {
+    const result = await withDb(projectRoot, async (sdb) => {
+      if (!head || head === 'status') return getStatus(sdb);
+      if (head === 'foreshadow') {
+        if (!tokens[1]) throw new Error('用法：query foreshadow <ID或名称>');
+        return getForeshadow(sdb, tokens[1]);
+      }
+      if (head === 'character') {
+        if (!tokens[1]) throw new Error('用法：query character <ID或名称>');
+        return getCharacter(sdb, tokens[1]);
+      }
+      if (head === 'relations') {
+        if (!tokens[1]) throw new Error('用法：query relations <人物ID或名称>');
+        return getRelations(sdb, tokens[1]);
+      }
+      if (head === 'knowledge') {
+        if (!tokens[1]) throw new Error('用法：query knowledge <人物ID或名称> [--chapter N]');
+        const { flags } = parseFlags(tokens.slice(2));
+        return getKnowledge(sdb, tokens[1], flags.chapter);
+      }
+      if (head === 'chapter') {
+        const range = chapterRange(tokens[1]);
+        if (!range) throw new Error('用法：query chapter <起始章>[-<结束章>]');
+        return getChapters(sdb, range.from, range.to);
+      }
+      if (head === 'sql') {
+        return runReadOnlySql(sdb, tokens.slice(1).join(' '));
+      }
+      if (/^(select|info|return|show|describe|explain)\b/i.test(text)) {
+        return runReadOnlySql(sdb, text);
+      }
+      throw new Error(
+        '未知查询。可用：status / foreshadow <ID> / character <ID> / relations <ID> / '
+        + 'knowledge <ID> [--chapter N] / chapter <起>[-<止>] / sql <SELECT ...>',
+      );
+    });
+    return notify(session, 'success', json(result));
+  } catch (err) {
+    return notify(session, 'error', '查询执行失败：' + (err && err.message ? err.message : String(err)));
+  }
+}
+
+export async function handleAnalyze(session, projectRoot, rawInput) {
+  const text = String(rawInput || '').replace(/^analyze\b/i, '').trim();
+  const tokens = splitArgs(text);
+  const head = (tokens[0] || '').toLowerCase();
+  try {
+    const result = await withDb(projectRoot, async (sdb) => {
+      if (head === 'relation') {
+        const { args, flags } = parseFlags(tokens.slice(1));
+        if (args.length < 2) {
+          throw new Error('用法：analyze relation <A> <B> [--to 对立] [--from 第N章]');
+        }
+        return analyzeRelationChange(sdb, args[0], args[1], {
+          newKind: flags.to && flags.to !== true ? flags.to : null,
+          fromChapter: flags.from && flags.from !== true ? Number(flags.from) : 1,
+        });
+      }
+      if (head === 'foreshadow') {
+        const { args, flags } = parseFlags(tokens.slice(1));
+        if (!args[0]) {
+          throw new Error('用法：analyze foreshadow <ID或名称> [--action 回收] [--chapter 第N章]');
+        }
+        return analyzeForeshadowChange(sdb, args[0], {
+          action: flags.action && flags.action !== true ? flags.action : null,
+          chapter: flags.chapter && flags.chapter !== true ? Number(flags.chapter) : null,
+        });
+      }
+      throw new Error('不支持的分析类型。可用：analyze relation <A> <B> / analyze foreshadow <ID>');
+    });
+    return notify(session, 'success', json(result));
+  } catch (err) {
+    return notify(session, 'error', '分析执行失败：' + (err && err.message ? err.message : String(err)));
+  }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * SurrealDB record id helpers.
+ *
+ * Business ids (C001 / FS012 / CH001 / V001 / A001 ...) are kept as the
+ * record key so that every stage file, prompt and export can round-trip.
+ * `type::thing()` is used instead of string interpolation so ids containing
+ * dashes (IG-X001-01) are escaped by the server.
+ */
+
+export function thing(table, id) {
+  return `type::record(${surrealString(table)}, ${surrealString(String(id))})`;
+}
+
+export function surrealString(value) {
+  return JSON.stringify(String(value));
+}
+
+/**
+ * Literal record id usable where SurrealQL does not accept a function call,
+ * e.g. the endpoints of RELATE. `⟨...⟩` is the canonical escaping form.
+ */
+export function recordLiteral(table, id) {
+  return table + ':⟨' + String(id).replace(/[⟩]/g, '_') + '⟩';
+}
+
+/** A deterministic edge key: relation:C001__C002__1 */
+export function edgeKey(parts) {
+  return parts
+    .map((part) => String(part == null ? '' : part))
+    .join('__')
+    .replace(/[^A-Za-z0-9_-]/g, '_');
+}
+
+/** Story record id. One embedded database per project, so `main` is stable. */
+export const STORY_ID = 'main';
+
+export function storyThing() {
+  return 'story:main';
+}