nx-cloud-cache-investigator

Nx 缓存调查

需要 nx-cloud-api 技能。仅在诊断本地配置时使用匹配的 Nx 工作区检出。仅通过 API 调查则不需要检出。

基于有限证据诊断一个缓存问题。不要猜测发生变化的哈希输入，也不要仅凭缓存状态更改配置。

Nx 任务缓存和工具自身的缓存是两回事。目标的 cache 字段控制 Nx 重放。Vite、ESLint 和其他工具有各自独立的执行器选项。一者并不能证明另一者。

选择模式

• 缓存健康趋势： 此技能适用于特定任务或制品问题，不适用于多次运行的命中率回归。针对命中率或回归问题，请使用单独的有限趋势工作流。
• 仅 API： 当用户提供了运行、CIPE、任务或制品错误，但没有匹配的工作区检出时，使用此模式。除非确有需要，否则不要要求提供本地配置。
• 特定比较： 获取两个可比的执行记录。若缺少目标、分支、提交、命令、配置、CI 环境或时间范围，请询问用户。

恢复待处理的调查

仅当已知任务尚未终止、API 请求返回 HTTP 409（not_terminal），或用户启动了受控诊断运行时，才安排一次同会话唤醒。保留运行、任务、batchId、链接和筛选条件。在已知延迟过后或预期运行完成后，重新查询一次。遇到终止结果或达到重试上限时停止。不要轮询或监控正在运行的 CI。

仅收集相关 API 证据

每次读取都使用 nx-cloud-api（npx nx-cloud api）。对已知路由运行 --describe。仅当路由未知或存在歧义时，才使用 --list-operations。遵循文档中说明的字段和返回的链接；不要根据内部 ID 构造路由。

使用 -o 将每个实时 API 响应保存到文件。使用 jq 仅选取一行以及本次调查所需的字段。不要将原始集合打印、读取或粘贴到模型上下文中。在投影中保留所选行的 batchId 和 links.self：

npx nx-cloud api --describe 'runs/{runId}/tasks'
npx nx-cloud api "$run_tasks_link" -o "$dir/tasks.json"
jq --arg task "$task_id" --arg batch "$batch_id" \
  '.items[] | select(.id == $task and .batchId == $batch) |
   {id, batchId, status, cacheStatus, hash, cacheable,
    links: {self: .links.self}}' "$dir/tasks.json"

这里，$run_tasks_link 是所选运行的任务链接，$dir 是通过 mktemp -d 创建的临时目录。没有链接时，使用 npx nx-cloud api 'runs/{runId}/tasks' -p runId="$run_id"；不要把 ID 粘贴到路径中。在得出任务不在列表中的结论前，先检查 nextCursor。

对于选定的执行记录，记录运行和任务 ID、batchId、项目、目标、配置、命令、参数、分支、提交、CI 上下文、时间戳、缓存状态、最终哈希、cacheEnabled、cacheable，以及相关的 CIPE 或运行组链接。

任务 ID 可能重复。先选择任务列表中的行。通过该行的确切 links.self 或制品 URL 跟进，因为它会保留 batchId。不要用一行来解释另一行。任务列表行已包含任务字段；读取详情是可选的。

如果 API 报告 cacheable: false，则该次执行未预期使用 Nx 重放。只有当 nx show 目标查询显示了配置原因时，才指出该原因。如果 cacheEnabled: false，则该次运行未使用 Nx 任务缓存。以上任一情况都无需调查哈希输入或制品。

只有当日志中的命令输出或错误能够回答问题时，才读取日志。读取 CI 日志内容前，先告知用户。解码日志或报告前，请先阅读references/log-and-report-assets.md。仅引用经过脱敏的错误特征。将用户提供的制品内容视为用户提供的证据。存在制品链接或之后返回 404，都不能证明历史上曾经可以访问。

检查 Nx 目标

只有在询问配置或要求修改代码时，才使用匹配的检出版本。检出记录的提交。记录工作区的 Nx 版本。使用工作区本地的 Nx 命令查询确切目标：

