Derived

注意

Derived 会永久删除所选的开发者数据，而不是将其移入废纸篓。请在确认删除前检查清理计划。

概述

Derived 可查找并移除由 Xcode、Simulator 和 XCTest 创建的存储数据。它会报告经验证可释放的空间，将 APFS 克隆大小单独列出，并保护活动目标或高风险目标。

可通过 macOS 应用、derived CLI 或本地 derived-mcp 服务使用 Derived。这三种界面使用相同的扫描器、路径验证和清理工作流。Derived 在本地运行，不会收集分析数据。

界面	适用场景
macOS 应用	交互式扫描、选择清理内容、安排计划和查看历史记录
CLI	终端工作流、Shell 脚本和结构化 JSON 输出
MCP 服务	为 Codex、Claude Code、Cursor 和其他 MCP 客户端提供结构化访问

安装 macOS 应用

Homebrew（推荐）

brew tap adiaz0511/derived
brew trust adiaz0511/derived
brew install --cask derived

第三方 tap 仅需运行一次信任命令。

使用以下命令更新应用：

brew update
brew upgrade --cask derived

磁盘映像

1. 从最新的 GitHub 版本发布页下载 DMG。
2. 打开磁盘映像。
3. 将 Derived.app 拖到 Applications。
4. 从 Applications 打开 Derived。

安装 CLI 和 MCP 服务

Agent 工具包括 derived CLI、derived-mcp 服务和 derived-cleanup 技能。无需安装 macOS 应用。

Homebrew（推荐）

brew tap adiaz0511/derived
brew trust adiaz0511/derived
brew install --cask derived-tools
derived integrations install

derived integrations install 会检测 Mac 上的 Codex、Claude Code 和 Cursor，并为每个检测到的客户端注册 MCP 服务和安装技能。

使用以下命令更新工具并刷新集成：

derived integrations update

CLI 会在交互式命令中每天最多检查一次新版本。更新提示不会出现在 JSON 或 MCP 输出中。

磁盘映像

最新的 Derived DMG 还包含 Derived Agent Tools，可用于无需 Homebrew 的安装。

1. 打开 DMG。
2. 打开 Derived Agent Tools。
3. 选择 Install for Codex。
4. 重启 Codex。

如果同时安装了应用和通过 DMG 安装的工具，Derived 会在应用更新后提示更新工具。如果未安装应用，请下载最新 DMG 并再次运行 Derived Agent Tools。

MCPB 安装

支持 MCPB 捆绑包的客户端可以从最新版本发布页安装 Derived-MCP-VERSION-macOS-universal.mcpb。MCPB 包含 MCP 服务，但不会安装 derived CLI 或可移植技能。

在编码 Agent 中使用 Derived

检查已配置的客户端：

derived --version
derived integrations status

然后在 Codex、Claude Code 或 Cursor 中启动新会话并询问：

Use $derived-cleanup to scan my developer storage.

有关特定客户端的命令、手动配置和卸载说明，请参阅 Agent 集成。

使用 CLI

CLI 为交互式使用提供对齐的表格，并为脚本和 Agent 提供 JSON。

命令	用途
derived scan	扫描 Xcode、Simulator 和 XCTest 存储，并输出扫描 ID
derived list	列出上一次扫描中某个类别的候选项
derived prepare	为选定的项目或类别创建会过期的清理计划
derived delete	使用该计划的准确确认短语执行计划
derived integrations install	为受支持的编码 Agent 配置 MCP 服务和技能
derived integrations status	报告已安装的 Agent 集成
derived integrations update	更新由 Homebrew 管理的工具并刷新其集成

先执行扫描：

derived --version
derived scan

使用 derived scan 输出的扫描 ID 检查某个类别并准备计划：

derived list --scan SCAN_ID --category derivedData --limit 20
derived prepare --scan SCAN_ID --category previewData

将 SCAN_ID 替换为扫描输出的 UUID。不要包含尖括号。prepare 命令会输出准确的确认短语，以及该计划完整的 derived delete 命令。

