@puwenhui/dsh-rag-kb 0.3.0 → 0.3.1

package/README.md

@@ -13,7 +13,8 @@ DSH RAG 知识库插件：**文档导入 → 智能切块 → 本地向量化
 - **会话语义管理**：所有操作（添加/删除/保存/检索）直接在对话里用大白话完成
 - **多格式支持**：pdf / docx / md / txt / csv / json
 - **完全本地**：模型本地运行，数据不出机器
-- **目录自动索引**：配置目录后文件放入/变更自动入库
+- **目录自动索引**：配置目录后，放入/修改的文件自动入库；**DSH 未运行期间放入的也会在下次启动时补扫**，不用管当时开没开
+- **文档原地更新**：同一文件改了内容会**覆盖更新**旧索引（以文件路径为身份），不会在库里留下旧版本
 - **对话内容保存**：把对话中的结论/总结一键存入知识库
 
 ## 版本要求
@@ -73,6 +74,19 @@ dsh plugin --profile web add @puwenhui/dsh-rag-kb
 
 实测效果（13 篇技术/管理文档，114 节）：切成 605 块，**96% 的块带节标题**。
 
+### 索引行为（v0.3.1 起）
+
+| 行为 | 说明 |
+|---|---|
+| 身份标识 | 文档以**文件绝对路径**为 doc_id（非内容），同一文件改了内容走覆盖更新，库里不留旧版本 |
+| 变更检测 | 单独存 `content_hash` 判断内容是否真的变了——未变则跳过，连向量化都不跑 |
+| 启动补扫 | 插件加载时扫描 `watchDir`，把已存在但未入库的文件补索引（`watch` 只捕获建立之后的变动） |
+| 实时监视 | 文件放入/修改后等 2 秒再索引，避免读到半写文件 |
+| 范围限制 | 监视与扫描均为**单层**，不递归子目录；扩展名限 pdf/docx/md/txt/csv/json/log |
+| 旧库兼容 | 自动补 `content_hash` 列；索引时清理同名旧格式记录（`content_hash` 为空的条目） |
+
+> 一次索引 = 一次 `documents` 行 + N 条 `chunks` 行；重复触发不会重复插入，由 doc_id 主键与「先删后插」双重保证。
+
 ## 技术栈
 
 | 层 | 选型 | 说明 |

package/lib/plugin.mjs

