dsh-kb-rag: 本地優先的 RAG 知識庫工具集

DSH 插件 yumu247/dsh-kb-rag 爲 DSH 提供了一套本地優先的 RAG 知識庫工具。它位於 kb-rag Python 管線之上，支持語義檢索、增量入庫、網頁抓取和關聯推薦。這套工具旨在滿足本地化部署需求，避免雲端 API 調用成本，並確保數據留在本地機器。

核心功能¶

插件封裝了四個核心命令，分別對應不同的知識庫操作：

kb_query (語義檢索)：在本地向量數據庫中進行語義搜索，返回相關文本塊及來源和相似度。
kb_ingest (增量入庫)：將文檔目錄導入 ChromaDB。支持增量更新（基於 manifest hash），並自動處理 SiYuan 的前置元數據。
kb_crawl (網頁批量抓取)：利用 Scrapling 和 markdownify 批量抓取 URL，並將結果清洗爲 Markdown 格式。
kb_related (關聯推薦)：基於檢索或圖譜模式，爲已知文檔推薦相關文檔。

在安裝插件之前，需要確保宿主機已配置好 Python 環境、Ollama 模型以及 kb-rag 管線。

    git clone https://github.com/YuMu247/kb-rag
    cd kb-rag
    pip install -r requirements.txt

    ollama pull bge-m3

配置路徑
將 kb-rag 的安裝路徑告知插件。可以通過插件配置或環境變量設置：
- 配置方式：在 DSH 的 profile 配置中設置 kbRagDir。
- 環境變量方式：設置 KB_RAG_DIR 環境變量指向 kb-rag 目錄。
- 默認行爲：如果未配置，插件會在會話工作目錄下查找 ./kb-rag。
安裝 DSH 插件
使用 DSH 的插件管理命令安裝：

    dsh plugin --profile <profile> add github:YuMu247/dsh-kb-rag

安裝後，`kb_query`、`kb_ingest`、`kb_crawl`、`kb_related` 四個命令將注入到當前 DSH 進程中。安裝前請確認當前 DSH 構建版本支持 `dsh plugin` 子命令。

用於查詢本地知識庫。
* 參數：
* query (必填)：查詢文本。
* k (可選)：返回結果數量，默認 5，最大 20。
* 返回格式：JSON 格式，包含匹配的文本塊及來源。

用於將文檔目錄導入向量庫。
* 參數：
* docs：默認爲 <kb-rag>/docs。
* chunkSize：分塊大小，默認 512。
* overlap：分塊重疊大小，默認 64。
* force、reset、heading：控制覆蓋和元數據處理。

用於批量抓取網頁。
* 參數：
* urls 或 urlsFile：目標 URL 列表或文件路徑。
* out：輸出目錄，默認 <kb-rag>/out。
* delay：抓取間隔（秒），默認 1.5。

用於文檔關聯推薦。
* 參數：
* seed 或 fromDoc：種子文檔 ID（二選一）。
* k：返回數量，默認 5。
* graph：圖模式開關，大於 0 時啓用圖模式知識漫步。