service-itsm-agentic-setup-agentforce-studio-validate

验证 Agentforce for IT Service 的前置条件

针对 Agentforce for IT Service 的就绪状态检查，适用于 Fulfiller 或 Employee Agent 路径。创建 ITSM Agent 之前，组织必须启用正确的 Salesforce Go 功能开关（位于 Agentforce for IT Service 设置页面）。此技能通过 Salesforce CLI（sf） 读取这些开关——通过 sf api request rest 发起一次经过身份验证的 Connect API 调用——并由辅助脚本将所选 Agent 路径判定为 READY / NOT-READY。

这是三技能流程中的只读步骤。它绝不会启用任何功能；启用开关属于另一个具备写入能力的技能：

步骤	技能	功能
1. 验证（本技能）	service-itsm-agentic-setup-agentforce-studio-validate	读取开关 → READY / NOT-READY（不执行写入）
2. 配置	service-itsm-agentic-setup-agentforce-studio-configure	将已禁用的开关设为 ON
3. 创建 Agent	service-itsm-agentic-setup-fulfiller-agent-configure	创建并激活 Fulfiller Agent

如果结果为 NOT-READY，本技能会列出每个已禁用的开关，并移交给 service-itsm-agentic-setup-agentforce-studio-configure 以启用这些开关；它不会自行 POST 启用请求。

功能开关及其实际的 featureApiName：

Go 页面开关	featureApiName	必需路径
Turn on Agentforce Studio	sales-cloud-agent-studio	两条路径（共用）
Agentforce for IT Service	service-cloud-agentforce-for-itsm	两条路径（共用）
IT Service Fulfiller Template	service-cloud-it-fulfiller-agent	fulfiller
IT Service Employee Template	service-cloud-requestor-agent	employee
Specialized Agent Templates for Employee	service-cloud-it-service-employee-agent	employee

这些都是 Connect API 功能（/connect/setup/discovery/...）——通过 sf api request rest 读取，无需 Headless360 dispatcher。判定逻辑是确定性的，位于 scripts/classify-readiness.mjs 中（通过 Bash 调用），而非写在说明文字中。

范围

• 范围内：通过 connect/setup/discovery/features/status 读取 Agentforce-for-IT-Service Go 功能开关；通过辅助脚本将 fulfiller 或 employee 路径判定为逐项功能和总体的 READY / NOT-READY；如果结果为 NOT-READY，则列出每个已禁用的开关，并移交给 service-itsm-agentic-setup-agentforce-studio-configure 以启用这些开关。
• 范围外：启用任何开关——该写入操作由 service-itsm-agentic-setup-agentforce-studio-configure 负责（本技能为只读技能，绝不会 POST 启用请求）；创建、提交或激活 Agent（由 service-itsm-agentic-setup-fulfiller-agent-configure 处理）；组织范围的多 Agent 编排开关（这是仅供 Headless360 使用的偏好设置，并非 ITSM Connect 功能，也不是设置页面上的开关之一）；分配权限集；CMDB CRUD。

---

选择哪条路径？

确定用户要设置的是 fulfiller Agent（面向 IT 履行人员的 Agent），还是 employee Agent（面向员工的 / NGA Agent）。如果请求中不明确，请提问（AskUserQuestion）。路径决定必需的开关：

• fulfiller → sales-cloud-agent-studio + service-cloud-agentforce-for-itsm + service-cloud-it-fulfiller-agent
• employee → sales-cloud-agent-studio + service-cloud-agentforce-for-itsm + service-cloud-requestor-agent + service-cloud-it-service-employee-agent

---

前提条件

在此技能读取任何内容之前，必须先配置 CLI 和目标组织。如果未满足其中任何一项，sf 会显示身份验证错误或 401/403/404；不要伪造状态——显示原始错误并停止。

1. 已安装 sf CLI，且已通过身份验证连接到目标组织（sf org display -o <alias> 显示 Connected）。所有调用都使用 --target-org <alias>；切勿手动提取或传递访问令牌。
2. API v67.0+：connect/setup/discovery 功能 API 从 v67.0 起可用。版本固定在 URL 路径中；切勿手动编辑到低于最低版本。
3. PATH 中有 node ≥ 18（用于运行分类脚本）。

如果前提条件未满足，sf 会返回以下错误之一：

• 身份验证错误 / 401 Unauthorized → 会话已过期或别名错误；重新运行 sf org login web。
• 403 Forbidden → 用户/组织缺少所需访问权限（缺少 Agentforce 许可证）。
• 404 Not Found → 此组织层级未接入功能发现接口——分类器会将缺失/错误响应正文映射为 CANNOT-CONFIRM，而不是硬失败。

---

操作一览

操作	命令	返回值
读取功能开关	sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" --method POST --body '{"featureApiNames":[...]}' --target-org <alias>	{items:[{apiName,status,enableBlockedReasons[],dependencyStatuses[]}]} — 每个开关的 status 为 ENABLED / NOT_ENABLED。

