compare-generations

比较生成

快速开始

通常会收到两个生成标识符。按以下步骤操作：

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

第 1 步：确定生成记录

如果 base/head 是生成 ID 或仪表板 URL

直接获取每条记录：

tuist generate show <base-id> --json
tuist generate show <head-id> --json

如果 base/head 是分支名称

列出各分支上的近期生成记录：

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

然后运行 tuist generate show <id> --json 获取完整详情。

默认值

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

第 2 步：比较顶层指标

获取两条生成记录后，比较以下内容：

指标	检查内容
duration	如果 head 的耗时比 base 多出 >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 步：分析缓存失效

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

缓存失效通常按以下方式发生：

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

识别根因目标

如果无法使用模块缓存目标详情端点（可通过 MCP 使用），请参考以下经验做法：

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

缓存失效的常见根因

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

第 4 步：评估影响

对缓存失效进行分类：

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

总结格式

总结内容应包括：

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

示例：

Generation Comparison: base (gen-123 on main) vs head (gen-456 on feature-x)

Duration: 12.5s -> 28.3s (+126%) -- REGRESSION
Cache hit rate: 92% (46/50) -> 64% (32/50) (-28%) -- REGRESSION
Status: success -> success

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

Cache invalidation breakdown:
- Direct changes: FoundationModule (sources changed)
- Cascade: NetworkModule, AuthModule, UIModule, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting FoundationModule into smaller modules to reduce cascade impact
- The 14 cascaded targets could benefit from more granular dependency declarations
- If FoundationModule changes frequently, consider interface/implementation module splitting

完成检查清单

• 已确定 base 和 head 的生成记录
• 已比较耗时和缓存命中率
• 已识别缓存失效的根因目标
• 已分析级联影响
• 已提供可执行的建议，以减少缓存未命中