tsParticles 仓库中的 monitor-ci 技能深度解析：基于 Nx Cloud 自愈能力的 CI 流水线监控编排

tsParticles 仓库中的 monitor-ci 技能深度解析：基于 Nx Cloud 自愈能力的 CI 流水线监控编排

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles

本文以 tsParticles monorepo（当前版本 4.3.3）仓库内.cursor/skills/monitor-ci/SKILL.md为骨架，配合仓库中真实存在的确定性决策脚本（ci-poll-decide.mjs、ci-state-update.mjs）、子代理定义（ci-monitor-subagent.md）以及 Nx 配置（nx.json），完整讲解如何用 Agent 技能编排 Nx Cloud CI 监控、识别自愈修复状态并执行受预算约束的本地修复流程。读完本文，你将掌握 monitor-ci 的完整状态机、MCP 工具调用策略、轮询循环与循环分类逻辑，以及如何通过用户指令覆盖默认行为。

技能定位与使用场景

monitor-ci是仓库.cursor目录下定义的 Cursor/Claude Agent 技能，用于编排 Nx Cloud CI 流水线执行的监控，并处理自愈（self-healing）修复。它的核心价值在于：普通 CI 提供方 CLI（如gh pr checks --watch、glab ci status -w）只能读取原生流水线状态，而无法访问 Nx Cloud 的自愈修复链路。该技能通过与 Nx Cloud 的 MCP 工具（ci_information、update_self_healing_fix）交互，实现了「监控 → 决策 → 执行修复 → 追踪新 CI Attempt」的完整闭环。

从仓库现状看，nx.json 根配置中确实存在"nxCloudId": "62a6df5ddbaff92c46e3b366"，即该工作区已连接 Nx Cloud，这正是技能运行的前提条件；同时根 package.json 声明了大量 Nx 相关依赖（@nx/devkit、@nx/js等），并使用nx run-many -t build --parallel=50%、nx affected -t build等命令组织构建，说明这是一个典型的 Nx 驱动 monorepo，CI 状态完全依赖 Nx Cloud 数据源。

技能触发词包括：monitor ci、watch ci、ci monitor、watch ci for this branch、track ci、check ci status，以及任何希望追踪 CI 状态或需要自愈 CI 修复帮助的场景。

配置默认值与参数合并

技能定义了一系列可配置默认值，用户可通过$ARGUMENTS传入覆盖，合并后的参数驱动整个监控循环：

注意--max-cycles只统计agent 主动触发的循环：在 ci-state-update.mjs 的postAction()中可以看到，fix-auto-applying（自愈自动应用）被标记为agentTriggered = false，因为它是 Nx Cloud 自愈完成的，而非监控 Agent 触发；其余动作（apply-mcp、local-fix-push等）均计为 agent 触发。

前置校验：Nx Cloud 连接检查

监控循环开始前，必须先验证工作区已连接 Nx Cloud，否则没有任何 CI 数据可用，整个技能无法运行。校验步骤（SKILL.md 中的 Step 0）：

1. 检查工作区根目录的nx.json是否存在nxCloudId或nxCloudAccessToken；
2. 若nx.json缺失或两者都不存在 → 直接退出并提示Nx Cloud not connected.；
3. 若已连接 → 进入主循环。

结合本仓库 nx.json 第 4 行可以看到真实连接示例："nxCloudId": "62a6df5ddbaff92c46e3b366"。这是该技能在当前仓库能够运作的事实基础。

架构总览：四层协作

技能采用四层架构，职责边界清晰：

1. SKILL.md（编排者）：负责派生子代理、运行确定性脚本、打印状态，以及本地编码工作（如本地修复）；
2. ci-monitor-subagent.md（子代理，fast 模型）：每次调用只执行一个 MCP 工具（ci_information或update_self_healing_fix），返回结构化结果后立即退出，不循环、不轮询、不睡眠；
3. ci-poll-decide.mjs（确定性决策脚本）：接收ci_information结果与状态参数，返回action + 状态码 + 消息；
4. ci-state-update.mjs（确定性状态脚本）：管理预算闸门（gate）、动作后状态迁移、循环分类。