此技能仅执行上述读取操作——它是只读的。启用开关（.../feature/{apiName}/enable）不在范围内：交由 service-itsm-agentic-setup-agentforce-studio-configure 处理。sf api request rest 会将原始响应正文（JSON）输出到 stdout——将其保存到文件并交给分类器。完整的命令格式和错误分类见 references/cli-invocation.md。

切勿提取访问令牌。 直接使用 sf api request rest——它会使用 CLI 中存储的目标组织会话。不要从 sf org display 中提取 accessToken，再用它手动构造 HTTP 请求；这样会绕过 CLI 会话，并将持有者令牌泄露到 shell 上下文中。

---

架构 — 检查的工作方式

步骤	操作	使用的工具
选择路径	确定是 fulfiller 还是 employee（不明确时询问）	AskUserQuestion
读取开关	为该路径所需的所有开关 POST 功能状态批量请求，并保存到文件	Bash（sf api request rest）
分类	运行 scripts/classify-readiness.mjs <file> <agentType> [exitStatus] → 各功能及总体判定	Bash（node）
报告	按输出格式呈现分类器的判定	—
交接	状态为 NOT-READY 时，列出每个已禁用的开关，并交由 service-itsm-agentic-setup-agentforce-studio-configure 启用	—

此技能为只读——绝不会启用开关。

---

工作流

将 <alias> 替换为目标组织别名（询问用户，或使用 sf config 中的默认组织）。<agentType> 为 fulfiller 或 employee。

阶段 1 — 读取功能开关

1. 针对所选路径所需的每个开关，POST 功能状态批量请求（也可以始终请求全部五个——分类器只会判定该路径所需的开关），并将 stdout 保存到文件。不要添加 --json：

   sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" \
     --method POST \
     --body '{"featureApiNames":["sales-cloud-agent-studio","service-cloud-agentforce-for-itsm","service-cloud-it-fulfiller-agent","service-cloud-requestor-agent","service-cloud-it-service-employee-agent"]}' \
     --target-org <alias> > /tmp/features-status.json 2>/tmp/features-status.err
   echo $? > /tmp/features-status.exit
   

   保存命令的退出状态（$?），以便分类器区分已确认的 404（接口未接入）与身份验证/权限/传输失败。不要使用 || true 吞掉退出状态——在阶段 2 中将其传递给分类器。

阶段 2 — 分类（辅助脚本）

2. 对捕获的文件、所选的 Agent 类型以及捕获的退出状态运行分类器。脚本路径必须使用该技能的绝对目录：

   node "<skill_dir>/scripts/classify-readiness.mjs" /tmp/features-status.json <agentType> "$(cat /tmp/features-status.exit)"
   

   它会输出 { agentType, readState, features, verdict, notEnabled, enableable, reasons, rawError }，其中每项功能的状态为 PASS | FAIL | CANNOT-CONFIRM | ERROR，verdict 的状态为 READY | NOT-READY | CANNOT-CONFIRM | ERROR。这是权威判定结果——不要在说明文字中根据原始响应重新推导。notEnabled 列出所有已禁用的必需开关；enableable 是其中没有 enableBlockedReasons 的子集——这些开关可由配置技能立即启用（其余开关则因未满足的依赖条件或购买／许可限制而受阻）。

阶段 3 — 报告并交接

3. 按照下方的输出格式呈现分类器结果。
   • READY → 引导用户使用 service-itsm-agentic-setup-fulfiller-agent-configure 创建 Agent（fulfiller 路径），或使用 service-itsm-agentic-setup-employee-agent-configure 创建 Agent（employee 路径）。
   • NOT-READY → 列出每个已禁用的开关（来自 notEnabled）。对于 enableable 子集，交接给 service-itsm-agentic-setup-agentforce-studio-configure，让其启用这些开关（通过 AskUserQuestion 询问："有 N 个前置开关处于关闭状态。要运行 service-itsm-agentic-setup-agentforce-studio-configure 启用它们吗？" → 选择 Yes 时委派；选择 No 时停止并报告）。对于已禁用但受阻的开关（在 notEnabled 中但不在 enableable 中），逐字报告其 enableBlockedReasons——在阻碍解除前无法启用。这项技能不会自行 POST 启用请求。
   • CANNOT-CONFIRM → 说明哪些开关没有状态，并指出此组织层级可能未接入功能发现接口。
   • ERROR → 读取失败（身份验证／权限／传输错误，或响应正文异常——参见 rawError）。呈现原始响应并停止；不要将其视为单纯的接口接入问题。

阶段 4 —（启用后）重新验证

4. 如果用户运行了 service-itsm-agentic-setup-agentforce-studio-configure 来启用开关，请在此处重新运行阶段 1 和阶段 2，确认判定结果已变为 READY，然后报告。此技能自身的职责始终仅限于读取。

规则 / 约束

