platform-flexipage-generate

何时使用此技能

当您需要以下操作时使用此技能：

• 创建 Lightning 页面（RecordPage、AppPage、HomePage）
• 生成 FlexiPage 元数据 XML
• 向现有 FlexiPage 添加组件
• 排查 FlexiPage 部署错误
• 理解 FlexiPage 结构和组件配置
• 处理页面布局或 Lightning 页面自定义
• 编辑或更新任何 *.flexipage-meta.xml 文件

规范

概述

关键：创建新的 FlexiPages 时，您必须始终从 CLI 模板命令开始。 切勿从头开始创建 FlexiPage XML——CLI 提供有效的结构、正确的区域和正确的组件配置，可防止部署错误。

使用 CLI 引导生成 Lightning 页面（RecordPage、AppPage、HomePage），用于组件发现和配置。

---

快速入门工作流

步骤 1：使用 CLI 引导

新页面必须执行此步骤：此步骤不是可选的。 创建新的 FlexiPage 时，始终使用 CLI 模板命令。CLI 生成有效的 XML 结构、正确的区域和正确的元数据，可防止常见的部署错误。仅当您编辑现有的 FlexiPage 文件时才跳过此步骤。

<packageDirectory> = sfdx-project.json 中 packageDirectories[0] 的 path 值（例如 force-app）。在运行命令之前从项目文件中读取它。

sf template generate flexipage \
  --name <PageName> \
  --template <RecordPage|AppPage|HomePage> \
  --sobject <SObject> \
  --primary-field <Field1> \
  --secondary-fields <Field2,Field3> \
  --detail-fields <Field4,Field5,Field6,Field7> \
  --output-dir <packageDirectory>/main/default/flexipages

关键： 如果 sf template generate flexipage 命令失败，停止。

1. 安装模板插件：

   sf plugins install templates
   

2. 重试 sf template generate flexipage 命令
3. 验证 FlexiPage XML 文件已创建

在模板命令成功之前，不要继续执行步骤 2。生成的 XML 是整个工作流所必需的。

模板特定要求

RecordPage：

• 需要 --sobject（例如 Account、Custom_Object__c）
• 需要字段参数：
  • --primary-field：最重要的标识字段（例如 Name）
  • --secondary-fields：记录摘要（建议 4-6 个，最多 12 个）
  • --detail-fields：完整记录详细信息，包括必填字段（例如 Name）

AppPage：

• 无额外要求

HomePage：

• 无额外要求

字段选择规则

• 验证字段存在：在命令中指定字段之前，使用 MCP 工具或 describe 命令发现对象可用的字段
• 优先使用复合字段：可用时使用 Name（而不是 FirstName/LastName）、BillingAddress（而不是 BillingStreet/BillingCity/BillingState）、MailingAddress 等
• 在 detail-fields 中包含必填字段：始终在 --detail-fields 参数中包含对象必填字段（如 Name），即使它们也用于 --primary-field 或 --secondary-fields

您将获得

• 具有正确结构的有效 FlexiPage XML
• 预配置的区域和基本组件
• 正确的字段引用和 Facet 结构
• 可直接部署或进一步增强

步骤 2：部署基础页面

运行试运行部署以验证页面和依赖项（使用 sfdx-project.json 中的默认包目录）：

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

关键： 在继续之前修复任何部署错误。页面必须成功验证。

步骤 3：动态添加组件（如果请求）

基础页面成功部署后，如果用户想要其他组件，请按照下面的动态添加组件工作流进行操作。所有组件添加都必须通过发现和推断管道——切勿仅凭记忆编写组件 XML。

---

关键 XML 规则

阅读 references/xml_rules.md 了解所有 XML 编码规则、字段引用格式、区域/Facet 类型、fieldInstance 结构、唯一标识符要求以及常见部署错误解决方案。

关键规则（快速提醒）：

• 在 <value> 标签中对 HTML 进行编码：先 &，然后 <、>、"、'
• 字段引用：Record.{FieldApiName}（切勿使用 Object.Field）
• 每个 <identifier> 和区域 <name> 必须在整个文件中唯一
• 同一 Facet 中的多个组件 → 合并到一个区域中，包含多个 <itemInstances>

---

标识符、区域和容器

阅读 references/identifiers_and_regions.md 了解标识符生成算法、Facet 命名模式（命名 vs UUID）、区域选择规则和容器组件 Facet 结构。

---

组件特定提示

dynamicHighlights（RecordPage 页眉）

