platform-data-and-tooling-api-context-get

Salesforce Data + Tooling API 技能

此技能提供 2130 个 Salesforce 标准对象的字段级参考，涵盖两个运行时 API 层面：Enterprise/Data API（通过 SOQL 查询并使用 DML 修改的标准 sObject）和 Tooling API（ApexClass、ApexCodeCoverage、TraceFlag 和 EntityDefinition 等与开发和元数据相关的记录）。

在编写 SOQL/SOSL、构建 DML 或在运行时读取记录之前，请用它查找权威的字段名称、类型和属性，以免查询和写入因 INVALID_FIELD / “No such column” 错误而失败。

仅包含标准对象。 这些资源涵盖标准 sObject 和 Tooling 记录。自定义 __c 对象以及标准对象上的自定义 __c 字段不在此语料库中——它们没有静态文档页面。 对于这些对象和字段，请改为描述实时组织（sf sobject describe --sobject <Name>）。

概览

每个对象都以 JSON 文件记录，包含：

• 字段定义：名称、类型和属性（Createable、Filterable、Groupable、Nillable、Sortable、Updateable）
• 企业 sObject 的关系元数据（关系名称、引用对象、关系类型）
• Tooling 记录支持的 SOAP 调用和 REST HTTP 方法
• WSDL 架构片段
• 用法说明和相关对象（企业 sObject）

此技能适用于运行时数据，而非部署。 对于编写 *-meta.xml 源文件（CustomObject、Flow、Profile 等），请使用 Metadata API 技能 （platform-metadata-api-context-get）。两者相辅相成，不能互相替代。

如何使用此技能

关键：字段存在性检查（在回答前执行）

绝不要根据记忆或训练数据回答字段问题——例如“字段 X 是否存在？”、“X 是否可筛选/排序/分组？”、“X 的 API 名称/类型是什么？”这也包括 Id、Name、CreatedDate、LastModifiedDate、OwnerId、IsDeleted 等显而易见的系统字段。务必先运行查找。 你在训练中了解这些字段，但此技能之所以存在，正是因为你对其属性（Filter/Sort/Group）以及哪个目录会记录它们的记忆并不可靠。确信不等于核实。

运行一条原子命令，同时检查两个目录（字段可能存在于 fields、field_reference，也可能两者都不存在——参见下方的双目录说明）：

jq '{fields: .fields["<FieldName>"], field_reference: .field_reference["<FieldName>"]}' assets/enterprise_api/<Object>.json
# e.g. checking CreatedDate on Account:
jq '{fields: .fields["CreatedDate"], field_reference: .field_reference["CreatedDate"]}' assets/enterprise_api/Account.json

解读结果：在 fields 中找到 → 回答能力相关问题时使用其 properties。仅在 field_reference 中找到 → 字段确实存在，但无法通过此技能判断它是否可筛选/排序/分组（该目录不包含属性标志）。两者均为 null → 此语料库中没有该字段（但它可能仍是实时组织中的真实字段或自定义字段——请描述该组织）。

强制验证关卡。 陈述任何字段事实之前，你必须先在给用户的回复中逐字输出以下内容（类似元数据技能的状态行）：

field_lookup: object=<Object> field=<FieldName> checked_fields=<yes|no> checked_field_reference=<yes|no> result=<in_fields|in_field_reference|not_found>

如果你无法如实输出此行，且两项检查的结果均为 yes，则说明你尚未执行查找——请停止并运行 jq 命令。未实际运行查找时，切勿捏造“根据该技能的数据”等引用。

此关卡行仅用于对话回复中的自我验证标记——不要将它写入你为用户生成的文件（.soql、.md、.json、查询注释头等）。交付内容应只包含用户要求的答案或查询；不要在其中加入 field_lookup: 行。

关键：按需读取特定部分

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

