super-file-manager

电脑文件管理技能 v2.0

统一的电脑文件管理工具，支持垃圾清理、文档分类、重复检测、自动备份和操作回撤。文件查找使用系统 find 命令即可，无需额外脚本。

跨平台原生支持: macOS / Linux / Windows（Python 3.6+，仅需标准库 + send2trash）

依赖

脚本清单

| 脚本 | 功能 | 状态 | |------|------|------| | scripts/scan_cleanup.py | 扫描垃圾文件生成清理建议清单 | 只读 | | scripts/classify_files.py | 文件分类方案预览（不执行移动） | 只读 | | scripts/find_duplicates.py | 基于内容的重复文件检测 | 只读 | | scripts/incremental_backup.py | 增量/全量文件夹备份 | 写入 | | scripts/move_with_log.py | 带操作日志的文件移动/删除 | 写入 | | scripts/rollback.py | 操作回撤工具 | 写入 |

安全红线（所有操作必须遵守）

绝对禁止

1. 禁止递归删除/清空桌面、下载、文档、Home、系统目录（/、C:\、/System、AppData、Library、~/.config） 2. 禁止使用 rm -rf、del /S /Q、shutil.rmtree() 或宽泛通配符（*.tmp、*.log）作用于上述目录 3. 禁止自动删除任何文件——所有删除/移动操作必须用户确认 4. 禁止修改文件内容——仅做读取、移动、复制操作 5. 禁止后台通知/弹窗/推送——仅在当前界面返回结构化结果

强制流程

1. 先扫描，后操作——所有操作先生成预览方案/清单，用户确认后再执行 2. 操作日志记录——所有移动/删除操作必须通过 scripts/move_with_log.py 执行，自动记录操作日志 3. 系统目录保护——以下目录默认加入保护白名单，禁止任何写入操作： - macOS/Linux：/System、/Library、/usr、/bin、/sbin、~/.config - Windows：C:\Windows、C:\Program Files、C:\Program Files (x86)、%USERPROFILE%\AppData 4. Trash 优先——删除操作使用 send2trash 库（跨平台统一回收站） 5. 小批量执行——每次最多操作 10 个文件，逐批确认 6. 结果报告——每项操作完成后输出清晰的结果报告（数量、路径、状态统计）+ 回撤指引

操作日志规范

所有文件移动/删除操作必须通过 scripts/move_with_log.py 执行，该脚本会自动记录 JSONL 格式操作日志：

# 移动文件（自动记录日志）
python3 scripts/move_with_log.py move <源文件> <目标路径> [--log-dir <日志目录>]
移到回收站（自动记录日志）
python3 scripts/move_with_log.py trash <文件> [--log-dir <日志目录>]
批量移动（文件列表格式：每行 source -> dest）
python3 scripts/move_with_log.py batch-move --files <文件列表路径> [--log-dir <日志目录>]

日志目录按平台自动选择：

日志格式（JSON Lines，路径含特殊字符时自动转义）：

{"action":"move","source":"/Users/xxx/Downloads/file.pdf","dest":"/Users/xxx/Downloads/文档/file.pdf","timestamp":"2026-04-03T00:30:00Z","status":"ok"}
{"action":"trash","source":"/Users/xxx/Downloads/old.dmg","dest":"trash","timestamp":"2026-04-03T00:30:01Z","status":"ok"}

操作完成后，必须在结果报告末尾附上回撤指引：

↩️ 如操作有误，可回复以下指令回撤：
「撤销本次所有操作」— 一键恢复所有文件到原位置
「撤销 <文件名>」— 单独恢复某个文件到原位置

模块决策表

| 用户意图 | 模块 | 说明 | |----------|------|------| | 清理垃圾/临时文件 | 模块1：垃圾清理 | 先扫描生成建议清单 | | 整理/分类文档 | 模块2：文档分类 | 先输出分类方案预览 | | 查找/删除重复文件 | 模块3：重复检测 | 内容级去重 | | 备份文件夹 | 模块4：自动备份 | 支持增量备份 | | 撤销之前操作 | 模块5：操作回撤 | 支持一键撤销或按文件撤销 |

模块1：垃圾清理

适用场景

脚本

python3 scripts/scan_cleanup.py <目标目录> [--days 90] [--min-size 100] [--installers] [--cache] [--max-depth N] [--max-files N]

