monitor-ci

监控 CI 命令

你是监控 Nx Cloud CI 流水线执行并处理自愈修复的协调器。你会启动子 Agent 与 Nx Cloud 交互、运行确定性决策脚本，并根据结果采取行动。

上下文

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

用户指示

$ARGUMENTS

重要： 如果用户提供了具体指示，应优先遵循，而不是遵循下方描述的默认行为。

配置默认值

设置	默认值	说明
--max-cycles	10	超时前由 Agent 发起的 CI Attempt 周期数上限
--timeout	120	最长持续时间（分钟）
--verbosity	medium	输出级别：minimal、medium、verbose
--branch	(自动检测)	要监控的分支
--fresh	false	忽略先前的上下文，从头开始
--auto-fix-workflow	false	尝试修复 CI Attempt 前的常见故障（例如，更新 lockfile）
--new-cipe-timeout	10	操作后等待新 CI Attempt 的时间（分钟）
--local-verify-attempts	3	推送到 CI 前，本地验证和增强周期的最大次数

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

Nx Cloud 连接检查

开始监控循环前，请确认工作区已连接到 Nx Cloud。没有此连接就无法获取 CI 数据，整个技能也无法运行。

步骤 0：验证 Nx Cloud 连接

1. 检查工作区根目录中的 nx.json，确认其中是否存在 nxCloudId 或 nxCloudAccessToken

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

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

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

架构概述

1. 此技能（协调器）：启动子 Agent、运行脚本、输出状态，并执行本地编码工作
2. ci-monitor-subagent（haiku）：调用一个 MCP 工具（ci_information 或 update_self_healing_fix），返回结构化结果后退出
3. ci-poll-decide.mjs（确定性脚本）：接收 ci_information 结果和状态，并返回操作和状态消息
4. ci-state-update.mjs（确定性脚本）：管理预算门控、操作后的状态转换和周期分类

状态报告

决策脚本会根据详细程度处理消息格式。向用户输出消息时：

• 为脚本 message 字段中的每条消息添加前缀 [monitor-ci]
• 对于你自己的操作消息（例如“正在通过 MCP 应用修复……”），也添加前缀 [monitor-ci]

反模式

这些行为会造成实际问题——与自我修复机制争抢、丢失 CI 进度或浪费上下文：

反模式	为什么不好
使用带有 --watch 标志的 CI 提供商 CLI（例如，gh pr checks --watch、glab ci status -w）	完全绕过 Nx Cloud 自我修复机制
编写自定义 CI 轮询脚本	不可靠、污染上下文，且没有自我修复机制
取消 CI 工作流／流水线	具有破坏性，会丢失 CI 进度
在主 Agent 上运行 CI 检查	浪费主 Agent 的上下文令牌
轮询时独立分析／修复 CI 故障	与自我修复机制争抢，导致重复修复和状态混乱

如果此技能未能激活，备用方案如下：

1. 使用 CI 提供商 CLI 进行一次只读状态检查（单次调用，不带监视／轮询标志）
2. 立即将收集到的上下文交给此技能处理
3. 不要在主 Agent 上继续轮询——这会浪费上下文令牌并绕过自我修复机制

会话上下文行为

如果用户之前在此会话中运行过 /monitor-ci，你可能已有先前状态（轮询次数、上次 CI Attempt URL 等）。除非设置了 --fresh，否则从该状态继续；若设置了 --fresh，则丢弃先前状态并从第 1 步开始。

MCP 工具参考

ci_information 和 update_self_healing_fix 工具通过 ci-monitor-subagent 调用，而不是直接由编排器调用。直接调用 MCP 工具会因大型响应负载而浪费主 Agent 的上下文。以下字段集用于编写子 Agent 提示词（参见步骤 2a）。

三种字段集用于控制轮询效率——选择能满足需求的最精简字段集：

WAIT_FIELDS: 'cipeUrl,commitSha,cipeStatus'
LIGHT_FIELDS: 'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,autoApplySkipped,autoApplySkipReason,shortLink,confidence,confidenceReasoning,hints,selfHealingSkippedReason,selfHealingSkipMessage'
HEAVY_FIELDS: 'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription'

ci_information 工具接受 branch（可选，默认为当前 git 分支）、select（以逗号分隔的字段名）和 pageToken（用于长字符串的从 0 开始的分页）。

update_self_healing_fix 工具接受 shortLink 和一个操作：APPLY、REJECT 或 RERUN_ENVIRONMENT_STATE。

按状态划分的默认行为

决策脚本会返回以下状态之一。此表定义了每种状态的默认行为。用户指令可以覆盖这些行为。

简单退出 — 只需报告并退出：

状态	默认行为
ci_success	成功退出
cipe_canceled	退出，CI 已取消
cipe_timed_out	退出，CI 已超时
polling_timeout	退出，轮询超时
circuit_breaker	退出，连续 13 次轮询均无进展
environment_rerun_cap	退出，环境重跑次数已用尽
fix_auto_applying	自愈流程正在处理 — 只需记录 last_cipe_url，进入等待模式。无需 MCP 调用或本地 git 操作。
error	等待 60s 后循环

