dx-devops-request-status

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DevOps Center Request Status

DevOps Center 请求状态

Polls the status of an asynchronous DevOps Center request — a promotion or deploy operation — by its request token via

sf devops request status

. Provides headless,

--json

-driven, read-only status checks for autonomous release workflows in CI. This skill never mutates pipeline state; it only reports the current status of an in-flight or completed request.

通过

sf devops request status

命令，根据请求令牌轮询异步DevOps Center请求的状态——包括晋升（promotion）或部署（deploy）操作。为CI中的自动化发布工作流提供无界面、基于

--json

格式的只读状态检查。此技能绝不会修改流水线状态，仅报告正在进行或已完成请求的当前状态。

Scope

适用范围

In scope: Check the status of a single async request by its request token; interpret the two-level outcome (request-processing
```
.result.status
```
vs. the
```
.result.errorDetails
```
failure oracle); poll with backoff until a request finishes or a caller-supplied timeout is reached; surface parsed error details on failure
Out of scope: Initiating a promotion or deploy (use
```
dx-devops-promote
```
), work item creation/status updates (use
```
dx-devops-work-item-manage
```
), conflict detection, running
```
sf devops promotion complete
```
(that is the caller's next step after this skill confirms success), pipeline or project setup

适用场景：根据请求令牌检查单个异步请求的状态；解析两层结果（请求处理状态
```
.result.status
```
与失败判定依据
```
.result.errorDetails
```
）；带退避策略轮询直到请求完成或达到调用者指定的超时时间；在请求失败时展示解析后的错误详情
不适用场景：发起晋升或部署操作（请使用
```
dx-devops-promote
```
）、创建工作项/更新工作项状态（请使用
```
dx-devops-work-item-manage
```
）、冲突检测、执行
```
sf devops promotion complete
```
（此操作是调用者在本技能确认成功后的下一步）、流水线或项目配置

Required Inputs

必填输入

Gather or infer before proceeding:

Request token (required): the request token returned in the
```
dx-devops-promote
```
promote response. Passed via
```
-i/--request-token
```
. Without it, this skill cannot proceed — ask for it or obtain it from the prior promote step's output
Target org:
```
-o/--target-org <alias>
```
(required unless the
```
target-org
```
config variable is set)

Defaults unless specified:

Output format:
```
--json
```
for headless consumption
Polling interval: 10 seconds between checks; cap total wait at a caller-supplied timeout (default 30 minutes). Never poll faster than every 5 seconds — DOCe API rate limits apply

If the user gives a clear request ("check request a0B…", "poll request a0B… until it finishes"), proceed once you have the request token.

执行前需收集或推断以下信息：

请求令牌（必填）：
```
dx-devops-promote
```
晋升响应中返回的请求令牌，通过
```
-i/--request-token
```
参数传入。若无此令牌，本技能无法执行——请向用户索要或从之前的晋升步骤输出中获取
目标组织：
```
-o/--target-org <别名>
```
（若已设置
```
target-org
```
配置变量则可选）

默认配置（除非另行指定）：

输出格式：
```
--json
```
，用于无界面场景消费
轮询间隔：每次检查间隔10秒；总等待时长上限为调用者指定的超时时间（默认30分钟）。轮询间隔不得短于5秒——需遵守DOCe API的速率限制

若用户明确提出请求（如"检查请求a0B…的状态"、"轮询请求a0B…直到完成"），获取请求令牌后即可执行。

Workflow

工作流程

All operations use

sf devops request status

with

--json

output. This skill is read-only — it issues no mutations. The command's flags and JSON output schema are documented in

references/cli-commands.md

所有操作均使用带

--json

输出的

sf devops request status

命令。本技能为只读——不会执行任何修改操作。该命令的参数与JSON输出架构记录在

references/cli-commands.md

中。

Phase 1 — Authenticate and confirm the request token

阶段1 — 身份验证并确认请求令牌

Verify org authentication before any operation:
bash
```
sf org display --json
```
- If it fails, instruct the user to run
```
sf org login web --set-default --alias <alias>
```
- Pass
```
-o/--target-org <alias>
```
  on every subsequent command (required unless the
```
target-org
```
  config variable is set)
Confirm you have a request token. If the user initiated a promotion in the same session, reuse the request token captured from the
```
dx-devops-promote
```
promote response. If no token is available, STOP and ask for it — do NOT guess or fabricate a token.

在执行任何操作前验证组织身份：
bash
```
sf org display --json
```
- 若验证失败，指导用户执行
```
sf org login web --set-default --alias <别名>
```
- 在后续所有命令中传入
```
-o/--target-org <别名>
```
  （若已设置
```
target-org
```
  配置变量则可选）
确认已获取请求令牌。若用户在同一会话中发起过晋升操作，复用从
```
dx-devops-promote
```
晋升响应中捕获的请求令牌。若无可用令牌，立即停止并向用户索要——请勿猜测或伪造令牌。

Phase 2 — Single status check (two-level semantics)

阶段2 — 单次状态检查（两层语义）

CRITICAL:
.result.status
(uppercase, e.g.
SUCCESS
) reports whether the async request finished processing — NOT whether the underlying deploy succeeded. A request can show
status: "SUCCESS"
while the deployment itself failed. The real outcome oracle is
.result.errorDetails
: non-null
errorDetails
means the operation failed, even when
status == SUCCESS
.

Run a single status check with
```
scripts/poll-status.sh --once
```
, which queries the request once and derives the true outcome deterministically (glob-matches the operation-prefixed
```
.result.status
```
suffix, then applies the
```
.result.errorDetails
```
failure oracle). Do NOT hand-roll the JSON parsing in prose — the script owns the two-level rule so it stays consistent with the polling path:
bash
```
scripts/poll-status.sh --once <request-token> <target-org-alias>
```
Interpret the exit code (the script prints a human-readable line to match):
- ```
0
```
  — request finished and the operation succeeded (
```
errorDetails
```
  null) → hand back to the caller
- ```
2
```
  — request finished but the operation FAILED (status suffix
```
*FAILED*
```
  /
```
*ERROR*
```
  /
```
*CANCELED*
```
  , or a
```
*SUCCESS*
```
  status with non-null
```
errorDetails
```
  ) → the printed line carries the parsed
```
errorType
```
  /
```
errorMessage
```
- ```
4
```
  — request is still processing (non-terminal suffix) → proceed to Phase 3 to poll, or report in-progress for a one-shot check
- ```
1
```
  — query/usage error (bad token, auth, or missing dependency)

关键提示：
.result.status
（大写格式，如
SUCCESS
）仅表示异步请求已处理完成——并不代表底层部署操作成功。即使请求状态显示
status: "SUCCESS"
，部署操作仍可能失败。真实结果的判定依据是
.result.errorDetails
：只要
errorDetails
不为空，即表示操作失败，哪怕
status == SUCCESS
。

执行单次状态检查，使用
```
scripts/poll-status.sh --once
```
脚本，该脚本会查询一次请求并确定性推导真实结果（通配匹配操作前缀的
```
.result.status
```
后缀，再应用
```
.result.errorDetails
```
失败判定规则）。请勿手动解析JSON——脚本负责维护两层规则，确保与轮询流程保持一致：
bash
```
scripts/poll-status.sh --once <请求令牌> <目标组织别名>
```
根据退出码解读结果（脚本会打印对应的可读信息）：
- ```
0
```
  — 请求已完成且操作成功（
```
errorDetails
```
  为空） → 将结果返回给调用者
- ```
2
```
  — 请求已完成但操作失败（状态后缀为
```
*FAILED*
```
  /
```
*ERROR*
```
  /
```
*CANCELED*
```
  ，或状态为
```
*SUCCESS*
```
  但
```
errorDetails
```
  不为空） → 打印的信息包含解析后的
```
errorType
```
  /
```
errorMessage
```
- ```
4
```
  — 请求仍在处理中（非终端后缀） → 进入阶段3进行轮询，或在单次检查中报告请求正在进行
- ```
1
```
  — 查询/使用错误（无效令牌、身份验证失败或缺少依赖）

Phase 3 — Poll until terminal (only when asked to wait)

阶段3 — 轮询直到进入终端状态（仅当用户要求等待时执行）

Poll with a bounded loop when the user asks to wait for completion. Run
```
scripts/poll-status.sh
```
and report the final status it prints:
bash
```
scripts/poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]
```
- The script polls every
```
interval-seconds
```
  (default 10), never sleeps past
```
timeout-seconds
```
  , stops on a terminal request state, and applies the same two-level outcome check as
```
--once
```
  . Exit codes:
```
0
```
  = finished + succeeded (
```
errorDetails
```
  null),
```
2
```
  = finished but the operation failed (
```
errorDetails
```
  set, or status suffix
```
*FAILED*
```
  /
```
*ERROR*
```
  /
```
*CANCELED*
```
  ),
```
3
```
  = timeout,
```
1
```
  = query/usage error
- It is a read-only loop — it issues only
```
sf devops request status
```
  queries, never mutations
- Do NOT hand-roll a polling loop in prose; the script enforces the interval floor, exact timeout, terminal-state detection, and the
```
errorDetails
```
  outcome check deterministically

当用户要求等待请求完成时，执行带边界的轮询循环。运行
```
scripts/poll-status.sh
```
脚本并报告其打印的最终状态：
bash
```
scripts/poll-status.sh <请求令牌> <目标组织别名> [轮询间隔秒数] [超时秒数]
```
- 脚本每隔
```
interval-seconds
```
  （默认10秒）轮询一次，不会等待超过
```
timeout-seconds
```
  ，在请求进入终端状态时停止，并应用与
```
--once
```
  相同的两层结果检查规则。退出码：
```
0
```
  = 请求完成且成功（
```
errorDetails
```
  为空），
```
2
```
  = 请求完成但操作失败（
```
errorDetails
```
  不为空，或状态后缀为
```
*FAILED*
```
  /
```
*ERROR*
```
  /
```
*CANCELED*
```
  ），
```
3
```
  = 超时，
```
1
```
  = 查询/使用错误
- 此为只读循环——仅执行
```
sf devops request status
```
  查询，不会执行任何修改操作
- 请勿手动编写轮询循环；脚本会严格执行最小间隔、精确超时、终端状态检测以及
```
errorDetails
```
  结果判定规则

Phase 4 — Report

阶段4 — 结果报告

Report the outcome:
- On success (finished,
```
errorDetails
```
  empty): "Request
```
<token>
```
  completed successfully." — then remind the caller that promotion finalization (
```
sf devops promotion complete
```
  ) is the next step, owned by
