@puwenhui/dsh-rag-kb 0.2.0 → 0.3.1

package/README.md

@@ -13,7 +13,8 @@ DSH RAG 知识库插件：**文档导入 → 智能切块 → 本地向量化
 - **会话语义管理**：所有操作（添加/删除/保存/检索）直接在对话里用大白话完成
 - **多格式支持**：pdf / docx / md / txt / csv / json
 - **完全本地**：模型本地运行，数据不出机器
-- **目录自动索引**：配置目录后文件放入/变更自动入库
+- **目录自动索引**：配置目录后，放入/修改的文件自动入库；**DSH 未运行期间放入的也会在下次启动时补扫**，不用管当时开没开
+- **文档原地更新**：同一文件改了内容会**覆盖更新**旧索引（以文件路径为身份），不会在库里留下旧版本
 - **对话内容保存**：把对话中的结论/总结一键存入知识库
 
 ## 版本要求
@@ -50,7 +51,7 @@ dsh plugin --profile web add @puwenhui/dsh-rag-kb
 ## 检索架构
 
 ```
-文档 → 解析(pdf/docx/md) → 标题感知切块(400 token + 10% 重叠)
+文档 → 解析(pdf/docx/md) → 标题感知切块(节标题强制断块 + 400 token + 10% 重叠)
   → 向量化(transformers.js bge-small-zh-v1.5, 512维, GPU/CPU)
   → FTS5 trigram 关键词索引（与向量索引同步写入）
 
@@ -59,6 +60,33 @@ dsh plugin --profile web add @puwenhui/dsh-rag-kb
   → 引用溯源(citation + position 字段)
 ```
 
+### 分块策略（v0.3.0 起）
+
+面向 Markdown 手册/知识库文档优化，保证**一节 = 一块**，引用溯源可精确到节：
+
+| 规则 | 说明 |
+|---|---|
+| 节标题强制断块 | 遇 `##` ~ `######` 立即断块，短节不再被合并；刻意不含单级 `#`——配置/代码注释普遍用它开头，误判会把命令序列切碎 |
+| 续块补回节标题 | 长节切成多块时，每块都带节标题，检索命中时能看清出处 |
+| 软下限 + 硬上限 | 块过短（如仅「节标题 + 来源行」）宁可略微超长也不单独成块；合并超过 1.2 倍上限则强制断开 |
+| 滑窗按换行对齐 | 超长无结构段落按换行位置切分，不把命令行从中间截断 |
+| 兜底宽度 | 块长控制在约 600 字符（≈400 token），实测上限 ~920 字符，避免超出 embedding 序列长度被截断 |
+
+实测效果（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 {}
 	}
-	/** 文档内容 hash 作 doc_id（同名不同内容=不同文档） */
-	static docId(content) {
+	/**
+	* 文件绝对路径 → doc_id：同一路径的文件内容变化时 doc_id 保持不变，
+	* 由 upsertDoc + insertChunks 覆盖更新，不会在库里留下旧版本。
+	* 路径转小写以适配 Windows 大小写不敏感。
+	*/
+	static docIdFromPath(filePath) {
+		return createHash("sha256").update(resolve(filePath).toLowerCase()).digest("hex").slice(0, 16);
+	}
+	/** 内容 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 = "") {
@@ -266,7 +278,12 @@ var indexer_exports = /* @__PURE__ */ __exportAll({
 });
 /** 中文友好的切块参数 */
 const CHUNK_TOKENS = 400;
-const OVERLAP_RATIO = .1;
+/**
+* 节标题行：`##` ~ `######` 视为节标题，遇之强制断块（保证「一节 = 一块」）。
+* 刻意不含单级 `#`——nginx/shell/mysql 等配置与代码的注释普遍用单 `#` 开头，
+* 误判会把命令序列切碎（实测语音平台文档 27 节被切成 231 块）。
+*/
+const HEADING_RE = /^#{2,6} /;
 async function extractText(filePath) {
 	const ext = extname(filePath).toLowerCase();
 	const buf = await readFile(filePath);
@@ -285,28 +302,47 @@ async function extractText(filePath) {
 	if (ext === ".md" || ext === ".txt" || ext === ".log" || ext === ".csv" || ext === ".json") return { text: buf.toString("utf8") };
 	throw new Error(`不支持的文件类型 ${ext}（支持 pdf/docx/md/txt/csv/json）`);
 }
-/** 标题感知切块：按标题/空行分段，过长段再固定长度切 */
+/** 标题感知切块：节标题强制断块（一节 = 一块）+ 空行分段 + 过长滑窗兜底 */
 function chunkText(text) {
 	const normalized = text.replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
 	if (normalized === "") return [];
-	const paragraphs = normalized.split(/\n(?=#{1,4} )|\n\n+/).map((p) => p.trim()).filter((p) => p !== "");
+	const paragraphs = normalized.split(/\n(?=#{2,6} )|\n\n+/).map((p) => p.trim()).filter((p) => p !== "");
 	const chunks = [];
 	let current = "";
+	let sectionHeading = "";
 	const maxChars = CHUNK_TOKENS * 1.5;
-	const overlap = Math.floor(maxChars * OVERLAP_RATIO);
 	for (const para of paragraphs) {
-		if (current !== "" && (current + "\n" + para).length > maxChars) {
+		const isHeading = HEADING_RE.test(para);
+		if (isHeading) sectionHeading = para.split("\n")[0].trim();
+		if (isHeading && current !== "") {
 			chunks.push(current);
-			current = current.length > overlap ? current.slice(-60) : "";
+			current = "";
 		}
-		if (para.length > maxChars * 2) {
-			if (current !== "") {
-				chunks.push(current);
-				current = "";
+		if (para.length > maxChars * 1.2) {
+			const prefix = current;
+			current = "";
+			const mergePrefix = prefix !== "" && prefix.length <= maxChars * .6;
+			if (prefix !== "" && !mergePrefix) chunks.push(prefix);
+			for (let i = 0; i < para.length;) {
+				let end = Math.min(i + maxChars, para.length);
+				if (end < para.length) {
+					const nl = para.lastIndexOf("\n", end);
+					if (nl > i + maxChars * .5) end = nl + 1;
+				}
+				const piece = para.slice(i, end);
+				const isFirst = i === 0;
+				i = end;
+				chunks.push(isFirst ? mergePrefix ? `${prefix}\n\n${piece}` : piece : sectionHeading !== "" ? `${sectionHeading}\n\n${piece}` : piece);
 			}
-			for (let i = 0; i < para.length; i += 540) chunks.push(para.slice(i, i + maxChars));
+			current = sectionHeading;
 			continue;
 		}
+		const merged = current + "\n" + para;
+		if (current !== "" && merged.length > maxChars && (current.length >= maxChars * .5 || merged.length > maxChars * 1.2)) {
+			chunks.push(current);
+			const tail = current.slice(-60);
+			current = sectionHeading !== "" ? `${sectionHeading}\n\n${tail}` : tail;
+		}
 		current = current === "" ? para : current + "\n" + para;
 	}
 	if (current !== "") chunks.push(current);
@@ -412,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`);
@@ -429,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);
@@ -459,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();
@@ -536,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");
@@ -545,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)}`);
 		}
@@ -667,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.2.0",
+  "version": "0.3.1",
   "description": "DSH RAG 知识库插件：混合检索(向量+FTS5)+Reranker 重排+GPU 加速+引用溯源+会话语义管理",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",