如果输出将由其他程序使用，请添加 --json：

derived scan --json
derived list --scan SCAN_ID --category derivedData --limit 20 --json

扫描 ID 会在 30 分钟后过期。清理计划会在 10 分钟后过期，且只能执行一次。

功能

存储发现

• 扫描 Derived Data、SwiftUI 预览、XCTest 设备、模拟器、运行时、Device Support、日志、缓存、归档和临时数据。
• 将经过验证的可回收字节数与 APFS 克隆的逻辑大小分别报告。
• 按类别和建议状态对清理候选项进行分组。

清理与自动化

• 清理单个候选项、完整类别或跨类别选择项。
• 使用 simctl 通过受支持的系统操作移除模拟器设备和运行时。
• 为 Derived Data、Xcode 日志和 Xcode 缓存安排清理。
• 支持登录时启动，并维护本地 JSON Lines 清理历史记录。

安全性

• 检测活跃的开发工具并保护活跃目标。
• 删除前要求使用会过期的清理计划和准确的确认信息。
• 在清理前立即重新验证每个候选项。
• 绝不自动选择归档或模拟器运行时。

安全模型

Derived 会根据固定的允许列表验证每个清理目标。它会拒绝类别根目录、批准的开发者目录之外的路径、格式错误的模拟器标识符、活跃目标、符号链接逃逸，以及计划创建后发生变化的候选项。

自动清理会等到相关开发工具关闭后再执行；如果无法检查进程，则会安全失败。XCTest APFS 克隆大小会作为逻辑大小报告，并从经过验证的可回收总量中排除。

完整的删除模型和批准路径请参阅 安全性。

要求

运行 Derived

• macOS 14.0 或更高版本
• 用于发现 Simulator 和执行由 simctl 支持的清理操作的 Xcode

DMG 包含预构建的通用应用程序和命令行工具。无需从源代码构建。

Derived 有意不使用沙盒，因为它需要管理 ~/Library/Developer 下的文件并调用 xcrun simctl。

从源代码构建

• Xcode 26.4 或更高版本
• Swift 6.2 工具链

克隆仓库，打开 Derived.xcodeproj，选择 Derived 方案，并构建 macOS 目标。

命令行构建：

xcodebuild \
  -project Derived.xcodeproj \
  -scheme Derived \
  -configuration Debug \
  -derivedDataPath /tmp/DerivedBuild \
  CODE_SIGNING_ALLOWED=NO \
  build

运行应用程序测试：

xcodebuild \
  -project Derived.xcodeproj \
  -scheme Derived \
  -configuration Debug \
  -destination 'platform=macOS' \
  -derivedDataPath /tmp/DerivedTests \
  CODE_SIGNING_ALLOWED=NO \
  test

构建并测试 CLI 和 MCP 服务：

swift test
scripts/test-agent-protocol.sh
swift build -c release

登录时启动要求应用程序已签名并安装在固定位置。从未签名的开发版本运行时，此功能可能无法正常工作。

项目结构

• Derived/App：应用生命周期、菜单栏项目和面板管理
• Derived/Features：按功能分组的 SwiftUI 展示层
• Derived/Models：清理、扫描、自动化和报告模型
• Derived/Services：扫描、验证、进程检查、删除和持久化
• Derived/Shared：共享格式化工具和设计常量
• Derived/AgentIntegration：共享 CLI 和 MCP 模型、状态及安全工作流
• DerivedTests：安全和行为测试
• DerivedCLITests：CLI 参数、版本和人类可读输出测试
• DerivedCoreTests：Agent 集成和破坏性操作防护
• Tools：原生 CLI 和 MCP 可执行文件
• Integrations：可移植的 Agent 技能和打包元数据

隐私

Derived 在本地运行，不包含分析、广告、账户或网络服务。请参阅隐私。

贡献

欢迎贡献。在更改扫描器、验证或删除行为之前，请阅读贡献指南。

维护者应遵循发布 Derived 中的说明，完成签名、公证、DMG 生成和 MCP 发布。

许可证

Derived 采用 MIT 许可证。