dx-devops-work-item-manage

DevOps Center 工作项管理

管理 DevOps Center 中工作项的完整生命周期 — 从创建、状态转换到晋级就绪。提供由 CLI 驱动的无头操作，支持自主发布工作流。

范围

• 包含：列出工作项、创建工作项、将更改提交到工作项分支、更新工作项字段（主题、描述、状态）、转换工作项状态（New → In Progress → Ready to Promote）、为工作项分支创建拉取请求
• 不包含：晋级/部署、冲突检测、管道或项目管理（由单独的技能负责）

---

必需输入

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

• 操作类型：list、create、update、commit 或 create-review
• 对于 list：项目 ID（必需）— 如果未提供，请通过 sf devops project list --json 获取
• 对于 create：项目 ID（必需）、主题（必需）、描述（可选）
• 对于 commit：工作项名称或 ID（必需）、提交消息，以及要提交的文件（git 路径）或要提交的组件（API 路径）。可选：开发组织别名 — 保存更改的组织。如果提供，请先尝试 DevOps Center 提交 API（见步骤 5）；否则使用 git
• 对于 update：工作项名称（例如 WI-000001）或工作项 ID（必需）、要更新的字段（主题、描述、状态）
• 对于 create-review：工作项名称（例如 WI-000001）或工作项 ID（必需）

除非另有说明，默认设置如下：

• 输出格式：使用 --json 以便无头使用
• 工作项标识符：如果两者都有，优先使用 --work-item-name（WI-000001），而不是 --work-item-id（名称更易读）

如果用户提出了明确请求（“列出 Project Alpha 的工作项”、“创建工作项以修复登录错误”、“将 WI-12345 移至 In Progress”、“为 WI-12345 创建 PR”），请立即继续操作，无需不必要的提问。

---

工作流

操作使用 sf devops work-item CLI 命令并通过 --json 输出；API 提交路径还会使用 sf api request rest 和 sf data query。

阶段 1 — 确定操作

1. 根据用户意图确定操作类型：
   • “list”、“show”、“find”等关键词 → list 操作
   • “create”、“new”、“add”等关键词 → create 操作
   • “commit”、“push”、“save changes”、“git commit”等关键词 → commit 操作
   • “update”、“change”、“modify”、“edit”、“move”、“transition”、“advance”、“mark as”等关键词 → update 操作
   • “create PR”、“pull request”、“code review”、“review”、“open PR”等关键词 → create-review 操作

阶段 2 — 执行操作

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

   sf org display --json
   

   • 如果未设置默认组织或身份验证已过期，请指示用户运行：

     sf org login web --set-default --alias <alias>
     

   • 尝试列出项目，以验证已通过身份验证的组织已启用 DevOps Center
   • 如果用户要指定目标组织，请在所有后续命令中使用 --target-org <alias>
   • 对于 API 提交路径，请对开发组织和中心组织均运行 sf org display --target-org <alias> --json

3. 列出工作项 — 用户想查看已有工作项时：

   sf devops work-item list --project-id <project-id> --json
   

   • 必须提供 --project-id；如果用户提供的是项目名称而非 ID，请先运行 sf devops project list --json，将名称解析为 ID
   • 确认命令返回状态码 0（成功）
   • 解析 JSON 输出：工作项位于 .result[] 数组中
   • 每个工作项包含：name（例如，WI-000001）、subject、branch、environment、status、description
   • 以易读的格式展示工作项名称、主题、状态、分支和环境
   • 如果 .result[] 是空数组，请确认“项目 中没有找到工作项。”
   • 如果用户要求按状态筛选（例如，“显示状态为 Ready to Promote 的工作项”），运行：

     sf devops work-item list --project-id <id> --json | jq '.result[] | select(.status == "<requested-status>")'
     

     然后展示匹配的工作项

4. 创建工作项 — 用户想创建新工作项时：

   sf devops work-item create \
     --project-id <project-id> \
     --subject "<subject>" \
     --description "<description>" \
     --json
   

   • 必须提供 --project-id（向用户获取，或通过 sf devops project list --json 获取）
   • 必须提供 --subject（面向用户的标题）
   • --description 为可选项（省略时默认为空）
   • 从 JSON 输出中记录返回的工作项名称（例如，WI-000001）、分支名称和环境，以供后续操作使用
   • 幂等：如果用户尝试创建重复项（主题和项目相同），先通过列表检查，并返回现有工作项

