目录

FFF.nvim:让 AI 和 Neovim 拥有极速文件搜索与记忆能力

FFF.nvim:让 AI 和 Neovim 拥有极速文件搜索与记忆能力

学习目标

通过本文,你将全面掌握以下核心能力:

  • 深入理解 FFF.nvim 的项目定位与设计理念
  • 掌握在 AI Agent(Claude Code、Codex、OpenCode)中集成 FFF MCP 服务的方法
  • 学会在 Neovim 中安装、配置和使用 FFF.nvim
  • 理解 Frecency(频率+时效)排序算法的原理
  • 掌握多种搜索模式(Plain/Regex/Fuzzy)的使用场景
  • 熟练运用 Git 状态高亮、多选、Quickfix 集成等高级功能
  • 学会故障排除和日志查看方法

1. 项目概述

1.1 是什么

FFF.nvim(Freakin Fast Fuzzy file finder)是一个极速文件搜索工具,同时为 AI Agent 和 Neovim 提供内置记忆的文件搜索能力。

它的核心理念:Just for file search, but we do the file search really fff well——只做文件搜索,但要把这件事做到极致。

1.2 核心定位

FFF.nvim 有两个主要使用场景:

使用场景说明
AI Agent (MCP)作为 MCP 服务器,为 Claude Code、Codex 等 AI Agent 提供文件搜索能力,大幅减少 Token 消耗
Neovim 用户作为 Neovim 插件,提供极速、抗拼写错误、带有记忆的文件搜索体验

1.3 核心数据

指标数值
GitHub Stars248
LicenseMIT
作者dmtrKovalenko
Neovim 版本要求≥ 0.10.0

1.4 技术栈

组件技术
Neovim 插件Lua
核心二进制Rust
搜索算法Smith-Waterman 评分
存储SQLite(frecency/history)

2. 核心特性详解

2.1 AI Agent MCP 集成

FFF.nvim 可以作为 MCP 服务器连接到 AI Agent,带来以下优势:

优势说明
减少 Token内置记忆让 AI 更精准地找到代码,减少往返次数
更快搜索Rust 实现的高速搜索,比内置工具快
减少无用文件读取智能排序让 AI 优先看到最相关的内容

安装命令

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

安装脚本会输出连接说明,指导你如何配置到 Claude Code、Codex、OpenCode 等 AI Agent。

在 CLAUDE.md 中添加

# CLAUDE.md

For any file search or grep in the current git indexed directory use fff tools

2.2 Neovim 文件搜索

对于 Neovim 用户,FFF.nvim 提供:

功能说明
极速模糊搜索基于 Rust,支持百万级文件
抗拼写错误Smith-Waterman 算法容忍 typos
Frecency 排序结合频率和时效的智能排序
Git 状态集成显示文件修改状态

快捷键映射

快捷键功能
ff查找文件
fg实时 Grep 搜索
fz模糊 Grep 搜索
fc搜索当前光标单词

2.3 Frecency 排序算法

Frecency 是一种结合**频率(Frequency)和时效(Recency)**的排序算法:

因素权重说明
Frecency最近打开且频繁打开的文件优先
Git 状态未跟踪、已修改的文件会提升排名
文件大小小文件略微优先
定义匹配与搜索词匹配的函数/类名优先

2.4 三种搜索模式

FFF.nvim 支持三种搜索模式,可通过 <S-Tab> 切换:

模式说明适用场景
Plain纯文本匹配,特殊字符无含义搜索代码中的正则元字符
Regex正则表达式需要精确模式匹配
FuzzySmith-Waterman 模糊匹配容忍拼写错误,如 mtxlk 可匹配 mutex_lock

2.5 跨模式建议

FFF.nvim 的智能之处在于跨模式建议

场景自动行为
文件搜索无结果自动显示 Grep 搜索建议
Grep 搜索无结果自动显示文件名建议

这避免了用户在两种模式之间手动切换。


3. AI Agent MCP 集成详解

3.1 为什么 AI Agent 需要 FFF

传统 AI Agent 的文件搜索存在以下问题:

问题影响
Token 浪费需要多次往返才能找到正确文件
上下文膨胀读取大量无关文件浪费 Token
搜索不精准不了解项目结构,优先显示无关文件

FFF 通过内置记忆解决这些问题:

# 安装后,AI 会自动学习
# 下次搜索 "auth" 时,会优先显示:
# - 最近频繁打开的 auth.py
# - 包含 "auth" 的重要文件
# - 忽略 test/auth_fixture.py(低频)

3.2 连接到的 AI Agent

AI Agent支持状态配置方式
Claude Code✅ 完全支持安装脚本自动配置
Codex✅ 完全支持安装脚本自动配置
OpenCode✅ 完全支持安装脚本自动配置
其他 MCP 客户端✅ 通用 MCP手动配置

3.3 使用示例

