深入解析 Nx Self-Healing CI 的修复流程：从状态机到本地修复的完整实战指南

深入解析 Nx Self-Healing CI 的修复流程从状态机到本地修复的完整实战指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx本篇技术指南以仓库中 .agents/skills/monitor-ci/references/fix-flows.md 为核心骨架结合 Nx 仓库内的 monitor-ci Agent 技能SKILL.md、两个确定性决策脚本ci-poll-decide.mjs、ci-state-update.mjs以及nx fix-ci/nx apply-locally命令的源码实现系统讲解 Nx Cloud Self-Healing CI 失败后的状态分类、修复动作流程、预算门控gate机制与 Git 安全规范。读完本文你将掌握在 AI Agent 场景下如何安全、有预算意识地处理自愈 CI 修复全流程并理解每个状态背后的底层实现依据。背景Self-Healing CI 与 monitor-ci 技能的关系Nx Cloud 的 Self-Healing CI 是一个 AI 驱动的系统能够在 CI 任务失败时自动检测、分析并提出修复建议详见 self-healing-ci.mdoc。其 CI 管道入口是在主 job 末尾添加npx nx fix-ci配合if: always()或after_script该命令在 fix-ci.ts 中实现先通过isNxCloudUsed校验工作区是否已连接 Nx Cloud再委托给nx-cloud fix-ci执行。monitor-ci是仓库内置的 Agent 技能用于主动监控 Nx Cloud CI 管道执行并处理自愈修复。它由四层组成编排器orchestrator本技能自身负责派生子 Agent、运行脚本、打印状态并执行本地编码工作ci-monitor-subagent调用ci_information或update_self_healing_fix两个 MCP 工具并返回结构化结果ci-poll-decide.mjs确定性决策脚本将ci_information结果与当前状态映射为 action 状态消息ci-state-update.mjs确定性状态管理脚本负责预算门控gate、动作后状态迁移与周期分类。fix-flows.md 正是第三步“处理 actionable 状态”时的详细操作手册。一、CI 失败状态的分类与处理当决策脚本返回action done后编排器需要根据code查找默认行为见 SKILL.md 中的状态表并查阅 fix-flows.md 执行对应流程。以下逐一展开。1. fix_auto_apply_skipped自愈已验证但自动应用被跳过当couldAutoApplyTasks true且autoApplySkipped true时决策脚本返回该状态见 ci-poll-decide.mjs。典型原因是“上一次 CI 管道执行由 Nx Cloud 触发”用于防止循环触发。处理流程将跳过原因报告给用户例如“Auto-apply 被跳过因为上一次 CI 管道执行是由 Nx Cloud 触发的”征询用户是否手动应用修复——若同意则派生 UPDATE_FIX 子 Agent 并传入APPLY动作记录last_cipe_url进入等待模式wait mode。2. fix_apply_ready修复已验证直接应用当自愈状态为COMPLETED且任务分类为all_verified所有失败任务均已被验证或e2e_only仅剩 e2e 类任务时进入该状态。此时派生 UPDATE_FIX 子 Agent传入APPLY记录last_cipe_url进入等待模式。此路径不涉及任何本地 Git 操作新 CI Attempt 由 Nx Cloud 自动派生。3. fix_needs_local_verify修复存在但含未验证任务决策脚本中的categorizeTasks()会将failedTaskIds中未被verifiedTaskIds覆盖的任务分类见 ci-poll-decide.mjs若剩余任务不含 e2e 后缀任务 ID 形如project:task第二段含e2e即视为 e2e 任务则归类为needs_local_verify并输出verifiableTaskIds。处理流程检测包管理器pnpm-lock.yaml存在 →pnpm nxyarn.lock存在 →yarn nx否则 →npx nx并行运行可验证任务为每个任务派生general子 Agent 本地执行全部通过→ 派生 UPDATE_FIX 子 Agent 传入APPLY进入等待模式任一失败→ 进入下方“Apply Locally Enhance Flow”。4. fix_needs_review修复需要人工审查当验证状态为FAILED/NOT_EXECUTABLE或couldAutoApplyTasks不为 true 且无验证状态时触发见 ci-poll-decide.mjs。此时先派生 FETCH_HEAVY 子 Agent 获取suggestedFixDescription、suggestedFixSummary、taskFailureSummaries字段再按三档决策修复看起来正确→ 通过 MCP 应用APPLY修复需要增强→ Apply Locally Enhance Flow修复是错误的→ 先运行ci-state-update.mjs gate --gate-type local-fix检查预算不允许则打印消息并退出允许则进入“Reject Fix From Scratch Flow”。5. fix_failed / no_fix自愈失败或无可用修复fix_failedselfHealingStatus FAILED自愈未能生成修复no_fixCI 失败但selfHealingEnabled false或selfHealingStatus NOT_EXECUTABLE。两者流程一致派生 FETCH_HEAVY 子 Agent 获取taskFailureSummaries运行ci-state-update.mjs gate --gate-type local-fix——不允许则打印消息并退出此时计数器已由 gate 自增尝试本地修复成功 → commit、push、进入等待模式失败 → 以失败状态退出。6. environment_issue环境状态失败当failureClassification environment_state时见 ci-poll-decide.mjs说明 CI 失败源于环境而非代码运行ci-state-update.mjs gate --gate-type env-rerun不允许则打印消息并退出派生 UPDATE_FIX 子 Agent 传入RERUN_ENVIRONMENT_STATE设置last_cipe_url后进入等待模式。若环境重试次数达到 2 次上限envRerunCount 2决策脚本会直接返回environment_rerun_cap并退出。7. self_healing_throttled自愈被限流当selfHealingSkippedReason THROTTLED积压了过多未应用的修复时派生 FETCH_HEAVY 子 Agent 获取selfHealingSkipMessage解析限流消息中的 CI Attempt URL用正则/cipes/{id}提取拒绝旧修复对每个 URL 派生 FETCH_THROTTLE_INFO 获取shortLink再通过 UPDATE_FIX 传入REJECT尝试本地修复运行ci-state-update.mjs gate --gate-type local-fix不允许则跳到第 5 步允许则使用failedTaskIds与taskFailureSummaries作为上下文兜底若本地修复不可行或预算耗尽推送空提交git commit --allow-empty -m ci: rerun after rejecting throttled fixes进入等待模式。8. no_new_cipe等待超时无新 CI Attempt向用户报告未发现新 CI Attempt建议检查 CI 提供商配置若指定了--auto-fix-workflow检测包管理器并运行安装若 lockfile 有变化则提交并进入等待模式否则打印引导信息后退出。9. cipe_no_tasksCI 失败但无任务记录向用户报告“CI 失败但没有记录任何任务”重试一次git commit --allow-empty -m chore: retry ci [monitor-ci]并推送进入等待模式若重试后仍返回cipe_no_tasks以失败状态退出。二、三大修复动作流程Fix Action Flows流程 AApply via MCP通过 MCP 应用派生 UPDATE_FIX 子 Agent 传入APPLY新 CI Attempt 自动派生不执行任何本地 Git 操作。这是最轻量的路径适用于修复已经过验证的场景fix_apply_ready。流程 BApply Locally Enhance Flow本地应用并增强适用于修复“90% 正确但需要微调”的场景运行nx-cloud apply-locally shortLink将 CI 状态置为APPLIED_LOCALLY。该命令在仓库中由 apply-locally.ts 实现——同样先校验 Nx Cloud 连接再委托nx-cloud apply-locallyCLI 入口见 command-object.ts其描述明确该命令是nx-cloud apply-locally的别名增强代码以修复失败任务本地运行失败任务验证仍失败 → 运行ci-state-update.mjs gate --gate-type local-fix不允许则提交当前状态并推送让 CI 作为最终裁判允许则回到第 2 步循环通过 → commit 并 push进入等待模式。提示官方文档中nx apply-locally fix-identifier命令支持--no-interactive关闭交互提示fix 标识符可在 Nx Cloud UI 与 PR/MR 评论中查看见 self-healing-ci.mdoc。流程 CReject Fix From Scratch Flow拒绝并从零修复运行ci-state-update.mjs gate --gate-type local-fix不允许则打印消息并退出派生 UPDATE_FIX 子 Agent 传入REJECT本地从零修复commit 并 push进入等待模式。三、环境失败与代码失败的识别任何本地修复路径在运行任务失败后在运行 gate 脚本之前必须先评估失败属于代码问题还是环境/工具链问题类型典型指标非穷举处理方式环境/工具链失败命令未找到 / 二进制缺失、OOM / 堆分配失败、权限拒绝、网络超时 / DNS 失败、系统库缺失、Docker/容器问题、磁盘空间耗尽立即退出bail不运行 gate不消耗预算向用户报告这是环境/工具链问题而非代码缺陷代码失败编译错误、测试断言失败、lint 违规、类型错误是本地修复的正当候选正常走 gate 流程这一设计背后的原因在 SKILL.md 的 Key rules 中亦有强调环境失败不是代码 bug将本地修复预算花在它们身上是浪费。四、预算门控机制ci-state-update.mjs 的三个命令ci-state-update.mjs 提供三个确定性命令是所有状态机动作的“守门员”。gate动作前的预算检查node skill_dir/scripts/ci-state-update.mjs gate --gate-type local-fix|env-rerun [counter args]local-fix读取--local-verify-count默认 0与--local-verify-attempts默认 3对应技能默认配置--local-verify-attempts: 3。count max时返回{ allowed: false }并提示Local fix budget exhausted (n/3 attempts)否则返回allowed: true并将计数器 1——注意gate 调用本身就会自增计数因此必须在每次本地修复尝试前调用env-rerun环境重试上限为 2 次count 2即拒绝超限提示Environment issue persists after 2 reruns. Manual investigation needed.。post-action动作后的状态迁移node skill_dir/scripts/ci-state-update.mjs post-action \ --action type --cipe-url current_cipe_url --commit-sha git_rev_parse_HEAD支持两类 action见 ci-state-update.mjs按 cipeUrl 追踪MCP 触发或自动应用fix-auto-applying、apply-mcp、env-rerun按 commitSha 追踪本地推送apply-local-push、reject-fix-push、local-fix-push、auto-fix-push、empty-commit-push。返回{ waitMode: true, pollCount: 0, lastCipeUrl, expectedCommitSha, agentTriggered }其中agentTriggered仅对fix-auto-applying为 false自愈自动完成非 monitor 触发。新 CI Attempt 的检测正是通过比对cipeUrl变化或commitSha expectedCommitSha完成的见 ci-poll-decide.mjs。cycle-check周期分类与限额判定node skill_dir/scripts/ci-state-update.mjs cycle-check \ --code code [--agent-triggered] \ --cycle-count cycle_count --max-cycles max_cycles \ --env-rerun-count env_rerun_count若上一周期为 agent 触发cycleCount非environment_issue状态时重置envRerunCount 0limitReached cycleCount maxCycles默认 10为硬停止打印消息并停止监控不得再处理代码或启动新周期approachingLimit cycleCount maxCycles - 2为告警此时应询问用户是否继续 5~10 个周期。五、Git 安全与提交规范Git 安全Git Safety按名称暂存特定文件git add -A或git add .有风险——可能把用户无关的工作进度work-in-progress或密钥提交上去。这一规则贯穿所有本地修复路径是所有 push 动作的前置约束。提交信息格式Commit Message Formatgit commit -m fix(projects): brief description Failed tasks: taskId1, taskId2 Local verification: passed|enhanced|failed-pushing-to-ci提交信息中必须携带两类元数据失败的 taskId 列表以及本地验证结论passed本地通过 /enhanced增强后通过 /failed-pushing-to-ci本地失败推给 CI 裁决。这不仅便于追溯也让后续 CI 排障一目了然。六、从源码看整体决策链路把以上流程串起来monitor-ci 的核心循环是完整定义见 SKILL.md 的 Main Loop初始化跟踪状态cycle_count、wait_mode、last_cipe_url 等 → 派生 FETCH_STATUS 子 Agentwait 模式用 WAIT_FIELDS正常模式用 LIGHT_FIELDS → 运行 ci-poll-decide.mjs 决策脚本输出 { action, code, message, delay, ... } → actionpoll/wait 则打印消息、按退避延时60/90/120/180 秒后继续轮询 → actiondone 则先 cycle-check再按 fix-flows.md 处理状态 → 触发新 CI Attempt 的动作后执行 post-action 更新跟踪状态值得注意的底层细节超时语义--timeout默认 120 分钟与--new-cipe-timeout默认 10 分钟均以分钟传入脚本内部转换为秒--elapsed-seconds是自监控开始以来的真实墙钟时间由编排器跨轮询携带是--timeout总预算的权威信号见 ci-poll-decide.mjs。等待模式下--timeout优先于--new-cipe-timeout防止长时间等待突破总预算进度熔断连续 13 次轮询无任何状态变化cipeStatus、selfHealingStatus、verificationStatus、failureClassification均未变即触发circuit_breaker字段分级拉取WAIT_FIELDS3 个字段、LIGHT_FIELDS21 个字段、HEAVY_FIELDS含taskOutputSummary、suggestedFix等大字段按需使用避免浪费上下文。七、实战要点速查场景关键动作是否消耗 local-fix 预算修复已验证fix_apply_readyMCPAPPLY否修复含未验证任务fix_needs_local_verify本地并行跑任务全过则APPLY是失败进入 Enhance Flow 后自愈失败fix_failed / no_fix先 gate再本地修复是环境失败environment_issue先 gateenv-rerunMCPRERUN_ENVIRONMENT_STATE否走 env-rerun 预算上限 2 次自愈限流self_healing_throttled拒绝旧修复 空提交触发重跑是本地修复阶段本地跑任务失败且为环境问题立即退出不运行 gate否结语fix-flows.md 本质上是一张“CI 失败状态 → 修复动作”的状态转移图其背后的两大设计哲学贯穿始终确定性优先所有决策交给纯函数的决策脚本Agent 只执行不拍脑袋与预算意识local-fix 与 env-rerun 都有硬上限环境问题绝不消耗代码修复预算。对于希望在自有 Agent 工作流中集成 Nx Cloud 自愈能力的团队这套状态机 门控 Git 安全规范可直接作为参考实现对于普通用户理解这些流程有助于在 PR 失败时判断“该让 AI 自己修、该本地微调、还是该直接推给 CI 裁决”。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考