5. 执行提交操作 — 操作类型为 commit 时。先选择路径：

   • API 路径 — 仅当用户提供了开发组织别名，且更改已部署到该开发组织时使用（如果不确定，请询问：使用 sf project deploy start 部署，还是使用 git）。开发组织别名：commitChanges、DevopsRequestInfo。Hub 别名：sf devops 和 WorkItemComponentList。DevOps Center 会从开发组织获取指定组件，并以 DevOps Center <[email protected]> 的身份提交。
   • Git 路径 — 其他所有情况。如果更改仅存在于开发组织中，请先运行 sf project retrieve start --target-org <dev-org>。

   API 路径（命令、请求正文、错误代码和轮询方式见 references/commit-api.md）：

   1. 在开发组织上预检 GET /connect/devops/doceConnectionType；如果调用失败（退出码非零或返回错误正文），或者 isCore 不为 true，则使用 git 路径。
   2. sf devops project list → 获取项目 ID，然后运行 sf devops work-item list --project-id <id> --target-org <hub> → 获取工作项 ID 和名称。状态必须为 New、In Progress、In Review 或 Ready to Promote。
   3. 在开发组织上执行 POST /connect/devops/commitChanges；请求正文为内部对象（不带 commitChanges 包装层）。
   4. 如果调用失败，或 status: "ERROR" 且 reqId = CODE:message，则报告该错误并停止。
   5. 如果 POST 的 status 为 SUCCESS（仅表示已受理），则每 10 秒在开发组织上轮询 DevopsRequestInfo WHERE RequestToken = '<reqId>'，直到 Status 为 SUCCESS 或 ERROR（报告 Message/ErrorDetails），最长等待 12 分钟。超过期限表示请求卡住；请报告情况，不要自动重试。
   6. 在创建评审前，确认 Hub 上存在新的 WorkItemComponentList。

   Git 路径：

   • 如果工作项处于 New 状态，先将其设为 In Progress（第 6 步）；工作项处于 New 状态时，Hub 会忽略推送
   • 使用工作项的 branch 字段作为分支
   • 标准 git 工作流：

     git checkout <branch-name>
     git add <files>
     git commit -m "<commit-message>"
     git push origin <branch-name>
     

   • Hub 会异步登记推送；创建 PR 前请重新检查

6. 更新工作项 — 当用户想要更改主题、描述或状态时：

   sf devops work-item update \
     --work-item-name <WI-name> \
     --subject "<new-subject>" \
     --description "<new-description>" \
     --status "<In Progress|Ready to Promote>" \
     --json
   

   • 必须提供工作项标识符：使用 --work-item-name <WI-000001>（首选）或 --work-item-id <id>
   • 如果用户提供的是工作项主题而不是名称，请先将其解析为名称：

     sf devops work-item list --project-id <id> --json | jq -r '.result[] | select(.subject == "<user-provided-subject>") | .name'
     

     然后将返回的名称（例如，WI-000001）传递给更新命令
   • 必须至少提供 --subject、--description 或 --status 中的一个
   • 有效状态值："In Progress" 或 "Ready to Promote"（必须使用带空格的精确字符串）
   • 仅包含要更新字段对应的标志（省略未更改的字段）
   • 确认命令返回状态码 0（成功）
   • 解析 JSON 响应：.result.name、.result.subject、.result.status 包含更新后的值
   • 特别针对状态转换：命令完成后，通过检查响应中的 .result.status 明确确认新状态。如果更新响应中缺少状态字段，请重新查询工作项列表，确认状态已持久化

7. 创建拉取请求 — 当用户想要为代码审查创建 PR 时：

   sf devops review create \
     --work-item-name <WI-name> \
     --json
   

   • 必须提供工作项标识符：使用 --work-item-name <WI-000001>（首选）或 --work-item-id <id>
   • 如果用户提供的是工作项主题而不是名称，请先将其解析为名称：

     sf devops work-item list --project-id <id> --json | jq -r '.result[] | select(.subject == "<user-provided-subject>") | .name'
     

     然后将返回的名称（例如，WI-000001）传递给创建审查的命令
   • 通过 DevOps Center API 创建 PR，使用组织中存储的 VCS 凭据
   • 无需本地 VCS 身份验证 — DevOps Center 会处理 GitHub/Bitbucket 身份验证
   • 适用于 GitHub 和 Bitbucket
   • 确认命令返回状态码 0（成功）
   • 解析 JSON 响应：.result.pullRequestUrl 包含 PR URL，.result.status 包含 PR 状态（新创建的 PR 通常为 "open"），.result.number 包含 PR 编号
   • 如果命令因 VCS 凭据错误而失败，请指导用户在 DevOps Center 组织中配置 VCS 凭据（Setup → DevOps Center → VCS Credentials）
   • 如果命令因 "PR already exists" 错误而失败，请告知用户此工作项已有 PR（此操作具有幂等性）

