service-itsm-agentic-setup-cmdb-discovery-configure

启用 CMDB 资产发现（Service Cloud ITSM）

通过启用 service-cloud-itsm-discovery-integration 功能，为 CMDB 启用 资产发现；然后通过分配 IT Service Discovery Manager 权限集（及其权限集许可证），授予用户访问 Discovery 页面的权限。这是 CMDB 设置的最后一层——只有在启用基础 CMDB 功能、用户已拥有 CMDB 访问权限且已安装 CMDB Foundation 内容包之后才运行。每次调用都会通过 Salesforce 托管的 Headless-360 MCP 服务 （服务键 headless-360）及其四个元工具（discover、describe、dispatch_readonly、 dispatch）执行。组织信息取自绑定到当前 MCP 会话的 OAuth JWT——此技能不会处理组织 ID、别名或凭据——因此在生产环境和沙盒中的运行方式完全相同，无需为每位用户单独安装 MCP。

此技能仅涵盖 Discovery 层——启用该功能，并授予用户 Discovery 页面访问权限。更早的 CMDB 层由单独的技能负责——请参阅本文件末尾。

在 CMDB 堆栈中的位置

CMDB 按顺序分层启用，每一层都以前一层为前提：

Layer 0  Org SKU / license      Org perm ITSrvcsCnfgMgmnt (verify only — no API can set it).
Layer 1  Tenant provisioning    CMDB tenant must reach status PROVISIONED (async).
Layer 2  CMDB feature           Enable service-cloud-itsm-cmdb-integration (lifts the 403 gate).
Layer 3  User access            Assign the PSL + CMDB permission sets to the user(s).
Layer 4  Content bundle         Install the CMDB Foundation (base) content bundle.
Layer 5  Asset Discovery        Enable service-cloud-itsm-discovery-integration + assign the
                                IT Service Discovery Manager permission set  ← THIS SKILL

建议最后启用 Discovery，但不要求事先启用基础 CMDB 功能：启用 Discovery 时会级联启用其依赖项（基础 CMDB 功能），前提是该功能本身的前置条件（例如，已配置 CMDB 租户）已满足。预检查中的 enableBlockedReasons 数组是判断阻塞情况的权威信号——仅处于 NOT_ENABLED 状态的基础 CMDB 功能会出现在 dependencyStatuses 中，其 enableBlockedReasons 为空，因此不构成阻塞。所以，绝不要告诉用户直接启用“会报错”；应告诉他们系统会先启用 CMDB，再启用 Discovery。只有非空的 enableBlockedReasons（例如，尚未配置租户）才表示确实存在未满足的前置条件，会阻止启用。

启用该功能会解除组织级限制；Discovery 权限集则会授予用户 Discovery 页面访问权限。 此技能会同时执行这两项操作：为组织启用 Discovery（步骤 2），然后为目标用户分配受许可证支持的 ItSrvcDscvrMgrPermissionSet（“IT Service Discovery Manager”，由 PSL ItSrvcDscvrMgrPsl 支持），使其能够实际打开和使用 Discovery 页面（步骤 4–7）。该权限集与 service-itsm-agentic-setup-cmdb-access-assign 为 CMDB 数据访问分配的四个 Configuration-Item 权限集（Reader / Owner / Type Reader / Type Manager）不同——仅持有这些权限集的用户无法访问 Discovery 页面。分配步骤具有幂等性：如果用户已经拥有 Discovery 权限集及其许可证，则会跳过分配，并报告为已完成。

范围

• 范围内：预检查、启用和验证 service-cloud-itsm-discovery-integration 功能；并在后续步骤中，为目标用户分配 IT Service Discovery Manager 权限集（及其权限集许可证），使其能够访问 Discovery 页面。
• 范围外：启用基础 CMDB 功能／配置 CMDB 租户（第 2 层—— service-itsm-agentic-setup-cmdb-configure）、分配用于 CMDB 数据访问的四个 Configuration-Item 权限集（第 3 层——service-itsm-agentic-setup-cmdb-access-assign）、安装内容包（第 4 层——service-itsm-agentic-setup-cmdb-bundle-deploy）、CMDB 记录 CRUD、Service Graph Connector 配置、识别规则、创建或编辑权限集。

机制

所有操作都通过 headless-360 MCP 工具分发。读取操作使用 mcp__headless-360__dispatch_readonly，写入操作使用 mcp__headless-360__dispatch——两者都接收原始 HTTP：{"url": "<path>", "method": "GET|POST", "body"?: {...}, "queryParams"?: {...}}——而不是 {operation_id, arguments}。每次调用的确切 url / method / body 请参阅 references/mcp-invocation.md。这四个工具：

