电脑文件整理（File Organizer）

把乱糟糟的文件夹，整理成「一眼能找到东西」的结构化目录 —— 有点像给抽屉做分类收纳。

核心做法是四步走：先看清有什么 → 出一份方案给你过目 → 你点头才动手 → 全程留痕可反悔。

铁律：安全协议（不可跳过）

整理的是用户自己的文件，任何一步疏忽都可能造成不可逆的损失。必须严格按顺序执行：

1. 先扫描，只读。 第一次接触任何目录，只运行 scan / plan，不移动任何文件。方案是纯文本产物，磁盘一字未改。
2. 方案先给用户看。 把生成的人读版方案（plan-*.md）用 present_files 呈现给用户，说明：会移动多少个文件、分成哪几个文件夹、按什么规则。
3. 必须拿到明确确认。 用户说「可以 / 执行 / 就这样」之后，才能进入 apply。用户没表态就不能擅自执行。若方案涉及任何删除或覆盖（本工具本身不会，但用户可能额外要求），必须先以加粗给出 「⚠️ 此操作非常危险，可能导致不可逆的数据丢失！」，列出全部受影响路径，并再次单独确认。
4. 动文件前先备份。 apply 加 --backup-dir <备份目录>，先把原件整份复制一份留底，确认成功再继续。
5. 只移动，不删除。 本工具只有 move 和 copy 两种动作，没有任何删除能力。目标重名时自动追加 (n)，永不覆盖。任何情况下都不得执行 rm、rm -rf、del /S /Q、shutil.rmtree、Remove-Item -Recurse 等删除命令；需要腾空目录时只使用 --prune-empty-dirs / --prune-empty（二者只删除确认为空的目录）。
6. 分批执行，逐批校验。 apply 默认每批 20 个（--batch 可调），每批校验源已消失、目标大小一致；任一失败立即中断并提示回滚命令。
7. 全程留痕，随时可撤回。 apply 先写 manifest 台账再动文件；undo 可依据台账把一切还原到原位。
8. 不确定就停下来问。 目标目录含糊（「帮我整理一下电脑」）、范围过大（整个 C:\）、或用户没指明整理维度时，先问清「整理哪个目录 + 按什么维度」，不要猜着动手。

> 单个整理批次建议不超过 500 个文件；超过时先按子目录拆分，逐个子目录反复确认。

工作流

第 0 步 · 澄清范围与维度

至少确认两件事（用户已经说清楚的不要重复问）：

• 整理哪个目录？ 必须是具体路径，例如 D:\下载、C:\Users\XX\Desktop。含糊的「帮我整理电脑」要追问，并明确告知不会碰系统目录。
• 按什么维度整理？ 见下方「四种整理维度」。用户说「随便」时，按目录类型给推荐：下载文件夹 → type；照片/素材 → time；工作资料 → function。

第 1 步 · 只读扫描

python <skill>/scripts/organize.py scan --dir "<目标目录>"

输出文件总数、总大小、按类别/年份/扩展名的分布。把关键数字讲给用户听（「一共 1372 个文件、约 6.4 GB，其中文档 412 个、图片 500+ 个…」）。

需要完整清单（文件多时适合）加 --out <清单.json>。

第 2 步 · 生成方案（只读）

python <skill>/scripts/organize.py plan --dir "<目标目录>" --strategy type

默认把方案写到 <目标目录>/.file-organizer/ 下，产出两个文件：

• plan-<时间戳>.md —— 人读版，给用户看的
• plan-<时间戳>.json —— 机器版，apply 的输入

第 3 步 · 呈现并取得确认

用 present_files 打开 plan-*.md，同时在回复里总结：移动多少个文件、生成哪些文件夹、举例 2–3 条归类。等用户明确同意。

第 4 步 · 备份 + 执行

python <skill>/scripts/organize.py apply \
  --plan "<目标目录>/.file-organizer/plan-xxxx.json" \
  --confirm --backup-dir "<备份目录>" --prune-empty-dirs

• 不加 --confirm 只会预览，不会动文件（可用来做二次核对）。
• --backup-dir 强烈建议始终带上。
• --prune-empty-dirs 会在整理后清掉腾空的源文件夹（只删确认为空的目录）。

第 5 步 · 交付报告

apply 会输出整理报告 report-<时间戳>.md。用 present_files 呈现，并告诉用户：

• 移动了多少个文件、去了哪些文件夹
• 台账与备份的位置
• 如需还原的完整命令

第 6 步 · 需要时回滚

python <skill>/scripts/organize.py undo --manifest "<台账.json>" --confirm --prune-empty

不加 --confirm 同样是预览。copy 模式不做回滚（原件还在）。

四种整理维度

关于「按功能用途」——需要你动脑

function 维度依据文件名关键词匹配（默认规则见 references/classification-rules.md），只能覆盖明显情况，剩下的都会落到「未分类」。

用户要的是语义化归类时，不要只跑一遍 function 就交付，正确做法是两步：

1. 先 scan --out inventory.json，读取文件清单；
2. 亲自阅读文件名，判断每个文件该归到哪个用途，整理成 moves.json：

{
  "moves": [
    { "src": "报告-2026Q1.docx", "category": "工作", "reason": "季度经营报告" },
    { "src": "发票-2026-03.pdf", "category": "财务", "reason": "报销用发票" },
    { "src": "照片/IMG_001.jpg", "category": "个人照片", "reason": "生活照" }
  ]
}

然后 plan --dir "<目录>" --moves moves.json 生成方案。src 可以是相对目标目录的路径；省略 dst 时按 <目标目录>/<category>/<文件名> 归位。

分类体系要先和用户对齐（比如「工作 / 学习 / 个人 / 财务」还是「项目A / 项目B / 行政」），别自己编一套。

脚本用法速查

# 扫描（只读）
python scripts/organize.py scan --dir "D:/下载" [--out inv.json] [--max-depth 4]

# 规划（只读）
python scripts/organize.py plan --dir "D:/下载" --strategy type [--into 已整理] [--mode move|copy]
python scripts/organize.py plan --dir "D:/照片" --strategy time --time-group year
python scripts/organize.py plan --dir "D:/工作" --moves moves.json

# 执行（必须 --confirm）
python scripts/organize.py apply --plan plan.json --confirm [--batch 20] [--backup-dir D:/备份] [--prune-empty-dirs]

# 回滚
python scripts/organize.py undo --manifest manifest.json --confirm [--prune-empty]

# 查看内置分类表
python scripts/organize.py cats

通用参数：--max-depth N（默认 4）、--include-hidden、--exclude-dir NAME（可重复，追加跳过目录）。

运行环境：仅依赖 Python 3.8+ 标准库，无第三方依赖。Windows / macOS / Linux 均可。若 python 不在 PATH 上，改用可用的解释器绝对路径。

常见场景配方

参考资料

• references/classification-rules.md —— 完整扩展名→类别映射表、功能维度默认关键词、自定义规则文件格式、维度选择建议。修改分类规则或编写自定义 rules.json / moves.json 前先读它。