service-itsm-agentic-setup-cmdb-configure

启用 CMDB 功能（Service Cloud ITSM）

按顺序完成 CMDB 前置条件的前三层，将组织从“CMDB 关闭”推进到“CMDB 功能已启用”。每次调用都通过 Salesforce 托管的 Headless-360 MCP 服务（服务键 headless-360）及其四个元工具（discover、describe、dispatch_readonly、dispatch）执行。组织根据绑定到当前 MCP 会话的 OAuth JWT 确定——此技能不会处理组织 ID、别名或凭据——因此，无论是针对生产环境还是沙盒环境，都可以使用相同方式运行，且每位用户无需单独安装 MCP。

此技能涵盖第 0–2 层。用户访问权限（第 3 层）和内容包（第 4 层）属于其他技能，详见本文件末尾。

此技能解除的限制

每个 CMDB Connect API 都会检查：

orgHasCMDBEnabled = orgHasCMDBPermission (org perm ITSrvcsCnfgMgmnt)  &&  OrgPreferences.CMDBEnabled

在 orgHasCMDBEnabled 为 true 之前，CMDB API 都会返回 403 FUNCTIONALITY_NOT_ENABLED。CMDBEnabled 不是可直接设置的首选项——它会在第 2 层启用功能时作为副作用切换为 true。此技能的任务就是解除这一限制。

这是必要条件，但不一定能满足特定用户的全部需求。 解除组织级限制本身并不能让特定用户读取 CMDB 数据。一些 CMDB 读取操作（例如 bundleListView）还会检查用户级别的 CMDB 访问权限；如果当前用户没有 CMDB 权限集，即使功能已正确启用，这些操作也会返回相同的 403 FUNCTIONALITY_NOT_ENABLED（“未为此用户启用”）。这是第 3 层（service-itsm-agentic-setup-cmdb-access-assign）的问题，并不表示此技能失败。请通过功能状态 status == ENABLED 确认此技能成功，切勿通过读取 CMDB 数据来确认。

范围

• 范围内：验证 CMDB 组织权限（第 0 层）、触发并轮询 CMDB 租户预配（第 1 层）、预先检查、启用并验证 CMDB 功能（第 2 层）。
• 范围外：权限集分配（第 3 层——service-itsm-agentic-setup-cmdb-access-assign）、包安装（第 4 层——service-itsm-agentic-setup-cmdb-bundle-deploy）、CMDB 记录 CRUD、Discovery / 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 路由不一定总会排在前面（也可能未编入索引），因此搜索未命中并不意味着路由不存在——请直接分发确切路径（参见 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 连接（并确认会话指向目标组织），然后停止。

---

澄清问题

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

• 目标组织是哪一个？ 确认目标组织，并明确说明此组织将被修改（租户预配和功能启用都属于写入操作）。如果是生产环境，请取得明确确认。

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

---

工作流

所有步骤都必须按顺序执行，并且设有关卡——如果某一层失败，不要继续推进。 始终先读取再写入：每次变更前都先运行只读检查。

第 0 层 — 验证 CMDB 组织 SKU（只读，硬性门槛）

CMDB 要求组织具有权限 ITSrvcsCnfgMgmnt，该权限只能通过版本、许可证或组织 模板授予。无法通过任何 API 设置此权限。 验证组织是否具有 CMDB SKU，最可靠且普遍可用的方法是查询 CMDB 权限集许可证——只有使用该许可证配置的组织才会存在此许可证：

dispatch_readonly({ "url": "/services/data/v63.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetLicense WHERE DeveloperName = 'ItSrvcCnfgItmReadPsl'" } })
→ totalSize == 1  (licensed)   |   totalSize == 0  (not licensed)

• totalSize == 1 → 组织已获得 CMDB 许可；继续执行第 1 层。
• totalSize == 0 → 停止。用通俗语言告知用户（用户看到的消息中不得包含开发者名称或 API 引用）：

  此组织未获得 CMDB 许可。CMDB 是否可用取决于组织的版本或许可证，无法通过设置启用；组织配置时必须包含 CMDB。请将组织配置为包含 CMDB（或使用已包含 CMDB 的组织），然后再次运行此操作。

