experience-ui-bundle-features-generate

UI Bundle 功能

使用 @salesforce/ui-bundle-features CLI，将预构建且经过测试的功能包安装到 Salesforce UI bundle 中，而不是手动构建。本文件是与框架无关的工作流主干；框架特定的详细信息——例如示例文件扩展名、功能会改写的文件、如何挂载功能的入口组件，以及构建命令——位于 <SKILL_DIR>/references/<framework>/ 下对应框架的参考文档中。

从头构建之前，务必先检查是否已有现成的功能。CLI 与框架无关：它会将每项功能适用于相应框架的变体安装到检测到的 bundle 中。目前最常用的是身份验证和搜索；运行 list --verbose 查看完整的当前目录，因为目录内容可能会逐渐增加。

归属说明： Agentforce AI 对话客户端和文件上传由单独的技能（experience-ui-bundle-agentforce-client-generate、experience-ui-bundle-file-upload-generate）负责。如果目录中也列出了 Agentforce 或文件上传条目，不要通过两个渠道重复安装——请与用户确认他们希望采用哪种交付方式，并且绝不要在同一个 bundle 中重复安装相同功能。

软件包名称： @salesforce/ui-bundle-features 是规范的软件包名称。一些较旧的模板/示例仍引用已弃用的 @salesforce/ui-bundle-features-experimental 名称——绝不要使用 -experimental 后缀。如果命令无法解析，请先通过 npm view @salesforce/ui-bundle-features version 确认已发布的版本，再判断软件包名称是否有误。

第 0 步：确定框架

<SKILL_DIR> = 此技能自身目录的绝对路径（即存放此 SKILL.md 的文件夹）；请根据上下文中的技能路径解析。

通常调用上下文已经确定了框架——由调用此技能的协调技能传递，或在用户请求中说明。请使用该框架。

此技能支持的框架，严格来说就是 <SKILL_DIR>/references/ 下包含 features.md 的参考文件夹（因此，react 对应 <SKILL_DIR>/references/react/features.md）。这是唯一可信来源——添加框架只需添加参考文件夹，此处无需改动。

• 如果已知框架——打开 <SKILL_DIR>/references/<framework>/features.md，并将其与本主干文档一并保留。该文档提供示例扩展名、集成目标、挂载示例和构建命令。

• 如果框架未知（独立运行时未说明框架）——在询问任何人之前，先对 UI bundle 根目录运行确定性检测器：

  bash "<SKILL_DIR>/scripts/detect-framework.sh" "<path-to-uiBundles/<name>/ dir>"
  

  根据退出代码分支处理（不要解析文字输出）：

  • react 或 angular（退出代码为 0）→ 使用该框架。不要询问用户——检测结果是确定的。打开 <SKILL_DIR>/references/<framework>/features.md。
  • ambiguous（退出代码为 2）→ 两种框架都存在。列出 <SKILL_DIR>/references/，并询问用户要将功能安装到哪个 bundle 中。如果他们指定的框架没有对应的参考文件夹，则此处不支持该框架——停止。
  • unknown（退出代码为 3）→ **未检测到受支持的框架。终止。**报告在 bundle 中未发现 React 或 Angular 的特征，因此无法安装功能，然后停止。不要猜测。

在以下步骤中，<framework> 均指此处选定的文件夹。

工作流

1. 先搜索项目代码 — 安装任何内容之前，先检查 src/ 中是否已有实现。将搜索范围限定在 src/，以免匹配到 node_modules/ 或 dist/。

2. 搜索可用功能 — 使用 npx @salesforce/ui-bundle-features list，并通过 --search <query> 按关键词筛选。使用 --verbose 查看完整说明。

3. 描述功能 — 接入前必须执行。 运行 npx @salesforce/ui-bundle-features describe <feature>，并在接入前使用 npm view <package> readme 阅读该功能的 README（使用上述输出中的 Package: 名称）。README 是接入规范：它会说明该功能的预期接入方式，包括任何可直接使用的入口组件，以及每个集成示例应放在哪个文件中。对照 describe 的 Copy Operations 目标路径下复制的源代码进行核验 — 该源代码（及其 JSDoc／注释）才是与当前版本匹配的实际安装内容，并且使用检测到的框架对应的文件类型。不要根据对文件名或组件 API 的猜测进行接入。跳过此步骤是功能安装成功却始终无法运行的最常见原因。

4. 安装 — 使用 npx @salesforce/ui-bundle-features install <feature> --ui-bundle-dir <name>。主要选项：

   • 使用 --dry-run 预览更改
   • 使用 --yes 以非交互模式运行（跳过冲突）
   • 使用 --on-conflict error 检测冲突，然后使用 --conflict-resolution <file> 解决冲突

   在此 UI bundle 中进行自定义前端／布局工作之前安装功能 — 功能可能会重写应用布局和路由文件（参见框架参考中的文件名），在手动修改布局后再安装可能会导致冲突。

