会话全文搜索 huangjua/dsh-session-index

🔍 dsh-session-index

DSH 的会话全文搜索与书签引擎 CJK 子串搜索 • 基于 Worker 的索引 • 多信号排序 • 稳定消息锚点

功能特性 • 快速开始 • DSH Power Suite • 参考手册 • 简体中文

💡 为什么需要 dsh-session-index？

DSH 把持久化的对话历史存成压缩的 .jsonl.zstd 事件日志。这个插件另外建立元数据索引和全文索引，让你能搜索历史中文短语和代码片段，同时不改动这些日志。

- 🇨🇳 CJK 与拉丁子串搜索：FTS5 trigram 先给出候选，再用完整的原始消息文本校验匹配结果。短词走 LIKE 路径。
- 🚀 基于 Worker 的索引：解析 Worker 流式解压；独立的 SQLite 写入进程和 WAL 读取进程把同步 SQL 挡在宿主事件循环之外。测量数据与资源限制见下文。
- 🎯 多信号相关性排序：融合 fzy 模糊评分、21 天半衰期的时间衰减和工作区亲和度，思路借鉴 Atuin 和 McFly。
- 🔖 稳定的消息书签：新书签使用 (sessionId, anchorId)。重建时，在支持的身份契约范围内保留锚点；锚点缺失或被替换时，返回明确的失败。

🚀 快速开始

安装与部署

包入口是 lib/index.js。DSH 通过 package.json 的 dsh.bundle.patch 和 cordis.patch.yml 把它作为 bundle 安装，由配置档的 dsh.profile.bundles 选择，或走 DSH 的 dsh plugin add 流程。加载前先编译完整的 lib/，包括 Worker 模块。

本检出中的 0.0.3-rc.2 是隔离运行时修复候选版，产物在 release/RUNTIME-20261002/。校验和部署步骤见 RUNTIME_FIX_REPORT.txt 和 DEPLOYMENT_AND_ROLLBACK.txt。生产部署需要单独授权。请在隔离的 E 盘工作区构建；已部署的 G 盘源码比其运行时旧，不得用于构建。候选版根目录的 cordis.patch.yml 是可移植版本，不得替换用户已有的配置。

典型用法

工具调用写法仅为示意；请使用内容搜索返回的确切 session/anchor 对。

session_index_search query="重构 认证中间件" mode="full" session_summary id="session-xxxx" session_index_bookmark action="add" sessionId="session-xxxx" anchorId="a1:..." label="JWT Auth Fix" session_index_bookmark action="list" query="JWT" session_index_search session_id="session-xxxx" anchor_id="a1:..." window=5

session_summary 接收 id，书签添加接收 sessionId 和 anchorId，SCROLL 接收 session_id 和 anchor_id。省略消息锚点会创建会话级书签。仅命中元数据的结果没有消息锚点。

🧩 DSH Power Suite

本插件属于 DSH Agent Power Suite，这套套件包含四个模块化插件，彼此之间没有硬依赖：

flowchart LR
M["🧠 dsh-local-memory(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy(2. Compact code reading)"]
E --> A["🛡️ dsh-evidence(3. Audit receipts)"]
A --> S["🔍 dsh-session-index(4. CJK search & bookmarks)"]
S --> M

style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px

| 插件 | 角色 | 与 Session Index 的协同 |
| 🔍 dsh-session-index | 会话搜索 | 搜索压缩归档，存储书签。 |
| 🧠 dsh-local-memory | 记忆层 | 整理高层记忆；本插件负责检索原始日志。 |
| 🛡️ dsh-evidence | 审计与回执 | 会话搜索帮你定位此前的证据包和审计结论。 |
| ⚡ dsh-context-economy | 上下文经济 | 紧凑的指针输出能减少日志量和索引工作量。 |

📖 深入解析与参考

🛠️ 可用工具（5 个）

| 工具 | 说明 |
| session_index_status | 查看或刷新元数据和 FTS 状态、已解析与已提交的检查点、扫描完整度、worker 健康状况和保留策略。 |
| session_index_list | 按工作区列出会话，支持稳定的游标分页或按相关度排序。 |
| session_index_search | 搜索元数据（mode=meta，默认）或内容（mode=full）；SCROLL 读取精确会话/消息锚点附近的上下文。 |
| session_summary | 返回确定性字段、时间戳、事件计数和工具计数；可选返回缓存的 LLM 一句话摘要。必填参数：id。 |
| session_index_bookmark | 添加、列出、删除书签；add 需要 sessionId，消息书签使用 anchorId。 |

可选的 LLM 摘要由 llmSummaryEnabled 控制（默认 true），只在摘要路径上运行，不可用时回退到确定性输出。设为 false 可关闭服务商调用和摘要缓存访问。

🔎 内容覆盖与过滤 mode=full 会先应用支持的 surface-replacement 规则，再搜索 user/assistant 文本和 tool/call 名称。它排除 system/developer 消息、工具结果正文、工具参数和非文本内容。tool 角色命中标识的是工具名，不是工具输出。没有指定消息角色时，full 搜索也可能包含仅元数据命中；这类命中的 kind=meta 条目没有锚点。

