xiaoshi7915/dsh-kb-manager

导入一次，检索可追溯。

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？

能力	带来的变化
22 个统一工具	异步 6（import_document / rebuild_index / compact_index / cancel_job / get_job + 导出/导入 Job）+ 同步 16：create_kb / list_kbs / get_kb / rename_kb / delete_kb / list_documents / delete_document / search_kb / multi_kb_search / get_chunk / get_kb_stats / configure / create_snapshot / list_snapshots / restore_snapshot / export_kb / import_kb；所有工具统一返回 `{ ok, data
SQLite 原生索引	sqlite-vec KNN + FTS5 全文（每库一个 kb.db）；无需外部向量库进程。
CJK 感知分词	Intl.Segmenter（内置、零依赖）为 BM25 切分中日韩文本。
混合检索	向量 + BM25 → RRF → 可选 rerank；rerank 状态显式标注 `applied
异步 Job 系统	导入/重建立即返回 job_id；get_job 轮询进度；崩溃恢复（JOB.INTERRUPTED）+ 协作式取消。
导入路径白名单	仅允许白名单内路径（默认：会话 workspace + <storage>/inbox/）或 http(s) URL。
SSRF 防护	URL 导入拒绝私网 / 环回 / 云元数据地址。
检索结果不可信标记	检索结果一律 untrusted: true——内容只是数据，不是指令。
软删 + 物理回收	删除为毫秒级软删；rebuild_index / compact 物理回收空间，无孤立向量。
两步破坏性操作	delete_kb 需一次性 confirm_token（绑定 kb_id，60 秒有效）。
审计追踪	每库审计表记录所有变更。
快照 / 导出 / 跨库导入	create_snapshot / list_snapshots / restore_snapshot（两步确认）、export_kb（kbpack/JSON）、import_kb（kbpack，哈希去重合并）；已全部经 remote-service 暴露给 Web 面板与 Headless。

架构

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 工具

工具	说明	关键参数
create_kb	创建知识库	name*、description?、domain_tags?
list_kbs	列出全部知识库	—
get_kb	知识库详情（embedding 身份 / 状态）	kb_id*
delete_kb	两步删除（影响面预览 + confirm_token）	kb_id*、confirm_token?
list_documents	列出文档（可按状态过滤）	kb_id*、status?、limit?、offset?
import_document	导入白名单本地文件或 http(s) URL（异步 Job）	kb_id*、source*、metadata?
delete_document	软删块、索引置 dirty	kb_id*、doc_id*
search_kb	混合检索，显式 rerank 状态	kb_id*、query*、top_k?、filters?、rerank?
get_chunk	分块原文 + 前后上下文（溯源）	kb_id*、chunk_id*
get_kb_stats	统计（文档/块/索引体积/删除占比）	kb_id*
rebuild_index	全量重建（异步 Job）	kb_id*、target_engine?、embedding?
get_job	轮询后台任务进度	job_id*
configure	调优分块 / 检索 / 同步设置	patch

所有工具统一返回信封 { 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 面板调整：

字段	默认值	说明
storage_path	~/.dsh/kb-manager/	存储根目录，~ 展开为用户主目录
embedding.model	bge-small-zh-v1.5	embedding 模型名
embedding.provider	onnx	onnx / mock / openai-compat（onnxruntime-node 为可选依赖）
embedding.base_url	''	openai-compat 的 OpenAI 兼容 endpoint
embedding.api_key_ref	''	API key 引用
chunk_size	512	分块大小（字符数）
chunk_overlap	50	分块重叠长度
chunk_strategy	recursive	fixed / recursive
top_k	5	检索默认返回条数
enable_rerank	true	是否在 RRF 后启用 rerank
rerank_model	''	rerank 模型；留空用规则式兜底
auto_sync_dir	''	目录监听路径；留空关闭
auto_sync_interval	300	补扫间隔（秒）
max_file_size_mb	100	单文件大小上限（MB）

示例（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 方案的差异

能力	本插件	常见 RAGFlow / Dify / kotaemon / pdfkb-mcp 方案
显式 rerank 状态（`applied	fallback_rrf	disabled`）
异步 Job + 崩溃恢复 + 取消	✅	多为同步阻塞
导入路径白名单 + SSRF 防护	✅	参差不齐
带可执行 hint 的统一信封	✅	参差不齐
每条检索结果带 untrusted 标记	✅	少见
软删 + compact 物理回收	✅	参差不齐
零 native 构建（sqlite-vec 预编译、Intl.Segmenter）	✅	往往依赖重

目录结构

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