• mcp__headless-360__discover — 对已编入索引的操作目录进行语义搜索。本技能使用的 Setup/Connect 路由以及 /query / /sobjects/... REST 路由不一定总是排名靠前（或已编入索引），因此搜索未命中不 代表路由不存在——请直接分发确切路径（参见 references/mcp-invocation.md）。
• mcp__headless-360__describe — 在任何 POST 之前获取完整的输入架构和规范路由。
• mcp__headless-360__dispatch_readonly — 用于所有读取操作（GET）的分发器。
• mcp__headless-360__dispatch — 用于所有写入操作（POST/PATCH）的分发器。

本技能不会处理凭据——组织绑定到当前 OAuth 会话。如果 dispatch* 调用返回身份验证错误，请告知用户重新进行 headless-360 MCP 连接身份验证（并确认会话指向预期的组织），然后停止。

Discovery 权限集

角色	权限集（Name）	后备 PSL（DeveloperName）	授予权限
Discovery Manager	ItSrvcDscvrMgrPermissionSet	ItSrvcDscvrMgrPsl	打开并使用 Discovery 页面

请在运行时（步骤 5）解析权限集的 Id 和其 LicenseId，不要硬编码 ID—— 不同组织的 ID 不同。

---

澄清问题

仅询问无法从对话中推断的信息：

• 使用哪个组织？ 确认目标组织，并明确说明将修改此组织（启用 Discovery 功能属于写入操作）。对于生产环境，请获取明确确认。
• 为哪位用户授予 Discovery 页面访问权限？ 即要分配 IT Service Discovery Manager 角色的用户。 如果请求是“为我启用 Discovery”/“设置 Discovery”，则默认使用当前（正在运行的） 用户。也可以接受其他用户的用户名/电子邮件地址。

不要重复询问用户已经提供的信息；预先填入并注明“（来自对话）”。

---

工作流

所有步骤都按顺序执行并设有检查关卡——检查失败时不得继续。 始终先读后写：启用前运行只读预检查，分配前运行检查。

步骤 1 — 预检查 Discovery 功能状态（读取）

功能 API 名称为 service-cloud-itsm-discovery-integration。

dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-discovery-integration/status", "method": "GET" })

• status == ENABLED → 功能已启用；跳到验证（步骤 3），然后继续后续的访问权限步骤（步骤 4–7）。
• status == NOT_ENABLED 且 enableBlockedReasons: [] → 可以启用（步骤 2）。确认前，请检查 dependencyStatuses：如果其中列出的基础 CMDB 功能 （service-cloud-itsm-cmdb-integration）状态为 NOT_ENABLED，这不构成阻碍——启用 Discovery 会先级联启用基础 CMDB 功能，然后再启用 Discovery。请明确告知用户这一点（“这会先启用 CMDB，然后启用 Asset Discovery”）。不要警告用户“这会报错”，也不要提出“让它报告依赖项错误”——这两种情况都不会发生。
• enableBlockedReasons 不为空 → 停止，并用通俗语言向用户说明每一项原因。这些是真正尚未满足的前置条件，组织仍需处理（例如，尚未预配 CMDB 租户，因此无法启用基础功能）。请引导用户使用之前的 CMDB 设置技能（参见“常见故障”），并且不要尝试启用。
• 此 GET 返回 403 FUNCTIONALITY_NOT_ENABLED → 基础 CMDB 门控仍处于关闭状态；组织需要先完成 service-itsm-agentic-setup-cmdb-configure。停止并引导用户前往该技能。

第 2 步 — 启用 Asset Discovery（写入 — 先向用户确认）

如果第 1 步已报告 ENABLED，则跳过此步骤。