子代理的命令契约（见 ci-monitor-subagent.md）包括四种：FETCH_STATUS（按 select 字段拉取 CI 状态）、FETCH_HEAVY（拉取重字段并摘要）、UPDATE_FIX（对 shortLink 执行 APPLY/REJECT/RERUN_ENVIRONMENT_STATE）、FETCH_THROTTLE_INFO（节流信息，仅返回{ shortLink, cipeUrl }）。子代理被要求绝不转储完整 MCP 响应，只返回契约中指定的字段，以控制上下文消耗。

状态报告约定

决策脚本根据 verbosity 级别格式化消息：

• minimal：仅当状态与上次不同才输出；
• medium（默认）：Poll #N | <消息>；
• verbose：输出Poll #N | CI / Self-healing / Verification三元组加消息正文。

无论哪个级别，主 Agent 在向用户打印时都要为每条来自脚本message字段的消息加上[monitor-ci]前缀；自己主动产生的动作消息（如 "Applying fix via MCP..."）同样加上该前缀，保证日志可归因。

MCP 工具与字段集控制

技能定义了三套字段集来控制轮询效率，原则是「能用最轻的就不用重的」：

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。轮询模式决定 select 字段：等待模式用WAIT_FIELDS，普通模式（首次轮询或检测到新 CI Attempt 后）用LIGHT_FIELDS。

反模式清单

技能明确列出会导致「与自愈抢跑、丢失 CI 进度、浪费上下文」的行为，监控时必须规避：

如果技能无法激活，回退方案是：先用 CI 提供方 CLI 做一次性只读状态检查（单次调用，不带 watch/轮询标志），拿到上下文后立即交给本技能，绝不在主 Agent 上继续轮询。

主循环：从初始化到动作处理

主循环由 4 个步骤构成（Step 1～Step 4），是技能的核心执行逻辑。

Step 1：初始化跟踪状态

cycle_count = 0 # 仅统计 agent 主动触发的循环（计入 --max-cycles） start_time = now() no_progress_count = 0 local_verify_count = 0 env_rerun_count = 0 last_cipe_url = null expected_commit_sha = null agent_triggered = false # monitor 执行了会触发新 CI Attempt 的动作后置 true 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

会话上下文行为：如果用户在本会话中运行过/monitor-ci，可能存在先前状态（轮询计数、上次 CI Attempt URL 等），默认从中恢复，除非设置了--fresh才丢弃并从头开始。

Step 2：轮询循环

2a. 派生 FETCH_STATUS 子代理

根据模式选择 select 字段（wait 模式用WAIT_FIELDS，普通模式用LIGHT_FIELDS），对当前分支调用ci_information，等待结果返回后再继续。

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_seconds>] \ [--new-cipe-timeout <new_cipe_timeout_seconds>] \ [--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>]

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

2c. 处理脚本输出

解析 JSON 并更新跟踪状态：no_progress_count、env_rerun_count、prev_cipe_status、prev_sh_status、prev_verification_status、prev_failure_classification、prev_status = output.action + ":" + (output.code || subagent_result.cipeStatus)，并poll_count++。

根据action分流：

• poll：打印output.message，休眠output.delay秒，回到 2a；若output.newCipeDetected为真，清除 wait 模式（wait_mode = false）；
• wait：打印消息、休眠、回到 2a；
• done：携带output.code进入 Step 3。

从 ci-poll-decide.mjs 源码可以看到决策引擎的具体实现：classify()是纯函数决策树，自上而下按优先级判断（wait 模式优先于普通模式），并依据以下规则：

• noProgressCount的增量/重置：wait 模式下新 CI 重置、否则保持；普通模式下状态有变化（cipeStatus、selfHealingStatus、verificationStatus、failureClassification任一改变）或检测到新 CI 则重置为 0，否则 +1；
• 熔断器（circuit breaker）：连续 5 次无进展即done；
• 退避延迟backoff(count)为[60, 90, 120]秒三档封顶；
• wait 模式下每条轮询按 30 秒估算，poll_count * 30 >= new_cipe_timeout判定等待超时；
• 任务分类categorizeTasks()：按taskId冒号分隔的第二段是否包含e2e区分 e2e 任务，据此产出all_verified/e2e_only/needs_local_verify三种类别；
• 消息模板按 verbosity 处理：minimal 只在状态变化时输出，verbose 增加轮询序号与三元组详情。

