企业官网建设流程全解析

Xcode-Build-Optimization-Agent-Skill 是一个开源的 Xcode 构建优化 Agent Skill，它的核心设计是 Recommend-First（推荐优先）批准机制：Agent 先分析、只推荐、绝不擅自改动，每一条优化建议都要经你逐条批准后才执行，最后再跑基准测试验证提速效果。这套"先推荐、后批准、再执行"的流程，让 AI 驱动的 Xcode 构建性能优化既安全又可控。

为什么 AI 优化构建性能需要"批准"这一步？

让 AI 直接动项目代码，风险是显而易见的：

• 误操作无法完全回滚：改错一个构建设置或脚本阶段，可能让编译直接失败；
• 优化效果需要证据：Xcode 大量任务并行执行，"省下的任务时间"未必等于"省下的等待时间"，盲目修改可能毫无收益甚至倒退；
• 优化存在权衡：比如开启编译缓存后，冷启动的 clean build 可能略变慢，但缓存命中的构建会明显变快，这种取舍需要人来判断。

所以这个项目把"推荐"和"修改"彻底分开了。官方规则写得很直白（见 AGENTS.md）：

Recommend-first by default. Never apply project, source, or package changes without explicit developer approval.（默认推荐优先。未经开发者明确批准，绝不修改项目、源码或依赖包。）

说明：上图用于展示 Benchmark → Analyze → Plan → You review & approve → Fix → Verify 的整体思路，流程细节可参考 README.md 中的工作流图。

核心流程：两阶段工作流

整个优化由xcode-build-orchestrator（总控技能）串联五个专项技能完成，中间被一道开发者审阅关卡切开：

阶段一：只分析、只推荐

1. 先跑基准测试：对 clean build（全新构建）和 incremental build（增量构建）分别测量多轮，取中位数作为基线；
2. 执行 40 余项检查：覆盖构建设置、脚本阶段、编译热点、SPM 包依赖等，完整清单见 OPTIMIZATION-CHECKS.md；
3. 合并为一份优化计划：生成到.build-benchmark/optimization-plan.md，包含基线数据、设置审计结果、按优先级排序的建议列表，以及一份批准清单（Approval Checklist）；
4. 停下来，等你审阅——这一步是机制的关键：Agent 到此为止，不碰你的任何项目文件。

阶段二：只执行被批准的项目

你打开优化计划文件，在批准清单里勾选（[x]）想要的项，然后让 Agent 执行。xcode-build-fixer会：

• 只实现被勾选的项，一次改一个逻辑修复，保证可审查、可回滚；
• 每次修改后验证编译通过；
• 用相同的输入重新跑基准测试，报告优化前后的真实等待时间差；
• 把验证结果追加回优化计划文件，形成完整证据链。

一个被驳回的建议就是被"跳过"了——机制本身不会执行任何未批准的改动。

批准清单长什么样？

优化计划文件里的批准清单项，由 scripts/generate_optimization_report.py 自动生成，每条包含名称、预期收益、可操作性、风险等级：

## Approval Checklist - [ ] 1. Guard a release-only symbol upload script -- Impact: Expected to reduce your incremental build by approximately 6 seconds. | Actionability: repo-local | Risk: Low - [ ] 2. Enable COMPILATION_CACHE_ENABLE_CACHING -- Impact: 5-14% faster cached clean builds | Actionability: repo-local | Risk: Low - [ ] 3. Pin branch-tracked SPM dependency to a tag -- Impact: Impact on wait time is uncertain -- re-benchmark to confirm | Actionability: package-manager | Risk: Medium

你只需把[ ]改成[x]，就可以决定"哪些做、哪些不做"。

每条建议都带结构化字段

为了让批准决策有据可依，所有技能的推荐都遵循统一的格式定义，见 references/recommendation-format.md。每条建议的必备字段包括：

其中actionability分四档，帮你快速判断风险面：

• repo-local—— 改动完全在项目内，无外部副作用；
• package-manager—— 涉及 SPM/CocoaPods 配置，影响面大，必须前后对比基准；
• xcode-behavior—— 成本由 Xcode 内部机制导致，只能报告、不能承诺修复；
• upstream—— 需要改第三方依赖，本地无法解决。

这个设计直接决定了 Agent 的"权限边界"：它有能力发现xcode-behavior类问题，但不会替你打补丁——这正是可控性的来源。

执行环节的"安全阀"

批准只是第一道关，执行环节还有多重保护（见 skills/xcode-build-fixer/SKILL.md）：

1. 回归评估：某项改动变慢不等于真回退。比如开启编译缓存后标准 clean build 可能略慢，但缓存命中的构建（切分支、拉取代码的真实场景）会更快——这种情况按"净收益"处理，不会被误回滚；
2. 明确何时回滚：只对"投机性改动"（源码重构、脚本改造等），如果所有构建类型都变慢，才标记Recommend revert；
3. 最佳实践设置不轻易回退：像COMPILATION_CACHE_ENABLE_CACHING = YES、EAGER_LINKING = YES这类 Apple 推荐的现代默认值，即使当次基准没有可见收益也会被保留——它们是为未来 Xcode 版本做铺垫；
4. 执行报告留痕：最终产出一份结构化 Execution Report，列出每一项改动的状态：Kept/Reverted/Blocked/No improvement，以及最终的累计提速结果。

一句话总结：批准的每一项，结果都被测量、被记录、被对比。

如何上手使用这套机制？

1. 安装全部 6 个技能（总控技能依赖各专项技能），手动安装时从skills/目录拷贝技能文件夹即可，仓库结构见 skills/xcode-compilation-analyzer/SKILL.md 等入口文件；

2. 对你的 AI 编码工具说一句：

   Use the /xcode-build-orchestrator skill to analyze build performance and come up with a plan for improvements.

3. 等待阶段一完成，审阅.build-benchmark/optimization-plan.md，勾选批准清单；

4. 再让 Agent 执行已批准项并重新跑基准验证。

整个过程中，.build-benchmark/目录就是你的证据仓库：基准 JSON、原始构建日志、优化计划全部落盘（格式规范见 references/benchmark-artifacts.md）。这份计划文件可以分享给队友、放进 PR 审查、也可以随时间做 diff 对比。

总结：把"信任"变成"流程"

Xcode 构建优化 Agent Skill 的 Recommend-First 机制，本质上回答了"AI 改我的项目我放不放心"这个问题：

• 安全：分析与修改严格分阶段，未批准 = 不执行；
• 可控：每条建议带证据、风险等级和预期收益，批准权在你手里，粒度精确到单条建议；
• 可验证：所有修改都以 wall-clock 等待时间为准绳，改前改后各跑一次基准，结果写回计划文件。

如果你想了解它具体检查哪些构建设置和编译热点，可以继续阅读 OPTIMIZATION-CHECKS.md；关于技能编写与协作规范，见 CONTRIBUTING.md。让 AI 帮你优化 Xcode 构建速度，从此有据可依、步步可控。