file-search-system v1.0.0

基于 Everything 的本地毫秒级文件搜索系统。 纯 Python 标准库（ctypes）零依赖；非管理员文件夹索引（NTFS / ReFS / FAT32 / exFAT / 可移动盘 / 网络共享）；Everything 后台静默运行（无窗口、 无托盘、便携模式）；全部能力经 CLI / Python / HTTP 三种接口提供。

• 环境要求：Windows 8.1+（推荐 Win10/11）· Python 3.12+
• 自带引擎：pip install / uv add 装完即用，无需单独安装 Everything
• 搜索语法即 Everything 官方语法：ext: size: dm: path: … https://www.voidtools.com/support/everything/searching/

安装

pip install file-search-system

uv add file-search-system

装好即带 Windows 版 Everything 引擎（Everything.exe + 四架构 SDK DLL）， 首次运行自动就绪，无需另行下载。

file-search init            # 一次性初始化：定位引擎 + 配置 + 静默拉起 + 就绪
file-search "README" -n 5   # 立刻可用

引擎与配置落在哪里

原因是 Everything 的便携模式必须在 Everything.exe 旁写 Everything.ini / Everything.db，而安装目录通常不可写，所以首次使用会把 引擎释放到用户可写目录，之后一直复用该副本。

自定义位置（任选其一）：

set FILE_SEARCH_BIN=D:\my-everything\bin   # 指定引擎目录（bin_dir= 参数同义）
set FILE_SEARCH_HOME=D:\my-data            # 指定引擎落地与配置目录
set FILE_SEARCH_DATA=D:\my-data            # 只指定 config.ini 所在目录

查看实际路径、或把自带引擎导出到任意目录：

file-search engine info                    # 显示引擎 / DLL / 配置文件的实际位置
file-search engine install D:\my-app\bin   # 复制一份自带引擎过去（独立分发用）

运行要求与安全说明

• 需要 Windows 与可运行的 Everything 引擎；非 Windows 平台会在导入时给出 明确报错。
• 本系统内部所有"重启/关闭引擎"的路径（shutdown / set_config 重启 / 看门狗恢复 / kill_own_process）都与查询串行，引擎死亡瞬间无在途查询。 若外部（任务管理器、taskkill /F）恰在查询在途时强杀引擎，SDK DLL 内部锁会被卡死线程持有，宿主的 Python 进程需要重启（is_running 会探测 到并告警）。

一、CLI

搜索

file-search search "关键词" [选项]        # search 可省略
file-search "ext:py size:>10mb"           # 等价写法
file-search "*.pdf" --paths-only -n 20

索引管理

file-search index add "D:\docs" "E:\media"      # 添加目录（立即返回，后台扫描）
file-search index add --disks C D               # 整盘
file-search index add "D:\data" --exclude temp  # 自定义排除目录
file-search index add "D:\data" --prescan       # 预扫描 junction（最安全，较慢）
file-search index add "D:\data" --no-monitor    # 不实时监控变化（更省资源）
file-search index snapshot "E:\backup"          # EFU 快照模式（秒级加载）
file-search index status [--wait 300]           # 扫描进度（可等待完成）
file-search index list                          # 当前索引配置（写法 -> 本机展开）
file-search index defaults                      # 预览默认目录发现（不改动）
file-search index disks                         # 本机磁盘（盘符/类型/文件系统）
file-search index network [--add]               # 发现网络共享（--add 加入索引）
file-search index remove "E:\media"             # 移除目录
file-search index clear                         # 清空索引

index add 参数：--disks（整盘列表）、--exclude（排除目录名）、 --exclude-files（排除文件通配）、--prescan / --no-prescan、 --monitor / --no-monitor。默认排除 node_modules / .pnpm / .git / __pycache__。

其他命令

file-search init                                # 初始化（幂等：配置+拉起+就绪）
file-search status                              # 运行/就绪/索引/OS 兼容等级
file-search compat                              # 本机兼容体检（10 项只读）
file-search config list [前缀]                  # 引擎键列表
file-search config get 键1 键2                  # 读引擎键
file-search config set 键=值 [键=值...]         # 写引擎键并重启生效
file-search runcount get "C:\a.exe"             # 运行次数 get / inc / set
file-search runcount inc "C:\a.exe"
file-search runcount set "C:\a.exe" 5
file-search db save                             # 数据库 save / rebuild /
file-search db rebuild                          #        update-folders /
file-search db run-history-delete               #        run-history-save / delete
file-search serve --host 0.0.0.0 --port 8465    # HTTP 服务（见第三节）
file-search engine info|install                 # 引擎目录查看 / 导出
file-search exit [--force]                      # 退出 Everything

python -m file_search 与 file-search 等价。

二、Python 库

导入与初始化

from file_search import EverythingManager

mgr = EverythingManager()      # 构造零副作用；首条命令自动完成启动链
info = mgr.init()              # 或显式初始化（幂等），返回状态摘要

构造参数：

自动定位优先级：bin_dir 参数 → FILE_SEARCH_BIN 环境变量 → base_dir/bin → 源码树 <项目根>/bin → 用户数据目录（首次自动释放引擎）。

搜索

results = mgr.search("*.pdf size:>1mb", max_results=50, sort="date-modified")
for r in results:
    print(r["full_path"], r["size"], r["date_modified"])

total = mgr.last_total_for_thread()    # 本次查询的总命中数（并发安全）

search() / submit_search() 参数：

