dmtrkovalenko--fff.nvim/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

面向人类与 AI agent 的文件搜索工具包。速度极快。

抗拼写错误的路径与内容搜索、按 frecency（访问频次）排序的文件访问、后台监视器，以及轻量级内存内容索引。在任何需要多次搜索的长期运行进程中，比 ripgrep、fzf 等 CLI 快得多。

为 opencode, nushell, 以及许多其他出色项目的文件搜索提供动力！

最初作为广受喜爱的 Neovim 插件 起步，但事实证明大量 AI harness 与代码编辑器都需要同样的能力：作为库提供准确、快速的文件搜索。这就是 fff。

---

选择你感兴趣的内容：

MCP server

可与 Claude Code、Codex、OpenCode、Cursor、Cline 及任何支持 MCP 的客户端配合使用。减少 grep 往返次数、节省无效上下文、更快得到答案。

一行安装

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

若想先阅读脚本，可查看 install-mcp.sh 与 install-mcp.ps1。它们会打印针对你客户端的精确接入说明。

Homebrew（macOS / Linux）

brew install dmtrKovalenko/fff/fff-mcp
brew upgrade fff-mcp   # after new stable releases

Formula 位于本仓库的 Formula/fff-mcp.rb，每次稳定版发布都会自动 bump（见 .github/workflows/release.yaml 中的 bump-homebrew-formula）。从 GitHub releases. 安装预构建的 fff-mcp 二进制。

服务器连接后，让 agent「使用 fff」，即可启用 ffgrep、fffind 与 fff-multi-grep 工具。

推荐的 agent 提示词

将其放入项目的 CLAUDE.md 或等价文件中：

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

带来的变化

• Frecency 记忆。你实际打开过的文件下次排名更高。会基于 git touch 历史自动预热。
• 定义优先提示。看起来像代码定义的行在 Rust 侧完成分类，提示中无需正则开销。
• 智能大小写并自动模糊回退。IsOffTheRecord 可匹配 snake_case 变体；零匹配查询会重试为模糊搜索并呈现最佳近似命中。
• Git 感知标注。已修改、未跟踪与已暂存文件会被标记，便于 agent 优先关注你正在修改的内容。

源码：crates/fff-mcp/。

MCP server 为任意 agent 提供比内置方案更快、更省 token 的文件搜索工具。

Pi agent extension

安装

pi install npm:@ff-labs/pi-fff

模式

三种运行模式，可在运行时用 /fff-mode 切换：

模式	作用
tools-and-ui（默认）	添加 ffgrep 与 fffind 工具，用 FFF 替换 @-mention 自动补全。
tools-only	仅注入工具。保留 pi 原生编辑器自动补全。
override	用 FFF 实现替换 pi 内置的 grep、find 与 multi_grep。

环境变量：PI_FFF_MODE、FFF_FRECENCY_DB、FFF_HISTORY_DB。标志：--fff-mode、--fff-frecency-db、--fff-history-db。

面向 agent 的工具

• ffgrep。内容搜索。接受 path、exclude（逗号、空格或数组；前导 ! 可选）、caseSensitive、context，以及游标分页。自动检测正则，零精确匹配时回退为模糊搜索， upfront 拒绝仅含 .* 风格通配符的模式。
• fffind。路径与文件名搜索。匹配整个仓库相对路径，而非仅文件名。支持 frecency 感知。弱匹配检测器会在散乱的模糊噪声淹没 agent 上下文之前将其标记出来。

命令

• /fff-mode [tools-and-ui | tools-only | override]。显示或切换模式。
• /fff-health。选择器、frecency 与 git 集成状态。
• /fff-rescan。强制重新扫描。

源码：packages/pi-fff/。

Pi 扩展将 pi 的原生工具替换为 FFF 实现，并从按 frecency 排序的索引为交互式编辑器的 @-mention 自动补全提供数据。

fff.nvim

在 Linux 内核仓库上的演示（10 万文件，8GB）：

https://github.com/user-attachments/assets/5d0e1ce9-642c-4c44-aa88-01b05bb86abb

安装

lazy.nvim

