dsh-knowledge-suite

dsh-knowledge-suite — 资料库知识能力插件（DeepSeek Harness 桌面版）

English | 中文

把 DeepSeek Harness 的资料库（knowledge）能力从应用内置改为可单独装卸的桌面插件。装上之后，设置面板里出现「资料库」区块（上传 / 列表 / 删除文档），模型侧拿到 knowledge 工具，每轮对话开始前自动做一次文档召回注入；卸载之后功能退回应用内置默认状态，运行时文件与配置一字不差地还原。

六个包、不自行安装 npm 依赖、零业务行为变化——只是把上游硬编码在 dsh-base / dsh-web-app 里的那 5 行搬到插件侧重新注册（配置值原样保留，含你之前手加的 64MiB 单文件上传上限）。

为什么需要「摘除」这一步

上游把知识能力写死在两个内置包的 cordis.patch.yml 里，随安装包分发：

只要这 5 行还在上游，插件再插一份就会撞车。三种插法的实测结果（2026-09-15 冷启复现）：

所以 install.ps1 干的事是：备份 → 复制插件包 → 从上游摘除那 5 行 → 由插件重新注册。摘除是硬性前提，不是可选优化。

摘除逻辑 fail-loud：如果上游只摘到 2/3 行（结构变了），脚本会中止并且不改动该文件，而不是留下一个半残的运行时。

安装 / 卸载

安装（右键 install.ps1 → 使用 PowerShell 运行，或）：

powershell -ExecutionPolicy Bypass -File install.ps1

五步：

1. 备份到 %LOCALAPPDATA%\DshNative\backup-dsh-knowledge-suite-<时间戳>（desktop.yml + 两个上游 cordis.patch.yml + 六个运行时包，写 manifest.json 记录 md5）
2. 复制六个插件包到 %LOCALAPPDATA%\DshNative\runtime\node_modules\@deepseek-ai\
3. 从 dsh-base 摘除 3 行、从 dsh-web-app 摘除 2 行
4. 改写桌面 overlay %LOCALAPPDATA%\DshNative\desktop.yml：清掉旧的插件标记块（幂等）、接管那条已失去目标的 64MiB knowledge-store 补丁行、追加插件注册块
5. 汇总打印包名 / 备份路径 / 回滚方式

重启 DeepSeek Harness 后生效。

卸载（回滚）：

powershell -ExecutionPolicy Bypass -File uninstall.ps1
# 指定某次备份：
powershell -ExecutionPolicy Bypass -File uninstall.ps1 -Backup <备份目录>

从最近一次备份还原两个上游 cordis.patch.yml 与六个运行时包，摘除桌面 overlay 的插件块，把 64MiB 补丁行原样放回。结果 = 本插件没装过。

幂等与覆盖安装

• install.ps1 可反复运行：会先备份当前状态，再去重写入。
• 应用覆盖安装后若上游那 5 行回来了（安装包会把 dsh-base / dsh-web-app 覆盖回原样），知识区块会消失或报重复注册——再跑一次 install.ps1 即可修复，不必先卸载。

六个包的分工

dsh-retrieval（检索原语）与 dsh-atomic-write（原子写）是共享原语，仍留在上游——它们被 memory 等其它能力共用，不属于本插件。插件只接管上面这六个。

零行为变化

pkg/ 里的六个包是从运行时已部署的包字节级复制的（79 个文件 md5 全一致），不是从仓库源码重新构建。这样保证：

• 插件启用后与「上游内置」在语义上完全等价，不改一行业务代码；
• 唯一的差异是注册位置（内置 → 插件），以及 ui-knowledge/client.js 与仓库 lib/ 版本的模块 import 顺序不同（语义等价，改用运行时字节正是为了避开这个差异）。

配置（desktop.yml）

插件注册块（install.ps1 写入 %LOCALAPPDATA%\DshNative\desktop.yml）：

