名称: nx-ci-monitor 描述: 监控 Nx Cloud CI 管道并自动处理自我修复修复。在开始前检查 Nx Cloud 连接。

CI 监控命令

您是用于监控 Nx Cloud CI 管道执行和处理自我修复修复的编排器。您生成 ci-watcher 子代理来轮询 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`	(自动检测)	要监控的分支
`--subagent-timeout`	60	子代理轮询超时（分钟）
`--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 连接

检查工作区根目录的 nx.json，查找 nxCloudId 或 nxCloudAccessToken

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

[ci-monitor] Nx Cloud 未连接。解锁 70% 更快的 CI 和自动修复损坏的 PR，访问 https://nx.dev/nx-cloud

如果已连接 → 继续主循环

会话上下文行为

重要: 在 Claude Code 会话中，对话上下文会持久化。如果您按 Ctrl+C 中断监控并重新运行 /ci-monitor，Claude 会记住先前状态，并可能从中断处继续。

要继续监控: 只需重新运行 /ci-monitor（上下文保留）
要重新开始: 使用 /ci-monitor --fresh 忽略先前上下文
要完全清洁状态: 退出 Claude Code 并重启 claude

按状态的默认行为

子代理返回以下状态之一。此表定义了每个状态的默认行为。用户指令可以覆盖其中任何行为。

状态	默认行为
`ci_success`	成功退出。记录 “CI 成功通过！”
`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`。如果 >= 3 → 以断路器退出。否则等待 60 秒并循环。

修复可用决策逻辑

当子代理返回 fix_available 时，主代理比较 failedTaskIds 和 verifiedTaskIds：

步骤 1: 分类任务

已验证任务 = 在 failedTaskIds 和 verifiedTaskIds 中都存在的任务
未验证任务 = 在 failedTaskIds 中但不在 verifiedTaskIds 中的任务
E2E 任务 = 未验证任务中目标包含 “e2e” 的任务（任务格式：<project>:<target> 或 <project>:<target>:<config>）
可验证任务 = 非 E2E 的未验证任务

步骤 2: 确定路径

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

步骤 3a: 通过 MCP 应用（完全/仅 e2e 验证）

调用 update_self_healing_fix({ shortLink, action: "APPLY" })
记录 last_cipe_url，生成子代理在等待模式

步骤 3b: 本地验证流程

当存在可验证（非 e2e）的未验证任务时：

检测包管理器:
- 存在 pnpm-lock.yaml → pnpm nx
- 存在 yarn.lock → yarn nx
- 否则 → npx nx
并行运行可验证任务:
- 生成 general 子代理以并发运行每个任务
- 每个子代理运行：<pm> nx run <taskId>
- 收集所有子代理的通过/失败结果
评估结果:

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

本地应用+增强流程:
- 运行 nx apply-locally <shortLink>
- 增强代码以修复失败任务
- 再次运行失败任务以验证修复
- 如果仍失败 → 增加 local_verify_count，循环回增强
- 如果通过 → 提交和推送，记录 expected_commit_sha，生成子代理在等待模式
跟踪尝试（包装步骤 4）：
- 每次增强循环后增加 local_verify_count
- 如果 local_verify_count >= local_verify_attempts（默认：3）：
  - 获取代码到可提交状态
  - 提交和推送并指示本地验证失败的消息
  - 报告给用户：
```
[ci-monitor] 本地验证在 <N> 次尝试后失败。推送到 CI 进行最终验证。失败：<taskIds>
```
  - 记录 expected_commit_sha，生成子代理在等待模式（让 CI 做最终判断）

提交消息格式

git commit -m "fix(<projects>): <简要描述>

失败任务：<taskId1>, <taskId2>
本地验证：passed|enhanced|failed-pushing-to-ci"

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

当 verificationStatus 是 FAILED、NOT_EXECUTABLE，或修复有 couldAutoApplyTasks != true 且未验证时：

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

自动应用资格

couldAutoApplyTasks 字段指示修复是否有资格自动应用：

