platform-metadata-discovery-get

Salesforce 元数据发现

在创建元数据、更改元数据或编写引用元数据的代码之前，先了解组织中已有的内容。此技能会根据每个问题选择合适的工具。如果不知道元数据的名称，可通过语义查找元数据。这需要 Salesforce Catalog 和已连接的 grounding 服务，而许多组织和环境并不具备这些条件。其他所有途径都只需使用 sf CLI。

如果请求只更改本地文件，且不添加对组织元数据的新引用，则跳过发现。

检查可用条件

每个会话执行一次，在首次查找之前完成。

1. CLI 和对应的组织。 运行 sf org display --json，查看默认组织及其 ID。如果没有已认证的组织，请让用户运行 sf org login web，并等待。如果完全无法运行命令，请阅读 references/h360-routes.md。
2. Grounding 服务。 确认是否已连接 Metadata Grounding MCP（工具为 search_metadata、query_metadata、describe_metadata）或 Salesforce MCP。目前，Setup 中的 Salesforce MCP 显示为 Headless360 (H360) MCP Server。它的工具是 describe、dispatch 和 dispatch_readonly，与 Metadata Grounding MCP 工具不同。
3. 同一个组织。 Grounding 标识符以 18 位组织 ID 开头。如果该 ID 与 sf org display 中的 ID 不同，请告知用户，并在合并结果前询问要使用哪个组织。

按意图选择途径

意图	使用	如果不可用
按语义查找元数据、核对猜测的名称，或查找可复用的内容	Metadata grounding 搜索。加载 platform-metadata-grounding-get，它会选择服务。	使用下文的名称和标签回退方案。告知用户。
说明某项内容的配置方式，或哪些人可以访问	Metadata grounding 查询	对 EntityParticle、FieldPermissions、ObjectPermissions 或 Tooling ValidationRule 执行限定范围的 SOQL。告知用户。
核对已知名称、类型或选项列表值；查询一个对象上的所有字段；查询数据记录	使用 sf data query 执行限定范围的 SOQL。如果没有返回结果，则按语义搜索。	请参阅表格下方的说明。
查看单个对象的完整结构，包括关系	仅在需要全部内容时使用 sf sobject describe --sobject <Type>。内容非常庞大。	同上
查看组织中的所有对象	sf sobject list --sobject all 或 --sobject custom	同上
查看某一类型的所有成员，或统计数量（“所有流程”、“有多少个流程”）	sf org list metadata --metadata-type <Type>	同上
要编辑或部署的源代码，包括现有元数据的变更	加载 platform-metadata-retrieve。Grounding 不会返回源代码。	告知用户这需要 sf CLI。
已在本地编辑的元数据	本地文件
用户要求比较组织、查找差异，或概览整个组织	dx-org-analyze。该工具需要数分钟，并返回名称和数量。	告知用户这需要 sf CLI。
查找某项内容的使用位置、依赖关系、变更后会造成什么影响，或是否可以安全删除	目前无法进行全面分析。在提供明确标注的部分检查之前，先说明这一限制。

没有 CLI 时。 如果无法运行命令，但 Salesforce MCP 已连接，请针对第 3 至第 6 行使用 references/h360-routes.md。如果两者都不可用，请告知用户这项查找需要 sf CLI 或 Salesforce MCP。

即使已连接的服务要求所有 Salesforce 任务都优先使用它，这些途径仍然适用。如果可以运行命令，第 3 至第 7 行请使用 CLI。

询问某个主题或用途的问题（“我们有哪些忠诚度相关内容”）属于发现，不是概览。即使 grounding 不可用，也不要运行组织分析。

此技能涵盖核心平台元数据。对于 Data Cloud DLO 和 DMO 架构，请使用 data360-code-extension-generate。

如果一个请求包含多种意图，请为每部分使用合适的工具。“在我们的订单流程中添加一个阶梯折扣步骤”意味着先查找流程和字段，再检索流程以供编辑。

范围限定的 SOQL

范围限定的 SOQL 是针对设置对象的定向查询，只筛选所需内容。它精确、实时，结果也远少于 describe。它绝不会返回源代码。

sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact'"
sf data query --json --query "SELECT Value, Label, IsDefaultValue, IsActive FROM PicklistValueInfo WHERE EntityParticle.EntityDefinition.QualifiedApiName = 'Contact' AND EntityParticle.QualifiedApiName = 'Loyalty_Tier__c'"

