dsh-knowledge

Readme

# dsh-knowledge 📚

**DeepSeek Harness 本地知识库插件(三期全:文档知识库 + 会话经验库 + 网页剪藏/Web 面板)**——纯本地、零依赖的全文检索 + 实战经验沉淀 + 网页收藏。导入 markdown/笔记/配置/源码到 SQLite FTS5 索引,模型回答时自动检索并**标注来源**;对话中解决的实际问题,模型会**主动**提炼成经验条目入库;网页教程一键剪藏;`kbquery` 围栏渲染交互式浏览面板。

> 🔌 生态:仓库已挂 `#dsh` · `#dsh-plugin` · `#knowledge-base` · `#rag` · `#fts5` topic。

## ✨ 特性

- **零 npm 依赖**:用 Node 24 内置 `node:sqlite`(DSH 官方会话检索同款引擎)+ 内置 fetch,不调 embedding API,完全离线
- **中文友好**:FTS5 `trigram` 分词 + 短词 LIKE 兜底,中文/代码/混合文本直接搜
- **带来源检索**:命中片段返回 `来源路径 + 标题 + 行号区间`,模型回答强制引用
- **经验库(二期)**:对话解决实际问题时模型**主动** `kb_remember` 入库;`kb_ingest_session` 读取历史会话(zstd 多帧解码)补录经验
- **网页剪藏(三期)**:`kb_add_url` 抓取网页 → 启发式正文提取(去导航/页脚/脚本)→ 转 Markdown 入库
- **交互面板(三期)**:`kbquery` 围栏渲染搜索面板(输入框 + 结果卡片),数据走 host JSON API
- **增量导入**:文件 mtime 未变自动跳过;同 URL 重新剪藏自动更新
- **安全**:导入路径限定工作区,二进制/PDF 跳过,抓取限 4 MiB
- **单文件存储**:`~/.dsh/knowledge/kb.sqlite`,可整体备份

## 工具

| 工具 | 说明 |
|---|---|
| `kb_add` | 导入文件或文件夹(默认递归),返回 per-file 状态与块数 |
| `kb_add_url` | 剪藏网页入库(kind=web,path=url:…),同 URL 自动更新 |
| `kb_search` | FTS5 BM25 全文检索文档+经验+网页,返回带来源的片段 |
| `kb_stats` | 文档数、块数、经验数、类型分布、库路径 |
| `kb_list` | 列出已入库文档(最新优先) |
| `kb_remember` | **主动**记录一条实战经验(title/problem/solution/tags/source) |
| `kb_ingest_session` | 读取历史会话转写补录经验(无参=列会话,带 sessionId=读转写) |
| `kb_experiences` | 列出已记录的经验 |

## 交互面板

模型输出 `kbquery` 围栏即渲染面板(你说"打开知识库面板"/"搜一下知识库"即可触发):

````markdown
```kbquery
{"placeholder":"搜索知识库…"}
```
````

支持 `{"q":"UE4.27 MCP"}` 预填搜索。面板数据来自 host API:`/plugins/dsh-knowledge/api/{search,list,stats}`。

## 🌌 知识图谱(Obsidian 风格)

窗口**右下角**(网易资产库图标正上方)有一个常驻悬浮 🌌 按钮,点击打开**Obsidian 式知识图谱**:

- **布局**:力导向——共享关键词的节点自动聚成星团,不同主题自然分离,布局稳定不重叠;**节点可拖动整理**(拖过的固定);**打开时节点从中心缓缓散开落位**(入场动画);**拖动节点时,其关联节点(1-2 层)被弹簧联动拉动,松手后弹性回弹**(Obsidian 式联动物理)
- **节点**:彩色圆点(文档蓝 / 网页绿 / 经验橙),**大小 = 内容量**(大文档大圆、小笔记小圆,差异明显);**常驻显示精简标签**(约 5 字,紧凑不挡);**悬停/选中展开为"图标+完整标题"**;节点带轻微呼吸脉动
- **连线**:细淡灰线(Obsidian 式),关联越强越亮;可勾选"显示连线"开关
- **动态效果**:入场散开动画、**节点缓慢漂移游走 + 残影轨迹**(Obsidian 粒子感)、点击涟漪扩散
- **左侧过滤面板**:
  - 搜索框实时过滤节点
  - 类型复选框(文档/网页/经验)开关显示
  - 显示标签 / 显示连线开关
  - 复位 / 刷新 / 关闭
- **交互**:点击节点 → 邻居+连线点亮、其余变暗 + 涟漪;右侧滑入**详情面板**(全文 + 关联知识列表可跳转);拖空白平移;滚轮光标锚定缩放;双击/Esc 复位
- **入口按钮可拖拽**,默认停在右下角、网易资产库图标上方
- 数据来自 `/api/graph`(节点+边)与 `/api/doc`(全文)

## 安装

```sh
# GitHub 仓库安装
dsh plugin --profile web add https://github.com/dhb861832993-star/dsh-knowledge#v0.2.1

# 或本地开发
dsh plugin --profile web add link:/path/to/dsh-knowledge
```

重启 dsh web,新会话生效。装完后问一句"知识库里有什么",模型会用 `kb_stats` 告诉你状态。

## 快速上手

```text
用户: 把我的 UE4.27-MCP-配置说明.md 和笔记文件夹导入知识库
模型: (调用 kb_add 导入,然后 kb_stats 确认)

用户: 上次 UE4.27 MCP 的端口配置是多少?
模型: (kb_search "UE4.27 MCP 端口",引用来源路径和行号回答)
```

## 架构

- `lib/index.js` — host 半边:`kb_*` 工具 + 系统提示段 + `/plugins/dsh-knowledge/api` JSON API
- `lib/client.js` — 浏览器半边:`kbquery` 围栏 → 交互式搜索面板(输入框 + 结果卡片)
- `lib/session-log.js` — DSH 会话日志读取:zstd 多帧扫描解码(`scanZstdFrames`)+ JSONL 解析 + 转写提取
- `lib/clip.js` — 网页剪藏:内置 fetch + 启发式 HTML→Markdown 正文提取(readability-lite)
- 存储:`node:sqlite`(`DatabaseSync`),docs / chunks / experiences 普通表 + `chunks_fts` / `experiences_fts` FTS5 虚拟表(trigram)
- 分块:按行切块(默认 800 字符/块,120 字符重叠),保留 1-based 行号区间
- 检索:长词走 FTS5 BM25(OR 组合),短词(中文双字词)走 LIKE 兜底,经验条目与文档统一返回

## 自测

```sh
node scripts/selftest.mjs
```

自测脚本模拟 DSH 的 `ctx` 环境,真实调用全部七个工具,验证导入→检索→统计→列出→经验记录→会话读取的全链路。

## 安全

- 导入路径解析后必须落在工作区根内(绝对/相对都校验,防越界)
- 二进制扩展名黑名单拒绝读取
- 数据库只写 DSH home 下的固定位置,不触碰其他路径

## License

MIT