local-knowledge-graph 1.5.0

package/.opencode/skill/kg-triples/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: kg-triples
+description: 将文本、文章或文档科学系统地转化为RDF三元组（含属性）并融合进入本地知识图谱。当用户要求"文本转三元组"、"文档建图"、"知识抽取"、"把这篇文章导入知识图谱"、"抽取实体关系"等任务时使用本技能。
+---
+
+# 文本/文档 → 三元组抽取技能
+
+按五段流水线处理用户提供的文本或文档附件。所有产出以 kg-ops 协议输出，由本地程序做 RDF 校验与原子入库，禁止直接操作数据库文件。
+
+## 第一步：预处理与分块
+
+1. 获取文本：用户粘贴的正文或附件（PDF/Word 等先提取纯文本，保留章节结构）
+2. 清洗：去掉页眉页脚、水印、乱码、参考书目噪音
+3. 识别标题层级与文体：叙事文（历史/新闻）以事件为核心；说明文/百科以实体-属性为主；表格按"行=实体、列=属性键"映射；技术文档关注概念层级
+4. 分块：按语义单元（小节/段落）切为 300-800 字的块，块间保留一句重叠；逐块处理，每块独立输出一个 kg-ops 代码块
+
+## 第二步：逐块抽取
+
+- 全量识别候选知识元素：人名、地名、机构、概念、事件、作品、数值、时间表达
+- 实体四大类判定：物理可感的存在 → 物理实体；观念/事件/作品/领域 → 抽象实体；量值作为关系端点 → 数值实体；时间作为关系端点 → 时间实体
+- 建模铁律：仅作描述说明的年份、日期、数量（成立年份、测量年份、海拔、人口）一律写入所属实体的 attributes，禁止为它们单独建节点
+- 属性：扁平键值对，值为字符串/数值/布尔，禁止嵌套
+- 关系：识别谓词（动词/系词/介词结构），对齐主语宾语，产出（主语, 谓词, 宾语）候选
+
+## 第三步：规范化
+
+- 命名全称优先、统一译名；同义实体合并为一个节点，原名称收进"别名"属性
+- 同名歧义靠上下文与属性区分，必要时加限定符（如"李白（诗人）"）
+- 谓词使用规范词：位于/属于/发生于/参与/包含/创作/国籍/推动发展 等，同义谓词归一（"坐落于"→"位于"）
+- 关系大类固定五选一：空间 / 互动 / 归属 / 时间 / 属性
+- 数值单位统一换算、日期统一格式
+
+## 第四步：融合（对齐已有图谱）
+
+- 每块抽取前先对照提示词中的"当前图谱"摘要：已存在的实体直接用其真实 id 引用（source_id/target_id），禁止重复创建同名实体
+- 本次新增的实体用 ref 占位符（如 "ref":"A"），同一块内后续关系用 source_ref/target_ref 引用
+- 与已有知识矛盾的信息：创建/更新时在 attributes 中加"来源"键标注文档名与原文表述，并在说明中提示用户裁决；禁止擅自覆盖或删除已有知识
+- 从文档新建的实体建议带"来源"属性记录出处文档名，保证可追溯
+
+## 第五步：输出协议
+
+- 先输出简短中文抽取报告：本块新建实体数、复用实体数、关系数、存疑项清单
+- 每个处理块输出一个 kg-ops 代码块（一次回复可含多个代码块），格式：
+
+````
+```kg-ops
+[
+  {"op":"add_entity","ref":"A","name":"实体名","category":"物理实体","attributes":{"来源":"xx文档"}},
+  {"op":"add_relation","source_ref":"A","target_id":3,"name":"位于","category":"空间"},
+  {"op":"update_entity","id":5,"attributes":{"别名":"某某"}}
+]
+```
+````
+
+- 底线原则：宁可漏抽并在说明中列出存疑项，也不硬造三元组；每条知识必须能回指原文位置

package/HELP.md