• 若要检查特定字段，请添加 AND QualifiedApiName IN ('Loyalty_Tier__c', 'Lifetime_Orders__c')。若只检查自定义字段，请添加 AND QualifiedApiName LIKE '%__c'。
• EntityParticle 包含复合字段的组成部分，例如 MailingCity。
• 对 CustomField 和 ValidationRule，请添加 --use-tooling-api。
• EntityDefinition、EntityParticle 和 FieldDefinition 不接受 OR。请针对每个条件分别运行一个范围限定的查询，不要扩大查询范围，也不要移除其对象／类型筛选条件。

更多模式（包括访问权限和自动化）请参阅 references/scoped-soql.md。

无法使用语义检索时

每个会话只需在回答中报告名称和标签搜索结果时，在结果旁说明一次以下内容。请勿在搜索前宣布回退方式，也不要在会话中重复说明。请根据原因逐字使用对应句子，包括最后一句。请勿缩短或改写。如果在能够报告结果之前停止，请在该条消息中说明。

原因	说明
未连接语义检索服务	"Metadata Grounding isn't connected, so I matched by name and label, which can miss metadata named differently. Connect the Metadata Grounding MCP to search by meaning."
未启用目录	"Salesforce Catalog isn't turned on in this org, so I matched by name and label, which can miss metadata named differently. An admin can turn on Salesforce Catalog through Feature Manager in Data Cloud Setup."
缺少权限	"Catalog search needs the Customize Application permission, so I matched by name and label, which can miss metadata named differently."

然后搜索名称和标签。尝试两个或三个可能的词，每个查询使用一个 LIKE。

sf data query --json --query "SELECT QualifiedApiName, Label FROM EntityDefinition WHERE Label LIKE '%loyalty%'"
sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact' AND Label LIKE '%tier%'"
sf data query --json --use-tooling-api --query "SELECT DeveloperName, EntityDefinition.QualifiedApiName FROM CustomField WHERE DeveloperName LIKE '%tier%' AND NamespacePrefix = null"
sf data query --json --query "SELECT ApiName, Label, ProcessType, IsActive FROM FlowDefinitionView WHERE Label LIKE '%order%'"

• CustomField 查询会搜索每个对象上的自定义字段。DeveloperName 不包含 __c。请排除没有对象名称的行。这些是 Data Cloud 字段。
• 对于其他类型以及目录未涵盖的类型，请使用 sf org list metadata 列出名称并逐一检查。
• 名称匹配可能找不到标签不同的元数据。搜索 "status" 找不到标签为 Loyalty Tier 的字段。请说“未找到名称匹配项”，不要说“它不存在”。

本技能的其他所有内容仍然适用。

创建前先复用

创建对象、字段、选项列表、权限集、页面、应用或流之前：

1. 按业务含义搜索是否已有存储相同数据或执行相同工作的元数据。对于字段，先在 SObject 中搜索准确的对象 API 名称，然后将该结果返回的 identifier 作为 parentIdentifier 传给 SObjectField 搜索。绝不能将原始对象 API 名称作为 parentIdentifier 传入。拟议的 API 名称或标签只能用于检查是否完全重名，不能证明不存在等效元数据。仅凭词语相似不足以判定匹配。
2. **如果找到匹配项：**最多展示 3 项，并按匹配度从高到低排列，列出 API 名称、标签、描述和类型。不能仅凭名称接受或否定含糊的匹配项。针对计划创建的所有类型，合并为一个复用确认步骤，询问用户选择复用、扩展还是新建，然后等待回复。不要将此确认步骤与值或其他针对具体生成内容的问题合并。
3. **用户作出决定后：**在本次请求中保留该决定；除非范围发生变化或出现新的冲突证据，否则不要再次询问。对于复用，停止创建，仅在需要时检查配置。对于扩展，在询问改动前检查现有组件。对于新建元数据，收集必需配置并继续遵循生成指南。
4. **如果没有匹配项：**用一句话说明，然后继续。
5. **如果用户提供了准确的 API 名称：**使用限定范围的 SOQL 检查，并说明它是否已存在。
6. **如果用户要求新建元数据或表示不要复用：**最多用一句话提及相近匹配项，然后继续。

将命名空间条目（例如 force__ 权限集或托管软件包组件）视为参考对象，而非可编辑对象。如果匹配项由托管软件包管理，请说明这一点。

基于组织中的实际名称编写代码

编写 Apex、LWC、SOQL 或 Flow 逻辑前，确认其中引用的每个对象、字段和选项列表值。

