English · 简体中文
## 导入一次，检索可追溯。
`dsh-kb-manager` 是面向 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 的本地知识库全生命周期插件：多格式导入 → 智能分块 → 纯 TypeScript 向量索引 → 混合检索（向量 + BM25 → RRF → 可选 rerank）→ 引用溯源；并提供快照/回滚、目录监听增量同步，以及可携带的 `.kbpack` 便携包。
用自然语言下达指令即可。插件提供 **16 个 Agent 工具** 与可选 **Web 面板**（知识库列表、导入向导、检索试验台、溯源定位）——无需另外部署 RAG 服务。
## 为什么选择 dsh-kb-manager？
| 能力 | 带来的变化 |
| --- | --- |
| **多格式导入** | PDF（逐页提取、扫描页降级标记）、DOCX、Markdown、HTML（Readability 正文）、CSV、JSON、TXT，以及 URL 抓取。 |
| **智能分块** | `fixed` / `recursive`（默认）/ `semantic`；heading 面包屑、表格独立成块、页码与段落溯源元数据。 |
| **纯 TS 索引** | Flat（精确）+ HNSW（近似）——无任何原生模块依赖。 |
| **混合检索** | 双路召回 → RRF（`k=60`）→ 可选 rerank；`debug: true` 返回逐阶段分数。 |
| **全离线降级链** | 本地 / OpenAI 兼容 embedding → 内置 HashEmbedder；rerank 失败自动降级为 RRF 顺序。 |
| **快照与回滚** | manifest + 索引备份；embedding 模型不一致时拒绝不安全回滚。 |
| **`.kbpack` 便携包** | tar.gz 打包原文 + 分块 + 索引 + 元数据；支持 `create_new` / `merge` 导入。 |
| **目录监听同步** | chokidar + SHA-256 变更判定 + 停机补扫；监听目录被删只暂停，不级联删除。 |
| **只读模式** | `read_only: true` 时写工具立即返回 `read_only_mode`。 |
| **Agent 友好工具** | 每个工具 description 内嵌 few-shot 调用示例。 |
## 架构
```mermaid
flowchart LR
A[文档 / URL] --> B[解析]
B --> C[分块]
C --> D[向量化]
D --> E[向量索引
Flat / HNSW]
C --> F[BM25]
E --> G[混合检索]
F --> G
G --> H[RRF]
H --> I[可选 rerank]
I --> J[引用 + debug 分数]
E --> K[快照 / .kbpack]
C --> K
```
## 安装
> [!NOTE]
> 使用前请确保已安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。
### 从 GitHub 安装
```sh
dsh plugin --profile web add github:xiaoshi7915/dsh-kb-manager
```
通过 git 安装时，`prepare` 脚本会自动运行 `tsdown` 完成自包含构建（无需 monorepo 上下文）。
### 从源码构建
```sh
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：
```sh
dsh --profile web --dump-config
dsh web
```
然后可以直接说：
> 创建一个名为「项目文档」的知识库，导入这份 PDF，检索认证流程是怎么写的，并给出原文出处。
## 工作方式
1. 用 `create_kb` 创建知识库，选择 embedding 模型（默认离线 `hash-embed-v1`；配置 `embedding_api_base` 后可用 OpenAI 兼容模型名）。
2. 用 `import_document` 导入本地文件或 URL → 解析 → 分块 → 向量化 → 建索引。
3. 用 `search_kb` / `multi_kb_search` 检索：向量 + BM25 → RRF → 可选 rerank；`debug: true` 可查看各阶段分数。
4. 用 `get_chunk` 溯源（前后文 + 出处元数据）。
5. 大改前可先 `create_snapshot`，需要时 `restore_snapshot`，或用 `.kbpack` 跨机器迁移。
6. 可选配置 `auto_sync_dir`，监听目录并增量更新目标知识库。
数据保存在 `storage_path`（默认 `~/.dsh/kb-manager/`）。Web 客户端复用同一套服务能力，提供概览、导入、检索与溯源定位。
## Agent 工具
| 工具 | 说明 | 关键参数 |
| --- | --- | --- |
| `create_kb` | 创建知识库 | `name*`、`description*`、`embedding_model?`、`tags?` |
| `list_kbs` | 列出全部知识库 | — |
| `get_kb` | 知识库详情（模型/文档数/块数/存储） | `kb_id*` |
| `delete_kb` | 删除整个知识库 | `kb_id*` |
| `import_document` | 导入本地文件或 URL | `kb_id*`、`source*`、`metadata?` |
| `list_documents` | 列出文档（可按状态过滤） | `kb_id*`、`status_filter?` |
| `delete_document` | 软删除块、索引置 dirty | `kb_id*`、`doc_id*` |
| `search_kb` | 混合检索，支持 debug 逐阶段分数 | `kb_id*`、`query*`、`top_k?`、`filters?`、`rerank?`、`debug?` |
| `multi_kb_search` | 跨库检索，结果附 `source_kb` | `kb_ids*`、`query*`、`top_k?` |
| `get_chunk` | 分块原文 + 前后上下文（溯源） | `kb_id*`、`chunk_id*` |
| `rebuild_index` | 全量重建（影子索引原子替换） | `kb_id*` |
| `create_snapshot` | 创建版本快照 | `kb_id*`、`note?` |
| `restore_snapshot` | 回滚到快照 | `kb_id*`、`snapshot_id*` |
| `export_kb` | 导出 `.kbpack` / JSON | `kb_id*`、`format?`、`output_path*` |
| `import_kb` | 导入便携包（`create_new` / `merge`） | `file_path*`、`merge_strategy?` |
| `get_kb_stats` | 统计（文档/块/索引体积/平均块长） | `kb_id*` |
写工具（`create_kb` / `delete_kb` / `import_document` / `delete_document` / `rebuild_index` / `create_snapshot` / `restore_snapshot` / `import_kb`）在只读模式下返回 `{ success: false, error: 'read_only_mode' }`。领域错误统一为 `{ success: false, error: , message }`，不向外 throw。
## 触发场景
1. 「把这份 PDF / 文档 / 网页收进知识库」→ `import_document`
2. 「查一下知识库里关于 X 的内容」→ `search_kb`
3. 「在所有知识库里找 Y」→ `multi_kb_search`
4. 「这条引用出自哪里 / 上下文是什么」→ `get_chunk`
5. 「检索效果不好，看看各阶段分数」→ `search_kb({ debug: true })`
6. 「大改前先留个备份」→ `create_snapshot`
7. 「回滚到改之前的状态」→ `restore_snapshot`
8. 「把这个知识库打包带走 / 迁到另一台机器」→ `export_kb` + `import_kb`
9. 「本地文件改了知识库会更新吗」→ 目录监听自动增量同步
10. 「看看知识库的规模和状态」→ `list_kbs` / `get_kb_stats`
## 配置
默认即可全离线使用。可在受信 Profile 中覆盖（插件 `id: kb-manager`）：
| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `storage_path` | `~/.dsh/kb-manager/` | 存储根目录，`~` 展开为用户主目录 |
| `default_embedding_model` | `hash-embed-v1` | 离线兜底；也可填 OpenAI 兼容模型名 |
| `embedding_api_base` | `''` | OpenAI 兼容 endpoint；留空用 HashEmbedder |
| `embedding_api_key` | `''` | embedding API key |
| `chunk_size` | `512` | 分块大小（字符数） |
| `chunk_overlap` | `50` | 分块重叠长度 |
| `chunk_strategy` | `recursive` | `fixed` / `recursive` / `semantic` |
| `top_k` | `5` | 检索默认返回条数 |
| `enable_rerank` | `true` | 是否在 RRF 后启用 rerank |
| `rerank_endpoint` | `''` | 远程 rerank；留空用内置规则式 reranker |
| `index_type` | `hnsw` | `hnsw` / `flat` |
| `auto_sync_dir` | `''` | 目录监听路径；留空关闭 |
| `auto_sync_kb_id` | `''` | 同步目标知识库 |
| `auto_sync_interval` | `300` | 补扫间隔（秒） |
| `max_file_size_mb` | `100` | 单文件大小上限（MB） |
| `read_only` | `false` | 只读模式开关 |
示例：
```yaml
- id: kb-manager
config:
storage_path: ~/.dsh/kb-manager/
default_embedding_model: text-embedding-3-small
embedding_api_base: https://api.openai.com/v1
chunk_strategy: recursive
index_type: hnsw
enable_rerank: true
read_only: false
```
## 使用边界
- 读写 `storage_path`；`import_document` / `import_kb` 还会读取用户指定的本地路径或 URL；`export_kb` 写出到 `output_path`。
- 不支持的格式返回 `unsupported_format`；超限文件由 `max_file_size_mb` 拒绝。
- 默认全本地运行；仅在配置了 `embedding_api_base` / `rerank_endpoint` 或导入 URL 时才发起网络请求。
- `export_kb` 不修改知识库数据，只读模式下仍可用。
- 纯 TS 索引：无需额外部署原生向量库进程。
## 与常见 RAG 方案的差异
| 能力 | 本插件 | 常见 RAGFlow / Dify / kotaemon / pdfkb-mcp 方案 |
| --- | --- | --- |
| KB 版本快照与回滚 | ✅ | 通常缺失 |
| `.kbpack`（原文+分块+索引+元数据） | ✅ | 通常缺失 |
| 目录监听 + 停机补扫 | ✅ chokidar + SHA-256 | 部分支持 / 缺失 |
| 检索管线逐阶段 debug 分数 | ✅ vector / BM25 / RRF / rerank | 多为黑盒 |
| 全离线 embedding 兜底 | ✅ HashEmbedder | 往往依赖外部服务 |
| 只读模式 | ✅ | 少见 |
## 目录结构
```
dsh-kb-manager/
├── package.json cordis.patch.yml tsconfig.json tsdown.config.ts vitest.config.ts
├── awesome-entry.yml README.md README_ZH.md
├── assets/readme/ # hero.png（请粘贴生成图到此处）
├── src/
│ ├── index.ts # 插件入口（name / inject / Config / apply）
│ ├── config.ts # Schemastery 配置 schema
│ ├── core/ parse/ chunk/
│ ├── embed/ index/ search/
│ ├── kb/ # KBService、快照、同步、kbpack
│ ├── tools/ # 16 个 Agent 工具
│ └── client/ # Web 面板
└── tests/
```
## 开发
```sh
npm install # 安装依赖（prepare 自动构建）
npm run build # tsdown 双入口 → lib/index.js + lib/client.js
npm test # vitest
npm run typecheck # tsc --noEmit
```
## 许可证
[MIT](./LICENSE) © 2026 xiaoshi7915