结果字段（按 request_flags）：full_path、file_name、path、 extension、size、date_created/modified/accessed/run/recently_changed、 attributes + attributes_str、cloud_only（OneDrive 云占位）、 run_count、is_file/folder/volume；高亮三字段需显式请求。

非阻塞搜索

h = mgr.submit_search("ext:log", max_results=100)   # 立即返回，绝不阻塞
if h.wait(3.0):                                     # 最多等 3 秒
    for r in h.results():
        print(r["full_path"])
else:
    print(h.status())      # {"state": "pending"|"scanning"|"complete"|...}

# 句柄方法：done() / wait(秒) / results() / status() / cancel()

索引与生命周期

mgr.index_add([r"D:\docs"], excludes=["temp"], monitor=True)   # live 索引
mgr.index_snapshot([r"E:\backup"])                             # EFU 快照
mgr.index_remove([r"D:\docs"])
mgr.index_clear()
mgr.prescan_junctions([r"F:\Data"])     # 并行 junction 预扫描
mgr.wait_index_stable(timeout=600)      # 等扫描完成
mgr.export("*.md", "out.csv", fmt="csv")# 导出 csv/json/txt/efu

mgr.start()                             # 静默启动（未运行时）
mgr.status()                            # 完整状态 dict
mgr.shutdown(force=True)                # 用完即关
mgr.cleanup()                           # 关闭自启实例 + 释放 SDK

默认退出语义为长驻（Python 结束后 Everything 留守，下次毫秒级可用）； shutdown(force=True) 为用完即关。

外部应用自带引擎时，可先用 CLI 复制一份再显式指定：

file-search engine install D:\my-app\bin

mgr = EverythingManager(bin_dir=r"D:\my-app\bin")

三、HTTP API

file-search serve                                  # 默认 127.0.0.1:8465
file-search serve --host 0.0.0.0 --port 8465       # 对外暴露（建议加 token）
file-search serve --token my-secret                # 令牌鉴权

所有端点在启用令牌后须带 X-Api-Token 头（不符 → 401）。

端点：

请求示例：

curl "http://127.0.0.1:8465/search?q=ext:pdf&max=20&sort=size-desc"
curl -H "X-Api-Token: my-secret" "http://127.0.0.1:8465/search?q=readme"

# /search 参数：q, max(≤10000), offset(≥0), sort, regex, case,
#               whole-word, match-path, timeout, wait_index

curl "http://127.0.0.1:8465/search/submit?q=readme&max=10"
# -> {"id": "e3ecfb87..."}
curl "http://127.0.0.1:8465/search/result?id=e3ecfb87..."
# -> {"status": {"state": "complete"}, "results": [...]}

curl -X POST "http://127.0.0.1:8465/index/add" \
     -H "Content-Type: application/json" \
     -d '{"folders": ["D:\\docs"], "monitor": true}'

内置限制：请求体 ≤ 1 MiB（413）、搜索串 ≤ 8192 字符与 max ≤ 10000（400）、 非阻塞句柄注册表 ≤ 4096（429）。

四、config.ini（唯一配置文件）

三节结构，每键带注释，可手编（支持记事本 UTF-8 BOM）；程序改写时注释 自动再生、原子写不损坏。默认位置见上文"引擎与配置落在哪里"， 也可用 FILE_SEARCH_HOME 指定目录。

[index]
# live = 实时文件夹索引（默认）；snapshot = EFU 快照（秒级加载，静态）
mode = live
# 索引目录列表（逗号分隔；支持 %ENV% 变量与相对路径 = 跨设备可移植；
# 留空 = init() 自动采用默认：用户数据目录 + 全部非系统盘）
folders =
# 按目录名排除（node_modules/.pnpm 是 junction 雷区，必须排除）
excludes = node_modules,.pnpm,.git,__pycache__
# 按文件通配符排除（如 *.log,*.tmp）
exclude_files =
# 1 = 实时监控目录变化；0 = 仅启动时扫描（更省资源）
monitor = 1
# snapshot 模式的 EFU 文件路径（index snapshot 自动生成维护）
efu =

[engine]
# Everything 引擎高级键（config set 写入；手编前先 config list 确认键名）
# 示例（去掉行首 # 即生效）：
# exclude_hidden_files_and_folders = 1
# exclude_system_files_and_folders = 1
# db_location =
# language = 0

[server]
# serve 监听地址（对外暴露请配 0.0.0.0 并启用 token）
host = 127.0.0.1
# serve 监听端口（CLI --host/--port 可临时覆盖）
port = 8465
# API 令牌：非空时所有 HTTP 请求须带 X-Api-Token 头（留空 = 本机免鉴权）
token =

引擎目录下的 Everything.ini（739 键）才是引擎实际生效文件，由系统从 config.ini 自动生成维护，不要手编。受管键（索引五键 + 无 GUI 四键） 禁止经 [engine] 改写。

项目结构

file_search/               # Python 包
├── sdk.py                 # Everything SDK 逐函数封装（80+ 方法）
├── manager.py             # 生命周期 / 索引配置 / 非阻塞搜索 / 看门狗
├── scanner.py             # 并行 junction 免疫扫描器 + EFU 生成
├── server.py              # HTTP JSON API
├── cli.py                 # 全功能命令行
├── paths.py               # 引擎与配置定位 / 引擎释放
└── _engine/               # 自带 Everything 引擎（exe + 四架构 SDK DLL）

_engine/ 内的 Everything 与 SDK 为 voidtools 的 MIT 许可 （见 _engine/License.txt），随本包一并分发。