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？

| 能力 | 带来的变化 |
| --- | --- |
| 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 | error: { code, message, hint } }。 |
| SQLite 原生索引 | sqlite-vec KNN + FTS5 全文（每库一个 kb.db）；无需外部向量库进程。 |
| CJK 感知分词 | Intl.Segmenter（内置、零依赖）为 BM25 切分中日韩文本。 |
| 混合检索 | 向量 + BM25 → RRF → 可选 rerank；rerank 状态显式标注 applied | fallback_rrf | disabled——降级不静默。 |
| 异步 Job 系统 | 导入/重建立即返回 job_id；get_job 轮询进度；崩溃恢复（JOB.INTERRUPTED）+ 协作式取消。 |
| 导入路径白名单 | 仅允许白名单内路径（默认：会话 workspace + /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[分块Intl.Segmenter CJK]
C --> D[向量化bge-small-zh / mock]
D --> E[向量索引sqlite-vec KNN]
C --> F[FTS5 BM25]
E --> G[混合检索]
F --> G
G --> H[RRF]
H --> I[可选 rerankapplied / 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 + /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