用途
carl-file-organizer 用于两类任务：一是整理下载目录或任意散乱文件夹，二是整机磁盘盘点。用户说「整理下载目录」「收拾一下」等，走整理流程；用户说磁盘满、空间紧、想清缓存，则默认同时扫描盘点。用户只是问某个文件该放哪，不用跑工具，直接回答。
工具的设计原则是把用户当作拿主意的人：脚本负责量、算、定色，执行者负责把每一项讲成人话，然后把报告交给用户，等用户在页面上一项一项点。全程只读，直到用户在页面上点按钮并在浏览器弹窗里二次确认。
主要能力
- 只读扫描目录，生成整理方案 plan.json 和盘点结果 storage-scan.json。
- 按绿黄红三色分级：绿的是规则已定去向的移动、敏感命名隔离和可再生产物；黄的是待判断、成对压缩包、重复副本和冷存候选；红的是禁刀区、被进程占用、被别处引用、静置期未满、常驻白名单等这轮不能碰的项。
- 分组处理选择题：压缩包和解压目录成对、内容相同的重复副本、构建产物各成一组，每组带 options，由用户在页面上单选。
- 对待判断项按文件名、扩展名、大小、修改时间判断，不打开文件、不读内容。
- 磁盘盘点按绿黄红分级，绿是纯缓存和构建产物，黄是含用户数据或暂时没用的，红是碰不得的（虚拟机镜像、浏览器用户数据、钥匙串、邮件和信息主数据、照片图库、iCloud 本地副本、活跃仓库的 .git 等）。
- 生成 report.html，清理和搬动在同一页，按绿黄红三区排，含磁盘条、杂乱度、先做什么、最大的五项、整理后预览。
- 支持预演 apply --dry-run，执行后支持 status 查看、undo 按记录逆序放回、clear-tags 清理复查用的 Finder 标签。
使用方式
流程为：scan 只读扫描 → 写 notes.json 与 analysis.json → report 生成报告 → 用户在页面上处理或导出 → apply --dry-run 预演 → 用户说执行才真跑。
基本命令形式为 python3 <skill>/scripts/organize.py，零依赖，Python 3.9 以上即可。示例：
python3 <skill>/scripts/organize.py scan ~/Downloads --lang zh --budget-seconds 60
python3 <skill>/scripts/organize.py report <管理目录>
python3 <skill>/scripts/organize.py report <管理目录> --serve
python3 <skill>/scripts/organize.py apply ~/Downloads/carl-file-organizer-decisions.json --dry-run
python3 <skill>/scripts/organize.py status ~/Downloads
python3 <skill>/scripts/organize.py undo <管理目录>/audit.jsonl
python3 <skill>/scripts/organize.py clear-tags ~/Downloads
也可以拆开跑：plan、build、review、storage_scan.py、storage-report、dispose 等。
用户没有指定目录时默认 ~/Downloads，英文目录名把 --lang 换成 en，只整理不盘点加 --no-storage。产物落在目标目录下的管理目录里，中文为 <目录>/00_下载目录管理/，英文为 <目录>/00_File_Organizer/。
适用场景
- 整理下载目录或其他散乱文件夹，生成移动与清理建议。
- 盘点磁盘空间去向，区分可清缓存、需查看项和不可碰项。
- 判断某个文件应放到哪个分区。
- 用户在页面上勾选或直接处置，并在浏览器二次确认后执行。
限制
- 不读 secrets、密钥文件、浏览器数据库、聊天正文；敏感命名只看名字。
- 永远不自己 rm、mv、trash，也不用 osascript 绕过工具动文件。
- 永远不给任何命令加 --allow-permanent-delete，这个开关只能用户自己加。
- 绿项可进废纸篓或永久删除（永久删除须用户加开关），黄项只能进废纸篓，红项只能打开所在位置。
- 工具拒绝执行或标为 refused 的，原样转告，不绕路重试。
- 用户说「整理一下」「看看」「先别动」「再想想」都算未授权，继续停在预演；只有用户明确说执行、apply、动手、可以了，或自己在页面上点按钮，才算授权。
- macOS 上隐私保护会挡住一批目录，一次出现上百个读不到属正常，总量因此偏小。
- 盘点默认六十秒预算，超时条目标为 partial，体积是下限。
- storage-scan.json 含本机绝对路径，只供本机使用；对外分享应发 report.html，其中家目录已替换为 $HOME。
- notes.json 只接受 what、why、if_removed 三个键，多余键会被丢弃并记提醒。
- overrides 的 destination_key 只能取自 plan.json 的 names，不许写字面路径。
- trash_paths 只填核实过的具体安全子路径，红项必须为空数组，路径须落在家目录内且无软链段。
- Windows 上 WinSxS、hiberfil、pagefile 只写不扫，放入 long_term 给正规释放方式，不给删除按钮。
- 资料未提供具体分类、收费、价格、平台范围或其他未提及的功能与效果。