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

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enable CMDB Asset Discovery (Service Cloud ITSM)

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

Turns on Asset Discovery for CMDB by enabling the

service-cloud-itsm-discovery-integration

feature, then grants a user access to the Discovery page by assigning the IT Service Discovery Manager permission set (and its permission-set license). This is the final layer of CMDB setup — it runs only after the base CMDB feature is enabled, users have CMDB access, and the CMDB Foundation content bundle is installed. Every call runs through the Salesforce-hosted Headless-360 MCP server (server key

headless-360

) via its four meta-tools (

discover

describe

dispatch_readonly

dispatch

). The org is derived from the OAuth JWT bound to the current MCP session — the skill never handles an org id, alias, or credentials — so this works identically against production and sandbox with no per-user MCP install.

This skill covers the Discovery layer only — enabling the feature and granting Discovery page access to a user. The earlier CMDB layers are separate skills — see the end of this file.

通过启用

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页面访问权限。CMDB设置的早期环节由其他独立技能负责——详见本文档末尾。

Where this sits in the CMDB stack

在CMDB架构中的定位

CMDB is enabled in ordered layers, each gated on the prior one:

text

Layer 0  Org SKU / license      Org perm ITSrvcsCnfgMgmnt (verify only — no API can set it).
Layer 1  Tenant provisioning    ITOM 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 is enabled last: it builds on the base CMDB feature and depends on the earlier layers being complete. The pre-check step below (

enableBlockedReasons

) is the authoritative signal that the prerequisites are met — if the base CMDB feature is not yet enabled, discovery cannot be enabled and the org reports a blocking reason rather than turning it on.

Enabling the feature lifts the org-level gate; the Discovery permission set gives a user the Discovery page. This skill does both: it turns Discovery on for the org (Step 2) and then assigns the target user the license-backed ItSrvcDscvrMgrPermissionSet
("IT Service Discovery Manager", backed by PSL ItSrvcDscvrMgrPsl
) so they can actually open and use the Discovery page (Steps 4–7). That permission set is distinct from the four Configuration-Item permission sets (Reader / Owner / Type Reader / Type Manager) that
service-itsm-agentic-setup-cmdb-access-assign
assigns for CMDB data — a user holding only those will not have Discovery page access. The assignment step is idempotent: if the user already holds the Discovery permission set and its license, it is skipped and reported as already-done.

CMDB需按顺序分层启用，每一层都依赖于前一层完成：

text

Layer 0  组织SKU/许可证      组织权限ITSrvcsCnfgMgmnt（仅验证——无API可设置）。
Layer 1  租户配置        ITOM租户必须达到PROVISIONED状态（异步）。
Layer 2  CMDB功能           启用service-cloud-itsm-cmdb-integration（解除403限制）。
Layer 3  用户访问权限            为用户分配PSL+CMDB权限集。
Layer 4  内容包         安装CMDB Foundation（基础）内容包。
Layer 5  资产发现        启用service-cloud-itsm-discovery-integration + 分配
                                IT Service Discovery Manager权限集  ← 本技能

发现功能最后启用：它基于基础CMDB功能构建，依赖于所有早期环节完成。下方的预检查步骤（

enableBlockedReasons

）是验证先决条件是否满足的权威信号——如果基础CMDB功能尚未启用，则无法启用发现功能，组织会返回阻止原因而非直接开启。

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

Scope

范围

In scope: pre-checking, enabling, and verifying the
```
service-cloud-itsm-discovery-integration
```
feature; and — as a follow-up — assigning the IT Service Discovery Manager permission set (and its permission-set license) to the target user so they can access the Discovery page.
Out of scope: enabling the base CMDB feature / provisioning the tenant (Layer 2 —
```
service-itsm-agentic-setup-cmdb-configure
```
), assigning the four Configuration-Item permission sets for CMDB data access (Layer 3 —
```
service-itsm-agentic-setup-cmdb-access-assign
```
), bundle installation (Layer 4 —
```
service-itsm-agentic-setup-cmdb-bundle-deploy
```
), CMDB record CRUD, Service Graph Connector configuration, identification rules, creating or editing permission sets.

包含范围：预检查、启用和验证
```
service-cloud-itsm-discovery-integration
```
功能；以及后续为目标用户分配IT Service Discovery Manager权限集（及其权限集许可证），使其能够访问Discovery页面。
排除范围：启用基础CMDB功能/配置租户（第2层——
```
service-itsm-agentic-setup-cmdb-configure
```
）、为CMDB数据访问分配四个配置项权限集（第3层——
```
service-itsm-agentic-setup-cmdb-access-assign
```
）、安装内容包（第4层——
```
service-itsm-agentic-setup-cmdb-bundle-deploy
```
）、CMDB记录增删改查、Service Graph Connector配置、识别规则、创建或编辑权限集。