FTS 在每个来源 50,000 条消息 / 64 MiB UTF-8 文本 的收集预算内，保留完整的原始消息文本。分块为 4096 个 UTF-16 代码单元，重叠 128 个单元，并保留代理对边界。候选会聚合回原始消息，对照完整文本验证，并在会话上限之前缩减为每个会话的最佳消息。短词和长于重叠长度的词走原始文本路径。多词搜索要求所有词出现在同一条原始消息中；只有当 FTS 和来源搜索两条路径合起来都没有内容 AND 命中时，full 搜索才放宽为 OR。不同消息不会合并来满足 AND。

原始日志回退覆盖不完整/脏索引和不可用的 FTS，受同一兼容性门控约束。默认上限为 每行 JSONL 4 MiB / 每个来源解压后总计 256 MiB。对于超长行，session_index_search ... maxLineBytes=33554432 会把来源搜索的行预算提高到 32 MiB；可接受值为 4 到 32 MiB 的整数字节，总预算仍为 256 MiB。临时搜索不会重写索引，也不接受未知的必需事件。

| 过滤器 | 实际粒度 |
| workspace | 会话工作区的子串匹配，不区分大小写。 |
| full 模式下的 filter.role | user、assistant、tool 或 any，在计数/截断之前应用。指定角色会排除仅元数据命中。 |
| meta 模式下的 filter.role | tool 近似表示有工具调用的会话；user/assistant 不在消息级别过滤。 |
| filter.sinceMs / filter.untilMs | 包含边界的会话 lastTime 范围，单位为 epoch 毫秒；不是单条消息的时间戳。 |

来源发现上限为 10,000 个会话文件。元数据/来源候选窗口上限为 2,000 个会话；FTS 排名窗口最多 500 个会话候选。Lineage 把相关分支归组，同时保持代表项的实际会话/文件/锚点在一起。在把 total 当作穷尽结果之前，先检查 totalExact、hasMore、truncated 和 coverage。来源失败会在 coverage.diagnostics 中暴露预算和原因（最多 20 条，带截断指示）；覆盖不完整时的空结果不能证明不存在。

🔖 锚点、旧版书签与迁移原始消息/调用 ID 锚点（a1:）使用会话/类型命名空间；受支持的 v0–v4 测试样本验证了跨代身份保持。没有原始 ID 的记录使用基于代/序号/完整内容的回退锚点（a1s:）。该回退锚点在重建同一源表示后仍然有效，但跨格式迁移或替换时不保证有效。

SCROLL 校验 (session_id, anchor_id)，并返回该会话中最多 window 条更早和更晚的原始消息（window=1..20，默认 5）。分块和全局行邻近度都不是导航单位。会话/锚点过期、缺失或有歧义时，响应会明确报错；邻近消息不能替代缺失的锚点。SCROLL 需要可用的 FTS，因此源回退锚点在建立索引前可能一直不可用。

旧版 message_id SCROLL 只读取已有的旧版 SQLite rowid；它绝不把这些 rowid 解释为事件序号，也不把它们当作新锚点行的别名。书签的 messageId 仍可读取，但仅凭一个数字无法证明位置。新消息书签应使用搜索结果中精确的 sessionId/anchorId。

书签是用户数据，存放在 bookmarks.jsonl 中，与可重建的 fts.db 分开；v2 读取器接受 v1。migrateBookmarks 需显式调用，默认 dry-run；search/list 从不迁移记录。转换需要已持久化的稳定锚点和身份证据。无法解析、有歧义、会话缺失和锚点已被替换的记录保留旧字段和诊断信息。生产环境迁移需要备份，并停止或升级所有共享数据目录的写入方。回滚必须保留部署后新增的书签。

🏗️ 架构与恢复

Tools → SessionIndexBuilder (single-flight per root/indexFile)
├─ Head pass: first 10 records → quick metadata index
├─ Full/delta parser workers → original messages in source order
├─ FtsClient → bounded transport → disk spool
│ ├─ SQLite writer: messages/chunks/metadata/checkpoint in one transaction
│ └─ read-only WAL reader: queries within one snapshot
└─ index.json → unique temp file → fsync → validate → rename

解析进度和 FTS 已提交进度彼此独立；SQL 失败不会推进已提交的检查点。失败的事务保留上一个可搜索快照。启动和 watcher 回退会核对指纹和脏检查点；未完成的扫描不确认删除。增量解压会真正从已校验的偏移读取压缩尾部，并做源竞争和帧边界校验。
FTS 包最大 512 KiB，最多 2 个在途，8 MiB 传输/排队生产者预算，最多 2 个活跃源。每个活跃源有独立的 64 MiB 正文预算。这些不是 RSS 限制：文本对象、解析器缓冲区和 SQLite 都会额外占用内存。每个 SQLite 连接有独立子进程，因此原生 SQL 能在有界终止期内取消。读端失败时独立恢复，不影响写端及其事务/检查点。队列过期不会重启健康的通道。

