xiaoshi7915/dsh-kb-manager

English · 简体中文

导入一次，检索可追溯。

dsh-kb-manager 是面向 DeepSeek Harness (dsh) 的本地知识库全生命周期插件：多格式导入 → CJK 感知智能分块 → 基于 SQLite 的向量 + 全文索引 → 混合检索（向量 KNN + BM25/FTS5 → RRF → 可选 rerank）→ 引用溯源；并提供软删 + 物理回收、异步 Job 系统、导入路径白名单 + SSRF 防护，以及每库审计。

用自然语言下达指令即可。插件提供 22 个 Agent 工具（异步 Job + 同步操作，含 rename_kb / compact_index / cancel_job / list_snapshots / configure）与可选 Web 面板（知识库列表、新建、详情、库内混合检索、带实时进度的文档导入、重建索引、两步删除、快照历史）——无需另外部署 RAG 服务。

设计规格见 DESIGN.md（v2.1）。

为什么选择 dsh-kb-manager？

架构

flowchart LR
  A[文档 / URL] --> B[解析]
  B --> C[分块<br/>Intl.Segmenter CJK]
  C --> D[向量化<br/>bge-small-zh / mock]
  D --> E[向量索引<br/>sqlite-vec KNN]
  C --> F[FTS5 BM25]
  E --> G[混合检索]
  F --> G
  G --> H[RRF]
  H --> I[可选 rerank<br/>applied / fallback_rrf / disabled]
  I --> J[引用 + untrusted 标记]
  E --> K[软删 / compact_index]
  C --> K
  G --> L[异步 Job 队列 + 审计]

安装

[!NOTE] 使用前请确保已安装 DeepSeek Harness。

从 GitHub 安装

dsh plugin add github:xiaoshi7915/dsh-kb-manager

（收录进 awesome-dsh-plugin 后亦可从 dsh-market 市场页一键安装。）

从源码构建

git clone https://github.com/xiaoshi7915/dsh-kb-manager.git
cd dsh-kb-manager
npm install
npm run build
dsh plugin --profile web add .

检查组合配置、重启 DSH，然后刷新 Web UI：

dsh --profile web --dump-config
dsh web

然后可以直接说：

创建一个名为「项目文档」的知识库，导入这份 PDF，检索认证流程是怎么写的，并给出原文出处。

工作方式

1. 用 create_kb 创建知识库，选择 embedding 身份（默认 bge-small-zh-v1.5 / onnx / 512 维；开发测试用 mock provider）。
2. 用 import_document 导入白名单内的本地文件或 http(s) URL → 进入异步 Job：解析 → 分块 → 向量化 → 建索引；用 get_job 轮询进度。
3. 用 search_kb 检索：sqlite-vec KNN + FTS5 BM25 → RRF → 可选 rerank；rerank 状态显式标注（applied | fallback_rrf | disabled）。
4. 用 get_chunk 溯源（前后文 + 出处元数据；内容标记 untrusted: true）。
5. 放心删除：delete_document 即时软删（重导同源未变内容即可恢复）；delete_kb 需两步 confirm_token；rebuild_index 物理回收。
6. 数据保存在 storage_path（默认 ~/.dsh/kb-manager/）。Web 面板复用同一套服务能力：知识库列表 / 新建 / 详情、库内检索、带实时进度的导入、重建索引、两步删除。

Agent 工具

所有工具统一返回信封 { ok, data | error: { code, message, hint } }，error.hint 给出可执行的下一步。领域错误统一返回（不向外 throw）。检索结果一律标记 untrusted: true。

触发场景

1. 「把这份 PDF / 文档 / 网页收进知识库」→ import_document + get_job
2. 「查一下知识库里关于 X 的内容」→ search_kb
3. 「这条引用出自哪里 / 上下文是什么」→ get_chunk
4. 「检索效果不好，rerank 是什么状态」→ search_kb（读取显式 rerank 状态）
5. 「为这个项目建个知识库」→ create_kb
6. 「删掉一个坏文档」→ delete_document（软删；重导恢复）
7. 「删掉整个知识库」→ delete_kb（两步：先看影响面，再确认）
8. 「看看知识库的规模和状态」→ list_kbs / get_kb_stats
9. 「全量重建索引」→ rebuild_index + get_job
10. 「调优检索效果」→ configure