Step 3：处理可动作状态

决策脚本返回action == "done"时，按顺序：先做循环检查（Step 4）→ 查看返回的code→ 查默认行为表 → 检查用户指令是否覆盖默认行为 → 执行动作 → 若动作预期产生新 CI Attempt，则更新跟踪（Step 3a）→ 若动作导致循环则回到 Step 2。

各状态对应的工具调用：

• fix_apply_ready：调用update_self_healing_fix，动作APPLY；
• fix_needs_local_verify：先用HEAVY_FIELDS拉取修复详情，再做本地验证；
• fix_needs_review：用HEAVY_FIELDS拉取suggestedFixDescription、suggestedFixSummary、taskFailureSummaries进行分析；
• fix_failed/no_fix：用HEAVY_FIELDS拉取taskFailureSummaries作为本地修复上下文；
• environment_issue：调用update_self_healing_fix，动作RERUN_ENVIRONMENT_STATE；
• self_healing_throttled：用HEAVY_FIELDS拉取selfHealingSkipMessage，然后对每个旧修复调用update_self_healing_fix。

Step 3a：为新 CI Attempt 检测跟踪状态

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

动作类型有 8 种：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 }，用输出更新所有跟踪状态后回到 Step 2。

从 ci-state-update.mjs 源码看，postAction()把动作分为两组：MCP 触发或自愈自动应用类（fix-auto-applying、apply-mcp、env-rerun）按cipeUrl跟踪；本地推送类（apply-local-push、reject-fix-push、local-fix-push、auto-fix-push、empty-commit-push）按commitSha跟踪。wait 模式被置为 true，pollCount归零——等待模式的轮询只关心「是否出现新 CI Attempt」。

Step 4：循环分类与进度跟踪

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, message }。规则：

• 若上一循环为 agent 触发，cycleCount++（源码中wasAgentTriggered为 true 时才计数）；
• 非environment_issue状态时重置envRerunCount；
• approachingLimit = cycleCount >= maxCycles - 2，即接近上限时询问用户是继续（+5 或 +10 循环）还是停止；
• 若上一循环非 agent 触发（人工推送），记录检测到人工触发的推送。

进度跟踪分工：no_progress_count、熔断器（5 次轮询）与退避重置由 ci-poll-decide.mjs 负责（进展 = 四个状态字段任一变化）；env_rerun_count在非环境状态下的重置由 ci-state-update.mjs 的cycle-check负责；检测到新 CI Attempt 时重置local_verify_count = 0、env_rerun_count = 0。

状态与默认行为表

决策脚本可返回以下状态码，表格定义默认行为，用户指令可覆盖任意项。

简单退出类——仅报告并退出：

需要动作类——Step 3 处理时需阅读 fix-flows.md 的详细流程：

从 ci-poll-decide.mjs 的classify()可以看到这些状态码的判定顺序（自上而下优先级递减）：wait 模式（新 CI 检测 → 等待超时 → 继续等待）→ 轮询超时 → 熔断器 →SUCCEEDED/CANCELED/TIMED_OUT终态 →cipe_no_tasks（FAILED 且无 failedTaskIds 且无自愈状态）→environment_state分类（重跑次数 ≥2 则封顶退出）→THROTTLED跳过原因 → CI 进行中 → 自愈进行中 → flaky 自动重跑 → 修复自动应用 → 自动应用路径（跳过/验证中/已验证）→ 自愈完成后的任务分类 → 自愈失败 → 无修复 → 兜底轮询。其中「真实进展」状态（ci_success、fix_auto_applying、fix_auto_apply_skipped、fix_needs_review、fix_apply_ready、fix_needs_local_verify）会触发noProgressCount归零。

始终适用的关键规则：

• Git 安全：只按文件名暂存特定文件——git add -A或git add .有把用户无关的进行中工作或密钥提交进去的风险；
• 环境类失败立即退出：OOM、命令未找到、权限拒绝等不是代码缺陷，在这些问题上消耗本地修复预算纯属浪费；
• 闸门检查：任何本地修复尝试前运行ci-state-update.mjs gate，预算耗尽则打印消息并退出。

