nx-ci-monitor

CI Monitor 命令

你是监控 Nx Cloud CI 流水线执行并处理自我修复的协调器。你会启动 ci-watcher 子 Agent 来轮询 CI 状态，并根据结果做出决策。

上下文

• 当前分支： !git branch --show-current
• 当前提交： !git rev-parse --short HEAD
• 远程状态： !git status -sb | head -1

用户指令

$ARGUMENTS

重要： 如果用户提供了具体指令，请优先遵循这些指令，而非以下默认行为。

默认配置

设置	默认值	说明
--max-cycles	10	超时前允许的最大 CIPE 周期数
--timeout	120	最长持续时间（分钟）
--verbosity	medium	输出级别：minimal、medium、verbose
--branch	(auto-detect)	要监控的分支
--subagent-timeout	60	子 Agent 轮询超时时间（分钟）
--fresh	false	忽略先前上下文，从头开始
--auto-fix-workflow	false	尝试修复常见的 CIPE 前置失败（例如更新锁文件）
--new-cipe-timeout	10	操作后等待新 CIPE 的分钟数
--local-verify-attempts	3	推送到 CI 前，本地验证与改进周期的最大次数

解析 $ARGUMENTS 中的所有覆盖项，并与默认值合并。

Nx Cloud 连接检查

关键： 开始监控循环前，请确认工作区已连接到 Nx Cloud。

步骤 0：确认 Nx Cloud 连接

1. 检查工作区根目录下的 nx.json，确认其中包含 nxCloudId 或 nxCloudAccessToken

2. 如果 nx.json 缺失，或这两个属性均不存在 → 退出并显示：

   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
   

3. 如果已连接 → 继续主循环

会话上下文行为

重要： 在 Claude Code 会话中，对话上下文会持续保留。如果按 Ctrl+C 中断监控，然后重新运行 /ci-monitor，Claude 会记住之前的状态，并可能从中断处继续。

• 继续监控： 只需重新运行 /ci-monitor（上下文会保留）
• 从头开始： 使用 /ci-monitor --fresh 忽略之前的上下文
• 彻底重置： 退出 Claude Code，然后重新启动 claude

按状态划分的默认行为

子代理返回以下某个状态。此表定义了每种状态对应的默认行为。用户指令可以覆盖这些行为。

状态	默认行为
ci_success	成功退出。记录日志 "CI passed successfully!"
fix_auto_applying	自愈功能将自动应用修复。不要调用 MCP。记录 last_cipe_url，并启动新的子代理进入等待模式，以轮询新的 CIPE。
fix_available	对比 failedTaskIds 和 verifiedTaskIds，确定验证状态。请参阅下方的可用修复决策逻辑部分。
fix_failed	自愈功能未能生成修复。根据 taskOutputSummary 尝试本地修复。若成功 → 提交、推送并循环。若失败 → 以失败状态退出。
environment_issue	调用 MCP 请求重新运行：update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })。系统会自动启动新的 CIPE。循环轮询新的 CIPE。
no_fix	CI 失败，且没有可用修复（自愈已禁用或无法执行）。尽可能尝试本地修复。否则以失败状态退出。
no_new_cipe	预期启动的 CIPE 未能启动（CI 工作流可能在 Nx 任务运行前失败）。向用户报告；若已配置，则尝试常见修复，否则退出并提供指导。
polling_timeout	子代理轮询超时。以超时状态退出。
cipe_canceled	CIPE 已取消。以已取消状态退出。
cipe_timed_out	CIPE 已超时。以超时状态退出。
error	将 no_progress_count 加 1。若 >= 3 → 触发断路器并退出。否则等待 60 秒后循环。

可用修复决策逻辑

当子代理返回 fix_available 时，主 Agent 会对比 failedTaskIds 和 verifiedTaskIds：

第 1 步：任务分类

