local-knowledge-graph 1.5.0

package/lib/embeddings.js

@@ -0,0 +1,166 @@
+'use strict';
+
+// 向量混合检索：实体名称+属性文本 → embedding（默认硅基流动 BAAI/bge-m3），
+// 与关键词检索做 RRF 融合排序。配置存于 data/settings.json（gitignored，密钥不入库）。
+
+const fs = require('fs');
+const path = require('path');
+const vectors = require('./vectors');
+const db = require('./db');
+
+const { DATA_DIR } = require('./paths');
+const SETTINGS_PATH = path.join(DATA_DIR, 'settings.json');
+
+const DEFAULTS = {
+  provider: 'siliconflow',
+  base_url: 'https://api.siliconflow.cn/v1',
+  model: 'BAAI/bge-m3',
+  dim: 1024,
+  api_key: '',
+  rrf_k: 60,
+};
+
+function loadSettings() {
+  try { return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8')) }; }
+  catch (_) { return { ...DEFAULTS }; }
+}
+
+function saveSettings(patch) {
+  const merged = { ...loadSettings(), ...(patch || {}) };
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(merged, null, 2));
+  return merged;
+}
+
+function entityText(e) {
+  let attrs = '';
+  try {
+    const o = JSON.parse(e.attributes || '{}');
+    attrs = Object.entries(o).map(([k, v]) => `${k}:${v}`).join('；');
+  } catch (_) { /* 属性非法时忽略 */ }
+  return `${e.name}（${e.category}）${attrs ? ' ' + attrs : ''}`;
+}
+
+function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  const d = Math.sqrt(na) * Math.sqrt(nb);
+  return d === 0 ? 0 : dot / d;
+}
+
+async function embed(texts, settings) {
+  const s = settings || loadSettings();
+  if (!s.api_key) throw new Error('未配置embedding API key，请打开"检索"页签填写');
+  const url = s.base_url.replace(/\/+$/, '') + '/embeddings';
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${s.api_key}` },
+    body: JSON.stringify({ model: s.model, input: texts }),
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw new Error(`embedding接口错误 ${resp.status}: ${body.slice(0, 300)}`);
+  }
+  const data = await resp.json();
+  const vectors = data.data.map((d) => d.embedding);
+  if (vectors.length !== texts.length) throw new Error('embedding返回数量与请求不一致');
+  return vectors;
+}
+
+function status() {
+  const s = loadSettings();
+  return {
+    configured: Boolean(s.api_key),
+    provider: s.provider, model: s.model, dim: s.dim,
+    indexed: vectors.count(),
+    total_entities: db.listEntities().length,
+  };
+}
+
+// 构建全部实体向量（增量：仅未入库或文本变化的实体），并清理已删实体的孤儿向量
+async function build(progress) {
+  const s = loadSettings();
+  const ents = db.listEntities();
+  vectors.pruneOrphans(ents.map((e) => e.id));
+  const pending = ents.filter((e) => {
+    const row = vectors.get(e.id);
+    return !row || row.text !== entityText(e);
+  });
+  const done = ents.length - pending.length;
+  if (progress) progress(done, ents.length);
+  const BATCH = 32;
+  for (let i = 0; i < pending.length; i += BATCH) {
+    const chunk = pending.slice(i, i + BATCH);
+    const texts = chunk.map(entityText);
+    const vecs = await embed(texts, s);
+    chunk.forEach((e, k) => vectors.upsert(e.id, texts[k], vecs[k]));
+    if (progress) progress(done + Math.min(i + BATCH, pending.length), ents.length);
+  }
+  return { indexed: vectors.count(), total: ents.length };
+}
+
+// 关键词检索：名称包含/属性包含，粗略打分（命中名称权重高）
+function keywordSearch(graph, query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const terms = q.split(/\s+/);
+  const scored = [];
+  for (const e of graph.entities) {
+    let score = 0;
+    const name = e.name.toLowerCase();
+    for (const t of terms) {
+      if (name === t) score += 10;
+      else if (name.includes(t)) score += 5;
+      else if (entityText(e).toLowerCase().includes(t)) score += 1;
+    }
+    if (score > 0) scored.push({ id: e.id, score });
+  }
+  return scored;
+}
+
+// 混合检索：语义(余弦) + 关键词 RRF 融合，k=60
+async function search(query, topK) {
+  const s = loadSettings();
+  const k = Number(s.rrf_k) || 60;
+  const limit = Math.max(1, Math.min(Number(topK) || 10, 50));
+  const graph = db.getGraph();
+  const byId = new Map(graph.entities.map((e) => [e.id, e]));
+
+  const kw = keywordSearch(graph, query);
+
+  let sem = [];
+  if (s.api_key && vectors.count() > 0) {
+    const [qvec] = await embed([query], s);
+    sem = vectors.all()
+      .map((row) => ({ id: row.entity_id, score: cosine(qvec, Float32Array.from(row.vector)) }))
+      .filter((x) => x.score > 0.15);
+  }
+
+  const rrf = new Map();
+  const addRanking = (arr) => {
+    arr.sort((a, b) => b.score - a.score).slice(0, limit * 3).forEach((x, rank) => {
+      rrf.set(x.id, (rrf.get(x.id) || 0) + 1 / (k + rank + 1));
+    });
+  };
+  addRanking(kw);
+  if (sem.length) addRanking(sem);
+
+  const results = [...rrf.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([id, rrfScore]) => {
+      const e = byId.get(id);
+      const semRow = sem.find((x) => x.id === id);
+      const kwRow = kw.find((x) => x.id === id);
+      return {
+        entity: e,
+        rrf_score: Number(rrfScore.toFixed(5)),
+        semantic_score: semRow ? Number(semRow.score.toFixed(4)) : null,
+        keyword_score: kwRow ? kwRow.score : null,
+        hit_relations: graph.relations.filter((r) => r.source_id === id || r.target_id === id).length,
+      };
+    });
+  return { results, mode: s.api_key && vectors.count() > 0 ? 'hybrid' : 'keyword_only' };
+}
+
+module.exports = { loadSettings, saveSettings, status, build, search, embed, entityText };

package/lib/git.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { DATA_DIR } = require('./paths');
+const DB_FILE = 'kg.db';
+const DB_PATH = path.join(DATA_DIR, DB_FILE);
+const META_FILE = '.kg_meta.json'; // 记录最近一次保存点覆盖到的日志id（随版本一起入库，回滚后自动一致）
+
+function git(args, opts = {}) {
+  return execFileSync('git', args, {
+    cwd: DATA_DIR,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    env: gitEnv(opts),
+  });
+}
+
+// 读取二进制对象（如SQLite文件）必须用Buffer，避免UTF-8转换损坏数据
+function gitBuffer(args) {
+  return execFileSync('git', args, {
+    cwd: DATA_DIR,
+    encoding: 'buffer',
+    maxBuffer: 256 * 1024 * 1024,
+    env: gitEnv({}),
+  });
+}
+
+function gitEnv(opts) {
+  return {
+    ...process.env,
+    GIT_AUTHOR_NAME: opts.name || 'KG-Local', GIT_AUTHOR_EMAIL: 'kg@localhost',
+    GIT_COMMITTER_NAME: opts.name || 'KG-Local', GIT_COMMITTER_EMAIL: 'kg@localhost',
+  };
+}
+
+function ensureRepo() {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  if (!fs.existsSync(path.join(DATA_DIR, '.git'))) {
+    git(['init', '-b', 'main']);
+  }
+  git(['config', 'user.name', 'KG-Local']);
+  git(['config', 'user.email', 'kg@localhost']);
+}
+
+function hasCommits() {
+  try { git(['rev-parse', '--verify', 'HEAD']); return true; } catch (_) { return false; }
+}
+
+function readMeta() {
+  try { return JSON.parse(fs.readFileSync(path.join(DATA_DIR, META_FILE), 'utf8')); } catch (_) { return { last_saved_log: 0 }; }
+}
+
+function writeMeta(meta) {
+  fs.writeFileSync(path.join(DATA_DIR, META_FILE), JSON.stringify(meta, null, 2));
+}
+
+// 打保存点：提交当前合规数据。git仅存差异对象，不冗余占用空间。
+// 提交信息内嵌日志id区间，实现操作日志与Git提交记录双向绑定。
+function savepoint(title, source = '系统') {
+  ensureRepo();
+  const meta = readMeta();
+  const currentMax = dbMaxLogId();
+  const from = meta.last_saved_log + 1;
+  const to = currentMax;
+  const finalTitle = (title && String(title).trim()) || `保存点 ${new Date().toLocaleString('zh-CN')}`;
+  // 无新增日志但库字节变化（如schema迁移/资产变更）时 from>to，区间收敛到最近日志
+  const rangeFrom = Math.min(from, to);
+  const msg = `${finalTitle}｜来源:${source}｜日志ID:${rangeFrom}-${to}`;
+
+  git(['add', '-A', '--', DB_FILE]);
+  const staged = git(['diff', '--cached', '--name-only']);
+  if (!staged.trim()) return { committed: false, message: '当前数据与最近保存点一致，无差异需要提交' };
+  // 元数据与数据在同一个提交内，回滚后自动一致
+  writeMeta({ last_saved_log: to });
+  git(['add', '-A', '--', META_FILE]);
+  git(['commit', '-m', msg]);
+  const hash = git(['rev-parse', '--short', 'HEAD']).trim();
+  backupCopy();
+  return { committed: true, hash, message: msg, log_range: [rangeFrom, to] };
+}
+
+// data/backups/ 自动滚动副本：距上次备份超过10分钟才复制，保留最近10份（目录损坏时仍有外部副本可救）
+const BACKUP_KEEP = 10;
+const BACKUP_MIN_INTERVAL_MS = 10 * 60 * 1000;
+let lastBackupAt = 0;
+
+function backupCopy(force = false) {
+  const backupDir = path.join(DATA_DIR, 'backups');
+  try {
+    const now = Date.now();
+    if (!force && now - lastBackupAt < BACKUP_MIN_INTERVAL_MS) return null;
+    fs.mkdirSync(backupDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19);
+    fs.copyFileSync(DB_PATH, path.join(backupDir, `kg-${stamp}.db`));
+    lastBackupAt = now;
+    const files = fs.readdirSync(backupDir).filter((f) => /^kg-.*\.db$/.test(f)).sort();
+    for (const f of files.slice(0, Math.max(0, files.length - BACKUP_KEEP))) {
+      try { fs.unlinkSync(path.join(backupDir, f)); } catch (_) { /* 单个旧副本清理失败可容忍 */ }
+    }
+    return path.join(backupDir, `kg-${stamp}.db`);
+  } catch (_) { return null; }
+}
+
+function dbMaxLogId() {
+  try {
+    const database = require('./db');
+    return database.maxLogId();
+  } catch (_) { return readMeta().last_saved_log; }
+}
+
+// 提交历史（含日志绑定信息）
+function history(limit = 100) {
+  ensureRepo();
+  if (!hasCommits()) return [];
+  const raw = git(['log', '-n', String(limit), '--date=iso-local', '--pretty=format:%H%x01%h%x01%aI%x01%s%x01%an']).trim();
+  if (!raw) return [];
+  return raw.split('\n').map((line) => {
+    const [hash, short, date, subject, author] = line.split('\x01');
+    let title = subject, logRange = null, src = '';
+    const m = subject.match(/^(.*)｜来源:(.*)｜日志ID:(\d+)-(\d+)$/);
+    if (m) { title = m[1]; src = m[2]; logRange = [Number(m[3]), Number(m[4])]; }
+    return { hash, short, date, author, title, source: src, log_range: logRange };
+  });
+}
+
+// 回溯：切到任意保存点。先自动备份当前状态，再恢复目标版本并校验完整性。
+function restore(hash) {
+  ensureRepo();
+  if (!hasCommits()) { const e = new Error('仓库中还没有任何保存点'); e.status = 400; throw e; }
+  try { git(['cat-file', '-e', `${hash}^{commit}`]); } catch (_) {
+    const e = new Error(`保存点 ${hash} 不存在`); e.status = 404; throw e;
+  }
+  let backup = null;
+  try { backup = savepoint(`回滚前自动备份 ${new Date().toLocaleString('zh-CN')}`, '系统'); } catch (_) { backup = null; }
+
+  // 先在临时文件上校验目标版本完整性，通过后才替换主库，确保任何情况下不损坏现有数据
+  const target = gitBuffer(['show', `${hash}:${DB_FILE}`]);
+  const tmp = path.join(os.tmpdir(), `kg_restore_${Date.now()}.db`);
+  fs.writeFileSync(tmp, target);
+  const { DatabaseSync } = require('node:sqlite');
+  let probe;
+  try {
+    probe = new DatabaseSync(tmp);
+    const r = probe.prepare('PRAGMA integrity_check').get();
+    const v = Object.values(r)[0];
+    if (v !== 'ok') { const e = new Error(`目标保存点数据异常: ${v}`); e.status = 500; throw e; }
+  } finally {
+    try { if (probe) probe.close(); } catch (_) {}
+  }
+  fs.copyFileSync(tmp, path.join(DATA_DIR, DB_FILE));
+  fs.unlinkSync(tmp);
+  // 同步恢复日志绑定元数据，保证保存点区间与日志双向绑定始终一致
+  try {
+    const metaBuf = gitBuffer(['show', `${hash}:${META_FILE}`]);
+    fs.writeFileSync(path.join(DATA_DIR, META_FILE), metaBuf);
+  } catch (_) {
+    writeMeta({ last_saved_log: 0 });
+  }
+  const database = require('./db');
+  database.reopen();
+  const check = database.integrityCheck();
+  if (!check.ok) {
+    const e = new Error('恢复后的数据库完整性校验失败: ' + check.detail);
+    e.status = 500; throw e;
+  }
+  // 记录回溯操作（source=系统），保证日志与版本可互溯
+  const counts = database.counts();
+  return { restored: hash, backup: backup && backup.hash ? backup.hash : null, counts };
+}
+
+module.exports = { ensureRepo, savepoint, history, restore, readMeta, writeMeta, backupCopy, DATA_DIR };

package/lib/importer.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// 整库导入校验：SQLite魔数 → 完整性 → 必需表 → 必需列 → 计数与日志水位。
+// 独立成模块便于单元测试（构造任意残缺库验证拦截）。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const REQUIRED_TABLES = ['entities', 'relations', 'operation_logs'];
+const REQUIRED_COLS = {
+  entities: ['id', 'name', 'category', 'attributes', 'source', 'created_at'],
+  relations: ['id', 'source_id', 'target_id', 'name', 'category', 'source', 'created_at'],
+  operation_logs: ['id', 'op_type', 'snapshot', 'source', 'created_at'],
+};
+
+function validateImportBuffer(buf) {
+  if (!buf || !buf.length) return { ok: false, error: '文件为空' };
+  if (buf.length > 200 * 1024 * 1024) return { ok: false, error: '文件超过200MB上限' };
+  if (!/^SQLite format 3\x00/.test(buf.toString('latin1', 0, 16))) return { ok: false, error: '该文件不是SQLite数据库' };
+
+  const tmp = path.join(os.tmpdir(), `kg_import_probe_${Date.now()}_${Math.random().toString(36).slice(2)}.db`);
+  fs.writeFileSync(tmp, buf);
+  const { DatabaseSync } = require('node:sqlite');
+  let probe;
+  try {
+    probe = new DatabaseSync(tmp);
+    const v = Object.values(probe.prepare('PRAGMA integrity_check').get())[0];
+    if (v !== 'ok') return { ok: false, error: `数据库完整性校验失败: ${v}` };
+    const tables = probe.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((r) => r.name);
+    for (const t of REQUIRED_TABLES) {
+      if (!tables.includes(t)) return { ok: false, error: `缺少必需的数据表 ${t}，这不是本系统的图谱文件` };
+    }
+    for (const [t, cols] of Object.entries(REQUIRED_COLS)) {
+      const actual = probe.prepare(`PRAGMA table_info(${t})`).all().map((c) => c.name);
+      const missing = cols.filter((c) => !actual.includes(c));
+      if (missing.length) return { ok: false, error: `表 ${t} 缺少必需字段: ${missing.join(', ')}` };
+    }
+    const importedMaxLog = probe.prepare('SELECT COALESCE(MAX(id),0) AS m FROM operation_logs').get().m;
+    const counts = {
+      entities: probe.prepare('SELECT COUNT(*) AS c FROM entities').get().c,
+      relations: probe.prepare('SELECT COUNT(*) AS c FROM relations').get().c,
+      logs: probe.prepare('SELECT COUNT(*) AS c FROM operation_logs').get().c,
+    };
+    return { ok: true, importedMaxLog, counts };
+  } catch (e) {
+    return { ok: false, error: '数据库读取失败: ' + e.message };
+  } finally {
+    try { if (probe) probe.close(); } catch (_) { /* 已关闭 */ }
+    try { fs.unlinkSync(tmp); } catch (_) { /* 临时探针文件清理失败可容忍 */ }
+  }
+}
+
+module.exports = { validateImportBuffer, REQUIRED_TABLES, REQUIRED_COLS };

package/lib/inference.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// OWL式推理引擎：基于本体属性特征（传递/对称/逆）从显式关系推导隐性关系。
+// 推理结果为虚拟三元组（不入库），附带推导规则与关系id路径，供前端展示与API查询。
+
+const fs = require('fs');
+const path = require('path');
+
+const DATA_DIR = path.join(__dirname, '..', 'data');
+const ONTOLOGY_PATH = path.join(DATA_DIR, 'ontology.json');
+
+const DEFAULT_ONTOLOGY = {
+  transitive: ['位于', '在', '包含', '包括', '属于', '下辖于', '隶属于', '统治', '管辖', '发源于', '流入'],
+  symmetric: ['挚友', '夫妻', '同学', '同事', '结为兄弟', '相邻', '同义词'],
+  inverse: [['父子', '子父'], ['包含', '属于'], ['创建', '创建者'], ['师从', '学生为']],
+};
+
+function loadOntology() {
+  try {
+    const o = JSON.parse(fs.readFileSync(ONTOLOGY_PATH, 'utf8'));
+    return normalizeOntology(o);
+  } catch (_) {
+    return normalizeOntology(DEFAULT_ONTOLOGY);
+  }
+}
+
+function normalizeOntology(o) {
+  const out = { transitive: [], symmetric: [], inverse: [] };
+  if (o && typeof o === 'object') {
+    if (Array.isArray(o.transitive)) out.transitive = o.transitive.filter((x) => typeof x === 'string' && x.trim()).map((x) => x.trim());
+    if (Array.isArray(o.symmetric)) out.symmetric = o.symmetric.filter((x) => typeof x === 'string' && x.trim()).map((x) => x.trim());
+    if (Array.isArray(o.inverse)) {
+      out.inverse = o.inverse
+        .filter((p) => Array.isArray(p) && p.length === 2 && p.every((x) => typeof x === 'string' && x.trim()))
+        .map((p) => [p[0].trim(), p[1].trim()]);
+    }
+  }
+  return out;
+}
+
+function saveOntology(o) {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.writeFileSync(ONTOLOGY_PATH, JSON.stringify(normalizeOntology(o), null, 2));
+  return loadOntology();
+}
+
+// 推理主入口：graph = {entities, relations}
+function computeInferred(graph, ontology) {
+  const ont = ontology || loadOntology();
+  const inferred = [];
+  const seen = new Set();
+  const explicitKeys = new Set(graph.relations.map((r) => `${r.source_id}|${r.target_id}|${r.name}`));
+
+  // R1 传递性(TransitiveProperty): A -n-> B, B -n-> C ⇒ A -n-> C（闭包，路径取最短）
+  for (const name of ont.transitive) {
+    const rels = graph.relations.filter((r) => r.name === name);
+    if (!rels.length) continue;
+    const adj = new Map();
+    for (const r of rels) {
+      if (!adj.has(r.source_id)) adj.set(r.source_id, []);
+      adj.get(r.source_id).push(r);
+    }
+    for (const [start, outEdges] of adj) {
+      const reached = new Map(); // nodeId -> path(rel[])
+      const queue = [];
+      for (const e of outEdges) queue.push({ node: e.target_id, path: [e] });
+      while (queue.length) {
+        const { node, path } = queue.shift();
+        if (reached.has(node) || node === start) continue;
+        reached.set(node, path);
+        for (const e of adj.get(node) || []) {
+          if (!reached.has(e.target_id)) queue.push({ node: e.target_id, path: [...path, e] });
+        }
+      }
+      for (const [node, path] of reached) {
+        const key = `${start}|${node}|${name}`;
+        if (explicitKeys.has(key)) continue;
+        seen.add(key);
+        inferred.push({
+          source_id: start, target_id: node, name,
+          category: path[0].category,
+          rule: `传递性(${name})`,
+          via: path.map((e) => e.id),
+        });
+      }
+    }
+  }
+
+  // R2 对称性(SymmetricProperty): A -n-> B ⇒ B -n-> A
+  for (const name of ont.symmetric) {
+    for (const r of graph.relations.filter((x) => x.name === name)) {
+      if (r.source_id === r.target_id) continue;
+      const key = `${r.target_id}|${r.source_id}|${r.name}`;
+      if (explicitKeys.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      inferred.push({
+        source_id: r.target_id, target_id: r.source_id, name: r.name,
+        category: r.category,
+        rule: `对称性(${r.name})`,
+        via: [r.id],
+      });
+    }
+  }
+
+  // R3 逆关系(inverseOf): A -p-> B ⇒ B -q-> A（p,q为逆对）
+  for (const [p, q] of ont.inverse) {
+    for (const r of graph.relations.filter((x) => x.name === p)) {
+      const key = `${r.target_id}|${r.source_id}|${q}`;
+      if (explicitKeys.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      inferred.push({
+        source_id: r.target_id, target_id: r.source_id, name: q,
+        category: r.category,
+        rule: `逆关系(${p} ↔ ${q})`,
+        via: [r.id],
+      });
+    }
+  }
+
+  return inferred;
+}
+
+module.exports = { loadOntology, saveOntology, computeInferred };

package/lib/paths.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// 数据目录统一解析：环境变量 > 开发仓库(./data) > npm安装(~/.local-knowledge-graph)
+// 全部数据（kg.db/vectors.db/settings.json/uploads/backups/保存点git仓库）都收敛在数据目录内，
+// npm 升级只替换程序文件，数据天然不受影响。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const APP_ROOT = path.join(__dirname, '..');
+const PKG_NAME = 'local-knowledge-graph';
+
+function isDevRepo(root = APP_ROOT) {
+  return fs.existsSync(path.join(root, '.git'));
+}
+
+function resolveDataDir(opts = {}) {
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+  const root = opts.root || APP_ROOT;
+  if (env.KG_DATA_DIR) return env.KG_DATA_DIR;
+  if (isDevRepo(root)) return path.join(root, 'data');
+  return path.join(home, '.local-knowledge-graph');
+}
+
+const DATA_DIR = resolveDataDir();
+const DB_PATH = process.env.KG_DB_PATH || path.join(DATA_DIR, 'kg.db');
+
+// npm 安装模式下，若包目录残留旧版数据（1.4.x 及之前存放在程序目录 data/），自动迁移到数据目录
+function ensureLegacyMigration(log = console.log) {
+  if (process.env.KG_DATA_DIR || process.env.KG_DB_PATH) return;
+  if (isDevRepo()) return;
+  const legacy = path.join(APP_ROOT, 'data');
+  if (!fs.existsSync(path.join(legacy, 'kg.db'))) return;
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  const files = ['kg.db', 'vectors.db', 'settings.json', '.kg_meta.json', '.agent_session'];
+  for (const f of files) {
+    const src = path.join(legacy, f);
+    const dst = path.join(DATA_DIR, f);
+    if (fs.existsSync(src) && !fs.existsSync(dst)) fs.copyFileSync(src, dst);
+  }
+  for (const dir of ['uploads', 'backups']) {
+    const src = path.join(legacy, dir);
+    const dst = path.join(DATA_DIR, dir);
+    if (fs.existsSync(src) && !fs.existsSync(dst)) {
+      fs.cpSync(src, dst, { recursive: true });
+    }
+  }
+  log(`[迁移] 检测到程序目录内的旧数据，已复制到 ${DATA_DIR}（原 data/ 目录保留未动）`);
+}
+
+module.exports = { APP_ROOT, DATA_DIR, DB_PATH, PKG_NAME, isDevRepo, resolveDataDir, ensureLegacyMigration };

package/lib/rdf.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// 标准RDF(Turtle)导出：所有字段严格映射为三元组，禁止冗余结构
+const { RDF_TYPE_MAP, RDF_RELATION_TYPE_MAP } = require('./validator');
+
+const HEADER = `@prefix kg: <http://monkeycode.local/kg/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+`;
+
+function esc(s) {
+  return String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}
+
+function lit(v) {
+  if (typeof v === 'number') return Number.isInteger(v) ? `"${v}"^^xsd:integer` : `"${v}"^^xsd:decimal`;
+  if (typeof v === 'boolean') return `"${v}"^^xsd:boolean`;
+  if (v === null || v === undefined) return `""^^rdf:nil`;
+  return `"${esc(v)}"`;
+}
+
+function exportTurtle(graph) {
+  const parts = [HEADER];
+
+  for (const e of graph.entities) {
+    const cls = RDF_TYPE_MAP[e.category] || 'Entity';
+    const lines = [];
+    lines.push(`kg:e${e.id} rdf:type kg:${cls} ;`);
+    lines.push(`    rdfs:label "${esc(e.name)}"@zh ;`);
+    lines.push(`    kg:category "${esc(e.category)}" ;`);
+    lines.push(`    kg:createdAt "${esc(e.created_at)}"^^xsd:dateTime ;`);
+    lines.push(`    kg:source "${esc(e.source)}"`);
+    let attrs = {};
+    try { attrs = JSON.parse(e.attributes || '{}'); } catch (_) { attrs = {}; }
+    const chunks = [];
+    for (const [k, v] of Object.entries(attrs)) {
+      chunks.push(`    kg:attribute [ kg:key ${lit(k)} ; kg:value ${lit(v)} ]`);
+    }
+    parts.push(chunks.length ? lines.join('\n') + ' ;\n' + chunks.join(' ;\n') + ' .\n' : lines.join('\n') + ' .\n');
+  }
+
+  for (const r of graph.relations) {
+    const cls = RDF_RELATION_TYPE_MAP[r.category] || 'Relation';
+    parts.push(
+      `kg:r${r.id} rdf:type kg:${cls} ;\n` +
+      `    rdfs:label "${esc(r.name)}"@zh ;\n` +
+      `    kg:category "${esc(r.category)}" ;\n` +
+      `    kg:subject kg:e${r.source_id} ;\n` +
+      `    kg:object kg:e${r.target_id} ;\n` +
+      `    kg:createdAt "${esc(r.created_at)}"^^xsd:dateTime ;\n` +
+      `    kg:source "${esc(r.source)}" .\n`
+    );
+  }
+
+  return parts.join('\n');
+}
+
+module.exports = { exportTurtle };