核心 Connect API GET /services/data/v63.0/setup/org/permissions/ITSrvcsCnfgMgmnt （{"isPermissionEnabled": true|false}）是另一种方法，但它在某些组织类型中会返回 404 错误（包括 orgfarm 测试组织），因此优先使用上述 PSL 查询。详情请参阅 references/mcp-invocation.md。如果没有任何查询能确认权限，请说明无法验证组织权限，并请用户确认组织是否已获得 CMDB 许可，然后再继续。

第 1 层 — 配置 CMDB 租户

CMDB 在专用租户（CMDB 租户）上运行，该租户必须达到状态 PROVISIONED（此过程为异步）。

1. 检查当前状态（读取）：

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

   根据 status 分支处理：

   • PROVISIONED → 已完成；跳到第 2 层（不触发，也不轮询）。
   • UNPROVISIONED → 尚未运行任何任务；前往步骤 2 并触发任务。此状态下不要等待或轮询——等待不会启动配置，只会浪费预算。
   • PROVISIONING_IN_PROGRESS → 任务已在运行；跳过触发，直接进入步骤 3 轮询。
   • FAILED → 按照步骤 3 中的 FAILED 情况处理（显示失败原因；不要通过 API 重试）。

2. 触发配置（写入）——仅当步骤 1 显示 UNPROVISIONED 时执行。请先向用户确认：

   dispatch({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "POST" })
   

   触发操作返回后，告知用户配置已启动，通常需要 2 分钟以上，因此目前无需检查。

3. 轮询 GET，直到 status == PROVISIONED。这是异步操作，完成时间通常可靠地在 2 分钟以上（实测完成时间集中在 约 2 分 40 秒），因此立即轮询必然毫无作用。所有计时都以响应中的 triggeredAt 为基准，而不是以本次运行的开始时间为基准——任务可能由之前的运行触发（即步骤 1 中的 PROVISIONING_IN_PROGRESS 状态）。将 triggeredAt 解析为 UTC 时间戳，并计算 elapsed = max(0, now − triggeredAt)——将结果限制为不小于 0，以免时钟偏差（或服务器与 Agent 的时区不一致）导致 elapsed 为负数（从而无限等待）或错误超时。如果 triggeredAt 缺失或无法解析（触发 POST 响应可能尚未填入该字段，或之前运行留下的进行中记录可能没有该字段），则改用本次运行的开始时间作为基准——将 elapsed 视为 0，并等待完整的约 2 分钟下限，确保分支始终能确定性地执行。然后：

   • elapsed < ~2 min → 等到 triggeredAt 之后约 2 分钟再首次检查（跳过必然无用的早期轮询），之后每 30 秒轮询一次。
   • ~2 min ≤ elapsed < 10 min → 立即轮询（初始等待时间已过，不要重新等待 2 分钟），之后每 30 秒轮询一次。
   • elapsed ≥ 10 min → 不要重新开始等待；按下方的超时情况处理（报告最后一次看到的状态，由用户决定下一步操作）。 总体预算为 从 triggeredAt 起 10 分钟（在约 2 分钟的最低等待时间后，约检查 16 次）。约 2 分钟是最低等待时间，不是额外延迟——通常约 2:40 即可完成，在一两次轮询内就能覆盖；不要再延长。初始等待期间不要轮询。满足以下任一条件时，立即退出循环：
   • status == PROVISIONED → 成功，继续第 2 层。
   • status == FAILED → 立即停止。不要通过 API 重试——用通俗易懂的语言向用户说明失败情况，并包含以下三项：
     1. 将失败原因转换为人类可读的文本。 从响应正文中读取（FAILED 负载包含 error / failureReason / message 等详情字段——解码 < / > 等 HTML 实体，并去除标记）。如果响应未包含详情，请说明租户预配失败，且未返回原因。
     2. 提供组织租户预配 Setup 页面的链接，根据目标组织的实例 URL 构建：<org instance URL>/lightning/setup/CMDBProvisionalSettings/home。
     3. 请用户打开该页面并手动尝试预配，待租户显示为 PROVISIONED 后再重新运行此技能。只有手动重试也失败时，才需要联系 Salesforce 支持。
   • 超过 10 分钟窗口 → 停止，报告最后一次看到的状态，并让用户决定是继续等待（重新运行）还是进行调查。绝不要超过 10 分钟的限制继续循环。

   在后台轮询（运行时允许时）。 预配需要等待数分钟，用户不应只能空等。仅当执行运行时支持后台工作时（例如，能够启动分离的子 Agent 或安排唤醒的 Agent 运行时），才将等待后轮询的循环交给后台任务，让用户可以继续工作，并在任务结束时报告结果（PROVISIONED / FAILED / 超时）。如果运行时采用单线程轮次（ADK / Agentforce / headless-360 生产路径为单线程——轮询循环会阻塞对话），则改为内联轮询。无论哪种方式：（a）提前告知用户需要几分钟；（b）提供恢复方式——如果用户离开后本轮结束，他们可以重新运行此技能，由第 1 层根据当前状态继续（已为 PROVISIONED 的租户会直接跳到第 2 层）。绝不要强制要求运行时可能不具备的后台功能。

第 2 层 — 启用 CMDB 功能（解除此 403 限制）

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

1. 预先检查状态（读取）：

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

   • status == ENABLED → 已完成；跳到验证。
   • status == NOT_ENABLED 且 enableBlockedReasons: [] → 可以启用。
   • enableBlockedReasons 非空 → 停止，用通俗易懂的语言向用户转达每项原因（这些是组织仍需满足的先决条件——不要尝试启用）。
2. 与用户确认，然后启用（写入）：

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

3. 验证（读取）——不要仅凭 POST 响应作判断：

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

   status == ENABLED 是此技能所需的唯一决定性确认。 第 2 层仅根据此项检查判定成功或失败；不会读取任何 CMDB 数据来确认限制是否解除。读取 CMDB 数据（例如 bundleListView）还取决于当前用户自身的 CMDB 访问权限，因此无法准确确认组织级别的启用状态——请参阅“The gate this skill lifts”下的说明。一旦功能显示为 ENABLED，第 2 层即完成。

---

规则 / 约束

约束	原因
先验证第 0 层，再进行任何其他操作	如果 ITSrvcsCnfgMgmnt 处于关闭状态，后续步骤都无法成功——应尽早失败并给出清晰说明
绝不尝试通过 API 设置 ITSrvcsCnfgMgmnt	没有可用的设置接口；它只能通过许可证、版本或模板配置
绝不直接设置 CMDBEnabled（例如通过 updateDefaultOrgPrefs）	它不在任何可设置偏好的允许列表中；服务器会以 500 错误拒绝。它只会作为启用第 2 层功能的副作用而切换
每次写入前都先读取；每次写入后都进行验证	租户和功能都是异步且有状态的；POST 响应可能滞后于实际状态
与用户确认目标组织和每次写入	这些是在实际运行中的组织上进行的真实变更，且难以撤销
某一层失败或受阻时，不要继续执行后续层	后续层依赖前面的层，并且会返回 403
根据响应中的 triggeredAt 计算轮询时间（解析为 UTC 时间戳；已用时间 = max(0, 当前时间 − triggeredAt)），而不是从本次运行开始计时；首次检查前至少等待约 2 分钟，此后每 30 秒检查一次，从 triggeredAt 起总计等待 10 分钟。如果缺少 triggeredAt 或无法解析，则从本次运行开始计时（已用时间 = 0）	配置通常需要 2 分钟以上（测得约 2 分 40 秒），因此更早轮询必定无效。PROVISIONING_IN_PROGRESS 条目可能由更早的一次运行触发——如果已超过约 2 分钟的等待下限，则立即轮询；如果已超过 10 分钟，则报告超时，而不是重新等待 2 分钟。将已用时间限制为 ≥ 0，避免时钟偏差或时区不匹配导致无限等待或误报超时；在缺少时间戳时使用后备方案，确保分支仍能执行。绝不超过 10 分钟上限
仅在运行时支持的情况下将轮询循环置于后台；否则就在当前流程中轮询——绝不强制要求使用后台机制	用户不应在数分钟的等待期间无所事事，但生产环境中的无头 headless-360/ADK 流程是单线程轮次；要求使用后台轮询器的技能会导致该流程无法运行。始终提供重新运行以继续操作的路径
状态为 FAILED 时，绝不通过 API 重试——解析失败原因，提供 Setup URL，并请用户手动重试	API 触发的操作已经失败；用户可以在 CMDB 配置的 Setup 页面重试，该页面会显示实际错误和任何需要手动处理的事项
绝不向用户透露内部术语	不要在面向用户的输出中出现记录 ID、组织 ID、HTTP 状态码（403/500/…）、API 错误代码（FUNCTIONALITY_NOT_ENABLED，…）、端点名称（bundleListView、tenantProvisioningStatus）、开发者名称（ITSrvcsCnfgMgmnt、CMDBEnabled）和工具内部信息（dispatch、headless-360）。请使用通俗语言；使用易于理解的名称和状态

