本地资料库 gaoheng980610/dsh-knowledge-base

dsh-knowledge-base · DSH 资料库

给 DeepSeek Harness 用的本地 Markdown 资料库插件：一边是给人看的可浏览面板，一边是给会话用的检索工具。

| 半边 | 文件 | 能力 |
| Host | lib/index.js | node:fs 读写 $DSH_HOME/knowledge-base/；webServer 开同源 HTTP 路由；向 ctx.tools 注册 kb_search / kb_read 两个 Agent 工具 |
| Browser | lib/client.js | __ModuleLoader__ 装载；侧边栏「资料库」入口 + 中栏面板（搜索 / 分类树 / Markdown 阅读 / 在线编辑） |

安装

推荐：按 tag 从仓库安装（锁定到具体提交，可重复安装与升级）
dsh plugin --profile <你的 profile> add "github:gaoheng980610/dsh-knowledge-base#v0.1.1"

也可以装 Release 里的预构建压缩包：

dsh plugin --profile <你的 profile> add "https://github.com/gaoheng980610/dsh-knowledge-base/releases/download/v0.1.1/dsh-knowledge-base-0.1.1.tgz"

压缩包直链在 pnpm 11 上有已知问题：第一次安装正常，再次安装/升级同一链接会报 ERR_PNPM_MISSING_TARBALL_INTEGRITY（store 里已有该包，但 lockfile 条目没有 integrity 字段）。
需要重复安装或升级的，用上面的 github: 方式。

dsh plugin add 会同时把 dsh-knowledge-base 写进 profile package.json 的 dsh.profile.bundles；装完重启 DeepSeek Harness——profile 的 bundle roster 在宿主进程启动时装载，宿主半边（HTTP 路由 + Agent 工具）与浏览器半边都要重启后才生效。

卸载：dsh plugin --profile <profile> remove dsh-knowledge-base（若 dsh.profile.bundles 中仍留有该行，一并删掉）。

从源码改动迭代时可以用 link 方式安装（改完即时生效，仍需重启）：

cd $env:DSH_HOME\profiles\<profile>
node <pnpm.mjs> add link:<本包路径>

为什么这样做

DSH 里唯一跨会话可见且可检索的载体是「技能目录 + 插件工具」。本插件把资料库做成插件，于是同一份内容有两条取用通道：

- 会话：任何会话都能调 kb_search / kb_read，按需取用，不用把资料塞进上下文
- 人：GUI 侧边栏「资料库」面板，可搜索、阅读、在线新建/编辑

数据布局

$DSH_HOME/knowledge-base/ （默认 ~/.dsh/knowledge-base/） <分类>/<名称>.md ← 目录即分类；id = 相对路径去掉 .md .trash/ ← 删除的资料（可恢复）

文件头支持 YAML frontmatter（title / tags / category / updated / source），没有也能用（标题取文件名）。

插件本体不含任何资料内容：安装后资料目录是空的，资料由你自己写进去，只存在本机。

Agent 工具

| 工具 | 说明 |
| kb_search | { query?, limit? }。query 空格分词，需全部命中；不传 query = 列出全部资料目录 |
| kb_read | { id }。返回该资料全文 Markdown |

HTTP 端点（浏览器半边用）

前缀 /knowledge-base，均 POST + JSON：

| 端点 | 入参 | 返回 |
| list | — | { ok, root, entries[] }（不含正文） |
| read | { id } | { ok, entry }（含正文） |
| save | { id?, title, tags, body, category? } | { ok, id }；id 省略时按 分类/标题 新建 |
| delete | { id } | { ok, id }（移入 .trash） |
| search | { q, limit? } | { ok, hits[] }（按标题/正文计分，带摘要） |
| stats | — | { ok, total, categories, latest[] } |

开发与自测

node --check lib/index.js
node --check lib/client.js
node test/smoke.mjs # 离线冒烟：假 ctx/window/react 驱动两半边，36 项断言

test/smoke.mjs 不需要 DSH 就能跑，覆盖：路由全端点、frontmatter 读写、全文搜索与计分、路径穿越防护、.trash 删除、两个 Agent 工具、浏览器半边的槽注册与面板渲染。

踩坑记录（cordis · 勿回退）

1. 没在 inject 里声明的服务，属性访问会直接抛异常

export const inject = ['webServer'] // 只声明了 webServer
const tools = ctx.tools // ❌ Error: cannot get property "tools" without inject

致命之处：apply() 抛异常会让 cordis 把该 fiber 的全部 effect 回滚——
包括已经注册成功的 HTTP 路由。现象极具迷惑性：
- 浏览器半边独立加载 → 侧边栏「资料库」入口与面板正常显示
- 但所有接口返回 405（落到静态处理器），面板提示「无法连接 Host 半边」

修复：用到的服务都写进 inject；可选能力一律 try/catch 兜底。

2. inject 只支持数组形式

export const inject = { required: ['webServer'], optional: ['tools'] } // ❌
// 现象：插件停在 pending (waiting for services: required, optional)

对象形式不被该 cordis 版本支持——键名会被当成服务名去等待。只用数组：

export const inject = ['webServer', 'tools']

3. 排查姿势：一定要看宿主启动输出

未激活的插件会写在启动输出里：

dsh: warning: 1 entry did not activate
ui-knowledge-base (dsh-knowledge-base): Error: cannot get property "tools" without inject

快速迭代环境（不必反复重启正在用的实例）：复制一份 profile，node_modules 用 junction 复用，换端口起独立实例：

profiles\kb-verify\package.json ← 复制 desktop；node_modules ← junction 到 desktop\node_modules
dsh --profile kb-verify --port 19997 --no-open --host 127.0.0.1
注意：语法是 dsh --profile <name> <app参数>，不要写成 dsh --profile x web

之后直接用 HTTP 打端点验证。用完记得先解除 junction 再删目录，避免误删 desktop 的 node_modules。

安全边界

- 所有 id 经 idToPath() 归一化并拒绝 .. / 绝对路径 / 非 .md，不能越出资料根目录
- 正文单份上限 4MB；list 不返回正文，避免把整个资料库灌进上下文
- delete 是软删除（移入 .trash），可手工恢复
- 插件不引入任何第三方依赖（浏览器半边只用宿主内置的 react）
- 资料只在本机读写，插件不发起任何外部网络请求

许可

MIT