xcode-build-orchestrator

Xcode 构建编排器

将此技能用作 Xcode 端到端构建优化工作的推荐优先入口。

不容妥协的规则

• 墙钟构建时间（开发者等待的时长）是首要成功指标。每项建议都必须说明其对开发者实际等待时间的预期影响。
• 从推荐模式开始。
• 做出更改前先进行基准测试。
• 未经开发者明确批准，不得修改项目文件、源文件、包或脚本。
• 保留每项建议的证据链。
• 经批准的更改完成后重新进行基准测试，并报告墙钟时间变化。

两阶段工作流

此编排分为两个不同阶段，中间由开发者进行审查。

阶段 1 —— 分析（仅提供建议）

以 Agent 模式运行此阶段，因为 Agent 需要执行构建、运行基准测试脚本、写入基准测试产物并生成优化报告。但阶段 1 必须严格遵循仅提供建议：不得修改任何项目文件、源文件、包或构建设置。Agent 在此阶段创建的文件只能是基准测试产物和 .build-benchmark/ 中的优化计划。

1. 收集构建目标的上下文信息：工作区或项目、方案、配置、目标设备和当前痛点。如果 .xcworkspace 和 .xcodeproj 同时存在，优先选择 .xcodeproj，除非构建需要工作区中包含的子项目。引用外部项目的工作区可能会因这些项目尚未检出而构建失败。
2. 如果没有最新的基准测试结果，运行 xcode-build-benchmark 建立基准。基准测试脚本会自动检测 COMPILATION_CACHE_ENABLE_CACHING = YES，并包含用于衡量真实开发者体验（暖缓存）的缓存清理构建。如果构建编译失败，检查 git log，查找近期可成功构建的提交。在工作树中工作时，可以从功能分支中挑选针对性的构建修复提交，以恢复可构建状态。如果 SPM 包在 exclude: 路径中引用了被 git 忽略的目录（例如 __Snapshots__），请在构建前创建这些目录——工作树不包含被 git 忽略的内容，否则 xcodebuild -resolvePackageDependencies 会崩溃。
3. 验证基准测试产物中的 timing_summary_categories 非空。如果为空，可能是计时摘要解析器运行失败——请重新解析原始日志或手动检查。如果启用了 COMPILATION_CACHE_ENABLE_CACHING，还要确认产物包含 cached_clean 运行结果。
   • 基准测试可信度检查：对于每种构建类型（清理构建、缓存清理构建、增量构建），比较最小值和最大值。如果差值（最大值 - 最小值）超过中位数的 20%，请指出基准测试的方差较高，并建议在得出结论前增加重复次数（至少运行 5 次）。高方差会使真实改进难以与噪声区分。应用更改后，只有当更改后的中位数落在基准测试最小值至最大值范围之外时，才能声称有所改进。
4. 如果增量构建是主要痛点，且可用 Xcode 16.4 或更高版本，建议开发者启用 Task Backtraces（Scheme Editor > Build 标签页 > Build Debugging > "Task Backtraces"）。此功能会揭示每项任务重新运行的原因，这对于诊断意外的重新规划或输入失效至关重要。在分析中加入任何 Task Backtrace 证据。
5. 确定编译任务是否可能阻塞实际构建进度，还是仅在消耗并行 CPU 时间。将计时摘要中各类别的秒数总和与实际构建耗时的中位数比较：如果总和达到中位数的 2 倍或以上，则大部分工作是并行化的，修复编译热点不太可能缩短等待时间。如果 SwiftCompile、CompileC、SwiftEmitModule 或 Planning Swift module 在计时摘要中占主导地位，且看起来处于关键路径上，请运行 diagnose_compilation.py，以捕获类型检查热点。如果这些任务是并行化的，仍需运行诊断，但应将发现标注为“并行效率改进”，而非“构建时间改进”。
6. 阅读各项技能的 SKILL.md 并遵循其工作流程，运行与现有证据相符的专项分析：
   • xcode-compilation-analyzer
   • xcode-project-analyzer
   • spm-build-analysis
7. 将发现汇总为一份按优先级排序的改进计划。
8. 使用 generate_optimization_report.py 生成 Markdown 优化报告，并保存到 .build-benchmark/optimization-plan.md。该报告包含构建设置审计、计时分析、按优先级排序的建议以及审批清单。
9. 停止并向开发者提交计划以供审阅。

开发者审阅 .build-benchmark/optimization-plan.md，勾选希望实施的建议对应的审批框，然后触发第 2 阶段。

第 2 阶段——执行与验证（Agent 模式）

开发者审阅并批准计划中的建议后，以 Agent 模式运行此阶段。通过阅读 xcode-build-fixer 的 SKILL.md 并应用其工作流，将所有实施工作委托给它。

