folder-organizer

---
name: folder-organizer
description: >-
  整理任意乱文件夹的完整方法——先按内容查重删冗余、再真正读进文件内容搞懂每个文件是什么、
  然后给出归类建议并按用户认可的结构重排（可选：内容驱动重命名 + 版本迭代 diff + 知识图谱）。
  凡是用户说「帮我整理一下这个文件夹 / 桌面太乱了 / 收拾下 Downloads / 这堆文件归一下类 /
  有一堆重复和版本残留 / 帮我重命名一下 / 清一清 / declutter / organize this folder /
  clean up my desktop」，或者丢来一个塞满杂七杂八文件的目录要求收拾时，务必使用本 skill——
  即使用户只说「乱」「重复」「归类」而没说「整理」。也适用于照片/代码/文档/音视频/混合内容的目录。
  不用于单个文件的读取或格式转换（那用对应文件工具）、不用于代码仓库的重构（那是工程任务）。
---

# Folder Organizer · 任意文件夹整理

## 为什么需要方法，而不是直接动手

乱文件夹的价值往往很高、删错代价也很高。两条铁律定了整个流程：

1. **先搞懂，再动手。** 文件名会骗人——叫 `final` 的可能是草稿，叫 `report.html` 的可能是登录页。
   不读内容就归类/改名，一定会把东西归错、把人误导。所以「读内容」是独立且必做的一步。
2. **一切可逆。** 删除只走「移进暂存夹」，永远不硬删；每个破坏性动作前先给用户确认。
   用户随时能反悔，这是他敢让你动手的前提。

还有一条贯穿全程：**分类法是问出来/从内容推出来的，不是你内置的。**
同一堆文件，有人要按日期、有人按客户、有人按项目、有人按类型——先问清「组织轴」，别硬套一套结构。

## 适用与不适用

- ✅ 个人/工作**长期堆积**的目录：桌面、Downloads、项目盘、照片库、素材库、文档堆、混合内容。
- ❌ **代码仓库**的重构（那是工程任务，有构建/依赖约束）；单文件的读取或格式转换（用对应工具）。

## 流程：五个阶段，每阶段收在一个「人工确认闸门」

脚本在 `scripts/`，都是 stdlib、跨平台、对中文/空格/特殊字符文件名安全。

### 阶段 0 · 画像（先看地形）
```
python3 scripts/scan.py "<folder>"
```
拿到：总体积、体积热点子夹、文件类型分布、最大的文件、时间跨度。
**先递归看全貌**——很多目录 80% 的体积集中在几个大文件（一个视频/一个 3D 源文件/一个 zip），
这决定你重点在哪。别只看顶层就下结论。

### 阶段 1 · 查重删冗余（先清最确定的）
```
python3 scripts/find_dupes.py "<folder>" --json /tmp/dupes.json
```
它按**内容 md5**（不是名字）分出两类，要分别对待：
- **A 完全重复**（逐字节相同）：可只留一份。典型来源：macOS 复制残留 `xxx 2.ext`、`(1)` 后缀、
  同一文件被打包进 zip 又散落一份。→ 走**暂存**（下方），确认后清。
- **B 版本残留**（名字相近、内容不同）：这是**迭代版本**（v1/v2、副本、_final、时间戳）。
  **绝不替用户决定删哪个。** 只做「归拢进 `_历史版本/`」，留最新版在外面——哪版是终版用户最清楚。

删除永远用暂存脚本（可逆）：
```
bash scripts/safe_stage.sh "<folder>" "<folder>/path/dup1" "<folder>/path/dup2"
```
🚪 **闸门**：动手前把「要暂存的精确清单」给用户看，确认后才 stage。

同时顺手识别两类需要**特别提醒**的文件（别删，是提醒/移走）：
- **明确垃圾**：`.~$…`（Office 崩溃临时）、`*.crdownload/*.part/*.qkdownloading`（没下完的半成品）、`.DS_Store`。
- **敏感个人信息**：身份证/护照/银行卡/合同/密码文件混在工作夹里——主动指出，建议移到私人目录。

