@puwenhui/dsh-rag-kb 0.1.0 → 0.3.0

package/README.md

@@ -1,21 +1,24 @@
 # @puwenhui/dsh-rag-kb
 
-DSH RAG 知识库插件：**文档导入 → 智能切块 → 本地向量化 → 语义检索**，让 DSH 对话拥有私域知识。
+DSH RAG 知识库插件：**文档导入 → 智能切块 → 本地向量化 → 混合检索（向量+FTS5）→ Reranker 精排 → 引用溯源**。
 
 > 面向公司非技术人员的使用帮助请阅读 **[USAGE.zh.md](./USAGE.zh.md)**。
 
 ## 核心特性
 
-- **语义检索**：自然语言提问，agent 自动从知识库找答案（中文/英文均可）
-- **多格式支持**：pdf / docx / md / txt / csv / json
-- **完全本地**：向量化模型本地运行（bge-small-zh ONNX），数据不出机器
+- **混合检索**：语义向量（bge-small-zh）+ FTS5 trigram 关键词双路合并，同义/改述和精确词/错误码都能找到
+- **Reranker 精排**（可选）：bge-reranker-base cross-encoder，对混合检索结果做语义精排，噪音过滤更准
+- **GPU 加速**：DirectML（RTX 4060 实测批量索引快 4 倍），无 GPU 自动回退 CPU
+- **引用溯源**：脚注式引用（正文上标¹²³ + 末尾参考来源清单），agent 回答自带出处
 - **会话语义管理**：所有操作（添加/删除/保存/检索）直接在对话里用大白话完成
-- **目录自动索引**：配置一个目录，文件放入/变更自动入库
+- **多格式支持**：pdf / docx / md / txt / csv / json
+- **完全本地**：模型本地运行，数据不出机器
+- **目录自动索引**：配置目录后文件放入/变更自动入库
 - **对话内容保存**：把对话中的结论/总结一键存入知识库
 
 ## 版本要求
 
-- **DSH ≥ 0.2.0**（依赖 settings 标签页体系与 volatile 字段机制）
+- **DSH ≥ 0.2.0**
 
 ## 安装
 
@@ -23,25 +26,19 @@ DSH RAG 知识库插件：**文档导入 → 智能切块 → 本地向量化
 dsh plugin --profile web add @puwenhui/dsh-rag-kb
 ```
 
-（源码宿主用 `pnpm dsh plugin --profile web add @puwenhui/dsh-rag-kb`）
-
-## 配置
+## 配置（设置 → 插件 →「知识库」标签页）
 
-安装后打开 `dsh web`，**设置 → 插件 →「知识库」**标签页：
-
-| 字段 | 说明 |
-|---|---|
-| 知识库描述 | agent 检索前阅读，知道库里有什么 |
-| 自动索引目录 | 放入文档自动入库（可选） |
-| 检索返回条数 | 默认 5 |
-| 相似度阈值 | 0~1，默认 0.3 |
-
-**首次使用**会自动下载中文向量化模型（约 100MB，下载后完全离线，模型缓存在 `$DSH_HOME/rag-kb/hf-cache/`）。
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| 知识库描述 | 空 | agent 检索前阅读，知道库里有什么 |
+| 自动索引目录 | 空 | 放入文档自动入库（可选） |
+| 检索返回条数 | 5 | 混合检索召回 top-K |
+| 相似度阈值 | 0.3 | 0~1，过低噪音多 |
+| 启用 Reranker | 关 | 开启后需下载 ~1GB 模型 |
+| 重排后返回条数 | 3 | Reranker 精排后返回 top-N |
 
 ## 会话语义操作
 
-所有知识库操作直接在对话里说，agent 自动调用对应工具：
-
 | 你说 | agent 调用 |
 |---|---|
 | 「把 D:\docs 加进知识库」 | `knowledge_manage add` |
@@ -50,51 +47,53 @@ dsh plugin --profile web add @puwenhui/dsh-rag-kb
 | 「删掉旧版手册」 | `knowledge_manage remove` |
 | 「根据知识库回答：XXX」 | `knowledge_search` |
 
-## 模型工具（3 个）
-
-| 工具 | 说明 |
-|---|---|
-| `knowledge_search` | 语义检索：query + top_k → 带来源/相似度/原文的结果 |
-| `knowledge_status` | 知识库状态：文档列表/配置/描述 |
-| `knowledge_manage` | 管理操作：save / add / remove / reindex / describe |
-
-## 技术架构
+## 检索架构
 
 ```