```
dx-devops-promote
```
- On failure (finished,
```
errorDetails
```
  set — even if
```
status == SUCCESS
```
  ): "Request
```
<token>
```
  failed." plus the
```
errorType
```
  /
```
errorMessage
```
  parsed from
```
errorDetails
```
  and the
```
message
```
  field — do NOT retry or remediate here; that is the caller's decision
- On timeout (still processing): report the last observed request status and the elapsed wait; suggest polling again later — do NOT report success or failure for a request that has not finished processing

报告结果：
- 成功（请求完成，
```
errorDetails
```
  为空）："请求
```
<令牌>
```
  已成功完成。" — 随后提醒调用者，晋升操作的最终确认（
```
sf devops promotion complete
```
  ）是下一步，由
```
dx-devops-promote
```
  负责
- 失败（请求完成，
```
errorDetails
```
  不为空——即使
```
status == SUCCESS
```
  ）："请求
```
<令牌>
```
  失败。" 并附上从
```
errorDetails
```
  和
```
message
```
  字段解析出的
```
errorType
```
  /
```
errorMessage
```
  — 请勿在此处重试或修复，该决策由调用者做出
- 超时（请求仍在处理）：报告最后观测到的请求状态及已等待时长；建议稍后再次轮询——请勿对未完成的请求报告成功或失败