---

验证清单

• 第 0 层：已确认 ITSrvcsCnfgMgmnt 为 true（或已停止并清楚说明许可证问题）？
• 第 1 层：租户的 status == PROVISIONED？
• 第 2 层：启用前的预检查显示 enableBlockedReasons: []？
• 第 2 层：启用操作返回 success: true？
• 第 2 层：验证 GET 显示 status == ENABLED？（这是唯一的成功判据——不使用 CMDB 数据读取来确认）
• 已事先与用户确认目标组织和每次写入？

---

输出要求

CMDB Feature Enable — Complete (via service-itsm-agentic-setup-cmdb-configure)

Target org: <org>

  CMDB license .................. Present
  CMDB tenant ................... Provisioned
  CMDB feature .................. Enabled

CMDB is now enabled on this org. Next steps:
  • Assign user access  → service-itsm-agentic-setup-cmdb-access-assign
  • Install base bundle  → service-itsm-agentic-setup-cmdb-bundle-deploy

不要在面向用户的输出中使用内部术语（不包含记录 ID、HTTP 状态码、错误代码、端点或开发者名称）。如果任何步骤失败，请停止并用通俗语言告诉用户设置的哪一部分未成功，以及这对他们意味着什么，然后提供相关的解决办法。将任何原始错误（例如 403 或 FUNCTIONALITY_NOT_ENABLED）转换为其含义（“CMDB 尚未启用”），而不是照搬错误代码。

---

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

症状	可能原因	告诉用户的内容
第 0 层返回 false	组织没有 CMDB SKU	许可/版本前置条件——没有任何 API 可以授予；请为组织配置 CMDB
CMDB 读取时出现 403 FUNCTIONALITY_NOT_ENABLED，且功能 status != ENABLED	功能尚未启用（第 2 层未完成）	完成第 2 层；只有功能状态变为 ENABLED 后，限制才会解除
调用 bundleListView 时出现 403 FUNCTIONALITY_NOT_ENABLED，且功能 status == ENABLED	功能已启用；当前运行用户缺少 CMDB 权限集（bundleListView 还会检查用户级访问权限）	这不是第 2 层故障，而是第 3 层问题；运行 service-itsm-agentic-setup-cmdb-access-assign，为用户授予 CMDB 访问权限
功能启用受阻（enableBlockedReasons 非空）	缺少组织仍需满足的依赖项	转达每条原因；先解决这些问题，然后重试
租户停留在 UNPROVISIONED / PROVISIONING_IN_PROGRESS 状态或耗时过长	配置是异步进行的	通常需要约 2–3 分钟；请在 10 分钟的时间限制内持续轮询，或重试触发操作
租户状态为 FAILED	Salesforce 侧的配置任务失败	分享解码后的失败原因以及组织的 /lightning/setup/CMDBProvisionalSettings/home 链接，并请用户在那里手动重试配置；只有手动重试也失败时，才升级给 Salesforce 支持团队
dispatch* 身份验证错误	headless-360 MCP 会话未通过身份验证或令牌已过期	重新验证 headless-360 MCP 连接，并确认会话指向预期的组织

---

参考文件索引

文件	阅读时机
references/mcp-invocation.md	第 0–2 层每次调用所需的准确 dispatch* URL、方法和请求体、响应封装格式及错误表