Passer au contenu principal
F

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.

Installer

dsh plugin --profile web add github:fsnh/dsh-plugin-knowledge-base

README

DSH 个人知识库插件

npm license

把本地文件整理成树状知识库,在 DeepSeek Harness 里直接读、直接搜,AI 也能检索并针对某一篇文档对话。

数据全在本机(默认 ~/.dsh/kb),不经过任何云端。

界面示意图

界面示意图(跟随 DSH 主题与窗口宽度变化)

它解决什么问题

你在电脑里攒了一堆培训 PPT、会议纪要、登记资料、报价单——平时找一份东西要翻好几个文件夹,找到了还得自己读一遍。

这个插件把它们组织成树状目录,然后给你两件事:

  1. 看得见原样:点开就是 PPT/Word/Excel 的原始版式(不是抽出来的文字),左边缩略图栏点哪页跳哪页;
  2. 问得出来:任何会话里问"我的资料里有没有关于 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/v1qwen3-vl-plus
硅基流动https://api.siliconflow.cn/v1Qwen/Qwen2.5-VL-72B-Instruct
OpenAIhttps://api.openai.com/v1gpt-4o-mini
本机 Ollamahttp://127.0.0.1:11434/v1qwen2.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/v1text-embedding-v4
硅基流动https://api.siliconflow.cn/v1BAAI/bge-m3
OpenAIhttps://api.openai.com/v1text-embedding-3-small
本机 Ollamahttp://127.0.0.1:11434/v1nomic-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(老格式)✅—❌ 会提示
pdf✅(浏览器阅读器)—✅ 有文字层的;扫描件会提示
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

Plugins associés