dsh-personal-kb

English — A local personal knowledge base plugin for DeepSeek Harness: ingest PDFs, images, web pages and notes into an on-device knowledge base, auto-compile them into structured Wiki pages with a multi-agent pipeline, and let the AI recall them in conversation. 100% local, no cloud.

DSH 个人知识库插件 —— 让 AI 真正记住你读过的东西。

把 PDF、图片、网页、笔记存进本地知识库，多代理管线自动编译成结构化 Wiki；之后在对话里随问随取，AI 会自动召回相关知识来回答——全程数据不出你的电脑。

拖入论文 PDF → AI 存入知识库 → 自动编译成 Wiki
三个月后问："我之前存的那篇图神经网络讲异常检测的，贡献点是什么？"
→ AI 自动从知识库召回原文，引用作答

为什么需要它

• AI 没有长期记忆：聊过的论文、读过的资料，关掉窗口就忘。知识库让它"越用越懂你"
• 通用 RAG 不懂你的资料：本地全文检索 + LLM 编译的 Wiki 摘要，召回比裸向量库更准
• 隐私第一：SQLite + Markdown 全部落盘 ~/.dsh/personal-kb/，无云同步、无遥测

功能

• 多模态摄取：.pdf（含扫描型）/ 图片 / 网页 HTML / 纯文本，统一管线
• 多代理编译：WikiWriter（正文编译）+ WikiLinker（双链链接）子代理，产出带 frontmatter、章节、反链的 Wiki
• 对话召回：kb_context 注入 Wiki 摘要（省 token），kb_read 按需读全文——agentic RAG 两段式闭环
• 检索：FTS5 关键词检索（trigram 分词，支持中文子串），按文件夹/层过滤
• 导出：一键打包单个 markdown bundle，喂给 Claude Projects / GPTs 等外部 AI，顺带当备份
• Web 界面：文档列表 / 文件夹树 / 图谱 / 反链 / 审批暂存区 / 健康检查
• 视觉处理外判：图片与扫描页统一走 ModLens CLI，插件本体不做多模态

工作原理

素材(PDF/图片/HTML/文本)
  → 摄取层（pdf-inspector 解析 / clawpdf 渲染扫描页 / ModLens 视觉识别）
  → raw 层（原始中间文档，Markdown + frontmatter）
  → kb_process（WikiWriter 编译正文 + WikiLinker 生成双链）
  → wiki 层（结构化 Wiki）
  → kb_context 摘要召回 / kb_search 检索 / kb_read 全文 / kb_export 打包

快速开始

前置要求

依赖	说明
Node.js 22+	用到内置 node:sqlite
DSH	已支持 dsh web
ModLens	必装（见下），图片与扫描型 PDF 的视觉识别通道

第 1 步：安装 ModLens（两种装法都需要）

# ① 对话端工具（modlens_read_image 等）
npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens

# ② CLI 进 PATH（本插件的视觉通道）
npm i -g @liustack/modlens

装好后打开 ModLens，配置任意视觉后端（支持国内 OpenAI 兼容 API）。

第 2 步：构建并注册本插件

git clone <本仓库>
cd Mnemos/packages/dsh-personal-kb
pnpm install
pnpm build          # host + client 产物都在 dist/

dsh plugin add link:<上面的绝对路径>

重启 dsh web，日志出现 dsh-personal-kb loaded 即成功。

第 3 步：存第一篇资料

对话里直接说：

/kb-save 然后拖入一个 PDF

或

把这段笔记存进知识库：……

工具返回「已存入 raw/」后，AI 会主动问「要现在编译成 Wiki 吗？」——同意即可。

对话即用法

日常使用不需要记工具名，自然语言就能触发（skill 见下）：

你说	背后发生的事
"我之前存过一篇讲 DART-GNN 的，讲讲它"	kb_context 召回摘要 → 不够再 kb_read 读全文
"毕业开题文件夹里都有什么？"	kb_context(folder=毕业开题) 列出该文件夹全部 Wiki
"把知识库导出成 md，我要喂给 Claude"	kb_export 打包单文件到 ~/.dsh/personal-kb/export/
"知识库健康状态如何？"	kb_lint 体检并报告问题

Skill（/ 命令触发）

插件自带三份 SKILL.md（skills/ 目录），通过 cordis.patch.yml 的 customSkillDirs 自动挂载——装好插件即可，无需手动拷贝。若 / 菜单没出现，重启 dsh web。

Skill	触发场景
/kb-save	拖入文件、粘贴图片/长文，或说"存进知识库 / 收录 / 记一下"
/kb-recall	回答知识类问题前检索；或问"我之前存过…吗 / 某文件夹里都有什么"
/kb-compile	把 raw 层素材编译（或重编译）成 Wiki

工具速览

工具	用途
kb_ingest_pdf	摄取 PDF（加密/超限按根因报错；扫描页走 ModLens，单篇最多 10 页）
kb_ingest_image	摄取图片（视觉识别由 ModLens 完成）
kb_ingest_html / kb_ingest_text	摄取网页 HTML / 纯文本笔记
kb_process	raw → Wiki 编译（异步，可传 folder 归档）
kb_search	FTS5 检索（raw/wiki 层，folder 可选）
kb_context	召回注入：wiki 摘要进上下文。query 按内容、folder 按文件夹（传父路径含子树），可组合
kb_read	按 doc_id 读单篇 Wiki 全文（50KB 护栏）
kb_export	打包导出单文件 markdown（outputDir 指定目录、folder/layer 过滤、50MB 分批护栏）
kb_lint	知识库健康检查

数据位置与隐私

~/.dsh/personal-kb/
├── kb.db          # SQLite 索引（FTS5）
├── raw/           # 摄取原始中间文档
├── wiki/          # 编译后的 Wiki
├── staging/       # 反链建议暂存区（审批制）
└── export/        # kb_export 默认输出目录

• 全部数据只在本地，无遥测、无云同步；可用环境变量 KB_ROOT 重定向
• 导出的 bundle 是明文 markdown，分享前请自行审查内容

FAQ

Q: 扫描型 PDF 能处理吗？ 能。扫描页由 clawpdf 渲染成图片后走 ModLens 视觉识别，单篇最多处理 10 页，超出会明确报错。

Q: 加密 PDF 呢？ 会明确报错并提示先解密，不会静默丢弃或编造内容。

Q: 编译会偷偷用我的对话模型吗？ kb_process 的子代理使用你 DSH 对话窗口当前默认模型，可在 DSH 里正常切换；除此之外没有任何外部调用。

Q: 摄取失败提示 ModLens 不可用？ 按报错文案三条路径排查：确认两条安装命令都执行过、视觉后端已配置、modlens 在 PATH 中（where modlens / which modlens）。

开发

pnpm typecheck      # 类型检查
pnpm verify         # 全量验证脚本（存储/搜索/API/标题/PDF…）
pnpm verify:usage   # 使用层（skill 资产 / kb_context / kb_read / kb_export）

设计文档见 specs/（01 存储 → 07 使用层，含全部机制调研结论与实测教训）。

License

MIT