第 3 卷

复制代码

跑 npm run start:ch11:search 看一个对比：脚本前后跑了三次调用，其中两段是 searchSessions()，中间那段「会话内」用的是 searchEvents()。

复制代码 1--- 跨会话全文搜索：搜「crash」 ---

2命中 1 个会话

同一个“落盘”，FTS 就是搜不到。它不是坏了，而是只认整个 token。FTS5 的 unicode61 分词器把连续的字⺟或数字当作一个 token（汉字在 Unicode 里也算字⺟，空格和标点则是

分隔符）：英文里 crash 被空格切开，是独立 token，好搜；中文里“日志怎么落盘”整句连在一起就是一个 token，搜“落盘”这个子串自然对不上。

能不能搜到，只看它是不是恰好一个完整 token：原文如果写成“日志落盘”（中间有空格），“落盘”自己就是 token，反倒能搜；英文搜半个词（cras）同理，都卡在 token 中

间。

原因在索引结构：全文索引按 token 建倒排索引（一个“哪个 token 出现在哪些事件里”的对照表），查一个词就是翻表直接定位，所以快；代价是“落盘”这种半个 token 在表上没有位

跨会话搜索返回一串会话（SessionSearchHit），已按相关性排好序，你要找的通常就是 items[0]；每条还带命中处的那段摘录（snippet），模型可直接拿它做下一步判断。会

话内搜索（searchEvents()）返回的是事件命中项：每条就是“一条事件 + 它自己的摘录”。

结果太多？分页。请求带 limit，返回里的 nextCursor 就是下一页的凭证，拿它再发一次同样的请求即可。

精确过滤：元数据圈定，text 子串兜底

全文搜索按内容找，靠 token 匹配。但很多时候，你要的是按元数据圈定，比如只看某个工作目录（cwd）下的会话、只看 fork 自某个父会话的后代、只看 surface 上还活着的

（current）事件。

这就是过滤器（filter）的活。绝大多数过滤器既能单独用（filterSessions / filterEvents），也能先作为条件传给搜索、圈好范围再搜；唯一的例外是 text 子句，

它只能单独用，不能塞给搜索。上一节留下的那个“搜不到子串”的坑，也在这节填上。

过滤器分两组，差别在作用范围：filterSessions 在整个语料库里筛，返回一串会话记录；filterEvents 得先给一个 sessionId，只在那一个会话里筛，返回一串事件文档。

不管哪一组，一个过滤器的形态都是 { kind, values }：kind 是“按什么维度筛”， values 是候选值列表（几处例外都标在表里）。会话级 filterSessions(filters)，

可用的 kind 与对应 values：

id按会话 id 圈定

事件级 filterEvents(sessionId, filters)，可用的 kind 与对应 values：

kindvalues

组合规则要记牢，只有两条：一个过滤器数组里的各项是 AND（同时满足），单个子句里的 values 是 OR（命中任一即可）。所以下面这个数组读出来是"是 sess-a 或 sess-b，而且

现在还在内存里"——两条规则各用上一次：

复制代码 1[

跑 npm run start:ch11:filter，把这两组过滤器和 text 兜底依次过一遍：

复制代码