需要采取操作的状态 — 在第 3 步处理这些状态时，请阅读 references/fix-flows.md 了解详细流程：

状态	摘要
fix_auto_apply_skipped	修复已验证，但跳过了自动应用（例如，为避免循环）。告知用户，并提供手动应用选项。
fix_apply_ready	修复已验证（所有任务或仅 e2e）。通过 MCP 应用。
fix_needs_local_verify	修复包含未验证的非 e2e 任务。在本地运行，然后应用或完善。
fix_needs_review	修复验证失败或尚未尝试验证。分析并作出决定。
fix_failed	自愈失败。获取详细数据，尝试本地修复（先执行门控检查）。
no_fix	没有可用修复。获取详细数据，尝试本地修复（先执行门控检查）或退出。
environment_issue	通过 MCP 请求环境重跑（先执行门控检查）。
self_healing_throttled	拒绝旧修复，尝试本地修复。
no_new_cipe	CI 尝试从未启动。运行自动修复工作流，或退出并提供指导。
cipe_no_tasks	CI 失败，且没有任务。使用空提交重试一次。

关键规则（始终适用）：

• Git 安全性：按名称暂存特定文件 — git add -A 或 git add . 可能会提交用户无关的进行中工作或机密信息
• 环境故障（OOM、找不到命令、权限被拒绝）：立即停止。这些不是代码错误，把本地修复预算花在它们上面毫无意义
• 门控检查：尝试本地修复前运行 ci-state-update.mjs gate — 如果预算已用尽，打印消息并退出

主循环

第 1 步：初始化跟踪

cycle_count = 0            # Only incremented for agent-initiated cycles (counted against --max-cycles)
start_time = now()         # Passed to the decision script as --elapsed-seconds on every poll to enforce --timeout across attempts
no_progress_count = 0
local_verify_count = 0
env_rerun_count = 0
last_cipe_url = null
expected_commit_sha = null
agent_triggered = false    # Set true after monitor takes an action that triggers new CI Attempt
poll_count = 0
wait_mode = false
prev_status = null
prev_cipe_status = null
prev_sh_status = null
prev_verification_status = null
prev_failure_classification = null

第 2 步：轮询循环

重复执行，直到完成：

2a. 启动子 Agent（FETCH_STATUS）

根据模式确定要选择的字段：

• 等待模式：使用 WAIT_FIELDS（cipeUrl,commitSha,cipeStatus）
• 普通模式（首次轮询或检测到 newCipeDetected 后）：使用 LIGHT_FIELDS

Task(
  agent: "ci-monitor-subagent",
  model: haiku,
  prompt: "FETCH_STATUS for branch '<branch>'.
           select: '<fields>'"
)

子 Agent 调用 ci_information 并返回包含所请求字段的 JSON 对象。这是一次前台调用——等待结果。

2b. 运行决策脚本

node <skill_dir>/scripts/ci-poll-decide.mjs '<subagent_result_json>' <poll_count> <verbosity> \
  [--wait-mode] \
  [--prev-cipe-url <last_cipe_url>] \
  [--expected-sha <expected_commit_sha>] \
  [--prev-status <prev_status>] \
  [--timeout <timeout_minutes>] \
  [--new-cipe-timeout <new_cipe_timeout_minutes>] \
  [--elapsed-seconds <seconds_since_start_time>] \
  [--env-rerun-count <env_rerun_count>] \
  [--no-progress-count <no_progress_count>] \
  [--prev-cipe-status <prev_cipe_status>] \
  [--prev-sh-status <prev_sh_status>] \
  [--prev-verification-status <prev_verification_status>] \
  [--prev-failure-classification <prev_failure_classification>]

以分钟为单位传入 --timeout 和 --new-cipe-timeout（取自 Configuration Defaults 的值）——脚本会在内部将其转换为秒。传入 --elapsed-seconds，其值为自 start_time 起经过的整秒数（now() - start_time）；这是跨所有轮询和尝试强制执行 --timeout 总监控时限的方式，因此监控开始后，每次调用都必须提供该参数。

脚本输出单行 JSON：{ action, code, message, delay?, noProgressCount, envRerunCount, fields?, newCipeDetected?, verifiableTaskIds? }

2c. 处理脚本输出

解析 JSON 输出并更新跟踪状态：

• no_progress_count = output.noProgressCount
• env_rerun_count = output.envRerunCount
• prev_cipe_status = subagent_result.cipeStatus
• prev_sh_status = subagent_result.selfHealingStatus
• prev_verification_status = subagent_result.verificationStatus
• prev_failure_classification = subagent_result.failureClassification
• prev_status = output.action + ":" + (output.code || subagent_result.cipeStatus)
• poll_count++