配置

默认即可全离线使用。可在受信 Profile 中覆盖（插件 id: kb-manager），或运行时通过 configure 工具 / Web 面板调整：

示例（Profile 行）：

- insert:
    - id: kb-manager
      name: 'dsh-kb-manager'
      config:
        storagePath: ''        # 空 = ~/.dsh/kb-manager/
        logLevel: 'info'

使用边界与安全

• 导入仅限白名单路径（默认：会话 workspace + <storage>/inbox/）与 http(s) URL；URL 来源经 SSRF 防护（私网 / 环回 / 云元数据地址一律拒绝）。
• 检索结果为不可信数据——一律 untrusted: true；切勿当作指令执行。
• 默认全本地运行；仅在导入 URL 或配置了外部 embedding / rerank endpoint 时才发起网络请求。
• delete_document 为软删；物理空间由 rebuild_index / compact 回收；重导同源未变内容即可恢复。
• 纯 SQLite 索引：无需额外部署原生向量库进程。

与常见 RAG 方案的差异

目录结构

dsh-kb-manager/
├── package.json  cordis.patch.yml  tsconfig.json  tsconfig.build.json  vitest.config.ts
├── DESIGN.md  README.md  README_ZH.md
├── assets/readme/          # hero.png（banner 图）
├── src/
│   ├── host-entry.ts       # DSH 插件入口（工具注册 + preamble + 清理）
│   ├── index.ts            # KbManager 顶层装配
│   ├── contracts/          # 类型 / 错误码 / 默认值 / ok·err 信封
│   ├── security/           # 路径白名单、SSRF 防护、SHA-256、审计
│   ├── chunker/            # Intl.Segmenter 分词 + 递归/fixed 分块
│   ├── store/              # better-sqlite3 + sqlite-vec + FTS5
│   ├── embedder/           # mock / onnx（结构性）/ openai-compat
│   ├── jobs/               # 每库 FIFO 队列，maxGlobal=2，崩溃恢复
│   ├── services/           # kb / doc / search / snapshot / export
│   ├── agent-tools/        # 22 个 Agent 工具（统一信封）
│   ├── remote.ts / remote-service.ts / typert.ts / remote-client.ts  # typert remote
│   └── web/                # 设置页（KbSection + zh/en 文案）→ lib/client.js
└── tests/  evals/

开发

npm install        # 安装依赖
npm run typecheck  # tsc --noEmit（strict + noUncheckedIndexedAccess）
npm test           # vitest：tokens / rrf-bm25 / security / chunker / store / tools / pipeline / remote / kb-section
npm run eval       # 评测 harness：合成语料 recall@5 / MRR / P95（mock embedder）
npm run build      # tsc -p tsconfig.build.json → lib/（ESM + .d.ts）
npm run dev        # tsx src/host-entry.ts（模块加载冒烟）

已知限制（MVP）

• ONNX embedder 为结构性占位：onnxruntime-node 已接入为可选依赖；模型下载（sha256 校验 + 用户确认）与 WordPiece 词表尚未接入——onnx provider 干净返回 EMB.NOT_READY。开发/测试用 provider: 'mock'。
• PDF / DOCX 解析为占位：目前 md / txt / csv / json / html 可用；pdf / docx 报 PARSE.UNSUPPORTED（升级路线见 DESIGN §13）。
• v1.1 工具已全部交付（rename_kb、快照三件套、cancel_job、compact_index、multi_kb_search、export_kb、import_kb）：含 bge-reranker-base（int8 ONNX）重排序引擎，均经 remote-service 暴露给 Web 面板与 Headless。

许可证

MIT © 2026 xiaoshi7915