local-knowledge-graph 1.6.1 → 1.8.0

package/HELP.md

@@ -65,6 +65,16 @@ kg
 - **OpenCode（AI 对话建图 / 智能提问编译）**：使用 opencode CLI 自身的认证（`opencode auth login`），应用不经手密钥。未安装或未认证时仅这两个功能降级。
 - 更换数据目录（`kg --data <目录>`）会使用该目录下的独立配置，互不串扰。
 
+## MCP 外部接入（外部 Agent 读写图谱）
+
+在 **MCP 页签** 开启"MCP 服务"后，外部 Agent（Claude Desktop、Cursor、Cline、opencode 等）即可通过标准 MCP 协议对本图谱做完整增删改查：
+
+- **HTTP 方式（推荐，支持远程 Agent）**：端点 `http://<主机>:3000/mcp`（Streamable HTTP，JSON 响应），启用后自动生成访问令牌，支持 `Authorization: Bearer` 头或 `?token=` 参数；界面提供三类客户端配置片段一键复制
+- **本机 stdio 方式（免令牌）**：客户端配置命令 `npx -y local-knowledge-graph --mcp`（或 `kg --mcp`）；数据目录默认 `~/.local-knowledge-graph`，可用 `KG_DATA_DIR` 环境变量指定
+- **工具集（12 个）**：查询类 kg_stats / kg_list_entities / kg_get_entity / kg_get_graph / kg_ego / kg_search / kg_cypher / kg_inference / kg_path / kg_digest / kg_export_rdf；写入类 kg_apply_ops（add/update/delete entity 与 relation，自动记操作日志 + Git 保存点）
+- **只读模式**：勾选后外部仅可查询；**令牌管理**：一键重新生成即刻吊销旧令牌
+- **实时同步**：图谱被任一写入方（页面、API、MCP、外部进程）修改后，网页 3 秒内自动刷新
+
 ## 功能速览
 
 - **AI 对话建图**：右侧输入自然语言指令（联网补全），或上传文档（md/txt/pdf/docx）批量抽取三元组
@@ -105,6 +115,8 @@ kg
 
 ## 版本历史摘要
 
+- **v1.8.0**：MCP 外部接入——设置新增 MCP 页签（服务开关/只读模式/令牌管理/三类客户端一键复制配置）；`/mcp` Streamable HTTP 端点（令牌鉴权+CORS，12 个工具含完整 CRUD）；`kg --mcp` 本机 stdio 接入；图谱变更实时同步（SSE 推送+跨进程探测，页面 3 秒内自动刷新）
+- **v1.7.0**：六项图谱能力升级——①实体别名（增删/全局唯一/搜索与消歧联动）②同名冲突检测（创建即提示，可合并可强制）③多路径查找（2-6跳，图上高亮，MCP kg_path）④相似实体推荐（语义+结构双模式）⑤关系置信度三档（确证/推测/存疑，样式区分可过滤）与来源引用标注 ⑥智能问答附证据路径链 ⑦文档批量入图（md/txt/pdf→LLM抽取→审核勾选→来源标记入库，支持跳过审核）
 - **v1.6.1**：修复浅色主题切换导致画布空白的问题；标题栏按钮防挤压（窄屏可横滑）；修复3D样式主题刷新后不恢复的问题；新增脚本异常提示
 - **v1.6.0**：界面主题新增浅色配色（视图设置一键切换，本地记忆）；GitHub 仓库与 npm 包通过 Actions 自动同步（打 tag 即测试+发布+Release）
 

package/bin/cli.js