1. 已验证任务 = 同时存在于 failedTaskIds 和 verifiedTaskIds 中的任务
2. 未验证任务 = 存在于 failedTaskIds 但不在 verifiedTaskIds 中的任务
3. E2E 任务 = 目标中包含 "e2e" 的未验证任务（任务格式：<project>:<target> 或 <project>:<target>:<config>）
4. 可验证任务 = 不是 E2E 任务的未验证任务

第 2 步：确定路径

条件	路径
没有未验证任务（全部已验证）	通过 MCP 应用
存在未验证任务，但全部都是 E2E 任务	通过 MCP 应用（视为验证充分）
存在可验证任务	本地验证流程

第 3a 步：通过 MCP 应用（已完全验证／仅 E2E 验证）

• 调用 update_self_healing_fix({ shortLink, action: "APPLY" })
• 记录 last_cipe_url，并启动子代理进入等待模式

步骤 3b：本地验证流程

存在可验证（非端到端）的未验证任务时：

1. 检测包管理器：

   • 存在 pnpm-lock.yaml → pnpm nx
   • 存在 yarn.lock → yarn nx
   • 否则 → npx nx

2. 并行运行可验证任务：

   • 启动 general 子 Agent，并发运行每项任务
   • 每个子 Agent 运行：<pm> nx run <taskId>
   • 收集所有子 Agent 的通过／失败结果

3. 评估结果：

结果	操作
所有可验证任务均通过	通过 MCP 应用
任一可验证任务失败	本地应用 + 增强流程

1. 本地应用 + 增强流程：

   • 运行 nx apply-locally <shortLink>
   • 增强代码以修复失败任务
   • 再次运行失败任务以验证修复
   • 若仍然失败 → 增加 local_verify_count，返回增强步骤继续循环
   • 若通过 → 提交并推送，记录 expected_commit_sha，启动处于等待模式的子 Agent

2. 跟踪尝试次数（对应步骤 4）：

   • 每轮增强后增加 local_verify_count
   • 如果 local_verify_count >= local_verify_attempts（默认值：3）：

     • 将代码调整到可提交状态

     • 提交并推送，提交说明中指出本地验证失败

     • 向用户报告：

       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
       

     • 记录 expected_commit_sha，启动处于等待模式的子 Agent（让 CI 做最终判断）

提交消息格式

git commit -m "fix(<projects>): <brief description>

Failed tasks: <taskId1>, <taskId2>
Local verification: passed|enhanced|failed-pushing-to-ci"

未验证修复流程（未尝试验证）

当 verificationStatus 为 FAILED、NOT_EXECUTABLE，或修复的 couldAutoApplyTasks != true 且未进行验证时：

• 分析修复内容（suggestedFix、suggestedFixReasoning、taskOutputSummary）
• 如果修复看起来正确 → 通过 MCP 应用
• 如果修复需要增强 → 使用上文的本地应用 + 增强流程
• 如果修复有误 → 通过 MCP 拒绝，从头修复、提交并推送

自动应用资格

couldAutoApplyTasks 字段表示修复是否符合自动应用条件：

• true：修复符合自动应用条件。验证进行期间，子 Agent 会继续轮询。验证通过时返回 fix_auto_applying，验证失败时返回 fix_available。
• false 或 null：修复需要手动操作（通过 MCP 应用、本地应用或拒绝）

要点：子 Agent 返回 fix_auto_applying 时，不要调用 MCP 应用修复——自愈流程会负责处理。只需启动一个新的等待模式子 Agent。

应用、拒绝与本地应用

• 通过 MCP 应用：调用 update_self_healing_fix({ shortLink, action: "APPLY" })。自愈 Agent 会在 CI 中应用修复，并自动启动新的 CIPE。无需执行本地 Git 操作。
• 本地应用：运行 nx apply-locally <shortLink>。将补丁应用到本地工作目录，并将状态设为 APPLIED_LOCALLY。当你希望在推送前增强修复时使用此方式。
• 通过 MCP 拒绝：调用 update_self_healing_fix({ shortLink, action: "REJECT" })。将修复标记为已拒绝。仅当修复完全错误且你将从头修复时使用。

