@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

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

@@ -0,0 +1,592 @@
+/**
+ * Shared tool catalog for the story graph.
+ *
+ * Both transports use this file:
+ *   - `mcp.js` exposes the catalog over MCP stdio for DSH/Hermes/other clients
+ *   - `dsh-tools.js` registers the same operations as native DSH tools
+ *
+ * All tools take an optional `project` (novel name or UUID). When omitted the
+ * resolver uses the cwd, the workspace active project, or the only project.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+  openStoryGraph,
+  ensureRootStory,
+  flattenError,
+} from './client.js';
+import {
+  apply,
+  previewApply,
+  getEntity,
+  searchEntities,
+  validate,
+  nextWork,
+  decisionsFor,
+  readQuery,
+} from './store.js';
+import { schemaCard, allSchemaCards } from './compile.js';
+import { chapterContext, entityContext } from './context.js';
+import { impactRelation, impactForeshadow } from './impact.js';
+import { exportStoryGraph } from '../../fancy-export/exporter.js';
+import { stageCheck } from './stage.js';
+import { parseChapterSelection } from './stage-command.js';
+import {
+  resolveWorkspace,
+  workspaceSummary,
+  workspacePaths,
+  readWorkspace,
+} from '../../../lib/workspace.js';
+import {
+  createProject,
+  deleteProject,
+  getProject,
+  listProjects,
+  renameProject,
+  resolveProject,
+  setProjectActive,
+  updateProjectTopic,
+} from '../../../lib/projects.js';
+import { initDatabases, initProjectDatabase } from '../../../lib/db-init.js';
+import { installSurreal, serverStatus, startServer, stopServer } from '../../../lib/surreal-server.js';
+import { createConfirmation, verifyConfirmation } from '../../../lib/confirmation.js';
+
+const sessions = new Map();
+const initialized = new Set();
+
+function jsonSchema(properties = {}, required = []) {
+  return { type: 'object', properties, required, additionalProperties: false };
+}
+
+const PROJECT = { type: 'string', description: '项目小说名或 UUID；省略时用当前项目' };
+const WORKSPACE = { type: 'string', description: '工作区路径；省略时从 cwd/FANCY_HOME/全局指针解析' };
+
+export const TOOLS = [
+  {
+    name: 'workspace_status',
+    description: '查看工作区、SurrealDB 服务、项目列表和共享目录。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'project_list',
+    description: '列出工作区里的所有项目（小说名 + UUID + 数据库）。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'project_get',
+    description: '按小说名或 UUID 查项目信息。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT }, ['project']),
+  },
+  {
+    name: 'project_find',
+    description: '按关键词模糊查找项目。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, query: { type: 'string' } }, ['query']),
+  },
+  {
+    name: 'project_create',
+    description: '创建项目：分配 UUID、项目目录、独立数据库和数据库用户。title 是小说名。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      title: { type: 'string' },
+      topic: { type: 'object' },
+    }, ['title']),
+  },
+  {
+    name: 'project_update_topic',
+    description: '更新项目的选题元数据（不改变 UUID 和目录）。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, topic: { type: 'object' } }, ['project', 'topic']),
+  },
+  {
+    name: 'project_rename',
+    description: '只改数据库里的书名；UUID、目录、数据库都不变。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, title: { type: 'string' } }, ['project', 'title']),
+  },
+  {
+    name: 'project_use',
+    description: '把项目设为工作区当前项目。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT }, ['project']),
+  },
+  {
+    name: 'project_delete',
+    description: '删除项目数据库。必须传 confirm=true；purge=true 时同时删除项目目录。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      confirm: { type: 'boolean' },
+      purge: { type: 'boolean' },
+    }, ['project', 'confirm']),
+  },
+  {
+    name: 'db_status',
+    description: '查看 SurrealDB 服务状态。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'db_start',
+    description: '启动工作区 SurrealDB 服务。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'db_stop',
+    description: '停止工作区 SurrealDB 服务。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'db_install',
+    description: '下载 surreal 二进制到工作区 .fancy/bin。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, version: { type: 'string' } }),
+  },
+  {
+    name: 'db_init',
+    description: '初始化工作区/项目数据库：创建 schema、校验函数、权限和元数据。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, all: { type: 'boolean' } }),
+  },
+  {
+    name: 'scan_list',
+    description: '列出工作区共享的扫榜结果文件。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'analyze_list',
+    description: '列出工作区共享的对标分析目录。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE }),
+  },
+  {
+    name: 'story_status',
+    description: '查看当前项目的总进度、章节数、各阶段数据量。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT }),
+  },
+  {
+    name: 'story_schema',
+    description: '查看故事图表结构；不传 table 时返回全部 schema 卡片。',
+    inputSchema: jsonSchema({ table: { type: 'string' } }),
+  },
+  {
+    name: 'story_get',
+    description: '按类型和 ID 取一条记录。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, kind: { type: 'string' }, id: { type: 'string' } }, ['kind', 'id']),
+  },
+  {
+    name: 'story_search',
+    description: '按字段条件查记录。where 是对象，例如 {"type":"主角"}。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      kind: { type: 'string' },
+      where: { type: 'object' },
+      limit: { type: 'integer' },
+    }, ['kind']),
+  },
+  {
+    name: 'story_context',
+    description: '取章节或实体的最小上下文包；章节模式可带前三章 handoff 和全文检索。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      chapter: { type: 'integer' },
+      prev: { type: 'integer' },
+      tail: { type: 'integer' },
+      search: { type: 'string' },
+      entity: { type: 'string' },
+    }),
+  },
+  {
+    name: 'story_query',
+    description: '只读 SurrealQL 查询（SELECT / INFO / RETURN / SHOW / DESCRIBE / EXPLAIN）。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, sql: { type: 'string' } }, ['sql']),
+  },
+  {
+    name: 'story_impact',
+    description: '影响分析：relation（改人物关系）或 foreshadow（改伏笔动作）。只读，不写入。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      kind: { type: 'string', enum: ['relation', 'foreshadow'] },
+      a: { type: 'string' },
+      b: { type: 'string' },
+      to: { type: 'string' },
+      from: { type: 'integer' },
+      action: { type: 'string' },
+      chapter: { type: 'integer' },
+    }, ['kind', 'a']),
+  },
+  {
+    name: 'story_validate',
+    description: '运行数据库内置校验函数，返回 errors / pending / warnings。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, scope: { type: 'string' } }),
+  },
+  {
+    name: 'story_stage_check',
+    description: '检查阶段完成度：scale / macro / cast / rhythm / outline / writing。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      stage: { type: 'string' },
+      chapters: { type: 'string', description: '章节范围，例如 CH001、1-10、all' },
+    }, ['stage']),
+  },
+  {
+    name: 'story_next',
+    description: '返回当前待办队列。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, limit: { type: 'integer' } }),
+  },
+  {
+    name: 'story_why',
+    description: '查看某条记录当前生效的设计决策。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT, subject: { type: 'string' } }, ['subject']),
+  },
+  {
+    name: 'story_export',
+    description: '把当前项目导出成中文 Markdown 到项目目录/导出。',
+    inputSchema: jsonSchema({ workspace: WORKSPACE, project: PROJECT }),
+  },
+  {
+    name: 'story_preview',
+    description: '预览一次写入：校验 ops/decisions 并返回 confirmation_token。写入前必须先调用它，把预览给用户确认。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      workflow: { type: 'string' },
+      summary: { type: 'string' },
+      ops: { type: 'array', items: { type: 'object' } },
+      decisions: { type: 'array', items: { type: 'object' } },
+      perChapter: { type: 'boolean' },
+      chapters: { type: 'array', items: { type: 'object' } },
+      replaceChapter: { type: 'boolean' },
+      chapter: { type: 'string' },
+      supersedeSubjects: { type: 'array', items: { type: 'string' } },
+      parent: { type: 'string' },
+    }),
+  },
+  {
+    name: 'story_apply',
+    description: '执行一次写入。必须带 story_preview 返回的 confirmation_token；没有 token 会返回 CONFIRMATION_REQUIRED 和预览。',
+    inputSchema: jsonSchema({
+      workspace: WORKSPACE,
+      project: PROJECT,
+      confirmation_token: { type: 'string' },
+      workflow: { type: 'string' },
+      summary: { type: 'string' },
+      ops: { type: 'array', items: { type: 'object' } },
+      decisions: { type: 'array', items: { type: 'object' } },
+      perChapter: { type: 'boolean' },
+      chapters: { type: 'array', items: { type: 'object' } },
+      replaceChapter: { type: 'boolean' },
+      chapter: { type: 'string' },
+      supersedeSubjects: { type: 'array', items: { type: 'string' } },
+      parent: { type: 'string' },
+    }),
+  },
+];
+
+function errorResult(err) {
+  return {
+    ok: false,
+    error: {
+      code: err && err.code ? err.code : 'TOOL_FAILED',
+      message: flattenError(err),
+      detail: err && err.detail ? err.detail : undefined,
+    },
+  };
+}
+
+function workspaceOf(args) {
+  return resolveWorkspace({ cwd: args.cwd || process.cwd(), explicit: args.workspace, required: true, allowGlobal: true });
+}
+
+async function projectOf(args, workspace) {
+  if (args.project) {
+    const project = await getProject(workspace, args.project);
+    if (!project) throw new Error('未找到项目：' + args.project);
+    return project;
+  }
+  return resolveProject({ workspace, cwd: args.cwd || process.cwd() });
+}
+
+async function withStory(args, fn) {
+  const workspace = workspaceOf(args);
+  const project = await projectOf(args, workspace);
+  const key = project.project_id;
+  let sdb = sessions.get(key);
+  if (!sdb || !sdb.isOpen()) {
+    sdb = await openStoryGraph(project.dir, {
+      project,
+      skipSchema: initialized.has(key),
+    });
+    sessions.set(key, sdb);
+    initialized.add(key);
+  }
+  await ensureRootStory(sdb, {});
+  try {
+    return await fn({ sdb, project, workspace });
+  } catch (err) {
+    throw err;
+  }
+}
+
+function listFiles(dir, limit = 200) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (out.length >= limit) return;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else {
+        const stat = fs.statSync(full);
+        out.push({
+          name: path.relative(dir, full),
+          path: full,
+          size: stat.size,
+          modified: stat.mtime.toISOString(),
+        });
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+function writePayload(input) {
+  const keys = ['workflow', 'summary', 'ops', 'decisions', 'perChapter', 'chapters', 'replaceChapter', 'chapter', 'supersedeSubjects', 'parent'];
+  const out = {};
+  for (const key of keys) if (input[key] !== undefined) out[key] = input[key];
+  return out;
+}
+
+async function preview(args) {
+  return withStory(args, async ({ sdb, project, workspace }) => {
+    const payload = writePayload(args);
+    const report = await previewApply(sdb, payload);
+    const confirmation = createConfirmation(workspace, project, payload);
+    return {
+      ok: report.ok,
+      requires_user_confirmation: true,
+      project: { id: project.project_id, name: project.name },
+      preview: report,
+      ...confirmation,
+      instructions: '把 preview 展示给用户；用户明确确认后，再调用 story_apply 并带上 confirmation_token。',
+    };
+  });
+}
+
+export async function callTool(name, args = {}) {
+  try {
+    switch (name) {
+      case 'workspace_status': {
+        const workspace = workspaceOf(args);
+        return {
+          ok: true,
+          workspace: workspaceSummary(workspace),
+          server: await serverStatus(workspace),
+          projects: await listProjects(workspace),
+        };
+      }
+      case 'project_list': {
+        const workspace = workspaceOf(args);
+        return { ok: true, projects: await listProjects(workspace) };
+      }
+      case 'project_get': {
+        const workspace = workspaceOf(args);
+        const project = await getProject(workspace, args.project);
+        return project ? { ok: true, project } : { ok: false, error: { code: 'PROJECT_NOT_FOUND', message: '未找到项目：' + args.project } };
+      }
+      case 'project_find': {
+        const workspace = workspaceOf(args);
+        const projects = await listProjects(workspace);
+        const q = String(args.query || '').toLowerCase();
+        return { ok: true, projects: projects.filter((p) => p.name.toLowerCase().includes(q) || p.project_id.startsWith(q)) };
+      }
+      case 'project_create': {
+        const workspace = workspaceOf(args);
+        const project = await createProject(workspace, { title: args.title, topic: args.topic || {} });
+        const init = await initProjectDatabase(workspace, project.project_id);
+        return { ok: true, project, init };
+      }
+      case 'project_update_topic': {
+        const workspace = workspaceOf(args);
+        const project = await updateProjectTopic(workspace, args.project, args.topic);
+        return { ok: true, project };
+      }
+      case 'project_rename': {
+        const workspace = workspaceOf(args);
+        const project = await renameProject(workspace, args.project, args.title);
+        return { ok: true, project };
+      }
+      case 'project_use': {
+        const workspace = workspaceOf(args);
+        const project = await setProjectActive(workspace, args.project);
+        return { ok: true, project };
+      }
+      case 'project_delete': {
+        const workspace = workspaceOf(args);
+        const target = await getProject(workspace, args.project);
+        if (target) {
+          const cached = sessions.get(target.project_id);
+          if (cached) {
+            try { await cached.close(); } catch { /* ignore */ }
+            sessions.delete(target.project_id);
+          }
+          initialized.delete(target.project_id);
+        }
+        const result = await deleteProject(workspace, args.project, { confirm: args.confirm === true, purge: args.purge === true });
+        return { ok: true, ...result };
+      }
+      case 'db_status': {
+        const workspace = workspaceOf(args);
+        return { ok: true, status: await serverStatus(workspace) };
+      }
+      case 'db_start': {
+        const workspace = workspaceOf(args);
+        return { ok: true, result: await startServer(workspace) };
+      }
+      case 'db_stop': {
+        const workspace = workspaceOf(args);
+        return { ok: true, result: await stopServer(workspace) };
+      }
+      case 'db_install': {
+        const workspace = workspaceOf(args);
+        return { ok: true, result: await installSurreal(workspace, { version: args.version }) };
+      }
+      case 'db_init': {
+        const workspace = workspaceOf(args);
+        const result = await initDatabases(workspace, {
+          project: args.project,
+          all: args.all !== false,
+        });
+        return { ok: true, result };
+      }
+      case 'scan_list': {
+        const workspace = workspaceOf(args);
+        return { ok: true, dir: workspacePaths(workspace).scan, files: listFiles(workspacePaths(workspace).scan) };
+      }
+      case 'analyze_list': {
+        const workspace = workspaceOf(args);
+        return { ok: true, dir: workspacePaths(workspace).analyze, files: listFiles(workspacePaths(workspace).analyze) };
+      }
+      case 'story_status':
+        return withStory(args, async ({ sdb, project }) => {
+          const story = await sdb.one('SELECT * FROM story:main;');
+          const counts = {};
+          for (const table of ['volume', 'act', 'character', 'faction', 'location', 'item', 'conflict', 'foreshadow', 'payoff', 'climax', 'information', 'chapter', 'outline', 'scene', 'chapter_text', 'handoff']) {
+            const row = await sdb.one(`SELECT count() AS n FROM ${table} WHERE story = story:main GROUP ALL;`);
+            counts[table] = Number(row && row.n) || 0;
+          }
+          return { ok: true, project: { id: project.project_id, name: project.name }, story, counts };
+        });
+      case 'story_schema':
+        return {
+          ok: true,
+          ...(args.table ? { table: args.table, card: schemaCard(args.table) } : { cards: allSchemaCards() }),
+        };
+      case 'story_get':
+        return withStory(args, async ({ sdb }) => ({ ok: true, entity: await getEntity(sdb, args.kind, args.id) }));
+      case 'story_search':
+        return withStory(args, async ({ sdb }) => ({
+          ok: true,
+          rows: await searchEntities(sdb, args.kind, { where: args.where || {}, limit: args.limit }),
+        }));
+      case 'story_context':
+        return withStory(args, async ({ sdb }) => {
+          if (args.entity) {
+            const [kind, id] = String(args.entity).split(':');
+            return { ok: true, context: await entityContext(sdb, kind, id) };
+          }
+          return {
+            ok: true,
+            context: await chapterContext(sdb, Number(args.chapter), {
+              prev: Number(args.prev) || 0,
+              tailChars: Number(args.tail) || 600,
+              search: args.search || '',
+            }),
+          };
+        });
+      case 'story_query':
+        return withStory(args, async ({ sdb }) => ({ ok: true, rows: await readQuery(sdb, args.sql) }));
+      case 'story_impact':
+        return withStory(args, async ({ sdb }) => {
+          if (args.kind === 'relation') {
+            return {
+              ok: true,
+              impact: await impactRelation(sdb, args.a, args.b, {
+                newKind: args.to || null,
+                fromChapter: Number(args.from) || 1,
+              }),
+            };
+          }
+          if (args.kind === 'foreshadow') {
+            return {
+              ok: true,
+              impact: await impactForeshadow(sdb, args.a, {
+                action: args.action || null,
+                chapter: args.chapter || null,
+              }),
+            };
+          }
+          throw new Error('未知影响分析类型：' + args.kind);
+        });
+      case 'story_validate':
+        return withStory(args, async ({ sdb }) => ({ ok: true, report: await validate(sdb, { scope: args.scope || null }) }));
+      case 'story_stage_check':
+        return withStory(args, async ({ sdb }) => {
+          const chapters = await sdb.rows('SELECT chapter_id, display_no FROM chapter WHERE story = story:main ORDER BY display_no;');
+          const selection = parseChapterSelection(args.chapters || 'all', chapters, args.stage);
+          if (!selection.ok) return { ok: false, error: { code: 'BAD_CHAPTER_RANGE', message: selection.error } };
+          const result = await stageCheck(sdb, args.stage, {
+            chapterIds: selection.all ? null : selection.ids,
+          });
+          return { ok: true, result: { ...result, selection: selection.label } };
+        });
+      case 'story_next':
+        return withStory(args, async ({ sdb }) => ({ ok: true, rows: await nextWork(sdb, Number(args.limit) || 20) }));
+      case 'story_why':
+        return withStory(args, async ({ sdb }) => ({ ok: true, decisions: await decisionsFor(sdb, args.subject) }));
+      case 'story_export':
+        return withStory(args, async ({ sdb, project }) => ({ ok: true, result: await exportStoryGraph(sdb, project.dir) }));
+      case 'story_preview':
+        return preview(args);
+      case 'story_apply': {
+        const workspace = workspaceOf(args);
+        const project = await projectOf(args, workspace);
+        const payload = writePayload(args);
+        if (!args.confirmation_token) {
+          return withStory(args, async ({ sdb }) => {
+            const report = await previewApply(sdb, payload);
+            return {
+              ok: false,
+              code: 'CONFIRMATION_REQUIRED',
+              message: '写入尚未确认。先展示预览，用户同意后再调用 story_apply 并带 confirmation_token。',
+              preview: report,
+              ...createConfirmation(workspace, project, payload),
+            };
+          });
+        }
+        const verified = verifyConfirmation(workspace, project, args.confirmation_token, payload);
+        if (!verified.ok) {
+          return {
+            ok: false,
+            code: 'CONFIRMATION_INVALID',
+            message: '确认令牌无效或已过期（' + verified.reason + '）。请重新调用 story_preview。',
+          };
+        }
+        return withStory(args, async ({ sdb }) => ({
+          ok: true,
+          result: await apply(sdb, payload),
+        }));
+      }
+      default:
+        return { ok: false, error: { code: 'UNKNOWN_TOOL', message: '未知工具：' + name } };
+    }
+  } catch (err) {
+    return errorResult(err);
+  }
+}
+
+export async function closeAll() {
+  for (const sdb of sessions.values()) {
+    try { await sdb.close(); } catch { /* ignore */ }
+  }
+  sessions.clear();
+  initialized.clear();
+}