Agent 的 grep 缺什么：排序远比匹配重要

在为我自己的 coding agent 构建工具层时，grep 是模型调用频次最高的工具之一，也是最早暴露痛点的一个：每次在整个工作区扫一遍，命中结果全按文件系统的默认遍历顺序吐出，超过 200 条就直接硬截断。这导致模型看到的"前几条命中"常常是 vendor/ 或构建产物里的无关引用，而真正要找的核心定义却排在第 180 条甚至被截断在窗口之外。

带着这个痛点，我深入调研了 pi-fff（一个主打"替换 agent 内置 find/grep"的扩展）及其底层的代码搜索引擎 FFF。

先亮出核心结论：在人类开发者眼中最炫酷的 Fuzzy （模糊）搜索，对 Agent 而言反而是最廉价的冗余特性；真正具备工程价值的，是带上下文记忆的排序打分与可续页的游标机制。 原因非常质朴——调用工具的"搜索者"是 LLM ，而不是容易按错键盘的人类手指。

FFF 是什么

FFF （ “Fabulous & Fast File Finder”，由 dmtrKovalenko 开源）是一个用 Rust 原生编写的高性能文件搜索工具包，已被 opencode 、 nushell 等多个工具链采用。其底层核心引擎发布在 crates.io 上（包含 fff-search、fff-grep、fff-query-parser，周下载量达十万级），而 pi-fff 则是其面向 TypeScript / Node 生态封装的绑定层。

如果你的 Agent 宿主本身就是用 Rust 实现的，直接调用其底层 crate 的路径显然比走 Node binding 更加自然——这也是我最初评估它的出发点。

它提供的六大特性与价值重估

通读 FFF 的设计规范与 crate 接口后，其核心能力与在 Agent 场景下的真实价值对比如下：

值得注意的是：在这张价值评估表里垫底的特性，恰恰是 FFF 面向人类用户时最核心的招牌卖点。

为什么 Fuzzy 匹配对 LLM 毫无意义

Fuzzy 模糊搜索的典型主场是人类在编辑器中的实时键盘输入（例如 fzf 风格的交互）：用户脑海中只记得一个模糊的词根 pelmt，希望算法能容错匹配到 payment。

但 Agent 的调用方是 LLM ，而非人类的手指：

1. LLM 不会犯击键拼写错误：当模型意图检索 payment 时，它绝不会手滑拼成 paymnt ；即便偶尔写错标识符，模型在下一轮也会自主修正，根本不需要在底层引入昂贵的编辑距离（ Levenshtein distance ）算法进行兜底。
2. Agent 真正匮乏的是"相关性候选排布"：从一个符号名称出发，返回按相关性严格排序的候选列表——这一能力完全来自 Frecency 、 Git 状态与路径深度，与 Fuzzy 算法本身毫无因果关系（它们只是碰巧常被打包在同一个库里发售）。
3. 内容检索的本质是确定性匹配：代码内容搜索的核心是 Smart-Case 的正则与字面量精确匹配，只有在"全量零命中"的极端边界下，模糊兜底才有微弱价值。

换言之， Fuzzy 对 Agent 而言纯属附属赠品，为其单独引入一套重型计算引擎在架构上得不偿失。

真正值得借鉴的机制一：多维相关性排序

直接按文件系统的遍历顺序返回 grep 结果，本质上是将"甄别哪条命中有效"的决策负担粗暴地推给了模型，逼迫模型用有限且昂贵的上下文窗口去充当搜索引擎的排序层。

通过引入三层轻量级权重信号，即可解决绝大多数排序劣化问题：

1. 语法定义优先（ Definition-first ）

当命中行的内容呈现出声明与定义特征（如以 fn、class、def、const、type 等关键字开头）时赋予最高加权。在 Agent 的实际场景中，模型检索某个符号， 90% 的动机是探查"它在哪里被定义"，而非"它在何处被重复引用了数百次"。

2. 新近修改优先（ Recency）

根据文件的 mtime（修改时间）计算新近度加分。这是感知"当前活跃文件"成本极低的启发式代理——当前正在编辑或排查的模块，其 mtime 必然是新鲜的。

3. 跨会话频次衰减（ Frecency）

维护一份跨会话的访问热度账本：文件每被读取一次或被 grep 命中一次便累积分数，并随时间呈半衰期平滑衰减。

经典的半衰期衰减公式即可满足需求：

只需在配置目录下持久化为一个轻量 JSON 即可，无需引入 LMDB 等重量级嵌入式数据库。它带来的直观收益是：“开发者最近几天一直在聚焦的业务模块"会自动在搜索结果中前置浮现。

综合打分实现

三者组合后的打分函数非常干脆：

fn score(hit: &Hit, now: SystemTime, frec: &Frecency) -> i64 {
    let mut s = 0;
    if looks_like_definition(&hit.line) { s += 300; }  // fn / class / def / const
    s += recency_bonus(hit.mtime, now);                // 0..200, age 平滑衰减
    s += frec.score(&hit.path);                        // 跨会话累积热度
    s
}

这三个信号全部基于已有命中结果的外围元数据计算，完全不需要改造底层搜索引擎内核，零新增外部依赖。

真正值得借鉴的机制二：全序确定的 Cursor 游标分页

