service-itsm-agentic-setup-cmdb-bundle-deploy

部署 CMDB Foundation Bundle（Service Cloud ITSM）

安装 CMDB Foundation（基础） 内容包——使 CMDB 可用的开箱即用配置项类型、架构和内容。这是 CMDB 设置堆栈中的 第 4 层，也是最后一层，且要求 CMDB 功能已启用（第 2 层）。每次调用都会通过 Salesforce 托管的 Headless-360 MCP 服务（服务键 headless-360）及其四个元工具（discover、describe、dispatch_readonly、dispatch）执行。组织信息取自绑定到当前 MCP 会话的 OAuth JWT——此技能不会处理组织 ID、别名或凭据——因此，无论针对生产环境还是沙箱，使用方式都相同，且无需为每位用户单独安装 MCP。

范围

• 范围内：确认 CMDB 已启用、读取实时内容包目录、解析基础内容包的准确版本、安装基础（CMDB Foundation）内容包并进行验证。
• 范围外：启用 CMDB 功能／配置 CMDB 租户（第 0–2 层——service-itsm-agentic-setup-cmdb-configure）、分配权限集（第 3 层——service-itsm-agentic-setup-cmdb-access-assign）、安装可选附加内容包（例如组件识别规则）、CMDB 记录的增删改查，或 Discovery。

此技能仅安装基础内容包。可选附加内容包不在此技能范围内。

顺序为何重要

Bundle Connect API（bundleListView、bundles/details、bundleInstallation）受 orgHasCMDBEnabled 限制。CMDB 功能启用前，这些 API 会返回 403 FUNCTIONALITY_NOT_ENABLED，因此此技能必须在启用 CMDB 功能的技能打开该功能后运行。

除了组织级限制外，这些读取操作还会检查当前用户自身的 CMDB 访问权限。因此，此处的 403 FUNCTIONALITY_NOT_ENABLED 有两种不同原因——功能未启用或用户无访问权限。步骤 1 会在将用户引导到其他地方前，通过功能状态区分这两种情况；切勿假设 403 意味着功能未启用。

机制

所有操作都通过 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 — 对已索引的操作目录进行语义搜索（仅用于发现／确认）。
• mcp__headless-360__describe — 在安装 POST 前获取完整输入架构和规范路由。
• mcp__headless-360__dispatch_readonly — 所有读取操作（GET）的分发器。
• mcp__headless-360__dispatch — 所有写入操作（POST/PATCH）的分发器。

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

---

澄清问题

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

• 哪个组织？ 确认目标组织，并明确说明内容将安装到此组织中（这是写入操作）。如果是生产环境，须获得明确确认。

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

---

工作流

按顺序执行。始终先读后写——读取目录并解析准确版本后再安装。切勿猜测版本字符串。

步骤 1 — 确认 CMDB 已启用（读取，门控）

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

• 200 → CMDB 已启用；响应会列出可用捆绑包及其安装状态。继续。
• 403 FUNCTIONALITY_NOT_ENABLED → 情况不明确——在告知用户 CMDB 未启用之前，先查明原因。 此读取操作会同时检查组织门控和当前运行用户自身的 CMDB 访问权限，因此 403 有 两种可能原因。检查功能状态以区分两者：

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

  • status != ENABLED → CMDB 功能未启用。停止，并先引导用户使用 CMDB 功能启用技能 （service-itsm-agentic-setup-cmdb-configure）。
  • status == ENABLED → 功能已启用；只是当前运行用户缺少 CMDB 权限集。停止，并引导用户使用 CMDB 访问权限分配技能 （service-itsm-agentic-setup-cmdb-access-assign）为自己授予 CMDB 访问权限——至少需要读取权限集，此外还需要用于管理捆绑包的 Type Manager，然后重试。不要将用户引导至功能启用技能；CMDB 已启用。

从 bundleListView 响应中，找到基础捆绑包（CMDB Foundation），并记下其 currentInstalledVersion。如果已安装最新版本，请告知用户无需进行任何操作。

步骤 2 — 确定准确的基础版本（读取）

不要猜测或硬编码版本。请从捆绑包详情中读取权威版本：

dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundles/details", "method": "GET", "queryParams": { "bundleIdentifier": "base" } })

从目录中读取 latestVersion，并在安装时原样使用该字符串——不要删除、添加或重新格式化任何字符（包括开头的 v）。安装端点会根据与注册表的精确字符串匹配来确定版本，而注册表会按目录报告的原样存储版本（例如 "v3.0"），因此必须原样传递该值。

**只能安装最新版本。**安装端点会拒绝任何非最新版本（"Target version <x> is not the latest available version"）——它不支持安装旧版本或回滚到旧版本，因此始终要确定 latestVersion 并准确安装该版本。如果 installedVersion 已等于 latestVersion，则停止操作——基础捆绑包已是最新版本。

如果 bundles/details 返回 403 FUNCTIONALITY_NOT_ENABLED，而 bundleListView（步骤 1）返回了 200：组织门控正常，但当前运行用户缺少捆绑包管理权限。 bundles/details 需要 Type Manager 角色——Reader / Owner / Type Reader 权限集均不足以满足要求。请引导用户使用 CMDB 访问权限分配技能，授予 Type Manager 权限，然后重试。作为备用方案，bundleListView 已返回基础捆绑包的 currentInstalledVersion 和 latestVersion，因此如果无法分配 Type Manager 权限，可以根据步骤 1 的响应确定版本。

步骤 3 — 与用户确认（写入前）

