文件搜索

======================================================================

 QuickFind —— 介绍文档

======================================================================

 版本   1.4.1.1032（里程碑 M5.3）

 许可   个人项目，未附开源许可（发行包含洁净室声明 LICENSE.txt）

 仓库   未公开

 形态   Windows 桌面搜索工具：命令行 + 原生界面 + 常驻服务

 依赖   C++20、CMake / Ninja（MSVC）、NTFS（$MFT / USN）、Win32 API

----------------------------------------------------------------------

 一、它是什么

----------------------------------------------------------------------

  一个直接从 NTFS 元数据取数的 Windows 文件名搜索工具：读 $MFT 建库、

  用 USN 日志做增量，查询语法自己解析求值，同一套核心同时供命令行、

  原生窗口界面和常驻服务使用。

----------------------------------------------------------------------

 二、解决什么问题

----------------------------------------------------------------------

  · 全盘遍历建索引慢，磁盘一忙就更慢。

  · 文件改名、移动后旧索引失真，只能整库重建。

  · 图形界面和命令行常常是两套实现，同一个查询给出两种结果。

----------------------------------------------------------------------

 三、功能

----------------------------------------------------------------------

  · 首次建库直读固定卷的 $MFT，并解析 $ATTRIBUTE_LIST 补齐扩展记录，

    不走目录遍历、不逐条回查路径。

  · 本机 C+F+I+J 四个固定卷合计约 602 万条，冷扫描约 23.5 秒；再次启动

    只重放 USN 增量，约 2.1 秒（测试机口径，不是通用性能承诺）。

  · 状态文件 QFI2 支持多卷，每条记录带卷号，路径、父链、排序互不串卷；

    删除做墓碑标记，--rebuild 可重整。

  · 查询语法：布尔与括号、通配符、短语、正则，以及 ext: / size: / dm: /

    dc: / da: / attrib: / len: / stem: / depth: / infolder: / parent: /

    child: / file: / folder: / dupe: / sizedupe: / frn: / count: 等。

  · 排序：名称 / 路径 / 大小 / 扩展名 / 类型 / 三个时间 / 属性 / 运行次数；

    带条数上限时先取前 k 条再排序，不全量排序。

  · 输出：控制台文本、JSON、CSV / TSV / EFU 导出；EFU 也可反向导入，

    当作离线索引直接用查询语法过滤。

  · 命令行与界面共用同一份配置文件：筛选器、书签、文件操作（复制、移动、

    改名、建快捷方式、删除到回收站）两边都有，语法与排序一致。

  · 原生界面：虚拟列表（按需取行）、六列显隐与拖拽重排、图标视图（异步

    系统缩略图）、预览面板（文本 / 图片 / 元数据 / 系统预览处理器）、

    多窗口、按显示器 DPI 缩放。

  · 常驻形态：命名管道服务端 + 客户端、托盘、Windows 服务，标准用户即可

    查询；高权限进程持有索引并持续吃增量。

  · 附带语音助手适配插件（qf_search.dll，独立发行包），按 JSON 取结果，

    不把核心代码链接进宿主进程。

----------------------------------------------------------------------

 四、技术与依赖

----------------------------------------------------------------------

  · 索引：$MFT 直读，扩展记录按 FSCTL_GET_NTFS_FILE_RECORD 补读；

    增量走 FSCTL_READ_USN_JOURNAL。

  · 内存结构：FRN + 父 FRN + 名字池 + 标准信息 / 数据元数据的紧凑索引。

  · 查询：自带词法分析与语法解析得到语法树，再多线程求值、排序、截断。

  · 界面：Win32 + comctl32 原生控件，不引入第三方界面框架。

  · 进程：核心库供命令行与窗口版共用；两个可执行文件静态链接 MSVC

    运行时（/MT），目标机无需安装 VC++ 运行库。

----------------------------------------------------------------------

 五、怎么跑

----------------------------------------------------------------------

  发行包：解压后双击 qf-gui.exe（或用 QuickFind.cmd），首次启动即建库。

  建库、--serve、安装服务需要管理员权限（要打开 \\.\C: 卷句柄）；

  --client 只连管道，标准用户即可。

    qf.exe --index C,F --search "size:>100mb dm:2026" --sort size --desc

    qf.exe --search "wfn:notepad.exe" --json-summary --limit 20

  源码构建（脚本会自动定位 VsDevCmd / CMake / Ninja）：

    .\tools\build.ps1 -Test

    .\tools\package.ps1 -Clean     产出 dist\QuickFind-<版本>-win-x64\

----------------------------------------------------------------------

 六、目录

----------------------------------------------------------------------

  src/core/     索引、查询、USN、EFU、IPC、服务与引擎

  src/ui/       原生界面：窗口、菜单、图标视图、预览、配置

  plugin/       语音助手适配插件（qf_search）

  docs/         总览、查询语法、IPC 协议、变更记录

  tools/        构建、打包、界面与插件回归脚本

  tests/        核心回归与插件冒烟

  dist/         发行产物（本目录）

----------------------------------------------------------------------

 七、边界与不做什么

----------------------------------------------------------------------

  · 只处理 NTFS / ReFS 固定卷，不索引网络盘与移动盘；建库需管理员权限。

  · 多卷状态整份复用：任一选中卷的序列号或日志 ID 变了就全部重建。

  · 管道仅本机可用，不按查询或路径做权限过滤；服务端查询串行，

    没有取消、分页与协议版本协商。

  · 不做 ETP / FTP / HTTP 服务端；runcount:、childcount:、dateaccessed:

    等函数未实现，会按普通文本处理。

  · dupe: 与 sizedupe: 只按名字、大小分组，不比对文件内容。

  · 界面不做深色主题与语法高亮，预览文本折行显示、不横向滚动。

  · 状态文件是内部格式，与任何其他搜索工具的数据库不兼容。