mcpField
C
compare-builds

compare-builds

github.com/tuist开发35300 次安装31 周前更新
代码仓库

关于 compare-builds

compare-builds 是用于分析 Tuist 构建结果的技能，面向需要比较基础构建与当前构建的开发者。它汇总耗时、状态、缓存和环境差异，并据此识别回归与改进。

主要功能

  1. 01解析并获取两次构建详情
  2. 02比较构建耗时与状态
  3. 03分析缓存命中和任务
  4. 04检查目标与问题详情
  5. 05根据差异提出建议

适用场景

  1. 01定位构建耗时回归
  2. 02检查构建失败或警告变化
  3. 03调查缓存命中率下降
  4. 04评估环境差异对比结果的影响

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tuist/agent-skills --skill compare-builds

安装后在 Claude Code 中输入/compare-builds确认已加载。

详细介绍

比较构建

快速开始

通常会收到两个构建标识符（ID、仪表板 URL 或分支名称）。请按以下步骤操作：

  1. 运行 tuist build list --json，查找每个分支上的构建。
  2. 分别对基准构建和当前构建运行 tuist build show <build-id> --json。
  3. 获取子资源详情：目标（tuist build xcode target list <id> --json）、问题（tuist build xcode issue list <id> --json）和缓存任务（tuist build xcode cache-task list <id> --json）。
  4. 比较耗时、状态、缓存命中率及其他指标。
  5. 总结回归、改进和建议。

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

第 1 步：确定构建

如果基准构建/当前构建是构建 ID 或仪表板 URL

直接获取每个构建：

tuist build show <base-id> --json
tuist build show <head-id> --json
如果基准构建/当前构建是分支名称

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

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

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

默认值
  • 如果未提供基准构建，请使用项目的默认分支（通常是 main）。
  • 如果未提供当前构建，请使用 git rev-parse --abbrev-ref HEAD 检测当前 Git 分支。

第 2 步：获取子资源详情

使用 tuist build show <id> --json 获取两个构建后，深入查看子资源，以便进行更详细的比较。

比较目标
tuist build xcode target list <base-id> --json
tuist build xcode target list <head-id> --json

查找状态发生变化（例如，从成功变为失败）或耗时显著变化的目标。

比较问题
tuist build xcode issue list <base-id> --json
tuist build xcode issue list <head-id> --json

查找当前构建中新增的警告或错误。

比较缓存任务
tuist build xcode cache-task list <base-id> --json
tuist build xcode cache-task list <head-id> --json

确定哪些具体目标未命中或命中了缓存，以及两个构建之间是否发生变化。

第 3 步：比较顶层指标

获取两个构建后，比较：

指标检查内容
duration如果当前构建比基准构建慢 >10%，则标记
status如果基准构建成功而当前构建失败，则标记
cacheable_tasks_count记录任务数量是否变化
cacheable_task_local_hits_count比较本地命中次数
cacheable_task_remote_hits_count比较远程命中次数
缓存命中率(local_hits + remote_hits) / cacheable_tasks_count * 100
category记录一个构建是 clean、另一个是 incremental 的情况（此时耗时比较意义较小）
scheme / configuration确保两个构建使用相同的 scheme 和 configuration，以便公平比较

计算缓存未命中数差值：base_misses - head_misses。正值表示当前构建的未命中数更少（有所改进）。负值表示出现回归。

第 4 步：调查耗时回归

如果当前构建明显更慢：

  1. 检查 category 是否不同（clean 构建和 incremental 构建无法直接比较）。
  2. 检查缓存命中率是否下降，这可能导致构建耗时增加。
  3. 如果两个构建都是 incremental，且缓存命中率相近，那么回归很可能出在编译耗时上。

第 5 步：调查缓存变化

比较缓存统计数据：

  • 命中率下降：可能原因包括依赖项变化、构建设置变化或 Xcode 版本更新。
  • 命中率提高：可能是缓存预热效果更好，或源代码变更更少所致。
  • 任务数量变化：新增或移除了目标。

第 6 步：检查构建上下文

比较环境详情：

  • xcode_version 和 macos_version：版本不同可能影响构建耗时和缓存有效性。
  • is_ci：CI 构建和本地构建的性能特征可能不同。
  • git_branch 和 git_commit_sha：确认构建来自预期的提交。

总结格式

请按以下内容总结：

  1. 总体结论：与基准构建相比，是更好、更差还是持平。
  2. 耗时：绝对变化和百分比变化。
  3. 缓存命中率：命中率变化及其说明。
  4. 状态：状态是否发生变化（通过变为失败，或反之）。
  5. 环境：指出影响可比性的环境差异。
  6. 建议：根据调查结果提出可执行的后续步骤。

示例：

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

Duration: 45.2s -> 62.8s (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 new cache misses
Status: success -> success

Root cause: Cache hit rate dropped due to 8 targets with invalidated caches.
The dependency hash changed for FeatureModule, cascading to 7 downstream targets.

Recommendations:
- Investigate why FeatureModule's cache was invalidated
- Consider splitting large targets to reduce cascade impact

完成清单

  • 解决了基线和最新提交的构建问题
  • 获取了子资源详情（目标、问题、缓存任务）
  • 对比了耗时、缓存和状态指标
  • 找出了所有回归问题的根本原因
  • 提供了可执行的建议

评论

支持 Markdown