service-digital-engagement-messaging-site-integrate

在 Experience Cloud 站点上嵌入消息小组件

将现有的 Embedded Messaging（MIAW）部署接入 Experience Cloud 站点：检索站点的 bundle（LWR DigitalExperienceBundle 或 Aura ExperienceBundle），修改主页 JSON 以放置 experience_messaging:embeddedMessaging 组件，将 bundle 暂存到本地项目中，进行部署，发布站点，并验证访客访问权限。

此操作具有幂等性：如果组件已存在，则会在原处更新（保留其 id），因此使用不同的 ESD 坐标重新运行也能顺利更新。

范围

• 范围内：检测 LWR 或 Aura bundle 类型；为站点模板补齐缺失的 LWR 模板路由（例如 too-many-requests）；修改所有 sfdc_cms__themeLayout/*/content.json 文件，在页脚区域插入或更新 Embedded Messaging 组件（全站放置）；将 bundle 暂存到 force-app；异步部署并轮询状态；解析 Network.Name 并发布站点；访客 URL 冒烟测试；提供带有深层链接的 Experience Builder 手动备用方案。
• 范围外：创建 EmbeddedServiceConfig（Embedded Service Deployment）本身——请使用 service-digital-engagement-deployment-configure；创建 MessagingChannel——请使用 service-digital-engagement-channel-configure；创建 Experience Cloud 站点本身——请使用 experience-lwr-site-generate；为非 Experience 网站生成独立的 JS 代码片段。

---

澄清问题

执行前，如果信息尚不明确，请询问用户：

• 站点名称？ Experience Cloud 站点的 DeveloperName（digitalExperiences/site/<siteName>/ 或 experiences/<siteName>/ 下的元数据文件夹名称）。
• 部署坐标？ deploymentName（Embedded Service Deployment 的 DeveloperName）、scrtUrl 和 siteEndpoint（Experience 站点的基础 URL）。这三项均来自已发布的 EmbeddedServiceConfig；如果用户未提供，请从 service-digital-engagement-deployment-configure 的输出中获取。
• 目标组织别名？ 用于 sf 命令。
• URL 路径前缀？ 站点的 UrlPathPrefix（用于解析发布所需的 Network.Name，以及访问访客 URL 进行验证）。

---

必需输入

继续操作前，请收集或推断以下信息：

• 站点名称 — 站点的 DeveloperName
• 部署名称 — EmbeddedServiceConfig 的 DeveloperName
• scrtUrl — 部署中的 SCRT2 端点 URL
• siteEndpoint — Experience 站点的基础 URL
• 目标组织别名
• URL 路径前缀 — 站点的公开 URL 路径段（例如 esw-site）

写入时应用于组件属性的默认值：

• isExpSiteAuthMode：false
• hideChatButtonOnLoad："Default"
• clientVersion："WebV1"

---

工作流

以下步骤按顺序执行。如果任何自动化步骤失败，请转到手动备用方案（阶段 6）；在访客 URL 冒烟测试返回 200 或用户确认已手动发布之前，不要声称小组件已“上线”。

阶段 1 — 检测 Bundle 类型

1. 将两个候选 bundle 都检索到 <retrieve-dir> 中。 脚本只会执行确定性的路径检查，因此必须先运行检索命令：

   sf project retrieve start --metadata "DigitalExperienceBundle:site/<siteName>" \
     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
   sf project retrieve start --metadata "ExperienceBundle:<siteName>" \
     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
   

   任一调用都可能返回“未找到元数据”——这是预期情况；缺失的 bundle 表示站点属于另一种类型。

2. 运行 scripts/detect_bundle_type.sh <retrieve-dir> <siteName>。 该命令会向标准输出准确输出一个标记：

   • LWR → LWR 标记文件存在（digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json）。转到阶段 2。
   • AURA → Aura 标记文件存在（experiences/<siteName>/views/homeGuestLayout.json）。转到阶段 3。
   • UNKNOWN（退出代码为 1）→ 两个标记文件都不存在。跳转到阶段 6 的手动备用方案。

检索命令格式和故障排除方法请参阅 references/bundle_detection.md。

第 2 阶段 — 修补 LWR Bundle

3. 修补前，先搭建任何缺失的 LWR 模板路由（通常是 too-many-requests），否则部署会失败。路由和视图的搭建由 experience-lwr-site-generate 负责（参见其 configure-content-route.md、configure-content-view.md 和 handle-component-and-region-ids.md）。实际搭建工作应委派给该技能；本技能只提供与消息相关的上下文（部署报错所指的路由，以及确认搭建的路由和视图解决了该特定部署错误）。委派说明请参见 references/lwr_route_scaffolding.md。

4. 修补所有 themeLayout 文件，运行：

   scripts/patch_lwr_bundle.sh \
     <retrieve-dir>/digitalExperiences/site/<siteName> \
     <deploymentName> <scrtUrl> <siteEndpoint>
   

   脚本会遍历每个 sfdc_cms__themeLayout/*/content.json 文件。对于每个文件，它会在 .contentBody.component.children[] 中找到 footer 区域，进入现有 community_layout:section 封装组件的内部插槽区域，然后就地更新现有的 experience_messaging:embeddedMessaging 组件（保留其 id），或追加新的组件节点。将组件放在 themeLayout 的 footer 中，即可让小组件在整个站点的每个页面上显示（作为浮动叠加层），效果等同于将其放置在 Aura themeFooter 中。有关 JSON 结构及验证方法，请参见 references/lwr_patch.md。

5. 继续执行第 4 阶段。

第 3 阶段 — 修补 Aura Bundle

6. 修补主页访客布局，运行：

   scripts/patch_aura_bundle.sh \
     <retrieve-dir>/experiences/<siteName>/views/homeGuestLayout.json \
     <deploymentName> <scrtUrl> <siteEndpoint>
   

   脚本会遍历 .regions[]，选取第一个 .components[] 非空的区域，递归遍历其中的 forceCommunity:section 封装组件，然后就地更新现有的 .componentName == "experience_messaging:embeddedMessaging" 组件（保留其 id），或追加新的 forceCommunity:section 封装组件。Aura 使用 componentName / componentAttributes（而非 definition / attributes），且没有 dxpStyle。有关 JSON 结构和验证步骤，请参见 references/aura_patch.md。

7. 继续执行第 4 阶段。

第 4 阶段 — 暂存并部署

8. 将修改后的 Bundle 复制到项目的默认包中。 使用 cp -R，以便未修改的文件也一并复制：

   • LWR：cp -R <retrieve-dir>/digitalExperiences force-app/main/default/
   • Aura：cp -R <retrieve-dir>/experiences force-app/main/default/，并且还要复制同级的 <siteName>.site-meta.xml 文件 — 缺少此文件会导致 Aura 部署被拒绝。

9. 异步部署并轮询：

   sf project deploy start --source-dir force-app/main/default \
     --target-org <org-alias> --async
   

   每隔 15 秒轮询一次，最多 10 分钟：

   sf project deploy report --job-id <job-id> --target-org <org-alias>
   

   当状态为 Succeeded、Failed、SucceededPartial 或 Canceled 时停止。若部署失败，请提供部署报告，不要继续发布。完整的轮询流程和常见失败情况请参见 references/deploy_and_publish.md。

第 5 阶段 — 发布并验证

10. 解析 Network.Name。 Network.Name 通常与站点的 DeveloperName 不同，因此请通过 URL 路径前缀查询，而不要猜测：

    sf data query --query \
      "SELECT Name FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
      --target-org <org-alias>
    

11. 使用解析出的名称发布社区：

    sf community publish --name "<resolved-Name>" --target-org <org-alias>
    

12. 通过访问公开 URL 对访客访问进行冒烟测试：

    curl -sL -o /dev/null -w "%{http_code}" \
      https://<domainHostname>/<urlPath>
    

    只有当响应为 200 时，才报告成功。

第 6 阶段 — 手动备用方案

13. 如果任何自动步骤失败（无法检测到 Bundle、补丁写入受阻、部署失败、发布失败，或访客 URL 返回的状态不是 200），请打印 Experience Builder 深层链接以及 references/manual_fallback.md 中的原文说明。在用户确认之前，不要声称组件已上线。

    深层链接如下：

    https://<MyDomain>.lightning.force.com/sfsites/picasso/core/config/commeditor.apexp?...networkId=<Network.Id>
    

    使用 sf org display --target-org <org-alias> 解析 <MyDomain>，并通过以下命令解析 <Network.Id>：

    sf data query --query \
      "SELECT Id FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
      --target-org <org-alias>
    

    不要将这两个值硬编码。 指示用户打开 Experience Builder，将 Embedded Messaging 组件拖到目标页面，在属性面板中选择部署，然后点击 Publish。

---

规则 / 约束

约束	理由
根据检索输出检测 Bundle 类型，不要自行假设	LWR 和 Aura 站点需要修补不同的文件，并使用不同的键名
原位更新时保留现有组件的 id	确保幂等性；Experience 运行时依据 id 进行识别
每个新 id 都必须是全新的 UUID	重复的 ID 会破坏布局，并可能导致渲染失败
LWR 使用 definition / attributes；Aura 使用 componentName / componentAttributes	键名错误会导致组件被静默地从渲染结果中丢弃
LWR community_layout:section 的 sectionConfig 位于 .attributes 内，且是 JSON 字符串（不是顶层属性，也不是嵌套对象）	放在顶层违反架构的 additionalProperties: false 约束；序列化器也要求值为字符串而非对象
必须将 Aura 同级文件 <siteName>.site-meta.xml 与 Bundle 一起复制	缺少此文件会导致部署被拒绝
轮询异步部署；不要启动后就不再检查	只有部署成功后才能执行发布
根据 UrlPathPrefix 解析 Network.Name，不要复用站点的 DeveloperName	两者经常不同
在访客 URL 返回 200 或用户确认之前，不要声称“已在站点上线”	发布是异步的；过早报告成功会误导用户
手动备用链接中绝不要硬编码 MyDomain 或 Network.Id	这些值因组织而异，必须通过查询获取
幂等性：使用新的 ESD 坐标重新运行时，必须原位更新	用户在设置期间会反复调整 deploymentName、scrtUrl、siteEndpoint

---

易错点

问题	解决方法
LWR 部署期间缺少 too-many-requests 路由	按照 references/lwr_route_scaffolding.md 搭建缺失的路由和视图文件
Aura 部署因缺少站点元数据而被拒绝	从检索目录复制同级文件 <siteName>.site-meta.xml
组件已追加但未渲染	确认区域包装器使用正确的 type: "region" 键，并且 Aura 组件使用 componentName（而非 definition）
sf community publish 因“community not found”失败	Network.Name 与站点的 DeveloperName 不同；通过 UrlPathPrefix 查询解析
发布后访客 URL 返回 403 或 503	发布是异步的——等待 60s 后重试冒烟测试，再改用手动方案
重新运行后新增了第二个消息组件	递归搜索匹配了错误的键名；组件检测必须使用 definition（LWR）或 componentName（Aura）
部署成功，但组件未显示在所有页面上	对于 LWR，确认组件已注入 sfdc_cms__themeLayout/*/content.json 的页脚（而非 sfdc_cms__view/home/content.json——该文件仅针对特定页面）。对于 Aura，确认已修补 homeGuestLayout.json（themeFooter 区域）。
sectionConfig 被写成对象	将其序列化为 JSON 字符串；CMS 解析器不接受对象

---

验证清单

Bundle Detection

• 是否恰好找到 sfdc_cms__view/home/content.json（LWR）或 views/homeGuestLayout.json（Aura）中的一个？
• 如果两者都未找到，工作流是否转至手动回退流程？

Patch Correctness

• 对于 LWR，消息传递组件的键是否为 definition 和 attributes？
• 对于 Aura，键是否为 componentName 和 componentAttributes？
• 原位更新时，是否保留了现有的 id？
• 追加时，所有新增的 id 值是否都是全新的 UUID？
• 对于 LWR，脚本是否修补了每个 sfdc_cms__themeLayout/*/content.json（而不只是 home/content.json）？
• 对于 LWR，每个 themeLayout 中的消息传递节点是否都位于 footer 区域的子树内？
• 对于 LWR，消息传递节点属性中的 clientVersion 是否设为 "WebV2"？

Deploy

• 对于 Aura，是否将 <siteName>.site-meta.xml 与 bundle 一起复制？
• 是否持续轮询异步部署，直到获得终止状态？
• 继续发布之前，终止状态是否为 Succeeded 或 SucceededPartial？

Publish

• 是否通过 UrlPathPrefix 解析 Network.Name，而不是复用站点的 DeveloperName？
• sf community publish 是否无错误完成？

Verify

• 访客 URL 的 curl 请求是否返回 200？
• 在观察到 200 或用户确认手动发布之前，工作流是否避免声称成功？

---

Output Expectations

交付物：

• 已修改的 sfdc_cms__themeLayout/*/content.json 文件（每个 themeLayout 各一个），位于检索目录和 force-app/main/default/... 中（LWR）；或已修改的 homeGuestLayout.json（Aura）
• （仅限 LWR，如有需要）为任何搭建的缺失路由新增的 sfdc_cms__route/<RouteApiName>/ + sfdc_cms__view/<viewId>/ 对
• Deploy job-id 和最终部署报告
• 发布确认
• 访客 URL 冒烟测试的 HTTP 状态
• 失败时：Experience Builder 深层链接和手动操作说明

不要生成 EmbeddedServiceConfig 或 MessagingChannel 元数据——这些分别由下方的部署技能和渠道技能负责。

---

Cross-Skill Integration

需求	委托给
创建或更新 Embedded Service Deployment	service-digital-engagement-deployment-configure
创建底层 MIAW 消息渠道	service-digital-engagement-channel-configure
创建 Experience Cloud LWR 站点本身	experience-lwr-site-generate
搭建缺失的 LWR 路由 + 视图对（例如 too-many-requests）	experience-lwr-site-generate（路由/视图创建、ID 处理）

---

Reference File Index

文件	阅读时机
references/bundle_detection.md	阶段 1 — LWR 与 Aura 检索及判别
references/lwr_route_scaffolding.md	阶段 2 — 委托搭建缺失的 LWR 模板路由的指引（由 experience-lwr-site-generate 负责）
references/lwr_patch.md	阶段 2 — patch_lwr_bundle.sh 的功能及其输出验证方法
references/aura_patch.md	阶段 3 — patch_aura_bundle.sh 的功能及其输出验证方法
references/deploy_and_publish.md	阶段 4–5 — 暂存到 force-app、异步部署轮询、发布和访客 URL 冒烟测试
references/manual_fallback.md	阶段 6 — Experience Builder 深层链接和手动拖放发布说明
scripts/detect_bundle_type.sh	阶段 1 — 对检索到的 bundle 进行确定性的 LWR/Aura/UNKNOWN 类型检测
scripts/patch_lwr_bundle.sh	阶段 2 — 幂等修补 LWR content.json（插入或原位更新）
scripts/patch_aura_bundle.sh	阶段 3 — 幂等修补 Aura homeGuestLayout.json（插入或原位更新）