simple-knowledge

simple-knowledge

DSH（DeepSeek Harness）插件：本地知识库与 Agent 检索

让 Agent 能够检索你导入的资料，并清晰展示每次回答引用了哪些知识库内容。

特性一览

特性	说明
知识库管理	创建、删除知识库，按知识库隔离文档
文件导入	支持 TXT、Markdown；导入前可预览文件内容
智能分块	按标题、段落和 Markdown 标题路径切分，并保留来源位置
双索引存储	SQLite 持久化文档与分块，同时建立 FTS5 和向量索引
三种检索	关键词检索、向量检索、RRF 混合检索
Embedding	支持 Ollama 和 OpenAI 兼容服务，可使用本地 nomic-embed-text
索引任务	显示文档、分块、批次进度，支持暂停、恢复、取消和失败重试
Agent 自动检索	从用户消息中检索指定知识库，并将结果注入 Agent 上下文
引用可追溯	记录知识库、文档、分块编号和引用 ID，清晰说明 Agent 使用的资料
本地优先	默认使用本地 SQLite 数据库，不依赖独立向量数据库

simple-knowledge 是 DeepSeek Harness（DSH）的轻量知识库插件，面向本地文档管理和 Agent 增强检索。当前版本为 0.1.0。

工作机制

文档导入与索引

文档导入后会计算内容哈希并写入数据库，再按配置切分成多个分块。每个分块同时写入 FTS5 全文索引；配置 Embedding 服务时，索引任务会按批次调用服务生成向量。

文档状态包括 pending、embedding、ready、embedding_failed；索引任务状态包括 queued、running、paused、completed、failed、cancelled。

未配置 Embedding 时，文档仍可完成关键词索引和关键词检索。配置服务后点击“重建索引”会清理旧向量并重新建立向量索引。服务或模型变更也会使已有向量失效，需要重新索引。

暂停在当前 Embedding 批次完成后生效；恢复会从没有向量的分块继续。DSH 重启时，运行中的任务会自动变为 paused，队列中的任务会自动继续排队。

检索

• 关键词检索：通过 SQLite FTS5 匹配词语，适合专有名词、精确名称和标识符。
• 向量检索：将查询和文档分块转换为向量，通过余弦相似度寻找语义相近内容。
• 混合检索：同时执行关键词和向量检索，通过 Reciprocal Rank Fusion（RRF）合并排序，默认模式为混合检索。

向量检索要求查询向量与文档向量维度一致。维度由模型决定，例如模型返回 768 个浮点数，则维度就是 768，不需要手工填写。管理页面的“测试连接”会请求一次 Embedding 并显示实际维度。

在 DSH 中使用

安装本地 link 包

要求 Node.js 22.5 或更高版本。在源码目录执行：

npm install
npm run build
npm link
dsh plugin --profile web add link:simple-knowledge

启动或重启 DSH Web 后，插件会出现在插件列表中，并在“设置 > 知识库”提供管理页面。修改源码后重新执行 npm run build，再重启 DSH Web。

卸载 link 包：

dsh plugin --profile web remove simple-knowledge
npm unlink -g simple-knowledge

使用 npm 安装与升级

从 npm 安装最新版插件：

npm install -g simple-knowledge
dsh plugin --profile web add simple-knowledge

安装后重启 DSH Web，在插件列表和“设置 > 知识库”中使用。升级到最新版：

npm update -g simple-knowledge

也可以显式安装指定版本：

npm install -g simple-knowledge@0.1.0

升级完成后建议重启 DSH Web，使新版本配置和界面生效。卸载 npm 版本：

dsh plugin --profile web remove simple-knowledge
npm uninstall -g simple-knowledge

管理页面

知识库设置分为三个 Tab：

• Embedding 与检索：选择 Embedding 服务、模型、地址、API Key、检索模式、Top K、分块和批次参数；保存后可测试连接或重建索引。
• 自动检索与 Agent 引用：开启自动检索，选择允许被引用的知识库，并查看 Agent 的检索活动和引用明细。
• 知识库与文件：创建知识库，上传 TXT/Markdown 文件，预览文件内容，查看文档状态、分块数和索引错误。