位置： 仅 header 区域。有关完整结构，请参阅 references/record_flexipage_dynamicHighlights.md。
CLI 根据 --primary-field 和 --secondary-fields 自动生成 Facets。

fieldSection

用于： 在列中显示字段。三级嵌套：区域 → 列 Facets → 字段 Facets。
有关完整结构和 XML 示例，请参阅 references/flexipage_fieldSection.md。
关键： columns 属性值是 Facet 名称，而不是数字。

richText

有关编码规则和 XML 结构，请参阅 references/flexipage_richText.md。
标识符：flexipage_richText 或 flexipage_richText_{N}

---

必需的元数据结构

<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
   <flexiPageRegions>
      <!-- 区域和组件 -->
   </flexiPageRegions>
   <masterLabel>页面标签</masterLabel>
   <template>
      <name>flexipage:recordHomeTemplateDesktop</name>
   </template>
   <type>RecordPage</type>
   <sobjectType>Object__c</sobjectType> <!-- 仅 RecordPage -->
</FlexiPage>

页面类型：

• RecordPage - 需要 <sobjectType>
• AppPage - 不需要 sobjectType
• HomePage - 不需要 sobjectType

---

验证清单

结构（新页面）

• [ ] 使用 CLI 引导——切勿从头创建 FlexiPage XML

标识符和区域

• [ ] 所有 <identifier> 值在整个文件中唯一
• [ ] 所有区域/Facet <name> 值在整个文件中唯一
• [ ] 同一 Facet 中的多个组件合并到一个区域中，包含多个 <itemInstances>

字段实例

• [ ] 所有字段引用使用 Record.{Field} 格式
• [ ] 每个 fieldInstance 具有带 uiBehavior 的 fieldInstanceProperties
• [ ] 每个 fieldInstance 位于自己的 <itemInstances> 包装器中

类型和编码

• [ ] 模板区域使用 <type>Region</type>；组件 Facets 使用 <type>Facet</type>
• [ ] 具有 HTML/XML 的属性值进行实体编码
• [ ] 没有不必要的 <mode> 标签（仅在组件模式需要时）
• [ ] 页面名称中没有 __c 后缀
• [ ] 每个 Facet 仅由一个组件属性引用

---

快速参考：CLI 命令

阅读 references/cli_commands.md 了解完整的 CLI 示例（RecordPage、AppPage、HomePage）和可用选项。

---

动态添加组件

强制工作流： 对 FlexiPage 的所有组件添加都必须遵循此工作流。不要凭记忆编写组件 XML 或跳过发现。这适用于标准 OOTB 组件、自定义 LWC 组件以及任何其他组件类型。

概述

当用户请求组件（例如“添加联系人相关列表和报告”）时，请遵循此管道：

1. 解析意图 → 识别所有请求的组件
2. 发现所有 → 通过 3 层发现批量处理组件
3. 推断属性 → 对每个发现的组件运行 3 步推断
4. 生成 XML → 为所有组件一起生成有效的 XML
5. 验证 → 检查标识符、区域、属性完整性

关键规则： 首先批量发现所有组件（一次扫描，一次 MCP 调用），然后为每个组件推断属性。不要按组件调用发现步骤，也不要交错发现和推断。

步骤 1：解析用户意图

从用户话语中提取每个组件请求。示例：

• “创建包含报告和相关联系人的 Account 页面” → 2 个组件：报告、相关列表
• “添加活动、Chatter 和 Cases 的 DRL” → 3 个组件：活动、Chatter、动态相关列表

步骤 2：3 层组件发现

在进入下一层之前，为所有组件完成每一层——不要按组件运行第 1→2→3 层：

层	来源	时机	调用
1	本地工作区扫描	始终首先——为所有组件运行	0（仅本地）
2	discoverUiComponents MCP 操作	对第 1 层后未解析的所有组件进行单次调用	1
3	生成新的 LWC 包	仅对第 2 层后仍未解析且用户确认的组件	0

第 1 层为所有组件完成后，仅收集未解析的组件，并在一次 MCP 调用中传递给第 2 层。只有第 2 层后仍未解析的组件才进入第 3 层。

有关详细信息，请参阅下面的本地工作区扫描器和MCP 操作集成部分。

步骤 3：属性推断（每个组件）

对于每个发现的组件，使用 3 步策略推断属性：

1. 获取模式或读取源代码 — 对于第 2 层（组织）组件，调用 getUiComponentSchemas；对于第 1 层（本地），从源代码中提取 @api 属性
2. 应用组件指令 — 如果 references/<name>.md 存在，请阅读并遵循其推断规则
3. 解决剩余 — 智能默认值 → LLM 推断 → 用户提示（最后手段）

