SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场experience-ui-bundle-custom-app-generate

experience-ui-bundle-custom-app-generate

编程与开发

查看项目

更新于 10-14 11:41

技能介绍

用途

本技能用于创建和配置一个 Salesforce Custom Application，用于在 Lightning Experience 中承载 React UI bundle。它生成 CustomApplication 元数据，使该应用出现在 Lightning App Launcher 中，并可供内部用户访问。

Custom Application 与 Experience Site 不同：它们不需要 Networks、CustomSite、DigitalExperienceConfig 或 DigitalExperienceBundle 元数据。Custom Application 充当一个轻量级启动入口，将渲染委托给由 uiBundle 引用的 React UI bundle。

主要能力

  • 解析并生成承载 UI bundle 所需的 CustomApplication 元数据。
  • 根据目标组织的 API 版本，确定应使用 <uiBundle> 还是 <webApplication> 字段。
  • 在 API 版本支持时，为现有 UIBundle meta XML 就地添加 <target>CustomApplication</target>。

必需属性

在生成任何元数据之前，需要先解析所有属性。每个属性都有回退链，按顺序逐一尝试直到找到值。

  • appName：格式为 lowercamelcase（例如 myInternalApp）。解析方式为使用来自 uiBundles/<name>/ 目录的 UI bundle 名称。
  • appNamespace：字符串。解析顺序为 sfdx-project.json 中的 namespace → 运行 sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias} → 默认 c。
  • appLabel：人类可读字符串。由用户提供，或从 appName 通过 camelCase 转 Title Case 派生。

appNamespace 和 appName 将 Custom Application 连接到正确的 React UI bundle。在较新的 API 版本中使用 <uiBundle>{appNamespace}__{appName}</uiBundle>；在较旧版本中使用 <webApplication>{appName}</webApplication>。若设置错误，应用启动器条目会存在但显示空白页面。工作流第 2 步决定使用哪个字段。

使用方式

第 1 步：解析所有必需属性

在构建任何内容前，先为上表中的所有属性确定值，使用各自的解析策略。

第 2 步：查询 API 上下文（版本感知的字段发现）

调用 salesforce-api-context MCP 工具，发现目标组织 API 版本存在哪些字段。这确保生成的元数据与用户的 Salesforce 版本兼容。

必需调用（使用与所示完全一致的 metadataType 参数，不要替换为 detail 参数或其他形式；metadataType 是该工具唯一接受的参数）：

  • get_metadata_type_fields({ "metadataType": "CustomApplication" }) — 检查响应字段列表中是否存在 uiBundle 字段。
  • get_metadata_type_fields({ "metadataType": "UIBundle" }) — 检查响应字段列表中是否存在 target 字段。

基于 API 响应的字段解析：

  • CustomApplication.uiBundle 存在时：使用 <uiBundle>{appNamespace}__{appName}</uiBundle>；不存在（较旧 API 版本）时：使用 <webApplication>{appName}</webApplication>（无命名空间）。
  • UIBundle.target 存在时：使用 <target>CustomApplication</target>；不存在时：完全省略 <target> 元素。

如果实际尝试后 salesforce-api-context 不可用，则回退到较新的字段名（uiBundle + target）。

第 3 步：创建项目结构

创建尚不存在的文件和目录。CustomApplication 的路径为 <sourceDir>/applications/{appName}.app-meta.xml。

注意：<sourceDir> 由 sfdx-project.json 确定。读取 packageDirectories[] 并使用 "default": true 的条目；完整源目录为 <path>/main/default。若未设置默认值，则使用第一个条目。通常为 force-app/main/default，但此路径可配置。

第 4 步：填充所有元数据字段

使用下方文档中的默认模板。{braces} 中的值为已解析属性的引用，用第 1 步的实际值替换。应用第 2 步的字段解析决定使用哪些 XML 元素。

CustomApplication 模板参考：configure-metadata-custom-application.md

第 4 步执行说明：加载并使用该文档。Agent 在尝试填充元数据字段之前，必须完整读取第 4 步引用的 references/*.md 文件内容。完整读取文件，将占位符（如 {appName}）替换为已解析的值，然后使用展开后的模板填充元数据 XML 内容。若第 2 步确定适用较旧的字段名，则在生成输出中将 <uiBundle> 替换为 <webApplication>。

第 5 步：更新 UI Bundle Meta XML

此步骤编辑一个已存在的文件，绝不创建新文件。UIBundle 是 bundle 式元数据类型：其 meta XML 通常位于自身文件夹内，路径为 uiBundles/{appName}/{appName}.uibundle-meta.xml，与 bundle 的其他源文件（如 index.html、src/）并列。某些较旧或手工编写的项目可能将其放在扁平路径 uiBundles/{appName}.uibundle-meta.xml（无子文件夹）。

运行 node scripts/resolve-uibundle-path.mjs "{appName}" — 它会打印现有 meta XML 的路径（优先嵌套布局，回退到扁平布局）。始终通过 node 调用（绝不作为裸可执行文件），以便在 Windows 及 macOS/Linux 上都能工作。就地编辑该确切文件；不要在其他路径创建第二个文件，也不要作为此技能的一部分将其迁移到不同布局。

若第 2 步确认 UIBundle 上存在 target 字段，则在该文件的现有 <UIBundle> 元素内添加 <target>CustomApplication</target>，保留所有其他现有元素和值不变（若目标组织的 API 版本不存在该字段，则完全跳过此步骤 — 不要创建文件或添加 <target>）。

禁止事项：

  • 创建新的 .uibundle-meta.xml 文件。
  • 当已存在 .uibundle-meta.xml（嵌套或扁平）时，在不同路径创建第二个文件 — 就地编辑已有的那个，无论它在哪。
  • 在别处添加 <target> 的同时，不修改原始的 uiBundles/{appName}/{appName}.uibundle-meta.xml（或 uiBundles/{appName}.uibundle-meta.xml，如果那是现有布局）。

此技能产生或修改的唯一文件是 applications/{appName}.app-meta.xml（新建）和现有的 {appName}.uibundle-meta.xml（就地编辑，仅在适用 <target> 时）。输出中出现的任何其他 UI-bundle 相关文件都是 bug。

完全更新后文件示例（位于 uiBundles/{appName}/{appName}.uibundle-meta.xml，或现有布局对应的扁平路径）— 这仅展示现有文件的最终状态，而非要创建的新文件：

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

第 6 步：不要修改非模板化属性

不要修改 CustomApplication 元数据中任何未以 {braces} 包裹的变量形式表达的默认属性值。

验证清单

部署前确认：

  • 所有必需属性已解析。
  • 已查询 API 上下文以确定可用字段（第 2 步）。
  • applications/{appName}.app-meta.xml 存在且内容正确。
  • bundle 引用字段与组织 API 版本匹配（<uiBundle> 或 <webApplication>）。
  • 若支持 target 字段：现有 {appName}.uibundle-meta.xml（嵌套于 uiBundles/{appName}/，或扁平位于 uiBundles/，以已存在者为准）含有 <target>CustomApplication</target>。
  • 未创建额外的 .uibundle-meta.xml 文件 — 恰好存在一个 {appName}.uibundle-meta.xml，位于其原本所在路径。
  • 部署验证成功：sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}。

适用场景

当项目包含 uiBundles/*/src/ 目录，且任务涉及创建或配置承载 UI bundle 的 Custom Application 时使用。

限制

  • 资源中未提供具体的收费、价格或平台支持信息。
  • 技能依赖 salesforce-api-context MCP 工具；若不可用则回退到较新字段名。