-文档 → unpdf/mammoth 提取纯文本
-     → 标题感知切块（400 token + 10% 重叠）
-     → transformers.js 向量化（bge-small-zh-v1.5, 512 维, GPU 自动检测/CPU fallback）
-     → node:sqlite 存储（chunk + 向量 BLOB）
-     → 检索时内存余弦相似 top-K（万级 chunk 毫秒级）
-```
-
-- **向量库**：`node:sqlite`（Node 22.5+ 内置，零 npm 依赖，万级 chunk 内存检索 <50ms）
-- **Embedding**：`@huggingface/transformers` + `Xenova/bge-small-zh-v1.5`（纯 JS ONNX，本地 CPU 3.6ms/chunk）
-- **PDF 解析**：`unpdf`（纯 JS）| **DOCX**：`mammoth`（纯 JS）
-- **数据目录**：`$DSH_HOME/rag-kb/`（index.db + hf-cache/）
-
-## 已知限制
-
-- 单库设计（不分知识库），适合 <1000 篇文档
-- 512 维向量（bge-small-zh），如需多语言可换 bge-m3（1024 维）
-- 附件出站（图片/文件回传 QQ）走路径文本，暂不支持直接推送
+文档 → 解析(pdf/docx/md) → 标题感知切块(节标题强制断块 + 400 token + 10% 重叠)
+  → 向量化(transformers.js bge-small-zh-v1.5, 512维, GPU/CPU)
+  → FTS5 trigram 关键词索引（与向量索引同步写入）
 
-## 目录结构
-
-```
-src/           # 宿主半边（工具 + 索引 + 检索 + systemPrompt 注入 + SSE + 目录监视）
-client-src/    # 浏览器半边（设置标签页）
-lib/plugin.mjs # 宿主半边构建产物
-lib/client.js  # 浏览器半边构建产物
-cordis.patch.yml
+检索: 混合检索(向量余弦 + FTS5 bm25 双路合并, via=vector/keyword/both)
+  → [可选] Reranker 精排(bge-reranker-base cross-encoder, 召回×3 → 精排 → top-N)
+  → 引用溯源(citation + position 字段)
 ```
 
-## 开发
+### 分块策略（v0.3.0 起）
 
-- 宿主半边：`npx tsdown`（产出 lib/plugin.mjs）
-- 浏览器半边：`cd client-src && npm install && npm run build`
-- 部署到本地 profile：构建后复制 `lib/plugin.mjs` 和 `lib/client.js` 到 profile 的 node_modules 目录
-- 发布：bump version → `npm publish`
+面向 Markdown 手册/知识库文档优化，保证**一节 = 一块**，引用溯源可精确到节：
+
+| 规则 | 说明 |
+|---|---|
+| 节标题强制断块 | 遇 `##` ~ `######` 立即断块，短节不再被合并；刻意不含单级 `#`——配置/代码注释普遍用它开头，误判会把命令序列切碎 |
+| 续块补回节标题 | 长节切成多块时，每块都带节标题，检索命中时能看清出处 |
+| 软下限 + 硬上限 | 块过短（如仅「节标题 + 来源行」）宁可略微超长也不单独成块；合并超过 1.2 倍上限则强制断开 |
+| 滑窗按换行对齐 | 超长无结构段落按换行位置切分，不把命令行从中间截断 |
+| 兜底宽度 | 块长控制在约 600 字符（≈400 token），实测上限 ~920 字符，避免超出 embedding 序列长度被截断 |
+
+实测效果（13 篇技术/管理文档，114 节）：切成 605 块，**96% 的块带节标题**。
+
+## 技术栈
+
+| 层 | 选型 | 说明 |
+|---|---|---|
+| Embedding | transformers.js + bge-small-zh-v1.5 ONNX | 512 维中文，本地 CPU 3.6ms/条 |
+| Reranker | transformers.js + bge-reranker-base ONNX | cross-encoder 精排 |
+| GPU 加速 | DirectML (device: 'dml') | 批量索引快 4 倍，无 GPU 回退 CPU |
+| 向量库 | node:sqlite BLOB + 内存余弦 | 万级 chunk <50ms |
+| FTS | SQLite FTS5 + trigram tokenizer | 中文 3 字滑窗精确匹配 |
+| PDF 解析 | unpdf（纯 JS） | 无原生依赖 |
+| DOCX 解析 | mammoth（纯 JS） | 无原生依赖 |
+| 数据目录 | $DSH_HOME/rag-kb/ | index.db + hf-cache/ |
+
+## 模型缓存
+
+| 模型 | 大小 | 位置 |
+|---|---|---|
+| bge-small-zh-v1.5 | ~91MB | $DSH_HOME/rag-kb/hf-cache/ |
+| bge-reranker-base | ~1GB | 同上（启用 Reranker 时自动下载） |
+
+离线部署：管理员把整个 `hf-cache/` 目录拷贝到同事机器的相同位置即可。
 
 ## License
 