阶段 3 — 验证并报告

8. 验证操作是否成功：

   • 对于列表操作：确认 CLI 返回状态码 0，解析 JSON .result[] 数组，并验证其中包含工作项（如果没有匹配项，则数组为空）。如果用户按名称指定了项目，请确认解析出的项目 ID 与之匹配。
   • 对于创建操作：确认 CLI 返回状态码 0，且 JSON 输出包含 .result.name（工作项 ID，例如 WI-000001）、.result.branch（分支名称）和 .result.environment 字段。
   • 对于提交操作（git 路径）：确认每条 git 命令的退出代码均为 0。如果 git push 成功，则提交已保存到工作项分支；hub 会异步登记该提交。
   • 对于提交操作（API 路径）：确认 POST status，然后确认 DevopsRequestInfo.Status 均为 SUCCESS，并且 hub 上存在带有 CommitReference 的新 WorkItemComponentList。如果新列表中的 CommitReference 为空，表示没有提交任何新内容；应如实报告，而不能报告为成功。
   • 对于更新操作（常规字段）：确认 CLI 返回状态码 0，并将返回的 JSON 字段与用户请求的更改进行比较。如果更新的是主题，请确认 .result.subject 与新值一致。
   • 对于更新操作（状态转换）：确认 CLI 返回状态码 0，然后通过检查 JSON 响应中的 .result.status 是否与目标状态匹配，明确确认状态已转换（例如，“Ready to Promote”）。如果响应中不包含状态字段，请重新运行 sf devops work-item list，筛选此工作项并验证状态已保存。
   • 对于创建评审操作：确认 CLI 返回状态码 0，且 JSON 输出包含 .result.pullRequestUrl（PR URL）和 .result.status（应为“open”或等效状态）。如果缺少 VCS 凭据，CLI 会返回错误 — 请将此情况告知用户。

9. 报告结果：

   • 列表操作：以易读的格式展示工作项名称、主题、状态、分支和环境。如果用户要求按状态筛选，则只显示符合条件的工作项。
   • 创建操作：返回工作项名称（例如 WI-000001）、分支名称和环境，并确认“工作项已成功创建。”
   • 提交操作：git 路径 — 确认暂存了哪些文件、提交 SHA（来自 git 输出），并说明“更改已提交并推送到分支 。”API 路径 — 确认 reqId、已提交的组件以及 hub 的 CommitReference（作者为 DevOps Center）。
   • 更新操作（常规）：确认哪些字段发生了更改，并列出更改前后的值（例如，“主题已从 ‘X’ 更新为 ‘Y’。”）。
   • 状态转换：明确说明状态转换，列出旧状态 → 新状态（例如，“状态已更新：In Progress → Ready to Promote”）。
   • 创建评审操作：返回 PR URL，并确认“拉取请求已成功创建。状态：open。URL：”

---

规则 / 限制

限制	原因
所有 sf devops 命令都必须使用 --json 标志	无头环境需要结构化输出；人类可读的输出不便于解析
提交、更新和创建评审时必须提供工作项标识符	使用 --work-item-name（首选）或 --work-item-id；从列表或先前的创建操作中获取
列出和创建时必须提供项目 ID	所有工作项都属于某个项目；如果未提供，请使用 sf devops project list --json
至少需要一个更新字段	如果未提供 --subject、--description 或 --status 标志，更新命令将失败
状态值必须是准确的字符串	"In Progress" 和 "Ready to Promote"（包含空格并使用正确的大小写）；其他值会导致失败
创建操作必须幂等	创建前，检查是否已有主题和项目相同的工作项，以免重复创建
创建 PR 前必须先提交	先提交，并确认 hub 上存在组件列表，然后再执行 review create
API 提交只会发送 dev 组织中已有的组件	API 从 dev 组织获取内容，而非本地磁盘；请先部署仅在本地的编辑（sf project deploy start），或使用 git 路径
检查提交 API 响应中的 status	错误会以 HTTP 200 返回，且 status: "ERROR"
创建 PR 需要组织中配置 VCS 凭据	DevOps Center API 使用存储的 VCS 凭据；无需本地 git 身份验证
切勿使用交互式提示	技能在无头环境中运行；所有输入都必须通过 CLI 标志提供

