compare-gradle-builds

比较 Gradle 构建

快速入门

通常你会收到两个构建标识符（ID、仪表板 URL 或分支名称）。使用 Tuist MCP 工具执行以下步骤：

1. 使用 list_gradle_builds 查找每个分支上的构建。
2. 使用 get_gradle_build 获取 base 和 head 构建。
3. 使用 list_gradle_build_tasks 获取两个构建的任务级详情。
4. 比较耗时、状态、缓存命中率和任务结果。
5. 总结回归、改进和建议。

如果只提供了一个标识符，则使用项目的默认分支作为基准。

步骤 1：解析构建

如果 base/head 是构建 ID 或仪表板 URL

使用 get_gradle_build(build_run_id: "<id>") 直接获取每个构建。

如果 base/head 是分支名称

列出每个分支上的近期构建，并选择最新的构建：

list_gradle_builds(account_handle: "...", project_handle: "...", git_branch: "<branch>", page_size: 1)

然后使用 get_gradle_build(build_run_id: "<id>") 获取完整详情。

默认值

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

步骤 2：比较顶层指标

获取两个构建后，比较：

指标	检查内容
duration_ms	如果 head 比 base 慢 >10%，则标记
status	如果 base 成功而 head 失败，则标记
tasks_local_hit_count	比较本地缓存命中数
tasks_remote_hit_count	比较远程缓存命中数
tasks_executed_count	比较运行的任务数（数值越高表示缓存未命中越多）
cacheable_tasks_count	注意可缓存任务数是否发生变化
cache_hit_rate	(local_hits + remote_hits) / cacheable_tasks_count * 100
requested_tasks	确保两个构建运行了相同的任务，以便公平比较
gradle_version / java_version	注意会影响可比性的环境差异

计算缓存未命中差值：base_executed - head_executed。结果为正表示 head 执行的任务更少（有所改进）；结果为负表示出现回归。

步骤 3：深入分析任务

对两个构建都使用 list_gradle_build_tasks。比较每个任务路径的 duration_ms 和 outcome。

查找：

• 从 local_hit 或 remote_hit 变为 executed 的任务（缓存失效）。
• 从 executed 变为 local_hit 或 remote_hit 的任务（缓存有所改善）。
• 变为 failed 的任务（新增失败）。
• head 构建中出现的新任务。
• 耗时显著增加的任务。

按绝对时间差排序，找出最大的回归。

筛选任务

使用 outcome 筛选器，重点查看特定任务状态：

• list_gradle_build_tasks(build_run_id: "<id>", outcome: "executed") 仅查看已执行的任务。
• list_gradle_build_tasks(build_run_id: "<id>", outcome: "failed") 查看失败的任务。
• list_gradle_build_tasks(build_run_id: "<id>", cacheable: true) 仅查看可缓存的任务。

步骤 4：调查耗时回归

如果 head 构建明显更慢：

1. 检查 requested_tasks 是否不同（不同的任务集无法直接比较）。
2. 检查缓存命中率是否下降，这可能导致构建时间变长。
3. 查找从缓存命中变为 executed 的任务。
4. 检查 gradle_version 或 java_version 是否发生变化，因为这可能影响性能。
5. 比较各个任务的耗时，找出影响最大的任务。

步骤 5：调查缓存变化

比较任务级缓存行为：

• 命中率下降：可能的原因包括依赖项变化、构建配置变化，或改变缓存键的 Gradle 版本更新。
• 命中率提高：可能是缓存预热效果更好，或源代码变更更少。
• 任务数变化：新增或移除了模块或任务。
• 结果变化：任务在 up_to_date、local_hit、remote_hit 和 executed 之间转换，可以反映缓存效果。

第 6 步：检查构建上下文

比较环境详情：

• gradle_version 和 java_version：版本不同可能影响构建时间和缓存有效性。
• is_ci：CI 与本地构建的性能表现可能不同。
• git_branch 和 git_commit_sha：确认构建来自预期的提交。
• root_project_name：确保两个构建来自相同的项目结构。

摘要格式

请按以下内容生成摘要：

1. 总体结论：与基准相比更好、更差或持平。
2. 耗时：duration_ms 的绝对变化值和百分比变化。
3. 缓存命中率：命中率的变化及说明。
4. 任务结果：值得注意的结果变化（从命中变为执行、新增失败）。
5. 状态：任何状态变化（从成功变为失败，或反之）。
6. 环境：说明影响可比性的环境差异。
7. 建议：根据发现给出可执行的后续步骤。

示例：

Build Comparison: base (abc123 on main) vs head (def456 on feature-x)

Duration: 45200ms -> 62800ms (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 tasks went from cache hit to executed
Status: success -> success

Root cause: Cache hit rate dropped because 8 tasks had invalidated caches.
The :app:compileKotlin task changed from remote_hit to executed,
cascading to 7 downstream tasks.

Recommendations:
- Investigate which source changes invalidated :app:compileKotlin cache
- Consider splitting large modules to reduce cache invalidation cascading

完成清单

• 已解析基准构建和当前构建
• 已比较耗时、缓存和状态指标
• 已深入分析两个构建的任务级结果
• 已找出任何性能退化的根本原因
• 已提供可执行的建议