local-knowledge-graph 1.8.0 → 1.9.0

package/HELP.md

@@ -61,10 +61,23 @@ kg
 
 程序自身零内置密钥，所有需要 key 的能力都在界面上自由配置：
 
-- **语义检索 / 智能提问综述**：检索页签"语义检索配置"填入 API Key（默认硅基流动 BAAI/bge-m3，可换任意 OpenAI 兼容接口的 Base URL 与模型）。Key 仅存本地数据目录的 settings.json，服务端永不回传真实值。不配置则自动退化为关键词检索，其余功能不受影响。
+- **语义检索 / 智能提问综述**：检索页签"语义检索配置"卡片完成三步——
+  1. **API Base URL**：默认 `https://api.siliconflow.cn/v1`（硅基流动）。任何 OpenAI 兼容接口都可换：填其 Base URL 即可（如 `https://api.openai.com/v1`、`https://api.deepseek.com/v1` 及各类本地/私有化网关）
+  2. **API Key + 模型**：粘贴密钥并填模型名（硅基流动默认 `BAAI/bge-m3`；换服务方时选其支持的 embedding 模型，如 OpenAI `text-embedding-3-small`）
+  3. **测试连接**：保存前先点「测试连接」，用页面上当前填写的配置（未保存也生效）向服务方发一次真实请求，成功会显示模型名、向量维度与耗时；失败给出具体错误（密钥无效 / 地址不可达 / 模型名错误）
+
+  Key 与 Base URL 仅存本地数据目录的 settings.json，服务端永不回传真实值。不配置则自动退化为关键词检索，其余功能不受影响。改配置后需重新「构建全量向量」才能让新模型生效于语义检索。
 - **OpenCode（AI 对话建图 / 智能提问编译）**：使用 opencode CLI 自身的认证（`opencode auth login`），应用不经手密钥。未安装或未认证时仅这两个功能降级。
 - 更换数据目录（`kg --data <目录>`）会使用该目录下的独立配置，互不串扰。
 
+## 关系编辑与关系图片
+
+关系（边）与实体一样支持人工与 AI 两种编辑方式，并可绑定佐证图片：
+
+- **人工编辑**：画布上点击关系边，右侧信息卡可修改——置信度三档（确证/推测/存疑）、来源引用（URL/文献+页码）、删除关系。所有修改实时写库并产生可撤销的操作记录。
+- **AI 编辑**：外部 Agent 通过 MCP 的 `kg_apply_ops` 可对关系做增删改（支持 `confidence` 置信度、`evidence_ref` 来源引用、按名称引用端点实体）；文档批量入图抽取出的关系同样带置信度与来源，经审核勾选后入库。AI 写入与人工修改互相实时可见。
+- **关系图片**：选中关系后点「绑图片」上传本地图片（支持多选，jpg/png/gif/webp/bmp，单张 ≤10MB，自动生成缩略图）。图片在关系信息卡缩略图网格展示，点击进入灯箱翻看，灯箱内可删除。典型用途：史料扫描件、聊天记录截图、地图/图表、新闻照片等佐证材料。图片文件存于数据目录 `data/uploads/r<关系id>/`，删除关系时其图片一并清理。
+
 ## MCP 外部接入（外部 Agent 读写图谱）
 
 在 **MCP 页签** 开启"MCP 服务"后，外部 Agent（Claude Desktop、Cursor、Cline、opencode 等）即可通过标准 MCP 协议对本图谱做完整增删改查：
@@ -75,16 +88,52 @@ kg
 - **只读模式**：勾选后外部仅可查询；**令牌管理**：一键重新生成即刻吊销旧令牌
 - **实时同步**：图谱被任一写入方（页面、API、MCP、外部进程）修改后，网页 3 秒内自动刷新
 
