nx-cloud-api

Nx Cloud API

使用只读的 Nx Cloud Public API 命令 npx nx-cloud api，回答明确的工作区数据问题。这是一项 API 访问技能，不是报告生成器或配置编辑器。每条命令都要从工作区根目录运行，以便命令找到 nx.json。

运行一次 npx nx-cloud api --help（或单独运行 npx nx-cloud api）以查看语法和选项。本技能涵盖相关工作流。

所有输出均为 JSON。stdout 仅包含响应数据。stderr 每行包含一个 JSON 对象：{"error": ...}、{"output": ...}，以及在使用 -i 或 NX_VERBOSE_LOGGING 时的 {"response": ...} 和 {"log": ...}。唯一的例外是资源下载，其原始字节会写入 -o 指定的文件。

不可妥协的规则

• 从实时规范中发现端点。使用 npx nx-cloud api --list-operations 查找路由，并使用 npx nx-cloud api --describe <operationId | path | link> 查看其参数、响应字段和错误状态。两者都会显示某个操作的 returns 类型：list（下方所述的封装列表）、object（响应正文）或 file（资源下载）。不要使用记忆中的路由、字段、筛选器名称或枚举值。
• 从 cipes 开始，并沿着返回的 links 值继续。不要手动构造子级 URL，也不要将内部工作流 ID 用作路由参数。必须通过 ID 指定实体时，使用 --describe 中的 {placeholder} 路径，并用 -p name=value 填入。绝不要将 ID 直接粘贴到路径中：ID 是原始值，可能包含 / 或 :（例如 @scope/app:build 这样的任务 ID）。
• 从一个带筛选条件的页面开始。如果缺少工作区、范围或时间范围，请先询问。默认不要收集历史数据。
• 阅读 --describe 中的操作说明。说明中列出了命令本身不会强制执行的服务器限制。
• 不要使用本技能轮询或监控实时 CI。

缓存边界

API 返回记录的任务和运行字段。它不会查询本地 Nx 目标。cacheEnabled 描述记录中的运行。cacheable 描述记录中的任务。这两个值都不能用于判断 targetDefaults、推断出的目标，或 Vite、ESLint 等工具自身的缓存。

不要因项目属性缺失就推断 cache: false。如需排查缓存原因、目标设置、输入、输出或配置更改，请使用 nx-cloud-cache-investigator。仅凭 API 数据不足以证明缓存或输入相关的拉取请求是合理的。

快速工作流

npx nx-cloud api --describe cipes

# Save one bounded page to a scratch file, then project only what you need.
dir="$(mktemp -d)"
npx nx-cloud api cipes \
  -f createdAfter=2026-08-01T00:00:00Z \
  -f statuses=FAILED -f statuses=CANCELED \
  -o "$dir/cipes.json"
echo "exit $?"
jq '{pageLimitReached, nextCursor, items: [.items[] | {id, status, createdAt, links}]}' "$dir/cipes.json"

# Follow a link from a previous response as-is.
npx nx-cloud api "<link from a previous response>" -o "$dir/next.json"

# Address an entity by ID only through a path parameter.
npx nx-cloud api 'runs/{runId}/tasks' -p runId="$run_id" -o "$dir/tasks.json"

按原样传入 links.* 值；它可能已经带有查询参数，-f 可添加更多参数。仅接受配置的 Nx Cloud 主机上的完整 URL。这包括 https://cloud.nx.app/cipes/<id> 这样的应用链接，它们会像裸路径 cipes/<id> 一样解析。

精简 API 输出

为保留上下文，请使用 -o 将每个实时数据响应写入工作区之外的临时目录中的文件（文件权限仅限所有者）。为文件指定扩展名。未指定扩展名时，文件会使用 .json、.ndjson 或下载资源自带的扩展名（例如 .tar.gz），命令会在 stderr 中以 {"output": {"file": "..."}} 的形式报告最终路径。使用 mktemp -d 创建临时目录，并读取针对具体问题的 jq 投影结果。除非用户提出要求，否则不要让原始集合直接打印到对话中。根据 --describe 选择投影字段。对于单行数据，先选中该行，再仅投影所需字段。任务完成后删除保存的数据，除非用户要求保留。

--describe 的输出通常较小。只有在大型操作中需要部分内容时，才通过 jq 处理。

退出代码和错误

始终检查退出代码。每次失败都会在 stderr 中输出一条记录，命令不会提供恢复提示；不要使用 2>/dev/null 隐藏 stderr：

{"error":{"type":"http","message":"HTTP 409 Conflict","status":409,"url":"...","body":{"code":"not_terminal","message":"..."}}}

type 为 usage、http、network、response（命令无法使用的答案）或 output（无法写入的 -o 文件）。对于 http，body 是服务端的错误正文；如果正文是 JSON，则会对其进行解析；如果正文为空，则不包含该字段。退出码 4 和 5 对应的正文包含稳定的 code（401 和正文为空的 429 除外）；请根据 .error.body.code 分支处理，而不要依据说明性 message。