package/USAGE.zh.md

@@ -93,6 +93,9 @@ AI 会自动提取内容、起标题、入库。
 - 把「相似度阈值」调高（如 0.5）——结果更精准但可能漏掉
 - 在「知识库描述」里写得更具体，帮助 AI 判断什么时候该检索
 
+**Q：什么是 Reranker？要不要开？**
+Reranker 是对检索结果做二次精排的技术，能过滤噪音让结果更准。如果知识库内容多且检索有噪音，建议开启（需下载约 1GB 模型）。文档少（<50篇）时不开也够用。
+
 **Q：能同时存多少文档？**
 建议 1000 篇以内。超过后检索仍可用，但不同主题的文档可能互相干扰。
 

package/lib/client.js

@@ -38,6 +38,18 @@ window.__ModuleLoader__.load({ id: "@puwenhui/dsh-rag-kb", factory: (require) =>
 				label: "相似度阈值",
 				type: "number",
 				hint: "0~1，默认 0.3，过低噪音多"
+			},
+			{
+				key: "enableReranker",
+				label: "启用 Reranker 重排序",
+				type: "boolean",
+				hint: "首次使用会下载约 500MB 模型"
+			},
+			{
+				key: "rerankTopN",
+				label: "重排后返回条数",
+				type: "number",
+				hint: "默认 3"
 			}
 		];
 		function KbSettingsTab(props) {
@@ -169,18 +181,23 @@ window.__ModuleLoader__.load({ id: "@puwenhui/dsh-rag-kb", factory: (require) =>
 				}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					style: {
 						display: "grid",
-						gridTemplateColumns: "1fr",
-						gap: "10px",
+						gridTemplateColumns: "1fr 1fr",
+						gap: "10px 14px",
 						marginTop: "12px"
 					},
 					children: [FIELDS.map((f) => {
 						const overridden = Object.hasOwn(userLayer, f.key);
+						const isBoolean = f.type === "boolean";
 						return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
 							style: {
 								display: "flex",
 								flexDirection: "column",
 								gap: "4px",
-								fontSize: "13px"
+								fontSize: "13px",
+								...isBoolean ? {
+									gridColumn: "span 1",
+									justifyContent: "center"
+								} : {}
 							},
 							children: [
 								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
@@ -193,7 +210,45 @@ window.__ModuleLoader__.load({ id: "@puwenhui/dsh-rag-kb", factory: (require) =>
 										children: "·已覆盖"
 									})]
 								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+								isBoolean ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									style: {
+										display: "flex",
+										alignItems: "center",
+										gap: "12px",
+										padding: "4px 0"
+									},
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+										style: {
+											display: "flex",
+											alignItems: "center",
+											gap: "4px",
+											cursor: "pointer"
+										},
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+											type: "radio",
+											name: f.key,
+											checked: shown[f.key] === true,
+											onChange: () => {
+												edit(f.key, true);
+											}
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: "开" })]
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+										style: {
+											display: "flex",
+											alignItems: "center",
+											gap: "4px",
+											cursor: "pointer"
+										},
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+											type: "radio",
+											name: f.key,
+											checked: shown[f.key] !== true,
+											onChange: () => {
+												edit(f.key, false);
+											}
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: "关" })]
+									})]
+								}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
 									value: draft !== null && draft[f.key] !== void 0 ? String(draft[f.key]) : String(shown[f.key] ?? ""),
 									placeholder: f.placeholder ?? "",
 									onChange: (e) => {
@@ -212,6 +267,7 @@ window.__ModuleLoader__.load({ id: "@puwenhui/dsh-rag-kb", factory: (require) =>
 						}, f.key);
 					}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						style: {
+							gridColumn: "1 / -1",
 							display: "flex",
 							alignItems: "center",
 							gap: "10px",

package/lib/plugin.mjs

@@ -25,18 +25,22 @@ var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /** 用户可见配置（设置面板「知识库」标签页） */
 const PublicConfig = z.object({
 	watchDir: z.string().default("").description("本地文档目录（放入即自动索引）"),
-	topK: z.number().default(5).description("检索返回条数（默认 5）"),
+	topK: z.number().default(5).description("混合检索召回条数（默认 5）"),
 	minScore: z.number().default(.3).description("相似度阈值（0~1，默认 0.3）"),
-	description: z.string().default("").description("知识库描述（agent 检索前会阅读）")
+	description: z.string().default("").description("知识库描述（agent 检索前会阅读）"),
+	enableReranker: z.boolean().default(false).description("启用 reranker 重排序（首次下载约 500MB 模型）"),
+	rerankTopN: z.number().default(3).description("重排后返回条数（默认 3）")
 });
 /** 完整配置（含高级项） */
 const Config = z.object({
 	watchDir: z.string().default("").description("本地文档目录"),
-	topK: z.number().default(5).description("检索返回条数"),
+	topK: z.number().default(5).description("混合检索召回条数"),
 	minScore: z.number().default(.3).description("相似度阈值"),
 	description: z.string().default("").description("知识库描述"),
 	embeddingModel: z.string().default("Xenova/bge-small-zh-v1.5").description("embedding 模型"),
-	batchSize: z.number().default(32).description("批量推理大小")
+	batchSize: z.number().default(32).description("批量推理大小"),
+	enableReranker: z.boolean().default(false).description("启用 reranker 重排序"),
+	rerankTopN: z.number().default(3).description("重排后返回条数")
 });
 /** 全字段 volatile 注入（npm 版 schemastery 无 .volatile()，0.2.0 设置面板只收录 volatile 字段） */
 for (const schema of [PublicConfig, Config]) for (const child of Object.values(schema.dict ?? {})) child.meta.volatile = true;
@@ -48,7 +52,9 @@ function resolveKbConfig(c = {}) {
 		minScore: Math.max(0, Math.min(1, c.minScore ?? .3)),
 		description: c.description ?? "",
 		embeddingModel: c.embeddingModel ?? "Xenova/bge-small-zh-v1.5",
-		batchSize: Math.max(1, Math.min(128, c.batchSize ?? 32))
+		batchSize: Math.max(1, Math.min(128, c.batchSize ?? 32)),
+		enableReranker: c.enableReranker === true,
+		rerankTopN: Math.max(1, Math.min(20, c.rerankTopN ?? 3))
 	};
 }
 //#endregion