+## 知识推理：现有功能与方法体系
+
+### 本程序已有的推理功能
+
+图页签勾选「显示推理关系」后，图谱会叠加展示**隐性关系**（带"推"标记与推导依据链，仅推理展示、数据库中无记录）：
+
+- **传递推理**：师从(A,B) ∧ 师从(B,C) ⇒ 师从(A,C)；位于(A,B) ∧ 位于(B,C) ⇒ 位于(A,C) 等具备传递性的关系自动沿链推导
+- **对称/逆推理**：师生、上下级等方向的自动取反向边
+- **推理限定中心**：可只在某实体为中心的子图范围内推理，配合中心层级视图排查隐性关联
+- **问答证据链**：智能提问的回答附带支撑路径，推理结论可解释、可回溯
+
+### 知识推理的科学方法体系（由浅入深）
+
+| 方法 | 原理 | 典型代表 | 适合场景 |
+| ---- | ---- | ---- | ---- |
+| 公理/本体推理 | 依据关系性质（传递、对称、逆、子类）做逻辑推导 | OWL/RDF-Schema 推理机 | 本程序已内置；一致性与常识性推导 |
+| 规则推理 | 用户自定义 if-then 规则批量推导 | Datalog、SWRL、Prolog | 领域规则明确的图谱（师承同门、亲属称谓、企业控股） |
+| 图算法/链路预测 | 基于图结构打分：共同邻居、路径相似度、图嵌入向量 | Adamic-Adar、TransE、Node2Vec | 预测"可能存在但未录入"的关系，做补全推荐 |
+| 概率/统计推理 | 从历史边中统计规律，给出候选与置信度 | 路径排序 PRA、规则挖掘 AMIE | 大规模图谱的关系发现与排序 |
+| LLM+图谱协同 | 把子图上下文交给大模型归纳，人审核入库 | GraphRAG、LLM 关系抽取 | 开放域、规则难写尽的场景；本程序文档入图即此思路 |
+
+### 与本程序结合的路线
+
+1. **已具备**：传递/对称/逆公理推理 + 问答证据链 + MCP 推理查询（外部 Agent 可调 `kg_inference`）
+2. **低成本扩展·共同邻居推荐**：A→B、B→C 有边则提示 A↔C 为候选关系，在实体信息卡列出"推荐关系"，一键让 AI 验证或人工确认入库
+3. **AI 推荐关系**：选取两个实体，把二者属性与邻域子图交给 LLM 判断"是否存在关系、是什么关系、依据是什么"，经审核界面勾选入库（复用文档入图的审核管线）
+4. **进阶·自定义规则**：设置页开放规则编辑（如 师从(A,B) ∧ 师从(B,C) ⇒ 同门(A,C)），与内置传递/对称推理共用"推"标记展示
+
+### 应用场景与效益
+
+- **教育与学习**：历史人物、生物分类、概念依赖图谱——学生顺着推理链发现隐性关联，"为什么他俩有瓜葛"有推导依据可看
+- **情报与调研**：碎片信息建图后，推理把散点串成网络（共同雇主、共同事件），链路预测提示值得人工核查的候选线索
+- **企业知识管理**：专家经验、项目关系、人岗技能沉淀为图谱；推理显性化隐性知识（"做过 A 类项目且懂 B 技术的人"自动成组），降低对个别专家的依赖
+- **可解释问答**：相比黑盒大模型直答，图谱推理每一步给出证据路径，答案可验证、可追溯
+- **效益本质**：把已录入的显性关系"盘活"——同一份数据，推理可多挖掘出一批隐性关联与候选补全（实践中常见 20% 以上的新边发现），同时暴露矛盾数据（如传递链断裂）反哺数据质量
+
 ## 功能速览
 
 - **AI 对话建图**：右侧输入自然语言指令（联网补全），或上传文档（md/txt/pdf/docx）批量抽取三元组
 - **智能提问**：检索页签一句话找关系（LLM 编译检索计划，本地只读执行，可生成带引用的综述）
 - **语义检索**：配置硅基流动 API Key 后支持语义+关键词混合检索（未配置时自动退化为关键词模式）
-- **最短路径 / 中心子图 / 推理**：挖掘实体间关联链路、层级范围与隐性关系
+- **最短路径 / 中心子图 / 推理**：挖掘实体间关联链路、层级范围与隐性关系（方法体系见上文"知识推理"章节）
 - **撤销**：Ctrl+Z 或按钮，可连续撤销
 - **浅色主题**：视图设置 → 界面主题 → 浅色，整站配色与 3D 画布同步切换，选择本地记忆
 - **保存点与回溯**：版本页签打保存点，随时回滚；每次保存点自动滚动备份到 `data/backups/`
-- **图片绑定**：实体信息卡上传本地图片
+- **图片绑定**：实体与关系信息卡上传本地图片（缩略图+灯箱，佐证材料留存）
 - **导出**：RDF(Turtle)、整库 .db、单文件只读网页版
 
 ## 键盘快捷键
@@ -115,6 +164,7 @@ kg
 
 ## 版本历史摘要
 
+- **v1.9.0**：检索配置增强（Base URL 页面可配 + 测试连接按钮，保存前即可验证密钥/地址/模型）；关系图片绑定（信息卡上传/缩略图/灯箱，佐证材料与关系绑定，删关系连带清理）；帮助文档全面增补（检索配置详解/关系编辑与图片/知识推理方法体系与应用场景）
 - **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样式主题刷新后不恢复的问题；新增脚本异常提示

package/lib/db.js

@@ -78,6 +78,16 @@ function initSchema() {
       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);