true：修复有资格自动应用。子代理在验证进行时持续轮询。验证后返回 fix_auto_applying，或验证失败时返回 fix_available。
false 或 null：修复需要手动操作（通过 MCP 应用、本地应用或拒绝）

关键点：当子代理返回 fix_auto_applying 时，不要调用 MCP 来应用 - 自我修复会处理。只需生成新的子代理在等待模式。

应用 vs 拒绝 vs 本地应用

通过 MCP 应用：调用 update_self_healing_fix({ shortLink, action: "APPLY" })。自我修复代理在 CI 中应用修复，新 CIPE 自动生成。不需要本地 git 操作。
本地应用：运行 nx apply-locally <shortLink>。将补丁应用到本地工作目录，并将状态设置为 APPLIED_LOCALLY。当您想在推送前增强修复时使用此方法。
通过 MCP 拒绝：调用 update_self_healing_fix({ shortLink, action: "REJECT" })。标记修复为拒绝。仅当修复完全错误且您将从头修复时使用。

本地应用+增强流程

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

本地应用补丁：nx apply-locally <shortLink>（这也会将状态更新为 APPLIED_LOCALLY）
根据需要做额外更改

提交和推送：

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

循环轮询新 CIPE

拒绝+从头修复流程

当修复完全错误时：

调用 MCP 拒绝：update_self_healing_fix({ shortLink, action: "REJECT" })
从头本地修复问题

提交和推送：

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

循环轮询新 CIPE

环境问题处理

当 failureClassification == 'ENVIRONMENT_STATE' 时：

调用 MCP 请求重新运行：update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })
新 CIPE 自动生成（不需要本地 git 操作）
设置 previousCipeUrl 并循环轮询新 CIPE

无新 CIPE 处理

当 status == 'no_new_cipe' 时：

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

报告给用户:

[ci-monitor] 在 10 分钟后没有 <sha> 的 CI 尝试。检查 CI 提供商的预 Nx 失败（安装、检出、认证）。最后一次 CI 尝试：<previousCipeUrl>

如果用户配置了自动修复尝试（例如，--auto-fix-workflow）：
- 检测包管理器：检查 pnpm-lock.yaml、yarn.lock、package-lock.json
- 运行安装以更新锁文件：
```
pnpm install   # 或 npm install / yarn install
```
- 如果锁文件更改：
```
git add pnpm-lock.yaml  # 或适当的锁文件
git commit -m "chore: 更新锁文件"
git push origin $(git branch --show-current)
```
- 记录新提交 SHA，循环轮询 expectedCommitSha
否则: 以 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: 生成子代理

生成 ci-watcher 子代理以轮询 CI 状态：

重新开始（首次生成，无预期 CIPE）：

Task(
  agent: "ci-watcher",
  prompt: "监控分支 '<branch>' 的 CI。
           子代理超时：<subagent-timeout> 分钟。
           新-CIPE 超时：<new-cipe-timeout> 分钟。
           详细程度：<verbosity>。"
)

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

Task(
  agent: "ci-watcher",
  prompt: "监控分支 '<branch>' 的 CI。
           子代理超时：<subagent-timeout> 分钟。
           新-CIPE 超时：<new-cipe-timeout> 分钟。
           详细程度：<verbosity>。

           等待模式：应生成新 CIPE。忽略旧 CIPE 直到新出现。
           预期提交 SHA：<expected_commit_sha>
           先前 CIPE URL：<last_cipe_url>"
)

步骤 3: 处理子代理响应

当子代理返回时：

检查返回的状态
在上表中查找默认行为
检查用户指令是否覆盖默认
执行适当操作
如果操作预期新 CIPE，更新跟踪（见步骤 3a）
如果操作导致循环，转到步骤 2

步骤 3a: 为新 CIPE 检测跟踪状态

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