索引任务区域会显示总文档数、已完成文档数、总分块数、已完成分块数、当前批次、重试次数和错误信息，并提供暂停、恢复、取消和重试操作。

Embedding 配置示例

使用本地 Ollama：

服务商：Ollama
地址：http://127.0.0.1:11434
模型：nomic-embed-text

使用 OpenAI 兼容服务：

服务商：OpenAI 兼容
地址：https://api.siliconflow.cn/v1
模型：BAAI/bge-m3
API Key：按服务商要求填写

API Key 仅保存为 DSH 配置，管理页面不会返回明文。

Agent 使用方式

插件向 DSH 注册以下工具：

• knowledge_list_bases：列出可用知识库。
• knowledge_search：检索知识库并返回带来源的文档分块；参数包括 query、可选 baseId、topK 和 mode。
• knowledge_create_base：创建知识库。
• knowledge_add_document：以文本参数添加 TXT 或 Markdown 内容。
• knowledge_list_documents：列出指定知识库中的文档及索引状态。

自动检索开启后，插件会从 Agent 对话中提取用户最新消息，在配置的知识库范围内检索，并将命中的内容注入当前 Agent 上下文。注入内容带有来源信息：

[知识库：团队规范 | 来源：开发流程.md | 分块：2 | 引用：chunk-id]

自动检索只使用“自动检索与 Agent 引用”中选中的知识库，并通过冷却时间和已引用分块去重，减少同一主题的重复注入。管理页面的 Agent 活动记录会显示查询、Agent ID、实际使用的知识库、文档标题和分块编号。

知识库内容被视为参考资料，不是新的系统指令；资料不足时 Agent 应明确说明。

HTTP 接口

插件提供受 DSH 信任请求保护的 JSON HTTP 接口。成功响应格式为 { "ok": true, "value": ... }，失败响应格式为 { "ok": false, "error": ... }。

配置、导入与检索

GET    /knowledge/config
PATCH  /knowledge/config
POST   /knowledge/embedding/test
POST   /knowledge/reindex
GET    /knowledge/bases
POST   /knowledge/bases
DELETE /knowledge/bases/:baseId
GET    /knowledge/bases/:baseId/documents
POST   /knowledge/bases/:baseId/documents
DELETE /knowledge/documents/:documentId
POST   /knowledge/search
GET    /knowledge/stats
GET    /knowledge/auto-retrieval/activity

POST /knowledge/bases/:baseId/documents 请求体示例：

{
  "title": "开发规范.md",
  "sourceType": "markdown",
  "content": "# 开发规范\\n\\n提交代码前需要运行测试。"
}

POST /knowledge/search 请求体示例：

{
  "query": "提交代码前需要做什么",
  "baseId": "可选的知识库 ID",
  "topK": 5,
  "mode": "hybrid"
}

索引任务

POST /knowledge/reindex 为异步接口，返回 HTTP 202 和新任务。使用以下接口查询任务和控制任务：

GET  /knowledge/index-jobs
GET  /knowledge/index-jobs/:jobId
POST /knowledge/index-jobs/:jobId/pause
POST /knowledge/index-jobs/:jobId/resume
POST /knowledge/index-jobs/:jobId/retry
POST /knowledge/index-jobs/:jobId/cancel

重试只允许用于 failed 或 cancelled 任务；同一时间只允许一个全量索引任务或相关文档索引任务处于活动状态。

开发与验证

npm run build
npm test
git diff --check

测试覆盖文档导入、去重、关键词检索、Embedding 配置变更、向量索引、索引进度、暂停恢复、失败重试和自动检索引用。

当前边界

0.1.0 暂不支持 OCR、PDF/Word/Excel 等复杂办公文档解析，也不接受 Agent 传入本地文件路径。文件导入目前支持 TXT 和 Markdown；Embedding 服务需要兼容 Ollama /api/embed 或 OpenAI /v1/embeddings 接口。