← 返回信息流
GitHub 热榜GitHub Trending · 日·3 天前

fff: 面向 AI Agent 与 Neovim 的最快最准文件搜索工具

原标题：dmtrKovalenko/fff
Rust★ 7,079 stars+121 今日

速览

fff 是一个用 Rust 编写的高性能文件搜索工具包，专为 AI Agent 和 Neovim 等场景优化，支持 Rust、C 和 NodeJS 集成。它通过极低的延迟和高准确率，解决复杂项目结构中快速定位文件的痛点，显著提升开发者和智能体的工作效率。

AI 深度解读

这是什么

fff 是一个由 Rust 编写的高性能文件搜索工具包，旨在为人类开发者和 AI 智能体（AI Agents）提供极速、准确的文件检索能力。该项目由 dmtrKovalenko 维护，在 GitHub 上获得了极高的关注度（★7079+）。

最初，fff 作为 Neovim 插件 fff.nvim 起步，因其出色的性能受到社区喜爱。随后开发者发现，许多 AI 辅助编程工具（如 Cursor、Claude Code 等）和代码编辑器同样需要一种高效的、可作为库调用的文件搜索后端。因此，fff 演变为一个通用的底层搜索基础设施，提供内存中的轻量级内容索引、背景文件监听以及基于 Frecency（频率+时间衰减）的排序算法。

解决的问题

传统命令行搜索工具（如 ripgrep、grep）或简单的模糊搜索插件在处理“长期运行进程中的多次搜索”场景时存在显著瓶颈：

  1. 重复搜索开销大：每次搜索都重新扫描文件系统或从头开始索引，导致 CPU 和 I/O 浪费。
  2. 上下文窗口污染：AI 助手在搜索文件时，往往需要返回大量不相关的匹配结果，消耗宝贵的 Token 并干扰智能体的判断。
  3. 缺乏智能排序：传统工具通常只按文件名或匹配度排序，无法反映用户“最近常用”或“最近修改”的文件，导致开发者需要手动筛选。
  4. AI 集成困难：现有的搜索工具多为 CLI 设计，缺乏针对 MCP（Model Context Protocol）或特定 AI 框架优化的结构化输出接口。

fff 通过构建常驻内存的索引和智能排序机制，解决了上述效率与上下文管理问题。

核心功能

fff 提供了一套完整的搜索生态，涵盖 CLI、AI 集成、编辑器插件及 API 调用：

1. 智能索引与排序

  • Frecency 记忆机制：基于文件被访问的频率和时间衰减算法，自动对文件进行排名。你经常打开的文件在搜索结果中会优先显示。
  • Git 感知注解：自动识别文件的 Git 状态（已修改、未跟踪、已暂存），帮助智能体或用户优先关注当前正在活跃变更的文件。
  • 定义优先提示：在 Rust 后端对代码定义行进行分类，减少提示词中的正则表达式开销。

2. 多模式搜索接口

  • fff-grep：内容搜索。支持路径过滤、排除规则、大小写智能匹配（Smart-case）。若精确匹配为零，自动降级为模糊搜索（Fuzzy）。
  • fff-find：路径与文件名搜索。匹配仓库相对路径而非仅文件名，具备防噪点机制，避免模糊匹配产生大量无关结果。
  • fff-multi-grep：支持多模式组合搜索。

3. AI 智能体集成 (MCP & Pi)

  • MCP Server：提供标准化的 MCP 服务器，兼容 Claude Code、Codex、OpenCode、Cursor、Cline 等支持 MCP 的客户端。连接后，智能体可调用 fff-grep、fff-find 等工具，减少 Grep 往返次数，降低 Token 消耗。
  • Pi Extension：为 pi 编辑器提供原生工具替换，并通过 Frecency 索引驱动 @ 提及自动补全。