对于 assets/enterprise_api/*.json 和 assets/tooling_api/*.json 文件，始终使用 jq 或程序化 JSON 解析，只提取需要的部分。 不要通过 Read、cat 或 read_file 整体加载这些文件——其中包含冗长的 wsdl_segment 和 field_reference 部分，对于 Account 这类大型 sObject，会浪费 60-80% 的令牌。

每个 JSON 文件都包含多个部分。大多数用例只需要 1-2 个：

• 查询/DML 字段列表：只加载 fields 部分
• 关系遍历：加载 fields（其中内含 relationship_name / refers_to 列）
• Tooling 调用支持情况：加载 supported_soap_calls / supported_rest_api_http_methods
• “此用户能否查询该对象？”/权限问题：加载 special_access_rules（对象文档中列出访问限制时，两类 API 中都会提供）
• 查询上限/不支持的子句（记录数上限、不支持 ORDER BY/queryMore()/OFFSET）：加载 limitations——仅对设有此类限制的对象提供
• 默认跳过：wsdl_segment、ispersonaccount_fields

双目录规则（必须遵守——这是最容易出错的地方）：

1. 一个字段可能存在于 fields、field_reference、两者中，或两者都不存在。这是两个不同的目录，并非包含关系。
2. 在 fields 中找不到字段，并不能说明“字段不存在”。 在得出结论前，也要检查 field_reference——上面的原子 jq 命令会一次完成这两项检查。
3. Filter/Sort/Group/Create/Update/Nillable 属性仅来自 fields。如果某字段只在 field_reference 中找到，此处就没有可检索的能力标志——请明确说明，不要猜测。

两个目录为何不同（参考信息——可选阅读）

fields 来自 Salesforce SOAP 的“Fields”表（查询/DML 属性： Create/Filter/Sort/Group/Update/Nillable）。field_reference 来自另一张面向 UI 的“Field List”表（标签/长度/精度/小数位数），有些对象会将其与 SOAP 表分开记录——而且其中可能包含许多 fields 根本没有列出的字段（例如，包含大量布尔标志字段目录的对象，或 SOAP 表省略的各种面向管理员的字段）。在整个语料库中，数千个字段仅存在于 field_reference 中，也有少量字段仅存在于 fields 中。因此，要确认字段是否存在，必须检查两者；而能力相关问题只能根据 fields 回答。

应使用哪个文件夹？

• 运行时查询和修改的标准 sObject（Account、Contact、Opportunity、Lead、Case 等）→ assets/enterprise_api/
• 开发人员/诊断记录（ApexClass、ApexCodeCoverageAggregate、TraceFlag、EntityDefinition、MetadataComponentDependency、SymbolTable）→ assets/tooling_api/
• 自定义 __c 对象和自定义 __c 字段 → 这些资源中不包含。请描述实时组织：sf sobject describe --sobject <Name> --target-org <alias>。（标准 Account 上的自定义字段，如 Region__c，也不会出现在 assets/enterprise_api/Account.json 中。）

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

请这样做：

• “仅显示 assets/enterprise_api/Account.json 中的 ‘fields’ 部分”
• “Opportunity 上哪些字段可筛选？”
• “Contact 上哪些字段是关系字段？它们关联到什么？”
• “ApexClass 在 Tooling API 中支持哪些 SOAP 调用？”
• “字段 X 不在 fields 中——请先检查 field_reference，再判断它是否不存在”

不要这样做：

• “加载 Account.json”（这会读取巨大的 wsdl_segment；请分别加载 fields 和 field_reference，不要加载整个文件）

JSON 文件结构

Enterprise（数据）sObject 位于 assets/enterprise_api/；Tooling 记录位于 assets/tooling_api/。两者共享通用核心，但也包含少数表面专属部分。

{
  "sections": ["title", "description", "fields", "wsdl_segment", ...],
  "title": "Account | Enterprise API",
  "description": "Plain-text description of the object.",
  "fields_columns": ["type", "properties", "description", "relationship_name", "refers_to", "relationship_type"],
  "fields": {
    "fieldName": {
      "type": "string | reference | picklist | ...",
      "properties": "Create, Filter, Group, Nillable, Sort, Update",
      "description": "Field description",
      "relationship_name": "(reference fields only)",
      "refers_to": "(reference fields only) e.g. Account"
    }
  },
  "wsdl_segment": "<xsd:complexType>...</xsd:complexType>"
}

fields 是一个以字段 API 名称为键的字典（例如 fields["AnnualRevenue"]），而不是列表——请使用 .items()/.keys() 迭代，不要按位置索引。

各部分的生成方式（假定部分列表固定前请先阅读）

每个 JSON 文件都根据该对象 Salesforce 文档页面上实际出现的 ## Heading 部分生成——JSON 架构并非应用于每个对象的固定统一模板。因此直接会得出两个结论：

1. 不能保证每个对象都包含某个部分，fields 也不例外。 只有源文档页面中存在匹配标题时，文件中才会包含相应部分。有些 Tooling 文档页面没有字段表（内容较少的页面或测试版页面），因此可能缺少 fields；少数 SOAP 标头风格的页面会将字段表标为单数形式的 field，而非复数形式。假定某个部分存在前，请务必检查文件自身的 sections 数组（或检查 "fields" in sections）——不要仅凭查看过一两个示例对象，就将预期写死。
2. 页面可以包含常见部分之外的额外部分，每个额外部分对应 Salesforce 在该页面上使用的一个额外 ## 标题（例如，字段引用的嵌套复杂类型，如选项列表的值元数据说明，或记录类型信息块）。这些部分会规范化为 snake_case 键，并作为独立的顶层部分存储；如果转换器将标题识别为独立子类型而非普通内容部分，则会嵌套在以子类型名称为键的 sub_types 字典中。请将下方“可用部分”列表视为常见情况，而非穷举列表——对于任何一个对象，其权威列表都是该对象自身的 sections 数组。

可用部分（常见情况，并非穷举；见上文）

• title、description、fields_columns：几乎所有对象都包含
• fields：大多数对象都包含，但请参阅上面的第 1 点——通过 sections 核实，不要想当然
• 仅限 Enterprise：usage、associated_objects、ispersonaccount_fields、field_reference、field_reference_columns
• 仅限 Tooling：supported_soap_calls、supported_rest_api_http_methods
• special_access_rules：谁可以查询/访问该对象，以及任何权限或许可证限制（例如“客户门户用户无法访问此对象”“需要 Omnistudio 许可证”）。两种表面均可能包含。判断特定用户能否执行查询前，请先阅读此部分——这是字段标志无法体现的查询资格信息。
• limitations：该对象施加的查询上限和不支持的 SOQL 子句（例如：MetadataComponentDependency 通过 Tooling API 最多可查询 2000 条记录，通过 Bulk API 2.0 最多可查询 100,000 条记录；不支持 ORDER BY、OFFSET、queryMore() 和 *Name 字段筛选）。针对包含此部分的对象编写查询前，请先阅读——这些限制无法从 fields 属性推导出来。
• wsdl_segment：架构定义（内容冗长——除非需要原始类型，否则可跳过）
• sub_types 以及上方未列出的其他 snake_case 命名部分：对象专属的嵌套架构说明，仅当该对象的文档页面包含匹配标题时才会出现——请检查文件的 sections 数组，以查明各对象包含哪些部分 fields_columns 数组会告诉你每个对象的 fields 条目包含哪些列——请逐个对象检查，不要假定字段结构固定。企业版 sObject 通常会添加 relationship_name、refers_to 和 relationship_type；Tooling 记录通常只包含 type、properties、description，但也有相当一部分 Tooling 对象包含 relationship_type，因此不要将其视为企业版专有字段。源数据中 relationship_type 的取值也存在拼写变体（例如 "Lookup" 与 "Look up"）——请宽松比较（例如 .replace(" ", "").lower()），不要进行严格的字符串相等比较。

不同对象的类型字符串大小写不一致——不要假定大小写统一。 同一概念会因源文档页面不同而采用多种大小写形式：string/String、boolean/Boolean、dateTime/DateTime/datetime。请不区分大小写地比较 type 值（例如使用 .lower()），不要用 == 与某一种大小写形式比较。除常见的 string | reference | picklist 类型外，实际数据还包括 int、boolean、double、currency、date、dateTime、textarea、address、url、phone、email、time、anyType、base64 等——请将类型列表视为开放集合。

即使对象的其他字段具有结构化的 type/properties，某个字段也可能缺少这些信息——在判定数据缺失之前，请检查 description 是否可用作备用来源。 每个对象的 JSON 都是根据该对象自己的文档页面生成的，因此，如果页面将字段的类型/属性作为散文（"Type: ... Properties: ... Description: ..."）放在单个描述段落中，而不是作为独立的表格列，那么对应的 fields 条目中的 type/properties 就会为空，这些内容则会放进 description。这可能由多种原因造成（例如，通用模板页面被多个标准对象重复使用，包括历史记录、共享、动态消息跟踪的配套对象），并且可能影响对象中的一个字段，也可能影响所有字段——最坏情况下，fields_columns 本身可能只显示 ["description"]。如果 type/properties 为空，或者 fields_columns 看起来异常精简，请检查 description 是否以 "Type: " 开头，并将其解析为备用来源，再判定字段/对象没有类型信息。

**允许的选项列表有时会出现在 description 的散文中——请先检查，再假定其缺失。**没有任何 fields 条目包含结构化的 picklistValues 列表。选项列表是否会在 description 中列出（以 "Possible values are: ..." 开头，后接各个值），完全取决于源文档页面是否为该特定字段列出这些值——很多页面会列出，也有很多不会列出（例如，由组织配置并由单独的 value-set 对象支持的选项列表，通常只会提供 "such as New, Closed, or Escalated" 之类的示例，而不会给出完整列表）。即使存在，具体格式也不一致——有时是以空格或逗号分隔的值，有时则是每行一个 Value—explanation 的破折号配对——因此没有唯一可靠的正则表达式；请提取 "Possible values are:" 之后的子字符串并逐案解析，也不要假定每个选项列表都能在此处找到可用的值集合。 字段的 description 可能会提及某种关系（例如“这是一个依赖型选项列表”“此字段控制 X”），但不会指出或解析这种关系的另一端——企业版 sObject 自身的 fields 部分并不总能提供答案。 此数据集的 Tooling API 部分记录了 Salesforce 的字段元数据对象（描述架构的架构，例如公开逐字段 describe 样式属性的对象），这些对象可能包含结构化属性，例如依赖型选项列表中控制字段的标识，而企业版 sObject 的文档页面从未明确指出这一信息。如果企业版字段的描述指向某种尚未解析的关系，请先检查 Tooling 侧的字段元数据对象是否能解答，再断定此技能中的任何位置都不存在相关数据。

给定对象的 JSON 可能包含上述常见列表以外的部分——请检查该对象自身的 sections 数组，不要假定部分类型是固定的。 源文档页面上的任何额外 ## 标题都会成为一个独立的 snake_case 命名部分（或者在转换器将其识别为独立的嵌套类型时，成为 sub_types 条目）。这些内容只会出现在文档恰好包含该标题的特定对象中——它们是针对单个对象的架构描述数据，不是可以忽略的杂项。所有可能的额外部分名称没有固定枚举；请通过 sections 按对象查找。

完整的对象列表和各对象的额外部分请参阅 索引表——该文件约有 125 KB，因此只需查找单个对象时，请用 grep -i "<ObjectName>" 搜索，而不是通读整个文件。

更多详情： references/usage_guide.md 中提供了查询/DML 示例、关系遍历模式和完整的部分术语表。仅在需要时使用 Read 工具加载该文件。

文件位置

对象 JSON 文件按 API 类型拆分：

assets/
├── enterprise_api/      # standard sObjects (SOQL/DML)
│   ├── Account.json
│   ├── Contact.json
│   └── ...
└── tooling_api/         # developer / diagnostics records
    ├── ApexClass.json
    ├── TraceFlag.json
    └── ...

文件路径相对于技能根目录，例如 assets/enterprise_api/Account.json 或 assets/tooling_api/ApexClass.json。

示例

可运行的部分加载示例（每个示例都演示：提取字段、通过 properties 查找可筛选字段、关系遍历、fields 与 field_reference 双目录，以及读取 Tooling 的 supported_rest_api_http_methods）：

• 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 处理

有关用法和属性→SOQL/DML 能力表，请参阅 examples/README.md。

查询和 DML 生成要求

针对这些对象生成 SOQL/SOSL 或 DML 时，请遵循以下规则，确保语句能够实际运行。

验证字段是否存在及其 API 名称

1. 先查找字段（两个目录，使用原子 jq），并输出 field_lookup: gate 行——即使你确定这是系统字段也不例外。 请参阅“如何使用此技能”顶部的字段存在性 Gate。Salesforce 的字段 API 名称不区分大小写，但必须对应真实字段。自定义字段以 __c 结尾；自定义关系使用 __r 遍历。
2. 不要臆造字段。 猜测列会导致 INVALID_FIELD: No such column 'X' on entity 'Y'。如果不确定，请加载 fields 部分并确认。
3. 匹配 fields 键时不要统一大小写。 至少有一个对象（LoginEventLog）在同一个 fields 字典中，同时具有 UserName 和 Username 这两个不同的真实字段——小写化或不区分大小写的查找会导致它们被静默混淆。请严格按照给定的大小写匹配键。这是两个不同的列，所含数据可能不同——它们不是同一个字段，也不是“解析为平台所选的字段”。请分别按各自准确的大小写选择和筛选；不要把它们描述为可互换，也不要说查询会“产生歧义”，因为平台将它们视为不同字段。

遵循字段属性

每个字段上的 properties 字符串决定了你可以对它执行哪些操作：

• Filter → 可用于 WHERE 子句。没有 Filter 的字段不能用于筛选。
• Sort → 可用于 ORDER BY。
• Group → 可用于 GROUP BY。
• Createable / Updateable → 可通过 insert / update DML 设置。系统字段和公式字段为只读（没有 Create/Update）——写入会失败。
• Nillable → 可以为 null；不可为空的字段在插入时为必填字段。

此技能的 properties 字符串不包含 External ID 标记——upsert 要求组织中的字段已标记为 External ID，而此标记未被此数据源收录（它只会出现在 Metadata API 描述输出中，不会出现在此技能所依据的 HTML 文档中）。要查找或设置字段的 External ID 标记，请使用 Metadata API 技能（platform-metadata-api-context-get），并检查 CustomField 的 externalId 属性——不要仅凭此技能中的属性猜测用于 upsert 的字段。

关系（企业 sObject）

对于 reference 类型的字段，relationship_name 列给出了用于 SOQL 遍历的父关系，而 refers_to 列出了目标对象：

-- OwnerId (reference, relationship_name = Owner, refers_to = User)
SELECT Id, Owner.Name FROM Account
-- Custom lookup Foo__c traverses as Foo__r
SELECT Id, Foo__r.Name FROM My_Object__c

Tooling API 与 Data API

Tooling 记录（assets/tooling_api/）通过 Tooling API 端点（/services/data/vXX.0/tooling/query）查询，而不是通过常规 Data API。请检查 supported_soap_calls / supported_rest_api_http_methods，了解每种记录支持的操作。许多 Tooling 对象是只读的。

不用于部署。 要编写或编辑 *-meta.xml 源（CustomObject、 Flow、Profile，……），请使用 Metadata API 技能——此处的对象是运行时/可查询的表示形式，而不是可部署的元数据形式。

重名和含义模糊的对象

元数据 API 和此处都有一些同名对象（ApexClass、ApexTrigger、 CustomField、CustomObject、EmailTemplate、Layout、Profile、PermissionSet、 RecordType、ValidationRule、Flow，等等）。它们代表不同的内容：

• 此技能 = 可在运行时查询的记录：可通过 SELECT 选择、筛选，以及（有时）通过 Data 或 Tooling API 写入的字段。
• Metadata API 技能 = 你编写并部署的 *-meta.xml 源格式。

根据以下信号消除歧义：

• “query”、“SOQL”、“SOSL”、“DML”、“insert/update/upsert”、“有哪些字段/列”、 “可筛选”、“record”、“runtime”、“REST/SOAP” → 此技能。
• “编写”、“deploy”、“retrieve”、package.xml、force-app/、sfdx、 .meta.xml、“蓝图/模板” → Metadata API 技能。
• Tooling 专属：“Tooling API”、ApexCodeCoverage、EntityDefinition、 TraceFlag、SymbolTable、“代码覆盖率”、“编译错误”、“调试日志” → 此技能中的 Tooling 部分（assets/tooling_api/）。

如果用户只按名称直接调用，且没有其他信号，则默认采用运行时数据的解释，并说明这一假设。

故障排查

找不到文件

• 文件名区分大小写，采用与对象 API 名称相同的 PascalCase 格式（Account.json、ApexClass.json），不含分隔符。
• 检查正确的文件夹：企业 sObject 位于 assets/enterprise_api/， Tooling 记录位于 assets/tooling_api/。一个名称可能只存在于其中一个文件夹，也可能在两个文件夹中都有，但字段不同。
• 在判定“找不到”之前，请使用有针对性的 grep 搜索索引表（其中列出了语料库中的所有对象名称），而不要读取整个约 125 KB 的文件： grep -i "<ObjectName>" references/data_and_tooling_index_table.md。匹配时不区分大小写，并在确认对象不存在之前，考虑近似匹配（空格、复数形式、轻微拼写差异）。只有在需要全面调查时才读取整个文件。

INVALID_FIELD / No such column

• 该字段不属于此对象，或者你使用了错误的 API 名称。加载 fields 部分并确认准确名称（自定义字段以 __c 结尾）。
• 字段存在，但不具备所需属性：筛选非 Filter 字段、排序非 Sort 字段，或写入只读字段（没有 Create/Update）都会失败。检查 properties 字符串。

关系查询失败

• 使用 relationship_name（而非 id 字段）进行遍历：Owner.Name，而不是 OwnerId.Name。自定义查找关系使用 __r 遍历。
• 确认 refers_to — 多态字段（例如 WhoId、WhatId）可关联多个对象，需要使用 TYPEOF 或正确的关系。

Tooling 查询没有结果 / 出错

• 必须通过 Tooling API 端点（/tooling/query）查询 Tooling 对象， 而不是使用标准 Data API。通过 supported_rest_api_http_methods / supported_soap_calls 验证。

字段位于 wsdl_segment，但不在 fields 中

• 复杂的嵌套类型会在 wsdl_segment 中列出其子字段。使用 jq -r '.wsdl_segment' file.json | grep -A 30 'complexType name="Foo"' 仅提取匹配的 complexType，而不要加载整个片段。

常见对象

Enterprise / Data API（SOQL + DML）

• Account：表示一个账户，即与你的业务有关的组织或个人（例如客户、竞争对手和合作伙伴）。
• Contact：表示一个联系人，即与某个账户关联的个人。
• Opportunity：表示一个商机，即一笔销售或待成交的交易。
• Lead：表示一个潜在客户。
• Case：表示一个案例，即客户提出的问题或遇到的故障。
• User：表示组织中的用户。
• Task：表示一项业务活动，例如拨打电话或其他待办事项。
• Event：表示日历中的事件。

工具 API（开发者记录）

• ApexClass：表示已保存的 Apex 类副本。
• ApexTrigger：表示已保存的 Apex 触发器副本。
• ApexCodeCoverageAggregate：表示 Apex 类或触发器的汇总代码覆盖率测试结果。
• TraceFlag：表示一个跟踪标记，可在指定的日志记录级别触发 Apex 调试日志。
• EntityDefinition：提供基于行的方式来访问标准对象和自定义对象的元数据。