@@ -0,0 +1,112 @@
+# 本地知识图谱整合器 · 帮助
+
+把文档与联网信息整理成可导航的 3D 知识图谱。全流程本地运行，图谱数据、图片、API Key 全部保存在本机数据目录（npm 安装模式在 `~/.local-knowledge-graph/`，Git 克隆模式在项目内 `data/`），代码仓库不包含任何用户数据。
+
+## 查看当前版本
+
+- 网页端：页头「**视图设置**」面板底部，或页头「**帮助**」面板的"版本与更新"区域，显示当前版本号
+- 命令行：`node -e "console.log(require('./package.json').version)"`
+
+## 检查更新 / 一键更新
+
+1. 打开页头「**帮助**」面板（或「视图设置」面板底部）的"版本与更新"区域
+2. 点击「**检查更新**」—— 应用会连接 GitHub 对比本地与远端版本，并显示最新发布说明
+3. 若有新版本，点击「**一键更新**」—— 应用自动下载更新并重启服务，页面随后自动刷新
+
+注意事项：
+
+- 一键更新要求应用目录是本仓库的 Git 克隆（默认安装方式即是），且本地没有未发布的代码改动
+- 更新只替换程序代码；`data/` 目录（图谱数据、图片、配置）完全不受影响
+- 若自动重启失败，关闭窗口后重新运行启动脚本即可（`start.bat` / `start.command` / `bash start.sh`）
+
+## 手动更新（备用方式）
+
+npm 安装模式：
+
+```bash
+npm i -g local-knowledge-graph@latest
+```
+
+Git 克隆模式：
+
+```bash
+cd 项目目录
+git pull --ff-only origin master
+```
+
+然后重新启动应用。
+
+## 启动方式
+
+**npm 安装（推荐）**：
+
+```bash
+npm i -g local-knowledge-graph
+kg
+```
+
+数据保存在用户目录 `~/.local-knowledge-graph/`（Windows 在 `C:\Users\你\.local-knowledge-graph`），升级与卸载程序均不影响数据。也可 `npx local-knowledge-graph` 免安装试用。
+
+**脚本启动（Git 克隆模式）**：
+
+| 平台 | 方式 |
+| ---- | ---- |
+| Windows | 双击 `start.bat` |
+| macOS | 双击 `start.command` |
+| Linux / 命令行 | `bash start.sh` 或 `npm start` |
+
+此模式数据存放在项目内 `data/` 目录。启动后浏览器访问 `http://localhost:3000`。依赖 Node.js >= 22.5；自然语言补全需要全局安装 `opencode` CLI（`npm i -g opencode-ai`），未安装时仅该功能降级，其余功能正常。
+
+## API Key 配置（全部在界面上完成）
+
+程序自身零内置密钥，所有需要 key 的能力都在界面上自由配置：
+
+- **语义检索 / 智能提问综述**：检索页签"语义检索配置"填入 API Key（默认硅基流动 BAAI/bge-m3，可换任意 OpenAI 兼容接口的 Base URL 与模型）。Key 仅存本地数据目录的 settings.json，服务端永不回传真实值。不配置则自动退化为关键词检索，其余功能不受影响。
+- **OpenCode（AI 对话建图 / 智能提问编译）**：使用 opencode CLI 自身的认证（`opencode auth login`），应用不经手密钥。未安装或未认证时仅这两个功能降级。
+- 更换数据目录（`kg --data <目录>`）会使用该目录下的独立配置，互不串扰。
+
+## 功能速览
+
+- **AI 对话建图**：右侧输入自然语言指令（联网补全），或上传文档（md/txt/pdf/docx）批量抽取三元组
+- **智能提问**：检索页签一句话找关系（LLM 编译检索计划，本地只读执行，可生成带引用的综述）
+- **语义检索**：配置硅基流动 API Key 后支持语义+关键词混合检索（未配置时自动退化为关键词模式）
+- **最短路径 / 中心子图 / 推理**：挖掘实体间关联链路、层级范围与隐性关系
+- **撤销**：Ctrl+Z 或按钮，可连续撤销
+- **保存点与回溯**：版本页签打保存点，随时回滚；每次保存点自动滚动备份到 `data/backups/`
+- **图片绑定**：实体信息卡上传本地图片
+- **导出**：RDF(Turtle)、整库 .db、单文件只读网页版
+
+## 键盘快捷键
+
+| 快捷键 | 功能 |
+| ------ | ---- |
+| Ctrl+F | 聚焦搜索框 |
+| Ctrl+Z | 撤销最近操作 |
+| Delete | 删除选中实体/关系 |
+| Esc | 逐层关闭面板 / 取消选中 |
+
+## 常见问题
+
+**Q：打开页面是空白？**
+用现代浏览器（Chrome/Edge/Safari 最新版）；确认服务已启动且端口未被占用。
+
+**Q：OpenCode 检测未就绪？**
+运行 `npm i -g opencode-ai` 安装后重启应用；OpenCode 仅用于自然语言补全与智能提问的编译环节。
+
+**Q：数据会上传到云端吗？**
+图谱数据只存在本机。仅当你在"检索"页签配置了语义检索 API Key 时，检索向量化的文本片段才会发往你配置的模型服务；OpenCode 补全公开知识时按其自身机制联网。其余全部本地完成。
+
+**Q：如何回滚某次误操作？**
+优先用「撤销」（可连续）；需要回到更早状态时在"版本"页签回溯到对应保存点。
+
+## 版本历史摘要
+
+- **v1.5.0**：npm 包化（`npm i -g local-knowledge-graph` + `kg` 一键安装启动）；数据目录迁至用户目录（升级无损）；应用内更新支持 npm 与 git 双模式
+
+- **v1.4.0**：设置与帮助面板内置版本号、检查更新、一键更新；项目目录新增本帮助文档
+- **v1.3.0**：智能关系检索（自然语言提问 → 检索计划 → 关联发现 → 综述）
+- **v1.2.0**：连续撤销、最短路径查询、日志筛选、悬浮提示、键盘快捷键
+- **v1.1.0**：向量库拆分、导入去重加固、AI 任务互斥、聚焦飞行、日志人话渲染、推理持久化、单文件网页导出、移动端适配、一键启动脚本
+- **v1.0.0**：首版——三表数据模型、3D 可视化、RDF 校验、Git 保存点/回溯、文档导入、OWL 推理、MCP Server
+
+完整发布说明见 [GitHub Releases](https://github.com/iamsamyiok/local-knowledge-graph/releases)。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamsamyiok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# 本地知识图谱整合器
+
+全本地运行的个人知识图谱工具：3D 可视化、AI 文档导入、OWL 推理、向量混合检索、Git 级保存点、MCP Server。数据始终存放在本机 SQLite 中。
+
+## 适用场景
+
+- **个人知识管理**：读书笔记、学习摘录沉淀为可检索、可视化的关系网络，越用越密
+- **研究与考证**：人物、事件、地点、时间线的梳理与追溯（历史考据、家谱、案件梳理、情报分析）
+- **创作设定库**：小说、剧本、游戏世界观的角色关系、组织架构、地理设定统一管理
+- **文档资产化**：批量导入 Markdown / PDF / Word，AI 自动抽取实体关系，零手工建库
+- **离线分享**：单文件 HTML 查看器发给他人浏览器直接打开；整库 .db 一键交接
+
+## 功能总览
+
+| 模块 | 说明 |
+|------|------|
+| 3D 可视化 | three.js 力导向布局，实体按 4 大类区分形状/颜色，关系按 5 大类区分线型；支持中心层级视图（可调层数）、视图主题自定义、实体图片绑定与灯箱 |
+| AI 文档导入 | 调用 OpenCode CLI 将 Markdown/PDF/Word 等文档抽取为三元组并自动导入（分块+保存点对齐，防重复导入） |
+| OWL 推理 | 按 传递/对称/逆 三类规则动态推导隐性关系（不入库），可配置 data/ontology.json，前端一键叠加显示并可查看推导链 |
+| 混合检索 | 语义向量（默认硅基流动 BAAI/bge-m3，可换任意 OpenAI 兼容接口）+ 关键词检索，RRF 融合排序 |
+| 迷你 Cypher | 只读关系查询：`MATCH (a)-[r:互动]->(b) WHERE a.name contains 郑和 RETURN a.name, r.name LIMIT 10` |
+| 数据资产 | 实体图片（本地存储，独立表）、RDF Turtle 导出、SQLite 整库导出/导入（自动备份保存点）、单文件只读网页另存 |
+| 保存点 | 每次合规写入自动打 Git 保存点，违规写入自动回滚到上个合规版本；可一键回溯任意历史版本 |
+| MCP Server | 零依赖 stdio JSON-RPC，10 个工具可直接接入 Claude Desktop / OpenCode 等支持 MCP 的客户端 |
+| 双端适配 | 桌面端完整面板；手机端单行工具栏+抽屉面板+文件菜单 |
+
+## 快速开始
+
+环境要求：Node.js >= 22.5（使用内置 node:sqlite），Windows / macOS / Linux 均可，无需数据库安装。
+
+### npm 安装（推荐）
+
+```bash
+npm i -g local-knowledge-graph
+kg
+```
+
+一条命令安装，一条命令启动（自动打开浏览器）。数据保存在用户目录 `~/.local-knowledge-graph/`，升级（`kg` 内一键更新或 `npm i -g local-knowledge-graph@latest`）不影响数据。也可以免安装试用：`npx local-knowledge-graph`。
+
+启动参数：`kg --port 3000 --host 127.0.0.1 --data <目录> --no-open`（详见 `kg --help`）。
+
+### 脚本启动（Git 克隆 / 开发模式）
+
+| 平台 | 操作 |
+|------|------|
+| Windows | 双击 `start.bat` |
+| macOS | 双击 `start.command`（若提示无法打开：右键 → 打开；若提示无执行权限：终端执行一次 `chmod +x start.command start.sh`） |
+| Linux | `./start.sh`（首次可能需 `chmod +x start.sh`） |
+
+脚本自动完成：Node 版本检查 → 首次自动安装依赖（仅 express，几秒）→ 启动服务 → 自动打开浏览器 `http://localhost:3000`。此模式数据存放在项目内 `data/` 目录，应用内"一键更新"走 git 快进拉取。
+
+### 手动启动
+
+```bash
+# 环境要求：Node.js >= 22.5（使用内置 node:sqlite）
+npm install
+
+# 启动（默认 http://localhost:3000）
+npm start
+```
+
+AI 导入功能需要安装 [OpenCode CLI](https://opencode.ai) 并配置可用模型；其余功能（可视化/推理/检索配置/导出/MCP）无外部依赖。
+
+## 目录结构
+
+```
+server.js            Express 服务与全部 API
+lib/db.js            SQLite 三表核心（entities/relations/operation_logs）+ 图片表 + 向量表 + 迷你Cypher
+lib/validator.js     手工/AI 共用的合规校验（违规即整体拒绝，库保持上个合规版本）
+lib/agent.js         OpenCode CLI 封装（普通问答与文档导入两种模式）
+lib/git.js           data/ 目录 Git 保存点（差量提交与回溯）
+lib/inference.js     OWL 推理引擎（虚拟推导，不写库）
+lib/embeddings.js    向量构建/检索（data/settings.json 存配置，已被 gitignore）
+lib/rdf.js           RDF Turtle 导出
+lib/viewer.js        单文件只读网页查看器生成
+mcp/server.js        MCP Server（stdio）
+tools/ego.js         中心层级查询 CLI（只读）
+public/index.html    单文件前端（无构建步骤）
+data/                kg.db、ontology.json、settings.json、uploads/（gitignore，不出仓库）
+vendor/              three.js 本地副本（全离线）
+```
+
+## 数据模型
+
+三张严格字段表 + 两张资产表：
+
+- `entities(id, name, category, attributes, source, created_at)` — category 枚举：物理实体/抽象实体/数值实体/时间实体，attributes 为扁平 JSON
+- `relations(id, source_id, target_id, name, category, created_at)` — category 枚举：归属/空间/时间/互动/属性
+- `operation_logs(id, op_type, snapshot, source, created_at)` — 全部写入留痕，snapshot 为操作前后JSON快照
+- `entity_images` / `entity_embeddings` — 图片与向量资产，不进入图谱保存点语义
+
+## API 一览（http://localhost:3000/api）
+
+```
+GET  /meta                     版本与计数
+GET/POST /entities             实体 CRUD（PUT/DELETE /entities/:id）
+GET/POST /relations            关系 CRUD（PUT/DELETE /relations/:id）
+GET  /graph                    全图（含图片计数）
+GET  /graph/ego?center=&depth= 中心层级子图（depth 省略或 0 = 全部层级）
+GET  /inference?center=        推理关系（含推导依据与规则）
+GET/PUT /ontology              推理规则配置
+GET/PUT /embeddings/settings   检索配置（密钥不回传）
+POST /embeddings/build         构建全量实体向量
+POST /search                   混合检索 {query, top_k}
+POST /cypher                   迷你 Cypher {query}
+GET/POST /entities/:id/images  图片绑定（DELETE /images/:imgId）
+POST /agent                    OpenCode 问答+kg-ops 写入
+POST /agent/doc                文档批量导入（分块+保存点对齐）
+GET/POST /git/history|savepoint|restore  保存点
+GET  /export/rdf               RDF Turtle
+GET  /export/db?name=          SQLite 整库导出
+POST /graph/import             SQLite 整库导入（自动备份+校验）
+GET  /export/html              单文件只读网页
+```
+
+## kg-ops 写入协议
+
+AI 回答中输出 ```kg-ops 代码块（JSON 数组）即可写库，全部操作过校验、留日志、打保存点：
+
+```json
+[
+  {"op":"add_entity","ref":"A","name":"大雁塔","category":"物理实体","attributes":{"朝代":"唐"}},
+  {"op":"add_relation","source_ref":"A","target_id":58,"name":"位于","category":"空间"}
+]
+```
+
+支持操作：`add_entity / update_entity / delete_entity / add_relation / update_relation / delete_relation`。
+
+## MCP 接入
+
+`mcp/server.js` 零外部依赖，stdio 传输。以 Claude Desktop 为例（`claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "local-kg": {
+      "command": "node",
+      "args": ["/absolute/path/to/local-knowledge-graph/mcp/server.js"],
+      "env": { "KG_MCP_READONLY": "1" }
+    }
+  }
+}
+```
+
+工具列表：`kg_stats / kg_list_entities / kg_get_entity / kg_get_graph / kg_ego / kg_search / kg_cypher / kg_inference / kg_export_rdf / kg_apply_ops`。设 `KG_MCP_READONLY=1` 时拒绝全部写入。
+
+## 向量检索配置
+
+打开前端"检索"页签，填入硅基流动（或任意 OpenAI 兼容 /embeddings 接口）的 API Key 后保存，点击"构建全量向量"。配置仅存本机 `data/settings.json`（该目录已被 .gitignore 排除）。
+
+## CLI：中心层级查询
+
+```bash
+node tools/ego.js "郑和"        # 全部层级
+node tools/ego.js "郑和" 2      # 2 层内
+node tools/ego.js --json 3 郑和 # JSON 输出
+```
+
+退出码：0 成功 / 1 未找到 / 2 名称多义（附候选） / 3 参数错误。
+
+## 隐私与安全
+
+- 除 AI 导入/问答需联网调用 OpenCode 外，其余功能完全离线
+- `data/`（数据库、密钥、图片）与 `node_modules/` 均不出仓库
+- 前端密钥输入框不回传真实值，服务端只存本地文件

package/bin/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+'use strict';
+
+// local-knowledge-graph 命令行入口
+// 用法: kg [--port 3000] [--host 127.0.0.1] [--data <目录>] [--no-open] [-v|--version] [-h|--help]
+
+const args = process.argv.slice(2);
+
+function argValue(name, short) {
+  const i = args.indexOf(name);
+  const j = short ? args.indexOf(short) : -1;
+  const idx = i >= 0 ? i : j;
+  return idx >= 0 ? args[idx + 1] : undefined;
+}
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`本地知识图谱整合器 (local-knowledge-graph)
+
+用法:
+  kg [选项]
+
+选项:
+  --port <n>      服务端口（默认 3000，环境变量 PORT 同效）
+  --host <addr>   监听地址（默认 127.0.0.1，局域网访问用 0.0.0.0，环境变量 KG_HOST 同效）
+  --data <dir>    数据目录（默认 ~/.local-knowledge-graph，环境变量 KG_DATA_DIR 同效）
+  --no-open       启动后不自动打开浏览器
+  -v, --version   显示版本
+  -h, --help      显示本帮助
+
+数据说明: 图谱数据、图片、API Key 全部保存在本地数据目录，升级卸载均不影响。`);
+  process.exit(0);
+}
+
+if (args.includes('-v') || args.includes('--version')) {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
+const { ensureLegacyMigration, isDevRepo } = require('../lib/paths');
+
+const port = argValue('--port');
+const host = argValue('--host');
+const dataDir = argValue('--data');
+if (port) process.env.PORT = port;
+if (host) process.env.KG_HOST = host;
+if (dataDir) process.env.KG_DATA_DIR = dataDir;
+
+ensureLegacyMigration();
+
+// 启动后轮询就绪，自动打开浏览器
+if (!args.includes('--no-open')) {
+  const listenPort = Number(process.env.PORT || 3000);
+  const url = `http://localhost:${listenPort}`;
+  const started = Date.now();
+  const timer = setInterval(() => {
+    fetch(`${url}/api/version`, { signal: AbortSignal.timeout(1500) })
+      .then((r) => {
+        if (r.ok || Date.now() - started > 20000) {
+          clearInterval(timer);
+          if (r.ok) {
+            console.log(`已在浏览器打开 ${url}（如未弹出请手动访问）`);
+            openBrowser(url);
+          }
+        }
+      })
+      .catch(() => { if (Date.now() - started > 25000) clearInterval(timer); });
+  }, 800);
+}
+
+function openBrowser(url) {
+  const { spawn } = require('child_process');
+  const cmds = process.platform === 'win32' ? [['cmd', ['/c', 'start', '', url]]]
+    : process.platform === 'darwin' ? [['open', [url]]]
+    : [['xdg-open', [url]]];
+  try {
+    const [cmd, cargs] = cmds[0];
+    spawn(cmd, cargs, { detached: true, stdio: 'ignore' }).unref();
+  } catch (_) { /* 打不开就让用户手动访问 */ }
+}
+
+require('../server.js');
+
+// 开发仓库模式提示数据位置（npm模式由 server bootstrap 迁移逻辑打印）
+if (isDevRepo()) {
+  console.log('[开发模式] 检测到Git仓库，数据目录使用项目内 ./data');
+}

