前言¶
在 DeepSeek Harness（DSH）里给模型接文档，常见做法是装带 RAG 能力的插件，让会话里能检索本地资料并给出出处。社区里已有 dsh-kb-rag 等方案；据插件 README 说明，在 DSH 0.2.0-rc.2 上会因客户端注入依赖与 peer 版本范围无法安装。dsh-kb-lite（维护者 imaused）走另一条路：仅 Host 侧工具、无客户端 bundle、无浏览器 UI，索引与检索在本地目录完成，BM25 只依赖 Python 标准库即可工作。下面介绍它是什么、怎么装、五个工具怎么用。
这是什么¶
dsh-kb-lite 是 DSH 的「记忆」类插件：把 Markdown、纯文本和 PDF ingest 到本地索引，用 BM25 或可选的稠密向量检索片段，并通过 path、heading、行号或 PDF 页码等形式把引用交给模型。引擎不监听端口，不单独起数据库服务；一个知识库对应一个目录（默认 ~/.kb-lite）。许可证为 MIT，当前 package 版本为 0.1.0。
与完整 RAG 栈相比，范围刻意收窄：五个工具、一个索引目录、在无 torch 的机器上也能跑 BM25 路径。
核心功能¶
据 README 与 package.json 描述，能力包括：
- 五个 Host 工具：
kb_ingest（建索引）、kb_search（带得分的片段）、kb_ask（在字符预算内返回原文段落供引用，不改写）、kb_stats（文档/块数量与部分路径列表）、kb_clear（删除索引）。 - 输入格式：
.md、.markdown、.txt、.pdf。PDF 需要pymupdf；未安装时单文件报错，同批其余文件仍可索引。目录遍历会跳过隐藏目录以及.git、node_modules、.venv、__pycache__等。 - 增量索引：按文件
sha256跳过未变更文件；force: true强制重解析。单次max_files有上限，超出部分以pending返回，下次调用继续。 - 检索模式：纯 Python BM25（含 CJK 二元分词）；可选
sentence-transformers+ 默认模型BAAI/bge-small-zh-v1.5的稠密检索；hybrid用 reciprocal rank fusion 融合两者。kb_search的mode可为auto、bm25、dense、hybrid。 - 无客户端字段：
package.json不含dsh.client，仅增加 Host 工具，避免客户端 API 变更拖垮整个 Web UI。
安装与启用¶
在 DSH 所在环境执行（web 可换成你的 profile，例如 desktop）：
dsh plugin --profile web add dsh-kb-lite
或从 GitHub 安装：
dsh plugin --profile web add github:imaused/dsh-kb-lite
安装后需重启 DSH 并新建会话；工具在会话创建时绑定，已打开的会话看不到新工具。
可选环境变量（在启动 DSH 之前设置，而非在会话内）：
| 配置 | 默认 | 作用 |
|---|---|---|
KB_LITE_PYTHON |
未设置时依次尝试 python、python3、py |
运行引擎的 Python 解释器 |
KB_LITE_ROOT |
~/.kb-lite |
未传 kb_root 时的默认知识库目录 |
KB_LITE_MODEL |
BAAI/bge-small-zh-v1.5 |
稠密检索用的嵌入模型 |
单次调用可通过参数 kb_root 覆盖默认目录；优先级为：本次 kb_root > KB_LITE_ROOT > ~/.kb-lite。
典型用法¶
README 建议用对话里明确写出工具名与参数，便于稳定触发调用。
1. 索引文档目录
kb_ingest 的 paths 必须是绝对路径；相对路径不会按当前工作目录解析。
Ingest D:/docs into the knowledge base with kb_ingest: paths ["D:/docs"], recursive: true, max_files: 50.
返回中会包含 added/updated/skipped、逐文件 errors，以及超过上限时的 pending。
2. 带引用的问答素材
Answer from the knowledge base with kb_ask: query "how does the retry policy back off", top_k: 5, max_chars: 6000. Quote the passages and cite path and line numbers.
3. 仅用 BM25 对比检索行为
Use kb_search with query "BM25 k1 b", top_k: 8, mode: "bm25".
4. 查看索引概况
Run kb_stats and tell me the kb_root, document count, chunk count, whether dense is available, and the indexed paths.
5. 清空试验索引
kb_clear 会删除该 kb_root 下的 manifest.json、chunks.jsonl 及向量文件，不删源文档。
Use kb_clear with kb_root "D:/kb/scratch" and confirm: true.
常用默认值（README）：recursive: true，max_files: 50（1–500），with_embeddings: "auto"，kb_search 的 top_k 默认 8，kb_ask 默认 5，max_chars 默认 6000。
适用场景与注意¶
适合需要在 DSH 0.2.0-rc.x 一类 Host 上、本机离线建库、并希望引用落到文件与行号/页码的开发者。若只需关键词检索，可不装 sentence-transformers；要稠密或 hybrid，需在 ingest 前装好依赖并对旧索引 force: true 重 ingest 或先 kb_clear。
DSH 插件以当前 dsh 进程权限运行；kb_ingest 能读到的路径即进程能访问的路径。安装前建议在 GitHub 阅读源码与 MIT 许可证，确认符合你的安全与合规要求。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
若日后出现面向 0.2.x、且不注入 dsh-client-runtime 的 dsh-kb-rag 版本，功能面会与本文插件有较大重叠；选型时可对照依赖与 peer 范围，不必固守单一插件。
结尾¶
dsh-kb-lite 用五个 Host 工具把「入库—检索—可引用原文—统计—清空」收在本机目录里，BM25 零额外依赖即可用，需要时再叠稠密与 hybrid。目录页：https://www.skillhub.cn/plugins/imaused/dsh-kb-lite；源码与完整说明：https://github.com/imaused/dsh-kb-lite。
