dsh-title-index

Readme

# dsh-title-index

**EN** — A drop-in accelerator for the DeepSeek Harness web GUI's session title lookups. It replaces the stock `session-query-sqlite` row with a subclass that serves `readTitleSnapshots` from a disk index keyed by `(sessionId, mtimeMs, size)`, instead of decompressing and replaying every session log on each `@`-mention keystroke. Everything else the stock engine does is kept untouched. On a real 114-session corpus: top-50 `@` menu titles went from **~9.7 s to ~0.3 s**, with field-identical results.

---

为 dsh Web 端会话标题读取加磁盘索引的插件。

## 问题

Web 输入框的 `@` 会话候选(`dsh-session-reference`)为给出每个候选的"最新标题",会对每个持久化会话**完整解压并逐行解析** `session.jsonl.zstd` 来折叠标题(`sessionQuery.readTitleSnapshots`)。会话一多,每次按键都要扫几十上百份日志;而解析结果 LRU 只缓存 5 个,重复查询同样慢。

## 方案

本插件通过 `cordis.patch.yml` 禁用官方 `session-query-sqlite` 行并插入同服务的新行(`session-query-title-index`,注入名 `dsh-title-index`),继承官方 `SqliteSessionQueryEngine`,只 override `readTitleSnapshots`:

- 磁盘索引(默认 `<DSH_HOME>/title-index.json`)以 `(sessionId, mtimeMs, size)` 为失效键;
- 命中 → 直接返回缓存的标题快照(毫秒级);
- 未命中(新会话/日志有追加)→ 走官方折叠,并把结果连同折叠后的文件 stat 写回索引;
- 活动中的(live)会话、官方读取失败、索引损坏,全部原样回退官方路径,行为不会劣化。

其余方法(listSessions、readSurface、搜索、lineage、授权语义)全部保持官方实现。标题被标题生成插件重写时日志文件 mtime 变化,缓存自动失效。

> **为什么是"禁用 + 插入"而不是改行名?** dsh 的补丁机制(`applyEntryPatches`)允许修改已有行的 `config`/`disabled`,但不允许修改 `name`;而两个引擎类发布的服务名都固定为 `sessionQuery`,消费者按服务名注入,因此换行对它们完全透明。

## 实测(114 个会话,约 60MB zstd 日志)

| 场景 | 官方引擎 | 本插件 |
|---|---|---|
| `@` 菜单 top-50 标题读取 | ~9.7 s(全量折叠) | **0.30 s** |
| 全量 114 会话标题读取 | ~8.5–9.7 s | **0.34 s** |
| 单会话 | ~0.5 s | **~0 s** |
| 结果与官方逐字段等价 | — | 109 对全等,0 差异 |

冷启动一次约 8–9 s(仅发生在索引缺失或格式升级后);正在写入的会话每次追加都会失效重折叠,追加间歇由索引承接。

## 安装(web profile)

1. 在 profile 的 `package.json` 中添加依赖与 bundle(`dsh.profile.bundles` 中**必须排在 `@deepseek-ai/dsh-web-app` 之后**,保证补丁在官方行定义之后生效):

   ```jsonc
   {
     "dsh": {
       "profile": {
         "bundles": [
           "@deepseek-ai/dsh-base",
           "@deepseek-ai/dsh-web-app",
           "dsh-title-index" // ← 排在 web-app 之后
         ]
       }
     },
     "dependencies": {
       "dsh-title-index": "github:gtaifu/dsh-title-index"
     }
   }
   ```

2. 重新安装 profile 依赖:

   ```powershell
   dsh plugin --profile web install
   ```

3. 重启 dsh web。首次冷启动会全量折叠一次以填充索引;可用下面的预热命令提前完成。

## 配置(接管行的 config)

| Key | 默认值 | 说明 |
|---|---|---|
| `path` / `openAt` / 其余官方键 | 官方默认 | 原样转发给官方引擎;web 部署沿用 `:memory:` + `never` |
| `root` | `""` | 持久化会话根目录;空值时插件完全惰性(等价官方引擎) |
| `indexPath` | `<root>/../title-index.json` | 索引文件位置 |

补丁内置的默认配置:

```yaml
- insert:
    - id: session-query-title-index
      name: 'dsh-title-index'
      config:
        path: ':memory:'
        openAt: never
        root: !!js dshHomePath('sessions')
```

## 基准与预热

```powershell
node <profile>/node_modules/dsh-title-index/lib/bench.mjs
# 对照官方引擎计时 + 逐字段等价校验(索引写入临时文件,结束即删)

$env:DSH_TITLE_INDEX_PROD = "1"; node <profile>/node_modules/dsh-title-index/lib/bench.mjs
# 预热生产索引文件(DSH_HOME\title-index.json),重启后第一次 @ 即为热查询
```

环境变量:`DSH_TITLE_INDEX_ROOT` 覆盖语料根目录;`DSH_HOME` 缺省回退到 `~/.dsh`。

## 兼容性

- 依赖官方引擎的内部行为:`@deepseek-ai/dsh-session-query-sqlite@^0.1.1-rc.2`、`@deepseek-ai/schemastery@^3.18.1`(peerDependencies,由 dsh 安装目录解析,无需另装);
- Node ≥ 22(与 dsh 自身要求一致);
- 索引文件带格式版本号(`INDEX_FORMAT_VERSION`),未来条目结构变化时会自动丢弃重建。

## License

[MIT](./LICENSE)