10. 阅读 .build-benchmark/optimization-plan.md，并根据审批清单找出已批准的项目。
11. 将已批准的计划交给 xcode-build-fixer。修复工具会应用每项已批准的更改、验证编译，并重新进行基准测试。
12. 将验证结果追加到优化计划中：更改后的中位数、绝对和百分比变化，以及置信度说明。
13. 报告更改前后的结果，以及任何尚待跟进的优化机会。

优先级规则

目标是缩短开发者等待构建完成的时间。

1. 确定开发者最主要的痛点（全新构建、增量构建或两者都有），以及测得的实际耗时中位数。
2. 判断哪些因素可能正在阻塞实际耗时的缩短：
   • 如果计时摘要中所有类别的秒数之和达到实际耗时中位数的 2 倍或以上，说明大部分工作是并行执行的。修复编译热点不太可能缩短等待时间。
   • 如果某个串行类别（例如 PhaseScriptExecution、CompileAssetCatalog、CodeSign）占实际耗时的很大一部分，那么它才是真正的瓶颈。
   • 如果 Planning Swift module 或 SwiftEmitModule 主导了增量构建耗时，原因可能是失效范围或模块大小，而不是单个文件的编译速度。
3. 按可能节省的实际耗时对建议排序，而不是按累计任务耗时的减少量排序。
4. 除非有证据表明源代码级编译优化处于关键路径上，否则其优先级不应高于项目、依赖图或配置方面的优化。

优先选择可测量、可撤销且风险低的更改。

建议的影响说明

向开发者提出的每项建议都必须包含以下一种影响说明：

• “预计可将您的[全新/增量]构建耗时缩短约 X 秒。”
• “可减少并行编译工作，但其他任务耗时相当，因此不太可能缩短构建等待时间。”
• “对等待时间的影响尚不确定——应用后请重新进行基准测试以确认。”
• “预计不会缩短等待时间。收益是[构建结果更确定/更快切换分支/降低 CI 成本]。”
• 对于 COMPILATION_CACHE_ENABLE_CACHING，具体说明：“在测试过的项目中，全新构建速度提升了 5-14%。缓存会在构建之间保留时，实际工作流中的收益会不断累积——例如切换分支、拉取更改，以及使用持久 DerivedData 的 CI。”

绝不要把累计任务耗时节省量作为主要影响说明。如果某项更改减少了 5 秒的并行编译工作，但另一个耗时相当的任务仍在运行，那么开发者的等待时间不会改变。

审批关卡

在实施任何更改之前，先提供简短的审批清单，其中包括：

• 建议名称
• 预期的等待时间影响（使用上述影响说明）
• 证据摘要
• 受影响的文件或设置
• 风险等级：低、中或高

等待开发者明确批准。

获批后的执行

获得批准后，将工作委托给 xcode-build-fixer：

• 修复工具只实施已批准的项目
• 原子化应用更改，并将范围控制在必要范围内
• 记录与原始建议计划的任何偏差
• 按相同的基准测试规范重新进行基准测试

最终报告

开头用通俗语言说明实际耗时结果，例如：“现在干净构建耗时 82 秒（原来是 86 秒）——快了 4 秒。”然后包括：

• 基线干净构建和增量构建的实际耗时中位数
• 更改后干净构建和增量构建的实际耗时中位数
• 实际耗时的绝对变化量和百分比变化
• 做了哪些更改
• 有意保持不变的内容
• 如果噪声导致结论不够有力，请说明置信度；如果基准测试方差较高（最小值到最大值的范围超过中位数的 20%），请明确指出，不要将有噪声的数据说成确定的改进或退步
• 如果累计任务指标有所改善，但实际耗时没有改善，请明确说明：“编译器工作量减少了，但构建等待时间没有改善。当 Xcode 将这些任务与其他耗时相当的工作并行运行时，这是预期情况。”
• 可直接粘贴到社区的结果行，以及用于创建 PR 的链接（参见报告模板）

推荐的命令路径

python3 scripts/benchmark_builds.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --output-dir .build-benchmark

对于 macOS 应用，请使用 --destination "platform=macOS"。对于 watchOS，请使用 --destination "platform=watchOS Simulator,name=Apple Watch Series 10"。对于 tvOS，请使用 --destination "platform=tvOS Simulator,name=Apple TV"。省略 --destination 可使用方案的默认值。

若要测量实际的增量构建（修改文件后重新构建），而不是零更改构建，请添加 --touch-file path/to/SomeFile.swift。

编译诊断

python3 scripts/diagnose_compilation.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --threshold 100 \
  --output-dir .build-benchmark

优化报告

python3 scripts/generate_optimization_report.py \
  --benchmark .build-benchmark/<artifact>.json \
  --project-path App.xcodeproj \
  --diagnostics .build-benchmark/<diagnostics>.json \
  --output .build-benchmark/optimization-plan.md

其他资源

• 报告模板参见 references/orchestration-report-template.md
• 基准测试产物要求参见 references/benchmark-artifacts.md
• 建议格式参见 references/recommendation-format.md
• 构建设置最佳实践参见 references/build-settings-best-practices.md