commerce-b2b-open-code-components-replace

将 OOTB B2B Commerce 组件替换为开放代码

此技能会将站点元数据 content.json 文件中的 OOTB（开箱即用）B2B Commerce 组件定义替换为对应的开源 site: 组件，或在不做任何更改的情况下，查询给定 OOTB 定义对应的开放代码组件。它使用从 assets/ootb-to-open-code-mapping.json 加载的权威映射。

范围

模式： 完整替换会执行扫描（步骤 1）、必要时让用户选择，然后更新 content.json（步骤 2–3）。仅查询（用户询问对应组件，但不要求修改文件）：遵循映射权威规则，并报告指定组件或范围内 content.json 中找到的定义所对应的 OOTB → site: 映射；除非用户确认替换，否则不要调用 Write。限定视图范围的工作：将文件发现和读取范围限制在 sfdc_cms__view/<ViewName>/（或用户提供的路径），而不是所有视图。

---

前提条件

确定 <package-dir>

读取 sfdx-project.json 并选择活动的包目录。提取 packageDirectories[]，使用其中 "default": true 的条目；如果没有条目标记为默认值，则使用第一个条目。在下文中所有位置都使用此值作为 <package-dir>。如果缺少 sfdx-project.json 或其中没有 packageDirectories，请告知用户并中止。

委派设置工作

替换组件前，委派给 commerce-b2b-open-code-components-integrate 技能，确保：

1. 开源代码仓库已克隆到 .tmp/b2b-commerce-open-source-components
2. 已选择商店，且站点元数据已在本地检索
3. 开放代码组件已复制到商店的站点元数据中

集成技能负责 .tmp/ 克隆的生命周期（会提示用户复用现有检出目录或重新克隆）；本技能假定克隆目录已存在。

按照规则 1，向用户发送纯文本聊天回复：“替换组件之前，我需要确认商店中的开放代码组件已完成设置。让我来检查……”

如果未满足任何前提条件，集成技能会负责处理。所有检查通过后，继续执行替换工作流。

前提条件满足后的必要状态：

• 包目录 — 上文确定的值（例如 force-app）
• 商店名称 — 例如 My_B2B_Store1
• 站点元数据路径 — <package-dir>/main/default/digitalExperiences/site/<store-name>/

---

替换工作流

步骤 1：扫描站点并交叉比对映射

此步骤为必需。 尝试任何替换之前，始终先扫描站点。

按照规则 1，向用户发送纯文本聊天回复：“我正在扫描商店的站点元数据，以查找当前使用的所有 OOTB commerce 组件，并检查哪些组件有对应的开放代码版本。”

步骤 1a — 查找受影响的文件（一条命令，简单字面匹配）：

grep -rl '"commerce' \
  <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__view/ \
  <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__themeLayout/ \
  --include="content.json"

步骤 1b — 读取映射并解析匹配的文件。 将 assets/ootb-to-open-code-mapping.json 读取到内存中一次。然后使用 Read 工具解析每个匹配的文件，提取所有以 commerce 开头的 "definition" 值（例如 commerce_builder:cartBadge）。汇总所有文件中的 OOTB 组件，并去重。

步骤 1c — 列出仓库组件（一条命令）：

ls .tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/

使用解析出的定义、ls 输出和映射表，将发现的每个 OOTB 组件分为以下三组：

向用户展示分类明细和可选列表：

首先，告知用户已跳过和未映射的组件：

Found X OOTB components in your site:

In mapping table but NOT in repo (skipping):
  - commerce_builder:quoteSummary → site:quoteSummary (not found in repo)

No mapping available (not in mapping table):
  - commerce_builder:actionButtons
  - commerce_builder:layoutHeaderOne
  - commerce_builder:searchInputContainer
  - commerce_builder:myAccountMegaMenu

然后将可替换组件列为多选列表，让用户可以勾选，而无需输入。包含“以上全部”选项：

Which components would you like to replace?

[ ] commerce_builder:heading → site:productHeading
[ ] commerce_builder:cartBadge → site:cartBadge
[ ] commerce_builder:searchInput → site:searchInput
[ ] All of the above

如果用户在原始请求中提供了特定组件名称，则预先筛选出这些组件，并跳过选择提示。

步骤 2：在 content.json 中替换

按照规则 1，向用户发送一条纯文本聊天回复：“我现在要将所选 OOTB 组件定义替换为开放代码对应项，更新你的网站 content.json 文件。”

步骤 1 已确定受影响的文件。对于每个包含所选组件的文件：

1. 使用 Read 工具读取文件。
2. 对于每个所选 OOTB 组件，再次确认映射的 site: 目标存在于开放代码仓库中。只有通过此项检查的替换才能继续。
3. 将所有匹配的 "definition" 值替换为对应的开放代码值——始终使用映射表中的精确 site:<name> 字符串
   • 示例："definition": "commerce_builder:heading" → "definition": "site:productHeading"
4. 使用 Write 工具保存更新后的文件。
5. 保留所有其他 JSON 属性——只更改 "definition" 值。

高效批处理：如果一个文件包含多个 OOTB 组件，请在一次 Read → 修改 → Write 流程中完成所有替换。不要多次读取和写入同一个文件。

步骤 3：报告

Replacement Complete!

Replaced X components across Y files:
- commerce_builder:heading → site:productHeading (3 files)
- commerce_builder:cartBadge → site:cartBadge (2 files)
- commerce_builder:searchInput → site:searchInput (4 files)

Skipped (not in repo):
- commerce_builder:quoteSummary

