Loop Engineering 实战深入 CI Triage Skill 与 CI 失败分级处置方案loop-engineering【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering导读在 AI 编码 Agent 驱动的 CI 运维循环CI Sweeper Loop中最危险的错误不是修不动而是修错对象——把基础设施抖动当成回归去改代码、把真实回归当成 flake 去忽略。本指南围绕 loop-engineering 仓库中 Grok 版ci-triage技能的完整定义讲解如何在任何修复动作之前对 CI 失败进行结构化分类与处置决策并串联minimal-fix、loop-verifier、ci-sweeper-state.md与 GitHub Actions 事件驱动触发形成一套可落地、可审计、可控制成本的失败处理流水线。读完本文你将掌握技能定义的前置元数据规范、逐失败的标准输出模板、flake/regression/env/config 四分类判定规则以及env 类失败必须升级人工、不得代码修复等关键安全边界的完整落地方式。1. ci-triage 是什么CI Sweeper 循环的强制入口ci-triage是 patterns/ci-sweeper.md 中列出的Required Skills必需技能之一职责是Parse CI failures, identify failing job/step, classify as flake, regression, env, or config. Use in CI sweeper loopsbefore any fix attempt.翻译过来就是解析 CI 日志 → 定位失败的 job/step → 把失败归类为 flake偶发、regression回归、env环境、config配置四类之一。最关键的一句话在末尾在任何修复尝试之前使用。这是整个技能存在的意义——triage 是后续所有动作修、观察、升级的唯一裁决入口跳过 triage 直接改代码是 CI Sweeper 循环最典型的失败模式。在 loop-engineering 中Grok 版技能定义于 starters/ci-sweeper/.grok/skills/ci-triage/SKILL.md同时仓库还提供了 OpenCode 版变体 starters/ci-sweeper-opencode/skills/ci-triage/SKILL.md分类视角略有差异后文第 4 节会对照说明以及.codex、.claude等目录下的同类技能说明该技能被设计为跨工具分发的通用资产而不仅是 Grok 专用。1.1 为什么 triage 必须是修复前的强制步骤从源码结构看CI Sweeper 的典型循环见 patterns/ci-sweeper.md 的 How the Loop Runs要求对每个新失败先分类Discover CI failures on watched branches发现分支上的 CI 失败Classify: flake vs real regression vs infra分类flake、真实回归、还是基础设施问题若为 flake → 加入 Watch 列表不自动修复若可行动 → 打开 worktree实现子 Agent 起草修复Verifier 子 Agent 独立校验循环守卫loop-guard在每次重试前做熔断检查清理已解决的失败。可以看到分类第 2 步决定了后续分支走向它把无条件重试/无条件修复的朴素行为替换成了按类处置。这也是该技能description中强调 Use in CI sweeper loops before any fix attempt 的原因。2. 技能定义剖析frontmatter 元数据与调用方式Grok 版ci-triage技能以 Markdown YAML frontmatter 的形式存在完整头部如下--- name: ci-triage description: Parse CI failures, identify failing job/step, classify as flake, regression, env, or config. Use in CI sweeper loops before any fix attempt. user_invocable: true ---name: ci-triage技能唯一标识供循环编排层如opencode run Run ci-triage按名引用description供 LLM 理解技能适用场景的语义描述同时也是 Agent 在技能路由阶段判断该不该加载这个技能的依据。这里的描述精确锁定了三件事——解析对象CI failures、产出物job/step 定位 四分类、使用时机fix 之前user_invocable: true声明该技能可由用户直接调用而不必等循环自动触发。从 starters/ci-sweeper-opencode/LOOP.md 可以看到它在 OpenCode 编排中的实际用法opencode run Run ci-triage --agent loop-triage即通过 cron/systemd 等调度器按 5–15 分钟的节奏周期触发 triage 任务这与 patterns/ci-sweeper.md 推荐的调度建议活跃开发期/loop 15m、main 变红时/loop 5m一致。3. 输出契约每个失败的标准化报告模板技能定义了**逐失败per failure**的结构化输出模板这是 triage 结果能被下游state 文件、minimal-fix、verifier、人类审查可靠消费的关键### Failure — branch sha - Job / step: - Error (1-3 lines): - Classification: flake | regression | env | config - Actionable: yes | no - Suggested loop action: minimal-fix | watch | escalate-human逐字段解读字段含义填写要点branch sha失败所在分支与 commit必须精确到 SHA这是后续跟踪与复现的锚点Job / step失败的 CI job 与 step定位到具体测试任务而不是笼统写CI 挂了Error (1-3 lines)精简错误摘要限制在 1–3 行防止上下文膨胀、便于人类快速扫读Classification四分类之一见第 4 节判定规则Actionable是否可自动处置由分类推导flake/env 通常不可行动Suggested loop action建议的循环动作minimal-fix/watch/escalate-human三选一这个模板实际上把输出与决策绑定在了一起每个失败不仅要有诊断前三项还必须给出处置建议后三项。输出不完整 triage 未完成这是该模板设计上的硬约束。对比 OpenCode 版 starters/ci-sweeper-opencode/skills/ci-triage/SKILL.md其输出要求略有差异但思路一致——不再输出单条 markdown 模板而是要求把结果回写进状态文件按类别列出所有失败List of failures by category每个条目的建议下一步动作Suggested next action per item每个条目的尝试次数Attempt count per item两种版本一个面向逐失败报告一个面向状态文件聚合可结合使用单次 triage 先产出逐失败报告再聚合进ci-sweeper-state.md供跨周期跟踪。4. 分类规则flake / regression / env / config 四类判定Grok 版技能给出了精确到可执行的分类判据分类判定特征flake偶发重试即通过无代码变更intermittent, passed on retry, no code changeregression新失败与最近的 commit 强相关new failure correlated with recent commitenv运行器、注册表、密钥、配额问题runner, registry, secrets, quotaconfig工作流、依赖安装、缓存问题workflow, dependency install, cache4.1 flake 的处置Watch不自动修patterns/ci-sweeper.md 明确写入 Flake PolicyIf the same test failed and passed on retry without code change → Watch, do not auto-fix.也就是说一旦 triage 判定为 flake循环动作是watch而非minimal-fix。starters/ci-sweeper/README.md 也复述了同一条策略可见这是整个 ci-sweeper 体系的通用铁律。原因很朴素用代码修复一个重试就过的问题等于在代码库里制造无意义的 diff还会掩盖真正的根因。4.2 regression 的处置进入修复通道regression 是唯一默认进入自动修复通道的分类新失败 与最近提交相关 → 有明确的怀疑对象 →Suggested loop action: minimal-fix。随后由 templates/SKILL.md.minimal-fix 定义的最小修复技能接手详见第 7 节。4.3 env / config基础设施问题与配置问题envrunner运行器资源/崩溃、registry制品注册表不可达、secrets密钥缺失/过期、quota配额耗尽——这类问题不能用代码修复见第 5 节configworkflow工作流定义错误、dependency install依赖安装失败、cache缓存失效/损坏——属于配置域可由 Agent 谨慎处置但仍需注意依赖安装失败可能只是上游环境抖动需结合重试信息判断。4.4 OpenCode 版分类的补充视角OpenCode 版 starters/ci-sweeper-opencode/skills/ci-triage/SKILL.md 提供了另一种分类切分可视为对四分类的补充细化Clear regression单文件、根因明显自动修复候选Infra flake网络超时、runner 问题、依赖不可用与 Grok 版env高度重叠Security test failure安全测试失败永不自动修复升级人类Non-deterministic不确定性失败先重试一次再分类。特别值得注意的是Non-deterministic: retry once before classifying这条——它把重试作为分类工具而非修复手段对不确定的失败先重试一次用结果辅助判定是 flake 还是真实问题这与无脑重试直到变绿的坏实践有本质区别。5. 安全边界env 失败必须 escalate-human不得用代码修复技能正文的最后一行是一条不可妥协的硬规则Env failures → escalate-human. Do not fix with code changes.这条规则在仓库多个层面被反复强化属于跨文件一致的策略约束starters/ci-sweeper-opencode/skills/ci-triage/SKILL.md 的 Rules 部分Infra and security failures always escalate基础设施与安全失败一律升级starters/ci-sweeper-opencode/LOOP.md 的 Human Gates 部分Infra / security / payments test failures 不自动修复patterns/ci-sweeper.md 的 Human Handoff Points 列出了完整的人类接管场景其中环境类包括Infrastructure failuresrunner OOM、registry down、secrets missingSecurity-sensitive test failures安全敏感测试失败Intermittent flakes that need quarantine, not code changes需要隔离而非改代码的偶发 flake。为什么 env 失败不能代码修复从根源上讲runner 资源耗尽、注册表不可达、密钥缺失这些问题的修复动作发生在 CI 基础设施层运维操作、凭据配置、配额调整Agent 即使强行改代码也无法作用于问题本体反而会制造噪音 diff、污染 blame、消耗 token。因此正确的循环动作只有两个escalate-human带上下文升级人类或按 patterns/ci-sweeper.md 的建议将间歇性 flake 隔离/跳过并开 ticket 跟踪。6. 状态跟踪把 triage 结果沉淀进 ci-sweeper-state.mdtriage 的价值在于跨周期可比对同一个失败是否反复出现、尝试了几次、上次处置是什么。仓库提供了状态文件模板 starters/ci-sweeper/ci-sweeper-state.md.example# CI Sweeper State Last run: never ## Active Failures ## Watch (flakes / infra) ## Resolved (last 7d) --- Run log: —结构分四块Active Failures进行中失败、Watch (flakes / infra)观望列表、Resolved (last 7d)近 7 天已解决、以及底部的 Run log。三个区块恰好对应三分类的出口regression→Active、flake/env→Watch、已处理→Resolved。patterns/ci-sweeper.md 给出了填充示例## CI Sweeper — Active Failures Last run: 2026-06-09 14:30 UTC ### main abc1234 - Job: test-auth - Failure: AssertionError in test_refresh_token_expiry - Attempts: 1/3 - Last action: Minimal fix proposed in worktree fix/ci-auth-refresh - Status: Waiting for verifier human ### Resolved (last 7d) - main def5678 — lint fix merged via PR #1250并明确要求跟踪commit SHA、failing job、attempt count、worktree/PR link、outcome。其中Attempts: 1/3呼应了 OpenCode 版技能与 starters/ci-sweeper-opencode/LOOP.md 中Max 3 fix attempts per item; escalate after的硬上限——同一失败最多尝试 3 次超过即升级人类防止 Agent 在同一个失败上无限空转烧 token。7. 修复与验证triage 之后的 minimal-fix loop-verifier 流水线triage 判定为可行动regression 且 Actionable: yes后循环进入修复 验证双角色流水线二者都是独立技能7.1 minimal-fix最小改动修复templates/SKILL.md.minimal-fix对应 skills/minimal-fix/SKILL.md的核心原则是用最小 diff 修一个具体问题Inputs确切的失败信息/评审意见、可能涉及的 file(s)、项目构建测试命令来自 AGENTS.md 或项目技能、路径 denylist来自 loop 安全策略永不触碰.env、auth/、payments/、密钥类文件Process能本地复现先复现 → 定位最小根因而非远端文件里的症状→ 只改必要内容、禁止顺手重构 → 运行相关测试/lint → 输出改动摘要Rules改动超过 5 个文件或涉及设计变更 → 停止升级路径命中 denylist → 停止升级禁止通过禁用测试或弱化断言来让 CI 变绿不得自行标记完成是否完成由 verifier 裁决。这条技能的每一条规则都在为修对、修小、不造假服务是 triage 决策落地时的执行层约束。7.2 loop-verifiermaker/checker 分离的独立裁决templates/SKILL.md.verifier对应 skills/loop-verifier/SKILL.md将验证者定义为checker默认立场是没有充分证据就 REJECT验收清单五项全过才 APPROVEScope只改相关文件、无 denylist 路径、无无关编辑、Intent改动确实针对目标问题、Tests亲自运行测试并附输出、No cheating无禁用测试/跳过断言/注释掉的检查、Riskmedium 以上风险即使测试通过也建议人工复核输出Verdict: APPROVE | REJECT | ESCALATE_HUMAN Evidence硬规则不信任实现者声称的测试通过必须自己跑无法运行测试环境问题→ESCALATE_HUMAN。结合 patterns/ci-sweeper.md 的 Verification Strategyverifier 必须在 worktree 中运行测试后才能批准、implementer 只能 propose 不能 merge、flake 判定后不自动修复——这套 maker/checker 分离是防止修症状型循环fix-the-symptom loops的关键机制。7.3 循环守卫与熔断patterns/ci-sweeper.md 要求每次重试前由loop-guard记录尝试到loop-ledger.json并运行loop-context --check对应 tools/loop-context同一失败重复出现 N 次或超过尝试上限如 3 次时熔断以裁剪后的上下文摘要升级人类而不是继续空转。这是第 6 节Attempts: 1/3计数与 3 次上限的运行时实现。8. 部署与集成把 ci-triage 装进 Grok / GitHub Actions8.1 快速起步loop-init 脚手架starters/ci-sweeper/README.md 提供了两种安装方式。推荐用 loop-init 一键生成npx cobusgreyling/loop-init . --pattern ci-sweeper --tool grok手动方式则逐文件复制mkdir -p .grok/skills cp -r starters/ci-sweeper/.grok/skills/ci-triage .grok/skills/ cp templates/SKILL.md.minimal-fix .grok/skills/minimal-fix/SKILL.md cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md cp starters/ci-sweeper/ci-sweeper-state.md.example ci-sweeper-state.md注意这里装配的是整套循环不只是 ci-triage 一个技能triage分类→ minimal-fix修复→ loop-verifier验证三个技能缺一不可否则循环链路断裂。安装后即可启动Grok/loop 15m Check CI on main. Update ci-sweeper-state.md. Classify failures. For new actionable failures (not flakes): worktree minimal-fix loop-verifier. Run loop-gate check before commit. Escalate after 3 attempts.这条启动命令本身就是对技能行为的显式编排分类 → 更新状态 → 非 flake 才修复 → worktree 隔离 → verifier 验证 → loop-gate 检查 → 3 次后升级。8.2 事件驱动GitHub Actions 触发examples/github-actions/ci-sweeper.yml 给出了非轮询的事件驱动方案——用workflow_run事件监听 main 分支的 workflow 完成情况仅在conclusion failure时触发清扫on: workflow_run: workflows: [*] types: [completed] branches: [main] permissions: contents: read pull-requests: write checks: read jobs: sweep: if: ${{ github.event.workflow_run.conclusion failure }} runs-on: ubuntu-latest steps: - uses: actions/checkoutv7 - name: Record failure context run: | echo Failed workflow: ${{ github.event.workflow_run.name }} echo Head branch: ${{ github.event.workflow_run.head_branch }} echo Run URL: ${{ github.event.workflow_run.html_url }} - name: Update ci-sweeper-state.md run: | FILEci-sweeper-state.md touch $FILE echo $FILE echo ### $(date -u %Y-%m-%dT%H:%M:%SZ) — workflow failure $FILE echo - Workflow: ${{ github.event.workflow_run.name }} $FILE echo - Branch: ${{ github.event.workflow_run.head_branch }} $FILE echo - URL: ${{ github.event.workflow_run.html_url }} $FILE echo - Loop action: pending agent invocation $FILE - name: Invoke CI Sweeper Agent uses: cobusgreyling/loop-engineering/tools/loop-actionmain with: pattern: ci-sweeper level: L2 sandbox: true sandbox-shell: true command: | echo ::notice::Wire to agent: classify failure, worktree fix, verifier, open PR. echo See patterns/ci-sweeper.md and docs/safety.md这个 workflow 本身已演示了 triage 流水线的两个前置环节记录失败上下文workflow 名、head branch、run URL对应技能的branch sha字段与把失败追加进ci-sweeper-state.md随后才把控制权交给 Agentloop-actionpattern 为 ci-sweeper、level L2、开启 sandbox。level: L2对应 patterns/ci-sweeper.md 成本模型中Fix attempt (L2) ~200k tokens级别的修复路径。8.3 循环级配置human gates、worktree 与预算starters/ci-sweeper-opencode/LOOP.md 展示了循环级而非技能级的策略配置是 triage 分类的政策外壳维度配置Cadence5–15mL2 cautiousHuman gatesinfra/security/payments 测试失败不自动修每项最多 3 次修复尝试无 verifier 通过不自动合并Worktrees每次尝试都派发到独立 git worktree一个 worktree 一个修复REJECT 后丢弃Budget每次运行最多 3 个 sub-agent每天最多 5 个自动 PR无失败时提前退出其中Worktrees一条呼应技能 Rules 中 Worktree isolation required for any code changeOpenCode 版——任何代码变更都必须在 worktree 隔离中进行这是 docs/safety.md 安全策略在 CI 清扫场景的具体化避免 Agent 在主分支工作区里直接改代码。9. 失败模式与成本控制triage 做不好会发生什么9.1 已知失败模式对照patterns/ci-sweeper.md 总结了 CI Sweeper 的典型失败模式及对应缓解措施全部与 triage 的职责直接相关失败模式缓解措施对应 triage 机制Fix-the-symptom loops修症状循环verifier 校验根因而非只看 CI 变绿分类时区分 symptom 与 root causeverifier 检查 IntentFighting flakes with retries跟 flake 死磕分类 flake隔离或带 ticket 跳过flake 判据 Watch 出口Token burn on red mainmain 红了烧 token失败 N 次后暂停批量修复3 次尝试上限 escalate-humanWrong branch targeted修错分支技能中显式分支 allowlistbranch sha精确锚定9.2 成本模型为什么 triage 要够用即止patterns/ci-sweeper.md 的成本模型给出了三个量级差异巨大的档位场景每轮 token 消耗无操作CI 全绿~5k必需——全绿时不要跑完整清扫Triage / 分类~50k日志解析 失败分类修复尝试L2~200kworktree 实现者 验证者并明确指出以 15m 节奏且无提前退出时最坏情况日消耗超过 5M tokens因此绝不能在每 tick 都执行完整动作路径。这条成本结构从经济层面解释了技能设计中的两个抠门原则Error (1-3 lines)限制输出长度以压缩上下文、flake/watch/env→escalate 通道避免让 200k 成本的修复路径进入 50k 就能解决的场景。成本核算命令参见 tools/loop-costnpx cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m --level L29.3 成功度量最后patterns/ci-sweeper.md 给出的成功指标可用来验证 triage 是否真的有效从 CI 变红到首次提出修复的平均时间Mean time to first proposed fix无需人工干预即解决的失败占比仅限琐碎案例同一 job 在 48 小时内再次失败的重复率Repeat failure rate。其中重复失败率直接考验 triage 的分类质量——若同一失败反复进入 Active 而非被正确归入 Watch/Resolved说明分类判据尤其 flake 与 regression 的区分执行不到位。总结ci-triage技能的精髓可以浓缩为三句话先分类再动手任何修复尝试之前必须先做四分类、按类分出口flake→watch、regression→minimal-fix、env→escalate-human、config→谨慎处置、全程留痕逐失败结构化报告 回写ci-sweeper-state.md跟踪 SHA/job/尝试次数/结果。它通过与minimal-fix、loop-verifier、loop-guard三个技能以及 worktree 隔离、3 次尝试上限、GitHub Actions 事件驱动触发的组合构成了 loop-engineering 仓库中完整度最高、最适合团队上手的闭环循环——分类决策在技能层执行边界在安全策略层成本控制在预算层三者缺一不可。【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考