@@ -95,6 +101,10 @@ var KbStore = class {
         FOREIGN KEY(doc_id) REFERENCES documents(doc_id) ON DELETE CASCADE
       );
       CREATE INDEX IF NOT EXISTS idx_chunks_doc ON chunks(doc_id);
+      CREATE VIRTUAL TABLE IF NOT EXISTS chunk_fts USING fts5(
+        text,
+        tokenize='trigram'
+      );
     `);
 	}
 	/** 文档内容 hash 作 doc_id（同名不同内容=不同文档） */
@@ -118,6 +128,9 @@ var KbStore = class {
 		this.loaded = false;
 	}
 	deleteDoc(docId) {
+		const ids = this.db.prepare("SELECT id FROM chunks WHERE doc_id=?").all(docId);
+		const ftsDel = this.db.prepare("DELETE FROM chunk_fts WHERE rowid=?");
+		for (const { id } of ids) ftsDel.run(id);
 		this.db.prepare("DELETE FROM chunks WHERE doc_id=?").run(docId);
 		this.db.prepare("DELETE FROM documents WHERE doc_id=?").run(docId);
 		this.loaded = false;
@@ -128,13 +141,22 @@ var KbStore = class {
 	getDoc(docId) {
 		return this.db.prepare("SELECT * FROM documents WHERE doc_id=?").get(docId);
 	}
-	/** 批量写入切块+向量（一个事务，失败回滚） */
+	/** 批量写入切块+向量+FTS 索引（一个事务，失败回滚） */
 	insertChunks(docId, chunks) {
 		this.db.exec("BEGIN");
 		try {
 			this.db.prepare("DELETE FROM chunks WHERE doc_id=?").run(docId);
+			const oldIds = this.db.prepare("SELECT id FROM chunks WHERE doc_id=?").all(docId);
+			const ftsDel = this.db.prepare("DELETE FROM chunk_fts WHERE rowid=?");
+			for (const { id } of oldIds) ftsDel.run(id);
 			const stmt = this.db.prepare("INSERT INTO chunks(doc_id, seq, text, embedding) VALUES(?,?,?,?)");
-			for (const c of chunks) stmt.run(docId, c.seq, c.text, Buffer.from(c.embedding.buffer, c.embedding.byteOffset, c.embedding.byteLength));
+			const ftsIns = this.db.prepare("INSERT INTO chunk_fts(rowid, text) VALUES(?,?)");
+			for (const c of chunks) {
+				const buf = Buffer.from(c.embedding.buffer, c.embedding.byteOffset, c.embedding.byteLength);
+				const info = stmt.run(docId, c.seq, c.text, buf);
+				const rowid = Number(info.lastInsertRowid);
+				ftsIns.run(rowid, c.text);
+			}
 			this.db.exec("COMMIT");
 		} catch (e) {
 			this.db.exec("ROLLBACK");
@@ -157,22 +179,69 @@ var KbStore = class {
 		}
 		this.loaded = true;
 	}
-	/** 余弦相似检索（向量已归一化，等价点积） */
-	search(queryVec, topK, minScore) {
+	/** 混合检索：向量余弦 + FTS5 关键词双路合并（加权排序） */
+	hybridSearch(queryVec, queryText, topK, minScore) {
 		this.ensureLoaded();
-		const scored = [];
+		const vectorScores = /* @__PURE__ */ new Map();
 		for (let i = 0; i < this.vectors.length; i++) {
 			const v = this.vectors[i];
 			let dot = 0;
 			for (let j = 0; j < queryVec.length; j++) dot += queryVec[j] * v[j];
-			if (dot >= minScore) scored.push({
-				docId: this.vectorRows[i].docId,
-				seq: this.vectorRows[i].seq,
-				score: dot
-			});
+			if (dot >= minScore) {
+				const key = `${this.vectorRows[i].docId}:${this.vectorRows[i].seq}`;
+				vectorScores.set(key, {
+					docId: this.vectorRows[i].docId,
+					seq: this.vectorRows[i].seq,
+					score: dot
+				});
+			}
 		}
-		scored.sort((a, b) => b.score - a.score);
-		return scored.slice(0, topK);
+		const keywordScores = /* @__PURE__ */ new Map();
+		if (queryText.trim().length >= 3) try {
+			const safe = queryText.replace(/["'*()\-:]/g, " ").trim().slice(0, 50);
+			if (safe.length >= 3) {
+				const rows = this.db.prepare(`
+            SELECT c.doc_id, c.seq, bm25(chunk_fts) AS rank
+            FROM chunk_fts f
+            JOIN chunks c ON c.id = f.rowid
+            WHERE chunk_fts MATCH ?
+            ORDER BY rank
+            LIMIT ?
+          `).all(`"${safe}"`, topK * 2);
+				for (const row of rows) {
+					const key = `${row.doc_id}:${row.seq}`;
+					const kwScore = 1 / (1 + Math.abs(row.rank));
+					keywordScores.set(key, {
+						docId: row.doc_id,
+						seq: row.seq,
+						score: kwScore
+					});
+				}
+			}
+		} catch {}
+		const merged = /* @__PURE__ */ new Map();
+		for (const [key, v] of vectorScores) merged.set(key, {
+			...v,
+			score: v.score,
+			via: keywordScores.has(key) ? "both" : "vector"
+		});
+		for (const [key, k] of keywordScores) if (merged.has(key)) {
+			const existing = merged.get(key);
+			existing.score = existing.score + k.score * .3;
+			existing.via = "both";
+		} else merged.set(key, {
+			...k,
+			via: "keyword"
+		});
+		return [...merged.values()].sort((a, b) => b.score - a.score).slice(0, topK);
+	}
+	/** 向后兼容：纯向量检索（内部调 hybridSearch 空 queryText） */
+	search(queryVec, topK, minScore) {
+		return this.hybridSearch(queryVec, "", topK, minScore).map((r) => ({
+			docId: r.docId,
+			seq: r.seq,
+			score: r.score
+		}));
 	}
 	/** 按 doc_id + seq 取 chunk 原文 */
 	chunkText(docId, seq) {
@@ -192,11 +261,17 @@ var indexer_exports = /* @__PURE__ */ __exportAll({
 	chunkText: () => chunkText,
 	extractText: () => extractText,
 	getEmbedder: () => getEmbedder,
-	indexFile: () => indexFile
+	indexFile: () => indexFile,
+	rerank: () => rerank
 });
 /** 中文友好的切块参数 */
 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);
@@ -215,58 +290,86 @@ 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);
 	return chunks.filter((c) => c.trim().length >= 10);
 }
-let pipelinePromise;
-async function loadPipeline(modelName) {
+let gpuPipeline;
+let cpuPipeline;
+async function loadPipeline(modelName, device) {
 	const { pipeline, env } = await import("@huggingface/transformers");
 	const { dshHomePath } = await import("@deepseek-ai/dsh-home-paths");
 	env.cacheDir = dshHomePath("rag-kb", "hf-cache");
-	return pipeline("feature-extraction", modelName);
+	try {
+		return await pipeline("feature-extraction", modelName, { device });
+	} catch (e) {
+		if (device === "dml") {
+			console.log("[rag-kb] DML GPU 不可用，回退 CPU");
+			return await pipeline("feature-extraction", modelName, { device: "cpu" });
+		}
+		throw e;
+	}
 }
 async function getEmbedder(modelName) {
-	pipelinePromise ??= loadPipeline(modelName);
-	const embedder = await pipelinePromise;
 	return {
-		/** 单条向量化（检索查询用） */
+		/** 单条向量化（检索查询用，CPU 单条比 GPU 快） */
 		async embed(text) {
-			const out = await embedder(text, {
+			cpuPipeline ??= await loadPipeline(modelName, "cpu");
+			const out = await cpuPipeline(text, {
 				pooling: "cls",
 				normalize: true
 			});
 			return new Float32Array(out.data);
 		},
-		/** 批量向量化（索引用，batch 推理吃满多核/GPU） */
+		/** 批量向量化（索引用，GPU/DML 批量快 4 倍，不可用自动回退 CPU） */
 		async embedBatch(texts, batchSize) {
+			gpuPipeline ??= await loadPipeline(modelName, "dml");
 			const results = [];
 			for (let i = 0; i < texts.length; i += batchSize) {
 				const batch = texts.slice(i, i + batchSize);
-				const out = await embedder(batch, {
+				const out = await gpuPipeline(batch, {
 					pooling: "cls",
 					normalize: true
 				});
@@ -277,6 +380,31 @@ async function getEmbedder(modelName) {
 		}
 	};
 }
+let rerankerPipeline;
+async function loadReranker() {
+	const { pipeline, env } = await import("@huggingface/transformers");
+	const { dshHomePath } = await import("@deepseek-ai/dsh-home-paths");
+	env.cacheDir = dshHomePath("rag-kb", "hf-cache");
+	return pipeline("text-classification", "Xenova/bge-reranker-base");
+}
+/**
+* 对混合检索结果做 cross-encoder 精排。
+* 输入：query + 候选列表（含原文），输出按相关性重排序。
+*/
+async function rerank(query, candidates) {
+	rerankerPipeline ??= await loadReranker();
+	const pairs = candidates.map((c) => ({
+		text: query,
+		text_pair: c.text
+	}));
+	const scores = await rerankerPipeline(pairs);
+	const scored = candidates.map((c, i) => ({
+		...c,
+		rerankScore: scores[i].score
+	}));
+	scored.sort((a, b) => b.rerankScore - a.rerankScore);
+	return scored;
+}
 /** 完整索引管线：文件路径 → 切块+向量数组 */
 async function indexFile(filePath, embedder, batchSize, onProgress) {
 	const { text } = await extractText(filePath);
@@ -355,16 +483,46 @@ async function indexOne(ctx, filePath, source) {
 		};
 	}
 }
-/** 语义检索 */
+/** 混合语义检索（向量+关键词）+ 可选 reranker 精排 + 引用元数据 */
 async function search(query, topK) {
 	const s = await ensureStore();
 	const queryVec = await (await getEmbedder(cfg?.embeddingModel ?? "Xenova/bge-small-zh-v1.5")).embed(query);
-	return s.search(queryVec, topK ?? cfg?.topK ?? 5, cfg?.minScore ?? .3).map((h) => ({
-		doc: s.getDoc(h.docId)?.name ?? h.docId,
-		seq: h.seq,
-		score: Number(h.score.toFixed(3)),
-		text: s.chunkText(h.docId, h.seq).slice(0, 800)
+	const effectiveTopK = topK ?? cfg?.topK ?? 5;
+	const recallK = cfg?.enableReranker === true ? effectiveTopK * 3 : effectiveTopK;
+	let results = s.hybridSearch(queryVec, query, recallK, cfg?.minScore ?? .3).map((h) => {
+		const docName = s.getDoc(h.docId)?.name ?? h.docId;
+		const fullText = s.chunkText(h.docId, h.seq);
+		return {
+			docId: h.docId,
+			doc: docName,
+			seq: h.seq,
+			score: Number(h.score.toFixed(3)),
+			via: h.via,
+			text: fullText,
+			citation: `${docName} 第${h.seq + 1}段`,
+			position: `文档「${docName}」第 ${h.seq + 1} 段`
+		};
+	});
+	if (cfg?.enableReranker === true && results.length > 0) try {
+		const reranked = await rerank(query, results);
+		const topN = cfg?.rerankTopN ?? 3;
+		results = reranked.slice(0, topN).map((r) => ({
+			...r,
+			text: r.text.slice(0, 800),
+			rerankScore: Number(r.rerankScore.toFixed(4))
+		}));
+	} catch (e) {
+		console.warn("[rag-kb] reranker 失败，使用混合检索结果:", String(e.message ?? e));
+		results = results.slice(0, effectiveTopK).map((r) => ({
+			...r,
+			text: r.text.slice(0, 800)
+		}));
+	}
+	else results = results.slice(0, effectiveTopK).map((r) => ({
+		...r,
+		text: r.text.slice(0, 800)
 	}));
+	return results;
 }
 function apply(ctx, config = {}) {
 	const unwrap = (v) => v !== null && typeof v === "object" && "get" in v ? v.get() : v;
@@ -432,12 +590,12 @@ function apply(ctx, config = {}) {
 	const disposers = [
 		ctx.tools.register({
 			name: "knowledge_search",
-			description: "在本地知识库中语义检索。返回最相关的知识块（带来源文档名、相似度、原文片段）。回答与知识库内容相关的问题前应先检索。query 支持自然语言。",
+			description: "在本地知识库中混合检索（语义向量 + 关键词）。返回最相关的知识块，每条带 citation 引用标注。回答知识库相关问题时：先检索 → 组织回答 → 在答案中标注来源 citation。query 支持自然语言和精确关键词（错误码/型号/人名等）。",
 			parameters: compileParams({
 				query: {
 					type: "string",
 					required: true,
-					description: "检索问题（自然语言，中英文均可）"
+					description: "检索问题（自然语言或精确关键词）"
 				},
 				top_k: {
 					type: "number",
@@ -635,11 +793,13 @@ function apply(ctx, config = {}) {
 		const docs = store?.listDocs().filter((d) => d.status === "ready").length ?? 0;
 		return [
 			"You have a local knowledge base accessible via these tools:",
-			"- knowledge_search: semantic search the KB (use BEFORE answering questions about its content)",
+			"- knowledge_search: hybrid search (semantic + keyword). Use BEFORE answering questions about KB content.",
 			"- knowledge_status: list documents and config",
 			"- knowledge_manage: add/save/remove/reindex documents",
+			"IMPORTANT: When the user says 搜一下/查一下/搜索, FIRST try knowledge_search on the local KB. Only do a web search if KB has no relevant results AND the topic is clearly not about local documents. Do NOT search both simultaneously — this confuses the answer.",
 			desc !== "" ? `KB description: ${desc}` : "",
 			`Currently ${docs} document(s) indexed.`,
+			"CITATION STYLE (footnote format): In the body of your answer, mark sources with superscript numbers like ¹ ² ³ (Unicode superscripts). At the END, add a \"参考来源\" section. IMPORTANT: MERGE citations from the same document into ONE entry — e.g. if citing 文档A 第1段/第2段/第3段, list as \"1. 文档A 第1-3段\" (not 3 separate lines). Only list each document once with all its paragraph numbers combined. Keep the answer body clean.",
 			"When the user says \"save this to the knowledge base\" (保存到知识库/记下来), extract the valuable content from the conversation and call knowledge_manage with action=\"save\", providing a concise title and the text.",
 			"For file/directory indexing use action=\"add\" with a path."
 		].filter(Boolean).join("\n");
@@ -652,6 +812,6 @@ function apply(ctx, config = {}) {
 	});
 }
 //#endregion
-export { Config, KbStore, apply, chunkText, extractText, getEmbedder, indexFile, inject, name, resolveKbConfig };
+export { Config, KbStore, apply, chunkText, extractText, getEmbedder, indexFile, inject, name, rerank, resolveKbConfig };
 
 //# sourceMappingURL=plugin.mjs.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@puwenhui/dsh-rag-kb",
-  "version": "0.1.0",
-  "description": "DSH RAG 知识库插件：文档导入→切块→本地向量化→语义检索，knowledge_search 工具 + 会话语义管理 + 设置面板",
+  "version": "0.3.0",
+  "description": "DSH RAG 知识库插件：混合检索(向量+FTS5)+Reranker 重排+GPU 加速+引用溯源+会话语义管理",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"