dsh-company-kb

dsh-company-kb

给 DeepSeek Harness 用的本地文件夹知识库插件：把公司资料目录建成一个中文可用的检索索引， 写方案 / 投标 / 核政策时按需调用；只在用户明确点名时检索，只在用户手动触发时同步。

• 索引对象：本地任意目录（在面板「设置」页填 roots），只读，插件永不写入
• 检索方式：中文分词 BM25 + 中文二字组合 + trigram 子串 → RRF 融合（全离线，零外部服务）
• 文档预览：.docx / .xlsx / .pptx 由插件自己解析成带排版的 HTML（Word 保留标题/表格/图片， Excel 是真表格网格，PPT 是分页卡片）——不启动 Office、不转 PDF、不写临时文件
• 图里的字也能搜：文档内嵌图片（架构图、界面截图）走 OCR，按 sha1 缓存，重建不重复识别
• 同步方式：纯手动（面板按钮 / 明确要求 / 命令行），没有任何定时器
• 交付形态：5 个模型工具 + Web 面板（侧边栏底部面板入口 / 会话开关 / 设置页）+ company-kb 技能

安装

环境要求：DSH 0.1.5 及以上，Node.js ^22.19.0 || >=24.0.0；OCR 与旧版 Office 抽取需要 Windows（可选，缺了不影响其它格式）。

# 方式一：从 GitHub 安装（pnpm 原生支持 git 源）
dsh plugin --profile <你的 profile> add github:wu81313-lab/dsh-company-kb

# 方式二：克隆到 profile 的 plugins/ 目录后按本地目录安装
cd <DSH_HOME>/profiles/<你的 profile>
git clone https://github.com/wu81313-lab/dsh-company-kb.git plugins/dsh-company-kb
dsh plugin --profile <你的 profile> add ./plugins/dsh-company-kb

# 确认 package.json 的 dsh.profile.bundles 含本行，并校验组合树
dsh --profile <你的 profile> --dump-config | findstr company-kb

# 重启 profile（宿主侧改动需要重启），然后刷新页面（客户端 bundle 需要刷新）

安装后打开「设置 → 插件 → 本地知识库」填好资料目录，再点面板「立即同步」建库。

卸载：dsh plugin --profile <你的 profile> remove dsh-company-kb，再从 dsh.profile.bundles 移除该行； 数据目录 ~/.dsh/local-kb 可整体删除，知识库原文件夹自始至终零改动。

快速上手

1. 先在「设置 → 插件 → 本地知识库」填好资料目录（roots），然后首次建库（二选一）：
   • 打开左栏「本地知识库」→ 点「立即同步」（首次约 1–5 分钟，含扫描件 OCR）
   • 或在终端：node lib/cli.mjs index
2. 在对话里点名使用：
   • 用知识库查一下 XX 政策的条款要求
   • 按 模板/技术方案书模板.docx 写一份 XX 项目方案
   • 或点输入框右侧的「知识库 已关」开关
3. 资料更新后手动同步：面板「立即同步」，或说"同步一下知识库"，或 node lib/cli.mjs index。

不点名、不打开开关，检索工具会直接返回一段说明而不会去查资料。

目录结构

lib/
  index.js         Cordis 插件入口：装配内核、注册工具、注入状态提示段、挂载 Web API
  core.js          内核：设置 + 索引库 + OCR 桥 + 同步引擎的组合，供工具/面板/CLI 共用
  store.js         SQLite(node:sqlite) + 双 FTS5 索引 + RRF 融合检索
  segment.js       中文分词、二字组合、FTS 查询构造与转义
  bigram.js        中文相邻二字组合（解决分词器把"袋线瓶线"切碎的问题）
  chunk.js         分块：标题面包屑、页码、重叠、超长段落切分
  scan.js          同步引擎：遍历 diff → 抽取 → 写库；手动触发，无定时器
  gate.js          显式调用门禁（触发词 / 路径点名 / 会话开关 / 同步意图）
  prompt.js        状态提示段（未启用 / 已启用 / 尚未建库 / 索引已过期）
  tools.js         kb_search / kb_read / kb_list / kb_status / kb_session
  web.js           宿主 HTTP API（同源，供面板调用）
  ocr.js           OCR / Word 助手桥（临时文件传参，不用管道）
  ocr-helper.ps1   Windows PowerShell 5.1 + WinRT：PDF 渲染、图片 OCR、Word COM
  open.js          用系统默认程序打开 / 在资源管理器中定位（explorer /select + 前台提权）
  focus-helper.ps1 把资源管理器窗口提到前台（后台进程默认不许抢前台，靠 AttachThreadInput 提权）
  settings.js      运行时设置（settings.json，热生效）
  client.js        客户端 bundle（手写 __ModuleLoader__ + React.createElement）
  render/          文档预览：docx → 排版化 HTML、xlsx → 表格网格、pptx → 分页卡片（零依赖）
  cli.mjs          命令行：status / probe / index / search / read / list
  selftest.mjs     验收自测：抽取覆盖率 + 15 条金标查询
  extract/         zip / docx / xlsx / pptx / text / media（零第三方依赖）
