XFE Git
XFE Studio Git
Git 首页 全局搜索
XFE 主站 文档 NuGet

XFEToolBox

【WPF】XFE工具箱

公开
关注 0 Fork 0 Star 0
README.md

文件快速搜索验收

Ctrl+Alt+Space 默认打开第一栏“文件快速搜索”;第二栏保留原工具、软件、项目和命令搜索。 快捷键仍可在设置中更改或关闭。主页的“搜索文件”、输入框回车及托盘入口进入第一栏。 “工具与命令”按钮进入第二栏,Ctrl+1 / Ctrl+2 可切换。

文件图标与结果视图

文件结果显示 Windows 关联图标;EXE、快捷方式、ICO 等使用路径专用图标,普通文档共享扩展名图标。 仅虚拟化列表中已经显示的行才请求图标;Shell 调用使用两个独立 STA 低优先级线程、128 项有界队列及 2048 项 LRU 缓存。 成功图标冻结后异步送回界面,失败时保留轻量文件/文件夹图形,不阻止搜索结果显示。 连续输入时优先处理最新可见图标,释放淘汰结果的请求,未变的结果模型和图标保持复用。

Ctrl+滚轮 调节结果行文字与图标大小(70%–160%,每次 10%),Ctrl+0 恢复 100%;不改变输入框大小。 普通滚轮仍正常滚动,缩放后保留列表虚拟化。窗口不再始终置顶,快捷键唤起时只正常激活窗口。 文件检索、结果准备及工具栏搜索排序均在后台执行,过期查询不会覆盖最新输入;界面只提交有效结果和少量可见行的绑定。

独立 NTFS 索引服务

安装器默认勾选“安装高速文件索引服务”;已有安装或便携版可在“选项设置 → 高速文件索引服务”安装/更新、查看状态或卸载。 仅服务安装助手申请 UAC,主程序仍使用 asInvoker,安装器完成后的启动也使用普通桌面用户令牌。 服务以 LocalSystem 延迟自动启动,独立于主窗口生命周期。未安装、拒绝 UAC、服务停止或卷不支持时,自动回退下述普通权限扫描。

  • 首次通过 FSCTL_QUERY_FILE_LAYOUT 批量读取 NTFS 文件记录及硬链接名称,建立父目录图和分片二/三元倒排索引。
  • 构建前保存 USN 起点,构建后回放日志以覆盖首扫期间的变动;目录移动、改名只更新受影响子树。
  • 原子持久化卷标识、日志 ID、USN 游标与目录图。有效缓存启动只恢复并回放 USN,不再重新枚举 MFT;日志截断、重建或卷身份变化仅重建受影响卷。
  • CPU 构建线程数默认等于可用逻辑处理器数,独立低优先级线程不占用搜索线程池;原生磁盘读取有界并使用低 I/O 优先级。会尽量利用多核,但磁盘受限阶段不保证 CPU 恒定 100%。
  • 主程序不重复扫描服务已覆盖的磁盘;正文搜索是例外,始终由普通权限主程序建立可选的本地正文索引。
  • 服务缓存位于 %ProgramData%/XFEToolBox/IndexingService,仅 SYSTEM/Administrators 可访问;服务发行文件位于 %ProgramFiles%/XFEToolBox/Services/IndexingService,普通用户只读。
  • 查询经过仅本地命名管道,客户端先验证服务器为 SCM 登记的 SYSTEM 服务;服务模拟请求用户检查目录祖先权限,不把受保护目录的文件名或匹配数直接返回用户。
  • 服务不读取正文、不创建 USN 日志、不接受任意路径写入/执行或普通用户发起的全量重建命令。无日志的卷回退普通扫描;重解析点祖先保守拒绝,当前以驱动器盘符根目录为完整支持范围。

F5/“重新扫描索引”刷新服务状态,并校准普通权限回退索引;不是强制服务全量重建。 单次服务查询最多显示 10,000 项,达到上限后请缩小范围或关键词。 索引任务与搜索均不在 Dispatcher 上运行;过期文件名查询使用 TrySearch 返回取消状态,不抛出正常输入替换引起的 OperationCanceledException。 库 API Search 仍保留标准取消异常契约。

已完成非提权模拟卷、持久检查点、真实 Windows ACL/管道及 WPF 回归;没有在开发机器注册服务或进行管理员真实整盘首扫。 因此不能把模拟样本耗时当作 Everything 级实盘速度,真实安装、重启追赶 USN 和磁盘首次性能仍需隔离 Windows 环境验收。

参考:微软 FSCTL_QUERY_FILE_LAYOUT、 USN 日志读取参数。

普通权限回退索引