有关完整详细信息，请参阅下面的混合属性推断策略。

步骤 4：生成 XML

您不能做的事情：

• 修改 XML 文件中的顶层结构
• 添加任何未通过 3 层组件发现解析的凭记忆的组件
• 进行任何增强

在编写任何 XML 之前阅读 references/xml_rules.md。 遵循其中定义的所有元素命名和结构规则。

为所有已解析的组件生成 <itemInstances> XML：

• 对每个属性使用 <componentInstanceProperties>（而不是 <properties>）
• 在整个集合中分配唯一标识符（参见 references/identifiers_and_regions.md）
• 插入到适当的区域（header、main、sidebar 或 facets）
• 遵循每个组件的指令文件或模式中的 XML 结构

步骤 5：验证

检查完整的 FlexiPage：

• 标识符唯一性（整个文件中无重复）
• 区域有效性（组件位于正确的区域）
• 属性完整性（所有必需属性已填充）
• XML 编码（HTML 值进行实体编码）
• 元素名称正确性（参见 references/xml_rules.md §6）

使用试运行部署（使用 sfdx-project.json 中的默认包目录）：

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

---

MCP 操作集成

阅读 references/mcp_action_examples.md 了解完整的输入/输出示例和参数表。

通过 execute_metadata_action 执行两个 MCP 操作：

操作	目的	时机
DISCOVER_UI_COMPONENTS	查找页面类型的组件	第 2 层发现——对所有未解析组件进行单次调用
GET_UI_COMPONENT_SCHEMAS	获取属性模式	属性推断步骤 1（仅第 2 层组织组件）

关键约定：

• 组件定义格式：MCP 调用中使用 namespace/blockName（正斜杠），XML 中使用 namespace:blockName（冒号）
• RECORD_PAGE 需要带有 entityName 的 pageContext
• getUiComponentSchemas 支持部分失败——检查每个组件的 success 布尔值

---

本地工作区扫描器

在进行任何 MCP 调用之前，扫描本地 SFDX 项目以查找自定义 LWC 组件（第 1 层发现）。

算法

为每个组件查询运行扫描器（本地扫描——无网络调用）：

scripts/scan-lwc-components.sh "<query>" [packageDirectory]

