getting-metadata-api-context

Salesforce Metadata API Skill

此 Skill 提供 604 种 Salesforce Metadata API 类型的完整文档。使用此 Skill 可在 Salesforce DX 项目中创建、理解和修改 Salesforce 元数据 XML 文件。

概述

Salesforce Metadata API 允许你检索、部署、创建、更新或删除组织中的自定义项。此 Skill 提供每种元数据类型的详细文档，包括：

• 字段定义和数据类型
• 必填字段与可选字段
• WSDL 架构定义
• XML 结构示例
• 文件命名约定
• Salesforce DX 项目中的目录位置

如何使用此 Skill

⚡ 重要：按需读取特定部分

始终只读取 JSON 文件中所需的特定部分，不要读取整个文件。

重要：对于 data/metadata_api/*.json 文件，始终使用 jq 或以编程方式解析 JSON，只提取所需的特定部分。 不要通过 Read、cat、read_file 或任何会载入整个文件的工具读取这些文件——它们包含冗长的 WSDL 片段和其他部分，会浪费 60-80% 的 token。（可以使用 Read 读取此类小文件，例如 SKILL.md 或索引表；此规则仅适用于大型元数据类型 JSON 文件。）

每个 JSON 文件都包含多个部分（字段、描述、wsdl_segment 等）。大多数情况下只需要 1-2 个部分：

• 获取字段定义：仅读取 fields 部分
• 了解用途：仅读取 description 部分
• 查看 XML 示例：仅读取 declarative_metadata_sample_definition 部分
• 默认跳过：wsdl_segment（冗长的架构）、file_information、directory_location

这样可将每个文件的 token 消耗减少 60-80%。

快速入门

若要获取特定元数据类型的信息：

1. 按需读取特定部分（最佳）：“仅显示 CustomObject.json 中的 'fields' 部分”
2. 读取多个部分：“显示 Flow.json 中的 'fields' 和 'description'”
3. 避免读取整个文件：不要询问“CustomObject 元数据类型”——请指定所需部分

查询示例（按需读取特定部分）

• ✅ “仅显示 CustomObject.json 中的 'fields' 部分”
• ✅ “Profile.json 的 'fields' 部分中有哪些字段？”
• ✅ “读取 Flow.json 的 'description' 和 'fields' 部分”
• ✅ “只提供 ApexClass.json 中的 'declarative_metadata_sample_definition'”
• ❌ “显示 CustomObject 元数据类型”（范围太广——会读取整个文件）
• ❌ “读取 CustomObject.json”（会包含不必要的 WSDL 和其他部分）

JSON 文件结构

每种元数据类型都以 JSON 文件的形式存储在 data/metadata_api/ 中，结构如下：

{
  "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 架构定义
• declarative_metadata_sample_definition：XML 代码示例

部分元数据类型还包含与其功能相关的其他章节。完整分类请参见 索引表。

更多详情： references/usage_guide.md 中介绍了 token 优化的重要性、详细的使用示例、常见工作流、完整的章节术语表，以及版本和支持说明。仅在需要时使用 Read 工具加载。

Token 优化策略

重要：为尽量减少 token 用量和成本：

1. 仅加载所需的特定元数据类型，不要加载整个语料库
2. 仅加载每个文件中的特定章节，不要加载整个文件

按章节加载（最佳实践）

⚠️ 严重警告：切勿对这些 JSON 文件使用 read_file 工具（或任何读取整个文件的工具）！

read_file 会将整个文件内容加载到上下文中，违背按章节加载的目的。加载不需要的 WSDL 片段和冗长章节会浪费 60-80% 的 token 预算。（对本 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。

快速步骤（根据所用语言调整）：

1. 读取 JSON 文件
2. 将其解析为数据结构
3. 仅提取所需章节（例如 fields、description）
4. 忽略冗长章节（wsdl_segment、declarative_metadata_sample_definition）

禁止事项

❌ 切勿对这些 JSON 文件使用 read_file 工具：

read_file data/metadata_api/CustomObject.json  # Loads entire file into context!
read_file data/metadata_api/Flow.json          # Wastes 60-80% tokens!

❌ 切勿加载所有文件：

read_file data/metadata_api/*.json  # This loads ~15MB of data!

Token 用量影响：

• 按章节加载：每种元数据类型 50-200 个 token
• 整个文件：每种元数据类型 500-2000 个 token
• 节省：每个文件 60-80%

何时加载多种类型

• 相关类型：CustomObject + CustomField + ValidationRule
• 权限集：Profile + PermissionSet + PermissionSetGroup
• UI 组件：Layout + CompactLayout + QuickAction
• 自动化：Flow + WorkflowRule + ApexTrigger

何时加载特定区段（强烈推荐）

许多元数据类型包含较大的 WSDL 片段或大量字段列表。始终只从每个 JSON 文件中加载所需的特定区段，而不是读取整个文件：

1. 首先，通过仅读取 JSON 中的 sections 数组来检查可用区段
2. 仅提取所需区段（例如，字段定义用 fields，概览用 description）
3. 跳过 WSDL 片段，除非确实需要进行架构验证
4. 跳过 declarative_metadata_sample_definition，除非需要完整的 XML 示例

这种做法可以通过排除冗长的 WSDL 定义和篇幅较长的示例，将每个文件的令牌消耗减少 60-80%。

使用此技能的概念性方法

步骤 1：确定需求

问问自己：

• 我想构建或修改什么？
• 我正在处理哪些 Salesforce 元数据类型？
• 我需要哪些具体信息？
  • 仅需字段定义？→ 加载 fields 区段
  • 想了解它的作用？→ 加载 description 区段
  • 需要 XML 示例？→ 加载 declarative_metadata_sample_definition 区段
  • 需要进行架构验证？→ 加载 wsdl_segment 区段（很少需要）

步骤 2：查找正确的类型

使用以下任一方法：

• 直接引用：如果你知道类型名称（例如，“CustomObject”）
• 索引搜索：在 references/metadata_index_table.md 中查找相关类型
• 常见类型：参见下方的“快速参考：常见元数据类型”区段

步骤 3：选择性加载（按区段加载）⚡

区段加载决策树：

Need field definitions?
  → Load ONLY 'fields' section (~50-200 tokens)

Need to understand what the type does?
  → Load ONLY 'description' section (~20-100 tokens)

Need XML structure example?
  → Load ONLY 'declarative_metadata_sample_definition' (~100-300 tokens)

Need all three?
  → Load 'fields' + 'description' + 'declarative_metadata_sample_definition'
  → Still skip 'wsdl_segment', 'file_information', 'directory_location'
  → Savings: ~60-70% vs loading entire file

Need schema validation?
  → Only then load 'wsdl_segment' (this is verbose)

请求格式：

• 单个区段（最佳）：“只显示 ApexClass.json 中的 'fields' 区段”
• 多个区段：“从 CustomObject.json 加载 'fields' 和 'description'”
• 跳过冗长区段：除非明确需要，否则切勿加载 wsdl_segment

步骤 4：应用到代码中

使用加载的信息来：

• 创建新的元数据 XML 文件
• 了解项目中现有的文件
• 验证字段名称和类型
• 使用正确的命名空间生成正确的 XML 结构

文件位置

所有元数据类型的 JSON 文件均位于：

data/metadata_api/
├── CustomObject.json
├── Flow.json
├── ApexClass.json
├── Profile.json
└── ... (600 more files)

路径解析

使用此技能时，文件的引用方式如下：

• 绝对路径：data/metadata_api/CustomObject.json
• 相对于技能根目录：./data/metadata_api/CustomObject.json

此技能将根据工作目录自动解析路径。

元数据文件生成要求

生成 Salesforce 元数据 XML 文件时，请遵循以下要求，以确保文件有效且可部署。

XML 结构要求

所有元数据文件必须：

1. 包含 XML 声明：

   <?xml version="1.0" encoding="UTF-8"?>
   

2. 使用正确的命名空间：

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

3. 使根元素与元数据类型匹配：

   • 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">  

必需字段与可选字段

每种元数据类型的字段要求各不相同：

• 架构必需（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
    }
  }
}

验证提示

部署前：

1. 验证 XML 语法：确保 XML 格式良好（标签匹配、嵌套正确）
2. 检查必需字段：确认所有必需字段均已提供
3. 验证命名空间：命名空间必须完全准确
4. 测试字段类型：确保字段值符合预期类型
5. 使用 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。

当提示词含义不明确时（例如“介绍一下 Profile”或“ApexClass 上有哪些字段”），请询问用户想要的是：

1. Metadata API XML 结构，用于源代码／部署编写（此技能，例如 .profile-meta.xml、.cls-meta.xml）。
2. Enterprise/Data API 运行时 sObject／记录参考（目前没有专用技能——请回退到 Salesforce API 系列路由器）。
3. Tooling API 开发工具记录参考（目前没有专用技能——请回退到 Salesforce API 系列路由器）。

无需询问即可消除大多数歧义的判断方法：

• 提及 package.xml、force-app/、sfdx、.meta.xml、“deploy”、“retrieve”、“authoring”、“blueprint”、“template”、“class definition”，或部署语境中的“permissions” → Metadata API（此技能）。
• “X 上有哪些字段”／“有哪些列”／“DML”／“SOQL”／“query”／“REST”／“sObject”／“record”／“runtime” → Enterprise/Data 或 Tooling API（其他技能）。
• Tooling 专属信号：“Tooling API”、ApexCodeCoverage、EntityDefinition、TraceFlag、“code coverage”、“compile errors”、SymbolTable、调试日志 → Tooling API。

无信号时的默认规则：如果提示词中没有上述任何信号，且用户直接按名称调用了此技能（getting-metadata-api-context），则默认按 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 信封／标头类型（有意保持精简）

需要识别两种相关模式：

1. 结果类型（AsyncResult、SaveResult、DeleteResult、UpsertResult、Error、DescribeMetadataResult 等）——fields 为空，且已填充 wsdl_segment。这些是 SOAP 响应包装器；其架构完全位于 wsdl_segment 中。如需了解其结构，请读取该部分。它们不是可部署的源文件。
2. SOAP 请求标头（AllOrNoneHeader、SessionHeader、CallOptions、DebuggingHeader、OwnerChangeOptions 等）——fields 中有 1–2 个最精简的条目，且没有 wsdl_segment。这些用于配置 SOAP 请求行为；它们是调用时选项，不是需要编写或部署的元数据。

在这两种情况下，精简的 JSON 输出都是正确的。不要尝试编写 .AsyncResult-meta.xml——这些类型没有源文件形式。

缺少部分

问题：JSON 文件中没有预期的部分

解决方案：

• 检查 sections 数组，查看有哪些可用内容
• 并非所有元数据类型都包含所有部分
• 某些部分仅适用于特定类型（索引表中有说明）

字段信息不完整

问题：字段定义缺少详细信息

解决方案：

• 检查 wsdl_segment，获取完整的架构定义
• 某些字段具有在 WSDL 中定义的复杂类型
• 查阅 Salesforce 文档，核对枚举值

跟进子类型指针（例如 ProfileObjectPermissions[]）

当 fields 部分给出的复杂类型名称为 ProfileObjectPermissions[]、LayoutItem[] 或 ApprovalStep[] 时，这些嵌套类型的子字段不在 fields 部分中——它们位于该复杂类型的 wsdl_segment 中。技能中“默认跳过 wsdl_segment”的规则旨在节省处理简单字段路径时的 token；对于嵌套类型，你需要继续深入查找。

操作示例——查找 Profile 上 objectPermissions 的子字段：

# 1. Get the field type name from the fields section
jq '.fields.objectPermissions' data/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. Pull just the matching complexType from wsdl_segment using grep -A
jq -r '.wsdl_segment' data/metadata_api/Profile.json   | grep -A 30 'complexType name="ProfileObjectPermissions"'

grep -A N 窗口可将 token 成本控制在约 150 个，而无需加载整个 wsdl_segment（对于大型类型，其内容可能超过 5K 个 token）。每当 fields 返回 Foo[] 类型，且你需要 Foo 的子字段时，都可以使用此模式。

XML 生成错误

问题：生成的 XML 未通过验证

解决方案：

• 确认命名空间完全一致：http://soap.sforce.com/2006/04/metadata
• 检查所有必填字段是否齐全
• 确保字段值符合预期类型
• 验证 XML 语法（闭合标签、正确嵌套）

部署失败

问题：元数据文件无法部署

解决方案：

• 先运行 sf project deploy validate
• 检查 Salesforce API 版本兼容性
• 确认文件命名符合规范
• 确保目录结构符合 SFDX 格式

快速参考：常见元数据类型

以下是最常用的元数据类型：

• CustomObject：定义自定义 sObject 的架构，包括字段、关系和设置
• Flow：使用由元素和连接器组成的可视化画布自动化业务流程
• ApexClass：编译后的 Apex 服务端类；包含类主体、API 版本和状态
• ApexTrigger：在特定 sObject 的 DML 事件前后执行的 Apex 代码
• Profile：控制用户配置文件的对象/字段权限、应用可见性和登录设置
• PermissionSet：可独立于用户配置文件授予用户的附加权限集
• CustomField：定义标准对象或自定义对象上的字段，包括类型、选项列表值和公式
• Layout：控制记录详情页/编辑页上字段和相关列表的排列方式
• ValidationRule：当公式条件为真时阻止保存，以确保数据质量
• ApexPage：Visualforce 页面定义，包括控制器引用和标记
• ApexComponent：可嵌入页面的可复用 Visualforce 组件
• CustomTab：定义指向自定义对象、Visualforce 页面或 Web URL 的选项卡
• CustomApplication：定义应用的选项卡栏、导航项和品牌样式
• LightningComponentBundle：包含 JS、HTML 和元数据描述符的 LWC 捆绑包
• AuraDefinitionBundle：包含组件、控制器和辅助文件的 Aura（Lightning）组件捆绑包
• StaticResource：上传的文件（JS、CSS、图像、ZIP），可从 Visualforce 和 LWC 访问
• EmailTemplate：用于工作流规则、Process Builder 或 Apex 的电子邮件模板
• Report：已保存的报表定义，包括筛选条件、分组和列
• Dashboard：由报表提供数据的仪表板组件集合

如需查看所有元数据类型的完整列表，请参阅 索引表。