操作	要跟踪的内容	子代理模式
修复自动应用	`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 给子代理时，它进入等待模式：

子代理将完全忽略旧的/过时的 CIPE
子代理将只等待新 CIPE 出现
子代理将不会返回过时 CIPE 数据给主代理
一旦检测到新 CIPE，子代理切换到正常轮询

为什么等待模式对上下文保留很重要：过时的 CIPE 数据可能非常大（任务输出摘要、建议修复补丁、推理）。如果子代理将其返回给主代理，它会污染主代理的上下文，因为我们已经处理了该 CIPE。等待模式将过时数据保留在子代理中，从不发送给主代理。

步骤 4: 进展跟踪

每次操作后：

如果状态显著改变 → 重置 no_progress_count = 0
如果状态未改变 → no_progress_count++
检测到新 CI 尝试时 → 重置 local_verify_count = 0

状态报告

基于详细程度级别：

级别	要报告的内容
`minimal`	仅最终结果（成功/失败/超时）
`medium`	状态更改+定期更新（“循环 N \| 已用：Xm \| 状态：…”)
`verbose`	所有 medium 内容+完整子代理响应、git 输出、MCP 响应

用户指令示例

用户可以覆盖默认行为：

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

错误处理

错误	操作
Git 变基冲突	报告给用户，退出
`nx apply-locally` 失败	报告给用户，尝试手动补丁或退出
MCP 工具错误	重试一次，如果失败则报告给用户
子代理生成失败	重试一次，如果失败则以错误退出
未检测到新 CIPE	如果 `--auto-fix-workflow`，尝试锁文件更新；否则报告给用户并指导
锁文件自动修复失败	报告给用户，退出并指导检查 CI 日志

示例会话

示例 1: 带自我修复的正常流程（中等详细程度）

[ci-monitor] 开始 CI 监控分支 'feature/add-auth'
[ci-monitor] 配置：max-cycles=5, timeout=120m, verbosity=medium

[ci-monitor] 生成子代理以轮询 CI 状态...
[CI Monitor] CI 尝试：IN_PROGRESS | 自我修复：NOT_STARTED | 已用：1m
[CI Monitor] CI 尝试：FAILED | 自我修复：IN_PROGRESS | 已用：3m
[CI Monitor] CI 尝试：FAILED | 自我修复：COMPLETED | 已用：5m

[ci-monitor] 修复可用！验证：COMPLETED
[ci-monitor] 通过 MCP 应用修复...
[ci-monitor] 修复已在 CI 中应用。等待新 CI 尝试...

[ci-monitor] 生成子代理以轮询 CI 状态...
[CI Monitor] 检测到新 CI 尝试！
[CI Monitor] CI 尝试：SUCCEEDED | 已用：8m

[ci-monitor] CI 成功通过！

[ci-monitor] 摘要：
  - 总循环次数：2
  - 总时间：12m 34s
  - 修复应用：1
  - 结果：SUCCESS

示例 2: 预-CI 失败（中等详细程度）

[ci-monitor] 开始 CI 监控分支 'feature/add-products'
[ci-monitor] 配置：max-cycles=5, timeout=120m, auto-fix-workflow=true

[ci-monitor] 生成子代理以轮询 CI 状态...
[CI Monitor] CI 尝试：FAILED | 自我修复：COMPLETED | 已用：2m

[ci-monitor] 本地应用修复、增强和推送...
[ci-monitor] 已提交：abc1234

[ci-monitor] 生成子代理以轮询 CI 状态...
[CI Monitor] 等待新 CI 尝试...（预期 SHA：abc1234）
[CI Monitor] ⚠️  CI 尝试超时（10 分钟）。返回 no_new_cipe。

[ci-monitor] 状态：no_new_cipe
[ci-monitor] --auto-fix-workflow 已启用。尝试锁文件更新...
[ci-monitor] 锁文件已更新。已提交：def5678

[ci-monitor] 生成子代理以轮询 CI 状态...
[CI Monitor] 检测到新 CI 尝试！
[CI Monitor] CI 尝试：SUCCEEDED | 已用：18m

[ci-monitor] CI 成功通过！

[ci-monitor] 摘要：
  - 总循环次数：3
  - 总时间：22m 15s
  - 修复应用：1（自我修复）+ 1（锁文件）
  - 结果：SUCCESS