根据 action 执行操作：

• action == "poll"：打印 output.message，休眠 output.delay 秒，然后转到 2a
  • 如果 output.newCipeDetected：清除等待模式，将 wait_mode = false 重置
• action == "wait"：打印 output.message，休眠 output.delay 秒，然后转到 2a
• action == "done"：使用 output.code 继续执行步骤 3

步骤 3：处理可执行状态

当决策脚本返回 action == "done" 时：

1. 处理代码之前先运行 cycle-check（步骤 4）
2. 检查返回的 code
3. 在上表中查找默认行为
4. 检查用户指令是否覆盖默认行为
5. 执行相应操作
6. 如果操作要求启动新的 CI 尝试，更新跟踪状态（见步骤 3a）
7. 如果操作会进入循环，转到步骤 2

为操作启动子 Agent

有几种状态需要获取详细数据或调用 MCP：

• fix_apply_ready：启动 UPDATE_FIX 子 Agent 并使用 APPLY
• fix_needs_local_verify：启动 FETCH_HEAVY 子 Agent 获取修复详情，然后进行本地验证
• fix_needs_review：启动 FETCH_HEAVY 子 Agent → 获取 suggestedFixDescription、suggestedFixSummary、taskFailureSummaries
• fix_failed / no_fix：启动 FETCH_HEAVY 子 Agent → 获取 taskFailureSummaries，用于本地修复参考
• environment_issue：启动 UPDATE_FIX 子 Agent 并使用 RERUN_ENVIRONMENT_STATE
• self_healing_throttled：启动 FETCH_HEAVY 子 Agent → 获取 selfHealingSkipMessage；然后针对每个旧修复运行 FETCH_THROTTLE_INFO + UPDATE_FIX

步骤 3a：跟踪状态以检测新的 CI 尝试

执行应触发新 CI 尝试的操作后，运行：

node <skill_dir>/scripts/ci-state-update.mjs post-action \
  --action <type> \
  --cipe-url <current_cipe_url> \
  --commit-sha <git_rev_parse_HEAD>

操作类型：fix-auto-applying、apply-mcp、apply-local-push、reject-fix-push、local-fix-push、env-rerun、auto-fix-push、empty-commit-push

脚本返回 { waitMode, pollCount, lastCipeUrl, expectedCommitSha, agentTriggered }。根据输出更新所有跟踪状态，然后转到步骤 2。

第 4 步：循环分类和进度跟踪

当决策脚本返回 action == "done" 时，在处理代码之前运行 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>

脚本返回 { cycleCount, agentTriggered, envRerunCount, approachingLimit, limitReached, message }。根据输出更新跟踪状态。

• 如果 limitReached → --max-cycles 预算已耗尽。打印 message 并停止监控（不要处理代码，也不要开始新一轮循环）。这是强制停止，不是建议。
• 否则，如果 approachingLimit → 询问用户是继续（再运行 5 或 10 轮循环）还是停止监控
• 如果上一轮循环并非由 Agent 触发（而是由人工推送），记录检测到了人工发起的推送

进度跟踪

• no_progress_count、熔断器（5 次轮询）和退避重置由 ci-poll-decide.mjs 处理（进度 = cipeStatus、selfHealingStatus、verificationStatus 或 failureClassification 中的任意变化）
• 非环境状态下重置 env_rerun_count 由 ci-state-update.mjs cycle-check 处理
• 检测到新的 CI Attempt（轮询脚本返回 newCipeDetected）时 → 将 local_verify_count = 0、env_rerun_count = 0

错误处理

错误	操作
Git rebase 冲突	报告给用户，退出
nx-cloud apply-locally 失败	通过 MCP 拒绝修复（action: "REJECT"），然后尝试手动补丁（拒绝 + 从头修复流程）或退出
MCP 工具错误	重试一次；如果仍然失败，则报告给用户
子 Agent 启动失败	重试一次；如果仍然失败，则报错退出
决策脚本错误	将状态视为 error，递增 no_progress_count
未检测到新的 CI Attempt	如果启用了 --auto-fix-workflow，则尝试更新 lockfile；否则向用户报告并提供指导
lockfile 自动修复失败	报告给用户，退出并指导其检查 CI 日志

用户指令示例

用户可以覆盖默认行为：

指令	效果
"never auto-apply"	应用任何修复前始终先询问
"always ask before git push"	每次推送前先询问
"reject any fix for e2e tasks"	如果 failedTaskIds 包含 e2e，则自动拒绝
"apply all fixes regardless of verification"	跳过验证检查，应用所有修复
"if confidence < 70, reject"	应用前检查 confidence 字段
"run 'nx affected -t typecheck' before applying"	添加本地验证步骤
"auto-fix workflow failures"	在 CI Attempt 前置失败时尝试更新 lockfile
"wait 45 min for new CI Attempt"	覆盖新 CI Attempt 超时时间（默认：10 分钟）