No mapping available (left unchanged):
- commerce_builder:actionButtons
- commerce_builder:layoutHeaderOne
- commerce_builder:searchInputContainer

Modified files:
- sfdc_cms__view/Home/content.json
- sfdc_cms__view/Product_Detail/content.json
- sfdc_cms__themeLayout/DefaultTheme/content.json

Next Steps:
1. Deploy: sf project deploy start -d <package-dir>/main/default/digitalExperiences/site/<store-name>
2. Test the store thoroughly in Experience Builder
3. Publish your site when ready

---

交互示例

用户：“将 OOTB 组件替换为开放代码版本”

Agent：“替换组件前，我需要确认开放代码组件已在你的商店中设置好。我来检查一下……”

• [done] 已克隆开放代码仓库
• [done] 已获取 My_B2B_Store1 的商店元数据
• [done] 已集成开放代码组件

Agent：“我正在扫描你商店的站点元数据，查找所有 OOTB commerce 组件，并检查它们是否有开放代码对应项。”

（运行 grep -rl 查找包含 commerce 定义的文件，读取这些文件以提取组件名称，运行 ls 列出仓库组件，然后与映射表交叉核对）

Found 8 OOTB components in your site:

No mapping available (not in mapping table):
  - commerce_builder:searchInputContainer
  - commerce_builder:layoutHeaderOne
  - commerce_builder:myAccountMegaMenu
  - commerce_builder:actionButtons

Agent （通过多选提示词询问用户）：

Which components would you like to replace?

[ ] commerce_builder:heading → site:productHeading
[ ] commerce_builder:cartBadge → site:cartBadge
[ ] commerce_builder:searchInput → site:searchInput
[ ] commerce_builder:cartSummary → site:cartSummary
[ ] All of the above

用户：（选择 heading 和 cartBadge）

Agent：“我现在要将所选 OOTB 组件定义替换为开放代码对应项，更新你的网站 content.json 文件。”

（扫描时已确定文件——每个受影响文件只进行一次 Read/Write 流程，并批量完成所有替换）

Replacement Complete!

Replaced 2 components across 5 files:
- commerce_builder:heading → site:productHeading (3 files)
- commerce_builder:cartBadge → site:cartBadge (2 files)

No mapping available (left unchanged):
- commerce_builder:searchInputContainer
- commerce_builder:layoutHeaderOne
- commerce_builder:myAccountMegaMenu
- commerce_builder:actionButtons

Modified files:
- sfdc_cms__view/Home/content.json
- sfdc_cms__view/Product_Detail/content.json
- sfdc_cms__themeLayout/DefaultTheme/content.json

Next Steps:
1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/My_B2B_Store1
2. Test the store thoroughly in Experience Builder

---

规则

1. **执行前始终先在聊天中说明。**每次调用 Bash 或 Write 工具前，都要在对话中发送一条纯文本回复，说明命令将执行什么操作以及原因。说明 MUST 作为普通聊天消息出现在工具调用之前。不要将其嵌入命令本身（不得使用 echo 行或 # 注释），不要将其加在命令前面，也不要只依赖工具的 description 参数——用户不一定能看到该字段。说明之后，发起工具调用，并等待用户批准后再继续。
2. **assets/ootb-to-open-code-mapping.json 是唯一事实来源。**所有 OOTB → 开放代码映射均来自该文件；切勿猜测、推断或虚构组件名称。每个替换后的新 "definition" MUST 是文件中的精确映射值，且始终使用 site: 命名空间（例如 site:productHeading）。写入前，确认映射目标存在于克隆的开放代码组件仓库中（位于 .tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/）；如果目标不存在，则跳过替换，并在“仓库中不存在”部分报告。
3. 使用 Read 和 Write 工具处理 JSON 文件。使用 Read 工具解析 content.json 文件，并使用 Write 工具更新文件。不得使用 bash 解析或编辑 JSON——不得对 JSON 内容使用 sed、awk、perl 或正则表达式。Bash 仅用于简单的文件查找（grep -rl、find、ls），不得用于提取或修改 JSON 值。
4. **尽量减少命令。**将工作合并为尽可能少的命令。使用一次 grep 扫描所有文件，使用一次 ls 验证仓库，并且每个文件只进行一次 Read/Write 流程。不得为每个组件或每个目录分别运行命令。

错误处理

错误	消息	操作
未满足前置条件	"尚未集成开放代码组件。"	先运行集成技能
未找到映射	"未找到 '{component}' 的映射。"	显示可用映射，并报告为未映射
组件不在仓库中	"在克隆的仓库中找不到开放代码组件 '{name}'。"	跳过并告知用户
站点中没有 OOTB 组件	"站点元数据中未找到 OOTB Commerce 组件。"	告知用户，无需替换
没有可替换的组件	"找到的所有 OOTB 组件均未映射，无法替换。"	显示未映射列表，并建议检查是否有更新的映射
content.json 解析错误	"无法解析 content.json：{file}"	显示错误，跳过该文件，并继续处理其余文件

---

验证清单

• 已通过集成技能验证前置条件（仓库、商店、组件）
• 已通过最少的命令扫描站点、验证仓库并交叉核对映射（步骤 1）
• 每次替换都使用精确映射的 site: 定义，并在写入前确认其存在于开放代码仓库中
• 操作前已向用户展示包含三个类别的明细
• 用户已选择要替换的组件（或提供了名称）
• 每个 content.json 文件都通过单次读取 → 修改 → 写入流程完成更新
• 已保留 JSON 结构，未引入语法错误
• 已告知用户哪些组件被跳过或未映射
• 已提供部署命令