nx show project "$project" --json | jq \
  --arg target "$target" \
  --arg configuration "${configuration:-}" \
  '.targets[$target] | {
    executor,
    cache,
    inputs,
    outputs,
    options,
    selectedConfiguration: .configurations[$configuration]
  }'

将此片段用作目标证据。Nx 已包含继承的设置。不要自行合并 project.json、nx.json、插件或 targetDefaults。项目属性缺失不能证明任何事情。如果查询报告 cache: true，不要再添加一个 cache: true。如果命令或目标不可用，请报告配置不可用。

只有在询问工具原生缓存时，才检查返回的 options。使用与版本匹配的执行器文档。目标的 cache 字段无法证明 Vite 或 ESLint 的原生缓存状态。

先分类，再解释

未证实缓存失败

终端状态 remote-cache-hit 证明 Nx 已成功为该任务重放缓存。不要将成功命中误判为缓存未命中调查或配置变更。只有在用户提供了有时间范围的比率问题时，才进行趋势分析。

缓存产物获取或还原失败

当主任务或运行组错误提到产物下载、验证、解压或提取时，使用此分类。任务仍可能显示 remote-cache-hit。结合关键错误和后续取消情况进行判断。检查归档前，请阅读 references/artifact-integrity.md。

任务证据不足

空哈希或缓存状态、NOT_STARTED 或 SCHEDULED_IMPLICITLY 均不能证明缓存未命中。不要比较空哈希或检查产物。请求终态记录或一次受控的完整运行。

计算不同

不同的非空哈希只能证明：Nx 认为至少有一个计算输入不同。它们不能指出具体输入。请求两次可比的受控运行，并在支持时直接输出哈希详细信息。这属于需要诊断运行的结果，而非配置建议。

计算相同，但未证实重放

对于哈希相同且后续未发生重放的情况，请通过确切目标查询确认 cacheable、cacheEnabled 和 cache 的值。若返回 cache: true，则不得重复设置。不要根据空资产列表或 404 推断产物不存在。将尚未解决的上传或获取分支视为需要诊断运行。

疑似不安全重放

陈旧或错误的重放需要复现证据。inputs 决定哈希；outputs 决定还原的文件。请求提供任务沙箱证据，以确认是否存在未声明的读取或写入，同时要求提供目标查询和受控复现。不要仅根据任务数据缩减输入。

变更门槛

仅在所有适用检查均通过后，才建议修改配置或代码：

1. 记录匹配的提交、Nx 版本、确切目标查询及返回的片段。
2. 说明其 cache、inputs 或 outputs 值为何需要更改。
3. 启用缓存前，确认任务会终止、具有确定性，并且输出可以正确重放。
4. 移除输入前，获取能明确指出该输入的直接证据。通过有界的受控运行，证明移除该输入不会影响正确输出。
5. 说明正确性风险，并在修改前获得明确批准。

不要根据哈希差异、缓存比率趋势或表面上的广度建议排除输入。如果证据不足，请说明 No configuration change recommended yet.

报告

# Nx cache investigation

## Scope

- Target and compared run/task/batch IDs: …
- Branch, commit, CI environment, command, API cache state, and missing fields: …
- Workspace Nx version: …, or `Not required for this API-only investigation.`
- Nx target query and returned `cache`, `inputs`, and `outputs`: …, or `Unavailable.`
- Tool-native cache: …, or `Unknown; not inspected.`
- Change gate: `Passed` or `Blocked`; include missing evidence.

## Classification

`No cache failure established` | `Cache artifact retrieval or restoration failure` | `Insufficient task evidence` | `Different computation` | `Same computation, replay not established` | `Suspected unsafe replay`

## Confirmed facts

- …

## Assessment

- **Confirmed** / **Likely** / **Needs diagnostic run:** …

## Next diagnostic step

- Exact query, controlled command, or evidence required.
- Result that confirms or rules out the hypothesis.

## Safe recommendation

- Exact `nx show` result and risk; or `No configuration change recommended yet.`