Mechanism

实现机制

All operations dispatch through headless-360 MCP tools. Reads go through

mcp__headless-360__dispatch_readonly

, writes through

mcp__headless-360__dispatch

— both take raw HTTP:

{"url": "<path>", "method": "GET|POST", "body"?: {...}, "queryParams"?: {...}}

— not

{operation_id, arguments}

. See

references/mcp-invocation.md

for the exact

url

method

body

of every call. The four tools:

```
mcp__headless-360__discover
```
— semantic search over the indexed operation catalog. The Setup/Connect routes and the
```
/query
```
/
```
/sobjects/...
```
REST routes this skill uses are not always ranked first (or indexed), so a miss does not mean the route is absent — dispatch the exact path directly (see
```
references/mcp-invocation.md
```
).
```
mcp__headless-360__describe
```
— pull the full input schema and canonical route before any POST.
```
mcp__headless-360__dispatch_readonly
```
— the dispatcher for every read (GET).
```
mcp__headless-360__dispatch
```
— the dispatcher for every write (POST/PATCH).

The skill never handles credentials — the org is bound to the current OAuth session. If a

dispatch*

call returns an auth error, tell the user to re-authenticate the headless-360 MCP connection (and confirm the session points at the intended org), then stop.

所有操作均通过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连接（并确认会话指向目标组织），然后停止操作。

The Discovery permission set

Discovery权限集

Role	Permission set ( `Name` )	Backing PSL ( `DeveloperName` )	Grants
Discovery Manager	`ItSrvcDscvrMgrPermissionSet`	`ItSrvcDscvrMgrPsl`	Open and use the Discovery page

Resolve the permission set's

Id

and its

LicenseId

at runtime (Step 5) rather than hardcoding IDs — IDs differ per org.

角色	权限集（ `Name` ）	支持的PSL（ `DeveloperName` ）	权限
Discovery Manager	`ItSrvcDscvrMgrPermissionSet`	`ItSrvcDscvrMgrPsl`	打开并使用Discovery页面

需在运行时解析权限集的

Id

及其

LicenseId

（步骤5），而非硬编码ID——不同组织的ID不同。

Clarifying questions

澄清问题

Ask only what you cannot infer from conversation:

Which org? Confirm the target org and state plainly that this org will be modified (enabling the discovery feature is a write). For production, get explicit confirmation.
Which user gets Discovery page access? The user to assign the IT Service Discovery Manager role. If the request is "enable discovery for me" / "set up discovery", default to the current (running) user. Accept a username/email for someone else.

Do not re-ask for anything the user already provided; pre-populate and note "(from conversation)".

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

目标组织是哪个？确认目标组织，并明确告知用户该组织将被修改（启用发现功能属于写入操作）。对于生产环境，需获取用户的明确确认。
哪个用户将获得Discovery页面访问权限？需分配IT Service Discovery Manager角色的用户。如果用户请求“为我启用发现”/“设置发现”，默认选择当前（执行操作的）用户。也支持为其他用户分配，需提供用户名/邮箱。

请勿重复询问用户已提供的信息；可预先填充并标注“（来自对话）”。

Workflow

工作流程

All steps are sequential and gated — do not advance past a failed check. Always read before you write: run the read-only pre-check before the enable, and the assignment checks before the assign.

所有步骤按顺序执行且相互依赖——检查失败后请勿继续后续步骤。始终先读取再写入：启用前运行只读预检查，分配前运行分配检查。

Step 1 — Pre-check discovery feature status (read)

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

The feature api name is

service-cloud-itsm-discovery-integration

text

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

```
status == ENABLED
```
→ feature already on; skip to verification (Step 3), then proceed to the access follow-up (Steps 4–7).

status == NOT_ENABLED

with

enableBlockedReasons: []

→ clear to enable (Step 2).

```
enableBlockedReasons
```
non-empty → STOP and relay each reason to the user in plain language. These are prerequisites the org still needs — most commonly the base CMDB feature is not yet enabled. Point the user to the earlier CMDB setup skills (see "Common failures") and do not attempt the enable.
```
403 FUNCTIONALITY_NOT_ENABLED
```
on this GET → the base CMDB gate itself is still closed; the org needs
```
service-itsm-agentic-setup-cmdb-configure
```
first. Stop and route the user there.

功能API名称为

service-cloud-itsm-discovery-integration

。

text

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）。

```
enableBlockedReasons
```
非空 → 停止并以通俗易懂的语言向用户传达每个原因。这些是组织尚未满足的先决条件——最常见的情况是基础CMDB功能尚未启用。引导用户使用早期CMDB设置技能（详见“常见故障”），请勿尝试启用。
此GET请求返回
```
403 FUNCTIONALITY_NOT_ENABLED
```
→ 基础CMDB限制仍未解除；组织需先执行
```
service-itsm-agentic-setup-cmdb-configure
```
。停止操作并引导用户至该技能。

Step 2 — Enable Asset Discovery (write — confirm with the user first)

步骤2 — 启用资产发现（写入——需先获得用户确认）

Skip this step if Step 1 already reported

ENABLED

text

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

如果步骤1已报告

ENABLED

，则跳过此步骤。

text

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

Step 3 — Verify the feature (read — do NOT trust the POST response alone)

步骤3 — 验证功能状态（读取——请勿仅依赖POST响应）

text

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

status == ENABLED
is the definitive confirmation that the feature is on. Once confirmed, continue to the access follow-up below — the feature being on does not by itself give any user the Discovery page.

text

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

status == ENABLED

是功能已开启的最终确认。**确认后，继续执行下方的访问权限分配步骤——功能开启本身不会为任何用户授予Discovery页面访问权限。

Step 4 — Resolve the target user (read)

步骤4 — 解析目标用户（读取）

For "the current user" / "me" / "set up discovery" (do NOT use

USER_ID()

— Apex-only, rejected by the REST query API; do NOT rely on

/chatter/users/me

/connect/user-profiles/me

— they

when Chatter/Communities are off). Read the API root and parse the identity URL:

text

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

The response

identity

field is a URL ending in

/<orgId>/<userId>

(the user Id is the last path segment and starts with

). Use that Id directly, or confirm it with a

User

query.

For a named user (username / email supplied):

text

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

Exactly one active user → capture the
```
Id
```
.
Zero results → STOP; ask the user to confirm the username.
More than one → STOP; list the candidates (Name + Username) and ask which one.

对于“当前用户”/“我”/“设置发现”请求（请勿使用

USER_ID()

——仅适用于Apex，会被REST查询API拒绝；请勿依赖

/chatter/users/me

或

/connect/user-profiles/me

——当Chatter/Communities关闭时会返回

）。读取API根目录并解析身份URL：

text

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

响应的

identity

字段是一个以

/<orgId>/<userId>

结尾的URL（用户ID是最后一个路径段，以

开头）。直接使用该ID，或通过

User

查询进行确认。

对于指定用户（提供了用户名/邮箱）：

text

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

恰好找到一个活跃用户 → 记录
```
Id
```
。
无结果 → 停止操作；请用户确认用户名。
找到多个用户 → 停止操作；列出候选用户（姓名+用户名）并询问用户选择哪一个。

Step 5 — Resolve the Discovery permission set + check existing assignment (read — idempotency)

步骤5 — 解析Discovery权限集 + 检查现有分配情况（读取——幂等性）

Resolve the permission set and its backing license:

text

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

Capture

Id

(the permission set) and

LicenseId

(the PSL to assign).

totalSize == 0

means the org is not licensed for Discovery — stop and report. Then check whether the user already has both:

text

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>'" } })

If both already exist, the role is already assigned — skip Step 6 and record it as already-done.

解析权限集及其支持的许可证：

text

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许可——停止操作并告知用户。然后检查用户是否已同时拥有两者：

text

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并标记为已完成。

Step 6 — Assign the license, then the permission set (write — confirm first)

步骤6 — 分配许可证，然后分配权限集（写入——需先获得用户确认）

Skip whatever Step 5 shows already assigned. Assign the PSL first, then the permission set:

text

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
```
→ assigned.
```
400 DUPLICATE_VALUE
```
→ the user already had it; treat as success (idempotent), not a failure.
A license-limit / no-seats error → STOP for the assignment; tell the user the Discovery license has no available seats (see
```
references/mcp-invocation.md
```
for the seat query). Do not retry.

跳过步骤5中显示已分配的项。先分配PSL**，再分配权限集：

text

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
```
）。请勿重试。

Step 7 — Verify the assignment (read — do NOT trust the POST response alone)

步骤7 — 验证分配结果（读取——请勿仅依赖POST响应）

Re-run the two Step 5 assignment queries. The user has Discovery page access only when both the

PermissionSetAssignment

and the

PermissionSetLicenseAssign

return

totalSize == 1

重新运行步骤5中的两个分配查询。只有当**

PermissionSetAssignment

和

PermissionSetLicenseAssign

均返回

totalSize == 1

**时，用户才拥有Discovery页面访问权限。