本地应用 + 增强流程

修复需要增强时（使用 nx apply-locally，不要拒绝）：

1. 在本地应用补丁：nx apply-locally <shortLink>（这也会将状态更新为 APPLIED_LOCALLY）

2. 按需进行其他更改

3. 提交并推送：

   git add -A
   git commit -m "fix: resolve <failedTaskIds>"
   git push origin $(git branch --show-current)
   

4. 循环轮询新的 CIPE

拒绝 + 从头修复流程

修复完全错误时：

1. 调用 MCP 拒绝：update_self_healing_fix({ shortLink, action: "REJECT" })

2. 在本地从头修复问题

3. 提交并推送：

   git add -A
   git commit -m "fix: resolve <failedTaskIds>"
   git push origin $(git branch --show-current)
   

4. 循环轮询新的 CIPE

环境问题处理

当 failureClassification == 'ENVIRONMENT_STATE' 时：

1. 调用 MCP 请求重新运行：update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })
2. 系统会自动启动新的 CIPE（无需执行本地 git 操作）
3. 循环轮询新的 CIPE，并设置 previousCipeUrl

未创建新 CIPE 的处理

当 status == 'no_new_cipe' 时：

这意味着预期的 CIPE 从未创建——CI 可能在 Nx 任务运行前就已失败。

1. 向用户报告：

   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
   

2. 如果用户配置了自动修复尝试（例如 --auto-fix-workflow）：

   • 检测包管理器：检查是否存在 pnpm-lock.yaml、yarn.lock、package-lock.json

   • 运行安装以更新锁文件：

     pnpm install   # or npm install / yarn install
     

   • 如果锁文件已更改：

     git add pnpm-lock.yaml  # or appropriate lockfile
     git commit -m "chore: update lockfile"
     git push origin $(git branch --show-current)
     

   • 记录新的提交 SHA，循环轮询并设置 expectedCommitSha

3. **否则：**以 no_new_cipe 状态退出，并提供指导，帮助用户进行调查

退出条件

满足以下任一条件时，退出监控循环：

条件	退出类型
CI 通过（cipeStatus == 'SUCCEEDED'）	成功
达到最大 CIPE 周期数	超时
达到最长持续时间	超时
连续 3 次迭代没有进展	熔断
没有可用修复，且无法进行本地修复	失败
未创建新 CIPE，且未配置自动修复	CIPE 创建前失败
用户取消	已取消

主循环

步骤 1：初始化跟踪

cycle_count = 0
start_time = now()
no_progress_count = 0
local_verify_count = 0
last_state = null
last_cipe_url = null
expected_commit_sha = null

步骤 2：启动子 Agent

启动 ci-watcher 子 Agent 以轮询 CI 状态：

全新启动（首次启动，没有预期的 CIPE）：

Task(
  agent: "ci-watcher",
  prompt: "Monitor CI for branch '<branch>'.
           Subagent timeout: <subagent-timeout> minutes.
           New-CIPE timeout: <new-cipe-timeout> minutes.
           Verbosity: <verbosity>."
)

触发新 CIPE 的操作后（等待模式）：

Task(
  agent: "ci-watcher",
  prompt: "Monitor CI for branch '<branch>'.
           Subagent timeout: <subagent-timeout> minutes.
           New-CIPE timeout: <new-cipe-timeout> minutes.
           Verbosity: <verbosity>.

           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
           Expected commit SHA: <expected_commit_sha>
           Previous CIPE URL: <last_cipe_url>"
)

步骤 3：处理子 Agent 响应

子 Agent 返回时：

