重复文件安全清理

概述

重复文件/照片安全清理（支付宝 AI 按量付费版）

在本地磁盘或移动硬盘上识别字节级完全一致的文件，生成核对清单，把多余副本移入独立目录，并保留可逐条恢复的清单。核心不是"删得多"，而是判断准、动得安全、随时能还原。

本技能已由支付宝官方 AI 按量付费（402 协议） 改造：对外提供 POST /api/cleanup/scan 计费接口，由平台/调用方按次支付后获取"重复分析报告"资源；本地 CLI 工具（扫描/移动/清单）逻辑完全保留。

计费口径（SkillPay 上架专项 · P6）

• 计费模式：按调用量计费（按次）。
• 单价：0.10 元/次（CNY）。三处单价必须一致：本 SKILL.md 声明价、支付平台登记单价、上架表单标价。
• 单次交付边界：每一笔成功付款（同一 Payment-Proof）对应一次只读扫描分析报告交付；同一 Payment-Proof 重试幂等，不重复计费、不重复生成。报告仅含重复组/文件清单与字节级哈希，不含任何删除/移动动作。
• 免费额度：扫描脚本（scripts/scan_duplicates.py）本身可在本地免费直接运行；付费接口只是把"云端/远程调用式扫描"包装为可计量资源。

何时使用

• 用户提到：重复文件、去重、清理硬盘、C/E/F 盘太满、移动硬盘整理、照片重复、备份冗余
• 用户想比较两个目录（或整个盘）里内容相同的文件
• 用户想清理手机/电脑多次备份产生的冗余照片、视频
• 用户/平台希望通过按量付费接口远程调用本能力

工作流程（严格按序执行）

第 0 步：摸清范围，别急着扫

先确认目录结构与规模，不要对未知大目录直接跑全量扫描：

powershell -c "Get-ChildItem -Path 'E:' -Directory | ForEach-Object { '{0}: {1}' -f $_.Name, (Get-ChildItem $_.FullName -Recurse -File -ErrorAction SilentlyContinue).Count }"

规模决定策略：< 1 万文件直接全量扫；1–10 万按目录分批；> 10 万必须先排除噪声并优先处理用户最关心的目录。

第 1 步：只读扫描

python -u scripts/scan_duplicates.py 
  --root "E:/照片" 
  --exclude-dir .thumbnails --exclude-prefix ._ 
  --workers 8 
  --out reports/photo.json

务必加载 references/safety-and-risk.md 的第三节，排除噪声项——在混用的移动硬盘上，._* 与 .thumbnails 常占 20%~30% 文件数，排除后遍历速度可提升一倍。

第 2 步：先判风险，再决定动不动

按 references/safety-and-risk.md 的第二节分级：

• A 类（用户照片/文档/下载的多份副本）→ 值得清理
• B 类（软件安装目录、聊天缓存缩略图、表情/UI 资源、node_modules、构建产物）→ 不要动
• C 类（证件/合同/财务单据）→ 交用户确认

若重复项全部落在 B 类，应如实说明"收益极低且存在程序风险，建议跳过"，而不是照单执行。

第 3 步：生成核对清单

python scripts/make_report.py --report reports/photo.json --out reports/photo_checklist.html

用 present_files 把 HTML 清单交给用户核对。清单按组展示「保留哪个 / 移出哪些」，并附目录与类型分布。

第 4 步：预演，再执行

# 预演
python scripts/move_duplicates.py --report reports/photo.json 
  --target "E:/_重复文件归档/待删除-照片" --dry-run
# 实际移动（只移不删，可回退）
python scripts/move_duplicates.py --report reports/photo.json 
  --target "E:/_重复文件归档/待删除-照片"

第 5 步：验证并汇报

核对目标目录实际文件数与清单条数是否一致。汇报时必须区分三个数字：重复组数 / 涉及文件总数 / 实际移出数。

按量付费接口（402 协议 · probe / pay / complete / ack 全链路）

本技能已完成支付宝 AI 按量付费改造，五项必需能力全部实现：

支付依赖包：aipay/ 目录即本技能的支付宝支付层（config.py 配置加载、core.py 402 主流程、gateway.py 网关调用与签名、crypto_utils.py RSA2 签名/验签、rsa_pure.py 纯 Python RSA 兜底、orders.py 订单库）。

调用时序

部署（pay_server.py 标准库零依赖 / server_flask.py）后，调用方流程（官方 AI 按量付费 402 新规范）：

1. 无 Payment-Proof 请求 POST /api/cleanup/scan → 服务端先调用支付宝预下单接口 alipay.aipay.agent.payment.precreate，返回 402 + 账单 body（含 out_trade_no、amount=0.10、currency=CNY、resource_id=/api/cleanup/scan、amt_pre_pay_id、pay_before），并在响应头 amtPaymentLink 返回预下单号。
2. 调用方完成付款拿到 Payment-Proof，用同一请求体 + Payment-Proof 重发。
3. 服务端调用 verify 验付 → 严格校验（active/金额/订单号/未重复履约）→ 运行只读扫描 → 返回 200 + 扫描报告 + Payment-Validation（履约回执）。
4. 同一 Payment-Proof 重试幂等，不重复计费。

请求体：{"target_path": "E:/照片备份", "mode": "duplicate_files", "dry_run": true}（mode 支持 duplicate_files / duplicate_photos；exclude_dirs / exclude_prefixes / min_size / workers 可选）。

安全边界：付费接口只做只读扫描并交付报告，绝不在接口内自动删除/移动文件；实际清理仍由本地人工确认后跑 move_duplicates.py（只移不删）。接口拒绝扫描个人敏感目录（Desktop/Downloads/Documents）与系统目录、整盘/整主目录根。

关键铁律

1. 第一轮只读，未确认不动文件
2. 只移不删，禁止 rm / del / rmtree
3. 每批写清单，保证可逆
4. 原件零改动
5. B 类风险项不处理，且要主动说明原因

资源

• scripts/scan_duplicates.py — 只读扫描（大小分组 → 4KB 头部 → 全量 MD5，多线程）
• scripts/move_duplicates.py — 安全移动（清单、分批、断点续传、dry-run）
• scripts/make_report.py — HTML 核对清单
• aipay/ — 支付宝 AI 按量付费支付层（402 协议封装，含纯 Python RSA 兜底）
• business/scan_runner.py — 原扫描脚本的桥接调用 + 敏感目录护栏
• pay_server.py / server_flask.py — 计费 HTTP 服务（零依赖 / Flask 可选）
• references/safety-and-risk.md — 安全规范与风险分级（执行前必读）
• README.md — 部署、沙箱联调、生产上线替换项、上线检查单