CarolZ1 File Organizer — 文件整理
概述 / Overview
本技能帮用户维护清晰、合理的文件结构，降低手动整理的认知负担。核心动作：分析结构、查重、建议分类方案、在确认后执行移动/重命名/清理。
设计原则是安全优先：先只读扫描出报告，任何改动都要明确确认，删除一律走回收站、绝不永久删除，改动前先备份，每次只动一小批。
何时使用 / When to Use
- Downloads 文件夹乱成一团
- 文件散落各处找不到
- 重复文件占用空间
- 文件夹结构不合理，想重新规划
- 新项目需要一套合理目录结构
- 归档旧项目前想先整理
- 「帮我整理桌面 / 下载文件夹」「找重复文件」「清理 6 个月没动的旧文件」
安全护栏 / Safety Guardrails（硬规则，不可绕过）
以下规则任何情况下都必须遵守，优先级高于整理效率：
- 只读优先：任何整理请求，第一步永远是只读扫描 + 生成报告，不动任何文件。即使原话是「直接清理」，第一轮也只扫描。
- 明确范围：动手前必须确认——目标目录、涉及的文件类型、整理/删除标准、排除项（如当前项目、敏感数据）。
- No-Go 区域：绝不递归删除/清空 Desktop、Downloads、Documents、Home、系统目录（
/、C:\、AppData、Library、~/.config）。*绝不**用rm -rf、del /S /Q、shutil.rmtree、`.tmp/*.log` 等通配符批量删除。用户坚持也要拒绝。 - 删除 = 回收站：用系统回收站（Windows 回收站 API / macOS
trash或osascript/ Linuxgio trash或trash-put），永不永久删除。回收站不可用时，警告并要求二次确认。 - 备份优先：移动/重命名/删除前，先备份（
cp -r/robocopy），确认备份成功并告知位置。 - 小批次：每次最多 10 个文件，做完立即验证，失败立刻停止。
- 明确确认：执行前列出每一个受影响文件路径 + 具体风险，用户确认后才执行。
- Windows 不写脚本文件：中文路径不用
.ps1/.bat写文件（编码会乱码），改用直接命令调用。
工作流程 / Workflow
第 1 步：理解范围（Ask First）
先问清（一次问一个关键问题）：
- 目标目录？（Downloads / Documents / 桌面 / 整个 Home）
- 主要问题？（找不到东西 / 重复 / 太乱 / 没结构）
- 要避开哪些？（当前项目 / 敏感数据）
- 整理力度？（保守 / 彻底）
第 2 步：只读分析（Scan, Read-Only）
只读扫描目标目录，产出报告：
# macOS / Linux
ls -la "目标目录"
find "目标目录" -type f | wc -l
du -sh "目标目录"/*
find "目标目录" -type f -exec file {} \; | head -20
# Windows PowerShell
Get-ChildItem "目标目录" -Force | Select-Object Mode,Length,LastWriteTime,Name
(Get-ChildItem "目标目录" -Recurse -File).Count
Get-ChildItem "目标目录" -File | Group-Object Extension | Sort-Object Count -Descending
汇总：文件/文件夹总数、类型分布、大小分布、日期范围、明显的结构问题。
第 3 步：查重（只读）
用自带脚本做确定性查重（只读，不删任何文件）：
python scripts/scan_duplicates.py "目标目录" --recursive --json duplicates.json
它会输出：完全重复组（按 SHA-256 哈希）、同名文件组、相似大小文件组，并给出「建议保留哪个」（通常保留最新或命名最清晰的），但绝不自动删除。
第 4 步：提案（Propose，不执行）
先呈现完整方案，等确认：
整理方案：目标目录
当前状态：X 个文件 / Y 个文件夹 / Z 大小
类型分布：...
问题：...
建议结构：
目标目录/
├── Work/（Projects、Documents、Archive）
├── Personal/（Photos、Documents、Media）
└── Downloads/（To-Sort、Archive）
将执行：
创建文件夹：[列表]
移动：X 个 PDF → Work/Documents；Y 张图 → Personal/Photos；Z 个旧文件 → Archive
重命名：[规则]
删除（回收站）：[重复/垃圾文件，逐个列出]
需你决定：[拿不准的文件]
第 5 步：执行（Confirmed, Batched）
用户确认后，才动手；遵守安全护栏：先备份、走回收站、每次 ≤10 个、逐批验证、失败即停。
跨平台命令对照 / Cross-Platform Commands
| 操作 | macOS / Linux | Windows PowerShell |
|---|---|---|
| 列出结构 | ls -la |
Get-ChildItem -Force |
| 统计文件数 | `find . -type f | wc -l` |
| 按类型统计 | `find . -type f | sed 's/.*.//' |
| 按大小排序 | `du -sh * | sort -rh` |
| 移入回收站 | gio trash / trash-put / osascript |
回收站 API（勿用 Remove-Item -Confirm 永久删） |
| 备份 | cp -r |
robocopy /E |
| 移动文件 | mv |
Move-Item |
| 查重 | scripts/scan_duplicates.py（跨平台） |
同左 |
环境与降级 / Environment & Fallback
| 状态 | 动作 |
|---|---|
| 有 Python 3 | 用 scripts/scan_duplicates.py 做查重（推荐，跨平台一致） |
| 无 Python | 用 find/Get-ChildItem + md5/Get-FileHash 手工查重，结果标注「未用脚本，可能不精确」 |
| 回收站不可用 | 只生成整理/删除清单，不执行删除，等用户提供回收站方案或明确二次确认 |
核心规则 / Rules
- 安全护栏（上方 8 条）优先于一切整理目标。
- 永远先报告、后执行；报告阶段零改动。
- 删除只进回收站；不永久删除、不静默删除、不通配符批量删。
- 每次只动一小批，验证后继续。
- 拿不准的文件列入「需你决定」，不擅自处理。
参考文件 / Reference Files
| 文件 | 何时读 |
|---|---|
scripts/scan_duplicates.py |
查重时运行（只读，输出报告） |
来源与许可 / Source & License
本技能为原创重写，参考了公开的「文件整理」技能的工作思路（分类、查重、清理），但规则、流程与脚本均为重新设计，强化了跨平台兼容与安全护栏。查重脚本为原创确定性实现。