test/              node --test 单测（门禁、分词、分块、索引、HTTP、手动同步语义、面板渲染、文档预览）
skills/company-kb/ 技能：检索流程与引用规则

数据目录（可整体删除）：%USERPROFILE%\.dsh\local-kb\ → index.sqlite、settings.json

工具

Web 面板

挂在 DSH 自己的 Web 服务下（同源路由 /company-kb-api/*，仅回环可访问，不开新端口）：

• 侧边栏底部「本地知识库」（在「设置」按钮上方，独占一行）：索引概况（文件数/字符/检索片段/上次同步/失败/待同步变化）、立即同步、重建索引、中止、进度条、搜索（含原文预览与失败清单）、同步记录
  • 搜索框下面有筛选行：类型（Word / Excel / PPT / PDF / 图片 / 文本）、时间（近 30/90 天/一年）、目录， 比如"只看近 90 天的投标文件"。
  • 「未抽取正文的文件」清单里每项都能单独重抽，也可以一次「全部重抽」—— 只重抽这几个文件，不是整库重建。
  • 面板分「搜索」「同步记录」两个页签；/company-kb-api/tree 与 kb_list 工具仍可用于浏览目录，只是不再占用面板页签。
  • 该入口挂在 sidebar.footer.action（与「上下文洞察」同一个行容器），插件把这一行改成竖排， 于是「上下文洞察」/「本地知识库」/「设置」各占一行、不会互相挤压、标签也不会被截成「本…」。 宿主的类名是 CSS Module 哈希（每次构建都会变），所以规则写成 后缀匹配 + :has() 兜底 （[class*="_footerActions"]:has(.dslkb-foot)）；侧栏收窄成图标条时自动退回圆形图标形态。
• 原文预览（点搜索结果或「同步记录」里的文件名即打开）：
  • 「用本机程序打开」= 交给系统默认程序，等价于双击：.docx/.doc → WPS/Word，.xlsx → WPS/Excel，.pptx → PowerPoint，.pdf → PDF 阅读器；.dwg 等图纸同理。打开后你可以直接在里面查看甚至编辑（原文件本身仍是你的，插件不参与写入）。
  • 「在文件夹中显示」= 在资源管理器中定位该文件，并把资源管理器窗口提到前台（focus-helper.ps1）。
  • 图片与 PDF 在面板内直接渲染（/raw 直出原文件）。
  • .docx / .xlsx / .pptx 走排版预览（/preview）：插件解析文件结构渲染成 HTML —— Word 保留标题层级、加粗斜体、列表、表格、内嵌图片；Excel 渲染成真正的表格网格（行号列标、 合并单元格、多工作表、日期/百分比/千分位格式）；PPT 渲染成分页卡片。可随时切到「抽取正文」看纯文本。 这一路不启动 Office、不转 PDF：79MB 的投标 docx 渲染 3935 段 + 38 表 + 287 图只需 210ms。 旧版 .doc/.xls/.ppt 是二进制格式，仍只显示抽取的文字。
  • 从检索结果点开的文档会自动滚到第一处命中并高亮，上方有「命中 N 处 / 上一处 / 下一处」； 高亮做在服务端渲染阶段（只作用于已转义的纯文本），不会碰坏文档结构。
  • 「重建索引」防误触：点它会先弹出确认框（写清代价与影响、并强调原文件不会被修改）， 点「确认重建」才开始；Esc 或点遮罩可取消。
  • 每次操作都有可见反馈：开始后在按钮下方出现「已开始…」横幅 + 进度条，跑完变成 「✓ 重建完成：新增 102｜耗时 54.2s｜内嵌图片 575 张」这样的结果横幅（20 秒后自动消失）。
  • 预览区可自由调整：拖中间的竖条改左右宽度（26%–80%）、拖预览右下沿改高度（320–1200px）， 也可以直接点「紧凑 / 标准 / 加高 / 满屏」；满屏会隐藏结果列表、预览占满窗口（Esc 退出）。 双击手柄或按 Home 恢复默认；手柄支持方向键微调。选择记在浏览器 localStorage，刷新后仍在。
  • 预览右上角还有「新标签页」：把渲染好的整页丢给浏览器，用整屏看长文档。
• 输入框右侧「知识库」开关：切换本会话是否允许检索（等价于点名）
• 设置 → 插件 → 本地知识库：根目录、同步方式、显式调用、路径点名、trigram、旧版 Office 处理、触发词（全部热生效，不用重启）

面板不可用时（例如客户端 bundle 没加载）工具与索引照常工作。

配置

行配置在 cordis.patch.yml（启动默认值），运行时覆盖在 ~/.dsh/local-kb/settings.json（面板写入，热生效）。

手动同步模型（本插件与"自动同步"的边界）

• 索引只在三种显式触发下变化：面板按钮 / 用户明确要求（kb_status action=now，同样过门禁）/ CLI。
• 启动不扫描：只打开数据库、校验 schema，并做一次"体检"（stat 比对，只报告差异）。
• 检索结果与状态卡会提示"索引之后有 N 个文件变化"，提醒你手动同步，但绝不偷偷重建。
• 每次同步按文件单事务提交：中止、断电、DSH 重启都不会留下半写的块，下次同步自然续做。
• 同步摘要（新增/更新/删除/跳过/失败/耗时）写入 sync_log，面板「同步记录」可查； 每条记录下面还会逐文件列出这次到底同步了哪些内容（新增 / 更新 / 删除 / 失败四组， 带相对路径；新增与更新的文件可一键在资源管理器中定位）。老记录没有明细，就只显示摘要。

「立即同步」与「重建索引」的区别

一句话：改了资料 → 立即同步；改了设置或想让老文件彻底重来 → 重建索引。

内嵌图片 OCR（图里的字）

• 有正文的 Office 文档也会抽内嵌图片做 OCR：架构图标签、界面截图、表格截图里的字本来完全搜不到。
• 三个刹车：小于 embeddedImageMinBytes（默认 20KB）的图当 logo 跳过；单文件最多 maxEmbeddedImagesPerFile（默认 40）张；结果按图片内容 sha1 缓存，重建索引时同一张图不再重复识别。
• 第一次开启会慢一些（本机语料 34 个文件 / 668 张图，约 6 分钟），之后重建只需要几秒。
• 新开的开关不需要整库重建：插件给每个文档记了 media_ocr 标记，下次普通同步会把还没做过的 Office 文件逐个补做一次。
• 识别出来的文字会带 【图片N】 前缀单独成块，引用时能看出"这段来自图片"。

只重抽某几个文件

同步记录里失败的文件（needs_ocr / needs_conversion / 抽取报错）可以在面板上单独重抽， 不必整库重建；命令行等价动作是 POST /company-kb-api/resync {"rels":["某个文件.docx"]}。 日志里这次同步会记成 同步(retry)，明细照常列出改了哪些文件。

为什么这样检索

抽取能力

OCR / Word 都不可用时不会报错中断：相应文件标为 needs_ocr / needs_conversion 并在状态里列出。

故障排查

验收

node --test test/*.test.mjs          # 77 项单测：门禁/分词/分块/索引/HTTP/面板渲染/文档预览/内嵌图片 OCR/重抽/预览布局/回环校验
node lib/selftest.mjs --rebuild      # 全量重建 + 抽取覆盖率 + 15 条金标查询
node lib/cli.mjs status              # 状态与失败清单
node lib/cli.mjs search "关键词"

单测里 手动同步语义 一项是这套设计的核心保证：新增文件后直接检索必须搜不到，手动同步后才搜得到，删除后同步即消失。

安全边界

• 插件对知识库目录只读：只调用读操作，从不写入、移动或删除其中任何文件。
• /preview 只读解析已在索引中、且位于配置根目录之内的文件，渲染结果放进 iframe（沙箱 + CSP：禁止脚本、禁止外部请求），文档里的文本一律转义。
• 唯一的写入目标是 ~/.dsh/local-kb/（索引库与设置）与系统临时目录（OCR 中间文件，用完即删）。
• Web API 挂在 DSH 自身站点下（默认 127.0.0.1:8080），能力仅"读索引 + 触发同步 + 读写插件设置
  • 打开/直出已在索引中且位于配置根目录之内的文件"；接口只接受回环 Host（挡 DNS rebinding）。 若把 DSH 暴露到公网，该接口与 DSH 本身同权，请用反向代理加登录保护。
• /open、/reveal、/raw 都先经 resolveOriginal() 校验：文件必须在索引里、路径必须落在 roots 之内、且磁盘上确实存在，否则一律 403/404；打开动作是"只读打开"（把文件交给关联程序）， 插件不写入原文件。
• Word 提取以 AutomationSecurity = 3（强制禁用宏）只读打开文档。

License

MIT © wu81313-lab