> 文件夹清理·一键去重 — 越用越懂你这台机器 · 只整理不删除 · 可一键还原
用户还会怎么说（意思对就唤起）：「帮我清一下重复文件」「这个文件夹里有好多一样的」「磁盘空间不够了，看看哪些是重复的」「照片/素材库备份了好几份，帮我找出来」「找出内容一样但名字不一样的文件」「有没有长得差不多、但字节不一样的图片」「把照片按月份归类」。
为什么选它：
- 🛡️ 只整理不删除：重复副本安全移入暂存区，绝不物理删除，随时可还原
- 🧠 记忆层：跨会话记住你的暂存区位置、保留策略偏好，越用越顺
- ✅ 真实踩坑案例：2026-09-05 拦下一批含 272 个二进制文件的误打包事故
> 三条红线
> 1. 绝不删文件 —— 重复副本只移进暂存区，随时能还原；唯一会自动删的是「文件被移空后的空目录壳」。
> 2. 先看报告再动手 —— 扫描阶段只读、零改动；任何移动都必须你点头后才执行。
> 3. 相似图 ≠ 重复 —— phash 组（带 similar）成员字节并不相同，可能是你有意保留的原图/压缩版，移动前必须人工复核。
🚀 30 秒上手
你说：「帮我把 D 盘下载文件夹里的重复文件清一下」
- 扫重复（只读，零改动）：
python scripts/scan_dups.py --root "D:\下载" --mode smart --out groups.json
→发现 12 组重复，23 个副本可移，约可释放 1.8 GB - 汇报 + 确认：把数字念给你，问「移到暂存区（可还原）？还是先试点一个目录？」
- 你回「移」→ 执行：
python scripts/move_dups.py --groups groups.json --root "D:\下载" --trash "_已删除重复文件" --log delete_log.csv - 收尾校验：
python scripts/verify_restore.py --root "D:\下载" --trash "_已删除重复文件夹"→孤儿 0（没有唯一内容被误移）
> 全程绝不删文件；任何一步都能 Ctrl+C 停；重跑从断点续跑。
何时使用
- 用户说"清理重复文件""查重""整理重复照片/素材/下载/备份""释放磁盘空间"
- 需要将散落在多处（如
202309\与2023年\202309\）的同素材/同备份归集 - 任何需要安全、可还原地移除重复副本的场景
不适用（别硬用，会失望）：
- 只想看"哪些文件/文件夹最占地方" → 用磁盘空间分析工具更快，本技能只管内容重复。
- 想按画面内容（人脸、场景、语义主题）归类 → 本技能不读画面内容，只认字节内容与文件时间。
- 想直接删除腾空间 → 本技能设计上不删除，重复副本一律进可还原暂存区。
工作流
第 1 步：扫描（只读）
| 模式 | 原理 | 抓得到 | 速度 |
|---|---|---|---|
fast（默认） |
同名同大小预筛 → 内容哈希 | 同名同内容的重复 | 最快，但漏掉改名文件 |
smart（推荐） |
大小预筛 → 头尾各 1MB 抽样哈希 → 候选才全量 | 含不同名同内容 | 快，只对候选全量 |
full |
按大小预筛后全量哈希 | 全部字节级重复 | 最慢，慢盘慎用 |
phash |
感知哈希 + 汉明距离聚类 | 肉眼相同、字节不同的图片 | 中等，需 Pillow |
python scripts/scan_dups.py --root "F:\BOBO亚马逊" --mode smart --out groups.json
python scripts/scan_dups.py --root "F:\照片" --mode phash --threshold 4 --out similar.json
> fast 的漏洞已实测确认：a\x.txt、b\x.txt、c\y.txt 三份内容完全相同，fast 只抓到前两个（y.txt 因文件名不同在预筛阶段被丢掉）。除非只要最快粗筛，否则一律用 smart。
> phash 特殊性：抓"看起来一样"，成员间字节并不相同（组带 similar: true），移动前必须人工复核；--threshold 默认 4，调大易误抓、调小易漏。
第 2 步：报告规模并请用户确认
汇报重复组数、待移动副本数、可释放空间，询问策略：A 全量 / B 试点（先移一个目录验证）/ C 调保留策略（默认保留路径最短者）。
在用户明确确认前，不要移动任何文件。
第 3 步：执行（两种模式）
模式 A — 移动暂存（默认）：scripts/move_dups.py 把副本剪切到暂存文件夹（保留原目录结构，可还原）；整文件夹重复时自动移除源端空目录壳。
模式 B — 打包归档（零改盘） ⭐ 遇 Windows Defender 实时防护拦截导致卡死时改用：AI 全程不碰原文件，只把待删清单打成 .7z，由用户核对后手动删。→ 详见 workflow_detail.md
第 4 步：复核与收尾
- 模式 A：抽查源目录已无重复残留、暂存副本完整；由用户决定是否彻底删除暂存文件夹。
- 模式 B：核对归档无误后，由用户手动删除原文件再删归档。
> ⚠️ 平行文件夹部分重叠是最高危场景：移动后必须跑第 4 步的 verify_restore.py 做唯一内容完整性校验，确认孤儿为 0。详见 workflow_detail.md。
关键安全原则
- 绝不物理删除：一律移到可恢复暂存文件夹，禁用
shutil.rmtree/del/ 系统回收站（外置盘回收站机制已实测不安全）。 - 保留集防误删：移动前确认 keep 存在；keep 缺失则整组跳过。
- 同盘可还原：root 与 trash 尽量同卷——同盘剪切=改名，原子可还原；跨盘变复制+删除，慢且有中断风险。
- 大批量谨慎：先试点目录，确认无误再全量；始终保留完整 CSV 日志。
反模式（别这么干）
- ❌ 用
fast整理改名文件 —— 会漏掉「内容一样但名字不同」的副本，一律用smart。 - ❌
phash组不复核就移动 —— 成员字节各不相同，可能是有意保留的原图/压缩版/水印版。 - ❌ 移动完就当结束、不跑
verify_restore—— 平行文件夹重叠时会丢独有内容。 - ❌ root 和 trash 跨不同盘 —— 慢且有中断风险。
- ❌ 对信任目录用默认 keep —— 默认留路径最短那份，未必是你要的正本；用
--keep under:信任目录固化。 - ❌ 让 AI 擅自切换图片识别模型 —— 视觉确认前先问你手动切换。
❓ 常见问题速查
| 你可能想问 | 一句话答案 |
|---|---|
| 会不会把我的文件删了？ | 不会。全程只移动不删除；唯一自动删的是文件被移空后的空目录壳。 |
| 四个模式该用哪个？ | 日常用 smart；只要最快粗筛用 fast（会漏掉改过名的重复）；找同一张图的不同版本用 phash（移动前必须人工复核）。 |
| 扫到一半能停吗？ | 能。Ctrl+C 立即存盘，重跑同一条命令从断点续跑，不白算。 |
| 暂存区在哪、怎么还原？ | 默认在整理目录下 _已删除重复文件，保留原目录结构；直接从里面拖回原位置即可。 |
| 移动时被杀软卡住？ | 改用打包模式 pack_dups.py（只读、不改盘），你核对后手动删 → workflow_detail.md。 |
| 报错看不懂？ | 每个错误都直接打印「出什么事 + 怎么办」；完整清单见 error_codes.md。 |
> 完整 12 问见 references/faq.md。
📚 按需深入（不占上下文，用到再读）
| 文件 | 什么时候读 |
|---|---|
references/faq.md |
常见疑问 |
references/error_codes.md |
报错看不懂（E 字头错误码字典） |
references/workflow_detail.md |
执行细节：groups.json 格式、断点续跑、打包模式 B、孤儿校验、视觉确认、复盘沉淀 |
references/cli_reference.md |
全部脚本参数表 |
references/memory_layer.md |
记忆层：规则沉淀与偏好固化 |
references/organize_files.md |
第二个能力：把散落文件按 时间+类型 归并为 YYYYMM照片 等 |
references/reliability.md |
发布前自检：TRACE-R 达标项与边界输入处理 |
> 记忆层铁律：启动先跑 python scripts/state_helper.py rules 读已沉淀规则；结束后必写 history；用户每次纠正立刻 add-rule。详见 memory_layer.md。