Rules / Constraints

规则与约束

Constraint	Rationale
Read-only — never mutate pipeline state	This skill only reports status; promotion/deploy/complete are owned by other skills
A request token is mandatory	Status cannot be checked without the `-i/--request-token` from the promote response; never fabricate one
`sf devops request status` must use `--json`	Structured output is required for headless consumption; human-readable output is unreliable to parse
Read `.result.status` and `.result.errorDetails` via `jq` , never by eyeballing	Deterministic parsing prevents misreading a still-processing request as done
A `SUCCESS` status is NOT proof of success — check `errorDetails`	`.result.status` reports the async request finished, not that the deploy succeeded; a `PROMOTE_SUCCESS` request can carry a failed deploy in `errorDetails`
Non-null `.result.errorDetails` means the operation FAILED	`errorDetails` is the outcome oracle; it is an escaped JSON string ( `errorType` / `errorMessage` ) that must be parsed with `jq` / `fromjson`
`.result.status` is operation-prefixed — match the suffix, not a bare token	Real values are `PROMOTE_IN_PROGRESS` / `PROMOTE_SUCCESS` / `DEPLOY_FAILED` ; exact-matching bare `IN_PROGRESS` / `SUCCESS` would misclassify (and a poller would hang until timeout)
A request is only "done" at a terminal suffix ( `SUCCESS` / `FAILED` / `ERROR` / `CANCELED` )	Reporting an `_IN_PROGRESS` / `_PENDING` / `*_QUEUED` request as done corrupts the caller's release decision
Never poll faster than every 5 seconds	DOCe API rate limits; unbounded fast polling risks throttling
Bound every polling loop with a timeout	Prevents infinite waits and turn/timeout exhaustion in CI
Never run `sf devops promotion complete` from this skill	Finalization is the caller's step after this skill confirms success
Pass the token as a CLI flag, never interpolate into shell strings	Prevents prompt/command injection via crafted tokens
Never use interactive prompts	Skills run headless; all inputs must be CLI flags