向用户展示基础捆绑包名称、要安装的版本和目标组织。在写入前获得明确确认。明确说明此操作会将开箱即用的 CMDB 内容安装到组织中。

步骤 4 — 安装基础捆绑包（写入）

调用 discover(query="cmdb bundle installation")，然后调用 describe(id=<bundleInstallation operation id>) 以确认输入架构，再进行安装：

dispatch({ "url": "/services/data/v67.0/connect/cmdb/bundleInstallation", "method": "POST", "body": { "bundleIdentifier": "base", "version": "<latestVersion from Step 2, verbatim>" } })

bundleIdentifier 和 version 都是必填项，且 version 必须是原样传递的目录 latestVersion 字符串。success: true 响应表示安装已启动——安装可能会异步完成。

步骤 5 — 验证（读取——不要仅凭安装响应判断）

重新读取捆绑包详情，并确认基础捆绑包现在报告的已安装版本：

dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundles/details", "method": "GET", "queryParams": { "bundleIdentifier": "base" } })

installedVersion 应与安装的版本相同。如果安装以异步方式进行，且版本尚未更新，请告知用户安装正在进行，并说明如何重新检查。

---

规则 / 约束

约束	原因
首先读取 bundleListView，将其作为启用门槛	此处返回 403 表示 CMDB 尚未启用，或用户无权访问 CMDB — 在采取操作前，应通过功能状态判断具体原因
从 bundles/details 获取版本；切勿猜测；原样传递 latestVersion	安装端点会将版本与注册表中的版本进行精确字符串匹配；注册表中存储的版本与目录报告的内容完全一致（例如 "v3.0"）— 不要删减或重新格式化任何字符
仅安装最新版本	端点会拒绝任何非最新版本（"Target version <x> is not the latest available version"）；它无法安装旧版本，也无法回滚到旧版本
仅安装 base	此技能仅适用于 CMDB Foundation 基础捆绑包；不包括可选附加组件
向用户确认目标组织和安装操作	在运行中的组织上安装内容属于真实且难以撤销的写入操作
如果已安装最新版本，则跳过	避免重复安装；报告“已是最新版本”
将 success: true 视为“已启动”；另行验证	安装可能是异步的
切勿向用户透露内部术语	不要在面向用户的输出中提及记录 ID、HTTP 状态码（403/400/500）、API 错误代码（FUNCTIONALITY_NOT_ENABLED，……）、端点名称（bundleListView、bundles/details、bundleInstallation）、开发者名称和工具内部细节（dispatch、headless-360）。应使用捆绑包名称和版本，并使用通俗语言

---

验证清单

• bundleListView 是否返回了 200（CMDB 已启用且用户有权访问）？
• 是否从 bundles/details 获取了 base 的 latestVersion（而非猜测）？
• 如果已是最新版本，是否跳过了安装？
• 写入前是否向用户确认了目标组织和安装操作？
• bundleInstallation 是否返回了 success: true？
• 是否验证了 installedVersion 与目标版本一致（或报告了异步进行中的状态）？

---

输出要求

CMDB Bundle Deploy — Complete (via service-itsm-agentic-setup-cmdb-bundle-deploy)

Target org: <org>

  Bundle:   CMDB Foundation (base)
  Version:  <version>
  Status:   Installation initiated — success

CMDB now has its base content installed. Combined with the enabled feature and assigned user
access, CMDB is ready end-to-end.

不要在面向用户的输出中提及内部术语（包括记录 ID、HTTP 状态码、错误代码或端点名称）。如果任何步骤失败，请停止并用通俗语言告知用户未能完成的事项及其影响（例如：“此组织尚未启用 CMDB，因此无法安装内容”，而不是照搬 403 代码），然后指出解决方法。

---

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

现象	可能原因	告知用户的内容
读取目录时出现 403，且功能未启用	组织尚未启用 CMDB 功能	必须先为该组织启用 CMDB；这是单独的设置步骤 — 指引用户使用功能启用技能
读取目录时出现 403，但功能已启用	功能已开启；当前用户无权访问 CMDB（此读取操作也会检查用户级访问权限）	请先授予用户 CMDB 访问权限（这是单独的设置步骤），然后重试 — 功能本身已开启
读取版本时出现 403，但读取目录成功	用户缺少 CMDB 捆绑包管理角色（Type Manager）	请授予用户 CMDB Type Manager 角色（这是单独的访问权限设置步骤），然后重试；组织本身的设置没有问题
安装被拒绝 — 捆绑包或版本不存在	版本字符串错误	重新读取目录，并使用其中报告的确切最新版本
安装报告成功，但版本尚未更改	安装正在后台运行	安装正在进行；请稍后再次检查，确认是否已完成
安装时出现下游错误	平台依赖项暂时出现问题	请重试；如果持续失败，则需要联系 Salesforce 支持
连接或身份验证错误	组织连接尚未设置或已过期	重新验证组织连接，并确认它指向预期组织，然后重试

---

跨技能集成

何时	技能
尚未启用组织 CMDB 功能（组织级开关仍关闭）	service-itsm-agentic-setup-cmdb-configure（第 0–2 层 — 先启用该功能，然后返回此处）
当前用户没有 CMDB 访问权限，或没有用于管理捆绑包的 Type Manager 权限	service-itsm-agentic-setup-cmdb-access-assign（第 3 层 — 授予用户 CMDB 访问权限，包括 Type Manager，然后返回此处）

---

参考文件索引

文件	何时阅读
references/mcp-invocation.md	捆绑包目录和安装调用的确切 mcp__headless-360__* 调用格式、响应封装、安装架构查询以及错误表