dsh-plugin-knowledge-base
fsnh/dsh-plugin-knowledge-base
Local knowledge base for DeepSeek Harness: a folder tree, in-app viewing of the original layout of Office files, PDFs and images, Chinese-friendly full-text search with optional vector fusion, image descriptions produced by a vision model so pictures become searchable, and three read-only tools the model calls to list, search and read files. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.
설치
dsh plugin --profile web add github:fsnh/dsh-plugin-knowledge-baseREADME
DSH 个人知识库插件
把本地文件整理成树状知识库,在 DeepSeek Harness 里直接读、直接搜,AI 也能检索并针对某一篇文档对话。
数据全在本机(默认 ~/.dsh/kb),不经过任何云端。
界面示意图(跟随 DSH 主题与窗口宽度变化)
它解决什么问题
你在电脑里攒了一堆培训 PPT、会议纪要、登记资料、报价单——平时找一份东西要翻好几个文件夹,找到了还得自己读一遍。
这个插件把它们组织成树状目录,然后给你两件事:
- 看得见原样:点开就是 PPT/Word/Excel 的原始版式(不是抽出来的文字),左边缩略图栏点哪页跳哪页;
- 问得出来:任何会话里问"我的资料里有没有关于 X 的",模型会自己检索、读片段、带出处回答。
三分钟上手
# 1. 装(桌面端把 web 换成 desktop)
dsh plugin --profile web add @xiaofanzhao/dsh-plugin-knowledge-base@0.1.0
2. 刷新页面 → 左栏点「知识库」
3. 点「新建知识库」起个名字
4. 点「上传文件」或把文件拖进来(解析在后台跑)
5. 左栏点文件 → 右边直接看原版式
想跟文档对话:文档页点「✳ 问 AI」,提问会预填进会话输入框,你把问题补完发出去即可。
功能
- 树状目录:多知识库 / 文件夹 / 拖拽移动 / 重命名 / 删除;文件树栏可收起,阅读区随之变宽
- 在线查看原版式:Word、PPT、Excel 用本机 LibreOffice 转成 PDF,再逐页渲染成图片,由插件自己的阅读器显示(缩略图栏 + 页码跳转 + 单页/连续 + 大屏放映)
- 全文检索:SQLite FTS5,中英文混排,中文两字词也能命中(CJK 逐字归一化)
- AI 检索:模型侧有三个工具
kb_list/kb_search/kb_read,任何会话里问"知识库里有没有…"都会自动用上 - 针对文档对话:「问 AI」把带 docId 的提问预填到会话输入框,模型先读文档再回答,并标注出处
- 看板:知识库规模、文件类型分布、解析状态、7 天检索趋势、热门检索词、零命中率、最近检索与最近添加——检索记录只存本地,最多 2000 条
- 图片也能搜(可选):接一个视觉模型,上传/重建时把图片描述成结构化文字(画面 / 文字 / 数据 / 场景),再走同一套关键词 + 向量检索,AI 也能读出图里写了什么
安装
插件是一个标准的 DSH bundle,三种装法。
方式一:从 npm 装(推荐)
dsh plugin --profile web add @xiaofanzhao/dsh-plugin-knowledge-base@0.1.0
已发布在 npm:@xiaofanzhao/dsh-plugin-knowledge-base
一条命令就够:它会把包装进 profile、把包名写进 dsh.profile.bundles,profile 启动时再合并包内自带的 cordis.patch.yml。不需要手改任何 profile 文件。
- 装哪个 profile 就把
web换成你的(桌面端是desktop) - 升级:把版本号换成新的(
@0.1.1)再执行一次 - 卸载:
dsh plugin --profile web remove @xiaofanzhao/dsh-plugin-knowledge-base
如果提示
E404 / 找不到这个版本,说明该版本还没发布到 npm,先用方式二。
方式二:从源码装(想改代码,或还没发布时)
git clone https://github.com/FSNH/dsh-plugin-knowledge-base.git
dsh plugin --profile web add .\dsh-plugin-knowledge-base
add <本地目录> 建立的是 link,之后你改 client.js / lib/* 只要在插件页里关掉再打开(或刷新页面)就能看到效果,不用重新安装。
方式三:界面里装 / 让 agent 装
plugin_manager install_bundle "C:\path\to\dsh-plugin-knowledge-base"
# 或界面:Plugins → Add plugin → 选择这个目录
装好后刷新页面,左栏会多一个「知识库」图标。
依赖:
pdfjs-dist(PDF 文字层抽取)。第一次装需要联网安装依赖。 Office 原版式预览依赖 DSH 自带的 LibreOffice(officeKit):没有它也能用,只是 Office 文档只能看抽取出来的文字。 包名 ≠ 仓库名:npm 上的dsh-plugin-knowledge-base已被别人的包占用,所以包名带@xiaofanzhao/作用域;仓库名保持不变。
打包与发布
插件本身就是一个标准的 DSH bundle:package.json 里 dsh.bundle.patch 指向自带的 cordis.patch.yml,dsh.client 声明浏览器半部。
1. 本地打包自测(不需要发布)
npm pack # 产出 xiaofanzhao-dsh-plugin-knowledge-base-0.1.0.tgz(25 个文件,约 95 KB)
dsh plugin --profile kbtest add .\xiaofanzhao-dsh-plugin-knowledge-base-0.1.0.tgz
装完打开 ~/.dsh/profiles/kbtest/package.json,应该能看到包名被自动追加进 bundles:
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@xiaofanzhao/dsh-plugin-knowledge-base"] } }
为什么包名带
@xiaofanzhao/前缀:npm 上的dsh-plugin-knowledge-base已经被别人的包占用(2026-08-19,作者 zhengjialux),所以发布名用作用域版本。 仓库名仍叫dsh-plugin-knowledge-base,两者不冲突;包名以package.json的name为准,并且cordis.patch.yml里那一行的name必须与它完全一致,否则 profile 合并 patch 时找不到包。
2. 发布
npm login
npm publish --access public # 作用域包(@xxx/yyy)必须带 --access public
发布后任何人:
dsh plugin --profile web add @xiaofanzhao/dsh-plugin-knowledge-base@0.1.0
3. 自动发布(可选)
仓库里带了 .github/workflows/publish.yml:在 GitHub 的仓库设置里加一个 NPM_TOKEN secret(npm 的 Automation token),然后
git tag v0.1.0
git push origin v0.1.0
就会自动校验「tag 与 package.json 版本一致」→ npm publish --provenance。
发布前检查清单
-
package.json:name没被占用、version已递增、private不为true、没有重复的dependencies键 -
files覆盖运行时需要的东西(index.js/client.js/lib/cordis.patch.yml/icon.svg/locale) -
cordis.patch.yml里的name与包名一致 -
npm pack --dry-run看到 25 个文件、没有把node_modules或数据文件打进去 -
node test/no-secrets.mjs通过(别把 API Key 打进包)
使用
| 想做的事 | 怎么做 |
|---|---|
| 建库 | 顶部「知识库」下拉旁的 +,或左栏空态里的「新建知识库」 |
| 建文件夹 | 先点中父文件夹,再点「新建文件夹」 |
| 上传文件 | 点「上传文件」或把文件拖进页面;落在当前选中的文件夹里 |
| 移动到别的目录 | 把文件行拖到文件夹上,或用行上的「移动到…」 |
| 收起文件树 | 顶部最左侧的箭头按钮(收起后左边留一条细条,点它展开) |
| 看原版式 | 点文档 → 默认「原版式」;Word/PPT/Excel 第一次要等转换 |
| 翻页 | 阅读器顶部 ‹ 4 / 123 › 直接跳页,或点左侧缩略图 |
| 大屏放映 | 文档页「大屏」→ 单页铺满、← → 翻页、右上角「恢复」或 Esc 退出 |
| 搜索 | 右上角搜索框,命中后点一条会跳到正文那一段并高亮 |
| 知识库设置 | 页面右上角齿轮按钮(面板内直接看),或系统设置里的「知识库」一节 |
| 看知识库看板 | 顶部「文档 / 看板」切换到看板:规模、类型分布、检索趋势与热门词都在这一页 |
| 问 AI | 文档页「问 AI」,提问会预填进会话输入框 |
阅读器
- 缩略图栏:点哪页跳哪页,当前页有描边;工具栏最左边的按钮可以收起它
- 单页 / 连续:单页像放映(整页装下、居中、不裁切),连续是滚动阅读
- 首屏很快:先渲染前 6 页给看,剩下的在后台继续补,几秒后自动出现(不用等整本渲完)
- 大屏:铺满整个窗口,
← →/PageUp PageDown翻页,Esc或右上角「恢复」回面板 - 文字版:「原版式 / 文字」随时切换,文字版用于快速读、也是 AI 检索的来源
桌面端不允许插件页面开新窗口(Electron 拦掉了
target=_blank),所以大屏是应用内全屏;要更大或用 PowerPoint 放映,用「下载」拿原件。
让图片也能被搜到(可选)
图片本身没有文字层,默认只能看、搜不到。打开「图片理解」后,上传或重建索引时会调用一个视觉模型把图片描述成结构化文字,再走和文档一样的索引:
图片 → 视觉模型 → 【画面】【文字】【数据】【场景】四段描述
→ 当正文存起来 → 切块 → 关键词 + 向量 → 可被搜索、可被 AI 读取
怎么开:知识库页面 → 右上角齿轮 → 「图片理解(可选)」→ 选服务商(自动填好地址和模型,也可以选「自定义」手填)→ 填 Key(留空则复用向量检索那把)→ 勾选启用 → 测试连接 → 保存 → 点「重建全部索引」给已有图片补描述。
内置预设(选完自动填地址 + 模型):
| 服务商 | 接口地址 | 视觉模型 |
|---|---|---|
| 阿里云百炼 | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen3-vl-plus |
| 硅基流动 | https://api.siliconflow.cn/v1 | Qwen/Qwen2.5-VL-72B-Instruct |
| OpenAI | https://api.openai.com/v1 | gpt-4o-mini |
| 本机 Ollama | http://127.0.0.1:11434/v1 | qwen2.5vl:7b |
| 自定义 | 任意 POST /chat/completions 的 OpenAI 兼容端点 | 自己填 |
只要求两点:
POST <baseUrl>/chat/completions能收 OpenAI 格式的messages,且支持{"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}。满足就能用,不限于上表。
几点说明:
- 默认关闭;没开的时候图片照常能看,只是搜不到
- 每张图一次模型调用(图片会发给该服务商,注意这一点)
- 单次转换失败会在文档状态里留下原因(比如
图片理解接口报错:HTTP 401),修好后点「重建」重试 - 只对
png / jpg / jpeg / gif / webp / bmp生效;扫描件 PDF 仍按「没有文字层」处理(可以把页面截成图再上传) - 想确认这台机器配的服务真的能用: est/vision-live.mjs 会真实请求一次(默认跳过,需要 KB_TEST_LIVE=1)
AI 工具
| 工具 | 作用 | 主要参数 |
|---|---|---|
kb_list | 列出知识库与目录树 | kbId? |
kb_search | 全文检索,返回片段 + 定位 | query、kbIds?、limit?、mode? |
kb_read | 按字符偏移读正文(单次 ≤ 6000 字) | docId、offset?、limit? |
库非空时会自动注入一段系统提示,告诉模型这套工具怎么用;库为空时什么都不加。
配置
在插件行的 config 里改(插件页 → 知识库 → 配置):
root: '' # 库目录,留空 = $DSH_HOME/kb
maxFileBytes: 67108864 # 单文件上限,默认 64 MiB
parseConcurrency: 1 # 解析并发
embedding:
enabled: false # 向量检索:填好 Key 再打开
baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1' # 出厂默认(百炼)
model: 'text-embedding-v4' # 出厂默认
地址和模型已经预填好百炼的默认值,正常情况下你只需要在设置里填 API Key 并勾选启用。
🔐 密钥怎么存:只在设置界面里填,写进
$DSH_HOME/kb/settings.json(权限 0600),不写进任何被 git 跟踪的文件。config.yaml的apiKey字段保留可用,但没人会建议你把 key 提交上去;仓库里还有test/no-secrets.mjs做提交前扫描。
开启向量检索(可选)
关键词检索开箱即用。想让"意思相近但用词不同"也能命中(比如搜"报关资料"能命中写着"清关单据"的段落),再接一个 OpenAI 兼容的 embeddings 接口。
⚠️ DeepSeek 官方没有 embeddings 接口,所以要接别家的,或在本机跑 Ollama。
界面上直接填,不用改配置、不用重启:
知识库页面 → 右上角齿轮 → 「向量检索」卡片 → 填 API Key → 勾选启用 → 测试连接 → 保存 → 点「重建全部索引」
接口地址和模型已经预填成百炼的默认值,直接能用;换服务商时再改这两栏。
| 服务 | 接口地址(填到 /v1 为止) | 模型 |
|---|---|---|
| 阿里云百炼 | https://dashscope.aliyuncs.com/compatible-mode/v1 | text-embedding-v4 |
| 硅基流动 | https://api.siliconflow.cn/v1 | BAAI/bge-m3 |
| OpenAI | https://api.openai.com/v1 | text-embedding-3-small |
| 本机 Ollama | http://127.0.0.1:11434/v1 | nomic-embed-text(key 随便填) |
几点说明:
- 保存在
$DSH_HOME/kb/settings.json(权限 0600),API Key 不会写进插件配置,界面上只回显尾号; - 保存即时生效,不用重载插件;「测试连接」会真发一次请求,成功会显示返回的向量维度;
- 必须点一次「重建全部索引」——已有文档没有向量,不重建就只有新导入的文档带向量;
- 配置错了不会卡住:接口不可用或返回异常时,索引阶段只写关键词、检索阶段自动退回关键词模式。
也可以用 YAML 配(config.embedding),但界面里保存过的值优先级更高:
embedding:
enabled: true
baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
model: 'text-embedding-v3'
apiKey: '' # 也可以留空,改用环境变量 DSH_KB_EMBEDDING_KEY
数据与隐私
$DSH_HOME/kb/
├── kb.db # 库结构 + 全文索引(SQLite)
├── files/<docId>.<ext> # 原始文件
├── files/<docId>.preview.pdf # Office 转出来的 PDF
├── files/<docId>.pages/ # 逐页大图(96 DPI)
└── files/<docId>.thumbs/ # 逐页缩略图(24 DPI)
- 插件不上传任何内容;只有开了向量检索才会把文本发给你指定的接口
- 卸载插件不会删除这些文件
- 页数多的文档会占几十 MB(123 页约 84 MB),设置页有「清理预览缓存」可随时清掉
支持的格式
| 类型 | 原版式 | 文字阅读 | 正文索引 |
|---|---|---|---|
| md / txt / csv / json / 代码 | — | ✅ | ✅ |
| html | — | ✅ | ✅ |
| docx / pptx / xlsx | ✅(转 PDF 再逐页出图) | ✅ | ✅ |
| doc / ppt / xls(老格式) | ✅ | — | ❌ 会提示 |
| ✅(浏览器阅读器) | — | ✅ 有文字层的;扫描件会提示 | |
| png / jpg / gif / webp / bmp / svg | ✅ | — | 开「图片理解」后可搜(描述成文字再索引) |
架构
一个插件的两半:浏览器侧只负责界面(三个插槽),所有读写/解析/索引都在 Host 进程里;两边只通过同源 HTTP 通信,Host 侧再落到本机 SQLite 和文件目录。AI 那一侧只注册三个只读工具 + 一段系统提示,不另造聊天窗——会话日志仍然是唯一真相。
模块职责见 lib/ 下的文件头注释;设计过程与踩过的坑记在 docs/DESIGN.md(含每一轮反馈的原因与改法)。
开发与测试
不需要构建步骤,纯 ESM + 浏览器端 __ModuleLoader__ 工厂。
# Host:解析 / 中文检索 / 三工具 / 树增删改 / 预览器降级
$env:ELECTRON_RUN_AS_NODE=1
& "<DeepSeek Harness.exe>" test/smoke.mjs
# Client:模块注册 / 插槽 / 各种状态渲染 / 树展开 / 缩略图 / 大屏 / 设置
& "<DeepSeek Harness.exe>" test/client-smoke.mjs
# 向量检索链路:自带一个假 embeddings 服务,验证写入向量 + hybrid 检索 + 接口挂了降级
& "<DeepSeek Harness.exe>" test/vector.mjs
# 真实视觉联调(可选,会真的调一次接口并产生费用)
$env:KB_TEST_LIVE = "1"
& "<DeepSeek Harness.exe>" test/vision-live.mjs [可选:图片路径]
$env:KB_TEST_LIVE = ""
# 密钥扫描:确认仓库里没有 API Key / 私钥 / token(提交前跑一下)
& "<DeepSeek Harness.exe>" test/no-secrets.mjs
仓库里不含任何真实文档,docx / xlsx 解析用例默认跳过。想覆盖真实文件解析,指一个你自己的样例:
$env:KB_TEST_DOCX = "C:\path\to\any.docx"
$env:KB_TEST_XLSX = "C:\path\to\any.xlsx"
用 DSH 自带的 Electron 可执行文件跑,是因为
node:sqlite需要 Node 24(DSH 内置),系统 Node 可能没有。
已知限制
-
老版 Office(
.doc/.ppt/.xls)能看原版式,但不抽正文,搜不到里面的字 -
扫描件 PDF / 纯图片没有文字层,搜不到内容
-
原版式转换受 DSH 的 office-kit 限制,默认
maxInputBytes = 50 MB。超过时不是卡住,而是立刻提示原因(可切「文字版」或「下载」)。 想放宽:在 profile 的cordis.patch.yml里给 office-kit 加一段配置(maxInputBytes必须 ≤maxSourceBytes):- id: office-kit name: "@deepseek-ai/dsh-office-kit" config: maxInputBytes: 209715200 maxSourceBytes: 314572800 maxOutputBytes: 314572800 timeoutMs: 300000本机没装原生 LibreOffice 时走的是 WASM 引擎:57 MB 的 PPT 实测转换约 58 秒,再大只会更慢,所以放宽上限主要适合"偶尔一个大文件"。
-
单次渲图最多 200 页
-
桌面端不允许插件页面开新窗口,所以「大屏」是应用内全屏,不是独立窗口
License
MIT