退出码	HTTP	code	后续操作
1	—	—	用法、网络、响应或输出错误；读取 stderr 上的 .error.type 和 .error.message。修正标志、路径或 -p 值，或检查主机（NX_CLOUD_API 或 nxCloudUrl）、代理和 VPN。
4	400	invalid_parameter	运行 npx nx-cloud api --describe <same path>，并修正其中指出的参数。未知查询参数一律会被拒绝。
4	400	invalid_limit、invalid_timestamp、invalid_date_range、invalid_filter	根据 message 中指出的内容修正值或筛选条件组合；使用 --describe 查看格式和限制。
4	400	invalid_cursor	游标仅对生成它的列表有效。使用相同路径和筛选条件继续，或移除 cursor 后重新开始。
4	401	none（body 是纯文本）	在工作区根目录运行 npx nx-cloud login --status。该命令需要通过 npx nx-cloud login 获取个人访问令牌，并在 nx.json 中设置 nxCloudId；或者使用 NX_CLOUD_ACCESS_TOKEN 中的工作区令牌。已存储的个人访问令牌优先级更高，因此即使设置了有效的工作区令牌，过期的个人访问令牌仍会导致失败。仅当状态检查报告没有可用登录信息时，才运行 npx nx-cloud login。
4	403	plan_not_allowed	组织的套餐不包含 Nx Cloud Public API。告知用户；不要重试或使用他人的令牌。
4	404	not_found	路径中的 ID 或父 ID 筛选条件（cipeId、runGroup、stepId、agentName）中的 ID 有误。未知父项不会返回空结果。重新检查 ID，或改为跟随链接。
4	404	none（没有 body）	路径未匹配到任何路由，通常是因为将包含 / 的原始 ID（例如 @scope/app:build）粘贴到了路径中。使用带 -p 的 {placeholder} 路径，或跟随 links，并使用 --describe 检查路径。
4	409	not_terminal	实体仍在运行。这并非失败；其数据尚未最终确定。请参见下文的同一会话重试说明。
4	429	rate_limit_exceeded 或没有 body	组织范围的配额已用尽。该命令已遵从 Retry-After 重试 3 次。等待一段时间，缩小筛选范围，并减少请求次数。
5	503	data_api_at_capacity、query_deadline_exceeded、audit_log_unavailable、rate_limit_unavailable	未返回数据。该命令已重试 3 次。再尝试一次前请等待一段时间；对于 query_deadline_exceeded，请缩短时间范围或缩小筛选范围。
5	5xx	其他	短暂等待后重试一次。向支持团队求助时，请保留响应正文中的端点、筛选条件、时间范围和 traceId。
--list-operations、--describe 和 --print-api-spec 无需凭据，因此即使数据请求因 401 失败，它们仍可成功。

除非用户明确要求，否则不要更改工作区配置或凭据。

同一会话重试

对于已知请求的 409 not_terminal，安排实体预计完成后在同一会话中最多唤醒一次。保留链接和筛选条件。收到终态响应后停止。

分页

每个列表响应都经过封装，即使只有一页也是如此： {source, pagesFetched, fetchedItemCount, pageLimitReached, nextCursor, items}。 source 会记录来源、端点和原始查询。使用 jq '.items[]' 读取行。非列表响应会按原样返回。

只有退出代码为 0 且 nextCursor 为 null 时，列表才算完整。 pageLimitReached: true 表示 --pages 在仍有更多结果时停止了运行。若要继续，请使用相同路径和筛选条件，通过 --cursor <nextCursor> 重新运行；或者说明数据不完整。输出中的 source.query 会记录启动时使用的游标。

默认情况下，命令只获取一页。谨慎提高 --pages，并保持较小的值；优先使用范围更窄的筛选条件，而不是增加页数。没有范围较窄的筛选条件时，不要获取许多 flaky-tasks 或 task-stats 页面。除非确有需要，否则保持页面大小不变：每页都会消耗组织速率限制的一个单位，而 --page-size（设置 limit，最大值为 500）只有在调高时才有帮助。

如果后续页面获取失败，命令仍会输出已获取的内容，并将 nextCursor 设为失败页面的游标，且以 4 或 5 退出。处理错误后，从该游标继续。

--format ndjson 只输出行，每行一条，不包含元数据。输出中没有任何信息表明是否还有更多页面，也不会记录恢复游标。它会在检索到每一页时立即输出；这在需要及时响应或响应非常大时可能很重要。 仅在无需保证完整性时使用它；否则使用默认的 JSON 输出。

对于多范围提取、任务或日志资源，或计算任务，请先阅读 references/extraction-and-calculation.md。

解读响应

集合响应的顶层包含 items 和 nextCursor。单个资源会按原样返回。不要仅凭字段名称推断其含义；先检查 --describe 和实时记录。

根据证据来源标注有关缓存的陈述：

• **API 响应字段：**记录的 cacheEnabled、cacheable、缓存状态或哈希值。
• **Nx 目标查询：**来自匹配检出版本中 nx show project ... --json 的值。
• **工具原生缓存：**检查执行器选项之前一律标为 Unknown。

空任务资源

有效的任务资源可以有零字节的终端输出，且没有输出文件；nx:noop 通常如此。报告日志捕获或归档缺陷之前，请先检查匹配的工作区任务。

报告

说明查询的操作、筛选条件、条目数以及数据是否完整。说明结果属于记录的 API 数据、本地目标查询还是假设。绝不要声称仅通过读取 API 就证明了配置来源或工具原生缓存状态。