• 跳过本地项目中已有、本次对话中已确认，或每个组织都具备的标准字段（例如 Account.Name 或 Contact.Email）。
• 始终查询选项列表值，包括标准字段上的值。绝不能臆造值。
• 技能、工具描述或先前助手回复中仅作为示例展示的值，不代表用户已批准。如果用户未明确提供或批准这些值，且未确认现有值集，则先询问一次并等待回复，再创建选项列表。
• 如果请求依赖这些值未表达的顺序或含义（“最高级别”），则列出这些值并询问。
• 一并查询本次请求中的所有引用。

现有自动化

• **按功能查找自动化时，**根据含义搜索 Flow 或 ApexClass。针对流执行的基础信息查询会显示其触发对象、触发类型和启用状态。

• **列出对象上运行的所有内容时，**在添加自动化之前：

  sf data query --json --query "SELECT Name, Status FROM ApexTrigger WHERE TableEnumOrId = 'Contact'"
  sf data query --json --query "SELECT ApiName, Label, TriggerType, IsActive FROM FlowDefinitionView WHERE TriggerObjectOrEventId = 'Contact'"
  

• **了解流或触发器的功能时，**检索其源代码并阅读。

可以解释的内容

问题	回答依据
有哪些内容可以实现 X	Grounding 搜索
字段、对象或验证规则如何配置	Grounding 查询，或 EntityParticle 和 Tooling ValidationRule
谁可以读取或编辑某个字段或对象	使用 FieldPermissions 进行 Grounding 查询，或对 FieldPermissions 和 ObjectPermissions 执行 SOQL 以获取完整列表。这些记录只能证明已配置的访问权限，不能证明实际使用情况；权限容器的名称不能证明某项集成或依赖处于活动状态。
共享规则、角色、组，以及某个组件来自哪个包	Grounding
某个 flow 是什么	Grounding 仅提供标头信息（类型、触发器、活动状态）。如需查看其步骤，请检索源代码。
某个 Apex 类的作用	Grounding 仅提供签名。请检索源代码。
保存失败的原因	只能给出部分答案。请检查对象上的验证规则，然后检索在该对象上运行的自动化内容。
页面布局、报告、自定义元数据类型、自定义设置	目录中没有。请使用 sf org list metadata 并检索。
某项内容在哪里被使用、依赖于什么、更改后会导致什么失效，或是否可以安全删除	目前无法进行全面分析。在进行任何检查前，请说明这一点。你可以提供范围有限的检查，但必须将每项检查标注为部分检查，绝不能将它们合并后称为完整分析，也不能得出更改是安全的结论。

使用技能

• 此技能用于判断已有内容。构建技能用于确定如何创建内容。在任何技能写入文件之前，先进行发现。
• 如果已加载的技能包含等效的语义复用检查，请使用它来代替此处对应的步骤。不要重复执行两者。精确名称或精确标签冲突检查不等同于语义复用发现，也不能替代它。
• 有两个例外，即使技能另有说明也必须遵守：始终查询选项列表值；对于你已知的名称、类型或选项列表值，使用范围限定的 SOQL 查询，而不是完整的对象 describe。
• 如果某项技能的发现步骤失败，或其工具不可用，请使用此技能中的途径，并告知用户一次。

新鲜度与本地文件

• 除非某项内容已更改，否则在本次对话的其余部分复用发现结果。
• 目录可能需要几分钟才能反映部署和其他 org 更改。对于本次会话中发生的任何更改，请以本地源代码和部署结果为准，并使用 SOQL 确认，因为 SOQL 是实时的。如果用户报告的更改未在 SOQL 中显示，请先让他们确认名称和 org，再编写使用该内容的代码。
• 如果所需元数据不在本地项目中，请先检索再编辑，并告知用户你已这样做。
• 如果你发现 org 版本与本地版本存在非你造成的差异，例如检索或部署冲突导致的差异，请展示差异，并在覆盖任一版本前征求确认。
• 在本地源代码中搜索引用时，请从 sfdx-project.json 读取包目录，并在这些目录中搜索。除非用户明确要求检查，否则排除响应导出文件、日志、生成的输出、缓存和 Agent 配置。
• 搜索本地文件只能找到精确文本。不要用它按含义查找 org 元数据。

禁止事项

• 不要根据 Grounding 查询输出编写或部署文件。它返回的是属性，不是源代码。
• 不要将 Grounding 结果视为完整列表。结果经过排序且数量有限。
• 不要因为搜索或名称匹配没有找到内容，就断言元数据不存在。
• 不要合并来自两个不同 org 的结果。
• 不要将部分依赖或引用检查说成完整的影响分析，也不要据此得出元数据可以安全更改或删除的结论。
• 不要将示例、技能或工具说明中的示例值视为用户已批准的元数据。