filesift

FileSift

一款本地开源工具，可帮助 AI 编码 Agent 智能地搜索和理解代码库。

---

FileSift 可让 AI 编码 Agent 根据代码的功能搜索代码库，而不是根据代码的外观进行搜索。Agent 无需在 grep 后筛查整个文件，而是可以使用“身份验证中间件”或“数据库连接池”等自然语言查询，直接跳转到最相关的代码。所有操作都在本地计算机上运行——代码不会离开你的环境。

主要优势：

• 更智能的搜索——结合关键词与语义的混合搜索，可根据意图而非仅字符串匹配来查找代码
• 减少上下文浪费——立即为 Agent 定位正确的文件，节省探索时的 token 预算

安装

pip install filesift

使用方法

根据你的工作流，FileSift 有三种使用方式：

1. CLI

最直接的方式，适合测试查询、管理索引和配置设置。

# Index a project
filesift index /path/to/your/project

# Search for files by what they do
filesift find "authentication and session handling"

# Search in a specific directory
filesift find "retry logic for API calls" --path /path/to/project

2. MCP 服务

安装 FileSift 后还会提供 filesift-mcp 命令——这是一个轻量级 MCP 服务，可通过 STDIO 将索引和搜索功能作为工具提供。它适用于大多数热门编码 Agent，包括 Claude Code、Cursor、Copilot 等。

将其添加到 Agent 的 MCP 配置中：

{
  "mcpServers": {
    "filesift": {
      "command": "filesift-mcp"
    }
  }
}

MCP 服务提供四种工具：

• filesift_search——通过自然语言查询搜索已建立索引的代码库
• filesift_find_related——通过导入关系和语义相似度查找与指定文件相关的文件
• filesift_index——为目录建立索引以启用搜索
• filesift_status——检查目录的索引状态

3. Skills

FileSift 内置了 search-codebase 技能，可直接安装到编码 Agent 的技能目录中。这样 Agent 就能通过 bash 与 FileSift CLI 交互，无需支持 MCP。

# Install for Claude Code (default)
filesift skill install

# Install for other agents
filesift skill install --agent cursor
filesift skill install --agent copilot
filesift skill install --agent codex

支持的 Agent：claude、codex、cursor、copilot、gemini、roo、windsurf。

工作原理

FileSift 使用守护进程化的嵌入模型来保持搜索速度。它的核心功能是根据代码描述生成嵌入，并在称为索引的小型向量存储中执行搜索。

1. 索引——filesift index 首先构建快速的关键词/结构索引（数秒内完成），然后触发后台语义索引，为每个文件生成嵌入。

2. 守护进程——后台守护进程将索引加载到内存中，并在达到可配置的不活动时长后自动关闭。首次冷启动搜索后，后续搜索几乎即时完成。

3. 搜索——查询会同时通过关键词（BM25）和语义（FAISS）搜索进行匹配，然后使用倒数排名融合结合两种方法的结果，以充分发挥各自优势。

索引存储在每个已建立索引的项目内的 .filesift 目录中。

配置

FileSift 使用 TOML 配置文件，可通过 CLI 管理：

# View all settings
filesift config list --all

# Set a value
filesift config set search.MAX_RESULTS 20
filesift config set daemon.INACTIVITY_TIMEOUT 600

# Manage ignore patterns
filesift config add-ignore "node_modules" ".venv"
filesift config list-ignore

配置部分：search、indexing、daemon、models、paths。

贡献

欢迎贡献！开始贡献的步骤如下：

git clone https://github.com/roshunsunder/filesift.git
cd filesift
pip install -e .

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/my-feature）
3. 提交更改并创建拉取请求

许可证

Apache 2.0——详情请参阅 LICENSE。