nx-cloud-ci-failure-review

Nx Cloud CI 失败审查

所有 Nx Cloud 读取操作都需要 nx-cloud-api 技能。此工作流为只读。

将失败的流水线归纳为少量诊断类别。流水线失败并不能证明是 Agent 或平台导致的失败。每个类别的归因程度不得超出证据所支持的范围。

范围与数据收集

当用户提供一个或多个 CIPE 或运行组链接时，使用聚焦调查模式。先获取这些确切记录，再跟进其返回的运行组、运行、任务和工作流链接。直接比较用户提供的执行记录。除非用户要求分析复发情况或范围，否则不要查询宽泛的时间窗口，也不要进行整个工作区范围的排名。将跟随指定关键错误发生的取消视为后果，而不是单独的根因类别。

当用户要求审查工作区失败情况时，使用审查模式。默认审查过去 24 小时内的失败。CIPE 和运行组列表筛选器使用的是 createdAt，而不是失败时间。查询 30 小时的创建时间窗口，以覆盖最长的常规 6 小时 CI 时长。说明预期的 24 小时审查时段和 30 小时创建时间窗口。

查询 statuses=FAILED、statuses=TIMED_OUT 和 statuses=CANCELED（cipes 筛选器仅接受终态）。说明分支、CI 上下文、状态、端点和记录数量。扩大时间窗口或混合不相关的仓库/工作区之前，先征求用户同意。

每次读取都使用 nx-cloud-api（npx nx-cloud api）。使用 --describe 检查 cipes、run-groups、run-groups/{runGroupId}、runs、runs/{runId}/tasks 以及相关 steps 和 instances 端点的实时架构。使用 --list-operations 确认路由；公共 API 没有单独的工作流路由。通过跟进返回的 links 获取子记录。聚焦调查模式从用户提供的 CIPE 开始。审查模式从失败的 CIPE 及其关联的运行组开始。只使用实时文档中列出的筛选器和字段。先获取一页范围较窄的结果，并检查 nextCursor 后再继续。

按以下顺序收集：

1. 获取失败、超时和取消的 CIPE，以及其状态、时间戳、分支和 CI 上下文。使用较小且明确说明的 --pages 值。只有在退出码为零且 nextCursor: null 时，才进行工作区范围的类别排名；否则应报告数据不完整。
2. 获取关联的运行组及其文档中列出的关键错误字段。
3. 获取每个选定组的运行和终态任务行。
4. 仅在任务数据无法解释该组时，才检查工作流和实例状态。
5. 获取具有代表性的案例中最少且相关的任务或实例日志摘录。

使用最多包含 5 个范围较窄的详细请求的信号量。只有在某个类别进入前 5 名后才获取日志。读取 CI 日志内容前告知用户。仅引用已脱敏的错误行。

在原因和时间信息证明取消应归入其他类别之前，将取消视为单独类别。缺少此类上下文时，不要将取消称为失败。

分组方法

根据稳定证据构建分组。优先使用任务标识符和规范化的错误特征。规范化时间戳、GUID、重试计数器、临时路径和随机端口。保留能够区分其他相似消息的堆栈上下文、命令和错误代码。

仅在存在相应证据时使用以下类别：

• 重复任务错误。
• 任务超时。
• 取消。
• 工作流或 Agent 故障。
• 未知流水线故障。

只有在工作流／实例状态、关键错误或 Agent 证据支持，且没有任务故障能解释流水线问题时，才将分组归类为工作流或 Agent 故障。不要仅凭缺少任务日志就推断为基础设施问题。

分类前，先综合判断整个流水线的情况。任务可能记录为 SUCCEEDED 或命中缓存，但主作业却在下载、验证或恢复制品时失败。请比较运行组的 criticalErrorMessage、任务状态、缓存状态、工作流状态以及后续取消情况。在这种情况下，将主作业的缓存恢复错误归为主要原因，取消的运行则视为后果。

对于每个分组，记录其 CIPE 数量、运行组数量、受影响的任务数量、首次和最后一次出现的时间、分支／上下文，以及一到两个代表性 ID。排序时，先按受影响的流水线数量，再按复发次数，最后按有记录的阻塞时长。

后续操作规则

• 重复任务错误：如果存在相关的工作区检出，请检查记录提交中的 CODEOWNERS 和项目所有权元数据。建议可能的审查负责人。缺少这些证据时，不要分配工作或声称某人拥有所有权。
• 任务超时：比较执行时长和资源证据。如果证据无法表明直接原因，请要求进行有针对性的复现或提供资源报告。
• 取消：指出有记录的取消来源；否则，将其单独归为原因未知的取消。
• 工作流或 Agent 故障：只有证据支持这是暂时性事件时，才重试或监控。否则，检查所提及的工作流／Agent 资产。
• 未知：请求最少量的日志或运行详情，以区分不同情况。

未经明确批准，不要更改代码、工作流或资源分配。

报告格式

# Failed CI review

## Scope

- Window: …
- Data: …

## Failure groups

### 1. <evidence-level category> — <short signature>

- **Confirmed facts:** affected CIPEs/runs/tasks; representative IDs; log excerpt.
- **Assessment:** **Confirmed** / **Likely** / **Needs diagnostic run** — …
- **Impact:** …
- **Highest-leverage next action:** …

## Unclassified or incomplete data

- …

审查报告最多包含五个分组。在定向调查模式下，如果提供的执行记录具有相同的规范化特征，则将其作为一组进行比较。每项发现都应链接到确切的 CIPE、运行组、运行记录和任务（如有）。如果分页、资产缺失或上下文不足影响结论，请说明数据限制。