everything-ai

AI agent 原生的全盘文件搜索 MCP server。机制逆向自 Everything 1.4.1.1032(NTFS MFT 直接解析 + USN Journal 增量),重新实现为 AI 可直接调用的工具——无需手动启动任何 GUI 程序挂后台。

与 Everything / WinShun 的关系

WinShun(LingCore/WinShun)对 AI 有价值的部分已吸收:延迟路径解析、便宜条件先筛/昂贵条件只跑候选、最长正项先测、!词 走排除快速路径、打分公式(整名相等 / 名字开头 / 词首 / 覆盖率 / 深度惩罚 / 低优先级目录降权)、recent_files / list_folder / file_info 三件套。未吸收的是图形界面、剪贴板历史、对话框搜索、拼音匹配和全文内容索引(那是独立的大工程,本项目的定位是文件名搜索,内容检索交给 ripgrep)。

机制逆向笔记(IDA 反编译 + 官方论坛交叉验证):docs/mechanism-notes.md

Related MCP server: everything-search-mcp

工具

search(query, kind, sort, limit, offset, path_scope, include_system)

主力工具,95% 的场景用这一个。

Everything 语法兼容子集:

• 空格 = AND,| = OR,! = NOT,"..." = 短语

• path:xxx 全路径匹配(词含 \ 时自动按路径匹配)

• ext:py;md 扩展名多值

• size:>1mb / <=100kb / =5gb(b/kb/mb/gb)

• dm:today / yesterday / thisweek / thismonth / thisyear / >2026-01-01 / 2026-10-14

• regex:xxx 正则、case:xxx 区分大小写、* ? 通配符

• kind: all / files / folders;sort: relevance(默认)/ modified / oldest / size / name

• path_scope: 只在某个目录子树里找;limit 1-200(默认 30)

• 空 query 返回最近修改的文件

默认相关性排序(移植 WinShun):整名相等 > 去扩展名相等 > 名字开头命中 > 词首命中 > 普通子串;命中覆盖率越高越前;目录略前、node_modules/.git/构建目录/系统目录里的降权 35、隐藏项降权 15、路径越深越靠后;同分时最近修改的靠前。

recent_files(folder, extensions, days, kind, limit, include_system)

最近修改的文件,倒序。问"刚写了什么""今天改了什么"用这个,不要用 search。

list_folder(path, extensions, days, kind, include_hidden, limit)

列出某个目录的直接子项(不递归,实读磁盘,永远是最新状态)。

file_info(path)

单个路径的元数据:是否存在、类型、大小、三个时间、扩展名、隐藏/只读。

index_status() / rebuild_index(volume="")

索引状态;强制全量重建(USN journal 断档时自动触发,一般无需手动)。

性能

C: 卷 157 万条、三卷 223 万条记录 / 274 万行扫描表(2026-10-15 实测,Windows 10,Python 3.14):

scripts/bench_search.py 同一次运行里,每个查询还会用"逐条完整 matcher"的暴力实现各跑一遍对结果总数——12 组全部一致;另外抽样比对索引里的 size 与磁盘 os.stat。

USN 增量是逐 FRN 落盘的;新建/改过的文件会回读磁盘补上 USN 记录里没有的文件大小(修改时间只向前推)。所以 agent 刚写出的文件不仅立刻能搜到,size 和 size: 查询也是对的。

启动:冷建索引(全量读 $MFT)约 70 s/三卷;之后从 SQLite 恢复 + USN 增量回放约 12-17 s。查询前的 USN 刷新只写变过的 FRN。

运行要求

• Windows + NTFS 卷,管理员权限(读 \\.\X: 卷设备;非 admin 时 search 返回明确错误)

• Python 3.12+,pip install mcp

注册到 MCP client

标准 stdio MCP server,任何支持 MCP 的 harness(Claude Code、Codex、Cline、DSH 等)都能直接挂载,配置项一致:

{
  "mcpServers": {
    "everything-ai": {
      "command": "python",
      "args": ["-m", "everything_ai.server"],
      "env": { "PYTHONPATH": "<本仓库克隆路径>" }
    }
  }
}

pip install -e . 后 PYTHONPATH 可省,command 可直接用 everything-ai(pyproject 里定义了同名入口)。各 client 的注册入口以其自身文档为准。

环境变量

已知边界

• 词只匹配文件名,不匹配父目录名:ext:py myproj 找不到 myproj\a.py,要写 ext:py path:myproj(WinShun 允许词落在父文件夹名上,这里没做——它会让预筛少一级,代价是候选循环里每个词都要再解析一次路径)。

• 首次运行会重建索引:SQLite 的 PRAGMA user_version 与代码里的 SCHEMA_VERSION 不一致时会丢掉缓存表重建(约 70 s)。升级后第一次启动属于这种情况。

• ReFS 卷未支持(Everything 支持;本机全 NTFS,未实现 V3/V4 record)

• USN 回放不跟踪硬链接别名增删(HARD_LINK_CHANGE),重建索引时校正

• 文件名搜索为主;file_info / list_folder 直读磁盘,内容搜索请用 grep/ripgrep

• 内存:索引含 lower(预折叠名)、parents/sizes/mtimes 平行数组和全部目录路径缓存,实测 274 万行约 1.34 GB

测试

python -m pytest tests/ -q          # 217 个单测(合成 fixture,不碰真实卷)
python scripts/bench_search.py      # 性能基线 + 与暴力实现的结果对拍(需管理员)
python scripts/compare_es.py        # 与 es.exe 对拍(需管理员 + Everything 索引在跑;
                                    #  es.exe 需在 PATH 或设 ES_EXE 指向完整路径)
python scripts/e2e_mcp.py           # MCP stdio 端到端(全部工具各调一次)

开发踩坑

从逆向到重实现、再到查询层优化踩过的坑按"现象 → 根因 → 修复"整理在 DEVELOPMENT.md——改解析层或查询层之前先读它。