xcode-disk-cleanup

Xcode 磁盘清理

安全约定

• 将每项清理请求视为允许审计，而非允许删除。
• 在向用户列出确切的候选项 ID、路径或模拟器标识符、测得的大小、风险和重新生成成本之前，绝不更改存储内容。
• 审计后提出的类别级请求（例如“移除所有过时的文档缓存”），如果此前已向用户完整列出匹配的当前冻结选择集，则视为批准该选择集。重新验证后，在该轮中执行；无需再次列出选择集并请求确认。无需特殊命令或重复确认。审计前提出的宽泛请求（例如“清理 Xcode”或“全部删除”）仍仅用于审计。
• 默认将普通文件和目录移至废纸篓。说明只有清空废纸篓后才会释放空间，并在清空前另行征求批准。
• 在执行更改前，立即重新验证对象身份和运行中进程对其的使用情况。
• 绝不使用通配符、无边界的 rm -rf、sudo、SIP 更改，或手动删除系统管理的 CoreSimulator 和 MobileAsset 目录中的内容。
• 除非用户证明确切的已分发构建已在其他位置备份，并另行批准删除，否则保留归档和 dSYM。
• 绝不删除 Package.resolved、签名资源、凭据、自定义 DocSets、当前使用的 Xcode、正在运行的模拟器，或唯一提供所需 SDK/工具链的 Xcode。
• 将候选项总大小与实际回收的 APFS 空间分开报告。

执行清理前，请阅读 references/safety-model.md。

工作流

1. 预检

1. 确认主机运行 macOS，且捆绑脚本可用。
2. 检查是否存在活动的 Xcode、Simulator、xcodebuild、Swift 构建、测试、归档和软件包解析进程。
3. 将打开的 Xcode 或 Simulator 应用视为上下文，而非自动阻止清理的条件。如果构建、测试、归档或软件包解析进程正在运行，某个确切的候选项正被该操作使用，或者受支持的删除 API 要求应用/设备停止运行，则延后受影响的清理。
4. 不要仅因为应用出现在 ps 中就要求用户退出。对于可重新生成的文档缓存，在 Xcode 打开时移走旧缓存可能会暂时导致本地文档不可用，直至重新加载，但无需退出 Xcode 或 Simulator。应说明这项代价。
5. 确定用于扫描项目本地 .build 和 .derived-data 的可选源目录。不要遍历整个主目录。

2. 运行只读审计

python3 "${SKILL_DIR}/scripts/xcode_disk_cleanup.py" audit \
  --output-dir .xcode-disk-cleanup-audit \
  [--scan-root /path/to/projects]

读取生成的两个文件：

• .xcode-disk-cleanup-audit/report.md
• .xcode-disk-cleanup-audit/audit.json

该脚本会审计 DerivedData、文档缓存、CocoaPods 缓存、模拟器设备和运行时（包括已过时且被后续版本取代的 Beta 运行时）、孤立的运行时卷、模拟器 dyld 缓存、Xcode 管理的组件、Xcode 安装器、已安装的 Xcode、归档（包括从未分发的孤立归档）、所有平台的 DeviceSupport、诊断日志、XCTest 设备克隆、旧版 DocSets，以及明确请求扫描的项目根目录。

共享编译器缓存（ModuleCache.noindex、预编译 SDK 模块）和全局 SwiftPM 下载缓存明确不在审计范围内：它们在活跃的开发机器上始终会被使用，清理它们会以实际的构建耗时换取很少且无法长期保持的空间。不要建议清理这些内容。

3. 验证并补充发现项

使用类别路由：

发现项	参考资料
DerivedData、模块缓存、项目 .build、CocoaPods	references/generated-data.md
模拟器设备、运行时、dyld 缓存、XCTest 克隆	references/simulators.md
归档、dSYM、DeviceSupport、日志、DocSets	references/release-artifacts.md
Xcode DMG/XIP 和已安装的 Xcode	references/xcode-installations.md
确认和删除行为	references/safety-model.md

不要机械地接受扫描器的分类。核实所有权不明、自定义路径、备份和工具链要求。

4. 展示方案

按可回收空间（GiB）排序，并显示：

1. 候选项 ID
2. 类别和准确路径/标识符
3. 可回收空间（GiB）
4. 风险：可重新生成、破坏性或保留
5. 证据——简短说明“为何已过时”（如天数、被什么取代、工作区缺失），而非仅给出分类标签
6. 必须重建、重新下载或将永久丢失的内容
7. 建议操作

让方案易于浏览：

• 将文件夹候选项显示为可点击的 file:// 链接，方便用户在批准前检查。仅在用户需要批准时显示候选项 ID，不要将其用作项目的显示名称。
• 在说明中保留审计的 evidence 和 reason 字段。脚本已说明每项“为何过时”（“4 天未变更”“已被 16.4.1 (325) 取代（于 2026-07-21 归档）”“相同文档仍然可用”）；删掉这些背景会让原本有据可查的方案变成单纯的文件列表。
• 隐藏小于约 0.5 GiB 的单项；完整的逐项列表仍保留在 report.md 中以供参考。不要用“较小项目”汇总项充数——这只会增加疑问，而非提供有用信息。
• 按运行时将不可用的模拟器分组列成表格。
• 每个类别都单独设置子标题并标注其总大小，即使类别很小，例如文档缓存或孤立归档。若将某类别汇总在另一类别的表格下方段落中，就容易被忽略；被忽略的项目也就无法得到有意义的批准。
• 除非有当前的相反证据，否则应信任扫描器的分类。尤其是，Orphan archive 候选项已包含证据（没有 Organizer 分发记录，且同一应用有更新的归档）；不要仅因其他情况下归档默认保留，就将其降级为保留。

