# DeepSeek Harness 记忆搜索增强插件（Memory Search Plus）

[English](README.md) | 简体中文

Memory Search Plus 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的独立 Web 插件，为本机会话提供**跨会话全文搜索**。它在后台维护一个可重建、有容量上限的 SQLite FTS5 派生索引；原始会话始终是事实源。

本仓库带有 [`dsh-plugin`](https://github.com/topics/dsh-plugin) GitHub topic，便于在生态里被发现。

## 功能

- **跨会话搜索，而非仅当前会话。** 所有已索引的用户消息、助手回复与工具调用，都从一个入口检索。
- **全文索引，不是侧边栏过滤。** 基于 SQLite FTS5，自定义分词管线（Intl.Segmenter 中英分词 + CJK 二元组 + CJK 单字 + 英文大小写归一），中文子串、英文短语、中英混合、多关键词 AND 均可命中。
- **自适应二段式搜索。** 阶段 1 从 128 条候选起步，按需要扩张、最多扫描 2,048 条并受时间预算约束；阶段 2 做字面校验和高亮。默认返回 100 条、最多 200 条，不会把上万行正文送进 UI。
- **消息级精确定位。** 结果按会话分组、时间倒序；点击命中项会按需加载更早历史、滚动到目标消息并高亮。
- **ChatGPT/VSCode 风格 UI。** 宽侧栏中的“查找聊天记录”按钮打开悬浮结果面板，可按角色筛选（全部 / 用户 / Agent / 工具）。可用按钮或 <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd> 快捷键打开。
- **增量索引。** 新事件实时追加；压缩检查点只重建对应会话；会话删除同步移除；设置页显示重建进度。启动与每 5 分钟后台对账保证一致性。分支/fork 会话会索引；真正的子代理会话（`origin=subagent`）不索引。
- **紧凑且有界。** schema v3 使用 contentless FTS（不在 FTS 内重复保存正文）、`detail=none` 和独立文档表。用户/Agent 消息最多索引 8 Ki 字符，工具输出最多 4 Ki 字符并保留头尾；结果会标记“索引预览”。
- **完全本地运行。** 默认索引位于 `${DSH_HOME}/storages/memory-search/index.db`（WAL 模式），也可在设置页指定存放路径，或用环境变量 `DSH_MEMORY_SEARCH_DB`。默认逻辑预算 1 GiB。超过预算只淘汰最旧索引条目，不删除会话；设置页显示磁盘占用、覆盖起点和淘汰数量。插件不做网络请求或遥测。

## 性能指标（目标）

| 场景 | 目标 |
| --- | --- |
| 本地索引写入路径：100 万条模拟消息 | < 60 秒 |
| 查询（中/英/短语混合） | < 300 毫秒 |
| 增量更新 | 仅触碰变化事件 |

实测数据见基准脚本 `scripts/bench.mjs` 的 QA 输出记录。

### 容量策略

- 默认上限：1 GiB。
- `DSH_MEMORY_SEARCH_MAX_INDEX_MB=<MiB>`：调整上限（64–16384 MiB）。
- `DSH_MEMORY_SEARCH_MAX_INDEX_MB=0`：显式选择无限索引。
- 设置页可指定索引数据库路径（目录或 `.db` 文件）。保存后会把当前 `index.db`（及 WAL 附属文件）搬到新位置并删除旧文件；选择写入 `${DSH_HOME}/storages/memory-search/location.json`。
- `DSH_MEMORY_SEARCH_DB=<绝对路径>`：无 UI 覆盖时使用该路径。

索引是派生缓存；容量淘汰不会修改 DSH 会话文件。手动重建会重新读取事实源，并再次按照当前容量预算收敛。

## 安装

要求：DeepSeek Harness `0.1.1-rc.2` 或更新，以及其支持的 Node.js 版本（`^22.19 || >=24`）。

将插件安装到 Web profile 后重启 Web（或重启已有的 `dsh-tunnel` / 网关进程，以便 Host 半边重新加载）：

```sh
dsh plugin --profile web add github:the-thinker0/dsh-memory-search-plus
dsh web
```

**本地开发安装**（在本仓库目录下）：

```sh
dsh plugin --profile web add ./
```

仓库提交了必需的 `lib/` 构建产物，因此以上安装均无需 pnpm 构建脚本。

启动输出会打印 `dsh web:` 后的实际 URL（默认 `http://127.0.0.1:3080`）。

### 更新

DeepSeek Harness **不会**把新版本静默推到已经装过本插件的机器上。GitHub 发了 release 之后，要等各 profile 自己再拉一次。

如果当初是 `github:the-thinker0/dsh-memory-search-plus` 安装的，重新执行下面的命令会取到最新提交，然后重启 Web（或已有的 `dsh-tunnel` / 网关）：

```sh
dsh plugin --profile web add github:the-thinker0/dsh-memory-search-plus
```

`dsh plugin` 会转发给 profile 目录里的 pnpm，因此在支持该子命令时也可以用 `dsh plugin --profile web update dsh-memory-search-plus`。Host 半边变更后必须重启加载插件的进程；只有 Web 客户端变了时刷新浏览器即可。

`file:` / `link:` 本地目录不会跟着 GitHub 走。开发安装请自己 pull，再按原方式重装或重启。

可选：社区工具如 [dsh-market](https://github.com/dsh-market/dsh-market)、[dsh-update-copilot](https://github.com/hezhongtang/dsh-update-copilot) 能对比 lockfile 里钉住的 commit 与 GitHub HEAD，并代你执行同样的 `dsh plugin add`。那也是用户点一下才更新，不会后台自动安装。

卸载插件：

```sh
dsh plugin --profile web remove dsh-memory-search-plus
```

> 注：插件注册的 Cordis id 为 `memory-search`；移除包会连带移除该插件（含其本地索引数据库，注册 patch 的移除会再次确认）。

## 与同类功能的区别

- **对比内置侧边栏搜索 / 侧边栏会话过滤**（如 dsh-better-sidebar）：那些是针对*当前打开会话*的过滤或搜索；Memory Search Plus 自建跨会话全文索引，能跳到任意会话中的具体消息。
- **对比 conversation-landmarks**：那个插件提供当前会话的导航竖线（按用户任务跳转）；Memory Search Plus 是内容检索——先找到*说了什么*，再跳转。
- **对比 Harness 自带会话搜索**：这是基于本地会话存储的社区索引，中文感知分词 + 消息级定位，数据不出本机。

## 开发

```sh
pnpm install
pnpm run check   # typecheck + build（tsdown）+ pack 预检
```

结构：本包是 Cordis Service 插件。`src/index.ts` 为 Host 半边（SQLite FTS5 索引器 + 二段式搜索 API，经 `lib/index.js` 导出 `{ name, inject, apply }`）；`src/client/` 为 Web 半边（侧栏按钮 + 结果面板，产物 `lib/client.js` 以 `window.__ModuleLoader__.load(...)` 包装）。

**宿主 API 契约**（模块接口 `tokenize`、`extractSessionEventText`、`anchorKeyFor`、`SearchIndex`、`computeSpans`/`buildSnippet`、RPC 返回形状与降级保证）以可执行验收契约的形式记录在 [tests/README.md](tests/README.md)（见其「QA 测试契约」一节）。单元测试位于 `tests/`；可复现基准脚本为 `scripts/bench.mjs`（`--impl lib/index.js` 测真实实现）。

## 隐私

一切都在本地：会话事件从本地 DSH 存储读取、写入有界 SQLite 派生索引（默认在 `DSH_HOME` 下，也可在设置页或 `DSH_MEMORY_SEARCH_DB` 指定路径）；插件不发起网络调用、无分析、无遥测、不使用外部 CDN 资源。SQLite 与 FTS 删除采用安全清理模式，损坏索引备份最多保留最近一代。

## 状态

**v1.0.0。** 社区项目，非 DeepSeek 官方发布。当前兼容目标：DeepSeek Harness `0.1.1-rc.2`。

## 反馈

Bug 与功能建议请提交 [Issues](https://github.com/the-thinker0/dsh-memory-search-plus/issues)，提交前请先搜索是否已有相同问题。

## 许可证

[MIT](LICENSE)