重复文件清理助手

磁盘上最容易被忽略的冗余

在长期运行的开发机、备份目录和素材库里，重复文件通常不会叫同一个名字。同一份设计稿可能被导出为 final.pdf、final (1).pdf 和按日期命名的副本；同一批照片可能同时存在于相机原始目录和后期处理目录。按文件名或目录归属判断是否重复并不可靠，真正需要确认的是文件内容是否完全一致。

duplicate-cleaner 面向这个具体问题：在一个或多个目录中找出内容完全相同的重复文件，并给出可恢复的清理路径。它只依赖 Python 3.8+ 标准库，无需 pip 安装第三方包。

四阶段扫描，先缩小范围再确认

扫描流程分为四个阶段：

1. 遍历采集：递归收集路径、大小和修改时间，并用 --min-size 过滤掉零碎小文件。
2. 按大小分组：大小不同的文件不可能内容重复，因此只保留同大小的候选。
3. 快速哈希：对候选文件计算前 1 MB 的 SHA256，快速排除大部分不同内容。
4. 完整哈希：仅对快速哈希仍冲突的文件计算完整 SHA256，形成最终重复组。

扫描本身是只读的。完成后会汇报扫描文件数、重复组数、重复项数、可释放空间，并用表格列出组号、文件大小、副本数量、路径和修改时间，便于先核对再行动。

清理必须经过预演和确认

删除流程被拆成显式步骤。先执行 --dry-run 预演，列出每组将要删除的文件和预计释放空间；只有把清单展示给用户并获得明确确认后，才进入真实清理。默认策略是 --keep newest，每组保留修改时间最新的一份；也可以选择 --keep oldest 保留最旧的一份。无论使用哪种策略，都保证每个重复组至少留下一份文件。

默认删除会送入回收站，因此误删后仍可恢复。只有在用户明确要求时，才使用 --permanent 永久删除，并且该操作强制搭配 --yes 二次确认。扫描系统盘时建议开启 --skip-system，避免触碰 Windows、Program Files、$RECYCLE.BIN 等系统或隐藏目录。

适用边界

它解决的是内容完全相同的字节级重复，不适合识别逻辑上的相似文档、图片缩略图或语义相近文件。目录权限异常、文件在扫描期间发生变化、回收站不可用等情况仍可能造成报告或清理结果不完整。对于重要数据，应把扫描报告当作审计结果，把预演清单当作删除依据，而不是让脚本自动删除。