文件名和路径使用本地二/三元倒排索引,目录路径单独建索引,查询不枚举磁盘。 没有可用服务覆盖时,首次使用后台扫描当前用户可访问的本地固定磁盘;扫描过程中已有条目可搜索。 压缩快照用于后续启动,恢复时分批发布,已恢复的条目可立即查询,不等待整个缓存读完。 磁盘初始化、切换范围、缓存恢复和搜索均从工作线程进入;取消搜索的清理回调也不在界面线程执行。 同一磁盘的目录由专用低资源优先级线程并行扫描(默认 2、最多 4),不占用搜索的共享线程池。 磁盘生产者与索引消费者分离;每批 256 项、有界批次队列提供背压,磁盘线程不持有搜索索引锁。 普通扫描优先桌面、文档、下载目录,索引按短批次更新;复用父目录字符串和滚动字元组,减少每文件对象分配。 文件监测负责新增、删除、移动及修改,溢出或定期校准时重新扫描。 监测事件使用容量为 1 的合并唤醒通道,实际变更单独排队;重复通知不再依赖抛出/捕获 SemaphoreFullException。 可在面板里限定文件夹范围或重新扫描。回退扫描不会请求管理员权限,无法访问的目录会跳过。

有效缓存启动时不再立即全盘校准:先恢复缓存并开始监听新变更,默认延后 2 分钟进行低优先级校准,之后仍每 15 分钟校准。 程序关闭期间的新增、移动、删除可能在校准前暂未反映,可按 F5/“重新扫描”立即校准。 状态文字区分“恢复索引”“首次建立”“本地缓存”和“后台校准”,后台校准不会清空已有搜索结果。

实验性 FileIndexOptions.EnableNtfsWarmup 默认关闭:Windows NTFS 整卷范围在已有权限允许时可用只读 FSCTL_ENUM_USN_DATA 批量预热主文件名,按父目录 ACL 过滤。 它不会申请 UAC、安装服务、启用特权或更改 USN 日志;无权限/不支持时自动使用普通扫描。 MFT 主名称不能覆盖所有硬链接别名,后续目录校准仍必须完成,预热结束不等于完整索引结束。 由于预热后仍需普通目录验证,会增加完整首扫工作量;在没有原生后端真实整盘对照数据前,不默认启用,也不能宣称已经达到 Everything 的完整首扫速度。 参考:微软 FSCTL_ENUM_USN_DATA、 Everything 的服务与权限要求。

输入 行为
项目 2026 同时包含两个关键词,文件名或路径,不区分大小写
"项目 计划" 完整短语
*.pdf / 报告?.* 任意字符串 / 任意单字符
report[0-9].txt / [!abc]* 字符范围 / 排除字符集合
*.png \| *.jpg 任一条件
报告 !临时 包含“报告”,排除“临时”
ext:cs;json 配置 扩展名筛选,分号表示任选一个
file: / folder: 只找文件 / 文件夹
path:C:\Projects\**\*.cs 路径筛选,** 可跨目录层级

正文搜索为可选项。首次勾选后建立 SQLite FTS5 trigram 持久索引,并在文件变化后增量更新。 支持常见文本和源代码,UTF-8 或带 BOM 的 UTF-16/UTF-32,单文件最大 8 MiB。 二进制、PDF/Office 等非文本格式、离线占位符和超限文件不参与正文检索。 正文索引只保存在本机,不向服务器发送路径或内容;取消勾选会停止当前正文索引任务。 三字以上关键词使用全文索引缩小候选,中文短词从缓存文本校验,不重新读取原文件。

自动化检查

dotnet run --project XFEToolBox.Test -c Release -- --artifacts .BuildValidation/final-independent-index-core-release
dotnet run --project XFEToolBox.Client.Wpf.Test -c Release -- --artifacts .BuildValidation/final-independent-index-wpf-release
dotnet run --project tests/Indexing.Validation -c Release
dotnet run --project tests/IndexingService.Validation -c Release
dotnet publish XFEToolBox/XFEToolBox.Client.csproj -p:PublishProfile=AOTProfile -o .BuildValidation/final-independent-index-client-release

