checking-devops-prerequisites

检查 DevOps 前提条件

所有 DevOps Center 测试技能共用的检查关卡。任何查询或系统调用之前都要运行这些检查。如有任何检查失败，请用通俗易懂的语言说明原因，并暂停操作，直到用户解决问题——切勿在环境未经验证时执行写入操作。

**API 版本：**所有 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 组织别名，除非确实无法确定：

1. 如果用户在消息中指定了组织别名，则使用该别名。
2. 否则，使用默认组织（sf org display --json，不带 --target-org）。
3. 仅当默认组织没有 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

检查是否有 name 包含 plugin-agent、agentforce 或 einstein（不区分大小写）的插件条目。

• **通过：**找到插件
• **失败：**没有匹配的条目

失败时：“尚未安装 Agentforce DX Plugin。请运行 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 Testing Skills。”
• 失败（不支持的对象）：“<doce-org-alias> 上似乎未安装 DevOps Center。请确认你连接的是正确的组织。”

---

前提条件 5 — 已确定管道阶段（有条件运行）

仅当调用技能针对特定阶段进行操作时才运行。

如果用户的消息中已指定阶段（例如“集成”“预发布”“生产”），则直接使用该名称——不要再次询问。查询其 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 名称
Review 触发器位于管道级别，而非阶段级别	查询 DevopsPipelineStageTrigger，并设置 TriggerType = 'Review' 和 RelatedRecordId = <pipelineId>
Connect API 的 testSuites 在使用 ?stageId= 时返回空结果	使用 ?triggerId=<reviewTriggerId>——stageId 仅适用于阶段级别的触发器
sf plugins 未匹配到 agentforce	已安装的插件是 @salesforce/plugin-agent——也要匹配 plugin-agent