platform-metadata-api-context-get

Salesforce Metadata API 技能

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

概述

Salesforce Metadata API 可用于检索、部署、创建、更新或删除组织中的自定义设置。此技能提供每种元数据类型的详细文档，包括：

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

如何使用此技能

重要：仅读取特定部分

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

重要：对于 assets/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

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

快速开始

如需了解某种特定元数据类型的信息：

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 文件形式存储在 assets/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 中提供了关于 令牌优化为何重要 的背景信息、实际使用示例、常见工作流、完整章节术语表，以及版本和支持说明。仅在需要时使用 Read 工具加载。

令牌优化策略

重要：为最大限度地减少令牌用量和成本：

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

按章节加载（最佳实践）

重要警告：请勿对这些 JSON 文件使用 read_file 工具（或任何整文件读取工具）！

read_file 会将整个文件内容加载到上下文中，违背按章节读取的目的。加载不必要的 WSDL 片段和冗长章节会浪费 60-80% 的令牌预算。（对这类 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 assets/metadata_api/CustomObject.json  # Loads entire file into context!
read_file assets/metadata_api/Flow.json          # Wastes 60-80% tokens!

绝不要加载所有文件：

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

令牌影响：

• 按章节加载：每种元数据类型 50-200 个令牌
• 整个文件：每种元数据类型 500-2000 个令牌
• 节省：每个文件 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 文件都位于：

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

路径解析

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

• 绝对路径：assets/metadata_api/CustomObject.json
• 相对于技能根目录：./assets/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、“部署”、“检索”、“编写”、“蓝图”、“模板”、“类定义”或部署语境中的“权限” → Metadata API（此技能）。
• “X 有哪些字段”／“有哪些列”／“DML”／“SOQL”／“查询”／“REST”／“sObject”／“记录”／“运行时” → Enterprise/Data 或 Tooling API（其他技能）。
• Tooling 专属信号：“Tooling API”、ApexCodeCoverage、EntityDefinition、TraceFlag、“代码覆盖率”、“编译错误”、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 信封／标头类型（有意保持精简）

需要识别两种相关模式：

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' assets/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. Pull just the matching complexType from wsdl_segment using grep -A
jq -r '.wsdl_segment' assets/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：由报表提供数据的仪表板组件集合

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