### 阶段 2 · 读进内容（本 skill 的差异化所在）
```
python3 scripts/signatures.py "<folder>"                 # 全部
python3 scripts/signatures.py "<folder>" --ext .html,.xlsx,.pdf   # 只挑某几类
```
对每个文件按类型抽「内容签名」，读不了就退化到元数据（见 `references/readers.md`）：
html 抽 title+h1/h2、office 抽表名/文档标题、pdf 抽首页、图片抽 EXIF、音视频抽时长标签……
**目的**：搞懂每个文件真实是什么，纠正「看名字会归错的分类」。
文件很多时先读体量最大或最关键的一批，够判断分类即可，不必逐个全读。

### 阶段 3 · 给整理建议（先问轴，再出方案）
基于阶段 2 读到的内容：
1. **问用户组织轴**：这堆东西按什么分？（日期 / 客户 / 项目 / 类型 / 主题 / 过程阶段）
   以及「理想终态想要什么」。分类法从这里定，不是你拍脑袋。
   决策类问题用一次性多选提问（若环境支持 AskUserQuestion），别来回挤牙膏。
2. 出一版**目标结构 + 归类映射**（哪个文件进哪个夹），大文件夹可再开二级（按子专题/过程）。
   小夹（就三五个文件）保持平铺，别过度嵌套。
🚪 **闸门**：结构方案先给用户确认/调整，认可后才执行。

### 阶段 4 · 执行归类（+ 可选重命名）
- 建目标结构、按映射 `mv`。破坏性小，但仍逐步做、每批回报。
- **重命名是可选的、且要先锁规则**——见下节。

## 重命名（只在用户要求时做，且先锁规则）

批量改名前，用一次提问锁死 4 件事，避免返工：
**① 命名结构**（如 `日期-内容-版本`）· **② 语言**（统一中文/英文/保持原样）·
**③ 版本标记**（v1/v2/v3 vs 日期 vs 只留终版）· **④ 分隔符**（`-` / `_` / 空格）。

起名原则——**一眼看穿内容**：把文件里最关键的结论/数字压进名字，而不是清理原标题。
> 反例：`分析.xlsx`　正例：`20250807-季度留存分析-流失集中在第3周.xlsx`

有多版本迭代时，**diff 出「每版新增了啥」**：文本/office 比标题与结构（如 xlsx 比工作表名），
把简短 delta 写进文件名（`-v2-拆一级二级汇总`），完整对比写一份 `_版本迭代说明.md`。
🚪 **闸门**：出逐文件「旧名 → 新名」对照表，确认后再批量改。

## 可选产出 · 知识图谱

当这堆东西之间**确有关系值得看**（数据流、依赖、工具供给、版本演进）时，
可产出一张 HTML「工作图谱」：画项目间真实关系（不是文件夹树），把关键结论嵌进节点。
关系从阶段 2 读到的内容推断。不是每个文件夹都需要——无关系就别硬画。

## 贯穿全程的安全写法（血泪教训，务必遵守）

- **暂存代替硬删**：删除一律进 `_待删_<日期>/`，可逆。
- **确认闸门**：每个破坏性阶段（删/大规模移动/批量改名）前，把精确清单给用户确认。
- **版本残留只归拢不删**：不替用户判断终版。
- **主动识别敏感件**并建议移出工作夹。
- **shell 处理文件名**：全程双引号包裹；遍历用 `find -print0 | while IFS= read -r -d ''`；
  别用 `for f in $(...)`（会按空格拆断中文/带空格文件名）。
- **`.DS_Store` 会让 `rmdir` 失败**：清空目录前先 `rm -f "<dir>/.DS_Store"` 再 `rmdir`。
- **zsh ≠ bash**：默认 shell 常是 zsh，别用 bash 关联数组 `${!arr[@]}`（会报 bad substitution）；
  用顺序 `mv` 或把脚本显式交给 `bash script.sh` 跑。
- **`mv` 链用 `&&` 时**：一步失败会中断后续；宁可逐条 `mv` 并在末尾核对，也别让半截链悄悄漏掉。

## 脚本清单

| 脚本 | 作用 |
|---|---|
| `scripts/scan.py` | 阶段0 · 文件夹画像（体积/类型/最大文件/时间跨度）|
| `scripts/find_dupes.py` | 阶段1 · 内容级查重（A完全重复 / B版本残留）|
| `scripts/signatures.py` | 阶段2 · 按类型深读内容签名（含优雅退化）|
| `scripts/safe_stage.sh` | 可逆暂存（删除的唯一方式）|

按类型的读取策略与可选外部工具，见 `references/readers.md`。