文献知识库检索 Breeze136/dsh-kb-rag

kb-rag：本地文献 RAG，段落级溯源

Awesome DSH Plugin
dsh.so security

kb-rag 是给 DSH（DeepSeek Harness）和其他 MCP 客户端用的本地文献知识库。它把 PDF 和 Zotero 文库索引进同一个 SQLite 文件，然后返回能回答问题的段落。每条结果都带上所属章节、物理页码和 DOI，以及该段落挂着的引用，包括被引文献是否已在你的文库中。

索引、嵌入和重排都在你的机器上跑。没有 API 费用，也不上传任何东西。预热后的查询在 quick 模式下耗时 0.33-0.38 s，deep 模式下 1.4-1.9 s；重启后第一次调用要等模型加载，最长 8.9 s。

npm 包 dsh-kb-rag 从 npm-package/ 发布。一页纸概览：docs/promo.html。fork 出来的仓库和名字相近的仓库都不是发布源；官方仓库是 Breeze136/dsh-kb-rag。

Figure 1　Every answer line traces back to a passage in your library: section, page, DOI, and who that passage cites.

图 2　全部都在你的机器上跑：分块、嵌入、关键词加向量检索，最后做本地重排。

结果长什么样

一次 kb_rag 调用按下面的结构返回证据。界面目前是中文，所以下面这段是译文。[in-library] 标记的是已经建好索引的引用文献。

Knowledge base sources Top-2
deep · reranked with BAAI/bge-reranker-base · cache hit