修复动作流程（fix-flows）

fix-flows.md 详述了各状态的具体处置与三种修复动作流程。

Apply via MCP（MCP 应用）：派生 UPDATE_FIX 子代理执行APPLY。新 CI Attempt 会自动生成，无需本地 git 操作。

Apply Locally + Enhance Flow（本地应用 + 增强）：

1. nx-cloud apply-locally <shortLink>（状态置为APPLIED_LOCALLY）；
2. 增强代码以修复失败任务；
3. 本地运行失败任务验证；
4. 仍失败则运行ci-state-update.mjs gate --gate-type local-fix；不允许则提交当前状态并推送（让 CI 做最终裁判），允许则回到增强循环；
5. 通过则提交并推送，进入等待模式。

Reject + Fix From Scratch Flow（拒绝 + 从零修复）：

1. gate --gate-type local-fix检查，不允许则打印消息退出；
2. 派生 UPDATE_FIX 子代理执行REJECT；
3. 本地从零修复；
4. 提交并推送，进入等待模式。

环境 vs 代码失败识别：任何本地修复路径运行任务失败时，先判断是代码问题还是环境/工具链问题再决定是否走闸门。环境/工具链失败指标（非穷举）：命令未找到/二进制缺失、OOM/堆分配失败、权限拒绝、网络超时/DNS 失败、系统库缺失、Docker/容器问题、磁盘空间耗尽。检测到环境类失败应立即退出且不消耗预算；代码类失败（编译错误、测试断言失败、lint 违规、类型错误）才是本地修复的正当候选。

提交消息格式：

git commit -m "fix(<projects>): <brief description> Failed tasks: <taskId1>, <taskId2> Local verification: passed|enhanced|failed-pushing-to-ci"

闸门（Gate）机制与预算控制

ci-state-update.mjs 提供三个子命令，其中gate是预算控制的闸门：

• gate --gate-type local-fix：读取--local-verify-count与--local-verify-attempts（默认 3），超限返回{ allowed: false, message: "Local fix budget exhausted" }，否则allowed: true并递增计数；
• gate --gate-type env-rerun：环境重跑上限硬编码为 2 次，超限返回{ allowed: false, message: "Environment issue persists after N reruns. Manual investigation needed." }。

cycle-check中还能看到approachingLimit的判定（maxCycles - 2）与envRerunCount的非环境状态重置逻辑。这些脚本均为纯 Node 脚本（#!/usr/bin/env node），输入输出为 JSON 单行，便于主 Agent 确定性解析，这正是「决策由确定性脚本完成、判断由 Agent 完成」这一架构原则的体现。

错误处理矩阵

用用户指令覆盖默认行为

用户可以在触发时提供自然语言指令覆盖任何默认行为，常用示例：

在本仓库中的落地要点

tsParticles 是一个使用 pnpm 工作区 + Nx 组织的巨型 monorepo（根 package.json 中有"packageManager"相关脚本如pnpm run prettify:readme && nx run-many -t build --parallel=50%）。对应当前仓库，nx.json 已配置nxCloudId，因此monitor-ci技能可直接运行。实际使用时注意两点与仓库环境的衔接：

• 包管理器检测：fix_needs_local_verify流程要求先探测包管理器——pnpm-lock.yaml存在则用pnpm nx，yarn.lock存在则用yarn nx，否则npx nx；本仓库使用 pnpm 工作区，对应pnpm nx前缀；
• Git 安全：仓库中包含大量子包与生成文件，任何本地修复提交都必须按文件名精确暂存，避免误提交无关变更。

对于希望将此类「CI 监控 + 自愈修复编排」模式复用到自己 Nx 项目的团队，可参考本仓库.cursor目录下的完整实现：技能本体（SKILL.md）、修复流程细化（fix-flows.md）、决策脚本（ci-poll-decide.mjs）、状态脚本（ci-state-update.mjs）与子代理定义（ci-monitor-subagent.md），它们共同构成了一个职责分明、可确定性测试的 CI 编排方案。

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles