platform-metadata-api-context-get

Salesforce Metadata API 技能

此技能提供所有 604 種 Salesforce Metadata API 類型的完整文件。使用此技能在您的 Salesforce DX 專案中建立、了解及修改 Salesforce 中繼資料 XML 檔案。

概觀

Salesforce Metadata API 可讓您擷取、部署、建立、更新或刪除組織的自訂項目。此技能提供每種中繼資料類型的詳細文件，包括：

欄位定義與資料類型
必要與選用欄位
WSDL schema 定義
範例 XML 結構
檔案命名慣例
Salesforce DX 專案中的目錄位置

如何使用此技能

重要：僅載入所需區段

請務必僅從 JSON 檔案載入您需要的特定區段，而非整個檔案。

重要：對於 assets/metadata_api/*.json 檔案，請一律使用 jq 或程式化 JSON 解析，僅擷取您需要的特定區段。 請勿透過 Read、cat、read_file 或任何會注入完整檔案的工具載入這些檔案 — 它們包含冗長的 WSDL 區段及其他區段，會浪費 60-80% 的 token。（使用 Read 載入小型檔案（例如此 SKILL.md 或索引表）是沒問題的；此規則僅適用於大型中繼資料類型 JSON 檔案。）

每個 JSON 檔案包含多個區段（fields、description、wsdl_segment 等）。大部分使用案例只需要 1-2 個區段：

欄位定義：僅載入 fields 區段
了解用途：僅載入 description 區段
XML 範例：僅載入 declarative_metadata_sample_definition 區段
預設略過：wsdl_segment（冗長 schema）、file_information、directory_location

這可將每個檔案的 token 消耗量減少 60-80%。

快速開始

若要取得特定中繼資料類型的資訊：

僅載入特定區段（最佳）："Show me only the 'fields' section from CustomObject.json"
多個區段："Show me 'fields' and 'description' from Flow.json"
避免載入整個檔案：不要要求「CustomObject 中繼資料類型」— 請指定區段

範例查詢（僅載入特定區段）

建議：

"Show me only the 'fields' section from CustomObject.json"
"What fields are in the 'fields' section of Profile.json?"
"Load the 'description' and 'fields' sections from Flow.json"
"Give me just the 'declarative_metadata_sample_definition' from ApexClass.json"

避免：

"Show me the CustomObject metadata type"（太廣泛 — 整個檔案）
"Load CustomObject.json"（包含不必要的 WSDL 及其他區段）

JSON 檔案結構

每種中繼資料類型儲存在 assets/metadata_api/ 中的 JSON 檔案，結構如下：

{
  "sections": ["title", "description", "fields", "wsdl_segment", ...],
  "title": "MetadataTypeName - Metadata API",
  "description": "Plain-text description of the metadata type.",
  "fields": {
    "fieldName": {
      "type": "string",
      "description": "Field description",
      "required": true
    }
  },
  "file_information": ".object",
  "directory_location": "objects",
  "wsdl_segment": "<xsd:complexType>...</xsd:complexType>",
  "declarative_metadata_sample_definition": [
    {
      "description": "Example description",
      "code": "<?xml version=\"1.0\"?>\n<MetadataType>...\n</MetadataType>"
    }
  ]
}

注意： 字串值（title、description、file_information、directory_location、wsdl_segment）儲存為純文字 — 沒有 markdown 標題（#/##）或程式碼圍欄。file_information 僅包含檔案後綴（例如 .object、.ai），directory_location 僅包含 SFDX 資料夾名稱（例如 objects、aiApplications）。

可用區段

sections 陣列指出每個檔案中存在的頂層鍵。常見區段包括：

title：中繼資料類型名稱與標題
description：中繼資料類型的代表意義
fields：類型自身的欄位，包含類型與描述
sub_types：（僅複合類型）被參考的子類型名稱對應到該子類型的欄位，例如 Flow → sub_types.FlowActionCall
file_information：檔案命名慣例與副檔名
directory_location：檔案在 SFDX 專案中的儲存位置
wsdl_segment：來自 WSDL 的 XML schema 定義
declarative_metadata_sample_definition：範例 XML 程式碼

某些中繼資料類型有額外的特定區段。請參閱索引表以取得完整說明。

更多詳細資訊： 關於為何 token 最佳化很重要、實際使用範例、常見工作流程、完整區段詞彙表，以及版本/支援說明的背景，位於 references/usage_guide.md。僅在需要時使用 Read 工具載入。

Token 最佳化策略

重要：為最小化 token 使用量與成本：

僅載入您需要的特定中繼資料類型，而非整個語料庫
僅從每個檔案載入特定區段，而非整個檔案

僅載入特定區段（最佳實務）

重要警告：請勿對這些 JSON 檔案使用 read_file 工具（或任何讀取整個檔案的工具）！

read_file 會將整個檔案內容載入您的上下文，破壞僅載入特定區段的目的。您會浪費 60-80% 的 token 預算載入不必要的 WSDL 區段與冗長區段。（對小型檔案（例如此 SKILL.md 或索引表）使用 Read 是沒問題的 — 此規則僅適用於大型中繼資料類型 JSON 檔案。）

方法：使用程式碼以程式化方式解析 JSON 檔案，僅擷取您需要的區段，而非使用讀取整個檔案的工具。

可用工作範例：

我們提供多種語言的完整、可運作程式碼範例：

Python：examples/python_section_loading.py — 展示 json.load() 搭配區段擷取
JavaScript/Node.js：examples/javascript_section_loading.js — 展示 JSON.parse() 搭配區段擷取
Bash + jq：examples/bash_section_loading.sh — 展示 jq 命令列 JSON 處理

請參閱 examples/README.md 以取得完整文件與使用說明。

快速模式（依您的語言調整）：

讀取 JSON 檔案
將其解析為資料結構
僅擷取您需要的區段（例如 fields、description）
忽略冗長區段（wsdl_segment、declarative_metadata_sample_definition）

不應做的事

絕對不要對這些 JSON 檔案使用 read_file 工具：

read_file assets/metadata_api/CustomObject.json  # 將整個檔案載入上下文！
read_file assets/metadata_api/Flow.json          # 浪費 60-80% token！

絕對不要載入所有檔案：

read_file assets/metadata_api/*.json  # 這會載入約 15MB 的資料！

Token 影響：

僅載入特定區段：每種中繼資料類型 50-200 token
整個檔案：每種中繼資料類型 500-2000 token
節省：每個檔案 60-80%

何時載入多種類型

相關類型：CustomObject + CustomField + ValidationRule
權限集：Profile + PermissionSet + PermissionSetGroup
UI 元件：Layout + CompactLayout + QuickAction
自動化：Flow + WorkflowRule + ApexTrigger

何時載入特定區段（強烈建議）

許多中繼資料類型有大型 WSDL 區段或廣泛的欄位清單。請務必僅從每個 JSON 檔案載入您需要的特定區段，而非消耗整個檔案：

首先，檢查可用區段：僅讀取 JSON 中的 sections 陣列
僅擷取您需要的區段（例如 fields 用於欄位定義，description 用於概觀）
略過 WSDL 區段，除非您特別需要 schema 驗證
略過 declarative_metadata_sample_definition，除非您需要完整的 XML 範例

此方法可透過排除冗長的 WSDL 定義與冗長範例，將每個檔案的 token 消耗量減少 60-80%。

使用此技能的概念方法

步驟 1：確認您的需求

問自己：

我想要建立或修改什麼？
我正在處理哪種 Salesforce 中繼資料類型？
我需要哪些特定資訊？
- 僅欄位定義？→ 載入 fields 區段
- 了解其用途？→ 載入 description 區段
- XML 範例？→ 載入 declarative_metadata_sample_definition 區段
- Schema 驗證？→ 載入 wsdl_segment 區段（很少需要）

步驟 2：找到正確的類型

使用以下方法之一：

直接參考：如果您知道類型名稱（例如 "CustomObject"）
索引搜尋：檢查 references/metadata_index_table.md 以取得相關類型
常見類型：請參閱下方「快速參考：常見中繼資料類型」

步驟 3：選擇性載入（僅載入特定區段）

區段載入決策樹：

需要欄位定義？
  → 僅載入 'fields' 區段（約 50-200 token）

需要了解類型用途？
  → 僅載入 'description' 區段（約 20-100 token）

需要 XML 結構範例？
  → 僅載入 'declarative_metadata_sample_definition'（約 100-300 token）

需要全部三個？
  → 載入 'fields' + 'description' + 'declarative_metadata_sample_definition'
  → 仍略過 'wsdl_segment'、'file_information'、'directory_location'
  → 節省：相較於載入整個檔案約 60-70%

需要 schema 驗證？
  → 僅在需要時載入 'wsdl_segment'（此區段冗長）

請求格式：

單一區段（最佳）："Show me only the 'fields' section from ApexClass.json"
多個區段："Load 'fields' and 'description' from CustomObject.json"
略過冗長區段：除非明確需要，否則絕不載入 wsdl_segment

步驟 4：套用至您的程式碼

使用載入的資訊來：

建立新的中繼資料 XML 檔案
了解專案中的現有檔案
驗證欄位名稱與類型
產生具有正確命名空間的正確 XML 結構

檔案位置

所有中繼資料類型 JSON 檔案位於：

assets/metadata_api/
├── CustomObject.json
├── Flow.json
├── ApexClass.json
├── Profile.json
└── ...（另有 600 多個檔案）

路徑解析

使用此技能時，檔案參考方式為：

絕對路徑：assets/metadata_api/CustomObject.json
相對於技能根目錄：./assets/metadata_api/CustomObject.json

技能會根據工作目錄自動解析路徑。

中繼資料檔案產生需求

產生 Salesforce 中繼資料 XML 檔案時，請遵循以下需求以確保檔案有效且可部署。

XML 結構需求

所有中繼資料檔案必須：

包含 XML 宣告：
```
<?xml version="1.0" encoding="UTF-8"?>
```

使用正確的命名空間：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

根元素對應中繼資料類型：
- CustomObject → <CustomObject>
- Flow → <Flow>
- Profile → <Profile>
- 等等

命名空間宣告

命名空間是必要的，且必須完全為：

http://soap.sforce.com/2006/04/metadata

正確：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

錯誤：

<CustomObject>  <!-- 缺少命名空間 -->
<CustomObject xmlns="http://salesforce.com/metadata">  <!-- 錯誤的命名空間 -->

必要與選用欄位

每種中繼資料類型有不同的欄位需求：

Schema 必要（JSON 中 required: true）：WSDL 將欄位標記為必要。
實際必要（未標記但實務上需要）：在許多情況下，WSDL 標記的必要欄位少於編寫合約實際要求的欄位。CustomObject 是典型範例 — JSON 僅將 externalDataSource、externalName、nameField 標記為 required: true（前兩個是外部物件專用的怪癖），但一般的 __c CustomObject 也需要 label、pluralLabel、deploymentStatus 和 sharingModel 才能部署。請務必與 declarative_metadata_sample_definition 範例交叉檢查。
條件必要：某些欄位僅在啟用特定功能時才需要。
選用：大部分欄位若不需要可省略。

CustomObject 範例（注意：實際編寫需要比 required: true 標記的更多）：

{
  "fields": {
    "nameField": {
      "type": "CustomField",
      "description": "The name field for the custom object",
      "required": true
    },
    "label": {
      "type": "string",
      "description": "The label for the custom object (effectively required for normal __c objects)",
      "required": false
    },
    "sharingModel": {
      "type": "SharingModel (enumeration)",
      "description": "The sharing model for the object (effectively required for normal __c objects)",
      "required": false
    },
    "enableHistory": {
      "type": "boolean",
      "description": "Enable field history tracking",
      "required": false
    }
  }
}

驗證提示

部署前：

驗證 XML 語法：確保 XML 格式正確（標籤配對、巢狀正確）
檢查必要欄位：確認所有必要欄位都存在
驗證命名空間：命名空間必須完全正確
測試欄位類型：確保欄位值符合預期類型
使用 Salesforce CLI：執行 sf project deploy validate 以捕捉錯誤

更多詳細資訊： 欄位類型→XML 對應表、檔案命名/雙檔案/子類型慣例，以及完整的格式正確檔案範例，位於 references/usage_guide.md。

重複與模糊的類型名稱

某些 Metadata API 類型名稱也存在於 Enterprise/Data API 或 Tooling API 物件名稱中。範例包括 ApexClass、ApexTrigger、CustomField、CustomObject、EmailTemplate、Layout、Profile、PermissionSet、RecordType、StaticResource、WebLink、ValidationRule 和 Flow。

當提示模糊時（例如 "tell me about Profile" 或 "what fields are on ApexClass"），請詢問使用者是否想要：

Metadata API XML 結構，用於來源/部署編寫（此技能，例如 .profile-meta.xml、.cls-meta.xml）。
Enterprise/Data API 執行時期 sObject/記錄參考（目前沒有專門技能 — 請回退至 Salesforce API 系列路由器）。
Tooling API 開發工具記錄參考（目前沒有專門技能 — 請回退至 Salesforce API 系列路由器）。

可解決大部分模糊性的啟發式規則（無需詢問）：

提及 package.xml、force-app/、sfdx、.meta.xml、"deploy"、"retrieve"、"authoring"、"blueprint"、"template"、"class definition" 或 "permissions"（在部署意義上）→ Metadata API（此技能）。
"What fields are on X" / "what columns" / "DML" / "SOQL" / "query" / "REST" / "sObject" / "record" / "runtime" → Enterprise/Data 或 Tooling API（其他技能）。
Tooling 特定訊號："Tooling API"、ApexCodeCoverage、EntityDefinition、TraceFlag、"code coverage"、"compile errors"、SymbolTable、偵錯記錄 → Tooling API。

無訊號時的預設規則：如果提示沒有上述任何訊號，且此技能（platform-metadata-api-context-get）是直接依名稱呼叫，則預設為 Metadata API 解讀，並明確向使用者揭露此假設（例如，「將此解讀為 .cls-meta.xml 編寫的 Metadata API 類型；如果您指的是 Tooling API 記錄或 Enterprise/Data sObject，請告知我」）。技能呼叫情境本身即為編寫/部署意圖的訊號。

疑難排解

找不到檔案

問題：找不到中繼資料類型檔案

解決方案：

檔案名稱是區分大小寫的 PascalCase，且沒有分隔符號（例如 CustomObject.json，不是 customobject.json、Custom_Object.json 或 Custom-Object.json）。
在宣告「找不到」之前，請查閱 references/metadata_index_table.md。使用此兩階段復原演算法對照索引：
1. 正規化並子字串比對（處理大小寫與分隔符號變體）：移除非英數字元並將查詢與每個索引項目轉為小寫，然後尋找子字串相符。可解析：customobject、Custom_Object、Custom-Object → CustomObject。
2. 若未命中，進行模糊比對（處理缺字母的拼寫錯誤）：使用 difflib.get_close_matches(query_normalized, index_normalized, n=3, cutoff=0.7) 或 Levenshtein 距離 ≤ 2。可解析：customfeld → CustomField、apxclass → ApexClass。純子字串比對無法復原字元刪除。
多重命中平手規則：當正規化並子字串比對傳回多個相符（例如 customobject 同時符合 CustomObject 和 CustomObjectTranslation），優先選擇正規化長度等於正規化查詢長度的項目；否則優先選擇最短的相符。
某些類型有非預期的命名慣例（無底線、無空格、無縮寫（例如 "OAuth"））；索引是唯一真相來源。

SOAP 信封 / 標頭類型（設計上精簡）

兩個相關模式需辨識：

結果類型（AsyncResult、SaveResult、DeleteResult、UpsertResult、Error、DescribeMetadataResult 等）— fields 為空，且 wsdl_segment 已填入。這些是 SOAP 回應包裝器；其 schema 完全位於 wsdl_segment。如果您需要其結構，請使用該區段。它們不是可部署的來源檔案。
SOAP 請求標頭（AllOrNoneHeader、SessionHeader、CallOptions、DebuggingHeader、OwnerChangeOptions 等）— fields 有 1-2 個最小項目，沒有 wsdl_segment。這些設定 SOAP 請求行為；它們是呼叫時選項，不是您編寫或部署的中繼資料。

在兩種情況下，精簡的 JSON 輸出是正確的。請勿嘗試編寫 .AsyncResult-meta.xml — 這些類型沒有來源檔案形式。

缺少區段

問題：JSON 檔案中沒有預期的區段

解決方案：

檢查 sections 陣列以查看可用的區段
並非所有中繼資料類型都有所有區段
某些區段是類型特定的（在索引表中註明）

欄位資訊不完整

問題：欄位定義缺少詳細資訊

解決方案：

檢查 wsdl_segment 以取得完整的 schema 定義
某些欄位有在 WSDL 中定義的複雜類型
與 Salesforce 文件交叉參考列舉值

追蹤子類型指標（例如 `ProfileObjectPermissions[]`）

當 fields 區段給出複雜類型名稱（例如 ProfileObjectPermissions[] 或 LayoutItem[] 或 ApprovalStep[]）時，該巢狀類型的子欄位不在 fields 區段中 — 它們位於該複雜類型的 wsdl_segment 中。技能的「預設略過 wsdl_segment」規則是用於簡單欄位路徑的 token 經濟性；對於巢狀類型，您需要深入鑽取。

實際範例 — 尋找 Profile 上 objectPermissions 的子欄位：

# 1. 從 fields 區段取得欄位類型名稱
jq '.fields.objectPermissions' assets/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. 使用 grep -A 從 wsdl_segment 僅擷取相符的 complexType
jq -r '.wsdl_segment' assets/metadata_api/Profile.json   | grep -A 30 'complexType name="ProfileObjectPermissions"'

grep -A N 視窗可將 token 成本維持在約 150 token，而非載入整個 wsdl_segment（大型類型可能超過 5K token）。每當 fields 傳回 Foo[] 類型且您需要 Foo 的子欄位時，請使用此模式。