ci-integration

CI 集成

价值： 反馈——CI 流水线会产生信号。确定的交互模式能确保这些信号得到正确接收、分类和处理。不规范的 CI 交互（在运行失败时继续推送、忽略不稳定测试）会削弱信号，直到流水线沦为噪声。

目的

传授规范的 CI/CD 交互方式：一次只处理一个待完成的运行、结构化的失败分诊、针对机械性故障的自动自愈，以及供流水线使用的结构化证据输出。防止最常见的 CI 故障模式：还没弄清上次运行失败的原因就再次推送。

实践

推送并等待

一次只处理一个待完成的 CI 运行。运行进行中时绝不推送。

1. 推送提交
2. 轮询或等待 CI 运行完成
3. 采取任何操作前，先阅读完整结果
4. 只有运行完成后（无论通过还是失败），才能再次推送

应该：

• 开始任何需要推送的新工作前，等待 CI 完成
• 阅读完整的 CI 输出，而不只是状态徽章

不应该：

• 在上一次运行仍在等待时推送“修复”
• 假设运行会通过并推送后续提交
• 取消运行以便推送新运行（除非该运行明显已过时）

失败分诊

尝试修复前，先对每个 CI 失败进行分类。分类决定修复策略。

分类	信号	修复策略
test-failure	测试断言失败	转交给 debugging-protocol
lint-failure	Linter 或格式化工具报错	自动修复：运行格式化工具，提交并重新推送
build-failure	编译或依赖错误	分析依赖，检查锁文件
flaky-test	测试失败后重试通过，且代码没有变更	标记并跟踪（见下文）
infra-failure	网络、运行器或服务错误	重试（最多 2 次），然后升级处理

阅读完整的 CI 日志以进行分类。不要只凭状态猜测。

自愈

对于有确定性修复方法的机械性故障，应自动解决：

1. Lint/格式错误： 使用项目的格式化工具或 Linter 进行自动修复，提交结果并重新推送。这只重试一次——如果格式化工具未能解决问题，则归类为 build-failure。
2. 基础设施故障： 重试 CI 运行（最多 2 次）。如果所有重试都失败，则将基础设施错误详情升级给用户处理。
3. 测试失败： 绝不自动重试。转交给 debugging-protocol 调查。测试失败是信号，不是噪声。
4. 构建失败： 检查依赖锁文件、构建配置和环境差异。不要盲目重试。

不稳定测试检测

如果测试在重试后通过，且期间没有任何代码变更，则该测试属于不稳定测试。

检测到后：

1. 标记该测试，并记录其名称、文件以及不稳定运行中的失败输出
2. 记录到项目记忆中（如果启用了 factory 模式，则记录到 .factory/audit-trail/flaky-tests.json，否则记录到项目笔记中）
3. 向用户报告——不稳定测试会侵蚀对 CI 的信任，必须解决
4. 在不稳定问题解决前，不要将一次不稳定测试后的通过视为质量门禁所认可的真正通过

结构化输出

每次 CI 交互都会生成一个 CI_RESULT 证据包：

{
  "run_id": "string (CI run identifier)",
  "status": "string (passed | failed | cancelled)",
  "duration": "number (seconds)",
  "failure_type": "string (test-failure | lint-failure | build-failure | flaky-test | infra-failure) -- omit if passed",
  "failure_details": "string (summary of failure) -- omit if passed",
  "fixes_applied": ["string (description of each auto-fix applied)"],
  "retry_count": "number (0 if no retries)"
}

流水线编排器和审计跟踪会使用此证据包。始终生成该证据包，即使运行通过也是如此。

强制执行说明

• 流水线模式：门禁模式。CI 通过或失败会以机械方式决定是否允许合并。
• 独立模式：建议模式。Agent 自行遵守推送并等待的规范。

硬性约束：

• 推送并等待：流水线模式下为 [H]，独立模式下为 [RP]
• 不将不稳定测试后的通过计为真正通过：[H]

约束

• 推送并等待：一次只能有一个待处理的运行。不是“每个分支一个”，也不是“每种变更一个”。如果 CI 运行正在进行，无论变更看起来多么无关，都不要推送。遵守这条纪律是因为 CI 资源竞争和合并顺序都很重要。
• 失败分类：先分类，再尝试修复。不要“我试了个修复，结果成功了，所以这肯定是 lint 失败”。分类决定修复策略，而不是反过来。如果你无法有把握地分类，就继续调查——不要猜测并直接修复。
• 不稳定测试：不稳定测试是指在相同代码上产生不同结果的测试。“不改代码重试后通过”就是定义。如果你更改了环境，那么重试就不能证明测试不稳定——它证明的是测试依赖环境。这是两种不同的问题，需要采用不同的修复方法。

验证

每次与 CI 交互后，请确认：

• 推送前等待上一次 CI 运行完成
• 阅读完整的 CI 输出（而不只是状态）
• 尝试修复前先对失败类型进行分类
• 根据分类采用正确的修复策略
• 未重试测试失败（应转交给 debugging-protocol 处理）
• lint/格式自动修复仅尝试一次
• 基础设施重试不超过 2 次
• 已标记并记录不稳定测试
• 已生成 CI_RESULT 证据包

如果有任何一项未满足，请先重新执行相关实践，再继续。

依赖项

此技能可独立用于任何具有 CI/CD 流水线的项目。它与以下内容集成：

• debugging-protocol： 测试失败会转交给调试协议进行系统化调查，而不是盲目尝试修复
• tdd： TDD 循环期间的 CI 失败会反馈到 RED-GREEN 循环中；CI 测试失败意味着循环尚未完成
• pipeline： 在工厂模式中使用时，流水线编排器会使用 CI_RESULT 数据包评估质量门禁

缺少依赖项？请安装：

npx skills add jwilger/agent-skills --skill debugging-protocol