FlashDir v3.5.0

FlashDir v3.5.0 Release Notes

自 3.4.2 以来的累积更新，包含界面重构、扫描与检索性能专项、MCP 接入三部分。

新增功能

MCP（Model Context Protocol）接入

• 桌面端内置 MCP 端点，AI 客户端（Claude Desktop / Cursor 等）可直接查询本机磁盘；
  不新增可执行文件，MCP 为桌面端本体的运行模式。
• 两种接入方式：
  • HTTP（推荐）：http://127.0.0.1:47821/mcp?token=<本机令牌>；端口固定、令牌持久，
    配置长期有效，仅监听回环地址；
  • stdio：flashdir.exe --bridge；桌面端未运行时会自动启动并等待就绪。
• 13 个工具：search_files、scan_directory、list_directory、find_large_files、
  find_duplicates、analyze_dev_cache、list_snapshots、save_snapshot、
  compare_snapshots、disk_usage_trend、list_volumes、cache_stats、diagnostics。
• 工具均带 MCP 标准标注（readOnlyHint / destructiveHint / openWorldHint）；
  除 save_snapshot 外全部只读。
• 设置页可开关端点、修改端口（约 1 秒内生效，无需重启）；状态栏显示连接状态与最近调用。

界面（按“指挥台”方向重构）

• 布局：范围条（卷容量条、命令入口、设置、面板开关）／工具栏（前进后退、扫描控制、
  路径面包屑、过滤、列表·热图、导出）／常驻目录树／文件表／检查器／洞察坞／状态栏。
• 主题跟随系统，可切换并记忆；统一设计令牌（深、浅两套变量，3px 圆角，1px 分隔线）。
• 洞察坞：大文件、增长趋势、重复文件、快照对比、开发缓存（Ctrl+1..5）。
• 体积构成：squarified treemap（面积严格对应体积），以工具栏“热图”整屏展示。
• 目录树支持无限层级与键盘导航（↑ ↓ ← →、Enter、Home、End）。
• 命令面板（Ctrl+K）：文件搜索与命令同框，Tab 切换模式，Ctrl+Enter 打开完整结果。
• 搜索结果视图：命中总数、虚拟滚动、加载更多、导出 CSV（最多 5 万条）。
• 状态栏可解释：结果来源、USN 校验状态、索引规模、MCP 状态；非管理员时提供“以管理员重启”。

目录分析与快照

• 重复文件检测：体积分组 + 内容哈希，输出重复组与可回收空间。
• 开发缓存分析：识别 node_modules、target、包管理器缓存、构建产物等占用。
• 快照：保存、任意两份对比、“快照与当前”对比、基于快照序列的体积趋势。

命令行

• cli.exe --filter <EXPR>：与桌面端一致的过滤语义，便于脚本化。

性能（同一台机器、同一数据集测量）

场景	优化前	3.5.0
全量扫描 C:\Windows（约 30.5 万条，含缓存写入）	约 47 s	约 3.4 s
磁盘缓存命中（约 30.5 万条）	1.1–7.6 s	约 0.4–0.5 s
全量扫描 C:\Users（约 29 万条）	约 36 s	约 2.4 s
全局检索（114 万条，分桶命中）	12–27 ms	1.5–3 ms
全局检索（114 万条，海量命中）	448–706 ms	30–40 ms
目录聚合（40 万条）	约 114 ms	约 59 ms
桌面端常驻内存	0.9–1.5 GB	约 0.2–0.5 GB
磁盘缓存写入（约 30 万条）	约 42 s	约 0.9 s

主要手段：

1. MFT 读取与解析：记录号即数组下标（替代哈希表），解析使用 rayon 并行；
   路径构建改为父链 + 记忆化，O(n) 摊还。
2. 磁盘缓存：由“每条目一行 + 多索引”改为“每目录单行数据块”，数据块外置为文件，
   写入在后台线程完成。
3. 全局检索：改为每线程 top-K 堆归并，只复制最终结果；索引改为连续数组 +
   128 位路径哈希 + 首字符分桶，名称等字段按需派生。
4. USN 增量：按实测校准阈值（增量约 1.67 ms/条，全量扫描 2.4–3.5 s，阈值取 1200）。

修复

类别	内容
USN	FSCTL_READ_USN_JOURNAL 控制码错误；将 MaxUsn 误作当前位置导致检查点无效；增量窗口失效后未回退全量扫描而返回陈旧数据；目录改名后按当前名称解析路径导致遗漏改名前的删除记录；常驻记录未读取未命名 $DATA 大小导致体积为 0
检索	全局检索响应结构被前端当作数组使用，导致命令面板渲染失败；! 前缀否定未实现（被当作字面量匹配，结果恒为空）；过滤匹配绝对路径，扫描根目录时输入根名会命中全部条目
布局	骨架使用固定行数网格，进度条未渲染时行错位，导致状态栏不贴底、洞察坞下方留白；小屏 / 高 DPI / 云桌面环境下窗口高于工作区，底部内容被裁剪
缓存	扫描根目录时级联清空所有子目录缓存；冗余索引与格式化文本持久化；全量扫描前未清理陈旧条目
稳定性	IPC 异常或事件订阅失败导致模块加载中断、界面空白（现提供防护与可见错误提示）；被 MCP 拉起的桌面端继承客户端 stdio 管道导致客户端挂起

兼容性与注意事项

• 磁盘缓存格式变更（数据块外置、字段调整）：升级后首次扫描会重建缓存；
• 旧版本保存的快照可能无法读取（条目结构新增访问时间字段）；
• MCP 端点仅监听回环地址并使用本机令牌，面向本机客户端。

文件

文件	说明
FlashDir-3.5.0.exe	桌面端（内嵌前端资源；同时提供 MCP 模式）
FlashDir_CLI_3.5.0_x64.exe	命令行工具

• 便携版：下载后直接运行，无需安装；
• 建议以管理员身份运行，以启用 MFT 直读与 USN 增量；首次启动会在后台建立全局索引。

已知限制

• 非管理员模式回退为目录遍历，扫描速度显著降低，数据新鲜度依赖目录修改时间；
• Windows 可能关闭“最后访问时间”更新，界面会标注该列不可用并回退显示修改时间；
• MFT 直读与全局索引仅覆盖 NTFS 卷；不提供删除、移动等改动用户数据的操作；
• 快照保存在本地缓存库中并占用磁盘空间（单目录保留 50 份 / 30 天）。