@@ -66,7 +66,7 @@ function resolveKbConfig(c = {}) {
 */
 /** 库归属标识（PRAGMA application_id，抄宿主 session-query-sqlite 惯例） */
 const APP_ID = 1380009794;
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 var KbStore = class {
 	db;
 	vectors = [];
@@ -83,6 +83,7 @@ var KbStore = class {
 		this.db.exec(`
       CREATE TABLE IF NOT EXISTS documents(
         doc_id TEXT PRIMARY KEY,
+        content_hash TEXT NOT NULL DEFAULT '',
         name TEXT NOT NULL,
         source TEXT NOT NULL DEFAULT 'upload',
         bytes INTEGER NOT NULL DEFAULT 0,
@@ -106,21 +107,32 @@ var KbStore = class {
         tokenize='trigram'
       );
     `);
+		try {
+			this.db.exec("ALTER TABLE documents ADD COLUMN content_hash TEXT NOT NULL DEFAULT ''");
+		} catch {}
+	}
+	/**
+	* 文件绝对路径 → doc_id：同一路径的文件内容变化时 doc_id 保持不变，
+	* 由 upsertDoc + insertChunks 覆盖更新，不会在库里留下旧版本。
+	* 路径转小写以适配 Windows 大小写不敏感。
+	*/
+	static docIdFromPath(filePath) {
+		return createHash("sha256").update(resolve(filePath).toLowerCase()).digest("hex").slice(0, 16);
 	}
-	/** 文档内容 hash 作 doc_id（同名不同内容=不同文档） */
-	static docId(content) {
+	/** 内容 hash：save 文档以它为 doc_id；文件文档用它判断内容是否变化 */
+	static hashContent(content) {
 		return createHash("sha256").update(content).digest("hex").slice(0, 16);
 	}
 	hasDoc(docId) {
 		return this.db.prepare("SELECT 1 FROM documents WHERE doc_id=?").get(docId) !== void 0;
 	}
-	upsertDoc(docId, name, source, bytes, status, error = "") {
+	upsertDoc(docId, name, source, bytes, contentHash, status, error = "") {
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		this.db.prepare(`
-      INSERT INTO documents(doc_id, name, source, bytes, chunk_count, status, error, created_at, updated_at)
-      VALUES(?,?,?,?,0,?,?,?,?)
-      ON CONFLICT(doc_id) DO UPDATE SET name=excluded.name, bytes=excluded.bytes, status=excluded.status, error=excluded.error, updated_at=excluded.updated_at
-    `).run(docId, name, source, bytes, status, error, now, now);
+      INSERT INTO documents(doc_id, content_hash, name, source, bytes, chunk_count, status, error, created_at, updated_at)
+      VALUES(?,?,?,?,?,0,?,?,?,?)
+      ON CONFLICT(doc_id) DO UPDATE SET content_hash=excluded.content_hash, name=excluded.name, bytes=excluded.bytes, status=excluded.status, error=excluded.error, updated_at=excluded.updated_at
+    `).run(docId, contentHash, name, source, bytes, status, error, now, now);
 		this.loaded = false;
 	}
 	setDocStatus(docId, status, chunkCount, error = "") {
@@ -436,6 +448,10 @@ const inject = [
 let store;
 let cfg;
 const progressListeners = /* @__PURE__ */ new Set();
+/** 目录监视与启动扫描支持的文件类型（两处必须用同一份，否则会出现「监视到了却扫不到」的错位） */
+const WATCH_EXT = /\.(pdf|docx|md|txt|csv|json|log)$/i;
+/** 去掉扩展名：save 文档的 name 是标题（无后缀），文件文档的 name 带后缀，比对前需归一 */
+const stripExt = (n) => n.replace(WATCH_EXT, "");
 function broadcastProgress(msg) {
 	for (const write of progressListeners) try {
 		write(`event: progress\ndata: ${JSON.stringify(msg)}\n\n`);
@@ -453,12 +469,15 @@ async function indexOne(ctx, filePath, source) {
 	const name = basename(filePath);
 	const bytes = statSync(filePath).size;
 	const content = await (await import("node:fs/promises")).readFile(filePath);
-	const docId = KbStore.docId(content);
-	if (s.hasDoc(docId) && s.getDoc(docId)?.status === "ready") return {
+	const docId = KbStore.docIdFromPath(filePath);
+	const hash = KbStore.hashContent(content);
+	for (const d of s.listDocs()) if (d.content_hash === "" && stripExt(d.name) === stripExt(name)) s.deleteDoc(d.doc_id);
+	const prev = s.getDoc(docId);
+	if (prev?.status === "ready" && prev.content_hash === hash) return {
 		ok: true,
 		message: `${name} 已索引（内容未变化，跳过）`
 	};
-	s.upsertDoc(docId, name, source, bytes, "indexing");
+	s.upsertDoc(docId, name, source, bytes, hash, "indexing");
 	broadcastProgress(`正在索引 ${name}`);
 	try {
 		const chunks = await indexFile(filePath, await getEmbedder(cfg?.embeddingModel ?? "Xenova/bge-small-zh-v1.5"), cfg?.batchSize ?? 32);
@@ -483,6 +502,27 @@ async function indexOne(ctx, filePath, source) {
 		};
 	}
 }
+/**
+* 启动时补索引：扫描 watchDir 里已存在但尚未入库的文件。
+* watch() 只捕获监视建立之后的变动，DSH 未运行期间放进目录的文件它看不到，故需补扫。
+* 内容未变化的已入库文件会被 indexOne 直接跳过，不会重复向量化。
+*/
+async function scanWatchDir(ctx, dir) {
+	let names;
+	try {
+		const { readdir } = await import("node:fs/promises");
+		names = (await readdir(dir)).filter((f) => WATCH_EXT.test(f));
+	} catch (e) {
+		console.warn(`[rag-kb] 扫描目录失败 ${dir}: ${String(e.message)}`);
+		return;
+	}
+	let indexed = 0;
+	for (const f of names) {
+		const r = await indexOne(ctx, join(dir, f), "watch");
+		if (r.ok && !r.message.includes("跳过")) indexed++;
+	}
+	if (indexed > 0) console.log(`[rag-kb] 启动扫描补索引 ${indexed} 个文件（${dir}）`);
+}
 /** 混合语义检索（向量+关键词）+ 可选 reranker 精排 + 引用元数据 */
 async function search(query, topK) {
 	const s = await ensureStore();
@@ -560,7 +600,7 @@ function apply(ctx, config = {}) {
 			const watcher = watch(dir, { persistent: false }, (_ev, filename) => {
 				if (filename === null || filename === void 0) return;
 				const fname = String(filename);
-				if (!/\.(pdf|docx|md|txt|csv|json|log)$/i.test(fname)) return;
+				if (!WATCH_EXT.test(fname)) return;
 				const f = join(dir, fname);
 				setTimeout(() => {
 					if (existsSync(f)) indexOne(ctx, f, "watch");
@@ -569,6 +609,7 @@ function apply(ctx, config = {}) {
 			ctx.effect(() => {
 				watcher.close();
 			}, "rag-kb: dir watcher");
+			scanWatchDir(ctx, dir);
 		} catch (e) {
 			console.warn(`[rag-kb] 目录监视失败 ${dir}: ${String(e.message)}`);
 		}
@@ -691,12 +732,12 @@ function apply(ctx, config = {}) {
 				if (a.action === "save" && a.text !== void 0 && a.text !== "") {
 					const title = a.title !== void 0 && a.title !== "" ? a.title : `对话保存 ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 16)}`;
 					const content = `# ${title}\n\n${a.text}`;
-					const docId = KbStore.docId(content);
+					const docId = KbStore.hashContent(content);
 					if (s.hasDoc(docId) && s.getDoc(docId)?.status === "ready") return {
 						ok: true,
 						message: `${title} 已在知识库中（内容相同，跳过）`
 					};
-					s.upsertDoc(docId, title, "save", content.length, "indexing");
+					s.upsertDoc(docId, title, "save", content.length, docId, "indexing");
 					broadcastProgress(`正在索引对话内容「${title}」`);
 					try {
 						const embedder = await getEmbedder(cfg?.embeddingModel ?? "Xenova/bge-small-zh-v1.5");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puwenhui/dsh-rag-kb",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DSH RAG 知识库插件：混合检索(向量+FTS5)+Reranker 重排+GPU 加速+引用溯源+会话语义管理",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",