DSH-RAG

English | 简体中文

DSH-RAG 是面向 DeepSeek Harness Web 的本地知识库插件。它把用户明确授权的本机目录建立为可增量同步的命名知识库；执行 /rag <问题> 时，插件会在模型回答前完成检索，并展示带原文片段、精确位置和原文件打开入口的可核查来源。普通对话不会访问本地资料。

功能

• 将一个或多个明确授权的本机目录建立为多个命名知识库。
• 命名知识库可跨项目和会话复用；一个知识库可包含一个或多个明确授权的目录。
• 只检索当前 Session 允许使用的知识库，也可以用一个或多个可选的 @知识库 临时覆盖本轮范围；普通消息不会搜索或注入本地资料。
• 在模型回答前完成检索，并通过可折叠来源卡片展示知识库、文件、原文片段、精确页码、幻灯片、段落或行号，以及经 Host 复核的原文件打开入口。
• 解析 PDF、DOCX、PPTX、Markdown 和 UTF-8 文本，支持增量索引、取消、文件级检查点、watcher 防抖和补偿扫描。
• 本地中英文 BM25 在没有 API Key 或网络时仍可检索；配置 SiliconFlow 后可启用 Embedding、本地向量、RRF 和 Reranker 混合检索。
• 中英文界面跟随 DeepSeek Harness 的语言设置，并适配浅色、深色和系统外观。

环境要求

• Node.js ^22.19.0 或 >=24.0.0
• PATH 中可以使用 pnpm（dsh plugin 通过 pnpm 管理 Profile 中的包）
• DeepSeek Harness：已验证版本为 0.1.1-rc.2

DeepSeek Harness 目前仍处于开发者预览期。0.1.1-rc.2 是 DSH-RAG 已实际通过安装、启动和卸载检查的版本，并不表示插件只能在该版本运行；其他 DSH 版本可能可用，但通过同样的兼容性检查前不作保证。

安装并启动

根据你的 DSH 使用方式选择下面一种即可。两种方式都会把 DSH-RAG 安装到同一个 web Profile，不需要重复执行。

方式一：通过 npx 运行 DSH

如果尚未安装 dsh 命令，直接在任意目录执行：

npx @deepseek-ai/dsh plugin --profile web add @kai232/dsh-rag
npx @deepseek-ai/dsh web

保持第二条命令运行，然后打开终端中显示的 Web 地址。

方式二：使用已经安装的 DSH

如果在终端执行 dsh --version 能正常显示版本，则不需要进入任何特定目录：

dsh plugin --profile web add @kai232/dsh-rag
dsh web

如果希望从 DeepSeek Harness 源码运行，则克隆仓库并使用仓库提供的 pnpm dsh 命令：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh plugin --profile web add @kai232/dsh-rag
pnpm dsh web

如果本机已经有该源码仓库，可以跳过 git clone，进入仓库根目录后从 pnpm install 继续。pnpm run build 会准备 pnpm dsh web 运行所需的源码产物。

更新 DSH-RAG 时，先停止正在运行的 Web 进程，重新执行对应方式中的 plugin add 命令，然后再次启动 Web。

创建知识库

1. 打开 设置 → 知识库。
2. 复核 SiliconFlow Endpoint、Embedding 模型和 Reranker 模型。
3. 输入 SiliconFlow API Key 并保存到操作系统凭据库。如果系统凭据库不可用，可在启动 DSH 前设置 SILICONFLOW_API_KEY；插件不会回退到明文 Key 文件。连接状态会自动检测，只有失败后才显示 重试。
4. 在设置中创建知识库，只填写你明确授权的目录。
5. 点击 同步，等待索引完成。
6. 在会话的 知识库 面板中选择当前 Session 允许检索的知识库；需要临时覆盖时，输入 /rag 并从第一次命令提示中选择一个本轮知识库。

知识库名称和文件名属于用户数据，切换界面语言时不会被翻译。

使用方式

命令格式：

/rag <问题>

输入 /rag 时，第一次命令菜单会同时显示标准命令和各知识库的本轮命令变体。进入命令后输入 /rag @，知识库也会排在通用文件、文件夹和 Session 候选之前；选择后插入普通文本参数。知识库不会出现在无关的 @ 菜单或已经开始输入的问题正文中。不选择而按空格继续输入问题时，使用当前 Session 已保存的范围。单独执行 /rag 只显示知识库统计和用法，不调用模型。

使用当前 Session 已选择的知识库发起显式检索：

/rag 项目记录中的发布时间窗口是什么？

发送命令后，插件会先真正完成检索，再把来源证据交给模型回答；不会依赖模型自行决定是否调用检索工具。命令只检索当前 Session 已选择的知识库。没有选择时，插件会提示先选择，不会自动搜索全部知识库。

需要临时覆盖本轮范围时，从 /rag 的第一次命令候选中选择一个知识库；插件会自动插入最短且无歧义的选择参数，不改变该 Session 已保存的选择：

/rag @项目资料 当前项目虚拟环境使用的 Python 版本是什么？

名称不含空格时使用简洁的 @知识库名；名称含空格等特殊字符时自动使用 @"知识库名"。下一条普通消息会恢复为零检索。

检索结果会显示知识库、文件名、结构上下文、原文片段和精确位置。打开原文件时，界面只提交不透明的来源 ID，Host 重新解析并验证路径后才交给操作系统打开。

检索与离线降级

配置 SiliconFlow 后，首次建立云向量索引会发送授权文档中提取出的全部文本片段；后续同步只为新增或变化片段请求 Embedding。显式查询时只向 Reranker 发送查询和有限候选。PDF、Word、PPT 等原始文件本身不会上传，但从中提取的文本会发送给 SiliconFlow。

SiliconFlow 或网络不可用时，界面会明确显示降级，并继续使用本地 BM25；已有本地索引仍可检索。AI 生成的文档或章节背景没有提高冻结评测指标，因此 v0.1 不提供该能力。

本机数据与删除

派生数据默认保存在 $DSH_HOME/dsh-rag/，不会随 DSH 的启动目录改变。实际位置可在 设置 → 知识库 → 数据位置 中查看并打开。只有需要自定义位置时，才应在启动 DSH 前将 DSH_RAG_DATA_DIR 设置为绝对路径。

如果默认位置为空，而旧启动目录中存在 .dsh-rag 数据，插件会复制、校验并原子迁入新位置，同时保留旧目录；如果新旧位置都有数据，则保持两边不变并提示冲突，不会自动混合。

设置页的 删除知识库 需要二次确认，只删除知识库配置和可再生的 catalog、检查点与索引，绝不会修改或删除授权目录中的原始资料。

备份派生数据时，应先停止 DSH，再复制整个数据目录。索引可以根据原始目录重新建立。

安全与隐私

• 授权路径经过规范化和 realpath 复核，拒绝符号链接、junction、UNC 和路径逃逸。
• 默认排除隐藏文件、常见凭据文件、可执行文件、Office 活动内容、嵌入对象和危险压缩展开。
• 文档文本始终是不可信数据，不会作为 Agent 指令执行。
• API Key 不会写入项目设置、日志、Session、浏览器存储、索引或 API 响应。
• 持久 Key 使用 Windows Credential Manager、macOS Keychain 或 Linux Secret Service，不提供明文凭据文件回退。

License

MIT