| 参数 | 说明 | 默认值 | |------|------|--------| | --days N | 超过 N 天未修改才列入 | 90 | | --min-size N | 大文件最小 MB | 100 | | --installers | 同时扫描安装包 | 关 | | --cache | 同时扫描缓存目录 | 关 | | --max-depth N | 最大扫描深度 | 无限 | | --max-files N | 最大扫描文件数 | 50000 |

扫描范围

执行流程

输出格式

🗑️ 清理建议清单（共 N 项，预计释放 X MB）
| # | 文件路径 | 大小 | 最后修改 | 建议 |
|---|---------|------|---------|------|
| 1 | ~/Downloads/installer.dmg | 256MB | 2025-01-15 | 删除 |
| 2 | ~/Downloads/old-report.pdf | 45MB | 2025-10-01 | 保留 |
请确认要清理的文件编号（如：1,3,5 或 全部）：

模块2：文档分类整理

适用场景

脚本（预览）

python3 scripts/classify_files.py <目标目录> [--by type|project|date] [--depth N] [--max-files N]

| 参数 | 说明 | 默认值 | |------|------|--------| | --by type\|project\|date | 分类方式 | type | | --depth N | 扫描深度 | 1 | | --max-files N | 最大扫描文件数 | 50000 |

分类维度

执行流程

输出格式

📂 分类方案预览
目标目录：~/Documents
分类方式：type
├── 📄 分类方案:
│   📁 图片/ (23个文件, 156.3MB)
│   📁 文档/ (45个文件, 12.8MB)
│   📁 代码/ (12个文件, 2.1MB)
│
├── 📊 合计: 80 个文件, 171.2 MB
│
请确认是否按此方案整理？(确认/取消/修改)

模块3：智能文件查找

适用场景

检索条件

执行方式（Python 跨平台统一）

输出格式

🔍 搜索结果（共 N 个文件）
| # | 文件名 | 路径 | 大小 | 修改时间 | 类型 |
|---|-------|------|------|---------|------|
| 1 | report.pdf | ~/Documents/work/ | 2.3MB | 2026-03-15 | PDF |
需要打开或操作哪个文件？

模块4：重复文件检测

适用场景

脚本

python3 scripts/find_duplicates.py <目标目录> [--min-size 1] [--exclude .git] [--max-depth 20] [--max-files 50000]

| 参数 | 说明 | 默认值 | |------|------|--------| | --min-size N | 最小文件大小 KB | 1 | | --exclude

🔁 重复文件检测报告
重复组 1 (共 3 个文件, 5.2MB)：
  ✅ 保留: ~/Documents/photo.jpg (最新, 2026-03-20)
  ❌ 重复: ~/Downloads/photo_copy.jpg (2026-02-15)
  ❌ 重复: ~/Desktop/photo_backup.jpg (2026-01-10)
📊 共发现 N 组重复文件，预计可释放 X MB

python3 scripts/incremental_backup.py <源目录> <备份目标路径> [--full] [--exclude ] [--no-verify] [--quiet] [--max-files N] [--max-depth N]

✅ 备份完成报告
源目录：~/Documents/project
备份至：~/Backup/project/2026-04-03/
模式：增量备份
新增文件：12 个 (15.3 MB)
跳过文件：45 个（无修改）
校验：✅ 通过
备份耗时：3.2 秒

# 查看可用日志
python3 scripts/rollback.py list-logs [--log-dir <日志目录>]
查看日志详情
python3 scripts/rollback.py show --log <日志文件路径>
一键撤销所有操作
python3 scripts/rollback.py rollback-all --log <日志文件路径>
撤销单个文件
python3 scripts/rollback.py rollback-single --log <日志文件路径> --file <原文件路径>
按范围撤销
python3 scripts/rollback.py rollback-range --log <日志文件路径> --from <起始行号> --to <结束行号>

↩️ 开始撤销日志中的所有操作...
日志: ~/.cache/file_manager/logs/operations_20260403.jsonl
  ✅ 恢复: ~/Downloads/文档/report.pdf -> ~/Downloads/report.pdf
  ✅ 恢复: ~/Downloads/图片/photo.png -> ~/Downloads/photo.png
  ⏭️ 跳过: ~/Downloads/图片/screenshot.png (原位置已有文件)
  ✅ 恢复: 回收站/old.dmg -> ~/Downloads/old.dmg
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 撤销完成: 成功 3 | 跳过 1 | 失败 0 | 总计 4
🧹 检查并清理因撤销而变空的自动创建文件夹...
  🗑️ 已清理空目录: ~/Downloads/文档