Pi 扩展包可以执行代码并影响智能体行为。安装第三方扩展前，请先检查其源代码与权限范围。
README · 中文参考版
@ff-labs/pi-fff
用 FFF 的 Rust 原生索引替代频繁启动 `fd` 与 `rg` 子进程，为 Pi 提供即时、模糊、具备使用记忆的文件和内容搜索。
它做什么
| 工具 | 改进 |
|---|---|
| fffind | 模糊文件名匹配、频近度排序、Git 感知和预索引 |
| ffgrep | SIMD 加速、频近度排序、mmap 缓存且无需子进程 |
| fff-multi-grep | 通过 Aho-Corasick 执行 OR 逻辑多模式搜索 |
| @ 文件补全 | 使用 FFF 索引和频近度进行模糊排序 |
相对内置工具的优势
- Rust 原生库通过 Node binding 调用，不为每次搜索启动
fd或rg。 - 会话开始时在后台建立索引，后续搜索即时完成。
- 经常访问的文件排名更高，并跨会话学习选择记录。
- 查询历史会记住某个查询最终选择了哪个文件，并为相同组合提供额外排序加成。
- 修改、暂存和未跟踪的 Git 文件会获得排名提升。
- 全小写查询不区分大小写，包含大写时自动切换为区分大小写。
- 文件搜索容忍拼写错误；内容搜索支持 cursor 分页。
安装
# 全局安装
pi install npm:@ff-labs/pi-fff
# 项目级安装
pi install -l npm:@ff-labs/pi-fff
# 从 Git 安装或固定版本
pi install git:github.com/dmtrKovalenko/fff
pi install git:github.com/dmtrKovalenko/fff@v0.3.0安装后会在 Pi 内置工具旁注册 fffind、ffgrep 与 fff-multi-grep。
本地开发或手动安装
git clone https://github.com/dmtrKovalenko/fff.git
cd fff/packages/pi-fff
npm install然后把扩展绝对路径加入 Pi settings.json 的 extensions，或直接运行 pi -e /path/to/fff/packages/pi-fff/src/index.ts 测试。
工具
ffgrep
搜索文件内容。默认使用纯文本和智能大小写，可选正则、目录约束、上下文行数、结果上限与 cursor。
| 参数 | 含义 |
|---|---|
| pattern | 搜索文本或正则表达式 |
| path | 目录、文件或 glob 约束，例如 src/、*.ts |
| ignoreCase / literal | 强制忽略大小写；literal 默认为 true |
| context | 每个命中前后的上下文行数 |
| limit / cursor | 最大匹配数默认 100；cursor 获取下一页 |
fffind
按文件名进行模糊搜索，并根据频近度排序。支持目录约束和结果数量限制。
| 参数 | 含义 |
|---|---|
| pattern | 模糊查询，例如 main.ts 或 src/ config |
| path | 可选目录范围 |
| limit | 最大结果数，默认 200 |
fff-multi-grep
使用 SIMD 加速 Aho-Corasick，同时搜索多个字面模式。支持文件约束、上下文和分页。
| 参数 | 含义 |
|---|---|
| patterns | 按 OR 逻辑匹配的字面字符串数组 |
| constraints | 文件约束，例如 *.{ts,tsx} !test/ |
| context | 命中前后的上下文行数 |
| limit / cursor | 最大匹配数默认 100；cursor 获取下一页 |
命令
| 命令 | 作用 |
|---|---|
| /fff-health | 查看索引文件数、Git 信息与频近度/历史数据库状态 |
| /fff-rescan | 触发文件重新扫描 |
| /fff-mode <mode> | 切换工作模式；工具名称变化时需要重启 |
模式
| 模式 | 行为 |
|---|---|
| tools-and-ui | 默认；新增三个 FFF 工具，并使用 FFF 驱动 @ 补全 |
| tools-only | 只新增工具，保留 Pi 默认 @ 补全 |
| override | 替换 Pi 的 find 与 grep，增加 multi_grep 和 FFF 补全 |
模式优先级为：--fff-mode CLI 参数、PI_FFF_MODE 环境变量、默认 tools-and-ui。切换工具名称后需要重启。
启动参数
| 参数 | 作用 |
|---|---|
| --fff-mode <mode> | 设置工作模式，也可用 PI_FFF_MODE |
| --fff-frecency-db <path> | 指定频近度数据库路径，也可用 FFF_FRECENCY_DB |
| --fff-history-db <path> | 指定查询历史数据库路径，也可用 FFF_HISTORY_DB |
| --fff-enable-root-scan | 明确允许从文件系统根目录建立索引，也可用 FFF_ENABLE_ROOT_SCAN=1 |
| --fff-enable-home-scan | 控制从 HOME 启动时是否索引整个主目录，也可用 FFF_ENABLE_HOME_SCAN |
主目录扫描默认开启。如果 HOME 中包含大型工具链、内核源码或构建输出，可传 --fff-enable-home-scan=false 或设置 FFF_ENABLE_HOME_SCAN=0；开启时 Pi 会提示正在索引整个主目录。
本地数据
FFF 使用两个 LMDB 数据库：frecency 保存文件访问频率与最近使用时间，history 保存查询到最终所选文件的记录。两个路径彼此独立解析。
- 优先使用对应 CLI 参数，其次使用 FFF_FRECENCY_DB 或 FFF_HISTORY_DB 环境变量。
- 若检测到现有 fff.nvim 数据库，会复用编辑器中积累的 frecency 与查询历史；只读取，不会把 Pi 的搜索回写到 Neovim 历史。
- 否则按需创建 Pi 自己的
$PI_CODING_AGENT_DIR/fff/{frecency,history}，默认位于~/.pi/agent/fff/。 - 数据库无法打开时，搜索仍会以无持久化模式启动并显示警告，不会导致扩展整体失败。
扩展不会上传项目文件；全部索引与排序在本地完成，只有 Pi 本身配置的模型提供商保持原有的数据路径。
安全
- 扩展代码不执行 shell。
- 扩展代码不发起网络请求，也不包含遥测。
- 除 Pi 与模型提供商已有行为外，不处理额外凭据。
- 搜索状态只保存在本地
~/.pi/agent/fff/。 - 默认拒绝从文件系统根目录初始化，避免意外扫描整个磁盘。
本页依据 pi.dev 的包详情与项目 README 逐节翻译并整理为中文参考内容。
查看英文原页 ↗