如果没有找到匹配的功能，请先询问用户，再构建自定义实现 — 相关功能可能使用了不同的名称。

冲突处理

在非交互环境中，使用两轮处理方式：

1. 运行带有 --on-conflict error 的安装命令，在不应用更改的情况下检测冲突。
2. 编写解决文件之前，先阅读 references/common/conflict-resolution-schema.json，了解允许使用的键和值枚举。
3. 在 <ui-bundle-dir>/conflict-resolution.json 创建解决文件（路径相对于要安装到的 UI bundle 目录，而不是仓库根目录）。使用第一轮中 CLI 打印的冲突确切路径作为键，原样填写：

   {
     "src/appLayout.tsx": "overwrite",
     "src/routes.tsx": "skip"
   }
   

   （冲突路径取决于检测到的框架，以 CLI 打印的内容为准 — 上述键仅作示例。）任何未列出的冲突路径默认设为 skip — CLI 不会覆盖未明确标记为 overwrite 的文件。
4. 使用 --conflict-resolution <path-to-that-file> 重新运行安装命令。

安装后：集成示例文件

功能可能会在 __examples__/ 目录（复数）下包含展示集成模式的示例文件。这些文件通常是完整、可运行的页面，具有具体名称，而非空白占位模板 — 使用检测到的框架对应的文件类型（参见框架参考）。对于每个文件：

1. 阅读示例文件以了解其模式 — 将其视为可运行的参考实现，不要想当然地认为它只是一个存根。
2. 阅读目标文件（见 describe 输出）。
3. 将示例中的模式应用到目标文件中。
4. 重要 — 删除前先验证：

   # Verify the build passes with the integrated pattern (build command per framework reference)
   npm run build || {
     echo "ERROR: Build failed after integration - do NOT delete __examples__/"
     exit 1
   }
   
   # Verify the pattern from the example is actually present in the target.
   # Adjust the grep to a key symbol/import/component from the example, over the
   # detected framework's source files (see the framework reference for a worked pattern).
   

   只有在构建通过且确认目标文件中已包含该模式之后，才能删除 __examples__/。

如果任一检查未通过，请勿删除 __examples__/ — 集成尚未完成。先修复集成，然后重新运行验证。

安装后：挂载开箱即用组件，不要自行编写平行实现

当某项功能提供集成点时，UI 必须使用该集成点，而不是自行编写平行实现。对于提供入口组件的功能，应挂载该组件（框架参考展示了挂载方式）；不要编写直接查询数据的自定义页面。基于种子数据的自定义结果页面或原始 GraphQL 调用会绕过已安装且经过测试的功能，因此已部署的 sObject/CMS 逻辑永远不会运行。唯一的例外是用户明确选择不使用该功能并要求自定义实现——请确认用户确有此意，不要自行推断。

提示占位符

某些文案路径会使用 <descriptive-name> 占位符（例如 <desired-page-with-search-input>），CLI 无法解析这些占位符。安装后，请将这些文件重命名或移至预期目标位置，或者将其中的模式整合到现有文件中。这与上文的 __examples__/ 约定是两回事——单个复制路径可以使用其中任意一种机制。

身份验证功能：组织端先决条件

安装身份验证功能只会复制文件，不会配置组织。这与框架无关（纯组织/元数据配置）。在告知用户身份验证已完成之前，请指出仍需完成以下组织端步骤（不属于本技能的范围，但功能要实际运行就必须完成）：

• 必须启用 Digital Experiences（Experience Cloud），为相关用户分配 Customer Community / Customer Community Plus 许可证，并启用 Salesforce Sites。
• 必须向社区和访客配置文件明确授予身份验证实用程序、登录/注册和密码重置类的 Apex 类访问权限——CLI 不会自动授予这些权限。
• 为身份验证流程涉及的任何对象配置访客配置文件共享规则/组织范围默认值。
• **已知限制：**注销存在已记录的 CSRF 处理缺陷（跟踪编号为 W-21253864）——请向用户说明这一点，不要声称注销功能已完全解决。

严重：每次安装后解析 <sfdxRoot>

CLI 可能会将文件复制到名为 <sfdxRoot> 的字面文件夹下——这是此项目 Salesforce DX 元数据根目录的未解析占位符（该目录来自 sfdx-project.json 的 packageDirectories[].path，例如 force-app/main/default）。留在该位置的文件无法部署。这与框架无关。

每次安装后：

find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$'

如果找到文件，请将每个文件移至 <metadata-root>/<same-relative-subpath>（保留其对应的 -meta.xml 旁文件），并删除已清空的占位符目录。

验证：

• 重新运行 find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$'——继续操作前，输出必须为空。