SnapDiff

SnapDiff 是一个 Windows 优先的本地目录快照工具，用来查看同一个文件夹在不同时间点之间发生了哪些变化。

它递归记录目录结构、文件大小、修改时间和 MD5，比较后展示新增、删除、修改，以及疑似移动或重命名的文件。适合检查游戏 Mod、项目目录或其他文件夹的变化。

快照只保存元数据和哈希，不保存文件内容，不提供备份或恢复。所有扫描由用户手动发起，程序不会自动监控目录，也没有云同步或账户系统。

使用方法

1. 创建快照：点击首页的“创建快照”并选择文件夹，也可以直接把一个文件夹拖入首页。填写可选的忽略规则后，点击“开始扫描并保存”。名称自动取自文件夹，无需填写。
2. 检查变化：进入目录页面，点击“检查变化”，重新扫描并与历史基准比较。这一步只更新当前扫描状态，不会新增历史快照。
3. 更新快照：点击对应目录的“更新”或目录页面的“更新快照”，重新扫描并保存一个新的历史节点，同时将它设为默认比较基准。
4. 比较历史：点击目录卡片上的“比较”打开历史窗口，或在目录页面更换比较基准和对照状态，可以比较历史与当前扫描状态，也可以比较两个历史节点。

结果支持状态筛选、文件名或路径搜索、目录树浏览、查看旧值和新值、复制路径及导出文字报告。历史节点可以添加备注、批量导出或删除；目录设置中可以配置忽略规则、重点关注规则和历史保留数量。

同一个目录不能重复创建，后续记录请使用“更新”。不同路径下的同名文件夹可以分别管理。页面中的“当前状态”指上次成功扫描的结果，并不是实时状态。

数据库位置

安装 EXE 安装包时，可以选择系统应用数据目录、安装目录下的 data 文件夹，或自选文件夹。安装时的选择在首次启动时生效；已有位置配置会保留，升级或重装不会自动迁移原库。MSI 安装包沿用系统默认位置，也可以安装后在应用中迁移。

已安装的应用点击右上角 数据库位置，选择目标文件夹，再点击 迁移数据库 并确认。迁移包含全部目录记录、历史快照、当前扫描状态、规则、备注和活动记录。完成校验并保存位置配置后立即切换，随后清理旧数据库，无需重新扫描。迁移过程中不允许扫描或修改记录；失败时继续使用原库。

目标文件夹须可写，且不能位于已管理的扫描目录内。目标已有 snapdiff.sqlite3 或其日志文件时会拒绝覆盖，请选择其他文件夹。安装在 Program Files 等受保护位置时，普通用户可能无法写入安装目录，建议选择系统应用数据目录或其他可写文件夹。数据库所在目录及其父目录也不能作为扫描目标。

数据库位置配置保存在 Tauri 的应用配置目录中的 database-location.json，窗口配置仍单独保存。自选位置无法访问或数据库丢失时，程序会显示错误，不会创建空库冒充原数据；重新接入原磁盘后再启动。卸载不删除数据库，目录中的历史旧版 JSON 也不会因迁移被删除。

忽略规则

可以在创建弹窗或目录设置中填写规则，每行一条；也可以在要扫描的目录根部创建 .snapshotignore：

# 忽略日志和临时目录
*.log
cache/
temp/
shadercache/

# 只忽略根目录下的 build
/build/

# 重新纳入某个文件
!cache/keep.txt

支持通配符、目录规则、根目录锚定和 ! 例外。根目录的 .snapshotignore 先读取，界面中的额外规则后读取，后匹配的规则优先；忽略文件自身不会进入快照。不读取各子目录自己的忽略文件。

技术栈

• Rust：目录扫描、分块计算 MD5、快照比较、查询和导入导出。
• Tauri 2：桌面窗口、原生文件选择器，以及前后端通信。
• SQLite / rusqlite：本地保存目录记录、历史快照和扫描活动。
• HTML、CSS、原生 JavaScript：界面展示，无前端框架或打包步骤。
• Node.js、JSDOM：开发工具和前端交互测试，不参与正式程序的数据处理。

主要代码位于 frontend/ 和 src-tauri/src/；测试位于 tests/ 及 Rust 模块中。面向 AI 开发者的详细约束见 AGENTS.md。

调试与构建

Windows 开发环境需要：

• Rust 稳定版，使用 MSVC 工具链。
• Node.js 当前 LTS 版本及 npm。
• Visual Studio Build Tools，安装“使用 C++ 的桌面开发”和 Windows SDK。
• Microsoft Edge WebView2 Runtime。

以下命令都在项目根目录运行。

安装依赖并启动开发模式：

npm ci
npm run tauri dev

前端是静态文件，Tauri 直接加载 frontend/，无需执行单独的前端构建命令。只查看界面布局时，可以启动演示预览：

node tests/preview.cjs

然后访问 http://127.0.0.1:47831。预览使用演示数据，不会扫描真实目录，也不能代替 Tauri 原生功能测试。

运行测试和代码检查：

cargo test --lib
npm test
cargo clippy --all-targets -- -D warnings
cargo fmt --all --check

构建正式程序和安装包：

npm run tauri build

Windows 构建产物通常位于：

target/release/snapdiff.exe
target/release/bundle/nsis/SnapDiff_<版本>_x64-setup.exe
target/release/bundle/msi/SnapDiff_<版本>_x64_en-US.msi

其他说明

• 数据默认保存在系统应用数据目录中的 snapdiff.sqlite3，可在“数据库位置”中迁移，不写入被扫描的文件夹。导入和导出使用 JSON，只包含快照元数据及相关设置。
• 删除快照或移除目录记录不会删除源文件。源目录暂时不可访问时，仍可比较已保存的历史节点。
• 扫描在 Rust 后台执行，上方显示按总字节数计算的总进度，下方显示当前文件的 MD5 进度；没有可读取字节时按已处理项数显示。读取目录、计算差异和提交阶段显示进行中动画。扫描支持取消；最终提交阶段会显示“正在完成”，此时不能取消。取消或扫描失败不会保存不完整的快照。
• MD5 需要读取文件内容，大目录耗时取决于数据量和磁盘速度。扫描期间尽量避免其他程序修改目录；底层读取阻塞时，取消需要等待该次读取返回。
• 符号链接和 Windows 重解析点不跟随扫描；“疑似移动”依据大小和 MD5 匹配推断，不能证明文件实际发生过移动。
• 窗口会记住上次关闭时的大小、位置和最大化状态，并在下次显示前恢复。