Photo Cull

Photo Cull 是一个 Windows 优先、键盘优先、文件夹优先 的本地照片筛选工具。

它的目标不是做大而全的相册管理器，而是把照片整理变成一条连续、低干扰、可撤销的单张决策流：打开文件夹，快速判断当前照片，删除、收藏、归类，然后自动进入下一张。

当前版本：1.0.0

界面预览

1.0 已实现

• 直接打开本地文件夹，不需要导入照片库。
• 扫描常见 RAW / JPEG / PNG / WebP / XMP 文件。
• 按同名文件自动合并 RAW + JPG + XMP 为一张逻辑照片。
• 自动过滤 macOS / exFAT 常见的 ._*、.__* 隐藏辅助文件。
• 有 JPG 时优先用 JPG 做快速预览。
• 暗色沉浸式整理流：左侧筛选、中央大图、右侧相册目标、底部快捷操作。
• 方向键切换照片。
• Delete / Backspace 先放入待删除队列，不直接物理删除。
• 待删除队列支持单选、全选、清空选择、删除到 Windows 回收站。
• F 收藏当前照片。
• 支持多个目标相册文件夹。
• 数字键 1-9 可快速归类到右侧第 1-9 个相册。
• 目标相册支持自定义 Alt+数字/字母 快捷键。
• D 移动到当前目标相册。
• 移动、收藏、待删除后自动跳到下一张照片。
• Ctrl+Z 撤销最近一次可恢复操作。
• 缩略图网格使用虚拟滚动，只渲染当前屏幕附近的照片。
• Rust 后端生成 420px 缩略图缓存，避免网格直接加载原始大图。
• 无边框 Windows 窗口，支持拖动、最小化、最大化、关闭。
• 自定义应用图标。

操作流程

常用整理方式：

1. 点击 打开文件夹，选择照片目录。
2. 在整理流中用 ← / → 浏览照片。
3. 按 Delete 把废片放入待删除队列。
4. 按 F 收藏重要照片。
5. 在右侧添加一个或多个相册目标文件夹。
6. 按数字键 1-9 快速移动当前照片到对应相册。
7. 进入 待删除 后，选择照片并点击 删除到回收站。

快捷键

动作	快捷键
上一张 / 下一张	← / →
整理流 / 缩略图切换	Space
返回缩略图	G
放入待删除	Delete / Backspace / X
收藏 / 取消收藏	F
移动到当前目标相册	D
移动到第 1-9 个相册	1-9
自定义目标快捷键	Alt+1 到 Alt+9、Alt+A 等
待删除队列全选	Ctrl+A
撤销	Ctrl+Z

文件配对规则

Photo Cull 按文件名 stem 忽略大小写配对。例如：

_ANA2404.JPG
_ANA2404.RW2
_ANA2404.XMP

会被视为同一张逻辑照片。移动或删除时，会尽量把配对文件一起处理。

当前策略：

• JPG / JPEG / PNG / WebP 用作可显示预览。
• RAW 文件参与配对和移动。
• 只有 RAW、没有 JPG 时，会显示 RAW 占位。
• RAW 内嵌 JPEG 提取还未做，这是后续重点。

高性能策略

1. 扫描阶段过滤无效文件
   跳过 ._* / .__* 隐藏辅助文件和 Windows Hidden 文件，避免把系统辅助文件当作照片。

2. 缩略图缓存
   网格不直接显示原始大图，而是由 Rust 后端生成 420px JPEG 缩略图，并缓存到系统临时目录。

3. 虚拟滚动
   即使目录里有数百上千张照片，前端也只渲染当前屏幕附近的卡片，降低 WebView 压力。

4. 后台解码
   缩略图生成放在后台线程里，避免卡住窗口主线程。

第一次打开大目录时需要生成缩略图缓存，会逐步显示；再次打开同一批照片会明显更快。

开发环境

需要：

• Node.js
• Rust / Cargo
• Windows WebView2
• Visual Studio C++ Build Tools 或 Visual Studio Community

安装依赖：

npm install

如果当前终端找不到 cargo，先补 PATH：

$env:PATH="$env:USERPROFILE\.cargo\bin;$env:PATH"

前端浏览器预览：

npm run dev -- --host 127.0.0.1

浏览器预览模式只适合看 UI，不能访问真实文件系统。

桌面开发模式：

$env:PATH="$env:USERPROFILE\.cargo\bin;$env:PATH"
npm run tauri:dev

类型检查：

npm run typecheck

前端构建：

npm run build

Rust 检查：

cd src-tauri
$env:PATH="$env:USERPROFILE\.cargo\bin;$env:PATH"
cargo check

构建 Windows release exe：

$env:PATH="$env:USERPROFILE\.cargo\bin;$env:PATH"
npm run tauri -- build --no-bundle

构建结果：

src-tauri/target/release/photo-cull.exe

1.0 验证状态

本地已验证：

• npm run typecheck
• npm run build
• cargo check
• npm run tauri -- build --no-bundle

目前限制

• 暂未持久化评分、待删除状态和筛选会话。
• 暂未写入 XMP sidecar。
• 暂未提取 RAW 内嵌 JPEG。
• 暂未做安装包签名。
• macOS 版本还未适配和打包。

后续路线

• SQLite 保存会话、评分、待删除状态、移动历史和撤销日志。
• XMP sidecar 读写，与 Lightroom / Bridge / digiKam 等工具互通。
• RAW 内嵌 JPEG 提取，提高无 JPG 场景的预览速度。
• 更成熟的缩略图缓存索引和清理策略。
• Windows 安装包和自动更新。
• macOS 版本。

设计原则

• 文件操作必须由 Rust 核心统一处理。
• 前端不直接拼路径、不直接移动或删除照片。
• 删除默认先进待删除队列，物理删除必须显式确认并进入回收站。
• 键盘操作优先。
• 本地优先，默认离线。
• 云同步和 AI 选片都不是 1.0 的基础能力。