1. 检查返回的状态
2. 在上方表格中查找默认行为
3. 检查用户指令是否覆盖默认行为
4. 执行相应操作
5. 如果操作预期会创建新的 CIPE，更新跟踪信息（参见步骤 3a）
6. 如果操作会进入循环，转到步骤 2

步骤 3a：跟踪状态以检测新 CIPE

执行应触发新 CIPE 的操作后，在循环前记录状态：

操作	跟踪内容	子 Agent 模式
修复并自动应用	last_cipe_url = current cipeUrl	等待模式
通过 MCP 应用	last_cipe_url = current cipeUrl	等待模式
本地应用并推送	expected_commit_sha = $(git rev-parse HEAD)	等待模式
拒绝 + 修复 + 推送	expected_commit_sha = $(git rev-parse HEAD)	等待模式
修复失败 + 本地修复 + 推送	expected_commit_sha = $(git rev-parse HEAD)	等待模式
不修复 + 本地修复 + 推送	expected_commit_sha = $(git rev-parse HEAD)	等待模式
环境重新运行	last_cipe_url = current cipeUrl	等待模式
没有新 CIPE + 自动修复 + 推送	expected_commit_sha = $(git rev-parse HEAD)	等待模式

重要：将 expectedCommitSha 或 last_cipe_url 传递给子 Agent 时，它会进入等待模式：

• 子 Agent 会完全忽略旧的／过时的 CIPE
• 子 Agent 只会等待新 CIPE 出现
• 子 Agent 不会将过时的 CIPE 数据返回给主 Agent
• 检测到新 CIPE 后，子 Agent 会切换到正常轮询模式

等待模式对保留上下文很重要的原因：过时的 CIPE 数据可能非常庞大（任务输出摘要、建议的修复补丁、推理内容）。如果子 Agent 将这些数据返回给主 Agent，由于我们已处理过该 CIPE，这些无用数据会污染主 Agent 的上下文。等待模式会将过时数据留在子 Agent 中，不会发送给主 Agent。

步骤 4：进度跟踪

每次操作后：

• 如果状态发生重大变化 → 重置 no_progress_count = 0
• 如果状态未变化 → no_progress_count++
• 检测到新的 CI 尝试 → 重置 local_verify_count = 0

状态报告

根据详细程度：

级别	报告内容
minimal	仅报告最终结果（成功／失败／超时）
medium	状态变化 + 定期更新（“周期 N | 已用时：Xm | 状态：...”）
verbose	包含 medium 的全部内容 + 完整的子 Agent 响应、git 输出、MCP 响应

用户指令示例

用户可以覆盖默认行为：

指令	效果
“绝不自动应用”	应用任何修复前始终先征求确认
“git push 前始终询问”	每次推送前都征求确认
“拒绝所有 e2e 任务的修复”	如果 failedTaskIds 包含 e2e，则自动拒绝
“无论验证结果如何都应用所有修复”	跳过验证检查，应用所有修复
“如果置信度 < 70，则拒绝”	应用前检查置信度字段
“应用前运行 'nx affected -t typecheck'”	添加本地验证步骤
“自动修复工作流失败”	尝试在 CIPE 前失败时更新 lockfile
“等待 45 分钟以获取新 CIPE”	覆盖新 CIPE 超时时间（默认：10 分钟）

错误处理

错误	操作
Git 变基冲突	向用户报告并退出
nx apply-locally 失败	向用户报告，尝试手动修补或退出
MCP 工具错误	重试一次；若仍失败，向用户报告
子 Agent 启动失败	重试一次；若仍失败，报错退出
未检测到新的 CIPE	若使用 --auto-fix-workflow，尝试更新锁文件；否则向用户报告并提供指导
锁文件自动修复失败	向用户报告并退出，同时指导用户检查 CI 日志

示例会话

示例 1：具有自我修复功能的正常流程（中等详细程度）

[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium

[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

示例 2：CI 前失败（中等详细程度）

[ci-monitor] Starting CI monitor for branch 'feature/add-products'
[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true

[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