local-knowledge-graph 1.8.1 → 1.10.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,53 @@ 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. **已具备·共同邻居推荐**：检索页签"关系推荐"卡一键扫描全图——无直接边但拥有共同邻居的实体对自动列为候选（Adamic-Adar 打分，邻居越稀有越靠前）；实体信息卡"推荐关系"按钮查看与该实体相关的候选。每条候选可点「AI 判断」让 LLM 给出关系名/大类/置信度/依据，确认后一键采纳入库（来源引用自动记为 AI 推荐依据，可撤销）
+3. **已具备·AI 推荐关系**：即上条「AI 判断」——把两实体属性与共同关联交给大模型判断"是否存在关系、是什么关系、依据是什么"，输出仅供决策，入库必须人工点击确认（AI 不直接写库）
+4. **进阶·自定义规则**：设置页开放规则编辑（如 师从(A,B) ∧ 师从(B,C) ⇒ 同门(A,C)），与内置传递/对称推理共用"推"标记展示
+
+### 应用场景与效益
+
+- **教育与学习**：历史人物、生物分类、概念依赖图谱——学生顺着推理链发现隐性关联，"为什么他俩有瓜葛"有推导依据可看
+- **情报与调研**：碎片信息建图后，推理把散点串成网络（共同雇主、共同事件），链路预测提示值得人工核查的候选线索
+- **企业知识管理**：专家经验、项目关系、人岗技能沉淀为图谱；推理显性化隐性知识（"做过 A 类项目且懂 B 技术的人"自动成组），降低对个别专家的依赖
+- **可解释问答**：相比黑盒大模型直答，图谱推理每一步给出证据路径，答案可验证、可追溯
+- **效益本质**：把已录入的显性关系"盘活"——同一份数据，推理可多挖掘出一批隐性关联与候选补全（实践中常见 20% 以上的新边发现），同时暴露矛盾数据（如传递链断裂）反哺数据质量
+
 ## 功能速览
 
 - **AI 对话建图**：右侧输入自然语言指令（联网补全），或上传文档（md/txt/pdf/docx）批量抽取三元组
 - **智能提问**：检索页签一句话找关系（LLM 编译检索计划，本地只读执行，可生成带引用的综述）
+- **关系推荐**：共同邻居算法找"该连没连"的实体对，AI 判断后一键采纳入库（检索页签"关系推荐"卡 / 实体卡"推荐关系"按钮）
 - **语义检索**：配置硅基流动 API Key 后支持语义+关键词混合检索（未配置时自动退化为关键词模式）
-- **最短路径 / 中心子图 / 推理**：挖掘实体间关联链路、层级范围与隐性关系
+- **最短路径 / 中心子图 / 推理**：挖掘实体间关联链路、层级范围与隐性关系（方法体系见上文"知识推理"章节）
 - **撤销**：Ctrl+Z 或按钮，可连续撤销
 - **浅色主题**：视图设置 → 界面主题 → 浅色，整站配色与 3D 画布同步切换，选择本地记忆
 - **保存点与回溯**：版本页签打保存点，随时回滚；每次保存点自动滚动备份到 `data/backups/`
-- **图片绑定**：实体信息卡上传本地图片
+- **图片绑定**：实体与关系信息卡上传本地图片（缩略图+灯箱，佐证材料留存）
 - **导出**：RDF(Turtle)、整库 .db、单文件只读网页版
 
 ## 键盘快捷键
@@ -115,6 +165,8 @@ kg
 
 ## 版本历史摘要
 
+- **v1.10.0**：关系推荐——共同邻居算法（Adamic-Adar 打分，排除已有直接边）全图/中心实体两种扫描；AI 判断候选关系（LLM 给出关系名/大类/置信度/依据，人工确认后入库，不直接写库）；检索页签新增"关系推荐"卡，实体信息卡新增"推荐关系"按钮
+- **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，主库内残留表直接清除
@@ -614,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();
@@ -835,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/lib/recommend.js

