checking-devops-prerequisites

用途

本技能是每个 DevOps Center 测试技能的共享前置关卡。在任何查询或系统调用之前运行这些检查。一旦出现失败，就展示通俗易懂的提示信息并停止，直到用户解决为止——绝不在未验证的环境中继续执行写入操作。

所有 DevOps 测试系统调用均以 Salesforce API v67.0（最低要求）为目标。

重要：所有 DevOps Center 数据（流水线、阶段、测试套件、执行记录）都存放在 Salesforce 组织中，而不是本地仓库。切勿在文件系统中搜索流水线配置。始终使用 sf data query 或 sf api request rest 查询组织。

其他技能如何使用本技能

每个 DevOps 测试技能都会先加载本技能，并按顺序运行前置条件 1–4。前置条件 5（阶段）仅在调用方技能针对特定流水线阶段（运行/重新触发套件、同步、配置门禁、映射套件）时运行。调用方技能会接收解析出的 doce-org-alias、pipelineId 以及（适用时）stageId，用于其自身命令。

在解析 DevOps Center 组织别名时，除非确实存在歧义，否则不要询问用户：

如果用户在消息中指定了组织别名，则使用它。
否则使用默认组织（sf org display --json，不带 --target-org）。
仅当默认组织没有 DevopsPipeline 记录（前置条件 4 失败）时，才询问：“你的 DevOps Center 组织别名是什么？”

前置条件 1 — Salesforce 组织：活动登录

sf org list --json

在 result.nonScratchOrgs、result.scratchOrgs 或 result.sandboxes 中查找至少一个 "connectedStatus": "Connected" 的条目。

通过：至少有一个组织处于 Connected 状态
失败：未列出任何组织，或全部显示为非连接状态

失败时提示：“未找到已认证的 Salesforce 组织。请在终端运行 sf org login web --alias <your-alias>，然后重试。”

前置条件 2 — 已安装 Agentforce DX 插件

sf plugins --json

查找名称包含 plugin-agent、agentforce 或 einstein 的插件条目（不区分大小写）。

通过：找到匹配插件
失败：无匹配条目

失败时提示：“未安装 Agentforce DX 插件。请运行 sf plugins install @salesforce/plugin-agent，然后重启 IDE 并重试。”

前置条件 3 — DevOps Center 组织已认证

sf org display --target-org <doce-org-alias> --json

检查 "connectedStatus" 是否为 "Connected"。

通过：Connected
失败：会话过期或出错

失败时提示：“你的 DevOps Center 组织会话已过期。请运行 sf org login web --alias <doce-org-alias> 重新认证。”

前置条件 4 — 已识别流水线

sf data query \
  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
  --target-org <doce-org-alias> \
  --json

通过（恰好一个）：自动使用它——不要询问。
通过（多个）：如果用户已指定流水线，则按名称匹配。否则显示编号列表并询问：

Found <N> pipelines:
1. <Name>
2. <Name>
Which pipeline would you like to work with?

失败（无记录）：“未找到 DevOps Center 流水线。请先在 DevOps Center 中创建项目和流水线，然后再使用 DevOps 测试技能。”
失败（不支持的对象）：“<doce-org-alias> 上似乎未安装 DevOps Center。请检查是否指向了正确的组织。”

前置条件 5 — 已识别流水线阶段（条件性）

仅在调用方技能针对特定阶段时运行。

如果用户消息中已指定阶段名称（例如 “Integration”、“Staging”、“Production”），直接使用该名称——不要再次询问。查找其 Id：

sf data query \
  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
  --target-org <doce-org-alias> --json

仅当未提及任何阶段时，才获取完整列表并询问：

sf data query \
  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
  --target-org <doce-org-alias> --json

然后询问：“我们要处理哪个流水线阶段？”——不要询问组织别名；阶段通过流水线按名称解析。

通过：阶段 Id 和 Name 已确认
延迟：在调用方技能需要之前不必执行

错误处理

错误情况	响应
`sf org list` 完全失败	“无法访问 Salesforce CLI。请确保已安装 `sf` 并在 PATH 中。”
`sf org display` 返回认证错误	展示通俗易懂的重新认证说明。不要暴露原始错误。
DevopsPipeline 查询返回 5xx	“DevOps Center 组织返回服务器错误。请几分钟后重试。”
任何检查意外抛出异常	“检查前置条件时出现问题。错误：[简要说明]。让我们重试——或者手动解决后告诉我已就绪。”

切勿向用户暴露原始 API 错误、堆栈跟踪或 JSON 错误负载。

注意事项

问题	解决方法
DevopsPipeline 查询返回空	目标组织未安装 DevOps Center，或组织别名错误——请用户核实
不支持 DevopsWorkItem sObject	使用 `WorkItem`（无命名空间）——这是该组织版本的正确 API 名称
审查触发器是流水线级别，不是阶段级别	查询 `DevopsPipelineStageTrigger`，条件为 `TriggerType = 'Review'` 且 `RelatedRecordId = <pipelineId>`
Connect API testSuites 带 `?stageId=` 返回空	使用 `?triggerId=<reviewTriggerId>`——`stageId` 仅适用于阶段级触发器
`sf plugins` 未匹配到 agentforce	已安装插件为 `@salesforce/plugin-agent`——也可匹配 `plugin-agent`