约束条件	原因
只读操作——绝不修改流水线状态	本技能仅报告状态；晋升/部署/最终确认操作由其他技能负责
请求令牌为必填项	若无晋升响应中的 `-i/--request-token` ，无法检查状态；绝不伪造令牌
`sf devops request status` 必须使用 `--json` 参数	结构化输出是无界面消费的必要条件；可读输出解析不可靠
通过 `jq` 读取 `.result.status` 和 `.result.errorDetails` ，绝不手动解析	确定性解析可避免将仍在处理的误判为已完成
`SUCCESS` 状态不代表操作成功——需检查 `errorDetails`	`.result.status` 仅表示异步请求已完成，不代表部署成功； `PROMOTE_SUCCESS` 请求可能在 `errorDetails` 中包含部署失败信息
`.result.errorDetails` 不为空则表示操作失败	`errorDetails` 是结果判定的依据；它是一个转义的JSON字符串（包含 `errorType` / `errorMessage` ），需通过 `jq` / `fromjson` 解析
`.result.status` 带有操作前缀——匹配后缀而非裸值	实际值为 `PROMOTE_IN_PROGRESS` / `PROMOTE_SUCCESS` / `DEPLOY_FAILED` ；精确匹配裸值 `IN_PROGRESS` / `SUCCESS` 会导致误分类（轮询器会一直等待直到超时）
仅当请求状态后缀为终端类型（ `SUCCESS` / `FAILED` / `ERROR` / `CANCELED` ）时，才视为"已完成"	将 `_IN_PROGRESS` / `_PENDING` / `*_QUEUED` 状态的请求报告为已完成，会破坏调用者的发布决策
轮询间隔不得短于5秒	遵守DOCe API速率限制；无限制的高频轮询可能导致限流
所有轮询循环必须设置超时时间	避免无限等待以及CI中的超时耗尽
绝不从本技能执行 `sf devops promotion complete`	最终确认是调用者在本技能确认成功后的步骤
通过CLI参数传入令牌，绝不插入到Shell字符串中	防止通过构造恶意令牌进行命令注入
绝不使用交互式提示	技能运行在无界面环境；所有输入必须通过CLI参数传入

Gotchas

常见问题

Issue	Resolution
No request token provided	STOP and ask for it, or obtain it from the prior `dx-devops-promote` promote response. Never guess
`status: "SUCCESS"` but the deploy actually failed	The most important trap: a `SUCCESS` status only means the request finished. Check `.result.errorDetails` — if non-null, the operation FAILED. Parse it: `jq -r '.result.errorDetails \| fromjson \| "\(.errorType): \(.errorMessage)"'`
`errorDetails` is a string, not an object	It is escaped JSON (e.g. `"{\"errorType\":\"DEPLOYMENT_FAILURE\",...}"` ); pipe through `fromjson` before reading `.errorType` / `.errorMessage`
Status is operation-prefixed ( `PROMOTE_SUCCESS` , `DEPLOY_FAILED` )	Match on the suffix with globs ( `SUCCESS` , `FAILED` ); exact-matching bare `SUCCESS` / `FAILED` misclassifies a prefixed value — a poller would treat `PROMOTE_IN_PROGRESS` as unknown and hang until timeout
Reporting a still-processing request as complete	Terminal suffixes are `SUCCESS` / `FAILED` / `ERROR` / `CANCELED` ; treat `_IN_PROGRESS` / `_PENDING` / `_QUEUED` / `_NEW` / `*_STARTED` as not done — keep polling or report in-progress
No default org set	Run `sf org display --json` ; if it fails, instruct the user to run `sf org login web --set-default`
Rate-limit / throttle errors while polling	Increase the interval (back off); never poll below the 5-second floor
Infinite wait	Always pass a timeout to `scripts/poll-status.sh` ; on timeout, report the last status rather than blocking
Confusing request failure with skill failure	A `Failed` request status is a valid result — report it clearly; do not treat it as a skill error or retry blindly

