platform-flexipage-generate

何時使用此技能

當您需要以下操作時，請使用此技能：

• 建立 Lightning 頁面（RecordPage、AppPage、HomePage）
• 產生 FlexiPage 中繼資料 XML
• 在現有 FlexiPage 中新增元件
• 疑難排解 FlexiPage 部署錯誤
• 了解 FlexiPage 結構與元件設定
• 處理頁面配置或 Lightning 頁面自訂
• 編輯或更新任何 *.flexipage-meta.xml 檔案

規格

總覽

重要：建立新的 FlexiPage 時，您必須一律從 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. 安裝 templates 外掛程式：

   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 產生 Facet。

fieldSection

用途： 以欄位顯示欄位。三層巢狀：區域 → 欄 Facet → 欄位 Facet。
完整結構和 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>；元件 Facet 使用 <type>Facet</type>
• [ ] 包含 HTML/XML 的屬性值已進行實體編碼
• [ ] 沒有不必要的 <mode> 標籤（僅在元件模式需要時使用）
• [ ] 頁面名稱中沒有 __c 後綴
• [ ] 每個 Facet 僅由一個元件屬性參考

---

快速參考：CLI 命令

閱讀 references/cli_commands.md 以取得完整的 CLI 範例（RecordPage、AppPage、HomePage）和可用選項。

---

動態新增元件

強制工作流程： 所有對 FlexiPage 的元件新增都必須遵循此工作流程。請勿僅憑記憶編寫元件 XML，或略過探索。這適用於標準 OOTB 元件、自訂 LWC 元件，以及任何其他元件類型。

總覽

當使用者要求元件（例如「新增聯絡人的相關清單和報表」）時，請遵循此管線：

1. 解析意圖 → 識別所有要求的元件
2. 探索所有元件 → 透過三層探索批次處理
3. 推論屬性 → 對每個探索到的元件執行三步驟推論
4. 產生 XML → 為所有元件一起產生有效的 XML
5. 驗證 → 檢查識別碼、區域、屬性完整性

關鍵規則： 先批次探索所有元件（一次掃描、一次 MCP 呼叫），然後再為每個元件推論屬性。請勿逐個元件執行探索步驟，或交錯探索和推論。

步驟 1：解析使用者意圖

從使用者的語句中提取每個元件請求。範例：

• 「建立包含報表和相關聯絡人的 Account 頁面」→ 2 個元件：報表、相關清單
• 「新增活動、Chatter 和 Cases 的 DRL」→ 3 個元件：活動、Chatter、動態相關清單

步驟 2：三層元件探索

在進入下一層之前，先為所有元件完成每一層——請勿逐個元件執行第 1→2→3 層：

層級	來源	時機	呼叫次數
1	本機工作區掃描	一律先執行——為所有元件執行	0（僅本機）
2	discoverUiComponents MCP 動作	針對第 1 層後未解析的所有元件進行單一呼叫	1
3	產生新的 LWC 套件	僅針對第 2 層後仍未解析的元件，且使用者確認後	0

第 1 層為所有元件完成後，僅收集未解析的元件，並在單一 MCP 呼叫中傳遞給第 2 層。只有第 2 層後仍未解析的元件才會進入第 3 層。

請參閱下方的本機工作區掃描器和MCP 動作整合章節以了解詳細資訊。

步驟 3：屬性推論（每個元件）

針對每個探索到的元件，使用三步驟策略推論屬性：

1. 取得結構描述或讀取來源 — 對於第 2 層（組織）元件，呼叫 getUiComponentSchemas；對於第 1 層（本機），從來源提取 @api 屬性
2. 套用元件指示 — 如果 references/<name>.md 存在，請閱讀並遵循其推論規則
3. 解析其餘屬性 — 智慧型預設 → LLM 推論 → 使用者提示（最後手段）

請參閱下方的混合屬性推論策略以了解完整詳細資訊。

步驟 4：產生 XML

您不能做的事：

• 修改 XML 檔案中的頂層結構
• 新增任何未經三層元件探索解析的記憶元件
• 進行任何增強

在撰寫任何 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> 目錄

---

混合屬性推論策略

針對每個探索到的元件，依序使用此三步驟策略填入其屬性：

步驟 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

命名慣例

• 從使用者意圖衍生：「customer health score」→ 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	新增 Rich Text 元件時
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 或索引標籤 Facet
  • flexipage:richText → 任何區域

屬性完整性

• 結構描述中標記為必要的所有屬性都有值
• 所有值都符合預期類型（String、Boolean、valueList、Integer）
• <value> 標籤中沒有原始 HTML（必須實體編碼）

結構完整性

• 元件屬性參考的每個 Facet 都存在於 <flexiPageRegions> 區塊中
• 沒有孤立 Facet（每個 Facet 僅由一個元件參考）
• 相同區域中的多個元件使用一個 <flexiPageRegions> 區塊，包含多個 <itemInstances>

跨元件一致性

• 對於多元件新增：識別碼在 ALL 新元件中是唯一的
• Facet UUID 在元件之間不衝突
• 需要單一放置的元件（dynamicHighlights、recordDetailPanelMobile）不會重複