system-cleanup

系统清理

目标：增加 Data 卷上的物理可用空间，并报告已清理、已保留以及待用户批准的内容。

前提：使用 macOS 主机，且用户请求清理或腾出空间。如果请求是调优性能、移除恶意软件，或未经批准删除个人或应用数据，请暂停并说明缺少什么。

审计磁盘，清理可安全重新生成的内容，并在处理其他内容前征求确认。

基本规则

• 使用 df -h /System/Volumes/Data 测量 macOS Data 卷上的物理可用空间；普通的 df /、du、Finder 分类和清理工具的估算只能作为佐证，不能作为最终结果。
• 优先使用工具当前原生的清理命令，而不是删除其目录。通过工具自身的帮助信息或当前文档确认已安装版本的接口；如有试运行模式，则使用该模式。不要在这里保留包管理器命令目录。
• 直接删除时，若有 trash，则使用它。先将项目移入废纸篓，再一次性询问是否清空。如果没有 trash，则在永久删除前征求确认。
• 只有明确安全的内容才可不经询问就移除：可重新生成的内容，或已在其他位置保留的内容（已合并并推送分支的干净工作树、已备份的文件）。列出其他所有内容及其原因，然后等待用户明确同意。只要可行，就移入废纸篓或备份，而不是直接删除。
• 通用清理请求即表示用户授权清理请求范围内准确识别出的、非活跃且可重新生成的构建产物和包／语言缓存；无需针对每项再次询问。
• 不要自动清理 GUI 应用数据。报告应用缓存／支持目录的大小；除非用户指定应用并接受登录状态、Cookie、历史记录或本地状态可能受影响的风险。
• 移除个人文件、媒体文件、应用、项目、备份、模型权重、Docker 卷、虚拟机、模拟器快照、SDK、运行时或工具链前，必须先征求确认。
• 绝不能为了达到预计清理量而绕过 SIP、削弱权限、终止无关进程或删除受保护的系统路径。

工作流程

1. 评估

测量 Data 卷并检查已挂载的卷。记录初始可用空间和任何外置驱动器。只有当 APFS 卷／快照的占用统计可能实质性解释结果时，才检查它们。

2. 调查

使用限定在目标文件系统范围内的定向大小扫描，而不是遍历整个 ~。先检查相关范围中最大的部分，再检查具体候选项。常见类别包括：

• 当前或关联工作树中的非活跃构建产物，以及依赖项／构建输出；
• 已安装开发工具的包／语言缓存；
• 过期工作树及其重复生成的输出；
• 大型媒体文件／下载文件；以及
• 大型应用缓存／支持目录，仅供报告，除非另行授权。

处理大型临时目录、工作树、缓存、虚拟机或当前构建输出前，先检查正在运行的进程和打开的文件句柄。将含义不明确的数据视为需要长期保留的数据。

3. 清理安全范围

无需再次询问即可清理非活跃、可重新生成的构建产物和包／语言缓存。对于每个选定工具，应通过已安装工具的接口或当前官方文档查找并使用其清理／修剪命令，而不是想当然地删除内部缓存目录。

当当前工具明确负责回收可安全清理的内容时，使用应用原生的清理功能清理 Docker／Xcode／模拟器或同类生成状态。除非另行授权，否则保留数据卷、兼容性运行时、用户创建的映像／状态及类似的持久数据。

每次只处理一个类别，每完成一批大型清理后，都重新检查 Data 卷的可用空间。APFS 克隆、共享资源、稀疏映像和废纸篓都可能导致逻辑估算与物理回收量不同。

4. 审核选定的 Git 工作树

要盘点，请将 SKILL_DIR 设为此已安装技能的目录，然后运行 python3 "$SKILL_DIR/scripts/worktrees.py"；--json 会输出 JSON，--remove-safe 会重新检查并移除安全的工作树，同时保留分支。

仅当工作树或其生成的输出被选为清理对象时，才执行此步骤。对于每个受影响的工作树，确认其是否有未提交更改、是否包含独有提交、是否领先于其上游分支，或是否包含未跟踪文件。保留并报告任何存在未提交更改、包含独有提交、尚未推送或尚未合并到接收工作区的内容。现有的清理授权并不允许移除这些内容。

提交已完全合并并推送的干净工作树是安全的：使用 Git 的常规工作树移除方式和非强制分支删除；绝不能仅为了清理而强制删除分支。

5. 将保留项转移到外部存储

如果用户选择转移到外部存储，请确认目标位置是已挂载的独立卷，并且有足够的可用空间。使用主机支持的元数据保留方法复制每个选定文件夹；任何特定的复制工具都只是一个起点，并不能证明保留了所有 macOS 元数据类型。

核对文件数量和大小；如果数据无法替代，请使用校验和。验证完成后才将原件移入废纸篓；在适当时，于原路径创建符号链接。仅对单个文件夹创建符号链接，不要对范围较大的特殊目录创建符号链接。提醒用户，外部驱动器未挂载时，该路径将不可用。

6. 总结（完成并返回）

报告初始和当前可用空间、立即释放的物理空间、废纸篓中待处理的项目、已清理的类别、保留的项目、失败项，以及可选的后续候选项及其大小和取舍。

需要时，请用户清空废纸篓。用户批准且废纸篓已清空后，重新测量 Data 卷并报告最终释放的物理空间。用尽已授权的安全候选项后即停止；报告任何需要单独批准的事项。