@@ -23,6 +23,7 @@ if (args.includes('-h') || args.includes('--help')) {
   --port <n>      服务端口（默认 3000，环境变量 PORT 同效）
   --host <addr>   监听地址（默认 127.0.0.1，局域网访问用 0.0.0.0，环境变量 KG_HOST 同效）
   --data <dir>    数据目录（默认 ~/.local-knowledge-graph，环境变量 KG_DATA_DIR 同效）
+  --mcp           以 MCP stdio 服务运行（供 Claude Desktop/Cursor 等客户端接入，不启动网页）
   --no-open       启动后不自动打开浏览器
   -v, --version   显示版本
   -h, --help      显示本帮助
@@ -36,6 +37,13 @@ if (args.includes('-v') || args.includes('--version')) {
   process.exit(0);
 }
 
+if (args.includes('--mcp')) {
+  // stdio MCP：数据目录仍由 KG_DATA_DIR / --data 决定
+  const d = argValue('--data');
+  if (d) process.env.KG_DATA_DIR = d;
+  require('../mcp/server.js');
+} else {
+
 const { ensureLegacyMigration, isDevRepo } = require('../lib/paths');
 
 const port = argValue('--port');
@@ -84,3 +92,4 @@ require('../server.js');
 if (isDevRepo()) {
   console.log('[开发模式] 检测到Git仓库，数据目录使用项目内 ./data');
 }
+}

package/lib/agent.js

@@ -138,7 +138,7 @@ async function runAgent(instruction, files = []) {
 
 // 底层进程调用：拉起 opencode run --format json，收集事件流（attempt与runPlain共用）
 // preArgs: 位于prompt之前的参数（如 --session）；prompt必须在-f之前（-f是贪婪数组选项）
-function runOpenCodeRaw(preArgs, prompt, files, timeoutMs) {
+function runOpenCodeRaw(preArgs, prompt, files, timeoutMs, envExtra) {
   return new Promise((resolve) => {
     const args = ['run', '--format', 'json', '--auto', ...preArgs, prompt];
     for (const f of files || []) {
@@ -148,7 +148,7 @@ function runOpenCodeRaw(preArgs, prompt, files, timeoutMs) {
     let stdout = '', stderr = '', done = false;
     let child;
     try {
-      child = spawn('opencode', args, { cwd: APP_ROOT, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+      child = spawn('opencode', args, { cwd: APP_ROOT, env: { ...process.env, ...(envExtra || {}) }, stdio: ['ignore', 'pipe', 'pipe'] });
     } catch (e) {
       return resolve({ ok: false, error: '无法启动OpenCode进程: ' + e.message });
     }
@@ -196,10 +196,10 @@ function attempt(sessionId, instruction, files) {
 }
 
 // 纯文本问答模式（智能检索编译/综述用）：无会话、无 kg-ops 解析，仅取回复文本
-async function runPlain(prompt, timeoutMs = 20000) {
+async function runPlain(prompt, timeoutMs = 20000, envExtra) {
   const p = String(prompt || '').trim();
   if (!p) return { ok: false, error: 'prompt不能为空' };
-  const r = await runOpenCodeRaw([], p, [], timeoutMs);
+  const r = await runOpenCodeRaw([], p, [], timeoutMs, envExtra);
   if (!r.ok) return { ok: false, error: r.error };
   return { ok: true, text: r.texts || '' };
 }

package/lib/ask.js

@@ -241,6 +241,63 @@ function scanByName(question, cap = 10) {
   return { entities: hits, relations };
 }
 
+// ---------- 证据路径归纳：在被提及实体的诱导子图内枚举1-3跳路径（确定性，无LLM） ----------
+function buildEvidencePaths(entities, relations, synthesisText, cap = 6) {
+  if (!entities.length || !relations.length) return [];
+  let seeds = entities;
+  if (synthesisText) {
+    const hits = entities.filter((e) => e.name && synthesisText.includes(e.name));
+    if (hits.length >= 2) seeds = hits; // 综述提及<2个实体时退回全部上下文实体
+  }
+  if (seeds.length < 2) return [];
+  const idSet = new Set(seeds.map((e) => e.id));
+  const ind = relations.filter((r) => idSet.has(r.source_id) && idSet.has(r.target_id));
+  if (!ind.length) return [];
+
+  const paths = [];
+  const seen = new Set();
+  for (const r of ind) { // 1跳
+    if (seen.has(r.id)) continue;
+    seen.add(r.id);
+    paths.push({ hops: [r] });
+    if (paths.length >= cap) return paths.slice(0, cap);
+  }
+  const adj = new Map();
+  for (const r of ind) {
+    if (!adj.has(r.source_id)) adj.set(r.source_id, []);
+    if (!adj.has(r.target_id)) adj.set(r.target_id, []);
+    adj.get(r.source_id).push(r);
+    adj.get(r.target_id).push(r);
+  }
+  for (const startId of idSet) { // 2-3跳：每个种子出发BFS，按关系id集合去重
+    let frontier = [{ id: startId, rels: [], visited: new Set([startId]) }];
+    for (let d = 0; d < 3 && paths.length < cap; d++) {
+      const next = [];
+      for (const node of frontier) {
+        for (const r of adj.get(node.id) || []) {
+          const other = r.source_id === node.id ? r.target_id : r.source_id;
+          if (node.visited.has(other)) continue;
+          const rels = [...node.rels, r];
+          const key = rels.map((x) => x.id).sort((a, b) => a - b).join('-');
+          if (d >= 1 && !seen.has(key)) {
+            seen.add(key);
+            paths.push({ hops: rels });
+            if (paths.length >= cap) break;
+          }
+          const visited = new Set(node.visited);
+          visited.add(other);
+          next.push({ id: other, rels, visited });
+        }
+        if (paths.length >= cap) break;
+      }
+      if (paths.length >= cap) break;
+      frontier = next;
+    }
+    if (paths.length >= cap) break;
+  }
+  return paths.slice(0, cap).map((p) => ({ hops: p.hops }));
+}
+
 // ---------- 编排入口 ----------
 async function ask(question, opts = {}) {
   const q = String(question || '').trim();
@@ -284,7 +341,8 @@ async function ask(question, opts = {}) {
     if (s.error) result.synth_error = s.error;
     result.timings.total_ms = Date.now() - t0;
   }
+  result.evidence_paths = buildEvidencePaths(merged.entities, merged.relations, result.synthesis || null);
   return result;
 }
 
-module.exports = { buildDigest, validatePlan, compilePlan, executePlan, findCoNeighbors, synthesize, ask, extractJson, clampCypher };
+module.exports = { buildDigest, validatePlan, compilePlan, executePlan, findCoNeighbors, synthesize, ask, extractJson, clampCypher, buildEvidencePaths };

package/lib/bus.js

@@ -0,0 +1,18 @@
+'use strict';
+
+// 极简进程内事件总线：图谱变更通知（SSE 推送用）
+
+const listeners = new Set();
+
+function on(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+function emit(type, payload) {
+  for (const fn of listeners) {
+    try { fn(type, payload); } catch (_) { /* 单监听器异常不影响其余 */ }
+  }
+}
+
+module.exports = { on, emit, count: () => listeners.size };

package/lib/db.js

@@ -40,7 +40,7 @@ function initSchema() {
       category TEXT NOT NULL CHECK(category IN ('物理实体','抽象实体','数值实体','时间实体')),
       attributes TEXT NOT NULL DEFAULT '{}',
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode'))
+      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','文档'))
     );
     CREATE TABLE IF NOT EXISTS relations (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -48,15 +48,17 @@ function initSchema() {
       target_id INTEGER NOT NULL,
       name TEXT NOT NULL,
       category TEXT NOT NULL CHECK(category IN ('空间','互动','归属','时间','属性')),
+      confidence TEXT NOT NULL DEFAULT '确证' CHECK(confidence IN ('确证','推测','存疑')),
+      source_ref TEXT NOT NULL DEFAULT '',
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode'))
+      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','文档'))
     );
     CREATE TABLE IF NOT EXISTS operation_logs (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       op_type TEXT NOT NULL,
       snapshot TEXT NOT NULL,
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','系统'))
+      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','系统','文档'))
     );
     CREATE INDEX IF NOT EXISTS idx_rel_source ON relations(source_id);
     CREATE INDEX IF NOT EXISTS idx_rel_target ON relations(target_id);
@@ -69,7 +71,15 @@ function initSchema() {
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
     );
     CREATE INDEX IF NOT EXISTS idx_img_entity ON entity_images(entity_id);
+    CREATE TABLE IF NOT EXISTS aliases (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      entity_id INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+      alias TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_alias_entity ON aliases(entity_id);
   `);
+  migrateEvidence();
   // 旧库迁移：entity_embeddings 已拆分至独立 vectors.db，主库内残留表直接清除
   const allTables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((c) => c.name);
   if (allTables.includes('entity_embeddings')) {
@@ -82,6 +92,74 @@ function initSchema() {
   }
 }
 
+// ---- 证据链迁移（幂等）：旧库补 relations.confidence/source_ref 列，source 枚举扩展"文档" ----
+function tableSql(name) {
+  const row = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name = ?").get(name);
+  return row ? row.sql : '';
+}
+
+function rebuildTableWithEnum(table, createSql, copyCols) {
+  db.exec('PRAGMA foreign_keys = OFF');
+  db.exec(`DROP TABLE IF EXISTS ${table}__rebuild`);
+  db.exec(createSql);
+  db.exec(`INSERT INTO ${table}__rebuild (${copyCols.join(',')}) SELECT ${copyCols.join(',')} FROM ${table}`);
+  db.exec(`DROP TABLE ${table}`);
+  db.exec(`ALTER TABLE ${table}__rebuild RENAME TO ${table}`);
+  if (table === 'relations') {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_rel_source ON relations(source_id)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_rel_target ON relations(target_id)');
+  }
+  db.exec('PRAGMA foreign_keys = ON');
+}
+
+function migrateEvidence() {
+  // 1) relations 补 confidence / source_ref 列（CREATE TABLE 已含新列的全新库会直接跳过）
+  const relCols = db.prepare('PRAGMA table_info(relations)').all().map((c) => c.name);
+  if (relCols.length && !relCols.includes('confidence')) {
+    db.exec("ALTER TABLE relations ADD COLUMN confidence TEXT NOT NULL DEFAULT '确证'");
+  }
+  if (relCols.length && !relCols.includes('source_ref')) {
+    db.exec("ALTER TABLE relations ADD COLUMN source_ref TEXT NOT NULL DEFAULT ''");
+  }
+  // 2) source 枚举扩展"文档"：检测建表语句，缺失则整表重建
+  const ENTITIES_NEW = `CREATE TABLE entities__rebuild (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      category TEXT NOT NULL CHECK(category IN ('物理实体','抽象实体','数值实体','时间实体')),
+      attributes TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','文档'))
+    )`;
+  const RELATIONS_NEW = `CREATE TABLE relations__rebuild (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_id INTEGER NOT NULL,
+      target_id INTEGER NOT NULL,
+      name TEXT NOT NULL,
+      category TEXT NOT NULL CHECK(category IN ('空间','互动','归属','时间','属性')),
+      confidence TEXT NOT NULL DEFAULT '确证' CHECK(confidence IN ('确证','推测','存疑')),
+      source_ref TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','文档'))
+    )`;
+  if (!tableSql('entities').includes("'文档'")) {
+    rebuildTableWithEnum('entities', ENTITIES_NEW, ['id', 'name', 'category', 'attributes', 'created_at', 'source']);
+  }
+  if (!tableSql('relations').includes("'文档'")) {
+    rebuildTableWithEnum('relations', RELATIONS_NEW, ['id', 'source_id', 'target_id', 'name', 'category', 'confidence', 'source_ref', 'created_at', 'source']);
+  }
+  if (!tableSql('operation_logs').includes("'文档'")) {
+    const LOGS_NEW = `CREATE TABLE operation_logs__rebuild (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      op_type TEXT NOT NULL,
+      snapshot TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+      source TEXT NOT NULL CHECK(source IN ('手工','OpenCode','系统','文档'))
+    )`;
+    rebuildTableWithEnum('operation_logs', LOGS_NEW, ['id', 'op_type', 'snapshot', 'created_at', 'source']);
+    bumpVersion();
+  }
+}
+
 function tx(fn) {
   db.exec('BEGIN');
   try {
@@ -173,8 +251,8 @@ function addRelationCore(input, source) {
   const check = V.validateRelationInput(input, db);
   if (!check.ok) throw writeErr(check);
   const v = check.value;
-  const info = db.prepare('INSERT INTO relations (source_id, target_id, name, category, source) VALUES (?, ?, ?, ?, ?)')
-    .run(v.source_id, v.target_id, v.name, v.category, source);
+  const info = db.prepare('INSERT INTO relations (source_id, target_id, name, category, confidence, source_ref, source) VALUES (?, ?, ?, ?, ?, ?, ?)')
+    .run(v.source_id, v.target_id, v.name, v.category, v.confidence, v.source_ref, source);
   const id = Number(info.lastInsertRowid);
   const row = getRelation(id);
   logOp('ADD_RELATION', { relation: row }, source);
@@ -187,8 +265,8 @@ function updateRelationCore(id, patch, source) {
   const check = V.validateRelationPatch(patch, existing, db);
   if (!check.ok) throw writeErr(check);
   const v = check.value;
-  db.prepare('UPDATE relations SET source_id = ?, target_id = ?, name = ?, category = ? WHERE id = ?')
-    .run(v.source_id, v.target_id, v.name, v.category, id);
+  db.prepare('UPDATE relations SET source_id = ?, target_id = ?, name = ?, category = ?, confidence = ?, source_ref = ? WHERE id = ?')
+    .run(v.source_id, v.target_id, v.name, v.category, v.confidence, v.source_ref, id);
   const row = getRelation(id);
   logOp('UPDATE_RELATION', { before: existing, after: row }, source);
   return row;
@@ -286,6 +364,45 @@ function findPath(fromId, toId, maxHops = 6) {
   return { found: false, hops: null, entities: [], relations: [] };
 }
 
+// 多路径枚举：无向BFS，按跳数升序返回至多 limit 条简单路径
+function findPaths(fromId, toId, opts = {}) {
+  const maxHops = Math.min(6, Math.max(2, Number.isInteger(opts.maxHops) ? opts.maxHops : 4));
+  const limit = Math.min(10, Math.max(1, Number.isInteger(opts.limit) ? opts.limit : 5));
+  const from = getEntity(fromId);
+  const to = getEntity(toId);
+  if (!from || !to) return { found: false, paths: [], hint: '起点或终点实体不存在' };
+  if (fromId === toId) return { found: true, paths: [{ hops: 0, entities: [from], relations: [] }] };
+  const adj = new Map();
+  const touch = (id) => { if (!adj.has(id)) adj.set(id, []); };
+  for (const r of listRelations()) {
+    touch(r.source_id); touch(r.target_id);
+    adj.get(r.source_id).push(r);
+    adj.get(r.target_id).push(r);
+  }
+  const paths = [];
+  let frontier = [{ id: fromId, entities: [from], relations: [] }];
+  const visitedAtDepth = new Map([[fromId, 0]]);
+  for (let d = 0; d < maxHops && frontier.length && paths.length < limit; d++) {
+    const next = [];
+    for (const node of frontier) {
+      for (const r of adj.get(node.id) || []) {
+        const other = r.source_id === node.id ? r.target_id : r.source_id;
+        if (node.entities.some((e) => e.id === other)) continue; // 简单路径：不重复访问
+        const entities = [...node.entities, getEntity(other)];
+        const relations = [...node.relations, r];
+        if (other === toId) {
+          paths.push({ hops: relations.length, entities, relations });
+          break; // 同层内到达终点即止，更长的绕行路径不扩展
+        }
+        next.push({ id: other, entities, relations });
+      }
+    }
+    frontier = next;
+  }
+  paths.sort((a, b) => a.hops - b.hops);
+  return { found: paths.length > 0, paths: paths.slice(0, limit), hint: paths.length ? null : `当前跳数上限${maxHops}内无路径` };
+}
+
 // ---- 撤销最近一条操作：按快照生成逆向写入，单事务 + 单条UNDO日志 ----
 // DELETE_ENTITY 的级联关系/图片不在快照内，仅恢复实体本身（完整恢复请回溯保存点）
 // 连续撤销：向后扫描时跳过UNDO日志与其已撤销的目标日志；候选为RESTORE时拦截
@@ -509,7 +626,84 @@ function egoSubgraph(centerId, depth) {
 }
 
 function getGraph() {
-  return { entities: listEntities(), relations: listRelations(), image_counts: imageCounts() };
+  return { entities: listEntities(), relations: listRelations(), image_counts: imageCounts(), aliases: aliasMap() };
+}
+
+// ---- 别名与同名消歧 ----
+function cleanAlias(alias) {
+  return String(alias === undefined || alias === null ? '' : alias).trim();
+}
+
+function listAliases(entityId) {
+  return db.prepare('SELECT id, entity_id, alias, created_at FROM aliases WHERE entity_id = ? ORDER BY id').all(entityId);
+}
+
+function aliasMap() {
+  const map = {};
+  for (const row of db.prepare('SELECT entity_id, alias FROM aliases ORDER BY id').all()) {
+    (map[row.entity_id] = map[row.entity_id] || []).push(row.alias);
+  }
+  return map;
+}
+
+function aliasRecords() {
+  return db.prepare('SELECT id, entity_id, alias, created_at FROM aliases ORDER BY id').all();
+}
+
+// 名称占用检测：与任何实体主名或别名一致（trim后精确匹配）
+function findNameConflicts(name) {
+  const n = cleanAlias(name);
+  if (!n) return [];
+  const conflicts = [];
+  for (const e of db.prepare('SELECT id, name, category FROM entities WHERE name = ?').all(n)) {
+    conflicts.push({ id: e.id, name: e.name, category: e.category, via: '主名' });
+  }
+  for (const row of db.prepare('SELECT a.entity_id, a.alias, e.name, e.category FROM aliases a JOIN entities e ON e.id = a.entity_id WHERE a.alias = ?').all(n)) {
+    conflicts.push({ id: row.entity_id, name: row.name, category: row.category, via: `别名(${row.alias})` });
+  }
+  return conflicts;
+}
+
+function aliasConflict(alias, excludeEntityId) {
+  const n = cleanAlias(alias);
+  if (!n) return null;
+  const byName = db.prepare('SELECT id, name, category FROM entities WHERE name = ?').get(n);
+  if (byName && byName.id !== excludeEntityId) return { id: byName.id, name: byName.name, category: byName.category, via: '主名' };
+  const byAlias = db.prepare('SELECT entity_id, alias FROM aliases WHERE alias = ?').get(n);
+  if (byAlias && byAlias.entity_id !== excludeEntityId) {
+    const e = getEntity(byAlias.entity_id);
+    return { id: e.id, name: e.name, category: e.category, via: `别名(${byAlias.alias})` };
+  }
+  return null;
+}
+
+function addAlias(entityId, alias, source) {
+  const e = getEntity(entityId);
+  if (!e) { const err = new Error(`实体id=${entityId} 不存在`); err.status = 404; throw err; }
+  const n = cleanAlias(alias);
+  if (!n) { const err = new Error('别名必须为非空字符串'); err.status = 400; throw err; }
+  if (n.length > 200) { const err = new Error('别名长度不得超过200字符'); err.status = 400; throw err; }
+  if (n === e.name) { const err = new Error('别名与实体主名相同'); err.status = 400; throw err; }
+  const dup = db.prepare('SELECT id, entity_id, alias, created_at FROM aliases WHERE entity_id = ? AND alias = ?').get(entityId, n);
+  if (dup) return dup; // 幂等：同一实体同名别名已存在则直接返回
+  const conflict = aliasConflict(n, entityId);
+  if (conflict) { const err = new Error(`别名"${n}"已被占用`); err.status = 409; err.conflicts = [conflict]; throw err; }
+  return tx(() => {
+    const info = db.prepare('INSERT INTO aliases (entity_id, alias) VALUES (?, ?)').run(entityId, n);
+    const row = db.prepare('SELECT id, entity_id, alias, created_at FROM aliases WHERE id = ?').get(Number(info.lastInsertRowid));
+    logOp('ADD_ALIAS', { alias: row }, source);
+    return row;
+  });
+}
+
+function removeAlias(aliasId, source) {
+  const row = db.prepare('SELECT id, entity_id, alias FROM aliases WHERE id = ?').get(aliasId);
+  if (!row) { const err = new Error(`别名id=${aliasId} 不存在`); err.status = 404; throw err; }
+  return tx(() => {
+    db.prepare('DELETE FROM aliases WHERE id = ?').run(aliasId);
+    logOp('DELETE_ALIAS', { alias: row }, source);
+    return { deleted: row };
+  });
 }
 
 function getLogs(limit = 200) {
@@ -605,7 +799,8 @@ module.exports = {
   addEntity, updateEntity, deleteEntity,
   addRelation, updateRelation, deleteRelation,
   addEntityImage, getEntityImage, listEntityImages, deleteEntityImage, imageCounts, pruneMissingImages,
-  egoSubgraph, findPath, resolveKey,
+  egoSubgraph, findPath, findPaths, resolveKey,
+  listAliases, addAlias, removeAlias, aliasMap, aliasRecords, findNameConflicts,
   undoLast,
   miniCypher,
   applyAgentOps, getGraph, getLogs, maxLogId, counts, logRestore,

package/lib/embeddings.js

@@ -18,6 +18,9 @@ const DEFAULTS = {
   dim: 1024,
   api_key: '',
   rrf_k: 60,
+  mcp_enabled: false,
+  mcp_token: '',
+  mcp_readonly: false,
 };
 
 function loadSettings() {
@@ -99,18 +102,22 @@ async function build(progress) {
   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 aliasMap = graph.aliases || {};
   const scored = [];
   for (const e of graph.entities) {
     let score = 0;
     const name = e.name.toLowerCase();
+    const aliases = (aliasMap[e.id] || []).map((a) => a.toLowerCase());
     for (const t of terms) {
       if (name === t) score += 10;
       else if (name.includes(t)) score += 5;
+      else if (aliases.some((a) => a === t)) score += 6;
+      else if (aliases.some((a) => a.includes(t))) score += 3;
       else if (entityText(e).toLowerCase().includes(t)) score += 1;
     }
     if (score > 0) scored.push({ id: e.id, score });