硬截断机制的致命缺陷不仅在于"丢弃了尾部结果”，更在于它在信息论层面上对模型制造了一个盲盒。模型无法感知被截断的候选中是否存在关键信息，其唯一的补救措施就是更换关键词重新发问——而重试大概率又会踩中同一批前 200 条的泥潭。

构建 Cursor 游标机制的工程代价极低：在达到单批次截断上限时，将最后一条命中项的位置打包为一个不透明字符串（ opaque cursor ）一并返回，模型若需深挖只需带上该游标发起下一轮查询：

{
  "matches": [ "/* ...精选出的前 200 条... */" ],
  "cursor": "src/payment/refund.rs:412"
}

排序与游标的张力（ Jitter 防范）

在工程实现上存在一个极易踩雷的边界：相关性打分与断点续查之间存在天然张力。 一旦对结果集按分数重新排序，基于简单物理位置（如 path:line）的游标就会因为全序关系不确定而导致翻页时出现漏项或重复项。

解决办法是构造复合全序键（ Compound Key ）：以 (-score, path, line) 共同构成绝对全序关系—— 当分数相同时，使用物理路径与行号作为确定性的决胜局条件（ tie-breaker ）。续页查询即转化为 “严格跳过所有复合键 $\le \text{cursor}$ 的匹配条目”。只要会话内部打分函数保持稳定，分页逻辑便具备确定性数学保证。

( 注： Frecency 热度在长会话中可能会动态微增。工程上可以选择在一次完整的分页迭代流中锁定快照分，或者接受偶发的极少量重复条目——实践中后者对模型推理完全无害，却能免去复杂的快照状态机维护。)

算清工程账后主动放弃的两项设计

1. 全局索引与文件变更监听（ Index + Watcher ）

这是 FFF 在"长驻桌面 GUI 进程、高频毫秒级模糊查询"场景下的杀手锏，但在 Agent CLI 架构中并不成立：

• 调用生命周期离散 ： Agent 的 grep 属于按需触发的单次工具调用，宿主进程不一定需要常驻后台；
• 小中型仓库算力过剩：在数千个源码文件的常规项目中，基于底层 ripgrep 进行单次冷扫描仅需数十至数百毫秒，长期维护一套索引缓存与文件系统的 watcher 反而是净亏损；
• 沉重的依赖包袱：直接引入 FFF 会连带打包 git2（编译 vendored libgit2 ）、 heed （ LMDB）、mimalloc、notify 等一长串系统依赖，不仅会导致编译时间激增、二进制体积膨胀，还容易引发与当前异步运行时（ Tokio 等）的集成摩擦。

何时值得启用？ 唯有当工作区规模庞大到"单次冷扫带来明显卡顿"（例如数十万文件的超大型单体代码仓库），或者检索成为高吞吐的核心管道时才需重新评估。

2. 宿主级深度 Git 状态感知

为 modified / staged / untracked 文件额外提权在直觉上非常契合场景，但深入核算成本后同样被果断放弃：

1. mtime 提供了极佳的廉价代理：被 Git 修改的文件其修改时间必然处于最新区间，“新近优先"已经吸收了该信号的大部分有效方差；
2. 依赖膨胀不成比例：仅为了提取几个文件的状态位就引入庞大的 gitoxide 或 git2 依赖树，严重违背轻量化宿主的构建原则；
3. 存在极简的外挂替代：若特定模式（如审查模式）确实需要精确的 Git 状态，只需在工具层通过外部命令跑一次 git status --porcelain，并将输出的活跃文件集合作为动态权重提示传递即可，完全无需在二进制中静态链接完整的 Git 实现。

这一取舍贯彻了一条核心工程准则：优先获取 80% 的主要收益，绝不为了剩余边际价值背负沉重的依赖债务。

落地效果与总结

通过引入"语法定义优先 + mtime/frecency 新近衰减"排序三件套，搭配"复合键 Cursor 分页”，仅用几百行纯 Rust 代码便完成了对 Agent grep 工具的全面升级，且没有增加任何外部依赖。

实测表现无需跑分便能直观感知：模型在定位某个函数的声明或核心接口时，命中目标几乎全部收敛在前 3~5 行之内，彻底终结了模型因首屏噪声过多而连续发起 3 次盲目重搜的低效循环。

这次改造留下的一句核心认知是：

Agent 在搜索时需要的从来不是"找到所有文件"，而是"把对的文件排在最前面"。

文本层面的匹配早已是成熟领域（ ripgrep 已经做到了极致）。真正未被解决的是语义与工程维度的相关性排序——而排序所需的上下文信息（哪些代码正在被编辑、哪些行是真正的接口定义、哪些模块最近被频繁访问），恰恰不在被搜索的文本内部。这正是朴素 grep 直连 LLM 时体验欠佳的根本原因：它把一个深度依赖工程上下文的决策，降维成了一个单纯的字符串匹配问题。

暂缓演进清单

• 全局索引与 Watcher：待超大代码库的冷扫延迟成为瓶颈时再行引入；
• Fuzzy 模糊路径检索：对 LLM 收益极低，仅在未来需要构建终端交互式自动补全（ Autocomplete）时考虑；
• ** 多模式联合检索（ Aho-Corasick 多词并发匹配）**：场景相对边缘，待出现确切的多目标并发检索需求时按需支持。