+    CREATE TABLE IF NOT EXISTS relation_images (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      relation_id INTEGER NOT NULL REFERENCES relations(id) ON DELETE CASCADE,
+      filename TEXT NOT NULL,
+      stored_path TEXT NOT NULL,
+      thumb_path TEXT NOT NULL DEFAULT '',
+      caption TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_rimg_relation ON relation_images(relation_id);
   `);
   migrateEvidence();
   // 旧库迁移：entity_embeddings 已拆分至独立 vectors.db，主库内残留表直接清除
@@ -484,26 +494,46 @@ function entNameIn(id) {
 
 // 批量应用OpenCode操作（单事务原子提交，任一违规整体回滚，保持上一个合规版本）
 // ref占位符解析：add_entity可带ref，后续关系用ref引用新实体
+// add_relation 支持按名称引用（source_name/target_name）：主名或别名精确匹配，事务内可见同批新建实体
 function applyAgentOps(ops) {
   const applied = [];
   const refMap = {};
   return tx(() => {
-    for (const op of ops) {
-      if (!op || typeof op !== 'object') throw badOp('每个操作必须为JSON对象');
+    for (let opIdx = 0; opIdx < ops.length; opIdx++) {
+      const op = ops[opIdx];
+      try {
+        if (!op || typeof op !== 'object') throw badOp('每个操作必须为JSON对象');
       switch (op.op) {
         case 'add_entity': {
           const row = addEntityCore({ name: op.name, category: op.category, attributes: op.attributes }, 'OpenCode');
+          if (Array.isArray(op.aliases)) {
+            // 同事务内联写别名（addAlias 内部自带事务，嵌套会失败）
+            for (const raw of op.aliases) {
+              const n = cleanAlias(raw);
+              if (!n || n.length > 200 || n === row.name) continue;
+              const dup = db.prepare('SELECT id FROM aliases WHERE entity_id = ? AND alias = ?').get(row.id, n);
+              if (dup) continue;
+              if (aliasConflict(n, row.id)) continue;
+              const info = db.prepare('INSERT INTO aliases (entity_id, alias) VALUES (?, ?)').run(row.id, n);
+              const arow = db.prepare('SELECT id, entity_id, alias, created_at FROM aliases WHERE id = ?').get(Number(info.lastInsertRowid));
+              logOp('ADD_ALIAS', { alias: arow }, 'OpenCode');
+            }
+          }
           if (op.ref !== undefined) {
             if (typeof op.ref !== 'string' || !op.ref.trim()) throw badOp('ref必须为非空字符串');
             refMap[op.ref.trim()] = row.id;
           }
-          applied.push({ op: 'add_entity', id: row.id, name: row.name });
+          applied.push({ op: 'add_entity', id: row.id, name: row.name, aliases_added: Array.isArray(op.aliases) ? op.aliases.length : 0 });
           break;
         }
         case 'add_relation': {
-          const sid = resolveRef(op.source_id, op.source_ref, refMap);
-          const tid = resolveRef(op.target_id, op.target_ref, refMap);
-          const row = addRelationCore({ source_id: sid, target_id: tid, name: op.name, category: op.category }, 'OpenCode');
+          let sid;
+          let tid;
+          if (op.source_name !== undefined && op.source_id === undefined && op.source_ref === undefined) sid = resolveEntityName(op.source_name);
+          else sid = resolveRef(op.source_id, op.source_ref, refMap);
+          if (op.target_name !== undefined && op.target_id === undefined && op.target_ref === undefined) tid = resolveEntityName(op.target_name);
+          else tid = resolveRef(op.target_id, op.target_ref, refMap);
+          const row = addRelationCore({ source_id: sid, target_id: tid, name: op.name, category: op.category, confidence: op.confidence, source_ref: op.evidence_ref }, 'OpenCode');
           applied.push({ op: 'add_relation', id: row.id, name: row.name });
           break;
         }
@@ -521,7 +551,7 @@ function applyAgentOps(ops) {
         }
         case 'update_relation': {
           const patch = {};
-          for (const k of ['source_id', 'target_id', 'name', 'category']) if (op[k] !== undefined) patch[k] = op[k];
+          for (const k of ['source_id', 'target_id', 'name', 'category', 'confidence', 'source_ref']) if (op[k] !== undefined) patch[k] = op[k];
           const row = updateRelationCore(Number(op.id), patch, 'OpenCode');
           applied.push({ op: 'update_relation', id: row.id, name: row.name });
           break;
@@ -534,6 +564,11 @@ function applyAgentOps(ops) {
         default:
           throw badOp(`未知操作类型"${op.op}"，仅支持 add_entity/add_relation/update_entity/delete_entity/update_relation/delete_relation`);
       }
+      } catch (e) {
+        const opKind = (op && op.op) || '未知';
+        e.message = `第${opIdx + 1}条操作(${opKind})失败: ${e.message}`;
+        throw e;
+      }
     }
     return applied;
   });
@@ -548,6 +583,17 @@ function applyAgentOps(ops) {
     if (!Number.isInteger(n) || n <= 0) throw badOp(`source_id/target_id必须为正整数或使用ref占位符`);
     return n;
   }
+  // 按名称解析实体id：主名或别名精确匹配；重名返回候选
+  function resolveEntityName(name) {
+    const hits = findNameConflicts(String(name).trim());
+    if (hits.length === 1) return hits[0].id;
+    if (hits.length > 1) {
+      const e = badOp(`实体名 "${name}" 存在${hits.length}个候选（${hits.map((h) => `id=${h.id}`).join(', ')}），请改用 source_id/target_id`);
+      e.candidates = hits.map((h) => ({ id: h.id, name: h.name, category: h.category, via: h.via }));
+      throw e;
+    }
+    throw badOp(`实体 "${name}" 不存在（本批或库中均未找到）`);
+  }
   function badOp(msg) { const e = new Error('OpenCode操作校验未通过: ' + msg); e.status = 400; return e; }
 }
 
@@ -578,6 +624,34 @@ function deleteEntityImage(id) {
   return row;
 }
 
+// ---- 关系图片绑定（结构与实体图片一致；文件本体由 server 层存取于 data/uploads/）----
+function addRelationImage(relationId, item) {
+  if (!getRelation(relationId)) { const e = new Error(`关系id=${relationId} 不存在`); e.status = 404; throw e; }
+  if (typeof item.filename !== 'string' || !item.filename.trim()) { const e = new Error('filename必须为非空字符串'); e.status = 400; throw e; }
+  if (typeof item.stored_path !== 'string' || !item.stored_path.trim()) { const e = new Error('stored_path必须为非空字符串'); e.status = 400; throw e; }
+  const caption = typeof item.caption === 'string' ? item.caption.trim().slice(0, 300) : '';
+  const thumbPath = typeof item.thumb_path === 'string' ? item.thumb_path.trim() : '';
+  const info = db.prepare('INSERT INTO relation_images (relation_id, filename, stored_path, caption, thumb_path) VALUES (?, ?, ?, ?, ?)')
+    .run(relationId, item.filename.trim().slice(0, 200), item.stored_path.trim(), caption, thumbPath);
+  logOp('ADD_RELATION_IMAGE', { relation_id: relationId, image_id: Number(info.lastInsertRowid), filename: item.filename }, '手工');
+  return getRelationImage(Number(info.lastInsertRowid));
+}
+
+function getRelationImage(id) {
+  return db.prepare('SELECT * FROM relation_images WHERE id = ?').get(id);
+}
+
+function listRelationImages(relationId) {
+  return db.prepare('SELECT * FROM relation_images WHERE relation_id = ? ORDER BY id').all(relationId);
+}
+
+function deleteRelationImage(id) {
+  const row = getRelationImage(id);
+  if (!row) { const e = new Error(`关系图片绑定id=${id} 不存在`); e.status = 404; throw e; }
+  db.prepare('DELETE FROM relation_images WHERE id = ?').run(id);
+  return row;
+}
+
 // 剪除悬空图片行：.db 文件可迁移，uploads/ 资产不随库走，导入后行指向的文件可能不存在
 function pruneMissingImages() {
   const rows = db.prepare('SELECT id, stored_path FROM entity_images').all();
@@ -799,6 +873,7 @@ module.exports = {
   addEntity, updateEntity, deleteEntity,
   addRelation, updateRelation, deleteRelation,
   addEntityImage, getEntityImage, listEntityImages, deleteEntityImage, imageCounts, pruneMissingImages,
+  addRelationImage, getRelationImage, listRelationImages, deleteRelationImage,
   egoSubgraph, findPath, findPaths, resolveKey,
   listAliases, addAlias, removeAlias, aliasMap, aliasRecords, findNameConflicts,
   undoLast,

package/mcp/core.js

@@ -32,7 +32,7 @@ const TOOLS = [
   },
   {
     name: 'kg_get_entity',
-    description: '按id或名称获取单个实体详情（含其全部关系）',
+    description: '按id或名称获取单个实体详情（含其全部关系与别名）',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'number' }, name: { type: 'string' } },
@@ -115,13 +115,22 @@ const TOOLS = [
   },
   {
     name: 'kg_apply_ops',
-    description: '写入图谱操作（kg-ops协议JSON数组）：add_entity/add_relation/update_entity/update_relation/delete_entity/delete_relation。所有写入均记入operation_logs并自动git保存点',
+    description: '写入图谱操作（kg-ops协议JSON数组）：add_entity/add_relation/update_entity/update_relation/delete_entity/delete_relation。add_relation 支持按名称引用（source_name/target_name，含别名，重名时返回候选要求改用id）；实体间同批引用可用 ref 占位符（add_entity 传 ref，add_relation 传 source_ref/target_ref，仅同一次调用内有效）；关系可带 confidence（确证/推测/存疑）与 evidence_ref（来源引用文本）。add_entity 支持 aliases 数组。所有写入均记入operation_logs并自动git保存点',
     inputSchema: {
       type: 'object',
       properties: { ops: { type: 'array', items: { type: 'object' } } },
       required: ['ops'],
     },
   },
+  {
+    name: 'kg_reset',
+    description: '清空图谱全部实体与关系（级联删除，自动保存点）。仅用于重建场景，必须显式传 confirm:true 才会执行',
+    inputSchema: {
+      type: 'object',
+      properties: { confirm: { type: 'boolean', description: '必须为true才执行清空' } },
+      required: ['confirm'],
+    },
+  },
 ];
 
 function createCore({ readonly = false, source = 'MCP' } = {}) {
@@ -133,7 +142,17 @@ function createCore({ readonly = false, source = 'MCP' } = {}) {
       throw new Error(`实体id "${key}" 不存在`);
     }
     const hits = ents.filter((e) => e.name === key);
-    if (hits.length === 0) throw new Error(`实体 "${key}" 不存在`);
+    if (hits.length === 0) {
+      const aliasMap = db.aliasMap();
+      const aliasHits = ents.filter((e) => (aliasMap[e.id] || []).some((a) => a === key));
+      if (aliasHits.length === 1) return { id: aliasHits[0].id };
+      if (aliasHits.length > 1) {
+        const e = new Error(`别名 "${key}" 对应${aliasHits.length}个实体，请改用id`);
+        e.candidates = aliasHits.map((h) => ({ id: h.id, name: h.name, category: h.category }));
+        throw e;
+      }
+      throw new Error(`实体 "${key}" 不存在`);
+    }
     if (hits.length > 1) {
       const e = new Error(`实体名 "${key}" 存在${hits.length}个候选，请改用id`);
       e.candidates = hits.map((h) => ({ id: h.id, name: h.name, category: h.category }));
@@ -142,6 +161,10 @@ function createCore({ readonly = false, source = 'MCP' } = {}) {
     return { id: hits[0].id };
   }
 
+  // add_relation 的名称引用解析已下沉到 db.applyAgentOps（事务内可见同批新建实体）
+
+  const aliasById = () => db.aliasMap();
+
   const HANDLERS = {
     kg_stats: async () => {
       const c = db.counts();
@@ -155,7 +178,9 @@ function createCore({ readonly = false, source = 'MCP' } = {}) {
       const total = ents.length;
       const limit = Math.max(1, Math.min(Number(args.limit) || 100, 500));
       const offset = Math.max(0, Number(args.offset) || 0);
-      return { total, count: Math.min(limit, total - offset), offset, entities: ents.slice(offset, offset + limit) };
+      const amap = aliasById();
+      const page = ents.slice(offset, offset + limit).map((e) => ({ ...e, aliases: amap[e.id] || [] }));
+      return { total, count: Math.min(limit, total - offset), offset, entities: page };
     },
     kg_get_entity: async (args) => {
       let e = null;
@@ -167,7 +192,7 @@ function createCore({ readonly = false, source = 'MCP' } = {}) {
       }
       if (!e) throw new Error('实体不存在（请提供id或name）');
       const rels = db.listRelations().filter((r) => r.source_id === e.id || r.target_id === e.id);
-      return { entity: e, relations: rels };
+      return { entity: { ...e, aliases: aliasById()[e.id] || [] }, relations: rels };
     },
     kg_get_graph: async (args) => {
       const g = db.getGraph();
@@ -219,6 +244,15 @@ function createCore({ readonly = false, source = 'MCP' } = {}) {
       try { git.savepoint(`${source}写入: ${applied.length} 项操作`, source); } catch (_) { /* 数据目录无git时忽略 */ }
       return { applied_count: applied.length, applied };
     },
+    kg_reset: async (args) => {
+      if (readonly) throw new Error('MCP运行于只读模式，清空被拒绝（可在应用设置中关闭只读）');
+      if (args.confirm !== true) throw new Error('清空图谱是危险操作，必须显式传 confirm:true 执行');
+      const ids = db.listEntities().map((e) => e.id);
+      if (!ids.length) return { deleted_entities: 0, message: '图谱已为空' };
+      db.applyAgentOps(ids.map((id) => ({ op: 'delete_entity', id })));
+      try { git.savepoint(`${source}清空: 删除${ids.length}个实体`, source); } catch (_) { /* 忽略 */ }
+      return { deleted_entities: ids.length, message: '图谱已清空，可通过保存点回溯恢复' };
+    },
   };
 
   return { TOOLS, HANDLERS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-knowledge-graph",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "本地知识图谱整合器：3D可视化 + AI对话建图 + 智能检索 + Git回溯 + RDF合规，全流程本地运行",
   "main": "server.js",
   "bin": {

package/public/app.js

@@ -12,6 +12,7 @@ const state = {
   inferredData: null,      // /api/inference 缓存 {inferred, entities, ontology}
   imageCounts: new Map(),  // entityId -> 图片数量
   entityImages: new Map(), // entityId -> [图片行]
+  relationImages: new Map(), // relationId -> [图片行]
   meta: null,              // /api/meta 缓存（图例与下拉框用）
   aliases: {},             // entityId -> [别名]（/api/graph 附带）
   confFilter: '',          // 关系置信度过滤：''=全部 | 确证 | 推测 | 存疑
@@ -623,6 +624,10 @@ function renderInfoCard() {
     const r = state.relations.find((x) => x.id === rid);
     if (!r) { card.style.display = 'none'; return; }
     const s = state.entityMap.get(r.source_id), t = state.entityMap.get(r.target_id);
+    const rimgs = state.relationImages.get(rid);
+    const rimgHtml = `<div id="rimg-section"><div class="kv"><b>图片</b>：${rimgs ? (rimgs.length ? rimgs.length + ' 张' : '（无）') : '加载中…'}</div>` +
+      (rimgs && rimgs.length ? `<div id="img-grid">` + rimgs.map((im, i) => `<img src="${escapeHtml(im.thumb_url || im.url)}" title="${escapeHtml(im.caption || im.filename)}" onclick="openRelLightbox(${rid},${i})">`).join('') + `</div>` : '') +
+      `</div>`;
     card.innerHTML = `
       <h4>${escapeHtml(r.name)} <span class="tag" style="color:${RELATION_STYLE[r.category].css};border-color:${RELATION_STYLE[r.category].css}55">${r.category}关系</span> ${confBadge(r)}</h4>
       <div class="kv"><b>${s ? escapeHtml(s.entity.name) : '?'}</b> --&gt; <b>${t ? escapeHtml(t.entity.name) : '?'}</b></div>
@@ -632,8 +637,10 @@ function renderInfoCard() {
           ${['确证', '推测', '存疑'].map((c) => `<option value="${c}"${(r.confidence || '确证') === c ? ' selected' : ''}>${c}</option>`).join('')}
         </select></div>
       <div class="kv"><b>来源引用</b>：<input id="rel-sref" value="${escapeHtml(r.source_ref || '')}" placeholder="URL/文献+页码" style="width:150px"></div>
-      <div class="btns"><button onclick="saveRelMeta(${r.id})">保存标注</button><button class="danger" onclick="delRelation(${r.id})">删除</button></div>`;
+      ${rimgHtml}
+      <div class="btns"><button onclick="saveRelMeta(${r.id})">保存标注</button><button onclick="$('entity-img-input').click()">绑图片</button><button class="danger" onclick="delRelation(${r.id})">删除</button></div>`;
     card.style.display = 'block';
+    if (!rimgs) loadRelationImages(rid);
   }
 }
 function escapeHtml(s) {
@@ -740,10 +747,13 @@ document.body.appendChild(imgInput);
 window.$ = $; // 信息卡内联onclick需访问$
 
 imgInput.addEventListener('change', async () => {
-  const id = state.selected && state.selected.type === 'entity' ? state.selected.id : null;
+  const sel = state.selected;
+  const isRel = sel && sel.type === 'relation';
+  const id = sel && (sel.type === 'entity' || sel.type === 'relation') ? sel.id : null;
   const files = [...imgInput.files];
   imgInput.value = '';
   if (!id || !files.length) return;
+  const postUrl = isRel ? `/api/relations/${id}/images` : `/api/entities/${id}/images`;
   for (const f of files) {
     try {
       if (f.size > 10 * 1024 * 1024) throw new Error('超过10MB上限');
@@ -751,15 +761,20 @@ imgInput.addEventListener('change', async () => {
       const thumb = await makeThumbB64(f);
       let caption = '';
       if (files.length === 1) caption = prompt('图片备注（可留空）', '') || '';
-      await api(`/api/entities/${id}/images`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ filename: f.name, content_b64: b64, caption, thumb_b64: thumb }) });
+      await api(postUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ filename: f.name, content_b64: b64, caption, thumb_b64: thumb }) });
       toast(`已绑定图片 ${f.name}`);
     } catch (e) { toast(`图片 ${f.name} 绑定失败: ${e.message}`, true); }
   }