安装完成后,只需在对话中告诉 AI:

请使用 fff 工具搜索 "auth" 相关的文件

AI 会自动调用 FFF MCP 服务,返回精准的搜索结果。

3.4 Token 节省效果

根据项目测试,FFF 相比内置工具可以节省:

场景Token 节省
单次文件搜索~30%
多轮搜索任务~50%
大型代码库(100k+ 文件)~70%

4. Neovim 安装与配置

4.1 前置要求

  • Neovim ≥ 0.10.0
  • Git(用于版本控制集成)
  • Rustup(用于从源码编译,非必须)

4.2 使用 lazy.nvim 安装

{
  'dmtrKovalenko/fff.nvim',
  build = function()
    -- 下载预编译二进制,或使用现有 rustup 工具链编译
    require("fff.download").download_or_build_binary()
  end,
  -- 如果使用 NixOS:
  -- build = "nix run .#release",
  opts = {
    -- (可选) 调试配置
    debug = {
      enabled = true,
      show_scores = true,  -- 显示评分,帮助优化
    },
  },
  -- 无需 lazy-load,FFF 会自动延迟加载
  lazy = false,
  keys = {
    { "ff", function() require('fff').find_files() end, desc = 'FF: Find files' },
    { "fg", function() require('fff').live_grep() end, desc = 'FF: Live grep' },
    { "fz", function() require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } }) end, desc = 'FF: Fuzzy grep' },
    { "fc", function() require('fff').live_grep({ query = vim.fn.expand("<cword>") }) end, desc = 'FF: Search current word' },
  }
}

4.3 使用 vim.pack 安装

-- 添加到 init.lua
vim.pack.add({
  'https://github.com/dmtrKovalenko/fff.nvim'
})

-- 配置自动构建
vim.api.nvim_create_autocmd('PackChanged', {
  callback = function(event)
    if event.data.updated then
      require('fff.download').download_or_build_binary()
    end
  end,
})

-- 基础配置
vim.g.fff = {
  lazy_sync = true,  -- 仅在打开 picker 时同步文件
  debug = {
    enabled = true,
    show_scores = true,
  },
}

-- 快捷键
vim.keymap.set('n', 'ff', function() require('fff').find_files() end, { desc = 'FF: Find files' })

4.4 完整配置示例

require('fff').setup({
  -- 基础配置
  base_path = vim.fn.getcwd(),
  prompt = '🪿 ',
  title = 'FFFiles',
  max_results = 100,
  max_threads = 4,
  lazy_sync = true,

  -- 布局配置
  layout = {
    height = 0.8,
    width = 0.8,
    prompt_position = 'bottom',
    preview_position = 'right',
    preview_size = 0.5,
    flex = {
      size = 130,
      wrap = 'top',
    },
    show_scrollbar = true,
    path_shorten_strategy = 'middle_number',
  },

  -- 预览窗口配置
  preview = {
    enabled = true,
    max_size = 10 * 1024 * 1024,  -- 10MB
    chunk_size = 8192,
    line_numbers = false,
    cursorlineopt = 'both',
    wrap_lines = false,
    filetypes = {
      svg = { wrap_lines = true },
      markdown = { wrap_lines = true },
      text = { wrap_lines = true },
    },
  },

  -- Frecency 配置(文件打开频率+时效)
  frecency = {
    enabled = true,
    db_path = vim.fn.stdpath('cache') .. '/fff_nvim',
  },

  -- 搜索历史配置
  history = {
    enabled = true,
    db_path = vim.fn.stdpath('data') .. '/fff_queries',
    min_combo_count = 3,
    combo_boost_score_multiplier = 100,
  },

  -- Git 集成
  git = {
    status_text_color = false,
  },

  -- Grep 配置
  grep = {
    max_file_size = 10 * 1024 * 1024,
    max_matches_per_file = 100,
    smart_case = true,
    time_budget_ms = 150,
    modes = { 'plain', 'regex', 'fuzzy' },
  },

  -- 调试配置
  debug = {
    enabled = false,
    show_scores = false,
  },
})

5. 高级功能详解

5.1 约束条件搜索

FFF 支持通过约束条件精细化搜索结果:

约束示例说明
Git 状态git:modified只显示已修改文件
目录限制test/显示任意嵌套的 test/ 目录
排除!something排除匹配项
Glob./**/*.{rs,lua}任意有效 glob 表达式

组合使用示例

git:modified src/**/*.rs !src/**/mod.rs user controller

这会查找:所有已修改的 Rust 文件,排除 mod.rs,优先显示包含 user 和 controller 的结果。

5.2 多选与 Quickfix 集成

快捷键功能
<Tab>切换当前文件选中状态
<C-q>发送选中文件到 Quickfix 并关闭

当选中文件时,sign column 会显示 标记。

5.3 Git 状态高亮

FFF 支持两种 Git 状态可视化方式:

Sign Column 指示器(默认启用)

状态高亮组
已暂存FFFGitSignStaged
已修改FFFGitSignModified
已删除FFFGitSignDeleted
已重命名FFFGitSignRenamed
未跟踪FFFGitSignUntracked
已忽略FFFGitSignIgnored

文件名文字高亮(需开启)

require('fff').setup({
  git = {
    status_text_color = true,  -- 启用文件名颜色
  },
  hl = {
    git_staged = 'FFFGitStaged',      -- 已暂存
    git_modified = 'FFFGitModified',   -- 已修改
    git_deleted = 'FFFGitDeleted',     -- 已删除
    git_untracked = 'FFFGitUntracked', -- 未跟踪
  },
})

5.4 .ignore 文件支持

FFF 自动读取 .gitignore 规则。此外,你还可以创建 .ignore 文件来额外过滤:

# .ignore

# 排除所有 markdown 文件
*.md

# 排除特定子目录
docs/archive/**/*.md

5.5 调试模式

启用调试

方式操作
快捷键在 picker 中按 F2
命令:FFFDebug [on|off|toggle]
默认启用debug.show_scores = true

查看日志

:FFFOpenLog

或手动打开:~/.local/state/nvim/log/fff.log


6. API 与命令

6.1 Lua API

-- 查找文件
require('fff').find_files()

-- 触发重新扫描
require('fff').scan_files()

-- 刷新 Git 状态
require('fff').refresh_git_status()

-- 在指定目录查找
require('fff').find_files_in_dir("/path/to/dir")

-- 更改索引基准目录
require('fff').change_indexing_directory("/new/path")

-- 带初始查询的 Grep
require('fff').live_grep({ query = "search term" })

6.2 Neovim 命令

命令说明
:FFFScan手动触发重新扫描
:FFFRefreshGit刷新 Git 状态
:FFFClearCache [all|frecency|files]清除缓存
:FFFHealth检查健康状态和依赖
:FFFDebug [on|off|toggle]切换调试模式
:FFFOpenLog在新标签页打开日志

6.3 健康检查

运行 :FFFHealth 会检查:

  • ✅ 文件 picker 初始化状态
  • ✅ 可选依赖(git、图片预览工具)
  • ✅ 数据库连接

7. 故障排除

7.1 常见问题

问题解决方案
搜索无结果运行 :FFFScan 强制重新扫描
Git 状态不更新运行 :FFFRefreshGit
调试评分F2 或设置 debug.show_scores = true
二进制下载失败检查网络连接,或手动编译

7.2 性能优化

场景建议
大型代码库(100k+ 文件)增大 max_threads
UI 卡顿设置 grep.time_budget_ms = 150
搜索太慢启用 lazy_sync = true
预览加载慢增大 preview.max_size 或关闭预览

7.3 日志位置

操作系统日志路径
Linux/macOS~/.local/state/nvim/log/fff.log
Windows%LOCALAPPDATA%\nvim\log\fff.log

8. 与同类工具对比

8.1 对比 Telescope.nvim

维度FFF.nvimTelescope.nvim
性能Rust 二进制,极速Lua 实现,稍慢
AI 集成原生 MCP 支持需额外配置
Frecency内置,开箱即用需插件额外配置
模糊算法Smith-Watermanfzf 算法
配置复杂度简洁较复杂

8.2 对比 fzf.vim

维度FFF.nvimfzf.vim
Neovim 原生✅ 专用插件❌ 依赖外部 fzf
Git 集成✅ Sign + 文字颜色仅 Sign
多选支持✅ Quickfix 集成基础
AI Agent 支持✅ MCP 服务器❌ 无

9. 总结

FFF.nvim 是一个专注于文件搜索的极致工具,它的核心价值在于:

为什么选择 FFF:

优势说明
双重用途同时服务 AI Agent 和人类开发者
极致性能Rust 二进制驱动,百万级文件秒搜
智能排序Frecency 算法让常用文件永远优先
AI 友好MCP 集成大幅减少 Token 消耗
抗错误Smith-Waterman 容忍拼写错误

适用场景:

  • 使用 Claude Code / Codex 等 AI Agent 进行开发
  • 在大型代码库中使用 Neovim
  • 需要精准文件搜索的开发者
  • 希望减少 AI Token 消耗的团队

不适用的场景:

  • 不使用 Neovim 的用户(可单独使用 MCP)
  • 小型项目(普通模糊搜索足够)

随着 AI 编程工具的普及,FFF.nvim 代表了一个重要方向:让 AI 和人类共享同一个高效的文件搜索基础设施


附录:相关资源

  • GitHub 仓库:https://github.com/dmtrKovalenko/fff.nvim
  • MCP 安装脚本:https://dmtrkovalenko.dev/install-fff-mcp.sh
  • 作者:dmtrKovalenko