Rules / Constraints

规则/约束

Constraint	Rationale
Run only after the base CMDB feature is enabled	Discovery is the final layer and depends on Layers 0–4; the pre-check `enableBlockedReasons` enforces this
Read the pre-check before enabling; verify with a read after enabling	The feature is stateful; the POST response can lag the real state
Do not attempt the enable when `enableBlockedReasons` is non-empty	Those are unmet prerequisites — relay them and route the user to the earlier CMDB skills
Always follow the enable with the Discovery-Manager assignment	The feature being on does not give any user the Discovery page; the permission set is what grants page access
Resolve the user to exactly one record before assigning	Assigning to the wrong (or an ambiguous) user is hard to reverse and a security concern
Read existing assignments before assigning; assign the PSL before the permission set	The permission set is license-backed and per-user — re-assigning throws `DUPLICATE_VALUE` ; the license seat must be held for the assignment to stick
Treat `DUPLICATE_VALUE` as success	It means the user already has that access — idempotent, not an error
Never create or edit permission sets	This skill only assigns the standard Discovery permission set
Confirm the target org, user, and each write with the user	These are real, hard-to-reverse changes on a live org
Never expose internal jargon to the user	Keep record IDs, org IDs, HTTP status codes (403/500/…), API error codes ( `FUNCTIONALITY_NOT_ENABLED` , `DUPLICATE_VALUE` , …), object names ( `PermissionSetLicenseAssign` ), endpoint names, feature api names ( `service-cloud-itsm-discovery-integration` ), developer names ( `ItSrvcsCnfgMgmnt` , `ItSrvcDscvrMgrPsl` , …), and tooling internals ( `dispatch` , `headless-360` ) out of user-facing output. Translate to plain language; use human-readable names and statuses

约束	理由
仅在基础CMDB功能启用后运行	发现功能是最后一层，依赖于第0–4层；预检查 `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` ）排除在用户可见输出之外。转换为通俗易懂的语言；使用易读的名称和状态

Verification checklist

验证清单

Step 1: pre-check showed
```
enableBlockedReasons: []
```
before enabling (or
```
status == ENABLED
```
already)?
Step 2: enable returned
```
success: true
```
(or skipped because already enabled)?
Step 3: verification GET shows
```
status == ENABLED
```
?
Step 4: target user resolved to exactly one record?
Step 5: Discovery permission set + license resolved; existing assignment checked (idempotency)?
Step 6: for the target user, both the permission set and its license are assigned (or already were)?
Step 7: assignment confirmed by a post-write read (not the POST response alone)?
Confirmed the target org, user, and each write with the user first?

步骤1：启用前预检查显示
```
enableBlockedReasons: []
```
（或已显示
```
status == ENABLED
```
）？
步骤2：启用操作返回
```
success: true
```
（或因已启用而跳过）？
步骤3：验证GET请求显示
```
status == ENABLED
```
？
步骤4：目标用户已解析为唯一记录？
步骤5：已解析Discovery权限集+许可证；已检查现有分配情况（幂等性）？
步骤6：已为目标用户分配权限集及其许可证（或已拥有）？
步骤7：通过写入后的读取操作确认分配结果（而非仅依赖POST响应）？
已提前向用户确认目标组织、用户和每个写入操作？

Output expectations

输出预期

text

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).

Keep internal jargon out of user-facing output (no record IDs, HTTP status codes, error codes, object, endpoint or developer names) — say "IT Service Discovery Manager access", not the developer name. If any step fails, stop and tell the user — in plain language — which part didn't succeed and what it means for them, then point to the relevant fix. Translate any raw error (e.g. a 403 or

FUNCTIONALITY_NOT_ENABLED

) into what it means ("CMDB isn't fully set up yet"), rather than echoing the code.

text

CMDB资产发现——完成（通过service-itsm-agentic-setup-cmdb-discovery-configure）

目标组织：<org>
用户：<name>（<username>）

  资产发现 ................... 已启用
  IT Service Discovery Manager ...... 已分配    （或：已拥有访问权限）

该组织现已启用资产发现，上述用户可打开并使用Discovery页面。CMDB设置已完成——基础功能、用户访问权限、内容包和发现功能均已配置到位。

如需为其他用户授予Discovery页面访问权限，请重新运行本技能并指定每个用户（或使用service-itsm-agentic-setup-cmdb-access-assign配置底层CMDB数据角色）。

用户可见输出中请勿包含内部术语（无记录ID、HTTP状态码、错误码、对象、端点或开发者名称）——请使用“IT Service Discovery Manager访问权限”而非开发者名称。如果任何步骤失败，请停止操作并以通俗易懂的语言告知用户哪部分未成功及其影响，然后引导至相关修复方案。将任何原始错误（如403或