约束	原因
此技能为只读——绝不会 POST 启用功能	开启开关属于另一个具备写入能力的技能（service-itsm-agentic-setup-agentforce-studio-configure）；将二者分开可确保 validate 动词名副其实，并避免两个技能负责同一项写入操作
如果状态为 NOT-READY，移交给 service-itsm-agentic-setup-agentforce-studio-configure 执行启用操作	该技能负责 .../feature/{apiName}/enable 写入路径（具备幂等性，并按依赖顺序执行）；此技能只指出哪些功能处于关闭状态
读取操作通过 sf api request rest 完成；绝不提取访问令牌，也不手动构造原始 HTTP 请求	sf api request rest 使用 CLI 为 --target-org 存储的会话；提取令牌会使承载令牌泄露到 shell 上下文中
分类逻辑位于 scripts/classify-readiness.mjs 中，并通过 Bash 调用——而非写在说明文字中	判定结果基于固定功能状态的确定性决策表；脚本可靠，而对说明文字的解读不可靠（编写标准 A9）
必需开关集合取决于 Agent 路径	Fulfiller 和 Employee Agent 受不同的模板开关控制；分类器同时编码了这两种路径
这些是 Connect API 功能——使用 SF CLI，而非 Headless360	存在 Connect/Tooling 等效方案，因此优先使用 SF CLI（避免受到 Headless360HostedMcpServer 组织权限门槛限制）
enableBlockedReasons 非空 ⇒ 开关不属于 enableable——报告阻止原因	在未满足的依赖项／购买门槛解除之前，即使是配置技能也无法开启被阻止的开关
不要向 sf api request rest 传递 --json	某些 Connect 端点不支持此参数；原始标准输出正文已经是 JSON

---

验证清单

• 已确定 Agent 路径（Fulfiller / Employee）；如果不明确，已询问。
• 已通过 sf api request rest 执行功能状态 POST 请求，并将其正文捕获到文件中。
• 已使用该文件、Agent 类型，以及捕获的退出状态调用 scripts/classify-readiness.mjs，并记录其 {verdict, notEnabled, enableable, rawError} 输出。
• 已原样报告分类器给出的判定结果（READY / NOT-READY / CANNOT-CONFIRM / ERROR）；若为 NOT-READY，已指出每个关闭的开关，仅对 enableable 子集提供启用路由，并报告其余开关的 enableBlockedReasons；若为 ERROR，已展示原始响应并停止此技能。
• 此技能未启用任何功能（它是只读的）；若为 NOT-READY，已指出关闭的开关并提出移交给 service-itsm-agentic-setup-agentforce-studio-configure，且从未提取访问令牌。

---

输出格式

按以下格式呈现就绪情况报告：

Agentforce for IT Service — Prerequisite Check (via service-itsm-agentic-setup-agentforce-studio-validate)

Org:          <org-alias> (API v67.0)
Agent path:   fulfiller | employee

  [PASS|FAIL] Agentforce Studio ......................... ENABLED | NOT_ENABLED (sales-cloud-agent-studio)
  [PASS|FAIL] Agentforce for IT Service ................. ENABLED | NOT_ENABLED (service-cloud-agentforce-for-itsm)
  [PASS|FAIL] <path-specific toggle(s)> ................. ENABLED | NOT_ENABLED (<featureApiName>)

Verdict: READY  |  NOT-READY  |  CANNOT-CONFIRM  |  ERROR

Next steps:
  - <If READY: "Org satisfies the prerequisites for the <path> agent. Create it via service-itsm-agentic-setup-fulfiller-agent-configure (fulfiller) / the employee-agent skill.">
  - <If NOT-READY: list each disabled toggle; for the enableable ones, hand off to service-itsm-agentic-setup-agentforce-studio-configure to turn them on; for blocked ones, report the enableBlockedReasons.>
  - <If CANNOT-CONFIRM: state which toggle(s) returned no status and that the feature-discovery surface may not be wired on this org.>

此技能为只读 — 不会写入任何组织状态。它生成的唯一文件是交给分类器的临时响应捕获文件。

每个切换项都使用其报告标签原文 — Agentforce Studio、Agentforce for IT Service、IT Service Fulfiller Template、IT Service Employee Template 和 Specialized Agent Templates for Employee — 在此技能与 service-itsm-agentic-setup-agentforce-studio-configure 中保持一致。（在上方的切换项表格中，Studio 行的 Go 页面切换项显示为“Turn on Agentforce Studio”；其呈现的报告标签则仅为 Agentforce Studio。）两个 Agent 模板切换项标签中的 Template 后缀是有意采用且具权威性的报告标签 — 它有意区别于设置页面上较短的切换项说明（IT Service Fulfiller / IT Service Employee），与上方的 Studio 行完全相同；安装的 Agent 则由 agent-configure 技能单独命名（IT Service Fulfiller Agent / IT Service Employee Agent，不带 Template）。特定路径的行分别为 IT Service Fulfiller Template（fulfiller 路径），或 IT Service Employee Template 和 Specialized Agent Templates for Employee（employee 路径）。切勿在标签中添加诸如“Requestor”、“Specialized”或“parent”这样的虚构角色限定词。

---

参考文件索引

文件	何时阅读
references/cli-invocation.md	每个阶段 — 精确的 sf api request rest 读取调用格式、功能状态路由、只读 / 移交规则、绝不提取令牌的规则、分类器契约以及错误分类