dispatch({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-discovery-integration/enable", "method": "POST", "body": {} })
→ {"success": true}

第 3 步 — 验证功能（读取 — 不要仅凭 POST 响应判断）

dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-discovery-integration/status", "method": "GET" })
→ expect status == ENABLED

status == ENABLED 是确认功能已开启的最终依据。 确认后，继续执行下方的访问权限后续步骤——功能开启本身并不会自动授予任何用户 Discovery 页面访问权限。

第 4 步 — 确定目标用户（读取）

对于“当前用户”/“我”/“设置 discovery”（不要使用 USER_ID()——仅限 Apex 使用，REST 查询 API 会拒绝；也不要依赖 /chatter/users/me 或 /connect/user-profiles/me——当 Chatter/Communities 关闭时，它们会返回 403）。读取 API 根路径并解析身份 URL：

dispatch_readonly({ "url": "/services/data/v67.0/", "method": "GET" })

响应中的 identity 字段是一个以 /<orgId>/<userId> 结尾的 URL（用户 Id 是最后一个路径段，并以 005 开头）。直接使用该 Id，或通过 User 查询确认。

对于指定用户（提供了用户名/电子邮件）：

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" } })

• 恰好有一个活跃用户 → 记录其 Id。
• 无结果 → 停止；请用户确认用户名。
• 多于一个结果 → 停止；列出候选用户（Name + Username），并询问用户选择哪一个。

第 5 步 — 确定 Discovery 权限集并检查现有分配（读取 — 幂等性）

确定权限集及其关联许可证：

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id, Name, LicenseId FROM PermissionSet WHERE Name = 'ItSrvcDscvrMgrPermissionSet'" } })

记录 Id（权限集）和 LicenseId（要分配的 PSL）。totalSize == 0 表示该组织未获 Discovery 许可——停止并报告。然后检查用户是否已同时拥有二者：

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetId = '<psId>'" } })
dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId = '<userId>' AND PermissionSetLicenseId = '<pslId>'" } })

如果二者都已存在，则该角色已分配——跳过第 6 步，并记录为已完成。

第 6 步 — 分配许可证，然后分配权限集（写入 — 先确认）

跳过第 5 步显示已分配的项目。先分配 PSL，然后分配权限集：

dispatch({ "url": "/services/data/v67.0/sobjects/PermissionSetLicenseAssign", "method": "POST", "body": { "AssigneeId": "<userId>", "PermissionSetLicenseId": "<pslId>" } })
dispatch({ "url": "/services/data/v67.0/sobjects/PermissionSetAssignment", "method": "POST", "body": { "AssigneeId": "<userId>", "PermissionSetId": "<psId>" } })

• 201 → 已分配。
• 400 DUPLICATE_VALUE → 用户已拥有该项；视为成功（幂等），而非失败。
• 达到许可证上限/无可用席位错误 → 停止分配；告知用户 Discovery 许可证没有可用席位（席位查询见 references/mcp-invocation.md）。不要重试。

第 7 步 — 验证分配（读取 — 不要仅凭 POST 响应判断）

重新运行第 5 步中的两条分配查询。只有当 PermissionSetAssignment 和 PermissionSetLicenseAssign 都返回 totalSize == 1 时，用户才拥有 Discovery 页面访问权限。

---

规则 / 约束

约束	原因
建议在启用基础 CMDB 功能后运行，但并非必需	Discovery 依赖基础 CMDB 功能，但只有在其状态为 NOT_ENABLED（enableBlockedReasons 为空）时，启用操作才会级联启用该功能；请说明这是级联启用，切勿声称直接启用“会报错”。真正决定能否启用的是预检查中的 enableBlockedReasons
启用前读取预检查结果；启用后通过读取进行验证	该功能具有状态；POST 响应可能滞后于实际状态
enableBlockedReasons 非空时，不要尝试启用	这些是尚未满足的前提条件——请告知用户这些条件，并引导其查看之前的 CMDB 技能
启用后务必分配 Discovery-Manager	功能启用后，并不会自动向任何用户授予 Discovery 页面访问权限；授予页面访问权限的是权限集
分配前，先将用户精确匹配到一条记录	分配给错误或不明确的用户很难撤销，并且存在安全风险
分配前读取现有分配；先分配 PSL，再分配权限集	权限集由许可证支持，且按用户分配——重复分配会触发 DUPLICATE_VALUE；必须先持有许可证席位，分配才能生效
将 DUPLICATE_VALUE 视为成功	这表示用户已经拥有相应访问权限——操作具有幂等性，并非错误
切勿创建或编辑权限集	此技能仅分配标准 Discovery 权限集
每次写入前，均须与用户确认目标组织、用户及写入内容	这些是在正式组织中进行的真实变更，且很难撤销
切勿向用户透露内部术语	不要在面向用户的输出中使用记录 ID、组织 ID、HTTP 状态码（403/500/…）、API 错误代码（FUNCTIONALITY_NOT_ENABLED、DUPLICATE_VALUE、…）、对象名称（PermissionSetLicenseAssign）、端点名称、功能 API 名称（service-cloud-itsm-discovery-integration）、开发者名称（ItSrvcsCnfgMgmnt、ItSrvcDscvrMgrPsl、…）以及工具内部术语（dispatch、headless-360）。请用通俗易懂的语言表达，并使用用户熟悉的名称和状态

---

验证清单

• 步骤 1：启用前的预检查是否显示 enableBlockedReasons: []（或状态是否已经是 ENABLED）？
• 步骤 2：启用操作是否返回 success: true（或因功能已启用而跳过）？
• 步骤 3：验证 GET 是否显示 status == ENABLED？
• 步骤 4：目标用户是否已精确匹配到一条记录？
• 步骤 5：是否已找到 Discovery 权限集和许可证，并检查现有分配（确保幂等性）？
• 步骤 6：目标用户是否已分配权限集及其许可证（或原本就已分配）？
• 步骤 7：是否通过写入后的读取确认分配结果（而非仅依赖 POST 响应）？
• 是否已事先与用户确认目标组织、用户及每次写入？

---

输出要求

CMDB Asset Discovery — Complete (via service-itsm-agentic-setup-cmdb-discovery-configure)

Target org: <org>
User: <name> (<username>)

  Asset Discovery ................... Enabled
  IT Service Discovery Manager ...... Assigned    (or: Already had access)

Asset Discovery is now enabled on this org and the user above can open and use the
Discovery page. This completes CMDB setup — the base feature, user access, content
bundle, and discovery are all in place.

To give additional users the Discovery page, re-run this and name each user (or use
service-itsm-agentic-setup-cmdb-access-assign for the underlying CMDB data roles).

请勿在面向用户的输出中使用内部术语（不得包含记录 ID、HTTP 状态码、错误代码、对象名称、端点名称或开发者名称）——请说“IT Service Discovery Manager 访问权限”，而不要使用开发者名称。如果任何步骤失败，请停止并用通俗易懂的语言告诉用户哪一步未成功以及这对他们意味着什么，然后指出相应的解决方法。请将任何原始错误（例如 403 或 FUNCTIONALITY_NOT_ENABLED）转换为其实际含义（例如“CMDB 尚未完成设置”），而不是照搬错误代码。

---

常见故障（以通俗语言说明）

症状	可能原因	告知用户的内容
预检查的 enableBlockedReasons 非空	确实未满足更深层的前置条件（例如，尚未配置 CMDB 租户——请注意，仅处于 NOT_ENABLED 状态的基础 CMDB 功能不会填入此数组；它会级联启用）	转达每条原因；先完成 CMDB 设置——运行 service-itsm-agentic-setup-cmdb-configure（配置租户并启用基础功能），然后运行 -access-assign（用户访问权限）和 -bundle-deploy（内容包），再重试发现
发现启用前，基础 CMDB 功能处于 NOT_ENABLED 状态；启用发现后，它也随之开启	符合预期——启用发现会级联启用其基础 CMDB 依赖项；这不是故障	启用前先告知用户：此操作会先开启 CMDB，再开启 Discovery；切勿警告用户“操作会报错”
状态 GET 返回 403 FUNCTIONALITY_NOT_ENABLED	基础 CMDB 闸门仍关闭（CMDB 功能未启用）	这不是发现故障——先使用 service-itsm-agentic-setup-cmdb-configure 启用基础 CMDB 功能，然后重试
部分设置后启用受阻（enableBlockedReasons 非空）	组织仍缺少所需依赖项	转达每条原因；解决这些前置条件，然后重试
启用返回成功，但验证 GET 的状态不是 ENABLED	状态延迟或下游问题	稍等片刻后重新运行验证 GET；如果问题仍然存在，则视为未启用并进行调查
针对 ItSrvcDscvrMgrPermissionSet 的 PermissionSet 查询结果 totalSize == 0	组织未获得 Discovery 许可	此组织无法使用 Discovery；确认该组织已获得许可
分配时返回 400 DUPLICATE_VALUE	用户已拥有 Discovery 页面访问权限	这不是错误——报告该角色已分配
分配时出现许可证数量限制／无可用席位错误	Discovery 权限集许可证席位已用尽	报告已用与可用席位数量；分配前必须释放一个席位（或添加更多许可证）
Discovery 处于 ENABLED 状态且功能已开启，但用户仍无法打开 Discovery 页面	从未向该用户分配 Discovery 权限集（ItSrvcDscvrMgrPermissionSet / PSL ItSrvcDscvrMgrPsl）	针对该用户重新运行此技能（步骤 4–7），授予“IT Service Discovery Manager”访问权限
dispatch* 身份验证错误	headless-360 MCP 会话未通过身份验证／令牌已过期	重新验证 headless-360 MCP 连接，并确认会话指向预期的组织

---

跨技能集成

何时	技能
预检查报告了真实阻碍项（enableBlockedReasons 非空——例如，尚未配置 CMDB 租户）	service-itsm-agentic-setup-cmdb-configure（第 0–2 层——配置租户并启用基础功能，然后返回此处）。仅处于 NOT_ENABLED 状态的基础功能不是阻碍项——Discovery 会级联启用它
用户需要底层 CMDB 数据角色（Configuration Item Reader / Owner / Type Reader / Type Manager）	service-itsm-agentic-setup-cmdb-access-assign（第 3 层——CMDB 数据访问权限，与 Discovery 页面访问权限不同）

---

参考文件索引

文件	阅读时机
references/mcp-invocation.md	预检查、启用、验证、用户解析和 Discovery-Manager 分配调用所需的确切 dispatch* URL／方法／正文、响应封装、许可证席位查询和错误表