{
  'dmtrKovalenko/fff.nvim',
  build = function()
    -- downloads a prebuilt binary or falls back to cargo build
    require("fff.download").download_or_build_binary()
  end,
  -- for nixos:
  -- build = "nix run .#release",
  opts = {
    debug = {
      enabled = true,
      show_scores = true,
    },
  },
  lazy = false, -- the plugin lazy-initialises itself
  keys = {
    { "ff", function() require('fff').find_files() end, desc = 'FFFind files' },
    { "fg", function() require('fff').live_grep() end, desc = 'LiFFFe grep' },
    { "fz",
      function() require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } }) end,
      desc = 'Live fffuzy grep',
    },
    { "fw",
      function() require('fff').live_grep_under_cursor() end,
      mode = { 'n', 'x' },
      desc = 'Search current word / selection',
    },
  },
}

vim.pack

vim.pack.add({ 'https://github.com/dmtrKovalenko/fff.nvim' })

vim.api.nvim_create_autocmd('PackChanged', {
  callback = function(ev)
    local name, kind = ev.data.spec.name, ev.data.kind
    if name == 'fff.nvim' and (kind == 'install' or kind == 'update') then
      if not ev.data.active then vim.cmd.packadd('fff.nvim') end
      require('fff.download').download_or_build_binary()
    end
  end,
})

vim.g.fff = {
  lazy_sync = true,
  debug = { enabled = true, show_scores = true },
}

vim.keymap.set('n', 'ff', function() require('fff').find_files() end, { desc = 'FFFind files' })

公开 API

require('fff').find_files()                        -- find files in current repo
require('fff').live_grep()                         -- live content grep
require('fff').live_grep_under_cursor()            -- grep <cword> in normal, selection in visual
require('fff').scan_files()                        -- force rescan
require('fff').refresh_git_status()                -- refresh git status
require('fff').find_files_in_dir(path)             -- find in a specific dir
require('fff').change_indexing_directory(new_path) -- change root

-- Programmatic search (no UI). Useful for plugin integrations.
require('fff').file_search(query, opts)            -- fuzzy search files / dirs / mixed
require('fff').content_search(query, opts)         -- programmatic grep

file_search(query, opts)

返回结构化结果 { items, scores, total_matched, total_files?, total_dirs?, location? }。每项包含 type 字段（"file" 或 "directory"）以及 name / relative_path。文件项还暴露 size、modified、git_status、is_binary 与 frecency 分数。

local r = require('fff').file_search('button', {
  mode             = 'mixed',  -- 'files' (default) | 'directories' | 'mixed'
  max_results      = 50,
  page             = 0,        -- 0-based pagination
  current_file     = nil,      -- path to deprioritize for distance scoring
  max_threads      = 4,
  cwd              = nil,      -- switch indexed root if different (see below)
  wait_for_index_ms = nil,     -- override the default scan wait timeout
})
for _, item in ipairs(r.items) do
  print(item.type, item.relative_path)
end

content_search(query, opts)

返回一个 GrepResult { items, total_matched, total_files_searched, total_files, filtered_file_count, next_file_offset, regex_fallback_error? }。每个匹配项包含 relative_path、name、line_number、col、line_content、match_ranges，以及与 file_search 相同的文件元数据。

local r = require('fff').content_search('TODO', {
  mode                  = 'plain',  -- 'plain' (default) | 'regex' | 'fuzzy'
  max_file_size         = 10 * 1024 * 1024,
  max_matches_per_file  = 100,
  smart_case            = true,
  page_size             = 50,
  file_offset           = 0,
  time_budget_ms        = 0,
  trim_whitespace       = false,
  cwd                   = nil,      -- switch indexed root if different
  wait_for_index_ms     = nil,      -- override the default scan wait timeout
})
for _, m in ipairs(r.items) do
  print(string.format('%s:%d %s', m.relative_path, m.line_number, m.line_content))
end

两个函数接受与 UI 选择器相同的约束语法（例如 git:modified、*.rs、!test/、glob 模式）。

cwd 与索引

file_search 和 content_search 均支持可选的 cwd 字段。首次调用任一函数时，会在 config.base_path（默认为你的 Neovim cwd）处惰性初始化选择器。