问题	解决方法
未提供请求令牌	立即停止并向用户索要，或从之前的 `dx-devops-promote` 晋升响应中获取。绝不猜测
`status: "SUCCESS"` 但实际部署失败	这是最关键的陷阱： `SUCCESS` 状态仅表示请求已完成。检查 `.result.errorDetails` ——若不为空，则操作失败。解析方式： `jq -r '.result.errorDetails \| fromjson \| "\(.errorType): \(.errorMessage)"'`
`errorDetails` 是字符串而非对象	它是转义后的JSON（如 `"{\"errorType\":\"DEPLOYMENT_FAILURE\",...}"` ）；在读取 `.errorType` / `.errorMessage` 前需通过 `fromjson` 处理
状态带有操作前缀（ `PROMOTE_SUCCESS` , `DEPLOY_FAILED` ）	使用通配符匹配后缀（ `SUCCESS` , `FAILED` ）；精确匹配裸值 `SUCCESS` / `FAILED` 会误分类带前缀的值——轮询器会将 `PROMOTE_IN_PROGRESS` 视为未知状态并一直等待直到超时
将仍在处理的请求报告为已完成	终端后缀为 `SUCCESS` / `FAILED` / `ERROR` / `CANCELED` ；将 `_IN_PROGRESS` / `_PENDING` / `_QUEUED` / `_NEW` / `_STARTED*` 视为未完成——继续轮询或报告请求正在进行
未设置默认组织	执行 `sf org display --json` ；若失败，指导用户执行 `sf org login web --set-default`
轮询时遇到速率限制/限流错误	增加轮询间隔（退避）；轮询间隔不得低于5秒
无限等待	始终为 `scripts/poll-status.sh` 设置超时时间；超时后报告最后观测到的状态而非持续阻塞
混淆请求失败与技能失败	`Failed` 请求状态是有效结果——需清晰报告；请勿将其视为技能错误或盲目重试

Output Expectations

输出预期

Deliverables vary by mode:

Single check:
```
.result.status
```
(request-processing state) plus the derived outcome — on failure, the
```
errorType
```
/
```
errorMessage
```
parsed from
```
.result.errorDetails
```
and the
```
.result.message
```
field
Poll-to-completion: the derived terminal outcome (succeeded or failed, per the
```
errorDetails
```
check) plus elapsed wait, or the last observed request status if the timeout was reached first

Outputs are derived from

sf devops request status

. This skill produces no artifacts and mutates nothing.

交付内容因模式而异：

单次检查：
```
.result.status
```
（请求处理状态）及推导的结果——失败时，包含从
```
.result.errorDetails
```
和
```
.result.message
```
字段解析出的
```
errorType
```
/
```
errorMessage
```
轮询直到完成：推导的终端结果（根据
```
errorDetails
```
检查判定成功或失败）及已等待时长；若先达到超时时间，则报告最后观测到的请求状态

输出内容均来自

sf devops request status

。本技能不会生成任何工件，也不会修改任何内容。

Cross-Skill Integration

跨技能集成

When	Action
A promotion or deploy must be initiated first to get a request token	Delegate to `dx-devops-promote`
Outcome is success (finished, `errorDetails` null) and the promotion still needs finalizing	Hand back to `dx-devops-promote` to run `sf devops promotion complete`
Status reports `Failed` due to a metadata conflict	Report the conflict from `errorDetails` ; hand back to `dx-devops-promote` to resolve and re-promote

场景	操作
需先发起晋升或部署操作以获取请求令牌	委托给 `dx-devops-promote`
结果为成功（请求完成， `errorDetails` 为空）且晋升操作仍需最终确认	返回给 `dx-devops-promote` 执行 `sf devops promotion complete`
状态报告因元数据冲突导致 `Failed`	从 `errorDetails` 中报告冲突信息；返回给 `dx-devops-promote` 解决冲突并重新发起晋升

Reference File Index

参考文件索引

File	When to read
`references/cli-commands.md`	When you need the `sf devops request status` flags, JSON output schema, status-value vocabulary, or error-handling patterns
`examples/polling-workflows.md`	When the user's request matches a common pattern (one-shot check, poll-until-done after a promote, timeout handling, failure reporting)
`scripts/poll-status.sh`	Phase 2 — invoke with `--once` for a single deterministic status check; Phase 3 — invoke without `--once` to poll a request token with a bounded interval and exact timeout until it reaches a terminal state

文件	阅读场景
`references/cli-commands.md`	需要了解 `sf devops request status` 的参数、JSON输出架构、状态值词汇或错误处理模式时
`examples/polling-workflows.md`	用户请求符合常见模式（单次检查、晋升后轮询直到完成、超时处理、失败报告）时
`scripts/poll-status.sh`	阶段2——使用 `--once` 参数执行单次确定性状态检查；阶段3——不使用 `--once` 参数，按指定间隔和超时时间轮询请求令牌直到进入终端状态