@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

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

@@ -0,0 +1,452 @@
+/**
+ * Compile storydb definitions into:
+ *   - SurrealQL DDL
+ *   - per-table schema cards
+ *   - JSON schemas for tool arguments
+ *
+ * One definition, three consumers. This is what keeps the LLM-facing schema
+ * and the database schema from drifting apart.
+ */
+
+import { ENTITIES, EDGES, HOOK_TYPES, EMOTION_PHASES } from './definitions.js';
+import { validationDdl, SCHEMA_VERSION, VALIDATION_VERSION } from './validation.js';
+
+function q(value) {
+  return JSON.stringify(String(value));
+}
+
+function enumAssert(values) {
+  return '$value IN [' + values.map(q).join(', ') + ']';
+}
+
+function baseType(field) {
+  switch (field.type) {
+    case 'string':
+    case 'text':
+      return 'string';
+    case 'int':
+      return 'int';
+    case 'float':
+      return 'float';
+    case 'bool':
+      return 'bool';
+    case 'datetime':
+      return 'datetime';
+    case 'array':
+      return 'array';
+    case 'object':
+      return 'object FLEXIBLE';
+    case 'record':
+      return 'record<' + field.table + '>';
+    case 'enum':
+      return 'string';
+    default:
+      return 'string';
+  }
+}
+
+function fieldDdl(table, name, field) {
+  const base = baseType(field);
+  const optional = !field.required && !['array', 'object'].includes(field.type);
+  const type = optional ? 'option<' + base + '>' : base;
+  const parts = [`DEFINE FIELD IF NOT EXISTS ${name} ON ${table} TYPE ${type}`];
+
+  if (field.type === 'array') {
+    parts.push('DEFAULT []');
+    if (field.required && field.nonEmpty) parts.push('ASSERT array::len($value) > 0');
+  }
+  if (field.type === 'enum') {
+    const assert = field.required
+      ? enumAssert(field.values)
+      : `$value = NONE OR ${enumAssert(field.values)}`;
+    parts.push('ASSERT ' + assert);
+  }
+  if (field.type === 'object' && field.required) {
+    parts.push('ASSERT $value != NONE');
+  }
+  if (field.default !== undefined) {
+    const v = field.default;
+    parts.push('DEFAULT ' + (typeof v === 'string' ? q(v) : String(v)));
+  }
+  return parts.join(' ') + ';';
+}
+
+function entityDdl(key, def) {
+  const table = def.table;
+  const lines = [
+    `DEFINE TABLE IF NOT EXISTS ${table} SCHEMAFULL;`,
+  ];
+  if (key === 'story') {
+    // story:main is the singleton root; no `story` back-reference.
+  } else {
+    lines.push(`DEFINE FIELD IF NOT EXISTS story ON ${table} TYPE record<story>;`);
+    if (!def.internal) {
+      lines.push(`DEFINE FIELD IF NOT EXISTS entity_id ON ${table} TYPE string;`);
+      lines.push(`DEFINE INDEX IF NOT EXISTS ${table}_entity ON ${table} FIELDS story, entity_id UNIQUE;`);
+    }
+  }
+  for (const [name, field] of Object.entries(def.fields || {})) {
+    lines.push(fieldDdl(table, name, field));
+  }
+  lines.push(`DEFINE FIELD IF NOT EXISTS payload ON ${table} TYPE object FLEXIBLE;`);
+  lines.push(`DEFINE FIELD IF NOT EXISTS created_at ON ${table} TYPE datetime VALUE time::now();`);
+  lines.push(`DEFINE FIELD IF NOT EXISTS updated_at ON ${table} TYPE datetime VALUE time::now();`);
+  return lines;
+}
+
+function edgeDdl(key, def) {
+  const table = def.table;
+  const lines = [
+    `DEFINE TABLE IF NOT EXISTS ${table} SCHEMAFULL TYPE RELATION IN ${def.in} OUT ${def.out} ENFORCED;`,
+    `DEFINE FIELD IF NOT EXISTS story ON ${table} TYPE record<story>;`,
+    `DEFINE FIELD IF NOT EXISTS from_id ON ${table} TYPE string;`,
+    `DEFINE FIELD IF NOT EXISTS to_id ON ${table} TYPE string;`,
+    `DEFINE FIELD IF NOT EXISTS payload ON ${table} TYPE object FLEXIBLE;`,
+    `DEFINE FIELD IF NOT EXISTS created_at ON ${table} TYPE datetime VALUE time::now();`,
+  ];
+  for (const [name, field] of Object.entries(def.fields || {})) {
+    lines.push(fieldDdl(table, name, field));
+  }
+  // Prevents duplicate structural edges; action edges are intentionally not unique.
+  if (['has_volume', 'has_act', 'has_chapter', 'chapter_cast', 'chapter_location'].includes(key)) {
+    lines.push(`DEFINE INDEX IF NOT EXISTS ${table}_pair ON ${table} FIELDS in, out UNIQUE;`);
+  }
+  return lines;
+}
+
+function knowledgeRules() {
+  return `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;
+  };`;
+}
+
+function chapterGuard() {
+  return `DEFINE EVENT OVERWRITE chapter_guard ON TABLE chapter WHEN $event = 'CREATE' OR $event = 'UPDATE' THEN {
+    IF array::len(SELECT VALUE id FROM volume WHERE story = $after.story AND volume_id = $after.volume LIMIT 1) = 0 { THROW '章节引用了不存在的卷：' + $after.volume; };
+    IF array::len(SELECT VALUE id FROM act WHERE story = $after.story AND act_id = $after.act LIMIT 1) = 0 { THROW '章节引用了不存在的幕：' + $after.act; };
+    IF $after.emotion.value != NONE AND ($after.emotion.value < 1 OR $after.emotion.value > 10) { THROW 'emotion.value 必须在 1-10'; };
+    IF $after.hook.strength != NONE AND !($after.hook.strength IN ['强','中','弱']) { THROW 'hook.strength 必须是 强/中/弱'; };
+    LET $prev = SELECT * FROM chapter WHERE story = $after.story AND display_no < $after.display_no ORDER BY display_no DESC LIMIT 1;
+    IF array::len($prev) > 0 {
+      LET $p = $prev[0];
+      IF $p.time.story_day != NONE AND $after.time.story_day != NONE AND $after.time.story_day < $p.time.story_day AND $after.time.flashback != true {
+        THROW '时间线倒退：第 ' + <string>$after.display_no + ' 章 story_day=' + <string>$after.time.story_day + ' 早于第 ' + <string>$p.display_no + ' 章 story_day=' + <string>$p.time.story_day + '（闪回应标记 time.flashback=true）';
+      };
+      IF $p.hook.type != NONE AND $after.hook.type != NONE AND $p.hook.type = $after.hook.type {
+        LET $prev2 = SELECT * FROM chapter WHERE story = $after.story AND display_no < $p.display_no ORDER BY display_no DESC LIMIT 1;
+        IF array::len($prev2) > 0 AND $prev2[0].hook.type = $after.hook.type {
+          THROW '钩子重复：第 ' + <string>$prev2[0].display_no + '/' + <string>$p.display_no + '/' + <string>$after.display_no + ' 章连续使用 ' + $after.hook.type;
+        };
+      };
+    };
+  };`;
+}
+
+function foreshadowOrder() {
+  return `DEFINE EVENT OVERWRITE foreshadow_order ON TABLE foreshadow_action WHEN $event = 'CREATE' THEN {
+    IF $after.action IN ['progress','reveal'] {
+      LET $plant = SELECT * FROM foreshadow_action WHERE story = $after.story AND to_id = $after.to_id AND action = 'plant' AND chapter_no <= $after.chapter_no LIMIT 1;
+      IF array::len($plant) = 0 { THROW '伏笔 ' + $after.to_id + ' 在第 ' + <string>$after.chapter_no + ' 章之前没有埋设，不能 ' + $after.action; };
+    };
+    IF $after.action = 'plant' {
+      LET $reveal = SELECT * FROM foreshadow_action WHERE story = $after.story AND to_id = $after.to_id AND action = 'reveal' AND chapter_no <= $after.chapter_no LIMIT 1;
+      IF array::len($reveal) > 0 { THROW '伏笔 ' + $after.to_id + ' 已在更早章节回收，不能再埋设'; };
+    };
+  };`;
+}
+
+function payoffOrder() {
+  return `DEFINE EVENT OVERWRITE payoff_order ON TABLE payoff_action WHEN $event = 'CREATE' THEN {
+    IF $after.action = 'payoff' {
+      LET $setup = SELECT * FROM payoff_action
+        WHERE story = $after.story AND to_id = $after.to_id AND action = 'setup'
+        ORDER BY chapter_no ASC LIMIT 1;
+      IF array::len($setup) > 0 AND $setup[0].chapter_no > $after.chapter_no {
+        THROW '爽点 ' + $after.to_id + ' 的兑现章（' + <string>$after.chapter_no + '）早于铺垫章（' + <string>$setup[0].chapter_no + '）';
+      };
+    };
+    IF $after.action = 'setup' {
+      LET $payoff = SELECT * FROM payoff_action
+        WHERE story = $after.story AND to_id = $after.to_id AND action = 'payoff'
+          AND chapter_no < $after.chapter_no
+        ORDER BY chapter_no DESC LIMIT 1;
+      IF array::len($payoff) > 0 {
+        THROW '爽点 ' + $after.to_id + ' 的铺垫章（' + <string>$after.chapter_no + '）晚于已有的兑现章（' + <string>$payoff[0].chapter_no + '）';
+      };
+    };
+  };`;
+}
+
+function completeGuards() {
+  const out = [];
+  for (const [key, def] of Object.entries(ENTITIES)) {
+    const reqs = (def.requirements || []).filter((r) => r.hard);
+    if (!reqs.length || key === 'story') continue;
+    const table = def.table;
+    out.push(`DEFINE EVENT OVERWRITE complete_${table} ON TABLE ${table}
+      WHEN $event = 'UPDATE' AND $after.status = 'complete'
+      THEN {
+        LET $pending = SELECT * FROM requirement
+          WHERE story = $after.story
+            AND subject = '${table}:' + $after.entity_id
+            AND status = 'pending'
+            AND hard = true;
+        IF array::len($pending) > 0 {
+          THROW '${def.label || table} 还有 ' + <string>array::len($pending) + ' 个必填待办未完成，不能标记 complete';
+        };
+      };`);
+  }
+  return out;
+}
+
+function fillEvents() {
+  const out = [];
+  for (const [key, def] of Object.entries(EDGES)) {
+    if (!def.fills) continue;
+    const table = def.table;
+    const kindExpr = (actionField) =>
+      `'${Object.values(def.fills)[0]}'`; // replaced per action below
+    for (const [action, kind] of Object.entries(def.fills)) {
+      out.push(`DEFINE EVENT OVERWRITE fill_${table}_${action} ON TABLE ${table}
+        WHEN $event = 'CREATE' AND $after.action = ${q(action)}
+        THEN {
+          UPDATE requirement SET status = 'filled', filled_by = <string>$after.id, updated_at = time::now()
+          WHERE story = $after.story AND subject = '${def.out}:' + $after.to_id AND kind = ${q(kind)} AND status = 'pending';
+        };`);
+      out.push(`DEFINE EVENT OVERWRITE unfill_${table}_${action} ON TABLE ${table}
+        WHEN $event = 'DELETE' AND $before.action = ${q(action)}
+        THEN {
+          IF array::len(SELECT * FROM ${table} WHERE story = $before.story AND to_id = $before.to_id AND action = ${q(action)} LIMIT 1) = 0 {
+            UPDATE requirement SET status = 'pending', filled_by = NONE, updated_at = time::now()
+            WHERE story = $before.story AND subject = '${def.out}:' + $before.to_id AND kind = ${q(kind)} AND status = 'filled';
+          };
+        };`);
+    }
+  }
+
+  // outline created -> chapter_outline filled
+  out.push(`DEFINE EVENT OVERWRITE fill_chapter_outline ON TABLE outline
+    WHEN $event = 'CREATE'
+    THEN {
+      UPDATE requirement SET status = 'filled', filled_by = <string>$after.id, updated_at = time::now()
+      WHERE story = $after.story AND subject = 'chapter:' + $after.chapter_id AND kind = 'chapter_outline' AND status = 'pending';
+    };`);
+  out.push(`DEFINE EVENT OVERWRITE unfill_chapter_outline ON TABLE outline
+    WHEN $event = 'DELETE'
+    THEN {
+      IF array::len(SELECT * FROM outline WHERE story = $before.story AND chapter_id = $before.chapter_id LIMIT 1) = 0 {
+        UPDATE requirement SET status = 'pending', filled_by = NONE, updated_at = time::now()
+        WHERE story = $before.story AND subject = 'chapter:' + $before.chapter_id AND kind = 'chapter_outline' AND status = 'filled';
+      };
+    };`);
+
+  // chapter_text created -> chapter_draft filled
+  out.push(`DEFINE EVENT OVERWRITE fill_chapter_draft ON TABLE chapter_text
+    WHEN $event = 'CREATE'
+    THEN {
+      UPDATE requirement SET status = 'filled', filled_by = <string>$after.id, updated_at = time::now()
+      WHERE story = $after.story AND subject = 'chapter:' + $after.chapter_id AND kind = 'chapter_draft' AND status = 'pending';
+    };`);
+  out.push(`DEFINE EVENT OVERWRITE unfill_chapter_draft ON TABLE chapter_text
+    WHEN $event = 'DELETE'
+    THEN {
+      IF array::len(SELECT * FROM chapter_text WHERE story = $before.story AND chapter_id = $before.chapter_id LIMIT 1) = 0 {
+        UPDATE requirement SET status = 'pending', filled_by = NONE, updated_at = time::now()
+        WHERE story = $before.story AND subject = 'chapter:' + $before.chapter_id AND kind = 'chapter_draft' AND status = 'filled';
+      };
+    };`);
+
+  // scene created -> outline_scenes filled
+  out.push(`DEFINE EVENT OVERWRITE fill_outline_scenes ON TABLE scene
+    WHEN $event = 'CREATE'
+    THEN {
+      UPDATE requirement SET status = 'filled', filled_by = <string>$after.id, updated_at = time::now()
+      WHERE story = $after.story AND subject = 'outline:' + $after.outline_id AND kind = 'outline_scenes' AND status = 'pending';
+    };`);
+
+  return out;
+}
+
+export const SEARCH_INDEX_DDL = {
+  modern: `DEFINE INDEX IF NOT EXISTS chapter_text_fts ON chapter_text FIELDS content SEARCH ANALYZER story_zh BM25(1.2, 0.75);`,
+  legacy: `DEFINE INDEX IF NOT EXISTS chapter_text_fts ON chapter_text FIELDS content FULLTEXT ANALYZER story_zh BM25(1.2, 0.75);`,
+};
+
+export const DDL = [
+  // ------------------------------------------------------------------
+  // core tables
+  // ------------------------------------------------------------------
+  ...Object.entries(ENTITIES).flatMap(([key, def]) => entityDdl(key, def)),
+  ...Object.entries(EDGES).flatMap(([key, def]) => edgeDdl(key, def)),
+
+  // ------------------------------------------------------------------
+  // knowledge timeline
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS knowledge_event SCHEMAFULL;`,
+  `DEFINE FIELD IF NOT EXISTS story ON knowledge_event TYPE record<story>;`,
+  `DEFINE FIELD IF NOT EXISTS chapter ON knowledge_event TYPE record<chapter>;`,
+  `DEFINE FIELD IF NOT EXISTS chapter_no ON knowledge_event TYPE int;`,
+  `DEFINE FIELD IF NOT EXISTS subject_type ON knowledge_event TYPE string ASSERT $value IN ['information','foreshadow'];`,
+  `DEFINE FIELD IF NOT EXISTS subject_id ON knowledge_event TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS character ON knowledge_event TYPE record<character>;`,
+  `DEFINE FIELD IF NOT EXISTS character_id ON knowledge_event TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS change ON knowledge_event TYPE string ASSERT $value IN ['learns','partially_learns','confirms','corrects','forgets','misinforms'];`,
+  `DEFINE FIELD IF NOT EXISTS coverage ON knowledge_event TYPE string ASSERT $value IN ['unknown','partial','full','false'];`,
+  `DEFINE FIELD IF NOT EXISTS knowledge ON knowledge_event TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS how ON knowledge_event TYPE string ASSERT $value IN ['witnessed','told','inferred','document','rumor','experience','other'];`,
+  `DEFINE FIELD IF NOT EXISTS source_character ON knowledge_event TYPE option<record<character>>;`,
+  `DEFINE FIELD IF NOT EXISTS scene ON knowledge_event TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS evidence ON knowledge_event TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS payload ON knowledge_event TYPE object FLEXIBLE;`,
+  `DEFINE FIELD IF NOT EXISTS created_at ON knowledge_event TYPE datetime VALUE time::now();`,
+
+  `DEFINE TABLE IF NOT EXISTS knowledge_state SCHEMAFULL;`,
+  `DEFINE FIELD IF NOT EXISTS story ON knowledge_state TYPE record<story>;`,
+  `DEFINE FIELD IF NOT EXISTS character ON knowledge_state TYPE record<character>;`,
+  `DEFINE FIELD IF NOT EXISTS subject_type ON knowledge_state TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS subject_id ON knowledge_state TYPE string;`,
+  `DEFINE FIELD IF NOT EXISTS state ON knowledge_state TYPE 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;`,
+
+  // ------------------------------------------------------------------
+  // metrics (time series)
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS chapter_metric SCHEMAFULL;`,
+  `DEFINE FIELD IF NOT EXISTS story ON chapter_metric TYPE record<story>;`,
+  `DEFINE FIELD IF NOT EXISTS chapter ON chapter_metric TYPE record<chapter>;`,
+  `DEFINE FIELD IF NOT EXISTS chapter_no ON chapter_metric TYPE int;`,
+  `DEFINE FIELD IF NOT EXISTS emotion_value ON chapter_metric TYPE option<int>;`,
+  `DEFINE FIELD IF NOT EXISTS hook_strength ON chapter_metric TYPE option<string>;`,
+  `DEFINE FIELD IF NOT EXISTS word_target ON chapter_metric TYPE int;`,
+  `DEFINE FIELD IF NOT EXISTS word_count ON chapter_metric TYPE option<int>;`,
+  `DEFINE INDEX IF NOT EXISTS chapter_metric_key ON chapter_metric FIELDS story, chapter_no UNIQUE;`,
+
+  // ------------------------------------------------------------------
+  // full-text index on prose
+  // ------------------------------------------------------------------
+  `DEFINE ANALYZER IF NOT EXISTS story_zh TOKENIZERS class FILTERS lowercase, ngram(1,2);`,
+
+  // ------------------------------------------------------------------
+  // hard rules / triggers
+  // ------------------------------------------------------------------
+  knowledgeRules(),
+  chapterGuard(),
+  ...completeGuards(),
+  foreshadowOrder(),
+  payoffOrder(),
+  ...fillEvents(),
+
+  // ------------------------------------------------------------------
+  // database-owned metadata and validation
+  // ------------------------------------------------------------------
+  `DEFINE TABLE IF NOT EXISTS fancy_meta SCHEMAFULL;`,
+  `DEFINE FIELD IF NOT EXISTS schema_version ON fancy_meta TYPE int;`,
+  `DEFINE FIELD IF NOT EXISTS validation_version ON fancy_meta TYPE int;`,
+  `DEFINE FIELD IF NOT EXISTS updated_at ON fancy_meta TYPE datetime VALUE time::now();`,
+  validationDdl(),
+  `DEFINE FUNCTION OVERWRITE fn::fancy::version() { RETURN { schema_version: ${Number(SCHEMA_VERSION)}, validation_version: ${Number(VALIDATION_VERSION)} }; };`,
+];
+
+const SPECIAL_CARDS = {
+  knowledge_event: `knowledge_event
+  chapter_id: string, 必填
+  chapter_no: int, 必填
+  subject_type: enum[information, foreshadow]
+  subject_id: string
+  character_id: string
+  change: enum[learns, partially_learns, confirms, corrects, forgets, misinforms]
+  coverage: enum[unknown, partial, full, false]
+  knowledge: string
+  how: enum[witnessed, told, inferred, document, rumor, experience, other]
+  source_character: string|null（how=told 必填）
+  scene: string
+  evidence: string
+  apply op: { "op": "knowledge", "data": { ... } }`,
+  chapter_metric: `chapter_metric
+  chapter_no: int
+  emotion_value: int 1-10
+  hook_strength: enum[强, 中, 弱]
+  word_target: int
+  word_count: int`,
+};
+
+export function schemaCard(table) {
+  if (SPECIAL_CARDS[table]) return SPECIAL_CARDS[table];
+  const def = ENTITIES[table] || EDGES[table];
+  if (!def) return null;
+  const isEdge = Boolean(EDGES[table]);
+  const lines = [];
+  lines.push(def.table + ' — ' + (def.label || def.table));
+  if (isEdge) {
+    lines.push('  edge: ' + def.in + ' -> ' + def.out);
+  }
+  if (!isEdge && !def.internal) {
+    const idKey = ['volume_id', 'act_id', 'line_id', 'node_id', 'ending_id', 'role_id', 'chapter_id']
+      .find((key) => def.fields && def.fields[key]);
+    if (['scale', 'world_doc', 'story_doc', 'emotion_doc'].includes(def.table)) {
+      lines.push('  id: 单例（不需要写 id）');
+    } else if (def.table === 'scene') {
+      lines.push('  id: 自动生成 SC_<outline_id>_<scene_order>');
+    } else if (idKey) {
+      lines.push('  id: string，create 时写 ' + idKey);
+    } else {
+      lines.push('  id: string，create 时写 data.id');
+    }
+  }
+  lines.push('  fields:');
+  for (const [name, field] of Object.entries(def.fields || {})) {
+    const type = field.type === 'enum' ? 'enum[' + field.values.join(', ') + ']' : field.type;
+    lines.push('    ' + name + ': ' + type + (field.required ? ', 必填' : ''));
+  }
+  if (!isEdge) {
+    const reqs = (def.requirements || []).map((r) => r.kind + (r.hard ? '(hard)' : '(soft)'));
+    if (reqs.length) lines.push('  requirements: ' + reqs.join(', '));
+    const edges = Object.values(EDGES).filter((e) => e.in === def.table || e.out === def.table);
+    if (edges.length) {
+      lines.push('  edges:');
+      for (const e of edges) {
+        lines.push('    ' + e.table + ': ' + e.in + ' -> ' + e.out);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+export function toolSchema(kind) {
+  const def = ENTITIES[kind];
+  if (!def) return null;
+  const properties = {};
+  const required = [];
+  for (const [name, field] of Object.entries(def.fields || {})) {
+    let schema;
+    switch (field.type) {
+      case 'int': schema = { type: 'integer' }; break;
+      case 'float': schema = { type: 'number' }; break;
+      case 'bool': schema = { type: 'boolean' }; break;
+      case 'array': schema = { type: 'array', items: {} }; break;
+      case 'object': schema = { type: 'object', additionalProperties: true }; break;
+      case 'enum': schema = { type: 'string', enum: field.values }; break;
+      case 'record': schema = { type: 'string' }; break;
+      default: schema = { type: 'string' };
+    }
+    if (field.required) required.push(name);
+    properties[name] = schema;
+  }
+  return { type: 'object', properties, required };
+}
+
+export function allSchemaCards() {
+  return Object.keys({ ...ENTITIES, ...EDGES }).map((table) => schemaCard(table)).filter(Boolean);
+}