按以下示例格式整理各类别，并根据机器上的情况调整标签：

### Orphaned DerivedData — 15.5 GiB · regenerable

All four belong to workspaces that no longer exist.

| Folder | Size | Why stale |
|---|---:|---|
| [RocketSim-beqqrx…](file:///Users/me/Library/Developer/Xcode/DerivedData/RocketSim-beqqrximmvoaakbpvjshhqhuacyv) | 5.6 GiB | Workspace deleted; unchanged for 1 day |
| [RocketSim-fjapct…](file:///Users/me/Library/Developer/Xcode/DerivedData/RocketSim-fjapctdhvtzcaaabmtsyumkmcarf) | 4.0 GiB | Only package downloads, no build products; unchanged for 4 days |

包括：

• 按风险汇总的候选项总 GiB 数
• 当前可用磁盘空间
• 警告：APFS 克隆和快照会导致候选项大小不可直接相加
• 直接请求用户批准确切的 ID。当用户选择某个类别时，将所有已选 ID、总大小、风险和建议操作重新列出，形成一个固定的选择集合。说明一次：之后用户以普通语言提出删除请求，即表示批准相符的集合。不要要求用户重复 ID、使用指定短语，或在重新验证结果未变时再次确认。

5. 展开类别选择并仅应用已批准的 ID

审计完成后，诸如“删除所有过时的 DerivedData”或“清理所有过时的文档缓存”之类的请求，只有在满足以下所有条件时，才可批准该类别中当前已审计的所有候选项：

1. 每个选定项都已通过该类别特定的验证，并具有准确且稳定的 ID、路径或模拟器标识符、大小、风险和操作。
2. 助手打印完整展开的 ID 列表、总大小和操作，将其作为固定的选择集，并说明用户用自然语言提出类别请求即可批准该选择集。
3. 用户随后明确、肯定地请求移除该类别。这是唯一一次批准，且仅授权所显示选择集中的 ID，而非整个类别。重新验证后立即应用；绝不要求用户提供特定短语或再发一条消息。
4. 重新验证成功。如果每个已批准的候选项都保留相同的 ID、身份、风险和操作，刷新审计不会使批准失效。静默使用刷新的审计结果并继续。绝不添加新候选项。
5. 如果某个已批准项发生变化、变为活动状态或被重新分类，则将其排除并报告。在安全的情况下，继续处理未变化的已批准项；仅当继续处理会实质性改变已批准的范围或操作时，才再次询问。

审计前绝不根据宽泛请求推断类别成员，也绝不包含保留项、归档文件/dSYM、活动资源或模拟器操作，除非满足它们各自独立的安全措施和审批要求。

仅在获得针对每个 ID 的直接批准，或用户用自然语言批准当前审计生成的固定展开 ID 选择集后，才调用 apply：

python3 "${SKILL_DIR}/scripts/xcode_disk_cleanup.py" apply \
  --audit-file .xcode-disk-cleanup-audit/audit.json \
  --ids "<approved-id-1>" "<approved-id-2>" \
  --confirm I_APPROVED_THE_SELECTED_ITEMS \
  --output .xcode-disk-cleanup-audit/cleanup-result.json

删除模拟器设备和运行时不可逆，必须获得第二次批准，并提供：

--confirm-irreversible I_APPROVED_IRREVERSIBLE_SIMULATOR_DELETION

只有当 simctl 报告某个过时运行时可删除、没有已安装的 Xcode SDK 可解析到其构建版本，并且同一平台上有较新的运行时取代它时，才会建议删除该运行时。在安装较新的 Xcode beta 后，Xcode Settings → Components 中遗留的 beta 平台就是这种情况。

除非对话中已有相应的用户批准，否则不要传递任一确认短语。

“单独批准”是指对不可逆的 Simulator 类别表达明确、独立的意图，不一定需要单独发送一条消息。显示确切的 Simulator ID 和永久数据丢失后，用户只需提出一个请求，例如“移除 DerivedData 和不可用的模拟器”，即可同时构成普通批准和针对该类别的单独不可逆操作批准。在该轮中重新验证并执行两项操作。“清理所有内容”之类的笼统请求不构成不可逆操作批准。

6. 验证

1. 重新运行审计。
2. 比较操作前后的 df 可用空间。
3. 区分“已移至废纸篓”和立即释放的空间。
4. 确认受保护和未获批准的候选项仍然保留。
5. 报告成功、失败和暂缓处理的项目。

Xcode 安装器和应用程序规则

• 通过 Spotlight 和常见下载文件夹搜索 .xip、.dmg 和 .zip 安装器。
• 只有当解析出的版本与已安装的 Xcode 匹配时，才建议使用某安装器；否则将其报告为不确定。
• 只有在较旧的 Xcode 未处于活动或运行状态，且存在同一发布渠道的较新安装时，才可建议使用较旧的 Xcode；绝不可自动选中。
• Spotlight 的 kMDItemLastUsedDate 反映的是 LaunchServices 打开记录，而非命令行使用记录。应结合 xcode-select、DEVELOPER_DIR、运行中的进程、.xcode-version、CI 脚本以及唯一的 SDK/工具链证据进行判断。
• 绝不推断稳定版 Xcode 会取代 beta 版，或 beta 版会取代稳定版。

输出质量检查清单

• 已完成审计，且未进行任何修改
• 每个项目都有精确的大小和稳定 ID
• 候选空间与实际回收空间分开列出
• 默认保留归档文件和 dSYM
• 保护活动进程和当前选定的 Xcode
• 用户直接批准了具体 ID，或在看到完整列出且已冻结的选择集后，明确提出了类别请求
• 不可逆操作获得了单独批准
• 清理后的审计确认只有获批项目发生了变化