默认截止时间：查询 10 秒，覆盖就绪、恢复、准入和执行，写入 120 秒，进程握手/关闭排空 15 秒，迁移总计 90 秒，迁移锁等待 60 秒、无进展 20 秒。启动过程暴露 booted/opening/migrating/ready/failed 状态和真实批次数。完整完整性检查和 FTS 维护与普通启动分离。长时间写入期间，健康检查返回带时间戳的快照并标记 healthBusy，不会排在事务后面等待。当前健康恢复后，错误和历史恢复计数仍可观测。

公开搜索结果包含实际后端和工具耗时。请求诊断报告队列、SQL、序列化、恢复和传输估算，但不存储查询文本或消息正文。transportMs 是带标签的残差；dispatchMs 包含 SQL，不能与它相加。增量回退诊断保留明确的解析器原因、累计实际字节数、尝试次数和最终检查点一致性；未解决的历史原因保持 unknown。

dataDir 默认 $DSH_HOME/session-index，存放 index.json、fts.db、bookmarks.jsonl 和可选的 llm-summary.jsonl。sessionsRoot/indexFile 可配置。ftsEnabled=false 跳过 SQLite，改用有界源搜索；SCROLL 不可用。保留期默认 90 天（0 表示禁用），只删除派生条目，不删原始日志或书签；FTS 不可用时跳过维护。

🧪 兼容性、验证与测量

锁定的构建/契约目标是 DSH 0.2.0-rc.2、Cordis 4.0.4 和 Schemastery 3.18.4。DSH 对等依赖声明 >=0.1.7-rc.1 <0.3.0；这个安装范围不能证明每个版本都测过。编译使用 Node v24.16.0。运行时修复资格验证使用已安装的 Electron 44 / Node v24.18.1 / SQLite 3.53.1。FTS 需要专用进程里可用的 node:sqlite/FTS5；SQLite 不可用时走可观测的源回退。
读取器支持旧版 session.jsonl.zstd（v0/v1）、session.v2.jsonl.zstd、session.v3.jsonl.zstd 和 session.v4.jsonl.zstd，每个目录只选最高代际。v3 建模 isSeeded/delegationDepth、系统折叠和 startSeq/endSeq 替换。v4 建模提升后的工具结果、直接系统溯源、开发者消息和 workspace/changes；折叠不会让被排除的正文变得可搜索。未知的必需事件仍会卡住闸门。2026-10-01 的历史证据记录了 321 份真实日志（v0=284/v3=14/v4=23）通过头部/完整/搜索解析；这不是当前版本的测试数量。

在隔离检出中直接使用锁定的编译器：

node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit
node scripts/check-dsh-contract.mjs
node node_modules/typescript/bin/tsc -p tsconfig.test.json
node scripts/run-isolated-tests.mjs <new-label> <affected-test-basenames...>

隔离运行器把 DSH_HOME、dataDir/session 夹具和临时目录分配到测试专属路径。从 diff 中挑选测试，并保留失败/重试日志。基准测试与测试分开运行。用锁定的编译器和 runbook 流程编译候选版本，避免依赖重新链接；当 DSH_CHECKOUT 选中完整宿主检出时，scripts/build.sh 可以重新链接依赖。

S5 夹具测量使用 20 个独立进程（基线/候选 × 冷/稳态 × 5）。五次候选稳态运行中观察到的最大事件循环间隙为 31.949 ms，达到夹具 100 ms 的目标；基线稳态最大值为 418.591–1529.072 ms。更完整的 schema 写入更慢（候选 1.366–2.773 s，基线 0.669–1.524 s）。这些宿主/夹具测量不保证固定的 UI 延迟。50,000 条消息的压力夹具中，并发读取器查询保持在 133.792 ms 以下；结束时 RSS 约为 257 MB，不是测得的峰值。另一项 delta 实验在全部 15 次运行中，于 1/16/64 MiB 前缀之后读取/分配了相同的 32 字节尾部。

原始结果、哈希、迁移计数和最终检查见 HANDOFF_S3_S5.txt、BENCHMARK_RESULTS/S3-S5_PERFORMANCE.json、TEST_RESULTS/S3-S5_VALIDATION.json、MIGRATION_DRY_RUN.json 和 RELEASE_READINESS.txt。合成迁移计数不能确定有多少生产书签可恢复。

🙏 致谢与先前工作

- OpenAI Codex（commit 9ded177）：非阻塞 v2 架构、片段预览和 HEAD_RECORD_LIMIT。
- jhawthorn/fzy：fzyScore 的 TypeScript 翻译和匹配加分矩阵。
- Atuin & McFly：命中层级和指数时间衰减评分。
- fzf：确定性平局排序。

属于 DSH Agent Power Suite 的一部分。采用 BSD-3-Clause 协议授权。