ci-optimize

CI 优化

在进行更改前，先测量 GitHub Actions 等待时间。保留必需的检查、构建产物和失败行为。

规范

铁律： 在提出具体编辑方案前，先采集基线数据。

进行破坏性清理、使用付费基础设施、安装依赖、编辑源代码或远程派发前，必须获得明确授权。

危险信号 — 注意到以下情况时立即停止：

• 为了缩短耗时而移除了某项检查、构建产物、工作负载或失败路径。
• 将重新运行、部分作业页面或已更改的验证约定纳入主要样本组。
• 用本地结果或零退出状态替代 CI 对比。

理由	问题所在	必须采取的行动
“缓存更改显而易见，我可以现在就应用。”	测量不代表批准修改。	提交方案并等待。
“并行作业的耗时要相加。”	指标的结束时间是所选作业中最晚的完成时间。	从运行创建时开始测量。
“重新运行使用相同的工作流，因此具有可比性。”	架构版本 1 将重新运行排除在主要等待时间之外。	将重新运行仅作为诊断数据。

工作流

1. 阅读仓库说明。确定权威验证命令。
2. 选择一个工作流、事件类别、工作负载、验证约定和所选作业集。
3. 在采集运行数据前阅读 references/github.md。在构造输入前阅读 references/schemas.md。
4. 采集基线初始尝试的数据，以及每个所选尝试对应的作业页面。
5. 采集计划样本数及用于排除样本的余量。规范化基线数据。
6. 检查符合条件和已排除的观测数据。
7. 对于混合请求，在定义本地计时前阅读 references/local.md。制定本地运行计划，注明确切命令、预热和样本数量、缓存操作、隔离方式、输出路径及成本。
8. 对于混合请求，获得对本地运行计划的明确批准。
9. 提交一项具体的编辑方案。
10. 说明受影响的文件、预期收益、风险、验证方式以及任何既定回滚方案。
11. 在编辑任何受版本控制的源文件、派发运行或执行远程修改前，获得对编辑方案的明确批准。
12. 通过现有的实现和验证工作流应用已批准的更改。
13. 使用相同的边界，重新完成完整的 CI 数据采集。计入排队和启动延迟。
14. 规范化更改后的数据集。使用明确的最小样本数对数据集进行比较。
15. 阅读比较结果 JSON。要求 comparability: true。
16. 验证必需的检查、覆盖率、构建产物和失败行为。
17. 报告观测结果，不承诺具体的数值提升。报告完成后即停止；若缺少必需输入，也应停止。

仅 CI 请求可以跳过本地计时。本地计时无法证明 CI 等待时间有所改善。不同缓存样本组应分开处理。

致谢用于记录已批准的环境、缓存状态或本地命令差异。 致谢不能豁免工作负载、验证、身份或等效覆盖率不匹配。 致谢不能证明因果关系，也不能授权编辑。

命令

从实际加载的 SKILL.md 所在目录解析 CI_OPTIMIZE_HELPER。 使用 scripts/ci_optimize.py 前先解析符号链接。 切勿根据使用方仓库的当前目录推导 helper 路径。 该 helper 不会执行命令、编辑工作流、安装依赖、派发运行或提交更改。

从使用方仓库的工作目录运行命令：

python3 "$CI_OPTIMIZE_HELPER" ci --input BEFORE-CAPTURES.json --output BEFORE.json
python3 "$CI_OPTIMIZE_HELPER" ci --input AFTER-CAPTURES.json --output AFTER.json
python3 "$CI_OPTIMIZE_HELPER" compare --before BEFORE.json --after AFTER.json --minimum-samples N --output COMPARISON.json

对各个获批的缓存样本组分别运行此序列，并使用不同的输出路径。 仅在替换已存在的明确指定输出文件时使用 --force。 运行 python3 "$CI_OPTIMIZE_HELPER" --self-test，检查被排除的运行是否会更改作业集。

证据与报告

CI 指标涵盖从创建运行到所选作业最近一次完成的时间。 主要队列仅使用首次尝试的数据。不要汇总并行作业的持续时间。 报告状态、工作流和所选作业边界、符合条件和排除的数量、中位数与范围，以及差值。 报告检查项、构件、限制、下一步审批和证据路径。 保留被排除的观测值及其原因。 回复不超过 200 个字。 不要重命名无关的门禁、添加自动修复检查或更改本地构建行为。