-  state.entityImages.delete(id);
-  const cnt = await api(`/api/entities/${id}/images`);
-  state.entityImages.set(id, cnt);
-  state.imageCounts.set(id, cnt.length);
-  await refreshAll(false);
+  if (isRel) {
+    const rows = await api(`/api/relations/${id}/images`);
+    state.relationImages.set(id, rows);
+  } else {
+    state.entityImages.delete(id);
+    const cnt = await api(`/api/entities/${id}/images`);
+    state.entityImages.set(id, cnt);
+    state.imageCounts.set(id, cnt.length);
+    await refreshAll(false);
+  }
   if (state.selected && state.selected.id === id) renderInfoCard();
 });
 
@@ -786,22 +801,39 @@ async function loadEntityImages(entityId) {
   } catch (e) { toast(e.message, true); }
 }
 
+async function loadRelationImages(relationId) {
+  try {
+    const rows = await api(`/api/relations/${relationId}/images`);
+    state.relationImages.set(relationId, rows);
+    if (state.selected && state.selected.type === 'relation' && state.selected.id === relationId) renderInfoCard();
+  } catch (e) { toast(e.message, true); }
+}
+
 /* ---- 灯箱 ---- */
-let lbState = null; // { list, idx }
+let lbState = null; // { kind:'entity'|'relation', list, idx }
 function openLightbox(entityId, idx) {
   const list = state.entityImages.get(entityId) || [];
   if (!list.length) return;
-  lbState = { list, idx };
+  lbState = { kind: 'entity', list, idx };
   renderLightbox();
   $('lightbox').classList.add('show');
 }
 window.openLightbox = openLightbox;
 