- insert:
    - id: knowledge-store
      name: '@deepseek-ai/dsh-knowledge-store'
      config:
        root: !!js dshHomePath('knowledge')
        minScore: 0.35
        chunkSize: 1200
        maxUploadBytes: 67108864     # 单文件上传上限 64MiB（默认 32MiB）
    - id: tool-knowledge
      name: '@deepseek-ai/dsh-tool-knowledge'
      config:
        maxResults: 8                # 单次搜索返回条数
    - id: knowledge-recall
      name: '@deepseek-ai/dsh-knowledge-recall'
      config:
        topK: 5                      # 首步召回条数
        minScore: 0.35
        firstStepOnly: true
    - id: knowledge-controller
      name: '@deepseek-ai/dsh-api-knowledge-controller'
    - id: ui-knowledge
      name: '@deepseek-ai/dsh-client-ui-knowledge'

root: !!js dshHomePath('knowledge') → 文档库落在 ~\.dsh\knowledge。

验证

test\ 下四个脚本，全部可直接运行、不需要 API key：

powershell -ExecutionPolicy Bypass -File test\verify-all.ps1

verify-all.ps1 依次跑三个脚本各自子进程并汇总（共 58 项断言，另有 3 个脚本结果汇总项）。安装脚本会在复制或改写前检查宿主 runtime 的 22 项运行时依赖；缺依赖时直接拒绝安装，避免留下半安装状态。

为什么用夹具而不是运行时活文件：装完之后运行时的那 5 行已经被摘掉了，拿活文件当输入只会测出「已经摘过了」，测不到算法本身。夹具是安装前从备份复制的上游 rc.2 原文快照。

目录结构

dsh-knowledge-suite\
├─ install.ps1                     # 安装（备份 → 复制 → 摘除 → 注册），幂等
├─ uninstall.ps1                   # 卸载（从备份还原上游 + 摘除插件块）
├─ README.md                       # 本文（英文）
├─ README.zh.md                    # 中文说明
├─ README.i18n.yaml                # 双语配对一致性记录
├─ docs\
│  ├─ knowledge-plugin-doc.html    # 技术文档（三张图 + 摘除前后对比）
│  └─ _shared\js\mermaid.min.js    # 内置 Mermaid，供文档中两张图使用
├─ pkg\                            # 六个插件包（运行时字节级复制，79 文件 / 225 KB）
│  ├─ dsh-knowledge\               (15 文件)
│  ├─ dsh-knowledge-store\         (19)
│  ├─ dsh-tool-knowledge\          (11)
│  ├─ dsh-knowledge-recall\        (11)
│  ├─ dsh-api-knowledge-controller\(11)
│  └─ dsh-client-ui-knowledge\     (12)
├─ tools\
│  ├─ patch-rows.ps1               # 摘除/计数助手（按 id 摘整行含 config 子树与上方注释块）
│  └─ copy-tree.mjs                # 递归复制（绕开本机失效的 fs.cpSync）
└─ test\
   ├─ dry-run-strip.ps1            # 摘除算法离线单测
   ├─ verify-install.ps1           # 静态 + 配置层验证
   ├─ verify-runtime.ps1           # 冷启 + 客户端取件验证
   ├─ verify-all.ps1               # 汇总跑三个
   └─ fixtures\                    # 上游 rc.2 cordis.patch.yml 原文快照

注意事项

• 仅 Windows + DshNative 桌面版（%LOCALAPPDATA%\DshNative）。安装前需先启动过一次应用，让运行时与 desktop.yml 生成出来。
• .ps1 必须带 UTF-8 BOM：Windows PowerShell 5.1 会把无 BOM 的脚本按 GBK 解析，中文注释变乱码直接语法错误。本插件所有脚本已带 BOM，改脚本时请保留。
• 不要手工删改 desktop.yml 里的 >>> dsh-knowledge-suite BEGIN/END 块——卸载依赖它定位。
• 卸载是从备份还原而非反向推导：如果备份目录被删掉，卸载会中止（fail-loud）而不是猜。
• 备份目录 backup-dsh-knowledge-suite-* 确认无误后可自行删除；卸载后建议保留一份以防万一。

相关

• 技术文档（能力分布图 / 三条语义陷阱详解 / 摘除前后对比）：docs/knowledge-plugin-doc.html