---

注意事项

问题	解决方法
未设置默认组织	先运行 sf org display --json；如果失败，请指示用户运行 sf org login web --set-default
用户提供的是主题而非工作项名称	通过以下命令解析：sf devops work-item list --project-id <id> --json | jq -r '.result[] | select(.subject == "<subject>") | .name'；然后将返回的名称传给 update/create-review 命令
用户提供的是项目名称而非 ID	先运行 sf devops project list --json，并按 .name 字段筛选 .result[] 以查找项目 ID，然后在 list/create 命令中使用该 ID
状态更新响应缺少 status 字段	CLI 的更新响应不一定会返回 status 字段；请重新运行 sf devops work-item list，筛选出此工作项，并检查 .result[0].status 以确认状态转换已生效
未找到工作项	用户提供的工作项名称 / ID 无效；运行 list 命令以显示可用工作项
状态值无效	只有 "In Progress" 和 "Ready to Promote" 有效（必须是包含空格的准确字符串）；请检查拼写和大小写
未找到项目	用户提供的项目 ID 无效；运行 sf devops project list --json 以显示可用项目
工作项主题重复	幂等创建检查应能发现此情况；请返回现有工作项名称，而不是创建重复项
工作项处于 New 状态时推送了提交	hub 会忽略 New 工作项的外部推送；请先将状态设为 In Progress，如果已经推送，则在状态更改后再次检查
API 提交在截止时间后仍在进行	报告此操作卡住；不要自动重试（新请求可能与其发生竞争）
Git 推送失败——没有提交或找不到分支	使用 git status 确认文件已暂存，并通过 list 命令从工作项中获取分支名称
创建 PR 失败——VCS 凭据问题	DevOps Center UI 中未配置 VCS 凭据；请指示用户前往 Setup → DevOps Center → VCS Credentials 进行配置

---

输出预期

交付内容因操作而异：

• List：工作项的 JSON 数组，包含工作项名称（WI-######）、主题、分支、环境和存储库详细信息
• Create：新建工作项的名称（例如 WI-000001）、ID、分支名称和环境
• Commit：确认 git 提交和推送成功，并提供提交 SHA；如果使用 API 路径，则提供 reqId、最终请求状态和 CommitReference
• Update：确认已更新的字段（主题／描述的旧值 → 新值，或状态变更）
• Create-review：拉取请求 URL、PR 编号和状态

输出来自 sf devops work-item CLI、sf devops review create CLI 和标准 git 命令。

---

验证清单

向用户报告结果前：

通用检查

• 是否已通过 sf org display --json 验证组织身份验证？
• 是否使用 --json 标志执行 CLI 命令？
• CLI 命令是否以成功退出代码（0）结束？
• JSON 输出是否可解析且非空？
• 如果涉及多个组织，是否在所有命令中指定了 --target-org？

List 操作检查

• 是否提供了 --project-id？
• 显示的工作项是否包含工作项名称、主题、分支和环境？
• 如果列表为空，是否已告知用户？

Create 操作检查

• JSON 输出中是否返回了工作项名称（WI-######）和 ID？
• JSON 输出中是否返回了分支名称？
• 是否提供了 --subject 并将其包含在命令中？
• 是否提供了 --project-id（或通过项目列表获取）？

Commit 操作检查

• API 路径：预检是否通过，POST status 是否已检查，DevopsRequestInfo 是否已轮询至 SUCCESS，Hub 上是否能看到带有 CommitReference 的新 WorkItemComponentList？
• Git 路径：工作项是否处于 In Progress 状态，是否已获取分支名称？
• Git 路径：git add、git commit 和 git push 是否均以 0 退出？

Update 操作检查

• 是否提供了工作项标识符（名称或 ID）？
• 是否至少提供了一个更新字段（主题、描述或状态）？
• 如果更新了状态，是否为有效值（“In Progress”或“Ready to Promote”）？
• 是否以 JSON 格式返回了已更新的工作项？

Create-Review 操作检查

• 是否提供了工作项标识符（名称或 ID）？
• JSON 输出中是否返回了 PR URL？
• 是否已确认 PR 创建成功？

---

参考文件索引

文件	何时阅读
references/commit-api.md	通过 DevOps Center API 提交时：请求正文、响应和错误代码、轮询、预检
references/cli-commands.md	需要了解详细的 CLI 标志说明、JSON 输出架构或错误处理模式时
examples/common-workflows.md	用户请求符合常见模式（批量更新、重新分配、幂等创建、顺序转换）时