Nx Cloud CI Watcher基于 MCP 轮询与自愈状态机的 Subagent 设计深度解析【免费下载链接】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导读本文以 Nx 官方仓库中的.cursor/agents/ci-watcher.md为核心完整拆解一个专用于轮询 Nx Cloud CI 流水线CI Attempt简称 CIPE并监听自愈Self-Healing状态的 AI Subagent 的设计包括ci_informationMCP 工具契约、两阶段操作模式、指数退避轮询、结构化返回格式与 verbosity 分级上报。读完本文你将掌握如何在 Claude Code 等 Agent 体系中构建一个只观测、不决策的监视型 Subagent理解其如何与主 Agent 协作完成监视 CI → 发现修复 → 应用/验证 → 再次监视的完整闭环并能直接照搬其中的状态机与字段设计。一、CI Watcher 的角色定位只观测、不决策CI Watcher 是一个被主 Agentorchestrator派生的监视子代理。其职责被严格限定为四条使用ci_informationMCP 工具轮询 CI 状态在两次轮询之间实现指数退避exponential backoff在达到可行动状态actionable condition时返回结构化状态跟踪迭代次数与累计耗时并按 verbosity 级别输出状态更新。最关键的一条边界是CI Watcher 不做 apply/reject 决策——那是主 Agent 的职责它也不执行任何 git 操作只负责轮询与上报。这种侦察兵式设计把上下文消耗控制在了子代理内部让主 Agent 的上下文窗口只接收有意义的、精简过的状态摘要。在仓库中这份定义与命令入口一一对应命令.cursor/commands/ci-monitor.md是编排器主 Agent技能文件.cursor/skills/ci-monitor/SKILL.md提供了同样的编排逻辑而.cursor/agents/ci-watcher.md正是主 Agent 通过Task(agent: ci-watcher, ...)派生的轮询执行体。输入参数契约主 Agent 通过 prompt 传入以下可选参数全部可省略有默认行为兜底参数说明默认行为branch要监视的分支未提供时自动探测当前 git 分支expectedCommitSha期望触发新 CI Attempt 的提交 SHA未提供则进入新鲜开始模式previousCipeUrl行动之前的 CI Attempt URL用于检测变化未提供则进入新鲜开始模式subagentTimeout轮询超时时间分钟60verbosity输出级别minimal / medium / verbosemedium其中expectedCommitSha与previousCipeUrl是关键信号只要二者出现其一Subagent 就必须进入等待新 CIPE模式Wait Mode检测是否有新的 CI Attempt 被触发。二、MCP 工具契约ci_information的输入与输出CI Watcher 唯一依赖的 MCP 工具是ci_information其 JSON Schema 是整套状态机的数据基础。输入结构{ branch: string (optional, defaults to current git branch), select: string (optional, comma-separated field names), pageToken: number (optional, 0-based pagination for long strings) }输出结构完整字段{ cipeStatus: NOT_STARTED | IN_PROGRESS | SUCCEEDED | FAILED | CANCELED | TIMED_OUT, cipeUrl: string, branch: string, commitSha: string | null, failedTaskIds: string[], verifiedTaskIds: string[], selfHealingEnabled: boolean, selfHealingStatus: NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null, verificationStatus: NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null, userAction: NONE | APPLIED | REJECTED | APPLIED_LOCALLY | APPLIED_AUTOMATICALLY | null, failureClassification: string | null, taskOutputSummary: string | null, suggestedFixReasoning: string | null, suggestedFixDescription: string | null, suggestedFix: string | null, shortLink: string | null, couldAutoApplyTasks: boolean | null, confidence: number | null, confidenceReasoning: string | null }对字段的语义理解是整个监视逻辑的前提cipeStatus描述 CI Attempt 本身的生命周期未开始、进行中、成功、失败、取消、超时selfHealingStatus描述 Nx Cloud 自愈代理的工作状态它是否在生成修复、修复是否完成、是否不可执行verificationStatus描述对生成修复的验证状态——自愈代理在应用修复前会先运行验证确认修复确实能解决问题couldAutoApplyTasks表示修复是否具备自动应用资格它与verificationStatus共同决定最终走自动应用还是人工介入failedTaskIds/verifiedTaskIds分别记录失败任务与已验证任务主 Agent 通过两者集合关系做进一步决策taskOutputSummary、suggestedFix、suggestedFixReasoning、suggestedFixDescription是重量级内容字段其中suggestedFix可能是完整补丁文件必须谨慎按需拉取。select参数轮询效率的关键ci_information通过select控制返回内容这是上下文节约的第一道闸门用法返回内容不传select格式化概览会被截断不推荐用于轮询单个字段字段原始值长字符串支持分页多个字段逗号分隔包含所请求字段值的对象文档还预定义了三个典型字段集按探测成本分级WAIT_FIELDS: cipeUrl,commitSha,cipeStatus # 最小字段集仅用于检测新 CI Attempt 是否出现 LIGHT_FIELDS: cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning # 状态字段集用于判定是否达到可行动状态 HEAVY_FIELDS: taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription # 大内容字段仅当要返回主 Agent 时才拉取这套分级设计贯穿整个轮询循环等待阶段只拉WAIT_FIELDS正常轮询阶段拉LIGHT_FIELDS只有在确定要返回结果时才补拉HEAVY_FIELDS。三、初始等待与两阶段操作模式首次轮询前的等待在第一次轮询之前CI Watcher 需要先睡一段时间让 CI 有时间启动或被触发新鲜开始无期望 CIPE等待 60 秒让 CI 有机会启动期望新 CIPE等待 30 秒因为触发动作已经发生CIPE 会更快出现。一个容易被忽略的实现细节是sleep 必须以前台命令运行绝不能放后台。后台 sleep 在结束时会产生多余的交互提示打断 Agent 的工作流sleep 60 # 或期望新 CIPE 时用 30前台执行不要后台化模式一Fresh Start新鲜开始当主 Agent 未提供expectedCommitSha或previousCipeUrl时Subagent 进入普通轮询模式ci_information返回什么 CIPE 就处理什么 CIPE。模式二Wait-for-New-CIPE等待新 CIPE当提供了expectedCommitSha或previousCipeUrl时Subagent 进入等待模式其核心纪律是完全忽略旧的/过期的 CIPE——不处理它的状态不基于它返回任何可行动状态。Phase A等待模式启动新 CIPE 超时计时器默认 30 分钟每次轮询ci_information时判断 CIPE 是否为新cipeUrl与previousCipeUrl不同 → 检测到新 CIPEcommitSha与expectedCommitSha匹配 → 检测到正确的 CIPE如果仍是旧 CIPE忽略所有状态字段继续等待并轮询输出等待状态见下若 30 分钟超时 → 返回no_new_cipe。Phase B正常轮询检测到新 CIPE 后清除新 CIPE 超时计时器、切换到正常轮询模式、按新 CIPE 的状态正常处理、在达到可行动状态时返回。等待模式的输出示例[CI Monitor] ═══════════════════════════════════════════════════════ [CI Monitor] WAIT MODE - Expecting new CI Attempt [CI Monitor] Expected SHA: expectedCommitSha [CI Monitor] Previous CI Attempt: previousCipeUrl [CI Monitor] ═══════════════════════════════════════════════════════ [CI Monitor] Polling... (elapsed: 0m 30s) [CI Monitor] Still seeing previous CI Attempt (ignoring): oldCipeUrl [CI Monitor] Polling... (elapsed: 2m 30s) [CI Monitor] ✓ New CI Attempt detected! URL: newCipeUrl, SHA: newCommitSha [CI Monitor] Switching to normal polling mode...等待模式的价值上下文保护Context Preservation为什么要设计如此严格的忽略旧 CIPE纪律因为过期 CIPE 的数据可能极其庞大taskOutputSummary可能包含数千字符的构建/测试输出suggestedFix完整的补丁文件suggestedFixReasoning详细的推理说明。没有等待模式时Subagent 会把旧 CIPE 的海量数据带回主 Agent主 Agent 的上下文窗口被无用信息污染——明明这个 CIPE 已经被处理过了。有了等待模式旧数据留在 Subagent 内部被丢弃只有新的、相关的 CIPE 数据才会返回给主 Agent。这是整套设计中最具工程价值的思想把轮询产生的噪声隔离在子代理层让主 Agent 只看到有意义的状态变化。四、轮询循环状态机、退避与重字段拉取内部状态累积Subagent 在多次轮询之间维护内部累积状态accumulated state每次轮询后把响应合并进去accumulated_state {}按模式选择字段集等待模式只拉最小字段cipeUrl,commitSha,cipeStatus仅用于检测 CIPE 变化绝不拉重字段过期数据浪费上下文正常模式拉LIGHT_FIELDS全集判断可行动状态。继续轮询的条件只要满足以下任一条件就继续带退避轮询条件原因cipeStatus IN_PROGRESSCI 仍在运行cipeStatus NOT_STARTEDCI 尚未启动selfHealingStatus IN_PROGRESS自愈代理正在工作selfHealingStatus NOT_STARTED自愈尚未开始failureClassification FLAKY_TASK自动重跑进行中userAction APPLIED_AUTOMATICALLY自动应用后正在生成新 CI Attempt当couldAutoApplyTasks true时判定进一步细化verificationStatus为NOT_STARTED或IN_PROGRESS→ 继续轮询验证仍在进行verificationStatus COMPLETED→ 返回fix_auto_applying自动应用即将发生主 Agent 会派生一个等待模式 Subagent 继续监视verificationStatus为FAILED或NOT_EXECUTABLE→ 返回fix_available自动应用不会发生需要人工介入。指数退避轮询间隔采用指数退避且带上限轮询次数等待时间第 1 次60 秒第 2 次90 秒第 3 次及以后120 秒封顶当状态发生显著变化时退避重置回 60 秒。同样强调前台执行sleep 60 # 第一次等待 sleep 90 # 第二次等待 sleep 120 # 第三次及以后封顶达到可行动状态时拉取重字段在返回主 Agent 之前按目标状态决定是否需要重字段状态所需重字段ci_success无fix_auto_applying无fix_availabletaskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescriptionfix_failedtaskOutputSummaryno_fixtaskOutputSummaryenvironment_issue无no_new_cipe无polling_timeout无cipe_canceled无cipe_timed_out无示例——为fix_available补拉重字段ci_information({ branch: branch_name, select: taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription })拉取后合并进accumulated_state再把合并后的状态返回主 Agent。注意分页重字符串字段默认只返回第一页若hasMore指示还有更多内容需要在返回格式中标注让主 Agent 知道可继续分页拉取。五、返回主 Agent 的判定条件可行动状态机CI Watcher 在满足以下任一条件时立即返回结构化状态状态触发条件ci_successcipeStatus SUCCEEDEDfix_auto_applyingselfHealingStatus COMPLETED且couldAutoApplyTasks true且verificationStatus COMPLETEDfix_availableselfHealingStatus COMPLETED且suggestedFix ! null且couldAutoApplyTasks ! true或verificationStatus为FAILED/NOT_EXECUTABLEfix_failedselfHealingStatus FAILEDenvironment_issuefailureClassification ENVIRONMENT_STATEno_fixcipeStatus FAILED且selfHealingEnabled false或selfHealingStatus NOT_EXECUTABLEno_new_cipe提供了expectedCommitSha/previousCipeUrl但 30 分钟内未出现新 CIPEpolling_timeoutSubagent 轮询超过配置超时默认 60 分钟cipe_canceledcipeStatus CANCELEDcipe_timed_outcipeStatus TIMED_OUT子代理级超时CI Watcher 需要持续追踪耗时一旦轮询超过 60 分钟主 Agent 可配置立即返回status: polling_timeout避免无限占用。六、结构化返回格式与分页指示标准返回格式## CI Monitor Result **Status:** status **Iterations:** count **Elapsed:** minutesm secondss ### CI Attempt Details - **Status:** cipeStatus - **URL:** cipeUrl - **Branch:** branch - **Commit:** commitSha - **Failed Tasks:** failedTaskIds - **Verified Tasks:** verifiedTaskIds ### Self-Healing Details - **Enabled:** selfHealingEnabled - **Status:** selfHealingStatus - **Verification:** verificationStatus - **User Action:** userAction - **Classification:** failureClassification - **Confidence:** confidence - **Confidence Reasoning:** confidenceReasoning ### Fix Information (if available) - **Short Link:** shortLink - **Description:** suggestedFixDescription - **Reasoning:** suggestedFixReasoning ### Task Output Summary (first page) taskOutputSummary [MORE_CONTENT_AVAILABLE: taskOutputSummary, pageToken: 1] ### Suggested Fix (first page) suggestedFix [MORE_CONTENT_AVAILABLE: suggestedFix, pageToken: 1]这种格式的价值在于把原始 JSON 转化为人类与 LLM 都易读的分节结构同时保留字段名cipeStatus、selfHealingStatus等便于主 Agent 精确解析。分页指示器当重字段还有更多内容时追加如下指示符[MORE_CONTENT_AVAILABLE: fieldName, pageToken: nextPage]主 Agent 需要时可继续拉取后续页ci_information({ select: fieldName, pageToken: nextPage })不同字段的分页方向不同需要在实现中注意taskOutputSummary反向分页——page 0 是最新的内容suggestedFix正向分页——page 0 是开头suggestedFixReasoning同样支持分页。no_new_cipe的专用返回格式当返回no_new_cipe时附带额外诊断上下文## CI Monitor Result **Status:** no_new_cipe **Iterations:** count **Elapsed:** minutesm secondss ### Expected CI Attempt Not Found - **Expected Commit SHA:** expectedCommitSha - **Previous CI Attempt URL:** previousCipeUrl - **Last Seen CI Attempt URL:** cipeUrl - **Last Seen Commit SHA:** commitSha - **New CI Attempt Timeout:** 30 minutes (exceeded) ### Likely Cause CI workflow failed before Nx tasks could run (e.g., install step, checkout, auth). Check your CI provider logs for the commit expectedCommitSha. ### Last Known CI Attempt State - **Status:** cipeStatus - **Branch:** branch这个格式直接把最可能原因CI 工作流在 Nx 任务执行前就失败了例如 install、checkout、认证步骤写进返回内容帮助主 Agent 立即向用户给出可执行的排查方向。七、Verbosity 分级输出用最少 Token 汇报状态输出由主 Agent 传入的verbosity参数控制级别输出内容minimal无中间输出只在达到可行动状态时返回最终结果medium默认只在显著状态变化时输出而非每次轮询都输出verbose每次轮询后输出详细阶段信息Minimal轮询期间静默完成时返回。Medium默认仅在状态显著变化时输出节省上下文 token。触发输出的变化包括cipeStatus变化如 IN_PROGRESS → FAILED、selfHealingStatus变化如 IN_PROGRESS → COMPLETED、等待模式下检测到新 CIPE。格式为单行、无装饰[CI Monitor] CI: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 4mVerbose每次轮询后输出详细阶段信息框[CI Monitor] ───────────────────────────────────────────────────── [CI Monitor] Iteration N | Elapsed: Xm Ys [CI Monitor] [CI Monitor] CI Status: cipeStatus [CI Monitor] Self-Healing: selfHealingStatus [CI Monitor] Verification: verificationStatus [CI Monitor] Classification: failureClassification [CI Monitor] [CI Monitor] → human-readable phase description [CI Monitor] ─────────────────────────────────────────────────────Verbose 模式还定义了状态组合到人类可读描述的一一映射例如cipeStatus: FAILEDselfHealingStatus: COMPLETEDverificationStatus: IN_PROGRESS→ Fix generated! Verification running...cipeStatus: FAILEDselfHealingStatus: FAILED→ Self-healing could not generate a fix.。八、与主 Agent 的完整协作闭环CI Watcher 本身只负责监视但它处于一个更大的闭环中。编排器.cursor/commands/ci-monitor.md 与 .cursor/skills/ci-monitor/SKILL.md在启动监视前会先校验工作区是否已连接 Nx Cloud——检查根目录 nx.json 中是否存在nxCloudId或nxCloudAccessToken字段。当前仓库的根 nx.json 并不包含这两个字段说明该仓库本身未连接 Nx Cloud使用本套监视流程前需要先完成连接。当 CI Watcher 返回fix_available时主 Agent 会对比failedTaskIds与verifiedTaskIds做进一步决策任务分类verified tasks 同时出现在两个数组中的任务unverified tasks 只在failedTaskIds中的任务E2E tasks 目标包含 e2e 的未验证任务任务格式为project:target或project:target:configverifiable tasks 非 e2e 的未验证任务路径选择无未验证任务或未验证任务全部是 e2e → 直接通过 MCP 应用存在可验证任务 → 走本地验证流程本地验证根据pnpm-lock.yaml/yarn.lock是否存在选择pnpm nx/yarn nx/npx nx并行派生 general subagent 逐个运行nx run taskId全部通过则经 MCP 应用任一失败则走nx apply-locally shortLink的本地应用 增强流程超过local_verify_attempts默认 3 次后提交推送交由 CI 做最终裁决。这个流程对应的命令实现可以追溯到 Nx 源码.cursor中提到的nx apply-locally命令在 packages/nx/src/command-line/nx-cloud/apply-locally/apply-locally.ts 中实现——它先调用isNxCloudUsed(readNxJson())检查工作区是否连接 Nx Cloud未连接时输出警告直接返回其命令定义位于 packages/nx/src/command-line/nx-cloud/apply-locally/command-object.ts描述为将自愈 CI 修复应用到本地是nx-cloud apply-locally的别名。这与文档中Runnx apply-locally shortLink应用补丁到本地工作目录并将状态置为APPLIED_LOCALLY的描述完全对应。九、完整会话示例下面两个示例展示了整套机制的实际运行形态来自 .cursor/commands/ci-monitor.md 的 Example Session 部分。示例一自愈正常流转medium verbosity[ci-monitor] Starting CI monitor for branch feature/add-auth [ci-monitor] Config: max-cycles5, timeout120m, verbositymedium [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m [CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m [CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m [ci-monitor] Fix available! Verification: COMPLETED [ci-monitor] Applying fix via MCP... [ci-monitor] Fix applied in CI. Waiting for new CI attempt... [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] New CI attempt detected! [CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m [ci-monitor] CI passed successfully! [ci-monitor] Summary: - Total cycles: 2 - Total time: 12m 34s - Fixes applied: 1 - Result: SUCCESS示例二CI 任务前失败 锁文件自动修复[ci-monitor] Starting CI monitor for branch feature/add-products [ci-monitor] Config: max-cycles5, timeout120m, auto-fix-workflowtrue [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m [ci-monitor] Applying fix locally, enhancing, and pushing... [ci-monitor] Committed: abc1234 [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234) [CI Monitor] ⚠️ CI attempt timeout (10 min). Returning no_new_cipe. [ci-monitor] Status: no_new_cipe [ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update... [ci-monitor] Lockfile updated. Committed: def5678 [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] New CI attempt detected! [CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m [ci-monitor] CI passed successfully! [ci-monitor] Summary: - Total cycles: 3 - Total time: 22m 15s - Fixes applied: 1 (self-healing) 1 (lockfile) - Result: SUCCESS第二个示例尤其体现了等待模式的价值主 Agent 应用本地修复并 push 后以expectedCommitSha派生等待模式 Subagent当 10 分钟--new-cipe-timeout默认值内没有新 CIPE 出现时返回no_new_cipe主 Agent 据此推断 CI 工作流可能在 Nx 任务执行前就失败install/checkout/认证等进而启用--auto-fix-workflow尝试更新锁文件并再次进入监视循环。十、重要注意事项与容错设计把ci-watcher.md中强调的工程约束汇总如下职责隔离不做 apply/reject 决策不做 git 操作只轮询和上报尊重 verbosity默认 medium避免无意义输出错误重试ci_information返回错误时等待并重试计为一次失败轮询连续 5 次失败时返回status: error双超时并行管理等待新 CIPE 的 30 分钟超时与整体轮询的 60 分钟超时要分开跟踪互不干扰前台 sleep所有退避等待都必须前台执行后台 sleep 结束时会触发无关的交互提示上下文即成本等待模式不拉重字段、旧 CIPE 数据不返回主 Agent、medium verbosity 只在状态变化时输出——每一处设计都在为上下文窗口节流。这套 CI Watcher 设计本质上是一份可复用的监视型 Agent范本明确的职责边界、分级字段拉取、双模式状态机、指数退避、结构化返回与分页协议。对于任何需要 Agent 长时间轮询外部服务CI、部署、任务队列并与主 Agent 协作的场景都可以直接借鉴其骨架——尤其是等待模式对陈旧数据的三重防护不拉取、不处理、不返回这是大型 Agent 系统中控制上下文成本最值得学习的设计决策。【免费下载链接】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），仅供参考
Nx Cloud CI Watcher基于 MCP 轮询与自愈状态机的 Subagent 设计深度解析【免费下载链接】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导读本文以 Nx 官方仓库中的.cursor/agents/ci-watcher.md为核心完整拆解一个专用于轮询 Nx Cloud CI 流水线CI Attempt简称 CIPE并监听自愈Self-Healing状态的 AI Subagent 的设计包括ci_informationMCP 工具契约、两阶段操作模式、指数退避轮询、结构化返回格式与 verbosity 分级上报。读完本文你将掌握如何在 Claude Code 等 Agent 体系中构建一个只观测、不决策的监视型 Subagent理解其如何与主 Agent 协作完成监视 CI → 发现修复 → 应用/验证 → 再次监视的完整闭环并能直接照搬其中的状态机与字段设计。一、CI Watcher 的角色定位只观测、不决策CI Watcher 是一个被主 Agentorchestrator派生的监视子代理。其职责被严格限定为四条使用ci_informationMCP 工具轮询 CI 状态在两次轮询之间实现指数退避exponential backoff在达到可行动状态actionable condition时返回结构化状态跟踪迭代次数与累计耗时并按 verbosity 级别输出状态更新。最关键的一条边界是CI Watcher 不做 apply/reject 决策——那是主 Agent 的职责它也不执行任何 git 操作只负责轮询与上报。这种侦察兵式设计把上下文消耗控制在了子代理内部让主 Agent 的上下文窗口只接收有意义的、精简过的状态摘要。在仓库中这份定义与命令入口一一对应命令.cursor/commands/ci-monitor.md是编排器主 Agent技能文件.cursor/skills/ci-monitor/SKILL.md提供了同样的编排逻辑而.cursor/agents/ci-watcher.md正是主 Agent 通过Task(agent: ci-watcher, ...)派生的轮询执行体。输入参数契约主 Agent 通过 prompt 传入以下可选参数全部可省略有默认行为兜底参数说明默认行为branch要监视的分支未提供时自动探测当前 git 分支expectedCommitSha期望触发新 CI Attempt 的提交 SHA未提供则进入新鲜开始模式previousCipeUrl行动之前的 CI Attempt URL用于检测变化未提供则进入新鲜开始模式subagentTimeout轮询超时时间分钟60verbosity输出级别minimal / medium / verbosemedium其中expectedCommitSha与previousCipeUrl是关键信号只要二者出现其一Subagent 就必须进入等待新 CIPE模式Wait Mode检测是否有新的 CI Attempt 被触发。二、MCP 工具契约ci_information的输入与输出CI Watcher 唯一依赖的 MCP 工具是ci_information其 JSON Schema 是整套状态机的数据基础。输入结构{ branch: string (optional, defaults to current git branch), select: string (optional, comma-separated field names), pageToken: number (optional, 0-based pagination for long strings) }输出结构完整字段{ cipeStatus: NOT_STARTED | IN_PROGRESS | SUCCEEDED | FAILED | CANCELED | TIMED_OUT, cipeUrl: string, branch: string, commitSha: string | null, failedTaskIds: string[], verifiedTaskIds: string[], selfHealingEnabled: boolean, selfHealingStatus: NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null, verificationStatus: NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null, userAction: NONE | APPLIED | REJECTED | APPLIED_LOCALLY | APPLIED_AUTOMATICALLY | null, failureClassification: string | null, taskOutputSummary: string | null, suggestedFixReasoning: string | null, suggestedFixDescription: string | null, suggestedFix: string | null, shortLink: string | null, couldAutoApplyTasks: boolean | null, confidence: number | null, confidenceReasoning: string | null }对字段的语义理解是整个监视逻辑的前提cipeStatus描述 CI Attempt 本身的生命周期未开始、进行中、成功、失败、取消、超时selfHealingStatus描述 Nx Cloud 自愈代理的工作状态它是否在生成修复、修复是否完成、是否不可执行verificationStatus描述对生成修复的验证状态——自愈代理在应用修复前会先运行验证确认修复确实能解决问题couldAutoApplyTasks表示修复是否具备自动应用资格它与verificationStatus共同决定最终走自动应用还是人工介入failedTaskIds/verifiedTaskIds分别记录失败任务与已验证任务主 Agent 通过两者集合关系做进一步决策taskOutputSummary、suggestedFix、suggestedFixReasoning、suggestedFixDescription是重量级内容字段其中suggestedFix可能是完整补丁文件必须谨慎按需拉取。select参数轮询效率的关键ci_information通过select控制返回内容这是上下文节约的第一道闸门用法返回内容不传select格式化概览会被截断不推荐用于轮询单个字段字段原始值长字符串支持分页多个字段逗号分隔包含所请求字段值的对象文档还预定义了三个典型字段集按探测成本分级WAIT_FIELDS: cipeUrl,commitSha,cipeStatus # 最小字段集仅用于检测新 CI Attempt 是否出现 LIGHT_FIELDS: cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning # 状态字段集用于判定是否达到可行动状态 HEAVY_FIELDS: taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription # 大内容字段仅当要返回主 Agent 时才拉取这套分级设计贯穿整个轮询循环等待阶段只拉WAIT_FIELDS正常轮询阶段拉LIGHT_FIELDS只有在确定要返回结果时才补拉HEAVY_FIELDS。三、初始等待与两阶段操作模式首次轮询前的等待在第一次轮询之前CI Watcher 需要先睡一段时间让 CI 有时间启动或被触发新鲜开始无期望 CIPE等待 60 秒让 CI 有机会启动期望新 CIPE等待 30 秒因为触发动作已经发生CIPE 会更快出现。一个容易被忽略的实现细节是sleep 必须以前台命令运行绝不能放后台。后台 sleep 在结束时会产生多余的交互提示打断 Agent 的工作流sleep 60 # 或期望新 CIPE 时用 30前台执行不要后台化模式一Fresh Start新鲜开始当主 Agent 未提供expectedCommitSha或previousCipeUrl时Subagent 进入普通轮询模式ci_information返回什么 CIPE 就处理什么 CIPE。模式二Wait-for-New-CIPE等待新 CIPE当提供了expectedCommitSha或previousCipeUrl时Subagent 进入等待模式其核心纪律是完全忽略旧的/过期的 CIPE——不处理它的状态不基于它返回任何可行动状态。Phase A等待模式启动新 CIPE 超时计时器默认 30 分钟每次轮询ci_information时判断 CIPE 是否为新cipeUrl与previousCipeUrl不同 → 检测到新 CIPEcommitSha与expectedCommitSha匹配 → 检测到正确的 CIPE如果仍是旧 CIPE忽略所有状态字段继续等待并轮询输出等待状态见下若 30 分钟超时 → 返回no_new_cipe。Phase B正常轮询检测到新 CIPE 后清除新 CIPE 超时计时器、切换到正常轮询模式、按新 CIPE 的状态正常处理、在达到可行动状态时返回。等待模式的输出示例[CI Monitor] ═══════════════════════════════════════════════════════ [CI Monitor] WAIT MODE - Expecting new CI Attempt [CI Monitor] Expected SHA: expectedCommitSha [CI Monitor] Previous CI Attempt: previousCipeUrl [CI Monitor] ═══════════════════════════════════════════════════════ [CI Monitor] Polling... (elapsed: 0m 30s) [CI Monitor] Still seeing previous CI Attempt (ignoring): oldCipeUrl [CI Monitor] Polling... (elapsed: 2m 30s) [CI Monitor] ✓ New CI Attempt detected! URL: newCipeUrl, SHA: newCommitSha [CI Monitor] Switching to normal polling mode...等待模式的价值上下文保护Context Preservation为什么要设计如此严格的忽略旧 CIPE纪律因为过期 CIPE 的数据可能极其庞大taskOutputSummary可能包含数千字符的构建/测试输出suggestedFix完整的补丁文件suggestedFixReasoning详细的推理说明。没有等待模式时Subagent 会把旧 CIPE 的海量数据带回主 Agent主 Agent 的上下文窗口被无用信息污染——明明这个 CIPE 已经被处理过了。有了等待模式旧数据留在 Subagent 内部被丢弃只有新的、相关的 CIPE 数据才会返回给主 Agent。这是整套设计中最具工程价值的思想把轮询产生的噪声隔离在子代理层让主 Agent 只看到有意义的状态变化。四、轮询循环状态机、退避与重字段拉取内部状态累积Subagent 在多次轮询之间维护内部累积状态accumulated state每次轮询后把响应合并进去accumulated_state {}按模式选择字段集等待模式只拉最小字段cipeUrl,commitSha,cipeStatus仅用于检测 CIPE 变化绝不拉重字段过期数据浪费上下文正常模式拉LIGHT_FIELDS全集判断可行动状态。继续轮询的条件只要满足以下任一条件就继续带退避轮询条件原因cipeStatus IN_PROGRESSCI 仍在运行cipeStatus NOT_STARTEDCI 尚未启动selfHealingStatus IN_PROGRESS自愈代理正在工作selfHealingStatus NOT_STARTED自愈尚未开始failureClassification FLAKY_TASK自动重跑进行中userAction APPLIED_AUTOMATICALLY自动应用后正在生成新 CI Attempt当couldAutoApplyTasks true时判定进一步细化verificationStatus为NOT_STARTED或IN_PROGRESS→ 继续轮询验证仍在进行verificationStatus COMPLETED→ 返回fix_auto_applying自动应用即将发生主 Agent 会派生一个等待模式 Subagent 继续监视verificationStatus为FAILED或NOT_EXECUTABLE→ 返回fix_available自动应用不会发生需要人工介入。指数退避轮询间隔采用指数退避且带上限轮询次数等待时间第 1 次60 秒第 2 次90 秒第 3 次及以后120 秒封顶当状态发生显著变化时退避重置回 60 秒。同样强调前台执行sleep 60 # 第一次等待 sleep 90 # 第二次等待 sleep 120 # 第三次及以后封顶达到可行动状态时拉取重字段在返回主 Agent 之前按目标状态决定是否需要重字段状态所需重字段ci_success无fix_auto_applying无fix_availabletaskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescriptionfix_failedtaskOutputSummaryno_fixtaskOutputSummaryenvironment_issue无no_new_cipe无polling_timeout无cipe_canceled无cipe_timed_out无示例——为fix_available补拉重字段ci_information({ branch: branch_name, select: taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription })拉取后合并进accumulated_state再把合并后的状态返回主 Agent。注意分页重字符串字段默认只返回第一页若hasMore指示还有更多内容需要在返回格式中标注让主 Agent 知道可继续分页拉取。五、返回主 Agent 的判定条件可行动状态机CI Watcher 在满足以下任一条件时立即返回结构化状态状态触发条件ci_successcipeStatus SUCCEEDEDfix_auto_applyingselfHealingStatus COMPLETED且couldAutoApplyTasks true且verificationStatus COMPLETEDfix_availableselfHealingStatus COMPLETED且suggestedFix ! null且couldAutoApplyTasks ! true或verificationStatus为FAILED/NOT_EXECUTABLEfix_failedselfHealingStatus FAILEDenvironment_issuefailureClassification ENVIRONMENT_STATEno_fixcipeStatus FAILED且selfHealingEnabled false或selfHealingStatus NOT_EXECUTABLEno_new_cipe提供了expectedCommitSha/previousCipeUrl但 30 分钟内未出现新 CIPEpolling_timeoutSubagent 轮询超过配置超时默认 60 分钟cipe_canceledcipeStatus CANCELEDcipe_timed_outcipeStatus TIMED_OUT子代理级超时CI Watcher 需要持续追踪耗时一旦轮询超过 60 分钟主 Agent 可配置立即返回status: polling_timeout避免无限占用。六、结构化返回格式与分页指示标准返回格式## CI Monitor Result **Status:** status **Iterations:** count **Elapsed:** minutesm secondss ### CI Attempt Details - **Status:** cipeStatus - **URL:** cipeUrl - **Branch:** branch - **Commit:** commitSha - **Failed Tasks:** failedTaskIds - **Verified Tasks:** verifiedTaskIds ### Self-Healing Details - **Enabled:** selfHealingEnabled - **Status:** selfHealingStatus - **Verification:** verificationStatus - **User Action:** userAction - **Classification:** failureClassification - **Confidence:** confidence - **Confidence Reasoning:** confidenceReasoning ### Fix Information (if available) - **Short Link:** shortLink - **Description:** suggestedFixDescription - **Reasoning:** suggestedFixReasoning ### Task Output Summary (first page) taskOutputSummary [MORE_CONTENT_AVAILABLE: taskOutputSummary, pageToken: 1] ### Suggested Fix (first page) suggestedFix [MORE_CONTENT_AVAILABLE: suggestedFix, pageToken: 1]这种格式的价值在于把原始 JSON 转化为人类与 LLM 都易读的分节结构同时保留字段名cipeStatus、selfHealingStatus等便于主 Agent 精确解析。分页指示器当重字段还有更多内容时追加如下指示符[MORE_CONTENT_AVAILABLE: fieldName, pageToken: nextPage]主 Agent 需要时可继续拉取后续页ci_information({ select: fieldName, pageToken: nextPage })不同字段的分页方向不同需要在实现中注意taskOutputSummary反向分页——page 0 是最新的内容suggestedFix正向分页——page 0 是开头suggestedFixReasoning同样支持分页。no_new_cipe的专用返回格式当返回no_new_cipe时附带额外诊断上下文## CI Monitor Result **Status:** no_new_cipe **Iterations:** count **Elapsed:** minutesm secondss ### Expected CI Attempt Not Found - **Expected Commit SHA:** expectedCommitSha - **Previous CI Attempt URL:** previousCipeUrl - **Last Seen CI Attempt URL:** cipeUrl - **Last Seen Commit SHA:** commitSha - **New CI Attempt Timeout:** 30 minutes (exceeded) ### Likely Cause CI workflow failed before Nx tasks could run (e.g., install step, checkout, auth). Check your CI provider logs for the commit expectedCommitSha. ### Last Known CI Attempt State - **Status:** cipeStatus - **Branch:** branch这个格式直接把最可能原因CI 工作流在 Nx 任务执行前就失败了例如 install、checkout、认证步骤写进返回内容帮助主 Agent 立即向用户给出可执行的排查方向。七、Verbosity 分级输出用最少 Token 汇报状态输出由主 Agent 传入的verbosity参数控制级别输出内容minimal无中间输出只在达到可行动状态时返回最终结果medium默认只在显著状态变化时输出而非每次轮询都输出verbose每次轮询后输出详细阶段信息Minimal轮询期间静默完成时返回。Medium默认仅在状态显著变化时输出节省上下文 token。触发输出的变化包括cipeStatus变化如 IN_PROGRESS → FAILED、selfHealingStatus变化如 IN_PROGRESS → COMPLETED、等待模式下检测到新 CIPE。格式为单行、无装饰[CI Monitor] CI: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 4mVerbose每次轮询后输出详细阶段信息框[CI Monitor] ───────────────────────────────────────────────────── [CI Monitor] Iteration N | Elapsed: Xm Ys [CI Monitor] [CI Monitor] CI Status: cipeStatus [CI Monitor] Self-Healing: selfHealingStatus [CI Monitor] Verification: verificationStatus [CI Monitor] Classification: failureClassification [CI Monitor] [CI Monitor] → human-readable phase description [CI Monitor] ─────────────────────────────────────────────────────Verbose 模式还定义了状态组合到人类可读描述的一一映射例如cipeStatus: FAILEDselfHealingStatus: COMPLETEDverificationStatus: IN_PROGRESS→ Fix generated! Verification running...cipeStatus: FAILEDselfHealingStatus: FAILED→ Self-healing could not generate a fix.。八、与主 Agent 的完整协作闭环CI Watcher 本身只负责监视但它处于一个更大的闭环中。编排器.cursor/commands/ci-monitor.md 与 .cursor/skills/ci-monitor/SKILL.md在启动监视前会先校验工作区是否已连接 Nx Cloud——检查根目录 nx.json 中是否存在nxCloudId或nxCloudAccessToken字段。当前仓库的根 nx.json 并不包含这两个字段说明该仓库本身未连接 Nx Cloud使用本套监视流程前需要先完成连接。当 CI Watcher 返回fix_available时主 Agent 会对比failedTaskIds与verifiedTaskIds做进一步决策任务分类verified tasks 同时出现在两个数组中的任务unverified tasks 只在failedTaskIds中的任务E2E tasks 目标包含 e2e 的未验证任务任务格式为project:target或project:target:configverifiable tasks 非 e2e 的未验证任务路径选择无未验证任务或未验证任务全部是 e2e → 直接通过 MCP 应用存在可验证任务 → 走本地验证流程本地验证根据pnpm-lock.yaml/yarn.lock是否存在选择pnpm nx/yarn nx/npx nx并行派生 general subagent 逐个运行nx run taskId全部通过则经 MCP 应用任一失败则走nx apply-locally shortLink的本地应用 增强流程超过local_verify_attempts默认 3 次后提交推送交由 CI 做最终裁决。这个流程对应的命令实现可以追溯到 Nx 源码.cursor中提到的nx apply-locally命令在 packages/nx/src/command-line/nx-cloud/apply-locally/apply-locally.ts 中实现——它先调用isNxCloudUsed(readNxJson())检查工作区是否连接 Nx Cloud未连接时输出警告直接返回其命令定义位于 packages/nx/src/command-line/nx-cloud/apply-locally/command-object.ts描述为将自愈 CI 修复应用到本地是nx-cloud apply-locally的别名。这与文档中Runnx apply-locally shortLink应用补丁到本地工作目录并将状态置为APPLIED_LOCALLY的描述完全对应。九、完整会话示例下面两个示例展示了整套机制的实际运行形态来自 .cursor/commands/ci-monitor.md 的 Example Session 部分。示例一自愈正常流转medium verbosity[ci-monitor] Starting CI monitor for branch feature/add-auth [ci-monitor] Config: max-cycles5, timeout120m, verbositymedium [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m [CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m [CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m [ci-monitor] Fix available! Verification: COMPLETED [ci-monitor] Applying fix via MCP... [ci-monitor] Fix applied in CI. Waiting for new CI attempt... [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] New CI attempt detected! [CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m [ci-monitor] CI passed successfully! [ci-monitor] Summary: - Total cycles: 2 - Total time: 12m 34s - Fixes applied: 1 - Result: SUCCESS示例二CI 任务前失败 锁文件自动修复[ci-monitor] Starting CI monitor for branch feature/add-products [ci-monitor] Config: max-cycles5, timeout120m, auto-fix-workflowtrue [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m [ci-monitor] Applying fix locally, enhancing, and pushing... [ci-monitor] Committed: abc1234 [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234) [CI Monitor] ⚠️ CI attempt timeout (10 min). Returning no_new_cipe. [ci-monitor] Status: no_new_cipe [ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update... [ci-monitor] Lockfile updated. Committed: def5678 [ci-monitor] Spawning subagent to poll CI status... [CI Monitor] New CI attempt detected! [CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m [ci-monitor] CI passed successfully! [ci-monitor] Summary: - Total cycles: 3 - Total time: 22m 15s - Fixes applied: 1 (self-healing) 1 (lockfile) - Result: SUCCESS第二个示例尤其体现了等待模式的价值主 Agent 应用本地修复并 push 后以expectedCommitSha派生等待模式 Subagent当 10 分钟--new-cipe-timeout默认值内没有新 CIPE 出现时返回no_new_cipe主 Agent 据此推断 CI 工作流可能在 Nx 任务执行前就失败install/checkout/认证等进而启用--auto-fix-workflow尝试更新锁文件并再次进入监视循环。十、重要注意事项与容错设计把ci-watcher.md中强调的工程约束汇总如下职责隔离不做 apply/reject 决策不做 git 操作只轮询和上报尊重 verbosity默认 medium避免无意义输出错误重试ci_information返回错误时等待并重试计为一次失败轮询连续 5 次失败时返回status: error双超时并行管理等待新 CIPE 的 30 分钟超时与整体轮询的 60 分钟超时要分开跟踪互不干扰前台 sleep所有退避等待都必须前台执行后台 sleep 结束时会触发无关的交互提示上下文即成本等待模式不拉重字段、旧 CIPE 数据不返回主 Agent、medium verbosity 只在状态变化时输出——每一处设计都在为上下文窗口节流。这套 CI Watcher 设计本质上是一份可复用的监视型 Agent范本明确的职责边界、分级字段拉取、双模式状态机、指数退避、结构化返回与分页协议。对于任何需要 Agent 长时间轮询外部服务CI、部署、任务队列并与主 Agent 协作的场景都可以直接借鉴其骨架——尤其是等待模式对陈旧数据的三重防护不拉取、不处理、不返回这是大型 Agent 系统中控制上下文成本最值得学习的设计决策。【免费下载链接】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），仅供参考