FUNCTIONALITY_NOT_ENABLED

）转换为用户易懂的表述（如“CMDB尚未完全设置”），而非直接回显错误代码。

Common failures (surface these in plain language)

常见故障（以通俗易懂的语言呈现）

Symptom	Likely cause	What to tell the user
Pre-check `enableBlockedReasons` non-empty	An earlier CMDB layer is incomplete (most often the base CMDB feature)	Relay each reason; finish CMDB setup first — run `service-itsm-agentic-setup-cmdb-configure` (base feature), then `-access-assign` (user access) and `-bundle-deploy` (content bundle), then retry discovery
`403 FUNCTIONALITY_NOT_ENABLED` on the status GET	Base CMDB gate still closed (CMDB feature not enabled)	Not a discovery failure — enable the base CMDB feature first with `service-itsm-agentic-setup-cmdb-configure` , then retry
Enable blocked ( `enableBlockedReasons` non-empty) after a partial setup	Missing dependency the org still needs	Relay each reason; resolve those prerequisites, then retry
Enable returned success but verification GET is not `ENABLED`	State lag or a downstream issue	Re-run the verification GET after a short wait; if it persists, treat it as not enabled and investigate
`PermissionSet` query `totalSize == 0` for `ItSrvcDscvrMgrPermissionSet`	Org not licensed for Discovery	Discovery access is not available on this org; confirm it is licensed
`400 DUPLICATE_VALUE` on the assignment	User already has Discovery page access	Not an error — report the role as already assigned
License-limit / no-seats error on the assignment	Discovery permission-set license seats exhausted	Report seats in use vs available; a seat must free up (or more licenses added) before assigning
Discovery is `ENABLED` and the feature turned on, but a user still can't open the Discovery page	The user was never assigned the Discovery permission set ( `ItSrvcDscvrMgrPermissionSet` / PSL `ItSrvcDscvrMgrPsl` )	Re-run this skill for that user (Steps 4–7) to grant "IT Service Discovery Manager" access
`dispatch*` auth error	headless-360 MCP session not authenticated / token expired	Re-authenticate the headless-360 MCP connection and confirm the session points at the intended org

症状	可能原因	告知用户的内容
预检查 `enableBlockedReasons` 非空	某个早期CMDB环节未完成（最常见的是基础CMDB功能未启用）	传达每个原因；先完成CMDB设置——运行 `service-itsm-agentic-setup-cmdb-configure` （基础功能），然后运行 `-access-assign` （用户访问权限）和 `-bundle-deploy` （内容包），再重试发现功能
状态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权限集许可证席位已用尽	报告已使用席位与可用席位数量；需释放一个席位（或添加更多许可证）才能分配
发现功能已 `ENABLED` 且已开启，但用户仍无法打开Discovery页面	用户从未被分配Discovery权限集（ `ItSrvcDscvrMgrPermissionSet` /PSL `ItSrvcDscvrMgrPsl` ）	为该用户重新运行本技能（步骤4–7）以授予“IT Service Discovery Manager”访问权限
`dispatch*` 返回身份验证错误	headless-360 MCP会话未验证/令牌过期	重新验证headless-360 MCP连接并确认会话指向目标组织

Cross-skill integration

跨技能集成

When	Skill
The base CMDB feature is not enabled yet (Discovery pre-check is blocked)	`service-itsm-agentic-setup-cmdb-configure` (Layers 0–2 — enable the base feature first, then return here)
A user needs the underlying CMDB data roles (Configuration Item Reader / Owner / Type Reader / Type Manager)	`service-itsm-agentic-setup-cmdb-access-assign` (Layer 3 — CMDB data access, distinct from Discovery page access)

场景	技能
基础CMDB功能尚未启用（发现预检查被阻止）	`service-itsm-agentic-setup-cmdb-configure` （第0–2层——先启用基础功能，再返回本技能）
用户需要底层CMDB数据角色（配置项Reader/Owner/Type Reader/Type Manager）	`service-itsm-agentic-setup-cmdb-access-assign` （第3层——CMDB数据访问权限，与Discovery页面访问权限不同）

Reference file index

参考文件索引

File	When to read
`references/mcp-invocation.md`	Exact `dispatch*` url/method/body for the pre-check, enable, verify, user resolution, and Discovery-Manager assignment calls, response envelopes, the license-seat query, and error table

文件	阅读时机
`references/mcp-invocation.md`	预检查、启用、验证、用户解析和Discovery Manager分配调用的具体 `dispatch*` url/method/body、响应包、许可证席位查询和错误表