package/lib/agent.js

@@ -0,0 +1,211 @@
+'use strict';
+
+// OpenCode进程管理：后端默认拉起OpenCode进程，前端自然语言指令直接传递执行。
+// OpenCode仅负责理解指令与联网补全，所有写库动作必须经本进程RDF校验后落库，禁止直连数据库。
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const { APP_ROOT, DATA_DIR } = require('./paths');
+const SESSION_FILE = path.join(DATA_DIR, '.agent_session');
+const TIMEOUT_MS = Number(process.env.AGENT_TIMEOUT_MS || 300000);
+
+function readSession() {
+  try { return fs.readFileSync(SESSION_FILE, 'utf8').trim() || null; } catch (_) { return null; }
+}
+
+function writeSession(id) {
+  if (id) fs.writeFileSync(SESSION_FILE, id);
+}
+
+// 构建Agent提示词：注入图谱摘要、RDF规范、输出协议
+function buildPrompt(instruction) {
+  const database = require('./db');
+  const graph = database.getGraph();
+  const entLines = graph.entities.map((e) => {
+    let attrs = {};
+    try { attrs = JSON.parse(e.attributes || '{}'); } catch (_) {}
+    const a = Object.keys(attrs).length ? ` 属性:${JSON.stringify(attrs)}` : '';
+    return `- id=${e.id} "${e.name}" [${e.category}]${a}`;
+  }).join('\n');
+  const relLines = graph.relations.map((r) => `- id=${r.id} e${r.source_id} --(${r.category}/${r.name})--> e${r.target_id}`).join('\n');
+
+  return `你是本地知识图谱的管理助手，通过OpenCode进程运行。你可以使用联网搜索补全公开信息，但必须遵守：
+
+【铁律】
+1. 本地图谱数据只增不删（除非用户明确要求删除/修改）。
+2. 联网补全的信息必须经过你核对（交叉验证可信来源）后才允许写入；无法核实的不要写入，并在说明中告知用户原因。
+3. 禁止向任何外部服务上传或泄露本地图谱的私有数据；联网时只查询公开信息。
+
+【当前图谱】
+实体 ${graph.entities.length} 个：
+${entLines || '（空）'}
+关系 ${graph.relations.length} 条：
+${relLines || '（空）'}
+
+【RDF规范（必须严格遵守）】
+- 实体大类只能是: 物理实体 / 抽象实体 / 数值实体 / 时间实体
+- 关系大类只能是: 空间 / 互动 / 归属 / 时间 / 属性
+- 实体属性(attributes)必须是扁平JSON对象，值为字符串/数值/布尔，禁止嵌套对象或数组
+- 关系的 source/target 只能引用已存在实体id，或用ref占位符引用本次新增的实体
+- 建模准则：数值实体/时间实体仅在"数值或时间作为某条关系的端点"时才创建（如"事件—发生于→744年"）；仅作描述说明的年份、日期、数量（如成立年份、测量年份、海拔、人口）一律写入所属实体的attributes，禁止为它们单独建节点
+
+【本地查询工具】
+- 需要聚焦某个实体的关联范围（直接或间接关系）时，运行只读命令：node tools/ego.js "<实体名或id>" [层数]
+  输出该中心 N 层内的实体（按层级分组）与关系；层数省略表示全部层级。该命令仅本地读库，无需联网。
+- 需要按关键词或关系模式检索时，运行只读命令：
+  node tools/search.js keyword "<关键词>" [数量]（名称/属性关键词检索，附每个实体的关系列表）
+  node tools/search.js cypher "MATCH (a)-[r:互动]->(b) WHERE a.name contains 词 RETURN a,r,b LIMIT 20"（按关系类型/名称与实体条件检索）
+  建议先用 keyword 找到实体名，再用 cypher 按关系类型展开。
+- 需要挖掘隐性/间接关系（如"大雁塔和长安有什么联系"）时，运行只读命令：node -e "const{computeInferred}=require('./lib/inference');const db=require('./lib/db');const g=db.getGraph();console.log(JSON.stringify(computeInferred(g),null,1))"
+  该推理引擎按OWL传递/对称/逆规则推导库中未显式存储的关系（含推导依据）。也可访问 http://localhost:3000/api/inference 获取同样结果。回答时请区分"库中显式关系"与"推理得出的隐性关系"。
+
+【输出协议】
+第一步：用简洁中文说明你的分析与结论（若涉及联网信息，注明来源可信度）。
+第二步：如需修改图谱，输出一个 \`\`\`kg-ops 代码块，内容为JSON数组（仅这一种操作格式），元素形如：
+  {"op":"add_entity","ref":"A","name":"实体名","category":"物理实体","attributes":{"键":"值"}}
+  {"op":"add_relation","source_ref":"A","target_id":3,"name":"关系名","category":"归属"}
+  {"op":"update_entity","id":5,"attributes":{"键":"新值"}}
+  {"op":"delete_entity","id":7}
+  {"op":"update_relation","id":2,"name":"新名"}
+  {"op":"delete_relation","id":4}
+  （source_id/target_id用数字id引用已有实体；本次新增的实体用ref占位符，如"ref":"A"供后续关系引用）
+第三步：若无任何图谱修改，省略代码块。
+
+【用户指令】
+${instruction}`;
+}
+
+// 从输出中提取全部 kg-ops 代码块（文档分块抽取时一次回复可含多个块）
+function parseOps(output) {
+  const re = /```kg-ops\s*([\s\S]*?)```/g;
+  const ops = [];
+  let parse_error = null;
+  let m;
+  while ((m = re.exec(output))) {
+    try {
+      const arr = JSON.parse(m[1].trim());
+      if (Array.isArray(arr)) ops.push(...arr);
+      else parse_error = 'kg-ops块必须是JSON数组';
+    } catch (e) {
+      parse_error = `kg-ops块JSON解析失败: ${e.message}`;
+    }
+  }
+  const reply = output.replace(/```kg-ops\s*[\s\S]*?```/g, '').trim();
+  return { ops, reply, parse_error };
+}
+
+// 解析OpenCode JSON事件流：提取文本回复、错误事件与会话id
+function parseEventStream(stdout) {
+  const texts = [];
+  const errors = [];
+  let sessionIdFound = null;
+  for (const line of String(stdout).split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    try {
+      const j = JSON.parse(t);
+      if (j.sessionID && !sessionIdFound) sessionIdFound = j.sessionID;
+      if (j.type === 'text' && j.part && j.part.text) texts.push(j.part.text);
+      const parts = j.parts || (j.message && j.message.parts) || [];
+      for (const p of parts) if (p.type === 'text' && p.text) texts.push(p.text);
+      if (j.type === 'error') {
+        const msg = (j.error && ((j.error.data && j.error.data.message) || j.error.message)) || '未知错误';
+        errors.push(`${msg}${j.error && j.error.data && j.error.data.ref ? `（ref:${j.error.data.ref}）` : ''}`);
+      }
+    } catch (_) { /* 非JSON行，忽略 */ }
+  }
+  return { texts: texts.join('\n'), errors, sessionId: sessionIdFound };
+}
+
+// 拉起OpenCode进程执行指令；服务端错误时自动清除会话并用全新会话重试一次
+// files: 附件路径数组（经 opencode run -f 挂载）
+async function runAgent(instruction, files = []) {
+  if (!instruction || !String(instruction).trim()) {
+    return { ok: false, error: '指令不能为空' };
+  }
+  let result = await attempt(readSession(), String(instruction), files);
+  if (!result.ok && result.retriable && readSession()) {
+    // 会话可能已失效或服务端状态异常，清除后用全新会话重试
+    clearSession();
+    const retry = await attempt(null, String(instruction), files);
+    if (retry.ok) return { ...retry, retried: true };
+    return { ...retry, retried: true, error: `重试仍失败: ${retry.error}` };
+  }
+  return result;
+}
+
+// 底层进程调用：拉起 opencode run --format json，收集事件流（attempt与runPlain共用）
+// preArgs: 位于prompt之前的参数（如 --session）；prompt必须在-f之前（-f是贪婪数组选项）
+function runOpenCodeRaw(preArgs, prompt, files, timeoutMs) {
+  return new Promise((resolve) => {
+    const args = ['run', '--format', 'json', '--auto', ...preArgs, prompt];
+    for (const f of files || []) {
+      if (f && fs.existsSync(f)) args.push('-f', f);
+    }
+
+    let stdout = '', stderr = '', done = false;
+    let child;
+    try {
+      child = spawn('opencode', args, { cwd: APP_ROOT, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      return resolve({ ok: false, error: '无法启动OpenCode进程: ' + e.message });
+    }
+
+    const timer = setTimeout(() => {
+      if (!done) { done = true; try { child.kill('SIGKILL'); } catch (_) {} resolve({ ok: false, error: `OpenCode执行超时(${timeoutMs / 1000}s)，已终止` }); }
+    }, timeoutMs);
+
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (e) => {
+      if (done) return; done = true; clearTimeout(timer);
+      resolve({ ok: false, error: `OpenCode进程启动失败: ${e.message}（请确认 opencode CLI 已安装）` });
+    });
+    child.on('close', (code) => {
+      if (done) return; done = true; clearTimeout(timer);
+
+      if (code !== 0 && !stdout.trim()) {
+        return resolve({ ok: false, error: `OpenCode进程退出码${code}: ${(stderr || '无输出').slice(0, 500)}` });
+      }
+      const ev = parseEventStream(stdout);
+      // 出现error事件：服务端执行失败；保留已产生的部分回复供参考
+      if (ev.errors.length) {
+        return resolve({
+          ok: false,
+          retriable: true,
+          error: `OpenCode执行出错: ${ev.errors[0]}`,
+          partial_reply: ev.texts || null,
+        });
+      }
+      resolve({ ok: true, texts: ev.texts || stdout.trim(), sessionId: ev.sessionId || null });
+    });
+  });
+}
+
+function attempt(sessionId, instruction, files) {
+  const preArgs = sessionId ? ['--session', sessionId] : [];
+  return runOpenCodeRaw(preArgs, buildPrompt(instruction), files, TIMEOUT_MS).then((r) => {
+    if (!r.ok) return r;
+    if (r.sessionId) writeSession(r.sessionId);
+    const replyText = r.texts;
+    const parsed = parseOps(replyText);
+    return { ok: true, reply: parsed.reply || replyText, ops: parsed.ops, parse_error: parsed.parse_error || null, session: readSession() };
+  });
+}
+
+// 纯文本问答模式（智能检索编译/综述用）：无会话、无 kg-ops 解析，仅取回复文本
+async function runPlain(prompt, timeoutMs = 20000) {
+  const p = String(prompt || '').trim();
+  if (!p) return { ok: false, error: 'prompt不能为空' };
+  const r = await runOpenCodeRaw([], p, [], timeoutMs);
+  if (!r.ok) return { ok: false, error: r.error };
+  return { ok: true, text: r.texts || '' };
+}
+
+function clearSession() {
+  try { fs.unlinkSync(SESSION_FILE); } catch (_) { /* 文件不存在则忽略 */ }
+}
+
+module.exports = { buildPrompt, runAgent, runPlain, parseOps, parseEventStream };