4. Neovim 插件 (fff.nvim)

  • 快速键位映射：提供 ff (Find files), fg (Live grep), fz (Live fuzzy grep), fc (Search current word) 等便捷操作。
  • 程序化 API：暴露 file_search 和 content_search 函数，支持分页、线程控制、自定义 CWD 及等待超时，便于其他插件集成。
  • 配置灵活：支持调整布局、线程数、最大结果数、调试模式等。

亮点 / 与同类相比

| 特性 | fff | 传统 CLI (ripgrep/fzf) | 其他 AI 搜索插件 | | :--- | :--- | :--- | :--- | | 性能模型 | 常驻内存索引，首次扫描后后续搜索极快 | 每次执行需重新扫描或依赖外部索引 | 通常依赖实时扫描，速度较慢 | | 排序算法 | Frecency (频率+时间)，反映用户习惯 | 默认按文件名或匹配行排序 | 简单的相关性排序 | | AI 友好度 | 原生支持 MCP，结构化输出，减少 Token 浪费 | 需额外封装，输出非结构化文本 | 部分支持，但缺乏底层索引优化 | | Git 集成 | 深度集成，标注文件状态，辅助决策 | 需配合 git 命令或插件 | 通常仅支持基本状态显示 | | 容错能力 | 自动降级：精确匹配失败自动转为模糊搜索 | 需手动切换模式 | 较少见 | | 适用场景 | 长期运行的 IDE、AI 代理、高频搜索场景 | 一次性查询、脚本处理 | 特定编辑器内的简单搜索 |

关键优势总结：

  • 速度：在 Long-running process（长期运行进程）中，只要搜索次数超过一次，fff 的速度显著优于 ripgrep + fzf 的组合。
  • 上下文效率：通过 fff-find 的弱匹配检测器和 fff-grep 的自动模糊回退，大幅减少发送给 AI 的无关噪声。
  • 跨平台与生态：支持 Linux/macOS/Windows，并提供 Shell 安装脚本、MCP 服务器、Neovim 插件及 Node.js/Python 集成。

适合谁用 / 上手

适合人群

  1. AI 辅助编程用户：使用 Cursor、Claude Code、Cline 等工具，希望减少 AI 搜索文件的延迟和 Token 消耗，提高回答准确性的开发者。
  2. Neovim 重度用户：需要极速文件导航和内容搜索，且希望搜索结果能反映个人使用习惯的 Vim 用户。
  3. AI 应用开发者：需要为自定义 AI Agent 或 MCP 客户端集成高性能文件搜索后端的技术人员。
  4. 大型代码库维护者：面对包含数万甚至数十万文件的项目（如 Linux 内核），需要快速定位文件和代码片段的工程师。

上手指南

1. 安装 MCP Server (用于 AI 客户端)

对于 Linux/macOS 用户，可通过一键脚本安装：

curl -L https://dmtrkovalenko.dev/install-fff-mcp.sh | bash

Windows (PowerShell) 用户：

irm https://raw.githubusercontent.com/dmtrKovalenko/fff.nvim/main/install-mcp.ps1 | iex

安装后，脚本会输出客户端配置指令。在 AI 客户端中启用 fff 工具后，即可在对话中直接调用。

2. 安装 Neovim 插件

使用 Lazy.nvim 或其他包管理器安装 fff.nvim：

{
  'dmtrKovalenko/fff.nvim',
  build = function()
    require("fff.download").download_or_build_binary()
  end,
  opts = {
    debug = { enabled = true, show_scores = true },
  },
  lazy = false,
  keys = {
    { "ff", function() require('fff').find_files() end, desc = 'FFFind files' },
    { "fg", function() require('fff').live_grep() end, desc = 'LiFFFe grep' },
    -- 更多键位映射...
  },
}

插件会自动下载预编译的二进制文件或通过 cargo build 编译。

3. 程序化集成

通过 API 进行集成，例如在 Lua 中：

local r = require('fff').file_search('button', {
  mode = 'mixed',
  max_results = 5

相关推荐

查看原文 →github.com