dx-devops-request-status

DevOps Center 请求状态

通过 sf devops request status，使用请求令牌轮询异步 DevOps Center 请求（提升或部署操作）的状态。为 CI 中的自主发布工作流提供由 --json 驱动的无头只读状态检查。此技能绝不会修改管道状态；它只报告正在进行或已完成请求的当前状态。

范围

• 范围内：通过请求令牌检查单个异步请求的状态；解读两层结果（请求处理的 .result.status 与 .result.errorDetails 失败判定依据）；采用退避方式轮询，直到请求完成或达到调用方指定的超时时间；失败时显示解析后的错误详情
• 范围外：发起提升或部署（请使用 dx-devops-promote）、创建工作项／更新状态（请使用 dx-devops-work-item-manage）、冲突检测、运行 sf devops promotion complete（此技能确认成功后，这是调用方接下来的步骤）、管道或项目设置

---

必需输入

继续之前，请收集或推断以下信息：

• 请求令牌（必需）：dx-devops-promote 提升响应返回的请求令牌。通过 -i/--request-token 传入。没有此令牌，此技能无法继续——请向用户索取，或从之前提升步骤的输出中获取
• 目标组织：-o/--target-org <alias>（必需，除非已设置 target-org 配置变量）

未另行指定时的默认值：

• 输出格式：--json，用于无头模式下的处理
• 轮询间隔：每次检查间隔 10 秒；总等待时间上限为调用方指定的超时时间（默认 30 分钟）。轮询间隔不得短于 5 秒——DOCe API 有速率限制

如果用户提出明确请求（“检查请求 a0B…”，“轮询请求 a0B…，直到完成”），则在获得请求令牌后继续。

---

工作流

所有操作都使用带有 --json 输出的 sf devops request status。此技能为只读——不会执行任何修改操作。命令标志和 JSON 输出架构见 references/cli-commands.md。

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

1. 在执行任何操作前验证组织身份：

   sf org display --json
   

   • 如果失败，请让用户运行 sf org login web --set-default --alias <alias>
   • 在后续每条命令中传入 -o/--target-org <alias>（必需，除非已设置 target-org 配置变量）

2. 确认已有请求令牌。 如果用户在同一会话中发起了提升操作，请使用从 dx-devops-promote 提升响应中获取的请求令牌。如果没有可用令牌，请停止并向用户索取——切勿猜测或伪造令牌。

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

关键： .result.status（大写，例如 SUCCESS）表示异步请求是否已完成处理，而不是底层部署是否成功。即使部署本身失败，请求仍可能显示 status: "SUCCESS"。真正的结果判定依据是 .result.errorDetails：errorDetails 非空表示操作失败，即使 status == SUCCESS 也是如此。

3. 运行一次状态检查，使用 scripts/poll-status.sh --once 查询请求一次，并以确定的方式判定真实结果（对操作前缀的 .result.status 后缀进行全局模式匹配，然后应用 .result.errorDetails 失败判定规则）。请勿在说明文字中自行编写 JSON 解析逻辑——脚本负责处理这项双层规则，以确保它与轮询流程保持一致：

   scripts/poll-status.sh --once <request-token> <target-org-alias>
   

   根据退出码进行判断（脚本会打印一行易于理解的结果）：
   • 0 — 请求已完成，且操作成功（errorDetails 为 null）→ 将结果交还给调用方
   • 2 — 请求已完成，但操作失败（状态后缀为 *FAILED*/*ERROR*/*CANCELED*，或状态为 *SUCCESS* 且 errorDetails 非空）→ 打印的行中包含解析后的 errorType/errorMessage
   • 4 — 请求仍在处理中（非终止状态后缀）→ 进入阶段 3 继续轮询；若仅执行一次检查，则报告仍在处理中
   • 1 — 查询/用法错误（令牌错误、身份验证失败或缺少依赖项）

阶段 3 — 轮询直至终止（仅在用户要求等待时）

4. 在有限循环中轮询，当用户要求等待完成时，运行 scripts/poll-status.sh 并报告它打印的最终状态：

   scripts/poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]
   

   • 脚本按 interval-seconds 轮询（默认值为 10），不会休眠超过 timeout-seconds，遇到终止请求状态时停止，并应用与 --once 相同的双层结果检查。退出码：0 = 已完成且成功（errorDetails 为 null），2 = 已完成但操作失败（errorDetails 已设置，或状态后缀为 *FAILED*/*ERROR*/*CANCELED*），3 = 超时，1 = 查询/用法错误
   • 这是只读循环——仅执行 sf devops request status 查询，不执行任何变更操作
   • 请勿在说明文字中自行编写轮询循环；脚本会以确定的方式强制执行最小轮询间隔、精确超时、终止状态检测以及 errorDetails 结果检查

阶段 4 — 报告

5. 报告结果：
   • 成功时（已完成，errorDetails 为空）："Request <token> completed successfully." — 然后提醒调用方，下一步是完成推广操作（sf devops promotion complete），由 dx-devops-promote 负责
   • 失败时（已完成，errorDetails 已设置——即使 status == SUCCESS 也是如此）："Request <token> failed." 并附上从 errorDetails 解析出的 errorType / errorMessage 以及 message 字段——此处请勿重试或修复，交由调用方决定
   • 超时时（仍在处理中）：报告最近一次观测到的请求状态和已等待时长；建议稍后再次轮询——对于尚未完成处理的请求，请勿报告成功或失败

---

规则 / 约束

约束	原因
只读——绝不修改流水线状态	此技能仅报告状态；晋级、部署和完成由其他技能负责
必须提供请求令牌	没有 promote 响应中的 -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 标志提供

---

易错点

问题	解决方法
未提供请求令牌	停止并索取令牌，或从先前的 dx-devops-promote 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 请求状态是有效结果——请明确报告；不要将其视为技能错误，也不要盲目重试

---

输出要求

不同模式的交付内容有所不同：

• 单次检查：.result.status（请求处理状态）以及推导出的结果——如果失败，则包括从 .result.errorDetails 解析出的 errorType/errorMessage 和 .result.message 字段
• 轮询直至完成：推导出的终态结果（根据 errorDetails 检查判断为成功或失败）以及等待时长；如果先达到超时时间，则返回最后观测到的请求状态

输出由 sf devops request status 推导得出。此技能不会生成任何产物，也不会修改任何内容。

---

跨技能集成

何时	操作
必须先发起 promotion 或部署才能获取请求令牌时	委托给 dx-devops-promote
结果成功（已完成，errorDetails 为 null），且仍需完成 promotion 时	交回给 dx-devops-promote，以运行 sf devops promotion complete
状态因元数据冲突而报告 Failed 时	报告 errorDetails 中的冲突；交回给 dx-devops-promote 以解决冲突并重新执行 promotion

---

参考文件索引

文件	何时阅读
references/cli-commands.md	需要了解 sf devops request status 标志、JSON 输出架构、状态值词汇或错误处理模式时
examples/polling-workflows.md	用户请求符合常见模式时（单次检查、promotion 后轮询直至完成、超时处理、失败报告）
scripts/poll-status.sh	阶段 2——使用 --once 执行一次确定性的状态检查；阶段 3——不带 --once 调用，以有界间隔和精确超时时间轮询请求令牌，直至达到终态