@@ -0,0 +1,133 @@
+'use strict';
+
+// 关系推荐：共同邻居图算法（Adamic-Adar打分）+ LLM候选关系判断
+// 设计约束：推荐纯本地只读计算；LLM判断只输出建议JSON，入库须经前端确认（走人工接口，来源'手工'）。
+
+const REL_CATS = ['空间', '互动', '归属', '时间', '属性'];
+const CONF_LEVELS = ['确证', '推测', '存疑'];
+const MAX_LLM_TIMEOUT = 60000; // opencode CLI 实测冷启动+推理可达30-50s，与综述超时一致
+
+// ---------- 共同邻居推荐 ----------
+// 对每对无直接边的实体统计共同邻居并按 Adamic-Adar 打分（邻居越稀有分越高）。
+// opts.centerId 限定只返回与该实体相关的候选；opts.minCommon 最小共同邻居数（默认2，center模式1）；opts.limit 返回上限（默认20）。
+function computeCoNeighborRecs(graph, opts = {}) {
+  const centerId = opts.centerId || null;
+  const limit = Math.min(Math.max(1, Number(opts.limit) || 20), 100);
+  const minCommon = Math.max(1, Number(opts.minCommon) || (centerId ? 1 : 2));
+
+  const byId = new Map(graph.entities.map((e) => [e.id, e]));
+  const neighbors = new Map(); // id -> Map(邻居id -> 经该邻居相连的关系数)
+  const touch = (id) => { if (!neighbors.has(id)) neighbors.set(id, new Map()); };
+  const direct = new Set(); // 'a|b' 双向规范化键
+  const dkey = (a, b) => (a < b ? `${a}|${b}` : `${b}|${a}`);
+  for (const r of graph.relations) {
+    if (!byId.has(r.source_id) || !byId.has(r.target_id)) continue;
+    touch(r.source_id); touch(r.target_id);
+    neighbors.get(r.source_id).set(r.target_id, (neighbors.get(r.source_id).get(r.target_id) || 0) + 1);
+    neighbors.get(r.target_id).set(r.source_id, (neighbors.get(r.target_id).get(r.source_id) || 0) + 1);
+    direct.add(dkey(r.source_id, r.target_id));
+  }
+
+  // 每节点收集2跳计数：O(V * deg^2)，大图时节点按度截断保护
+  const DEG_CAP = 300;
+  const nodes = [...byId.keys()].filter((id) => neighbors.has(id));
+  const counter = new Map(); // 'a|b' -> Map(commonId -> true)
+  for (const a of nodes) {
+    const nbs = [...neighbors.get(a).keys()];
+    if (nbs.length > DEG_CAP) continue; // 度数过高的枢纽节点跳过全对展开，防爆炸
+    for (const m of nbs) {
+      const mn = neighbors.get(m);
+      if (!mn) continue;
+      for (const b of mn.keys()) {
+        if (b === a || neighbors.get(a).has(b)) continue; // 自身或已有直接边
+        const k = dkey(a, b);
+        if (!counter.has(k)) counter.set(k, new Map());
+        counter.get(k).set(m, true);
+      }
+    }
+  }
+
+  const nameOf = (id) => (byId.get(id) ? byId.get(id).name : `#${id}`);
+  const recs = [];
+  for (const [k, commons] of counter) {
+    if (commons.size < minCommon) continue;
+    const [a, b] = k.split('|').map(Number);
+    if (centerId && a !== centerId && b !== centerId) continue;
+    // Adamic-Adar：sum(1/log(deg(共同邻居)))
+    let score = 0;
+    for (const c of commons.keys()) {
+      const deg = (neighbors.get(c) || new Map()).size || 1;
+      score += 1 / Math.log(deg + 1);
+    }
+    recs.push({
+      source_id: a, target_id: b,
+      source_name: nameOf(a), target_name: nameOf(b),
+      common_count: commons.size,
+      common_names: [...commons.keys()].slice(0, 6).map(nameOf),
+      score: Number(score.toFixed(4)),
+    });
+  }
+  recs.sort((x, y) => y.score - x.score || y.common_count - x.common_count);
+  return recs.slice(0, limit);
+}
+
+// ---------- LLM 候选关系判断 ----------
+function buildJudgePrompt(a, b, commonNames) {
+  const ent = (e) => {
+    let s = `- ${e.name}（${e.category}）`;
+    let attrs = '';
+    try { attrs = JSON.stringify(JSON.parse(e.attributes || '{}')); } catch (_) { attrs = String(e.attributes || '{}'); }
+    if (attrs && attrs !== '{}') s += ` 属性:${attrs.slice(0, 300)}`;
+    return s;
+  };
+  return [
+    '你是知识图谱专家。判断以下两个实体之间是否存在值得录入图谱的明确关系（基于常识与给出的事实，不要编造）。',
+    `实体A: ${ent(a)}`,
+    `实体B: ${ent(b)}`,
+    commonNames && commonNames.length ? `它们在图谱中拥有共同关联: ${commonNames.join('、')}` : '',
+    '',
+    '只输出JSON（不要其他文字），格式：',
+    '{"has_relation": true/false, "name": "关系名(2-4字，如 师从/位于/效力于)", "category": "空间|互动|归属|时间|属性 之一", "confidence": "确证|推测|存疑 之一", "evidence": "一句话依据"}',
+    'has_relation 为 false 时其余字段留空字符串。',
+  ].filter(Boolean).join('\n');
+}
+
+// 校验LLM输出；非法字段回退默认或拒绝
+function validateJudge(j) {
+  if (!j || typeof j !== 'object') return { ok: false, error: '输出不是JSON对象' };
+  const out = {
+    has_relation: Boolean(j.has_relation),
+    name: String(j.name || '').trim().slice(0, 30),
+    category: REL_CATS.includes(j.category) ? j.category : '',
+    confidence: CONF_LEVELS.includes(j.confidence) ? j.confidence : '推测',
+    evidence: String(j.evidence || '').trim().slice(0, 300),
+  };
+  if (!out.has_relation) return { ok: true, judge: { has_relation: false } };
+  if (!out.name) return { ok: false, error: 'has_relation为true时关系名不能为空' };
+  if (!out.category) return { ok: false, error: `关系大类必须是: ${REL_CATS.join('/')}` };
+  return { ok: true, judge: out };
+}
+
+function extractJson(text) {
+  let t = String(text || '').trim().replace(/```(?:json)?/gi, '');
+  const start = t.indexOf('{');
+  const end = t.lastIndexOf('}');
+  if (start === -1 || end <= start) throw new Error('输出中未找到JSON对象');
+  return JSON.parse(t.slice(start, end + 1));
+}
+
+// runPlain 可注入（测试mock）；graph 关系用于取两实体邻域摘要
+async function aiJudgeRelation(payload, runPlain) {
+  const { a, b, common_names } = payload || {};
+  if (!a || !b) { const e = new Error('必须提供待判断的两个实体'); e.status = 400; throw e; }
+  const rp = runPlain || require('./agent').runPlain;
+  const r = await rp(buildJudgePrompt(a, b, common_names || []), MAX_LLM_TIMEOUT);
+  if (!r.ok) { const e = new Error(`LLM判断失败: ${r.error}`); e.status = 502; throw e; }
+  let raw;
+  try { raw = extractJson(r.text); } catch (e) { const err = new Error(`LLM输出无法解析: ${e.message}`); err.status = 502; throw err; }
+  const v = validateJudge(raw);
+  if (!v.ok) { const err = new Error(`LLM输出校验未通过: ${v.error}`); err.status = 502; throw err; }
+  return { ...v.judge, source_id: a.id, target_id: b.id, source_name: a.name, target_name: b.name };
+}
+
+module.exports = { computeCoNeighborRecs, buildJudgePrompt, validateJudge, aiJudgeRelation, REL_CATS, CONF_LEVELS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-knowledge-graph",
-  "version": "1.8.1",
+  "version": "1.10.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: '',          // 关系置信度过滤：''=全部 | 确证 | 推测 | 存疑
@@ -588,9 +589,11 @@ function renderInfoCard() {
         <button onclick="focusEgo(${e.id})">以此为中心</button>
         <button onclick="askPath(${e.id}, '${escapeHtml(e.name).replace(/'/g, "\\'")}')">查路径</button>
         <button onclick="loadSimilar(${e.id})">相似实体</button>
+        <button onclick="loadEntityRecs(${e.id})">推荐关系</button>
         <button onclick="$('entity-img-input').click()">绑图片</button>
       </div>
       <div id="similar-box"></div>
+      <div id="rec-box"></div>
       <div class="btns"><button onclick="editEntity(${e.id})">编辑</button><button class="danger" onclick="delEntity(${e.id})">删除</button></div>`;
     card.style.display = 'block';
     if (imgCount > 0 && !imgs) loadEntityImages(e.id);
@@ -623,6 +626,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 +639,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 +749,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 +763,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 +803,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 +856,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);
@@ -1042,10 +1086,100 @@ async function loadSimilar(id) {
 }
 window.loadSimilar = loadSimilar;
 
+/* ================= 关系推荐（共同邻居 + AI判断） ================= */
+const judgeCache = new Map(); // 'a|b' -> judge结果（本会话内复用，避免重复调LLM）
+
+// 单条候选的展开渲染：AI判断按钮 → 判断结果 → 采纳入库
+function recRowHtml(rec, boxId) {
+  const key = `${rec.source_id}|${rec.target_id}`;
+  const id = `${boxId}-${key.replace(/\|/g, '_')}`;
+  return `<div class="kv" style="padding:6px 0;border-top:1px dashed #2a3a55" id="row-${id}">
+    <span style="cursor:pointer;color:#7fd1ff" onclick="focusEntity(${rec.source_id})">${escapeHtml(rec.source_name)}</span>
+    <b style="color:#c792ea"> ⇄? </b>
+    <span style="cursor:pointer;color:#7fd1ff" onclick="focusEntity(${rec.target_id})">${escapeHtml(rec.target_name)}</span>
+    <span style="color:#8fa3c0;font-size:11px">共同邻居${rec.common_count}：${escapeHtml((rec.common_names || []).join('、'))}　AA ${rec.score}</span>
+    <div style="margin-top:4px"><button class="ghost" onclick="aiJudgeRec(${rec.source_id},${rec.target_id},'${id}')">AI 判断</button></div>
+    <div id="jr-${id}"></div>
+  </div>`;
+}
+
+async function aiJudgeRec(sourceId, targetId, rowId) {
+  const box = $('jr-' + rowId);
+  if (!box) return;
+  const key = `${sourceId}|${targetId}`;
+  if (judgeCache.has(key)) { renderJudge(box, judgeCache.get(key), rowId); return; }
+  box.innerHTML = '<div class="kv" style="color:#8fa3c0">AI 判断中…（约10-30秒）</div>';
+  try {
+    const j = await api('/api/recommend/ai', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ source_id: sourceId, target_id: targetId }) });
+    judgeCache.set(key, j);
+    renderJudge(box, j, rowId);
+  } catch (e) { box.innerHTML = `<div class="kv" style="color:#e0a768">判断失败：${escapeHtml(e.message)}</div>`; }
+}
+window.aiJudgeRec = aiJudgeRec;
+
+function renderJudge(box, j, rowId) {
+  if (!j.has_relation) { box.innerHTML = '<div class="kv" style="color:#8b949e">AI 判断：无明显关系可录</div>'; return; }
+  const confColor = { '确证': '#7ee787', '推测': '#e0a768', '存疑': '#8b949e' }[j.confidence] || '#8fa3c0';
+  box.innerHTML = `<div class="kv" style="background:#1a2332;border-radius:6px;padding:6px">
+    建议关系：<b style="color:#7ee787">${escapeHtml(j.name)}</b>
+    <span class="tag" style="color:${confColor};border-color:${confColor}55">${j.category}·${j.confidence}</span>
+    <div style="color:#8fa3c0;font-size:11px">依据：${escapeHtml(j.evidence || '（无）')}</div>
+    <div style="margin-top:4px"><button class="primary" onclick="acceptRec(${j.source_id},${j.target_id},'${rowId}')">采纳入库</button></div>
+  </div>`;
+}
+window.acceptRec = acceptRec;
+
+async function acceptRec(sourceId, targetId, rowId) {
+  const judge = judgeCache.get(`${sourceId}|${targetId}`);
+  if (!judge || !judge.has_relation) { toast('判断结果已失效，请重新AI判断', true); return; }
+  try {
+    await api('/api/relations', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({
+      source_id: sourceId, target_id: targetId, name: judge.name, category: judge.category, confidence: judge.confidence,
+      source_ref: 'AI推荐: ' + (judge.evidence || '共同邻居推荐'),
+    }) });
+    toast(`已录入关系「${judge.name}」`);
+    const row = $('row-' + rowId);
+    if (row) row.remove();
+  } catch (e) { toast(e.message, true); }
+}
+
+function renderRecList(recs, boxId, emptyText) {
+  const box = $(boxId);
+  if (!box) return;
+  box.innerHTML = recs.length
+    ? recs.map((r) => recRowHtml(r, boxId)).join('')
+    : `<div class="kv">${emptyText}</div>`;
+}
+
+async function scanRecs() {
+  const btn = $('rc-scan');
+  btn.disabled = true;
+  $('rc-status').textContent = '扫描中…';
+  try {
+    const r = await api('/api/recommend?limit=20');
+    $('rc-status').textContent = `${r.recommendations.length} 条候选`;
+    renderRecList(r.recommendations, 'rc-list', '无可推荐候选（共同邻居≥2且无直接边的实体对）');
+  } catch (e) { $('rc-status').textContent = e.message; }
+  btn.disabled = false;
+}
+$('rc-scan').addEventListener('click', scanRecs);
+
+async function loadEntityRecs(id) {
+  const box = $('rec-box');
+  if (!box) return;
+  box.innerHTML = '<div class="kv">候选关系计算中…</div>';
+  try {
+    const r = await api(`/api/recommend?center=${id}&limit=10`);
+    renderRecList(r.recommendations, 'rec-box', '暂无候选（该实体2跳内无共同邻居≥1的无边实体对）');
+  } catch (e) { box.innerHTML = `<div class="kv" style="color:#e0a768">${escapeHtml(e.message)}</div>`; }
+}
+window.loadEntityRecs = loadEntityRecs;
+
 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 +2154,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 +2245,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>