该脚本扫描 <packageDirectory>/**/lwc/*/，对 camelCase 组件名称进行分词，根据用户意图关键字评分，并返回带有置信度层的 JSON 数组：

• 高置信度（≥70%）： 自动选择，与用户确认
• 中等置信度（40-69%）： 呈现排名列表供用户选择
• 低置信度（<40%）： 跳过，进入第 2 层

在将任何组件移至第 2 层之前，为所有组件运行第 1 层。收集第 1 层所有未解析的组件，然后在一次 MCP 调用中传递给第 2 层。

消歧

对于中等置信度匹配（40-69%）或多个高置信度匹配：

1. 读取每个候选的 .js-meta.xml 中的 <description> 和 <targetConfigs>
2. 向用户呈现排名列表，包含组件名称和描述
3. 用户选择或说“这些都不是”（→ 进入第 2 层）

何时跳过

在以下情况下跳过本地扫描：

• 用户明确提到组织级组件（“使用标准报告组件”）
• 用户意图明确映射到已知标准组件（DRL、richText 等）
• 工作区中不存在 <packageDirectory> 目录

---

混合属性推断策略

对于每个发现的组件，按顺序使用此 3 步策略填充其属性：

步骤 1：获取最新模式（条件）

仅当组件不存在于本地机器上（即第 2 层组织发现的组件）时，才调用 getUiComponentSchemas。对于本地组件（第 1 层），直接从源代码中提取 @api 属性。

何时调用：

• 第 2 层（组织发现）：始终——模式是属性信息的唯一来源
• 第 1 层（本地）：跳过——从组件的 .js 源文件中读取 @api 属性
• 第 3 层（生成）：跳过——您刚刚创建了源代码，因此属性已知

步骤 2：应用组件指令（如果存在）

运行 scripts/resolve-component-instructions.sh <namespace:component> — 如果存在，则返回指令文件路径，否则返回空字符串。

示例：

• record_flexipage:dynamicHighlights → references/record_flexipage_dynamicHighlights.md
• flexipage:fieldSection → references/flexipage_fieldSection.md
• c:expenseTracker → （空 — 无文件）

如果返回文件：阅读并遵循其推断规则、XML 模式和默认值。
如果为空：直接跳到步骤 3。

指令文件补充模式——它们提供如何从用户意图中派生值。模式中未由指令文件涵盖的任何属性在步骤 3 中解决。

步骤 3：解决剩余属性

对于任何尚未解决的属性，按此优先级顺序应用：

3a. 智能默认启发式：

属性模式	默认值
recordId	{!recordId}
objectApiName / sObjectName	页面的 <sobjectType> 值
show* / visible* / display*	true
hide* / hidden* / disabled*	false
无前缀的布尔值	false
模式指定 "default"	使用模式默认值

3b. LLM 推断：
使用组件模式 + 用户意图 + 页面上下文来推断合理的值。示例：用户说“显示最佳机会的报告” → 推断 reportName 应引用机会报告。

3c. 用户提示（最后手段）：
仅对无法推断的关键必需属性提示用户。如果用户说“跳过”，则完全省略该组件。

层特定行为

层	额外步骤	模式调用	指令
第 1 层（本地）	从源代码提取 @api 属性	否（使用源代码）	如果存在
第 2 层（组织）	—	是	如果存在
第 3 层（生成）	从刚生成的源代码中提取 @api	否（刚刚创建）	否

---

新 LWC 生成（第 3 层）

当本地（第 1 层）或组织（第 2 层）中未找到组件时，提供生成新 LWC 的选项。

触发条件

• 第 1 层和第 2 层均未命中或用户拒绝了所有候选
• 用户未明确说“跳过”或“不创建”

确认

创建前始终确认。解释：组件名称。如果用户拒绝：跳过，继续处理其他组件。

生成后

创建 LWC 包后：

1. 立即将其视为第 1 层本地组件
2. 从生成的源代码中提取 @api 属性
3. 为 recordId 和 objectApiName 应用智能默认值
4. 使用 c:{componentName} 作为 componentName 生成 FlexiPage XML

命名约定

• 从用户意图派生：“客户健康评分” → customerHealthScore
• camelCase，JS 类名中无连字符、无下划线
• 文件夹名称与类名匹配（首字母小写）：customerHealthScore/

---

参考文件索引

文件	何时阅读
references/xml_rules.md	在编写或编辑任何 FlexiPage XML 之前——编码、字段引用、标识符、部署错误
references/identifiers_and_regions.md	添加组件时——标识符算法、Facet 命名、区域选择、容器模式
references/cli_commands.md	引导新页面时——RecordPage、AppPage、HomePage 的完整 CLI 示例
references/mcp_action_examples.md	调用 MCP 操作时——discoverUiComponents 和 getUiComponentSchemas 的完整输入/输出 JSON
references/flexipage_fieldSection.md	添加带列的字段部分时
references/record_flexipage_dynamicHighlights.md	添加动态高亮面板时
references/flexipage_richText.md	添加富文本组件时
scripts/scan-lwc-components.sh	第 1 层本地工作区扫描——对 LWC 组件名称进行分词和评分，与用户查询匹配
scripts/resolve-component-instructions.sh	属性推断步骤 2——将组件定义解析为指令文件路径

要添加新的组件模式： 按照现有文件的结构创建 references/<namespace>_<componentName>.md。该技能在属性推断的步骤 2 期间自动检查该文件。

---

动态组件的验证规则

为动态添加的组件生成 XML 后，在部署前验证以下所有内容：

标识符唯一性

• 从整个 FlexiPage 文件中提取所有 <identifier> 值
• 确认零重复
• 如果冲突：自动递增后缀（_2、_3 等）

区域有效性

• 组件放置在正确的区域中，具体取决于其类型：
  • record_flexipage:dynamicHighlights → 仅 header
  • flexipage:fieldSection → main 或选项卡 facets
  • flexipage:richText → 任何区域

属性完整性

• 模式中标记为必需的所有属性都有值
• 所有值都符合预期类型（String、Boolean、valueList、Integer）
• <value> 标签中没有原始 HTML（必须进行实体编码）

结构完整性

• 组件属性引用的每个 Facet 都作为 <flexiPageRegions> 块存在
• 没有孤立 Facets（每个 Facet 仅由一个组件引用）
• 同一区域中的多个组件使用一个 <flexiPageRegions> 块，包含多个 <itemInstances>

跨组件一致性

• 对于多组件添加：标识符在所有新组件中唯一
• Facet UUID 在组件之间不冲突
• 需要单例放置的组件（dynamicHighlights、recordDetailPanelMobile）不重复