compare-cache-runs

比较缓存运行

快速开始

通常会收到两个缓存运行标识符。请按以下步骤操作：

1. 运行 tuist cache-run list --json，查找各个分支上的缓存运行。
2. 分别对 base 和 head 缓存运行执行 tuist cache-run show <id> --json。
3. 比较耗时、状态和缓存命中率。
4. 结合根因分析总结缓存变化。

步骤 1：解析缓存运行

如果 base/head 是缓存运行 ID 或仪表板 URL

直接获取每个运行：

tuist cache-run show <base-id> --json
tuist cache-run show <head-id> --json

如果 base/head 是分支名称

列出各分支上最近的缓存运行：

tuist cache-run list --git-branch <base-branch> --json --page-size 1
tuist cache-run list --git-branch <head-branch> --json --page-size 1

然后使用 tuist cache-run show <id> --json 获取完整详情。

默认值

• 如果未提供 base，则使用项目的默认分支（通常为 main）。
• 如果未提供 head，则检测当前 git 分支。

步骤 2：比较顶层指标

获取两个缓存运行后，比较以下内容：

指标	检查内容
duration	如果 head 慢了 >10%，则标记
status	如果 base 成功而 head 失败，则标记
cacheable_targets	留意目标数量是否发生变化
local_cache_target_hits	比较本地命中次数
remote_cache_target_hits	比较远程命中次数
is_ci	留意一个是否在 CI 上运行，另一个是否在本地运行

计算缓存命中率：

• Base：(local_hits + remote_hits) / cacheable_targets * 100
• Head：使用相同公式
• 差值：head_rate - base_rate

步骤 3：分析缓存失效

如果缓存命中率下降，关键问题是：哪些目标导致了失效级联？

tuist cache 中的缓存失效机制与 tuist generate 相同：

1. 某个“根因”目标发生了直接变更（源文件修改、构建设置变更等）。
2. 所有依赖根因目标的目标也会失效，因为它们的 dependencies 哈希会发生变化。
3. 单个根因变更可能引发级联，导致许多目标失效。

确定根因目标

如果没有模块缓存目标详情端点（可通过 MCP 使用），请使用以下启发式方法：

1. 检查 base 与 head 提交之间的 git diff，查看哪些文件发生了变化。
2. 将变更文件对应到 Tuist 目标／模块。
3. 有直接源文件变更的目标很可能是根因。
4. 仅因依赖哈希级联而发生变化的目标属于次级失效。

缓存失效的常见根因

原因	说明
源文件变更	目标源目录中的文件已修改
资源变更	资源、XIB、storyboard 或其他资源已更改
构建设置	目标或项目的构建设置已修改
依赖项变更	外部依赖项的版本已更改
Info.plist 变更	目标的 Info.plist 已修改
Entitlements 变更	Entitlements 文件已修改
部署目标	最低部署目标已更改
标头文件	公共标头文件或项目标头文件已更改
项目设置	共享的项目级设置已更改

步骤 4：评估影响

对缓存失效进行分类：

• 符合预期：有意修改了源文件，因此出现预期的缓存未命中。
• 意外：没有源文件变更，但缓存仍然失效（例如构建设置、Xcode 版本等）。
• 级联：小幅变更导致许多下游目标失效。

对于 tuist cache，还需考虑：

• 缓存预热策略：缓存运行是从头开始预热，还是增量预热？
• command_arguments 字段可以显示是否使用了不同的标志。

摘要格式

请按以下内容生成摘要：

1. 总体结论：缓存命中率有所提升、下降或保持稳定。
2. 缓存命中率：Base 与 head 的命中率及其差值。
3. 耗时：绝对变化和百分比变化。
4. 根因目标：哪些目标发生了直接变更。
5. 级联影响：有多少目标因依赖级联而失效。
6. 建议：如何尽量减少缓存失效。

示例：

Cache Run Comparison: base (run-123 on main) vs head (run-456 on feature-x)

Duration: 95.2s -> 142.8s (+50%) -- REGRESSION
Cache hit rate: 88% (44/50) -> 60% (30/50) (-28%) -- REGRESSION
Status: success -> success

Root cause: CoreModule had source changes (5 files modified).
This cascaded to 14 downstream targets that depend on CoreModule.

Cache invalidation breakdown:
- Direct changes: CoreModule (sources changed)
- Cascade: UIKit, Networking, Analytics, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting CoreModule into smaller, more focused modules
- Use interface/implementation module pattern for frequently-changed modules
- Run `tuist cache` on the feature branch after rebasing to warm caches

完成检查清单

• 解析了基准和最新缓存运行
• 对比了耗时和缓存命中率
• 确定了缓存失效的根因目标
• 分析了级联影响
• 提供了减少缓存未命中的可行建议