@@ -114,6 +117,11 @@
           <div class="row"><button class="primary" id="s-run">检索</button><span id="s-mode" style="font-size:11px;color:#8fa3c0;align-self:center"></span></div>
           <div id="s-results"></div>
         </div>
+        <div class="card">
+          <h3>关系推荐（共同邻居 + AI 判断）</h3>
+          <div class="row"><button class="primary" id="rc-scan">扫描全图推荐</button><span id="rc-status" style="font-size:11px;color:#8fa3c0;align-self:center"></span></div>
+          <div id="rc-list"></div>
+        </div>
         <div class="card">
           <h3>关系查询（迷你Cypher，只读）</h3>
           <textarea id="c-query" placeholder="MATCH (a)-[r:互动]->(b) WHERE a.name contains 郑和 RETURN a.name, r.name, b.name LIMIT 10"></textarea>
@@ -246,12 +254,13 @@
           <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>：共同邻居找"该连没连"的实体对（检索页签"关系推荐"卡 / 实体卡"推荐关系"按钮），AI 判断后一键采纳入库</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

@@ -10,6 +10,7 @@ const rdf = require('./lib/rdf');
 const agent = require('./lib/agent');
 const V = require('./lib/validator');
 const inference = require('./lib/inference');
+const recommend = require('./lib/recommend');
 const embeddings = require('./lib/embeddings');
 const askLib = require('./lib/ask');
 const updater = require('./lib/updater');
