photo-dedup

Photo Dedup — 从重复照片中查找并挑选唯一照片

当用户想要对照片去重、从大量照片中找出唯一图像、删除相似或重复照片，或按唯一性整理照片时，可使用本技能。触发短语包括：“dedup photos”“find duplicate photos”“unique photos”“remove duplicate images”“photo dedup”“/photo-dedup”。

概述

本技能处理一个照片文件夹（通常是来自学校摄影等活动产生的数百张照片），使用感知哈希识别重复和近似重复的照片，并将它们整理为唯一与重复两类文件夹。它面向的工作流是：输入约 500 张照片，但其中只有约 100 张真正唯一。

工作原理

感知哈希 — 每张图像被转换为表示其视觉内容的感知哈希（pHash）。即使图像在分辨率、压缩或轻微编辑上存在差异，外观相似的图像也会产生相似的哈希。

聚类 — 图像按哈希相似度分组。每个聚类代表一个“场景”或“镜头”。每个聚类中最佳图像（文件体积最大 = 质量最高）被选为唯一代表。

输出 — 唯一照片被复制到 unique/ 文件夹。同时生成报告，显示找到多少重复照片以及聚类分组情况。

使用方式

基本用法 — 对文件夹去重：

/photo-dedup ~/Photos/school-event/

自定义阈值：

/photo-dedup ~/Photos/school-event/ --threshold 8

阈值控制相似度敏感度（默认：6，范围 0-20）。数值越低 = 匹配越严格，数值越高 = 分组越激进。

预览模式（不复制文件）：

/photo-dedup ~/Photos/school-event/ --preview

工作流程

当用户调用本技能时：

验证输入 — 确认源文件夹存在且包含图像

如需要则安装依赖 — pip3 install Pillow imagehash pillow-heif

运行去重扫描：

python3 ~/.claude/skills/photo-dedup/scripts/dedup.py <source_folder> --preview [--threshold N]

向用户报告结果（总数、唯一数、重复数）

启动审阅服务器（本地运行，自动打开浏览器）：

python3 ~/.claude/skills/photo-dedup/scripts/review_server.py /tmp/dedup_report_<folder_name>.json --output ~/Desktop/selected_photos &

随后用户可以：

并排查看所有重复组（Notion 风格 UI）

点击选择每组中要保留哪张照片

使用“Auto-select best”一键采用默认选择

点击“Save selected” — 照片立即被复制，无需终端

用户保存后，告知其所选照片的位置

完成后关闭服务器：kill $(pgrep -f review_server)

审阅服务器是一个轻量级本地 HTTP 服务器 — 无需安装、无需配置，只需 Python。非技术用户只需与浏览器交互，一键即可保存。

输出结构

~/Desktop/selected_photos/ ← 用户所选照片（副本，原始文件不受影响） /tmp/dedup_report_*.json ← 聚类报告 （原始照片绝不会被修改或删除）

重要说明

非破坏性 — 原始照片绝不会被移动或删除。唯一照片被复制到子文件夹。

支持格式 — JPG、JPEG、PNG、HEIC、WEBP、TIFF、BMP

性能 — 在现代硬件上可在一分钟内处理 500 张以上照片

选择标准 — 发现重复时，选择文件体积最大（质量最高）的一张作为代表