• 如果 cwd 与当前已索引的根目录一致，则调用会立即针对现有索引返回结果。
• 如果 cwd 不同，选择器会在新根目录处重新建立索引，调用会 阻塞（默认最长 10 秒），直到新选择器安装完成且初始扫描结束——因此调用方总能从正确的目录树获得结果。
• 若在 change_indexing_directory 之后索引仍在预热，可传入 wait_for_index_ms = N，无论是否由 cwd 触发切换，均可阻塞等待最长 N ms。传入 0 可完全跳过等待（适用于可接受部分结果的 fire-and-forget 调用）。
• 无效或不存在的 cwd 路径会返回空结果，并通过 vim.notify 输出错误。

命令

• :FFFScan。重新扫描文件。
• :FFFRefreshGit。刷新 git 状态。
• :FFFClearCache [all|frecency|files]。清除缓存。
• :FFFHealth。健康检查。
• :FFFDebug [on|off|toggle]。切换评分显示。
• :FFFOpenLog。打开 ~/.local/state/nvim/log/fff.log。

配置

默认值已足够合理。只需覆盖你关心的项。

require('fff').setup({
  base_path = vim.fn.getcwd(),
  prompt = '> ',
  title = 'FFFiles',
  max_results = 100,
  max_threads = 4,
  lazy_sync = true,
  prompt_vim_mode = false,
  follow_symlinks = false,
  -- Allow indexing the user's $HOME directory. Enabled by default.
  -- Disable if you strictly sure you don't want this, as it makes whole fff error hard
  enable_home_dir_scanning = true,
  -- Allow indexing a filesystem root (e.g. `/`, `C:\`). Disabled by default
  enable_fs_root_scanning = false,
  layout = {
    height = 0.8,
    width = 0.8,
    prompt_position = 'bottom',   -- or 'top'
    preview_position = 'right',   -- 'left' | 'right' | 'top' | 'bottom'
    preview_size = 0.5,
    -- Border style for the picker windows. Leave unset (nil) to follow the
    -- global `vim.o.winborder`; set it to override fff's borders independently.
    border = nil, -- 'single' | 'double' | 'rounded' | 'solid' | 'shadow' | 'none'
    flex = { size = 130, wrap = 'top' },
    min_list_height = 10, --  do not display anything except the list below this threshold
    show_scrollbar = true,
    path_shorten_strategy = 'middle_number', -- 'middle_number' | 'middle' | 'end' | 'start'
    anchor = 'center',
  },
  preview = {
    enabled = true,
    max_size = 10 * 1024 * 1024,
    chunk_size = 8192,
    binary_file_threshold = 1024,
    imagemagick_info_format_str = '%m: %wx%h, %[colorspace], %q-bit',
    line_numbers = false,
    cursorlineopt = 'both',
    wrap_lines = false,
    filetypes = {
      svg = { wrap_lines = true },
      markdown = { wrap_lines = true },
      text = { wrap_lines = true },
    },
  },
  keymaps = {
    close = '<Esc>',
    select = '<CR>',
    select_split = '<C-s>',
    select_vsplit = '<C-v>',
    select_tab = '<C-t>',
    move_up = { '<Up>', '<C-p>' },
    move_down = { '<Down>', '<C-n>' },
    preview_scroll_up = '<C-u>',
    preview_scroll_down = '<C-d>',
    toggle_debug = '<F2>',
    cycle_grep_modes = '<S-Tab>',
    -- grep mode only: jump cursor to first match of next/prev file group
    grep_jump_to_next_file = { '<C-A-n>', '<A-Down>' },
    grep_jump_to_prev_file = { '<C-A-p>', '<A-Up>' },
    cycle_previous_query = '<C-Up>',
    toggle_select = '<Tab>',
    send_to_quickfix = '<C-q>',
    focus_list = '<leader>l',
    focus_preview = '<leader>p',
  },
  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 = {
    status_text_color = false, -- true to color filenames by git status
  },
  select = {
    -- Return winid to open the chosen file in, or nil to open in the original window
    select_window = function(current_buf, action) --[[ default impl ]] end,
  },
  grep = {
    max_file_size = 10 * 1024 * 1024,
    max_matches_per_file = 100,
    smart_case = true,
    time_budget_ms = 150,
    modes = { 'plain', 'regex', 'fuzzy' },
    trim_whitespace = false,
    enable_filename_constraint = false, -- treat filename-like tokens (e.g. `score.rs`) in a grep query as a file-path filter scoping the search; off = searched as literal text
    location_format = ':%d:%d', -- printf format for line:col prefix in grep results, e.g. ':%d' for line-only
  },
  debug = {
    enabled = false, -- show the file info panel next to the preview
    show_scores = false, -- inline scores in the file list
    -- Per-section toggles for the file info panel. Accepts a boolean shorthand
    -- (`show_file_info = true|false`) to flip everything at once. The panel
    -- adapts to width: narrow renders sections vertically, wide renders them
    -- as a two-column grid. Disable a section to also shrink the panel.
    show_file_info = {
      file_info = true, -- size, type, git status, frecency
      score_breakdown = true, -- total + match type, bonuses, modifiers, penalty
      -- modified + accessed timestamps; pass a table to hide individual rows:
      --   timings = { modified = false, accessed = true }
      timings = true,
      full_path = true, -- relative path at the bottom (wraps if too long)
    },
  },
  logging = {
    -- logs will be written in a parent directory of this file path in files like
    -- `<stem>+<UTC-timestamp>+<pid>.<ext>`. Run :FFFOpenLog to open current one
    log_file = vim.fn.stdpath('log') .. '/fff.log',
    log_level = 'info',
    retain_runs = 20,
  },
})

实时 grep 模式

<S-Tab> 在 plain、regex 和 fuzzy 之间循环切换。列表可通过 grep.modes 配置，单模式设置会完全隐藏指示器。

每次调用覆盖：

require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } })
require('fff').live_grep({ query = 'search term' }) -- pre-fill

约束

find 和 grep 均接受以下标记以细化查询：

• git:modified。modified、staged、deleted、renamed、untracked、ignored 之一。
• test/。test/ 的任意深层子项。
• !something、!test/、!git:modified。排除。
• ./**/*.{rs,lua}。任意有效的 glob，由 zlob.

仅 Grep：

• *.md、*.{c,h}。扩展名过滤。
• src/main.rs。在单个文件内 grep。

可自由组合：git:modified src/**/*.rs !src/**/mod.rs user controller。

在调用方窗口中打开

默认情况下，fff.nvim 会尝试在最合适的窗口中打开文件，因此不会影响到非文件缓冲区。你可以通过提供以下配置来自定义或禁用该行为：

require('fff').setup({
  select = {
    select_window = function(_current_buf, _action) return nil end,
  },
})

注意：所选文件会替换调用窗口中的缓冲区，即使该缓冲区不可修改或具有特殊 buftype。winfixbuf 窗口仍会回退到 :split，以避免 E1513。

多选与 quickfix

• <Tab>。切换选中状态（在 signcolumn 中显示粗体 ▊）。
• <C-q>。将所选文件发送到 quickfix 列表并关闭选择器。

Git 状态高亮

默认开启 sign-column 指示器。若要按 git 状态为文件名文本着色，请设置 git.status_text_color = true 并调整 hl.git_* 组。完整列表见 :help fff.nvim。

浮动窗口颜色

选择器将其浮动内容映射到 NormalFloat（通过 hl.normal），边框映射到 FloatBorder。默认情况下，FloatBorder 链接到 NormalFloat，因此边框与内容默认共享同一背景，选择器呈现为单一弹窗。可覆盖 hl.normal = 'Normal'，使选择器与编辑器融为一体。

如需更精细的控制，可设置 hl.winhl 以覆盖各窗口的 winhighlight。它既可接受应用于每个选择器窗口的单个字符串，也可接受包含可选键 prompt、list、preview 和 file_info 的表。缺失的键将回退到由 hl.normal、hl.border 和 hl.title 构建的默认值。

-- Apply the same winhighlight to all picker windows
hl = { winhl = 'Normal:NormalFloat,FloatBorder:FloatBorder,FloatTitle:Title' }

-- Or override specific windows only
hl = {
  winhl = {
    prompt  = 'Normal:Pmenu,FloatBorder:FloatBorder',
    list    = 'Normal:NormalFloat,FloatBorder:FloatBorder',
    preview = 'Normal:NormalFloat,FloatBorder:FloatBorder',
  },
}

文件信息面板

通过 debug.enabled = true 启用。面板位于预览上方，显示文件元数据、分数明细、时间戳和完整绝对路径。它会根据面板宽度自适应：窄宽度时段落垂直堆叠（B2），宽宽度时段落以双列网格渲染（H2）。可通过 debug.show_file_info 单独禁用各段落。

通过 hl 自定义面板：

key	default	used for
file_info_section	Title	段落标题标签
file_info_separator	FloatBorder	作为段落边界的短划线
file_info_label	Comment	行标签（Size、Type、Git 等）
file_info_value	Normal fg	普通值
file_info_value_dim	NonText	暗淡值、行内分隔符
file_info_size	Number	文件大小值
file_info_type	Type	文件类型值
file_info_path	Directory	完整路径
file_info_total_score	bold + Number	总分（粗体）
file_info_match_type	bold + Special	匹配类型（粗体）
file_info_score_pos	DiagnosticOk	正分数分量
file_info_score_neg	DiagnosticError	负分数分量

文件过滤

FFF 遵循 .gitignore。对于不影响 git 的仅选择器忽略规则，请添加同级的 .ignore 文件：

*.md
docs/archive/**/*.md

运行 :FFFScan 以强制重新扫描。

故障排除

• :FFFHealth 验证选择器初始化、可选依赖项和数据库连接。
• :FFFOpenLog 打开当前会话的日志文件。
• 历史日志文件保存在主日志文件 <state>/log/fff+<UTC-timestamp>+<pid>.log 附近（最多 20 个文件）
• 如需崩溃回溯，请运行 lldb -- nvim 或 gdb -- nvim 并复现问题

Neovim 最好的文件搜索选择器，没有之一。查询更快、更直观，支持 frecency 排序、定义分类等功能。

Node & Bun SDK

npm install @ff-labs/fff-node
# or
bun add @ff-labs/fff-node

import { FileFinder } from "@ff-labs/fff-node";

const finder = FileFinder.create({ basePath: process.cwd(), aiMode: true });
if (!finder.ok) throw new Error(finder.error);
await finder.value.waitForScan(10_000);

const files = finder.value.fileSearch("incognito profile", { pageSize: 20 });
const hits = finder.value.grep("GetOffTheRecordProfile", {
  mode: "plain",
  smartCase: true,
  beforeContext: 1,
  afterContext: 1,
  classifyDefinitions: true,
});

// Run extremely fast glob matching which is significantly (10-100 times) faster than Bun's and Node implementation
const rustFiles = finder.value.glob("**/*.rs", { pageSize: 100 });

finder.value.destroy();

每个方法均返回 Result<T>（{ ok: true, value } | { ok: false, error }）。完整类型参考：packages/fff-node/src/types.ts。

面向 nodejs 和 bun 的 C 库 TypeScript 封装。可在 FFF 之上构建自定义 agent 工具、CLI 或 IDE 集成。

Rust crate

添加依赖

FFF 用 Rust 编写，因此这是开销最低的用法。

[dependencies]
fff-search = "0.6"

完整 API 文档：docs.rs/fff-search.

执行全部搜索的原生 Rust crate。稳定且文档完善。

C library

构建

# Builds only the C cdylib (fastest):
make build-c-lib

# or directly with cargo:
cargo build --release -p fff-c --features zlob

zlob 功能（需要 Zig 工具链）会将 glob 匹配和文件系统遍历都切换到 zlob's 原生并行遍历器。未启用时，默认构建使用纯 Rust 的 ignore（ripgrep）遍历器和 globset。

输出为 cdylib（libfff_c.so / libfff_c.dylib / fff_c.dll）。头文件位于 crates/fff-c/include/fff.h。

每个版本（包括 main 上的每次提交）的预构建二进制文件均在 releases page. 同一二进制文件也随 @ff-labs/fff-bin-* npm 包一同发布。

安装

# System-wide (needs sudo):
sudo make install

# User-local, no sudo:
make install PREFIX=$HOME/.local

# Staged install for packagers:
make install DESTDIR=/tmp/pkgroot PREFIX=/usr

将 libfff_c.{so,dylib,dll} 放入 $(PREFIX)/lib，头文件放入 $(PREFIX)/include/fff.h。使用 make uninstall 移除，它会遵循相同的 PREFIX 和 DESTDIR。

安装后链接：

cc my_app.c -lfff_c -o my_app

确保 $(PREFIX)/lib 在运行时库搜索路径中（Linux 上为 LD_LIBRARY_PATH，macOS 上为 DYLD_LIBRARY_PATH，或在 /etc/ld.so.conf.d/ 中有一条条目）。

最小示例

#include <fff.h>
#include <stdio.h>

int main(void) {
    FffResult *res = fff_create_instance(
        ".",        // base_path
        "",         // frecency_db_path (empty = default)
        "",         // history_db_path
        false,      // use_unsafe_no_lock
        true,       // enable_mmap_cache
        true,       // enable_content_indexing
        true,       // watch
        false       // ai_mode
    );
    if (!res->success) {
        fprintf(stderr, "init failed: %s\n", res->error);
        fff_free_result(res);
        return 1;
    }
    void *handle = res->handle;
    fff_free_result(res);

    // Search
    FffResult *search = fff_search(handle, "main.rs", "", 0, 0, 20, 100, 3);
    // ... read FffSearchResult from search->handle, then fff_free_search_result()

    fff_destroy(handle);
    return 0;
}

版本化选项结构体（推荐）

创建实例请使用 FffCreateOptions——一种可在不破坏 ABI 的情况下演进的版本化结构体。C99 指定初始化器（designated initializers）使调用点保持可读，并将未指定字段零初始化：

FffResult *res = fff_create_instance_with(&(FffCreateOptions){
    .version = FFF_CREATE_OPTIONS_VERSION,
    .base_path = "/path/to/repo",
    .ai_mode = true,
    .watch = true,
    .enable_fs_root_scanning = false,   // off by default
    .enable_home_dir_scanning = false,  // off by default
});

仅 Glob 搜索

fff_glob 按单个 glob 模式筛选已索引文件，按 frecency（访问频率）排序并分页——完全绕过常规查询解析器。当你已有字面 glob（*.rs、**/*.test.ts、src/**）且不希望在其上叠加模糊匹配时使用。

FffResult *res = fff_glob(handle, "**/*.rs", "", 0, 0, 100);
// FffSearchResult in res->handle, free with fff_free_search_result.

说明

• 每个返回 FffResult* 的函数都使用 Rust 的 Box 分配内存。请用 fff_free_result 释放，不要使用 malloc 的 free
• 载荷（搜索结果、grep 结果、扫描进度）各有专用的释放函数，列于头文件中。
• handle 字段中返回的 C 字符串（例如来自 fff_get_base_path）使用 fff_free_string 释放。

源码：crates/fff-c/。

稳定的 C ABI。可从 C/C++、Zig、通过 cgo 的 Go、通过 ctypes 的 Python，或任何支持 C FFI 的环境绑定。

Python 绑定

安装

pip install fff-search

或从源码构建并安装：

cd packages/fff-python
uv sync --all-extras
uv run maturin develop --release

基本用法

from fff import FileFinder

with FileFinder("/path/to/project", watch=False) as finder:
    finder.wait_for_scan_blocking(timeout_ms=5000)

    result = finder.search("main")
    for item, score in zip(result.items, result.scores):
        print(f"{item.relative_path}: {score.total}")

    hits = finder.grep("class Profile", mode="plain", before_context=1, after_context=1)

异步用法

wait_for_scan 是一个协程，轮询扫描状态并让出给事件循环，因此不会阻塞其他任务。在同步代码中使用 wait_for_scan_blocking。

import asyncio
from fff import FileFinder

async def main():
    with FileFinder("/path/to/project", watch=False) as finder:
        await finder.wait_for_scan(timeout_ms=5000)
        result = finder.search("main")
        print(result)

asyncio.run(main())

你能获得什么

• search、glob、directory_search、mixed_search — 按 frecency 排序的模糊文件/目录搜索
• grep / multi_grep — 纯文本、正则或模糊内容搜索，带上下文行与游标分页
• track_query / get_historical_query — 可选的 frecency 与查询历史数据库
• reindex、refresh_git_status、scan_progress、health_check — 生命周期与诊断

类型化结果对象（FileItem、Score、GrepMatch、…），包含 py.typed 桩。以兼容 Python 3.10+ 的 abi3 wheel 形式发布。

源码：packages/fff-python/。

使用 PyO3 构建的原生 Python 绑定。适用于 notebook、agent 脚本或任何需要快速文件搜索的 Python 工具。

---

FFF 是什么，为何选用它而非 ripgrep 或 fzf？

FFF 是文件搜索库，而非 CLI。Ripgrep 和 fzf 都是出色的工具，但它们是命令行程序：每次调用都会 fork 新进程、重新读取 .gitignore、重新 stat 目录，并在能给出答案前于内存中重建所需状态。从 shell 里 grep 一次时这没问题；但当编辑器或 AI agent 希望在单次会话中执行数百次搜索时就很糟糕。

FFF 将索引与文件缓存保留在一个长生命周期进程中，并通过四层薄封装暴露同一 Rust 核心：原生 crate（fff-search）、C 库（libfff_c）、Node/Bun SDK（@ff-labs/fff-node）以及 MCP server。你只需调用一次 FileFinder.create()，之后每次搜索都命中温热内存。在 50 万文件的 Chromium checkout 上，这就是每次 spawn ripgrep 需 3-9 秒与每次 FFF 查询亚 10 ms 的差别。

模糊匹配算法比 fzf 的算法全面得多，具有**抗 typo（拼写错误）**能力；我们还提供带额外约束解析的查询语言用于预过滤，例如 "*.rs !test/ shcema" 对 fff 是完全有效的查询，但 fzf 即使在 "shcema" 中有一个 typo 也找不到任何结果。

为何程序化 API 很重要

• 无进程 spawn。每次调用都在进程内完成，避免在短 rg 调用中占主导的 fork、exec、argv 解析与 stdout 管道设置。
• 一次 FS 遍历、元数据收集与 .gitignore 解析。ignore walker 仅在扫描时运行一次，结果供每次搜索复用。
• 结果以类型化对象返回，而非需重新解析的文本。SDK 直接提供 { relativePath, lineNumber, lineContent, gitStatus, totalFrecencyScore, isDefinition, ... }。
• 跨调用可用的游标分页。Ripgrep 没有「这些匹配的第 2 页」的概念；FFF 有。
• 长生命周期进程带来一次性 CLI 无法应用的优化：温热缓存、增量重索引、跨查询 frecency 与共享 SIMD 状态。

核心实际做了什么

• Frecency 排序的模糊匹配。 每个已索引文件都带有访问分数与修改分数。搜索会将你最近且频繁打开的文件排在冷门结果之上。这与 VS Code 的最近打开列表是同一思路，但应用于每条搜索结果，而不仅是侧边栏。
• 路径与内容均支持抗 typo 匹配。 grep 路径可使用 Smith-Waterman 模糊评分；路径搜索使用 SIMD 加速的模糊匹配（通过 frizbee-derived core)，可容忍丢字与重排）。
• 三种模式的内容 grep。 纯文本字面量（SIMD memmem）、正则（Rust regex crate）与模糊（每行 Smith-Waterman）。根据模式自动检测使用哪种模式，纯文本搜索零命中时回退到模糊模式。
• 多模式 OR 搜索。 SIMD Aho-Corasick 用于「一次性查找这 20 个标识符中的任意一个」，比正则交替更快，也远快于 20 次独立的 ripgrep 运行。
• 后台文件监视器。 文件变更时索引会更新。热路径上无需为重新扫描付出代价。
• Git 状态感知。 已修改、已暂存、未跟踪与已忽略状态会被缓存并随每条结果返回，调用方可排序或筛选而无需 shell 调用 git。监视器直接与 libgit2 通信，而非 spawn git CLI。
• 定义分类器。 Rust 侧的字节级扫描器为以 struct、fn、class、def、impl 等开头的行打标签。

重要的性能取舍

• 高效的内存分配器与分配策略（见下段）。默认使用 mimaloc
• 并行多线程搜索流水线，不受编排逻辑拖累
• 一切以 SIMD 优先的算法。高效且无分配的排序。
• 针对 FS 的平台特定优化（getdents64, Windows 上的 NTFS API 等）
• 轻量级即时内容索引，支持实时且抗 typo 的 grep
• 内存映射内容缓存。我们将部分文件存放在虚拟内存中（数量有限）
• 字符串块的单一连续 arena 存储。显著减少工作集内存并大幅提升 CPU 缓存命中。

内存分配

是的，fff 本质上比调用单个子进程需要更多内存。这正是速度提升的主要来源。实践中，与 Neovim 最流行的文件搜索选择器之一搭配使用时，fff 最终占用的 RAM 少于一连串 ripgrep 调用.

FFF 还维护内容索引，每个已索引文件约 360 字节，因此 10 万文件仓库约 36 MB。并非所有文件都会被索引——二进制文件、超大文件以及不适合 grep 的内容会被跳过。若连该占用都过高，索引可放在内存映射文件中而非匿名 RAM。

实际意义

如果你正在构建 agent、IDE 扩展、pre-commit 检查，或任何会多次搜索同一仓库的长期运行工具，将 FFF 作为库调用，比通过 shell 调用 ripgrep 要划算得多。代价是真实的内存占用：FFF 会将索引保留在 RAM 中，并预热内容缓存。在约 1.4 万文件的仓库上，常驻内存大约 26 MB。在像 Chromium 这样约 50 万文件的仓库上，预计需要几百 MB。作为交换，每一次搜索都会附带 git 状态、frecency 排序、文件元数据、最近访问与编辑时间戳等信息。

如果你只是在终端里执行一次 grep，rg 仍然是合适的选择。如果你在同一个进程里执行几十次，从第二次调用起 FFF 就能收回成本。如果你在做 AI agent，fff 会在你的 AI 有机会调用它之前完成准备工作。

对比

• ripgrep：FFF 使用相同的底层正则引擎，以及更先进的纯文本匹配算法。会存储内容索引和文件树。在重复搜索场景下优势最明显；在「从 bash grep 一次然后退出」的场景下则不如。
• fzf：FFF 的路径搜索与 fzf 一样是模糊匹配，但它还支持 frecency 感知和 git 感知，并内置容错性更强的算法。fzf 是纯匹配与过滤工具；FFF 会按你实际打开文件的频率对结果排序。
• Telescope / fzf-lua / snacks.picker：FFF 自带 Neovim picker，排序逻辑与 MCP server 和 SDK 一致。picker 是可选的；核心相同。
• Tantivy 或其他全文搜索引擎：属于不同类别的工具。Tantivy 为大规模查询时评分而索引文档。FFF 限定在单个仓库，并针对亚 10 ms 响应进行优化。它不会在磁盘上持久化倒排索引。

---

仓库结构

• crates/fff-search、crates/fff-grep、crates/fff-query-parser — Rust 核心。
• crates/fff-c — 各语言绑定共用的 C FFI。
• crates/fff-nvim — Neovim 插件的 Lua/mlua 绑定。
• crates/fff-mcp — MCP server 二进制。
• packages/fff-node — Node.js SDK（@ff-labs/fff-node）。
• packages/fff-bun — Bun SDK（@ff-labs/fff-bun）。
• packages/pi-fff — pi 扩展（@ff-labs/pi-fff）。
• lua/ — Neovim 侧插件代码。

贡献

欢迎提交 bug 报告和 pull request。可以使用 agentic 编码工具，但必须经过人工审查。

许可证

MIT & open source forever.