SuperAPI AI 工具集

platform-metadata-discovery-get

编程与开发

查看项目

更新于 10-31 08:29

技能介绍

用途

本技能用于在创建、修改 Salesforce 元数据,或编写引用元数据的代码之前,先查明组织(org)中已经存在什么。它根据问题意图为每个查询挑选合适的工具,避免重复创建、引用错误名称或遗漏已有配置。

主要能力

  • 按语义查找元数据:当不知道元数据名称时,通过 Metadata Grounding MCP(工具 search_metadata、query_metadata、describe_metadata)按含义查找。此路径需要 Salesforce Catalog 和已连接的 grounding 服务器,许多组织和环境并不具备。
  • 按名称与标签回退查找:grounding 不可用时,用 scoped SOQL 按名称和标签匹配,并明确告知用户该方式可能遗漏命名不同的元数据。
  • 精确查询:用 scoped SOQL 查询 EntityParticle、FieldPermissions、ObjectPermissions、Tooling ValidationRule 等,检查已知的名称、类型、选项列表值、某对象的所有字段或数据记录。
  • 列出与描述:用 sf sobject describe 查看单个对象的完整结构(含关系),用 sf sobject list 列出全部对象,用 sf org list metadata 列出某类型的所有成员或计数。
  • 检索源码:需要编辑或部署时加载 platform-metadata-retrieve,grounding 从不返回源码。
  • 组织对比与概览:用 dx-org-analyze 比较组织、发现漂移或获取整体概览(耗时数分钟,返回名称与计数)。
  • 复用检查:创建对象、字段、选项列表、权限集、页面、应用或流程前,按业务含义搜索已有元数据,展示最多 3 个最佳匹配并等待用户决定复用、扩展还是新建。
  • 代码引用确认:编写 Apex、LWC、SOQL 或 Flow 逻辑前,确认每个对象、字段和选项列表值真实存在,选项列表值必须查询,不得凭空编造。
  • 现有自动化检查:用 scoped SOQL 查询 ApexTrigger 和 FlowDefinitionView,了解某对象上已运行的自动化。

使用方式

  1. 会话初始化:每个会话在首次查找前执行一次。运行 sf org display --json 查看默认组织及其 id;若无已认证组织,请用户运行 sf org login web 并等待。确认 Metadata Grounding MCP 或 Salesforce MCP(即 Headless360 MCP Server,工具为 describe、dispatch、dispatch_readonly)是否已连接。grounding 标识符以 18 位组织 id 开头,若与 sf org display 的 id 不同,需先询问用户使用哪个组织。
  2. 按意图路由:按语义查找用 grounding search;解释配置或访问权限用 grounding query 或 scoped SOQL;检查已知名称、类型、选项列表值用 scoped SOQL;查看单对象完整结构用 sf sobject describe;列出全部对象用 sf sobject list;列出某类型全部成员用 sf org list metadata;需要源码编辑或部署时加载 platform-metadata-retrieve;本地已编辑的元数据直接读本地文件;组织对比或概览用 dx-org-analyze。
  3. scoped SOQL 示例:
    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 (...);仅自定义字段可加 AND QualifiedApiName LIKE '%__c'。CustomField 和 ValidationRule 需加 --use-tooling-api。EntityDefinition、EntityParticle、FieldDefinition 不接受 OR,每个条件单独查询。
  4. grounding 不可用时的回退:按原因(未连接 grounding 服务器、Catalog 未启用、缺少权限)使用对应固定说明语句,然后按名称和标签搜索,尝试两三个可能词,每个查询一个 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%'"
    
    名称匹配会遗漏标签不同的元数据,应说“未找到名称匹配”,而非“不存在”。
  5. 复用检查流程:创建前按业务含义搜索;找到匹配则展示最多 3 个(API 名称、标签、描述、类型),不凭名称接受或拒绝模糊匹配,提供复用、扩展或新建的合并检查点并等待;用户决定后保留该决定,除非范围变化或出现新冲突证据。若用户给出确切 API 名称,用 scoped SOQL 检查并说明是否已存在。命名空间项(如 force__ 权限集或托管包组件)视为引用而非可编辑对象。
  6. 代码引用确认:跳过本地项目已有、本对话已确认或每个组织都有的标准字段(如 Account.Name、Contact.Email)。选项列表值必须查询,包括标准字段。技能、工具描述或先前回复中仅作示例的值不算用户批准的值。若请求依赖值未说明的顺序或含义(如“最高层级”),列出值并询问。

适用场景

  • 创建新对象、字段、选项列表、权限集、页面、应用或流程前的复用检查。
  • 编写 Apex、LWC、SOQL 或 Flow 逻辑前确认引用的对象、字段和选项列表值。
  • 检查某对象上已有的自动化(触发器、流程)。
  • 解释字段、对象或验证规则的配置方式,或谁可以读取/编辑字段或对象。
  • 比较组织、发现漂移或获取组织概览。
  • 需要编辑或部署源码时检索现有元数据。

限制

  • 元数据 grounding 需要 Salesforce Catalog 和已连接的 grounding 服务器,许多组织和环境不具备。
  • grounding 结果是有排序和上限的,不能当作完整列表。
  • grounding 查询返回属性而非源码,不能据此编写或部署文件。
  • 页面布局、报表、自定义元数据类型、自定义设置不在 catalog 中,需用 sf org list metadata 并检索。
  • 关于“某物在哪里被使用、什么依赖它、修改会破坏什么、是否可安全删除”的全面分析尚不可用;只能提供明确标注为局部的检查,不得将其合并呈现为完整影响分析。
  • catalog 反映部署和组织变更可能需数分钟;本会话内变更应信任本地源码和部署结果,并用实时 SOQL 确认。
  • 本地文件搜索只能找到精确文本,不能用于按含义查找组织元数据。
  • 不得合并来自两个不同组织的结果。
  • 不得因搜索或名称匹配无结果就断言元数据不存在。
  • 不得将示例、技能或工具描述中的说明性值当作用户批准的元数据。
  • 本技能覆盖核心平台元数据;Data Cloud DLO 和 DMO schema 应使用 data360-code-extension-generate。