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 并在末尾核对，也别让半截链悄悄漏掉。

脚本清单

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