本地 RAG 知识库YuMu247/dsh-kb-rag

@dsh-external/dsh-kb-rag

面向 DSH 的本地优先 RAG 知识工具 —— 围绕
kb-rag Python 流水线（Ollama bge-m3 +
ChromaDB + SiYuan）的轻量工具封装。四个工具，全部本地部署，零 API 成本，你的文档
永远不会离开本机。

| 工具 | 功能 | 支撑脚本 |
|---|---|---|
| kb_query | 在本地向量数据库上进行语义搜索（返回 top-k 分块，含来源 + 相似度） | query.py --json |
| kb_ingest | 将文档目录摄取到 ChromaDB（增量式，基于清单哈希幂等；思源笔记会自动剥离 front-matter + 机器层） | ingest.py |
| kb_crawl | 批量抓取 URL 并转换为干净的 Markdown（Scrapling + markdownify） | crawl.py |
| kb_related | 相关文档推荐：检索式、图式知识游走，或从已知文档出发 | related.py |

该插件是一个纯粹的转发器：它定位 Python，启动 kb-rag 脚本并解析其输出。所有
知识库逻辑都位于 Python 项目中，你也可以独立使用该项目。

安装

需要带有 dsh plugin 子命令的 dsh 构建； = tui/headless/web/...
dsh plugin --profile  add github:YuMu247/dsh-kb-rag
dsh --profile         # 重启：kb_query / kb_ingest / kb_crawl / kb_related 已注入

对等依赖（@deepseek-ai/dsh-tools、@deepseek-ai/cordis）由 dsh profile 提供。

前置条件（在主机上一次性完成）

1. Python 流水线
git clone https://github.com/YuMu247/kb-rag
pip install -r kb-rag/requirements.txt

2. Ollama + 嵌入模型
ollama pull bge-m3        # ~1.2GB

3. 告诉插件 kb-rag 所在位置（任选其一）
a) 插件配置：  kbRagDir: "/path/to/kb-rag"
b) 环境变量：  KB_RAG_DIR=/path/to/kb-rag
c) 默认值：    会话工作目录下的 ./kb-rag

4. 摄取一些内容，然后提问
python kb-rag/ingest.py --docs /path/to/docs

可选（Windows 每日同步）：kb-rag 仓库中的 examples/sync_daily.cmd
会启动 Ollama、同步思源视频笔记、摄取并导入到 SiYuan。

工具参数

- kb_query — query（必填）、k（默认 5，最大 20）。返回 {ok, count, chunks:[{source, chunk, similarity, text}]}。
- kb_ingest — docs（默认 /docs）、force、reset、heading、chunkSize（默认 512）、overlap（默认 64）。返回 {ok, summary}。
- kb_crawl — urls（数组）或 urlsFile（路径）、out（默认 /out）、delay（默认 1.5s，最小 0.2）。返回 {ok, summary, outDir}。
- kb_related — seed 或 fromDoc（二者恰好其一）、k（默认 5）、graph（>0 启用图式游走）。返回 {ok, text}。

插件配置

所有键均为可选，在 profile 插件配置中设置：

| 键 | 默认值 | 含义 |
|---|---|---|
| pythonCmd | python（win）/ python3（其他） | Python 可执行文件 |
| kbRagDir | KB_RAG_DIR 环境变量，然后是 /kb-rag | kb-rag 检出目录 |

开发

npm install                 # typescript + @types/node + dsh-tools/cordis 类型（仅编译）
npm run typecheck           # tsc -b

运行时零 npm 依赖；src/ 是唯一事实来源，lib/
是编译后的副本（两者均随包发布）。

中文说明

DSH 的本地优先知识库插件：kb_query（语义检索）/ kb_ingest（增量入库）/
kb_crawl（网页批量抓取）/ kb_related（关联推荐），底层调用
kb-rag Python 管线（Ollama bge-m3 +
ChromaDB），全程本地、零 API 成本。安装：dsh plugin --profile  add
github:YuMu247/dsh-kb-rag。前置：克隆 kb-rag、pip install -r requirements.txt、
ollama pull bge-m3，并用配置 kbRagDir 或环境变量 KB_RAG_DIR 指明 kb-rag 路径。

许可证

MIT