@@ -317,11 +318,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()));
@@ -353,6 +413,45 @@ api.get('/inference', (req, res) => {
 
 api.get('/ontology', (req, res) => res.json(inference.loadOntology()));
 
+// ---------- 关系推荐（共同邻居 + LLM判断） ----------
+api.get('/recommend', (req, res) => {
+  const g = db.getGraph();
+  const center = String(req.query.center || '').trim();
+  const opts = { limit: Number(req.query.limit) || 20 };
+  if (center) {
+    let cid = null;
+    if (/^\d+$/.test(center)) cid = Number(center);
+    else {
+      const cands = g.entities.filter((e) => e.name === center);
+      if (cands.length === 1) cid = cands[0].id;
+      else if (cands.length > 1) return res.status(409).json({ error: `实体名"${center}"存在${cands.length}个候选，请改用id`, candidates: cands.map((h) => ({ id: h.id, name: h.name, category: h.category })) });
+    }
+    if (cid && !g.entities.some((e) => e.id === cid)) return res.status(404).json({ error: `实体"${center}"不存在` });
+    if (cid) opts.centerId = cid;
+  }
+  res.json({ recommendations: recommend.computeCoNeighborRecs(g, opts) });
+});
+
+// LLM判断候选关系：只给建议，入库由前端确认后走人工接口
+api.post('/recommend/ai', async (req, res) => {
+  if (agentBusy) return res.status(429).json({ error: '已有AI任务执行中（问答、导入或智能检索），请稍后再试' });
+  const body = req.body || {};
+  const g = db.getGraph();
+  const byId = new Map(g.entities.map((e) => [e.id, e]));
+  const a = byId.get(Number(body.source_id));
+  const b = byId.get(Number(body.target_id));
+  if (!a || !b) return res.status(404).json({ error: '待判断的实体不存在' });
+  agentBusy = true;
+  try {
+    const judge = await recommend.aiJudgeRelation({ a, b, common_names: body.common_names });
+    res.json(judge);
+  } catch (e) {
+    res.status(e.status || 500).json({ error: e.message });
+  } finally {
+    agentBusy = false;
+  }
+});
+
 // ---------- 向量混合检索 ----------
 api.get('/embeddings/status', (req, res) => res.json(embeddings.status()));
 
@@ -371,6 +470,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();