1. Chemical vapour deposition of graphene on copper substrates — Author A; Author B · 2024 · Carbon · Results · p.4 graphene domains nucleate on the copper surface and coalesce into a continuous film ... at a growth rate of ~2 um/min citations from this evidence ([in-library] = already held, searchable)
· [Ref 4] Author C, et al. Carbon 48, 1234 (2010)
[in-library] Nucleation and growth of graphene on transition metals (Author C · 2010 · Carbon) (this evidence's Ref 4) · open in Zotero
· 3 further citations collapsed (Ref 6-8); use the numbers to fetch them

Related work
- [A Practical Guide to Raman Spectroscopy of Graphene] — Author G et al. · 2020 (same author, related topic)

作者、期刊和 DOI 都是占位符，格式是真的。完整走查见 docs/OUTPUT-FORMAT.md。

顺着引用往下追

一段文字会保留 PDF 里印出的引用标记。kb-rag 拿每个标记去文献库里解析，所以 [4, 7] 会变成两条：一条你已经收录，带它自己的页码；另一条还在库外——是条线索，去取回来，而不是死胡同。

图 3　实线箭头是解析器已解析的引用；底部那条线是相关文献，不是引用。

补充文献是个循环

加一条库外参考文献——用 kb_fetch 按 DOI 取，或者把 PDF 丢进文件夹再跑一次入库——它自己的参考文献列表就进入下一轮检索。同一个问题会返回更多证据，可追的链条也更长。索引始终增量进行：没变的文件跳过，什么都不重建。

图 4　Ref 7 原本在库外；补充之后它打开在第 9 页，它自己的 Ref 9 成为下一条线索。

1.6.8 改了什么

1.6.8 修复了两处问题，它们导致 DSH 0.2 安装失败：peer 版本范围和客户端注入列表。这两处都错了，插件在安装时被拒绝，工具卡片也一直是空的。

本次发布还新增了由引擎渲染的 HTML 答案页，以及标题级探测。kb_stats 现在会报告模型缓存状态；深度搜索时，如果最佳重排分数仍低于下限，就返回 no_hit。搜索核心其余部分没有变化：在同一个知识库上，结果与 1.6.7 一致。完整列表见 CHANGELOG.md。

安装

kb-rag 运行在 DSH 桌面应用里。从插件面板安装即可。命令行方式留给维护者和旧的 web 部署；新用户用不到。

A. DSH 桌面应用

1. 打开 Settings → Plugins（设置 → 插件）。
2. 搜索 kb-rag。包名是 dsh-kb-rag，条目应显示 1.6.8。
3. 安装，重启 DSH，然后新建一个会话。

桌面应用需要 0.2 或更高版本。1.6.7 及更早版本过不了这个版本的兼容性检查；1.6.8 是第一个能通过的版本。

模型下载（最常见的卡点）

首次搜索会下载两个模型（约 1.2 GB）。这一步最容易卡住。可以让插件自己拉取，也可以预先下载到你选定的目录：

[Environment]::SetEnvironmentVariable("HF_HOME", "<cache-dir>", "User")
new shell
$env:HF_HOME = "<cache-dir>"
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-zh-v1.5')"
python -c "from sentence_transformers import CrossEncoder; CrossEncoder('BAAI/bge-reranker-base')"

如果 Python 提示缺少 sentence-transformers，先装上它。kb_stats 会报告两个模型是否已缓存。默认下载卡住的话，设置 HF_ENDPOINT=https://hf-mirror.com 和 KB_HF_MIRROR_FIRST=1，重启 DSH 后重试。完整说明：docs/MIGRATION-1.6.8.md。

已经在 1.6.7 上？插件面板检查的是已安装的 1.6.7 manifest，所以安装 1.6.8 可能失败，报错里引用的还是 1.6.7。先卸载 1.6.7，再安装 1.6.8。

B. 从 DSH web 迁移过来

web 配置档不是受支持的安装目标。先安装 DSH 桌面应用，再按 A 操作。知识库（.kb）留在原处；变的只是插件宿主。删掉旧的 web 配置档副本，免得两边不一致：

dsh plugin --profile web remove dsh-kb-rag

C. 从源码安装（维护者）

git clone https://github.com/Breeze136/dsh-kb-rag.git && cd dsh-kb-rag
./npm-package/scripts/install.sh # macOS / Linux / Git Bash
Windows: install.cmd, or npm-package\scripts\install.ps1

如果你的桌面版无法访问 npm，先安装一次 dsh-plugin-registry，再用它的市场面板。kb-rag 已在那里上架。

[!WARNING]
不要在 DSH 配置档里运行 npm install dsh-kb-rag。它会在 pnpm 的符号链接存储旁边写入 npm 风格的 node_modules，之后 dsh plugin 操作会变得不可预测。npm install 只用于你手动管理的部署；见 npm-package/README.md。

故障排查

| 现象 | 含义 | 修复 |
| 面板提示 @1.6.7 ... incompatible | 它检查的是已安装的 1.6.7 清单 | 卸载 1.6.7，重启，安装 1.6.8 |
| Cannot find package ...\dsh-kb-rag\index.js | 装的是 GitHub 仓库根目录，不是 npm 包 | 卸载它，从 npm 安装 dsh-kb-rag |
| .hotload\...\package.json 缺失 | 本地预览的元数据已过期 | 重装 1.6.8；若仍存在，清空面板缓存 |
| 安装成功，但没有 kb_ 工具 | 会话太旧，或配置档里仍是 1.6.7 | 重启 DSH，打开新对话，检查版本 |
| 全新会话里没有 /kb | 命令列表还没刷新 | 先发一条消息，再输入 /kb；不用它工具也能正常工作 |
| 缺少 Python 包或模型 | 属于引擎依赖，不是插件问题 | 运行报错信息里的命令，或设置 KB_AUTO_PIP=1；模型使用 HF_ENDPOINT |

详细说明和上报前的检查清单：docs/TROUBLESHOOTING.md。

用户手册

建立知识库

按论文当前所在的位置，有三种入口：

Zotero 文库（优先用这个）。 先预览再同步，避免整个文库被误导入：

告诉我哪些带 PDF 附件的 Zotero 条目可以入库，先不要执行。

这就是 kb_zotero(dry_run=true)。去掉 dry_run 就会真正执行；整库迁移时加上 async_mode=true。Zotero 的标题、作者、年份、期刊和 DOI 会写入搜索结果；没有本地 PDF 附件的条目会被跳过，也不会替你下载任何东西。自动检测失败时，显式传入 zotero.sqlite 路径。

一个 PDF 文件夹。

把这个石墨烯文献文件夹加入知识库，并告诉我新增、跳过和失败各有多少个文件。

把文件夹路径一起传过去；智能体会调用 kb_ingest，它支持 PDF、TXT、MD 和 DOCX。未改动的文件按 SHA-256 跳过；完全相同的副本按哈希识别，不会重复索引；只有内容变化时才会重新解析文件。

单篇论文。 给 kb_fetch 一个 DOI 或 arXiv ID，它一步完成下载和索引：

用 kb_fetch 抓取 10.5555/12345678，然后入库。

待处理文件超过 KB_ASYNC_THRESHOLD（默认 25）时，批处理会分叉成后台任务，并立即返回 job_id。用 kb_status 轮询，直到它报告 done；宿主侧超时不会中断任务。

优先用带文本层的 PDF。 扫描版 PDF 没有文本层，解析会失败并报 no text extracted；引擎不做 OCR。先把这类文件过一遍 OCR 工具，再入库结果。

提问

- 「哪些论文讨论了铜上生长石墨烯？」→ kb_search
- 「哪一页写了这个？」→ 证据上的 page 字段，或 Zotero 页面链接
- 「只从文库回答」→ 通过 kb_scope 开启严格模式（DSH）

两种检索模式，默认 quick：

- quick（默认）——快速找论文、查术语、定位段落。混合召回，不做重排、引文链接或相关工作。
- deep——跨论文比较方法、写综述、追踪引文链。在混合召回之上加一个重排器，外加引文链接和相关工作。

先用 quick。 它的职责是确认文库已建好，并能返回有据可查的段落（热态 0.2-0.4 s）；确认没问题后，再切到 deep（热态 1-2 s）做跨论文比较或引文链。可以在对话里切换，用 /kb deep 设会话默认值，或在 MCP 里传 depth: "deep"。

想要排版好的答案，就说「生成 HTML 报告」：智能体传入 answer 对象，引擎写出一个自包含 HTML 页面，旁边是此前答案的画廊。十个模板覆盖即时一屏卡片、综述、方法拆解、对比、数值发现、时间线、术语表、争议、推导和问答。见 HTML answers。

Figure 5　Three steps: build the library, ask in the chat, export a self-contained HTML answer. The index is built once.

Figure 6　Four of the ten answer templates: instant card, comparison, numeric KPIs, timeline.

HTML answers

聊天回复变长、不好扫读时，就改要一份 HTML 报告：在 DSH 里说「把这个写成可分享的 HTML 报告」，智能体会把 answer 对象传给 kb_rag。普通 kb_rag 调用只返回证据供模型作答，不写文件。页面由引擎自己排版：不调用模型，渲染示例页面耗时 2-4 ms，与检索分开计算。结果的 answer_file 对象带有 path、url、bytes、template、layout 和 warnings。

compare 答案已用英文渲染。本地化界面文案是下一版本的预览；1.6.8 发布的是中文界面。* 打开在线页面

{
"query": "graphene CVD nucleation density on copper",
"depth": "quick",
"answer": {
"template": "compare", // review is the default
"fields": {
"bottom_line": {
"text": "Pre-treatment changes nucleation density by up to two orders of magnitude; oxygen plasma gives the lowest density and the highest monolayer coverage.",
"refs": [1, 2] // 1-based indexes into this call's evidence
},
"matrix": {
"columns": [
{ "label": "Pre-treatment" },
{ "label": "Density (cm⁻²)", "num": true },
{ "label": "Monolayer coverage", "num": true }
],
"rows": [
["Mechanical polish", "10⁶–10⁷", "80–90%"],
["Electropolishing", "10⁶–10⁷", "90–95%"],
["Oxygen plasma", "10⁵–10⁶", "95–97%"]
]
},
"reading": ["Ranges come from different experiments; compare within a column, not across rows."]
}
}
}

模板。 模板决定有哪些区块、区块的顺序，以及每个区块用哪个渲染器；模板没定义的字段会被忽略，空字段会被跳过。

| template | 适用场景 | 主要字段 |
| instant | 单个问题，一屏答完 | answer、limit、followup |
| review | 综合多篇论文 | bottom_line、state、methods、limits、takeaway |
| method | 完整讲清一种方法 | what、when、steps、params、figure、caveats |
| compare | 并排对比 | bottom_line、matrix、numbers、reading |
| numeric | 重点在数字上 | bottom_line、kpis、numbers、trend、reading |
| timeline | 一条研究路线的发展过程 | bottom_line、line |
| concept | 术语与定义 | cards |
| dispute | 结论互相矛盾的论文 | bottom_line、issues |
| derivation | 推导，结果可验证 | conventions、deriv、figure、result、code、verify、pitfalls |
| qa | 用问答形式讲概念 | intro、questions、summary |

stage: "instant" 是快捷方式：选中 instant，把预算设为 300 字符，并强制 quick。layout: "doc" 把卡片布局切换成长文布局。模板没有 bottom_line，或该字段为空时，用 summary 补一句导语。
字段。 一个 section 接受字符串、{ text, refs }、数组、表格（{ columns: [{ label, num, heat, bar }], rows: [[...]] } 或 markdown 管道表格）、rank 和 kpis 用的 { items: [{ label, value, unit }] }、chart 用的 { x, series }，以及 flow 用的 { nodes, edges }。refs 是本次调用证据里的 1 起始索引；超出范围的数字会写进 warnings，渲染成没有来源的标记。数字和单位按论文原样写；坐标轴范围、刻度、条形长度、热力等级和排序都由渲染器推导，不要预先算好。字段在模板上限处截断，设置 budget.max_total_chars 时整个信封也在那里截断；每次截断都列在 warnings 里。

文件。 页面落在 ~/.kb-rag/answers/，文件名是 <date>_<question-slug>-<hash8>.html，和 index.html（最近 200 条答案的画廊，最新的在前）、index.json 放在一起。在调用里设置 answer_dir（绝对路径，或以 ~ 开头），或在环境里设置 KB_ANSWER_DIR，就能挪走这个文件夹。文件名带内容哈希，所以同一天重新渲染同一个信封只会覆盖一个文件，不会多出一个。

打开、打印、分享。 用任意浏览器打开文件即可；不需要服务器，也不需要网络。公式页面是唯一例外：它们从 jsDelivr 加载 MathJax，请求失败时回退到原始 TeX。顶部有两个按钮，分别打印或导出 PDF、把正文复制成 Markdown；Ctrl/Cmd+P 也能用，布局在手机宽度下依然撑得住。页脚最后是该答案的检索与渲染耗时：

检索 1.6 s · 渲染 12 ms

纯文本客户端仍然拿到紧凑卡片；HTML 文件是附加项，不是依赖。

颜色。 四套预设（blue、green、ink、warm）可从底部控件切换，并记在那个浏览器里。要给工作区钉一个默认值，在 .kb 旁边创建 .kb-rag/answer-theme.json；调用上的 theme 对象会覆盖它。

1.6.8 的限制。 页面外壳是中文；英文外壳计划下个版本提供。未知的 template 名称在引擎里回退到 review；DSH 工具 schema 会先拒绝它们。

| 症状 | 修复 |
| 只有文本答案，没有文件 | 没有传 answer；显式要求一份报告 |
| answer_file.ok 为 false | 错误文本会指明原因；修好后重跑 |
| 某个 section 缺失 | 它的字段为空；空 section 会被省略 |
| 字段以 … 结尾 | 字段到了上限；warnings 会说是哪一个 |
| 引用标记没有来源 | 它的 refs 数字超出本次调用的证据；warnings 会点名 |
| 英文报告里出现中文标签 | 外壳是中文；正文不变 |

工具

DSH 插件注册 10 个工具。

| 工具 | 用途 |
| kb_ingest | 导入文件或文件夹（PDF/TXT/MD/DOCX）。增量跳过、去重、按章节切块、向量化。metadata_only=true 原地刷新标题/作者/年份/期刊/DOI；rebuild=true 重新解析每个已索引文档；大批量会转入后台任务 |
| kb_status | 轮询后台任务：running 时看进度，done 时看总数和最近文件，出错时看错误信息 |
| kb_zotero | 迁移本地 Zotero 文库，含 PDF 附件 |
| kb_search | 混合检索，返回段落及其标题、作者、年份、期刊、DOI、页码和章节 |
| kb_rag | 基于证据作答，带编号引用；可选生成 HTML 答案页 |
| kb_scope | 查询范围（文库 / 文库加网络 / 网络）、严格模式、检索深度 |
| kb_dedup | 删除重复文档，保留最早的一份 |
| kb_clear | 清空所有文档和索引；需要 confirm=true |
| kb_stats | 文档、切块和向量数量，最近导入记录，模型缓存状态，过期文档 |
| kb_fetch | 按 DOI 或 arXiv ID 下载 PDF（优先出版商版本，取不到再退回开放获取版本） |

MCP 服务器同样暴露 10 个工具，包括 kb_status 和用于诊断的 kb_mcp_status。kb_scope 是 DSH 专有的，MCP 没有对应工具。MCP 里 kb_rag 默认 deep；DSH 插件默认 quick。配置和客户端片段见：mcp-server/README.md。

引擎能力

- 切块感知章节：摘要权重 1.5，方法 1.2。还能处理行内标题、摘要提升、图注块，以及非论文类文档的段落合并。
- 检索组合了 BM25（含 CJK 二元组）、bge-small 向量余弦、RRF 融合和章节权重。
- 重排用 bge-reranker-base 把前 20 条压到 3 条，取不到时退回 bge-large-en 双编码器。
- 每个段落都带 PDF 页码和章节。页码渲染为 section · p.N，可映射到 Zotero 的 ?page=N 链接。
- 正文里的 [n] 标记会解析到参考文献条目。Nature 风格的上标靠字体度量识别，所以 graphene1,2 会变成 graphene[1,2]。被引文献按 DOI、规范化标题，或第一作者加年份匹配，命中库内的会标出来。
- SHA-256 哈希跳过未改动的文件（重跑约快 40 倍），并发现跨文件夹的重复副本。
- 每个文档记录写入它的解析器版本（docs.indexed_with），kb_stats 据此报告旧版本遗留的行。
- 相同查询命中缓存。任何导入或引擎重建都会清空缓存。
- 引擎以常驻守护进程运行。模型只加载一次，崩溃后守护进程自行恢复，插件停止时释放。
- 如果文库的向量是用别的嵌入模型建的，检索会直接报错停下，不会退回关键词搜索。

查询指引

用什么语言提问都行。智能体会先把你的问题改写成英文术语串，再送到检索引擎——大多数文献库约 98% 是英文——当你想找该语言的文档时，还会附上你原话的查询。

有两件事值得做：

- 一次只问一件事，把材料、方法、属性一起说出来。这样检索效果远好于「帮我总结一下」。
- 把限制条件明说出来——「只要 2020 年以后的论文」「只限这本期刊」。智能体会把它们转成 filters，而不是塞进查询里。

背后的机制——为什么 CJK 关键词查询匹配不到英文正文、filters 支持哪些字段、lang_note 是什么意思——见 docs/DESIGN.md 第 5 节。

MCP

pip install -r mcp-server/requirements.txt
python mcp-server/server.py

在 Claude Desktop、Cherry Studio、Kimi、Cursor、DeepSeek 或其他 MCP 宿主里把它注册为 stdio 服务器。该服务器共用同一套引擎和同一个 kb.sqlite。默认使用 ~/.kb-rag，而不是 DSH 工作区的 .kb；每个工具都接受 kb_root，可指向别处。配置片段、能力隔离和超时行为见 mcp-server/README.md。

架构

DSH model / MCP client (Claude, Cherry, Kimi, Cursor, ...)
| tool call: kb_ingest / kb_search / kb_rag / kb_stats ...
v
plugin host (JS) or MCP server (server.py + engine_client.py)
| JSON lines over stdio, one request/response per line
v
kb_engine.py -- resident serve daemon (models load once)
|-- ingest: sha256 skip -> PyMuPDF extraction -> section chunking -> bge-small encode
| (committed per file; above KB_ASYNC_THRESHOLD the batch is forked as a job
| under .kb-jobs/ and a job_id is returned for kb_status to poll)
|-- search: SQL prefilter -> BM25 + vector -> RRF fusion -> bge-reranker rerank
| -> top-N verbatim passages with DOI, page, section and score
-- storage: <kb_root>/kb.sqlite (docs, chunks, vecs, cache; schema v4,
migrations gated by PRAGMA user_version)

实测性能

Windows 平台，除特别说明外均为 CPU 推理。查询数据来自一个 248 篇文档、20,760 个分块的文献库；入库数据来自一次 242 个文件、1.8 GB 的运行。

| 指标 | 结果 |
| 查询延迟（热态） | quick 0.33-0.38 s；deep 1.4-1.9 s，中位数 1.6 s |
| 冷启动首次调用 | 模型加载期间最长 8.9 s |
| 入库吞吐 | 242 个 PDF/DOCX 文件（1.8 GB）用时 85.9 s，约每篇文档 355 ms |
| 增量重跑 | 同一目录用时 2.17 s，提速 40 倍 |
| HTML 答案渲染 | 样本集中每页 2-4 ms；检索单独计时 |
| 全量重建索引（GPU） | 316 个 PDF / 23.5k 分块 / 20.1k 向量，在 8 GB 消费级 GPU 上用时 219 s，零错误 |
| 嵌入吞吐 | GPU 上 164 分块/s，CPU 上 37 分块/s（约 4.4 倍）；从批大小 32 到 256 基本持平，说明分词是瓶颈 |
方法论与设计思路：docs/DESIGN.md。

设备处理（GPU / CPU）

入库和搜索共用同一个嵌入模型。默认自动使用 CUDA 版 torch（KB_DEVICE=auto）。

- 首次加载模型前，先用一次小矩阵乘法探测设备。驱动可能报告有 GPU，但第一个 kernel 就失败，所以探测能提前发现这种情况，回退到 CPU，并给出可读的原因。KB_GPU_PROBE=0 跳过探测。
- 调用过程中设备出错时降级处理，不中止：批次减半，再降到 4，然后把模型移到 CPU 跑完这次调用。能跑通的批次大小会被记住。非设备类错误原样抛出。
- 修好驱动后，用 reload 重置设备判定。drop_models=true 把模型重新加载到 GPU，不用重启宿主。
- 批次大小取决于设备和空闲显存。KB_EMBED_BATCH / KB_RERANK_BATCH 可以覆盖，但调大对小模型没有加速效果。
- 纯 CPU 下嵌入这一步大约慢 4 倍。PDF 提取、分块和 BM25 无论如何都受限于 CPU。

kb_stats 在 device 里报告结果；发生回退时还会带上 gpu_disabled_reason 和 note。

配置

| 变量 | 默认值 | 适用对象 | 说明 |
| KB_EMBED_MODEL | BAAI/bge-small-zh-v1.5 | 引擎 | 嵌入模型，首次使用时下载到 Hugging Face 缓存 |
| KB_RERANK_MODEL | BAAI/bge-reranker-base | 引擎 | 重排模型 |
| KB_DEVICE | auto | 引擎 | auto 使用可用的 CUDA 设备；cpu / cuda / cuda:1 / mps 强制指定。设备出错时回退到 CPU |
| KB_GPU_PROBE | 1 | 引擎 | 0 跳过一次性探测「这台设备能不能算？」 |
| KB_EMBED_BATCH | GPU 128 / CPU 32（低于 8 GB 时分级下调） | 引擎 | 入库和搜索的嵌入批次大小 |
| KB_RERANK_BATCH | GPU 64 / CPU 16（低于 8 GB 时分级下调） | 引擎 | 重排批次大小 |
| KB_MODEL_RETRY_SECS | 120 | 引擎 | 模型加载失败后记住多久再重试（0 = 每次调用都试，负数 = 永不重试） |
| HF_ENDPOINT | 无 | 引擎 | 网络受限时用 https://hf-mirror.com |
| KB_HF_MIRROR_FIRST | 关 | 引擎 | 1 先试镜像再直连下载 |
| KB_AUTO_PIP | 0 | npm 包 | 1 在启动时安装缺失的 Python 依赖（固定 argv）；默认只打印命令 |
| KB_RAG_ROOT | DSH：工作区 .kb；MCP：~/.kb-rag | MCP | 知识库目录；单次调用可用 kb_root 覆盖 |
| KB_RAG_PYTHON | 当前解释器 | MCP | 引擎使用的解释器 |
| KB_ASYNC_THRESHOLD | 25 | 引擎 | 待处理文件超过这个数时，kb_ingest 派生后台任务 |
| KB_SQLITE_WAL | 关 | 引擎 | 1 启用 SQLite WAL；.kb 会被同步时默认值更安全 |
| UNPAYWALL_EMAIL | 内置占位地址 | 引擎 | kb_fetch 中 Unpaywall 的联系地址；请换成你自己的 |
工作区文件 .kb-rag/engine.env（KEY=VALUE，每行一项）会在启动时合并进引擎的环境变量；显式设置的环境变量优先。想给某个库固定模型或镜像，又不想改系统设置，用这个文件最省事。

仓库结构

kb-rag/
├─ kb_engine.py Python engine: chunking, retrieval, reranking, serve daemon
├─ install.cmd Windows entry point (runs scripts\install.ps1)
├─ scripts/ Installer scripts (install.ps1, install.sh)
├─ plugin/ DSH dynamic plugin (kbrag.plugin.json, host.js, client.js)
├─ npm-package/ npm package dsh-kb-rag (published contents, cordis.patch.yml)
├─ dsh-kb-rag-install/ Micro-package for the bare npx dsh-kb-rag-install command
├─ mcp-server/ MCP server (server.py, engine_client.py)
├─ docs/ DESIGN.md, OUTPUT-FORMAT.md, MIGRATION.md, BACKLOG.md
├─ tests/ Engine and client test suites

├─ tools/ Internal maintenance scripts (not published)
└─ QUICKSTART.md, CHANGELOG.md, SECURITY.md, UNINSTALL.md, LICENSE

Runtime data: the DSH plugin writes to .kb/kb.sqlite in the session workspace; the MCP server defaults to ~/.kb-rag/kb.sqlite. Background job files live in <kb_root>/.kb-jobs/ and are removed when a job finishes.

Known limitations

- Scanned PDFs are not supported. Documents without a text layer are skipped; OCR is out of scope.
- Page anchors are PDF-only. TXT, MD and DOCX files, and documents indexed before schema v3, fall back to section-level location until re-ingested with force.
- Citation linking requires a re-ingest. Superscript detection and reference splitting run at parse time.
- Metadata is only as good as the PDF. It is never 100% accurate; when it is missing, title and year are judged from the cover page, and existing Zotero metadata is preferred.
- Captions are searchable as text; content that exists only inside a figure is not.
- Keyword matching is in memory. Beyond a few hundred thousand chunks, FAISS HNSW or SQLite FTS5 would be the next step.
- Some publishers redirect automated PDF requests to a login page. kb_fetch reports the failure and leaves the manual path (download, then kb_ingest) as the fallback.

Documentation

| Document | Contents |
| QUICKSTART.md | Five-minute setup |
| docs/DESIGN.md | Storage model, chunking, retrieval pipeline, engine protocol |
| docs/OUTPUT-FORMAT.md | Output and citation conventions |
| docs/MIGRATION.md | Schema migration, v1 through v4 |
| docs/UPGRADE-1.6.8.md | Upgrading from 1.6.7 when the plugin panel quotes the installed version |
| docs/MIGRATION-1.6.8.md | Migration notes for existing users (Chinese) |
| docs/TROUBLESHOOTING.md | Symptom-to-fix table and the before-report checklist |
| docs/BACKLOG.md | Known gaps and how to verify a change |
| mcp-server/README.md | MCP configuration, tool mapping, timeouts |
| npm-package/README.md | npm installation and troubleshooting |
| SECURITY.md | Execution model and security boundaries |
| UNINSTALL.md | Removal, leaving PDFs and Zotero untouched |
| CHANGELOG.md | Release history |

Contact

- Bugs and feature requests: GitHub Issues
- Questions: GitHub Discussions
- Security: see SECURITY.md

License

MIT. The BAAI/bge-* models are downloaded at runtime and remain under their own licences.