dsh-knowledge

DSH 的知识库插件

English · 中文

一个深度的知识库系统，作为 DeepSeek Harness（DSH）的独立、可开源 bundle 插件。提供知识库（含分组）与文档管理、文本分块、向量化（OpenAI 兼容 / Ollama / 本地模型 / 关键词降级）、检索，以及模型可见工具与浏览器管理面板。

---

为什么选择 dsh-knowledge

dsh-knowledge 把文档导入、解析、分块、检索、证据组织和模型续读整合进 DSH。它既可以零向量配置运行，也可以完全使用本地模型，不要求额外部署独立的知识库服务。

能力	说明
文档来源	文件、目录、网页和文本笔记；本地路径可持续重扫和重新索引
混合检索	FTS5 BM25、向量召回、RRF 融合、MMR 去重以及可选重排
证据上下文	按文档顺序动态生成 ContextWindow，支持围绕命中位置继续阅读
本地运行	本地 embedding、本地 rerank、本地 OCR；也支持 OpenAI 兼容接口和 Ollama
文档处理	常见办公格式、扫描 PDF、PaddleOCR、Tesseract 回退及可选 MinerU
管理界面	知识库分组、批量导入、预览、召回测试、模型管理和索引重建

---

快速开始

1. 准备环境

• Node.js：^22.19.0 || >=24.0.0
• pnpm：>=10
• 已安装并初始化 DeepSeek Harness

在安装插件之前，将以下构建许可合并到目标 profile 的 pnpm-workspace.yaml 中已有的 allowBuilds 映射。不要重复添加第二个 allowBuilds: 键，否则 YAML 会失效。这些依赖包含安装期构建；pnpm 10 默认拒绝执行时，dsh plugin add 会在登记 bundle 前退出。

allowBuilds:
  esbuild: true
  onnxruntime-node: true
  protobufjs: true
  sharp: true
  tesseract.js: false

2. 安装插件

dsh plugin --profile <name> add dsh-knowledge

插件安装在 profile 层。无论 DSH 来自 npm 还是源码 checkout，都使用同一条命令。安装完成后重启 web 服务，并刷新页面加载管理面板。

3. 完成首次配置

1. 点击侧边栏底部、设置旁的“知识库”入口。
2. 新建知识库并导入文件、目录、网页或文本。
3. 如需本地向量检索，在“设置 > 本地模型”下载 embedding 模型；也可以配置 OpenAI 兼容服务或 Ollama。
4. 如需识别扫描件，再下载约 21 MB 的 OCR 模型。
5. 在“召回测试”中检查结果，再让模型通过 knowledge_search 使用知识库。

不下载模型也可以使用关键词检索。扫描件 OCR、本地 embedding 和本地 rerank 只有在对应模型已下载并通过就绪检查后才启用。

其他安装方式

# GitHub Release 或 npm pack 生成的 tarball
dsh plugin --profile <name> add ./dsh-knowledge-0.5.2.tgz

# 本地源码目录，需要先完成构建
dsh plugin --profile <name> add file:/path/to/dsh-knowledge

如果第一次安装因 pnpm 构建许可失败，请补全 allowBuilds 后重新运行 add。包通常已经进入 node_modules，第二次执行会继续完成 bundle 登记。

恢复 <code>ERR_PNPM_WORKSPACE_MANIFEST_WRITER_PARSE</code>

这表示 pnpm 无法解析 DSH profile 自己的 pnpm-workspace.yaml，发生在下载或构建本插件之前。先备份文件，再修复错误信息指出的 YAML 行：

• Windows：%USERPROFILE%\.dsh\profiles\<profile>\pnpm-workspace.yaml
• macOS / Linux：~/.dsh/profiles/<profile>/pnpm-workspace.yaml

不要在不清楚原有设置用途时覆盖该文件。如果 profile 没有其他有意保留的 pnpm 设置，可恢复为以下最小有效配置，再将上方的 allowBuilds 合并进去：

packages:
  - .

nodeLinker: hoisted
autoInstallPeers: false

allowBuilds:
  esbuild: true
  onnxruntime-node: true
  protobufjs: true
  sharp: true
  tesseract.js: false

随后重新执行同一条 dsh plugin --profile <profile> add ... 命令。若修复 YAML 后出现 ERR_PNPM_IGNORED_BUILDS，这是独立的构建授权问题；仅按 pnpm 输出的确切包名补充授权，不要宽泛地允许所有脚本。

---

核心能力

文档与来源管理

• 创建、重命名、分组和删除知识库；侧边栏支持分组折叠和库间移动。
• 从文件、绝对路径、目录、URL 或纯文本导入文档。目录来源保留稳定 ID、类型和原始路径，可重新扫描磁盘变化。
• 批量上传单次最多 20 个文件、单文件最大 22 MB，并使用 5 路后台导入池。
• 同名冲突由服务端统一检测，可选择重命名、替换或取消；内容哈希用于避免重复导入。
• 文档列表展示等待、解析、embedding、完成和失败状态；支持 PDF 原文、文本和完整分块预览。
• 原始文件保存到知识库 raw 存储。不同目录根的同名相对路径互不冲突，失败的替换重建不会破坏上一份已提交内容。

支持的文档格式与目录行为

目录导入递归扫描 txt、md、csv、html、json、pdf、docx、doc、pptx、ppt、xlsx、xls、epub 等格式，并在界面中保留可下钻的文件夹树。

重新扫描目录时会导入新增文件、重建已修改文件并移除已不存在的文件。单个文件失败不会隐藏其他成功结果，服务端和界面都会保留逐文件错误信息。

更新已导入目录的正确方式：重新导入同一路径，或在界面中对目录容器执行重扫——两者现在走同一条同步路径，都只会原地更新原来那棵树。目录来源以“知识库 + 规范化真实路径”确定身份，所以重复导入不会再新建第二棵树。目录中的文件以“目录来源 + 相对路径”确定身份；只有名称和类型都唯一的旧文件才会被认领，出现两个候选时报告 ambiguous_source，不会猜测、合并或自动删除。管理 API 的文档详情会返回目录容器的 sourcePath，客户端可据此找到该重扫哪一个容器。

检索与证据链

…