+function openRelLightbox(relationId, idx) {
+  const list = state.relationImages.get(relationId) || [];
+  if (!list.length) return;
+  lbState = { kind: 'relation', list, idx };
+  renderLightbox();
+  $('lightbox').classList.add('show');
+}
+window.openRelLightbox = openRelLightbox;
+
 function renderLightbox() {
   if (!lbState) return;
   const im = lbState.list[lbState.idx];
   $('lb-img').src = im.url;
-  $('lb-cap').textContent = (im.caption || im.filename) + `（实体#${im.entity_id}）`;
+  $('lb-cap').textContent = (im.caption || im.filename) + `（${lbState.kind === 'relation' ? '关系' : '实体'}#${lbState.kind === 'relation' ? im.relation_id : im.entity_id}）`;
   $('lb-pos').textContent = `${lbState.idx + 1} / ${lbState.list.length}`;
 }
 
@@ -822,6 +854,16 @@ async function delImage() {
   const im = lbState.list[lbState.idx];
   if (!confirm(`删除图片绑定「${im.filename}」？文件将从磁盘移除。`)) return;
   try {
+    if (lbState.kind === 'relation') {
+      await api(`/api/relation-images/${im.id}`, { method: 'DELETE' });
+      const rid = im.relation_id;
+      lbState.list.splice(lbState.idx, 1);
+      state.relationImages.set(rid, lbState.list);
+      if (!lbState.list.length) closeLightbox(); else renderLightbox();
+      toast('图片绑定已删除');
+      if (state.selected && state.selected.type === 'relation' && state.selected.id === rid) renderInfoCard();
+      return;
+    }
     await api(`/api/images/${im.id}`, { method: 'DELETE' });
     const eid = im.entity_id;
     lbState.list.splice(lbState.idx, 1);
@@ -1043,9 +1085,10 @@ async function loadSimilar(id) {
 window.loadSimilar = loadSimilar;
 
 async function delRelation(id) {
-  if (!confirm(`删除关系 #${id}？`)) return;
+  if (!confirm(`删除关系 #${id}？其绑定的图片文件将一并移除。`)) return;
   try {
     await api(`/api/relations/${id}`, { method: 'DELETE' });
+    state.relationImages.delete(id);
     if (state.selected && state.selected.id === id) state.selected = null;
     toast('关系已删除');
     await refreshAll();
@@ -2020,6 +2063,7 @@ async function loadSearchStatus() {
     const [st, cfg] = await Promise.all([api('/api/embeddings/status'), api('/api/embeddings/settings')]);
     $('s-status').textContent = `已索引 ${st.indexed}/${st.total_entities}`;
     if (!$('s-model').value) $('s-model').value = cfg.model;
+    if (!$('s-baseurl').value) $('s-baseurl').value = cfg.base_url || 'https://api.siliconflow.cn/v1';
     $('s-key').placeholder = cfg.api_key === '已配置' ? '已配置（输入新值可更换）' : '仅存本地 data/settings.json';
   } catch (_) { /* 服务未就绪时静默 */ }
 }
@@ -2110,16 +2154,38 @@ try {
 } catch (_) { /* 浏览器不支持时依赖手动刷新 */ }
 
 $('s-save').addEventListener('click', async () => {
-  const patch = { model: $('s-model').value.trim() || 'BAAI/bge-m3' };
+  const patch = {
+    model: $('s-model').value.trim() || 'BAAI/bge-m3',
+    base_url: $('s-baseurl').value.trim() || 'https://api.siliconflow.cn/v1',
+  };
   const key = $('s-key').value.trim();
   if (key) patch.api_key = key;
   try {
     await api('/api/embeddings/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(patch) });
     $('s-key').value = '';
+    $('s-status').textContent = '配置已保存';
     loadSearchStatus();
   } catch (e) { $('s-status').textContent = e.message; }
 });
 
+// 测试连接：用页面上当前填写的配置（未保存的也生效）向服务方发一次真实请求
+$('s-test').addEventListener('click', async () => {
+  const btn = $('s-test');
+  btn.disabled = true;
+  $('s-status').textContent = '测试中…';
+  const patch = {
+    model: $('s-model').value.trim() || 'BAAI/bge-m3',
+    base_url: $('s-baseurl').value.trim() || 'https://api.siliconflow.cn/v1',
+  };
+  const key = $('s-key').value.trim();
+  if (key) patch.api_key = key;
+  try {
+    const r = await api('/api/embeddings/test', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(patch) });
+    $('s-status').textContent = `连接成功：${r.model} 维度${r.dim} 耗时${r.ms}ms`;
+  } catch (e) { $('s-status').textContent = `连接失败：${e.message}`; }
+  btn.disabled = false;
+});
+
 $('s-build').addEventListener('click', async () => {
   const btn = $('s-build');
   btn.disabled = true;

package/public/index.html

@@ -101,11 +101,14 @@
         </div>
         <div class="card">
           <h3>语义检索配置（硅基流动默认）</h3>
+          <div class="row">
+            <div style="flex:1"><label>API Base URL</label><input id="s-baseurl" placeholder="https://api.siliconflow.cn/v1"></div>
+          </div>
           <div class="row">
             <div style="flex:1"><label>API Key</label><input id="s-key" type="password" placeholder="仅存本地 data/settings.json"></div>
             <div style="width:110px"><label>模型</label><input id="s-model"></div>
           </div>
-          <div class="row"><button class="primary" id="s-save">保存配置</button><button id="s-build">构建全量向量</button><span id="s-status" style="font-size:11px;color:#8fa3c0;align-self:center"></span></div>
+          <div class="row"><button class="primary" id="s-save">保存配置</button><button id="s-test">测试连接</button><button id="s-build">构建全量向量</button><span id="s-status" style="font-size:11px;color:#8fa3c0;align-self:center"></span></div>
         </div>
         <div class="card">
           <h3>混合检索（语义+关键词 RRF 融合）</h3>
@@ -246,12 +249,12 @@
           <h3>快速上手</h3>
           <ul class="hp-list">
             <li><b>AI 对话建图</b>：右侧输入自然语言（如"联网查一下珠穆朗玛峰的海拔并建入图谱"），或上传文档（md/txt/pdf/docx）批量抽取</li>
-            <li><b>检索页签</b>：智能提问（一句话找关系）、语义/关键词混合检索</li>
+            <li><b>检索页签</b>：智能提问（一句话找关系）、语义/关键词混合检索；语义配置卡可填 Base URL/Key/模型并一键测试连接</li>
             <li><b>最短路径</b>：搜索或列表选中实体后，用"路径"功能查两实体关联链路</li>
             <li><b>撤销</b>：按钮或 Ctrl+Z，可连续撤销；删除实体仅恢复实体本身，关联关系可在日志页看到级联记录</li>
             <li><b>推理</b>：开关叠加虚线显示的隐性关系（传递/对称/逆规则），点击可见推导依据</li>
             <li><b>保存点与回溯</b>：版本页签打保存点，随时回滚到任一历史状态</li>
-            <li><b>图片绑定</b>：实体信息卡上传本地图片，自动生成缩略图</li>
+            <li><b>图片绑定</b>：实体与关系信息卡上传本地图片（缩略图+灯箱），佐证材料随图谱留存</li>
             <li><b>导出</b>：RDF(Turtle)、整库 .db、单文件只读网页版</li>
           </ul>
           <h3>键盘快捷键</h3>

package/server.js

@@ -42,7 +42,9 @@ const mcpHandler = createMcpHandler({
 const PORT = Number(process.env.PORT || 3000);
 const app = express();
 app.use(express.json({ limit: '30mb' }));
-app.use(express.static(path.join(__dirname, 'public')));
+app.use(express.static(path.join(__dirname, 'public'), {
+  setHeaders: (res) => { res.setHeader('Cache-Control', 'no-cache, must-revalidate'); }
+}));
 app.use('/uploads', express.static(path.join(git.DATA_DIR, 'uploads')));
 
 const api = express.Router();
@@ -315,11 +317,70 @@ api.delete('/images/:imgId', (req, res) => {
   res.json({ deleted: row });
 });
 
+// ---------- 关系图片绑定（与实体图片同模式，目录 r<id>）----------
+api.get('/relations/:id/images', (req, res) => {
+  const id = Number(req.params.id);
+  if (!db.getRelation(id)) return res.status(404).json({ error: `关系id=${id} 不存在` });
+  const rel = (p) => (p ? '/uploads/' + p.replace(/^uploads[\\/]/, '') : null);
+  res.json(db.listRelationImages(id).map((r) => ({ ...r, url: rel(r.stored_path), thumb_url: rel(r.thumb_path) || rel(r.stored_path) })));
+});
+
+api.post('/relations/:id/images', (req, res) => {
+  const id = Number(req.params.id);
+  const { filename, content_b64, caption, thumb_b64 } = req.body || {};
+  if (!filename || !content_b64) return res.status(400).json({ error: '必须提供文件名与内容(content_b64)' });
+  const ext = path.extname(String(filename)).toLowerCase();
+  if (!IMAGE_EXTS.includes(ext)) return res.status(400).json({ error: `仅支持图片格式: ${IMAGE_EXTS.join(' ')}` });
+  let buf;
+  try { buf = Buffer.from(content_b64, 'base64'); } catch (_) { return res.status(400).json({ error: 'content_b64不是合法的base64' }); }
+  if (!buf.length) return res.status(400).json({ error: '文件内容为空' });
+  if (buf.length > MAX_IMAGE_BYTES) return res.status(400).json({ error: '单张图片不得超过10MB' });
+
+  const dir = path.join(git.DATA_DIR, 'uploads', `r${id}`);
+  fs.mkdirSync(dir, { recursive: true });
+  const safe = path.basename(String(filename)).replace(/[^\w.\-\u4e00-\u9fa5]/g, '_').slice(0, 80) || 'image';
+  const storedPath = path.join('uploads', `r${id}`, `${Date.now()}_${safe}`);
+  fs.writeFileSync(path.join(git.DATA_DIR, storedPath), buf);
+  let thumbPath = '';
+  if (thumb_b64) {
+    try {
+      const tbuf = Buffer.from(thumb_b64, 'base64');
+      if (tbuf.length > 0 && tbuf.length <= 2 * 1024 * 1024) {
+        thumbPath = path.join('uploads', `r${id}`, `${Date.now()}_thumb_${safe}`);
+        fs.writeFileSync(path.join(git.DATA_DIR, thumbPath), tbuf);
+      }
+    } catch (_) { thumbPath = ''; }
+  }
+  try {
+    const row = db.addRelationImage(id, { filename, stored_path: storedPath, caption, thumb_path: thumbPath });
+    const rel = (p) => (p ? '/uploads/' + p.replace(/^uploads[\\/]/, '') : null);
+    res.json({ ...row, url: rel(row.stored_path), thumb_url: rel(row.thumb_path) || rel(row.stored_path) });
+  } catch (e) {
+    cleanupImageFiles([storedPath, thumbPath]);
+    throw e;
+  }
+});
+
+api.delete('/relation-images/:imgId', (req, res) => {
+  const row = db.deleteRelationImage(Number(req.params.imgId));
+  cleanupImageFiles([row.stored_path, row.thumb_path].filter(Boolean));
+  res.json({ deleted: row });
+});
+
+// 删除关系时连带清理其图片文件（表行由外键级联清除）
+api.delete('/relations/:id', (req, res) => {
+  const id = Number(req.params.id);
+  const files = db.listRelationImages(id).flatMap((r) => [r.stored_path, r.thumb_path].filter(Boolean));
+  const out = db.deleteRelation(id, '手工');
+  cleanupImageFiles(files);
+  res.json(out);
+});
+
 // ---------- 关系 ----------
 api.get('/relations', (req, res) => res.json(db.listRelations()));
 api.post('/relations', (req, res) => res.json(db.addRelation(req.body, '手工')));
 api.put('/relations/:id', (req, res) => res.json(db.updateRelation(Number(req.params.id), req.body, '手工')));
-api.delete('/relations/:id', (req, res) => res.json(db.deleteRelation(Number(req.params.id), '手工')));
+// DELETE /relations/:id 已在上方"关系图片"块定义（连带清理图片文件）
 
 // ---------- 图谱 / 日志 ----------
 api.get('/graph', (req, res) => res.json(db.getGraph()));
@@ -369,6 +430,21 @@ api.put('/embeddings/settings', (req, res) => {
   } catch (e) { res.status(400).json({ error: e.message }); }
 });
 
+// 测试连接：用当前（或请求体内临时覆盖的）配置向服务方发一次真实embedding请求
+api.post('/embeddings/test', async (req, res) => {
+  const overrides = req.body || {};
+  if (overrides.api_key === '已配置') delete overrides.api_key; // 占位=沿用已存密钥
+  const s = { ...embeddings.loadSettings(), ...overrides };
+  const started = Date.now();
+  try {
+    const vec = await embeddings.embed(['连接测试'], s);
+    const dim = Array.isArray(vec) && Array.isArray(vec[0]) ? vec[0].length : (vec && vec.length) || 0;
+    res.json({ ok: true, model: s.model, base_url: s.base_url, dim, ms: Date.now() - started });
+  } catch (e) {
+    res.status(400).json({ ok: false, error: e.message, ms: Date.now() - started });
+  }
+});
+
 api.post('/embeddings/build', async (req, res) => {
   try {
     const result = await embeddings.build();