核心测试覆盖通配符与组合筛选、中文、候选集与直接匹配的一致性、分页/取消、大目录查询、缓存恢复、移动/删除目录、文件监听,以及正文编码、修改、分页和内容缓存。 服务测试覆盖首次枚举期间日志回放、持久缓存重启不再枚举、日志失效单卷重建、硬链接/目录改名、坏卷隔离及慢速原生 I/O 不阻塞启动和搜索。 安全测试覆盖实际管道权限、假冒服务拒绝、模拟身份、祖先 ACL、深处授权候选完整性、断开查询静默取消及安装源文件验证;不会触发 UAC 或注册服务。 WPF 回归覆盖服务/回退切换、正文仍以普通用户读取、整框焦点与不获取焦点的清空按钮,以及完整主题中 Hint/光标左边缘和垂直位置一致。 性能回归覆盖百万条目构建期间查询与取消、慢速输入枚举不持有索引锁、不变条目复用、批量清理、并行目录扫描和损坏缓存回滚。 通知回归监测 first-chance 异常:并发突发通知及关闭后迟到通知不得产生满信号量/已释放异常,突发新增、删除及空闲后唤醒仍完整更新索引。 冷启动回归覆盖有效缓存不立即扫描、手动校准离线变更、专用低优先级线程与取消,以及 NTFS v2/v3 记录解析、ACL 祖先链、目录链接/循环/坏数据。 界面回归覆盖默认第一栏、第二栏工具结果、连续输入取消过期搜索、正文开关和隐藏窗口后的取消, 以及取消清理不阻塞 UI、25 万条缓存恢复完成前即可查询已恢复的条目。

前轮 Release 对照(仅用于回归对比,不代表完整磁盘的耗时):

  • 32,768 个实际文件、256 个目录的热缓存扫描及保存:463 ms → 309 ms。
  • 百万条合成路径的索引构建:3,383 ms → 1,861 ms;累计分配约 3,676 MB → 716 MB。
  • 完整 WPF 主题、百万条缓存:首批结果约 0.44 秒进入列表(含 120 ms 输入防抖); 后台恢复及失效条目校准约 5.8 秒,UI 心跳最大间隔 77.1 ms,无 Dispatcher 异常。

本轮进一步优化后的 Release 测量(OS 文件缓存未清空,非真实整盘首次读取):

  • 相同规模 32,768 个实际文件样本:扫描及缓存保存约 181 ms(前轮约 309 ms),首批结果约 40 ms,并发查询最大约 10 ms。
  • 百万条合成路径,直接子项共享父路径工厂:构建约 1,946 → 1,462 ms,累计分配约 708.5 → 560.1 MB。
  • 百万条合成路径,构建时并发查询最大约 60.1 → 16.7 ms;* 宽查询约 318 → 64.5 ms。
  • 8,192 个实际文件、128 个目录、真实 WPF Dispatcher 两轮:扫描及保存 ≤45.5/88.0 ms,搜索最大18.0/20.6 ms,输入心跳最大间隔30.0/35.5 ms;小样本存在 OS/其他任务调度波动。
  • 连续宽查询使用清引用归还的 ArrayPool 候选快照,避免每次按键分配完整大数组;已返回结果不借用缓冲区。

物理文件性能基准为显式测试 FileIndexSingleRootRemainsSearchableDuringScanAndCacheHydration,默认回归不创建大量文件。 新增显式 ColdScanResponsivenessTests.ColdDirectoryScanKeepsDispatcherAndSearchResponsive:8,192 个物理文件、真实 WPF 输入心跳及并发查询,准备文件不计入扫描计时。

手动检查:首次索引、缓存启动、禁用/启用热键、中文与长路径、不同 DPI 屏幕居中,双击/回车打开、右键定位与复制路径;在大量文件索引期间检查输入和其他页面响应。

快速搜索窗口交互

  • 顶部空白区域可拖动窗口;搜索框、清空按钮、页签、结果和滚动条不参与拖动,窗口不保持置顶。
  • Ctrl+滚轮 在 70%–160% 之间缩放结果文字和文件图标,Ctrl+0 恢复 100%;普通滚轮继续滚动,列表维持回收式虚拟化。
  • 文件图标由独立低优先级 STA 工作者读取 Windows Shell,只有可见结果请求图标,程序/快捷方式按实际路径读取;有界队列和缓存避免拖慢输入。
  • 快捷键或托盘再次打开时保留未清空的搜索内容;只有显式新查询覆盖它。最后一项查询以单个 JSON 字符串保存在 %LocalAppData%\XFEToolBox\CrossVersion\FileSearch\last-query.json,不记录历史。点击清空后重启也保持为空。
  • 查询状态的读取、250 ms 合并保存和原子替换均在后台完成;迟到的恢复不能覆盖键入、显式清空或已关闭的窗口。正常退出异步等待最后一次保存,上限 2 秒。
  • 三处搜索菜单使用独立浅紫圆角边框模板,不绘制外部阴影;透明 Popup 保留圆角,顶部和底部各留 7 DIP 间距。
  • QuickSearchInteractionTests、QuickSearchQueryMemoryTests、QuickSearchContextMenuTests 覆盖上述窗口交互、恢复竞争和菜单真实模板/像素;QuickSearchViewBehaviorTests 验证连续输入取消、UI 心跳、集合/图标复用和缩放后的虚拟化。