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% 的令牌。（使用 Read 加载像此 SKILL.md 或索引表这样的小文件是可以的；此规则专门适用于大型元数据类型 JSON 文件。）

每个 JSON 文件包含多个部分（fields、description、wsdl_segment 等）。大多数用例只需要 1-2 个部分：

• 对于字段定义：仅加载 fields 部分
• 对于理解用途：仅加载 description 部分
• 对于 XML 示例：仅加载 declarative_metadata_sample_definition 部分
• 默认跳过：wsdl_segment（冗长的模式）、file_information、directory_location

这将每个文件的令牌消耗减少 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 文件结构

每种元数据类型存储为 assets/metadata_api/ 下的 JSON 文件，结构如下：

{
  "sections": ["title", "description", "fields", "wsdl_segment", ...],
  "title": "MetadataTypeName - Metadata API",
  "description": "元数据类型的纯文本描述。",
  "fields": {
    "fieldName": {
      "type": "string",
      "description": "字段描述",
      "required": true
    }
  },
  "file_information": ".object",
  "directory_location": "objects",
  "wsdl_segment": "<xsd:complexType>...</xsd:complexType>",
  "declarative_metadata_sample_definition": [
    {
      "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 会将整个文件内容加载到您的上下文中，破坏了按部分消费的目的。您将浪费 60-80% 的令牌预算加载不必要的 WSDL 段和冗长部分。（使用 Read 加载像此 SKILL.md 或索引表这样的小文件是可以的——此规则仅适用于大型元数据类型 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  # 将整个文件加载到上下文中！
read_file assets/metadata_api/Flow.json          # 浪费 60-80% 的令牌！

切勿加载所有文件：

read_file assets/metadata_api/*.json  # 这会加载约 15MB 的数据！

令牌影响：

• 按部分：每种元数据类型 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：选择性加载（按部分）

部分加载决策树：

需要字段定义？
  → 仅加载 'fields' 部分（约 50-200 令牌）

需要理解类型做什么？
  → 仅加载 'description' 部分（约 20-100 令牌）

需要 XML 结构示例？
  → 仅加载 'declarative_metadata_sample_definition'（约 100-300 令牌）

需要全部三个？
  → 加载 'fields' + 'description' + 'declarative_metadata_sample_definition'
  → 仍然跳过 'wsdl_segment'、'file_information'、'directory_location'
  → 节省：与加载整个文件相比约 60-70%

需要模式验证？
  → 仅然后加载 'wsdl_segment'（这是冗长的）

请求格式：

• 单个部分（最佳）："仅显示 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 多个文件）

路径解析

使用此技能时，文件引用为：

• 绝对路径：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": "自定义对象的名称字段",
      "required": true
    },
    "label": {
      "type": "string",
      "description": "自定义对象的标签（对于普通 __c 对象实际必需）",
      "required": false
    },
    "sharingModel": {
      "type": "SharingModel (枚举)",
      "description": "对象的共享模型（对于普通 __c 对象实际必需）",
      "required": false
    },
    "enableHistory": {
      "type": "boolean",
      "description": "启用字段历史跟踪",
      "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。

无信号时的默认规则：如果提示没有上述任何信号，并且此技能（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"规则是为了简单字段路径的令牌经济性；对于嵌套类型，您需要深入。

工作示例——查找 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 窗口将令牌成本保持在约 150 令牌，而不是加载整个 wsdl_segment（在大型类型上可能超过 5K 令牌）。每当 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：LWC 包，包括 JS、HTML 和元数据描述符
• AuraDefinitionBundle：Aura (Lightning) 组件包，包含组件、控制器、帮助程序文件
• StaticResource：可从 Visualforce 和 LWC 访问的上传文件（JS、CSS、图像、ZIP）
• EmailTemplate：用于工作流规则、Process Builder 或 Apex 的电子邮件模板
• Report：保存的报表定义，包括筛选器、分组和列
• Dashboard：由报表支持的仪表板组件集合

有关所有元数据类型的完整列表，请参阅索引表。