DSH plugin 会话查询 API 怎么用：有界精确读取、关系追踪、语义筛选与全文检索

DSH plugin 的会话查询分两个面：一面是精确读取与关系追踪，与后端无关；另一面是全文检索，由提供方实现索引生命周期。 两面的共同前提是「live 优先」——同一 id 既在内存又在磁盘时，数据取自 live 源，记录上分别用 live 与 persisted 标注可用性。日常最容易踩的是过滤器的组合语义：数组之间是 AND，单子句多值是 OR，范围含两端；而文本过滤是对语义文本做字面量扫描，不是可执行 FTS 语法。

把这两条记住，sessionQuery 的多数误用都能避免。

DSH plugin 会话查询 API 的两个面：精确读取与全文检索

一句话结论：精确读取、过滤与追踪走同一套抽象服务；全文索引由提供方负责，换后端不改变查询词汇。

1. 与后端无关的部分：有界读取、过滤器、事件追踪、谱系、标题观测都是具体行为。
2. 与后端相关的部分：全文观测、对账、排序、游标代际与查询执行。
3. 单一服务入口：都挂在 ctx.sessionQuery 上，不需要另找服务。
4. 选型：要「某条事件的原文与上下文」用精确读取；要「哪些会话提到过某个词」用全文搜索。
5. 判据：需要稳定顺序与精确 seq 时走精确读取，需要相关性排序时走搜索。

DSH plugin 的逻辑记录与 live 优先：两种快照

一句话结论：SessionRecord 给可用性，两种 Snapshot 给一次性观测——它们都不是持续订阅。

1. 列表是全语料库：listSessions() 按最新在前返回确定顺序。
2. 观测是一次性的：快照是可克隆的观测结果，不是订阅；要更新就重新读。
3. 表面分类：SessionEventRecord.surface 取 current、shadowed、log-only，用于区分当前上下文、被替换上下文与仅日志。
4. 标题观测同规则：批量读取按请求 id 顺序返回，单个失败只影响该 id，取消则整体拒绝。
5. 别把 persisted 当 live：只持久化的会话需要经冷读路径，语义与活跃会话不同。

DSH plugin 的过滤器：AND、OR 与字面量文本扫描

一句话结论：数组内 AND、子句内 OR、范围含两端；文本是字面量扫描，不是可执行查询语法。

// 会话语义：cwd 命中其一，且创建时间在范围内
const sessions = await ctx.sessionQuery.filterSessions([
  { kind: 'cwd', values: ['/work/a', '/work/b'] },
  { kind: 'created-at', from, to },
])

1. 会话过滤：id、cwd、created-at、parent、availability。
2. 事件过滤：seq、time、type、surface、text。
3. 文本规则：按字面量处理、Unicode 不区分大小写、允许空白灵活匹配。
4. 语义文本范围：消息、工具调用与结果、待办事项、失败与状态详情会进入；推理块、被阻止的提示词、结构事件与流分片不进入。
5. 排序：filterEvents 按 seq 升序返回匹配文档。

DSH plugin 的全文搜索：分组命中、会话内命中与游标

一句话结论：跨会话按最强匹配事件分组，会话内按事件返回；游标与规范化请求绑定，不能跨查询复用。

1. 跨会话：searchSessions({ query, sessionFilters, eventFilters, limit, cursor })，每组带 bestMatch。
2. 会话内：searchEvents({ sessionId, query, filters, limit, cursor })，即使零命中也会返回目标 header。
3. 查询即数据：query 被当作数据解释，绝不是可执行 FTS 语法。
4. 游标规则：不透明游标绑定规范化查询、元数据过滤器与上限；改任何一项都要从头搜。
5. 提供方过滤器不含文本扫描：元数据过滤在排序前应用，文本匹配由索引负责。
6. 分页：items + 可选 nextCursor，最后一页没有游标。

DSH plugin 的有界读取、事件关系与谱系

一句话结论：读取给原始窗口，追踪给替换链与引用关系，谱系给祖先与后代树。

1. 有界读取：SessionEventReadRequest 指定目标 seq 与 before/after 数量，返回带 startSeq/endSeq 的窗口；结果携带 header 而非可用性标志。
2. 替换关系：replacedBy 是直接替换者，replacementChain 追到最终替换；replacedEventSeqs 是本事件替换掉的位置节点。
3. 引用关系：sourceEventSeqs 是它引用的更早事件，derivedEventSeqs 是之后引用它的事件。
4. 谱系：ancestors 由近及远，descendants 是递归森林；complete: false 时给 unresolvedParentId，不要当成完整根。
5. 错误分类：EVENT_NOT_FOUND、INVALID_CURSOR、STALE_CURSOR、SEARCH_DISABLED、INDEX_FAILED、SOURCE_CONFLICT 等是稳定 code，按 code 分支而不是匹配文案。

DSH plugin 排查注意事项

一句话结论：查询问题先分「查不到」「查得慢」「结果顺序怪」三类，分别对应过滤语义、索引与排序契约。

1. 查不到 → 检查 AND/OR 语义与文本是否被当成语法；换关键词再试。
2. 会话内搜索零命中 → 正常返回空 items，但 header 仍在，别据此判断会话不存在。
3. 翻页报游标失效 → 查询或上限变了，必须重新搜。
4. 顺序与预期不符 → 搜索按相关性，精确读取才按 seq 升序。
5. 谱系不完整 → 看 complete 与 unresolvedParentId，不要自行补根。
6. 修复状态如实：本文的记录类型、过滤语义、搜索请求与错误码均取自官方「会话查询」页面；接口签名以该页 Cordis API 与你所用版本为准。

来源：会话查询、session-query 包、会话持久化。