接入你的智能体
发布者自己的命令。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
npx -y [email protected]Claude Code 没有针对本地命令的安装链接。复制下方命令并在终端中运行。
claude mcp add dsh-kb-rag -- npx -y dsh-kb-rag@1.6.8在终端中运行。
{ "mcpServers": { "dsh-kb-rag": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
远程 URL 还是本机命令？ 两种安装方式的区别
English | Chinese
kb-rag is a local literature knowledge base for DSH (DeepSeek Harness) and other MCP clients. It indexes PDFs and Zotero libraries into one SQLite file, then returns the passages that answer a question. Each result carries its section, physical page and DOI, and the citations attached to that passage, including whether the cited work is already in your library.
Indexing, embedding and reranking run on your machine. There is no API cost and nothing is uploaded. Warm queries take 0.33-0.38 s in quick mode and 1.4-1.9 s in deep; the first call after a restart can take up to 8.9 s while the models load.
The npm package dsh-kb-rag is published from npm-package/. One-page overview: docs/promo.html. Forks and similarly named repositories are not release sources; the canonical repository is Breeze136/dsh-kb-rag.
A kb_rag call returns evidence in this shape. The interface is in Chinese today, so the block below is a translation. [in-library] marks a cited work that is already indexed.
**Knowledge base sources Top-2**
deep · reranked with BAAI/bge-reranker-base · cache hit
1. [Chemical vapour deposition of graphene on copper substrates](https://doi.org/10.5555/12345678) — 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](https://doi.org/10.5555/12345684) (Author C · 2010 · Carbon) (this evidence's Ref 4) · [open in Zotero](zotero://open-pdf/library/items/EXAMPLEKEY1)
· 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)
Authors, journals and DOIs are placeholders; the format is real. The full walkthrough is in docs/OUTPUT-FORMAT.md.
A passage keeps the citation marks printed in the PDF. kb-rag resolves each mark against the
library, so [4, 7] becomes two entries: one you already hold, with its own page number, and
one that is still outside — a lead to fetch rather than a dead end.
Add an outside reference — by DOI with kb_fetch, or by dropping the PDF into the folder and
ingesting again — and its own reference list enters the next search. The same question then
returns more evidence and a longer chain to follow. Indexing stays incremental: unchanged files
are skipped, nothing is rebuilt.
1.6.8 fixes two things that broke the DSH 0.2 install: the peer range and the client injection list. With both wrong, the plugin was rejected during install and the tool cards stayed empty.
The release also adds HTML answer pages rendered by the engine and a title-level probe. kb_stats now reports model cache state, and deep searches return no_hit when the best reranked score stays below the floor. The search core is otherwise unchanged: on the same library, results line up with 1.6.7. The full list is in CHANGELOG.md.
kb-rag runs in the DSH desktop app. Install it from the plugin panel. The command-line routes exist for maintainers and old web deployments; new users do not need them.
kb-rag. The package is dsh-kb-rag, and the entry should say 1.6.8.The desktop app needs to be 0.2 or newer. 1.6.7 and earlier fail that version's compatibility check; 1.6.8 is the first release that passes it.
The first search downloads the two models (~1.2 GB). This is the step most likely to stall. Let the plugin fetch them, or pre-download to a directory you choose:
[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')"
Install sentence-transformers first if Python reports it missing. kb_stats reports whether both models are cached. If the default download stalls, set HF_ENDPOINT=https://hf-mirror.com and KB_HF_MIRROR_FIRST=1, restart DSH, and retry. Full notes: docs/MIGRATION-1.6.8.md.
Already on 1.6.7? The plugin panel checks the installed 1.6.7 manifest, so installing 1.6.8 can fail with an error that quotes 1.6.7. Uninstall 1.6.7 first, then install 1.6.8.
The web profile is not a supported install target. Install the DSH desktop app, then follow A. The knowledge base (.kb) stays where it is; only the plugin host changes. Remove the old web-profile copy so the two do not drift:
dsh plugin --profile web remove dsh-kb-rag
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
If your desktop build cannot search npm, install dsh-plugin-registry once and use its marketplace panel. kb-rag is listed there.
[!WARNING] Do not run
npm install dsh-kb-raginside a DSH profile. It writes an npm-stylenode_modulesnext to pnpm's symlink store, and laterdsh pluginoperations become unpredictable.npm installis only for a deployment you manage by hand; see npm-package/README.md.
Details and the before-report checklist: docs/TROUBLESHOOTING.md.
Three ways in, depending on where the paper lives right now:
Zotero library (do this first). Preview before syncing, so a whole library does not move in by accident:
Show me which Zotero items with PDF attachments can be ingested, without running it yet.
That is kb_zotero(dry_run=true). Drop dry_run to run it; add async_mode=true for a whole-library migration. Zotero's title, authors, year, journal and DOI are written into the search results; items without a local PDF attachment are skipped, and nothing is downloaded for you. If auto-detection fails, pass the zotero.sqlite path explicitly.
A folder of PDFs.
Add this graphene literature folder to the knowledge base and tell me how many files were added, skipped and failed.
Pass the folder path along; the agent calls kb_ingest, which handles PDF, TXT, MD and DOCX. Unchanged files are skipped by SHA-256; identical copies are recognised by hash and not indexed twice; a file is only re-parsed when its content changes.
A single paper. Give kb_fetch a DOI or arXiv ID and it downloads and indexes in one step:
Use kb_fetch to fetch 10.5555/12345678, then ingest it.
Above KB_ASYNC_THRESHOLD (default 25) pending files, the batch forks into a background job and returns a job_id immediately. Poll it with kb_status until it reports done; a host-side timeout does not interrupt the job.
Prefer PDFs that have a text layer. A scanned PDF has none, so parsing fails with no text extracted; the engine does not OCR. Run such files through an OCR tool first, then ingest the result.
kb_searchpage field on the evidence, or the Zotero page linkkb_scope (DSH)Two retrieval modes, quick by default:
quick (default) — find papers, look up terms, locate a passage fast. Hybrid recall, with no reranking, citation linking or related work.deep — compare methods across papers, build a review, follow a citation chain. Adds a reranker on top of hybrid recall, plus citation links and related work.Start with quick. Its job is to confirm the library is built and returns grounded passages (0.2-0.4 s warm); once that checks out, switch to deep (1-2 s warm) for cross-paper comparison or citation chains. Switch in the conversation, set a session default with /kb deep, or pass depth: "deep" in MCP.
For a formatted answer, say "generate an HTML report": the agent passes an answer object and the engine writes a self-contained HTML page next to a gallery of earlier answers. Ten templates cover an instant one-screen card, a review, a method breakdown, a comparison, numeric findings, a timeline, a glossary, disputes, a derivation, and Q&A. See HTML answers.
When a chat reply gets long and hard to scan, ask for an HTML report instead: in DSH, say "write this up as a shareable HTML report" and the agent passes an answer object to kb_rag. A plain kb_rag call returns evidence for the model to answer from and writes no file. The engine lays out the page itself: there is no model call, and rendering the sample pages takes 2-4 ms, separate from retrieval. The result's answer_file object carries path, url, bytes, template, layout and warnings.
Rendered compare answer in English. The localized chrome is a preview of the next release; 1.6.8 ships Chinese chrome. Open the live page
{
"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."]
}
}
}
Templates. The template fixes the sections, their order and each block's renderer; fields it does not define are ignored, and empty ones are skipped.
stage: "instant" is a shortcut: it selects instant, sets a 300-character budget, and forces quick. layout: "doc" switches from the card layout to long-form. summary supplies a one-line lead when the template has no bottom_line, or that field is empty.
Fields. A section takes a string, { text, refs }, an array, a table ({ columns: [{ label, num, heat, bar }], rows: [[...]] } or a markdown pipe table), { items: [{ label, value, unit }] } for rank and kpis, { x, series } for chart, and { nodes, edges } for flow. refs are 1-based indexes into this call's evidence; a number outside that range is reported in warnings and renders as a marker with no source. Write numbers and units as the paper gives them; the renderer derives axis ranges, ticks, bar lengths, heat levels and sort order, so do not pre-compute them. Fields are clipped at the template limit, and the whole envelope at budget.max_total_chars when set; every clip is listed in warnings.
Files. Pages land in ~/.kb-rag/answers/ as <date>_<question-slug>-<hash8>.html, next to index.html (a gallery of the latest 200 answers, newest first) and index.json. Set answer_dir on the call (an absolute path, or one starting with ~), or KB_ANSWER_DIR in the environment, to move the folder. The filename carries a content hash, so re-rendering the same envelope on the same day overwrites one file instead of adding another.
Open, print, share. Open the file in any browser; it needs no server and no network. Formula pages are the one exception: they load MathJax from jsDelivr and fall back to raw TeX if that request fails. Two buttons at the top print or export to PDF and copy the body as Markdown; Ctrl/Cmd+P works too, and the layout holds down to phone width. The footer ends with the retrieval and render time for that answer:
检索 1.6 s · 渲染 12 ms
Text-only clients still get the compact card; the HTML file is an addition, not a dependency.
Colours. Four presets (blue, green, ink, warm) are switchable from a control at the bottom and are remembered in that browser. To pin a default for the workspace, create .kb-rag/answer-theme.json next to .kb; a theme object on the call overrides it.
Limits in 1.6.8. The page chrome is Chinese; English chrome is planned for the next release. Unknown template names fall back to review in the engine; the DSH tool schema rejects them first.
The DSH plugin registers 10 tools.
The MCP server exposes 10 tools as well, including kb_status and a diagnostic kb_mcp_status. kb_scope is DSH-specific and has no MCP equivalent. MCP keeps kb_rag's default at deep; the DSH plugin defaults to quick. Configuration and client snippets: mcp-server/README.md.
section · p.N and maps onto Zotero's ?page=N link.[n] markers resolve to reference entries. Nature-style superscripts are detected from font metrics, so graphene1,2 becomes graphene[1,2]. Cited works are matched by DOI, normalised title, or first author plus year, and in-library matches are marked.docs.indexed_with), so kb_stats can report rows an older revision left behind.Ask in whatever language you think in. The agent rewrites your question into an English term string before it reaches the engine — most libraries are around 98% English — and adds a query in your own words when you want documents in that language.
Two things are worth doing:
filters rather than stuffing them into the query.The mechanics — why a CJK keyword query cannot match English body text, which fields filters supports, what lang_note means — are in docs/DESIGN.md, section 5.
pip install -r mcp-server/requirements.txt
python mcp-server/server.py
Register it as a stdio server in Claude Desktop, Cherry Studio, Kimi, Cursor, DeepSeek or another MCP host. The server shares the same engine and the same kb.sqlite. By default it uses ~/.kb-rag rather than the DSH workspace .kb, and every tool accepts kb_root to point elsewhere. See mcp-server/README.md for config snippets, capability quarantine and timeout behaviour.
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 inference unless noted. Query numbers come from a 248-document / 20,760-chunk library; ingest numbers from a 242-file / 1.8 GB run.
Methodology and design rationale: docs/DESIGN.md.
Ingestion and search share one embedding model. A CUDA build of torch is used automatically (KB_DEVICE=auto, the default).
KB_GPU_PROBE=0 skips the probe.reload resets the device verdict after a driver fix. drop_models=true reloads the models onto the GPU without restarting the host.KB_EMBED_BATCH / KB_RERANK_BATCH override them, but raising them does not speed up small models.kb_stats reports the outcome in device, including gpu_disabled_reason and note when a fallback happened.
A workspace file .kb-rag/engine.env (KEY=VALUE, one per line) is merged into the engine's environment at startup; explicit environment variables win. It is the practical way to pin a model or mirror per library without editing system settings.
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.
force.kb_fetch reports the failure and leaves the manual path (download, then kb_ingest) as the fallback.MIT. The BAAI/bge-* models are downloaded at runtime and remain under their own licences.
Literature knowledge base for DSH and MCP clients. Index PDFs or a Zotero library into one SQLite file; search and RAG tools return passages with section, page and DOI. Embedding and reranking run loc
{ "mcpServers": { "dsh-kb-rag": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}概览
Literature knowledge base for DSH and MCP clients. Index PDFs or a Zotero library into one SQLite file; search and RAG tools return passages with section, page and DOI. Embedding and reranking run locally.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Dsh Kb Rag 通过 stdio 在本地运行。
上次检查时间：2026-11-15。 Literature knowledge base for DSH and MCP clients. Index PDFs or a Zotero library into one SQLite file; search and RAG tools return passages with section, page and DOI. Embedding and reranking run locally.