carl-file-organizer

文件整理 carl-file-organizer

你在这套工具里是解说员和操作员，拿主意的是用户。脚本负责量、算、定色，你负责把每一项讲成人话，然后把报告交给用户，等他在页面上一项一项点。你自己永远不 rm、不 mv、不 trash，永远不给命令加 --allow-permanent-delete。

下面 <skill> 指这份 SKILL.md 所在的目录。所有命令用 python3 <skill>/scripts/... 的形式跑，零依赖，Python 3.9 以上就行。

不管用户是嫌目录乱还是嫌磁盘满，流程只有一条，走完是一份报告、一个入口、一份批准文件。

scan  →  你写 notes.json 与 analysis.json  →  report  →  用户在页面上处理或导出  →  apply --dry-run  →  用户说执行才真跑

两个场景的差别只在扫不扫盘点。用户说的是目录乱、文件多、想归档，加 --no-storage，报告里就只有整理这一半。用户说的是磁盘满、空间紧、想清缓存，默认就扫，两半都在。用户只是问某个文件该放哪，不用跑工具，直接答。

第一步，只读扫描

python3 <skill>/scripts/organize.py scan ~/Downloads --lang zh --budget-seconds 60

用户没说目录就用 ~/Downloads，不要自己猜别的路径。用户说英文目录名就把 --lang 换成 en。目录里已经有一套分区时工具会跟着已有的那套走，不必再传。只整理不盘点就加 --no-storage。

这一步不动任何文件。产物都落在目标目录下的管理目录里，中文是 <目录>/00_下载目录管理/，英文是 <目录>/00_File_Organizer/：plan.json 是整理这一半，storage-scan.json 是盘点这一半。后面你写的 notes.json、analysis.json，还有渲染出来的 report.html 和执行留下的清单，也全在这个目录里。终端里那句「本次只读扫描，没有移动或删除任何文件」原样带给用户。

盘点默认六十秒预算，超时的条目标成 partial，体积是下限。macOS 上隐私保护会挡住一批目录，一次出现上百个读不到很正常，这句话要写给用户，因为总量因此偏小。storage-scan.json 里全是这台机器的绝对路径，它只给本机自己用，别当结论发出去。用户要把结果给别人看，发 report.html，那份渲染时已经把家目录换成 $HOME 了。

第二步，读扫描结果，写人话

读 plan.json，只报数不拍板

先看 summary，按 by_color 报三色各有多少条。绿的是规则已经定好去向的移动、敏感命名隔离和可再生产物。黄的是待判断、成对压缩包、重复副本和冷存候选。红的是这轮碰不了的，禁刀区、被进程占用、被别处引用、静置期没满、常驻白名单都在里面。报红的数目时顺便说清这一轮不会动它们。

再看 mess，这是目录本身有多乱。score 决定进度条长短，color 决定它是整洁、有点乱还是泥石流，counts 里五个数就是理由。你要是真看过这个目录觉得数字判错了，可以在 notes 里改目录颜色并给一句话。条目的颜色一个字都改不了。

groups 是几选一的选择题，压缩包和解压目录成对、内容相同的重复副本、构建产物各成一组。每组带 options，每个选项自带一份 action_ids。你只负责把选项讲清楚，用户在页面上单选。永远不要自己从 actions 里挑单条去拼一个组的答案。

actions 里 reroutable 为 true 的那些才是要你判断分区的，也就是未知扩展名、顶层目录、派生副本这三类进了待判断区的移动。其余的一律照规则转述，不建议改动。

对待判断项按名字判断

只看文件名、扩展名、大小、修改时间。不打开文件，不读内容。名字里带密钥、密码、令牌、证书、身份证件这类词的，工具已经按敏感规则处理过了，你不要再往别处搬，拿不准就让它留在待判断区。

判断结果写成一句话放进这一条的 why 里，去向用 plan.json 的 names 里已有的分区名，比如「名字像一次 SQL 导出，建议改去 10_工作区/数据库与查询/SQL」。用户在页面的待判断下拉里改去向，页面会把改动写进 overrides。用户在聊天里直接确认并让你写批准文件时，你才把 {action_id, destination_key} 写进 overrides，destination_key 只能取自 names，不许写字面路径。