shopify-admin-metafield-definition-audit

用途

该技能用于盘点 Shopify 商店中所有元字段定义（涵盖 PRODUCT、VARIANT、CUSTOMER、ORDER、COLLECTION、COMPANY、LOCATION 等 owner 类型），并标记以下三类问题定义：未使用（存储值为零）、未记录（缺少描述）、以及跨 owner 类型共享 namespace.key 的重复键。定义泛滥是主题/应用 bug 和 Admin 搜索变慢的主要来源之一。该技能为只读，不执行任何变更，为定义清理工作流提供数据基础。

主要能力

枚举所有 owner 类型下的元字段定义，分页获取直至 hasNextPage 为 false。
按定义构建标记集合：unused（metafieldsCount 为 0 且 flag_unused 为 true）、undocumented（description 为 null 或空且 flag_undocumented 为 true）、duplicate_key（namespace.key 出现在多个 owner 类型上且 flag_duplicates 为 true）。
按 owner 类型分组结果并输出各标记的汇总。
支持 human 或 json 输出格式，并生成 CSV 审计文件。

使用方式

前置条件：已认证的 Shopify CLI 会话，命令为 shopify store auth --store <domain> --scopes read_products,read_customers,read_orders,read_inventory；以及范围内 owner 类型的读取权限（默认：read_products、read_customers、read_orders）。

参数：

store（string，必填）：商店域名，例如 mystore.myshopify.com。
owner_types（string，可选，默认 all）：逗号分隔的 owner 类型，例如 PRODUCT,CUSTOMER；all 扫描所有支持的类型。
flag_unused（bool，可选，默认 true）：标记 metafieldsCount 为零的定义。
flag_undocumented（bool，可选，默认 true）：标记描述为空/null 的定义。
flag_duplicates（bool，可选，默认 true）：标记存在于多个 owner 类型上的 namespace.key 对。
format（string，可选，默认 human）：输出格式，human 或 json。

工作流步骤：

根据 owner_types 确定要扫描的 owner 类型列表（默认完整列表）。
对每个 owner 类型执行 metafieldDefinitions 查询，输入 first: 250、ownerType: <TYPE>，选择 id、namespace、key、name、description、type { name }、pinnedPosition、metafieldsCount、validations { name value } 及分页游标；分页直至 hasNextPage 为 false。
为每个定义构建标记集合（unused、undocumented、duplicate_key）。
按 owner 类型分组结果并输出各标记汇总。

GraphQL 操作（已针对 api_version 2025-01 验证）：

query MetafieldDefinitionAudit($ownerType: MetafieldOwnerType!, $after: String) {
  metafieldDefinitions(first: 250, after: $after, ownerType: $ownerType) {
    edges {
      node {
        id
        namespace
        key
        name
        description
        ownerType
        pinnedPosition
        metafieldsCount
        type {
          name
          category
        }
        validations {
          name
          value
          type
        }
        access {
          admin
          storefront
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪：技能在启动、每步之后和完成时输出指定格式的状态信息（human 或 json）。

输出格式：CSV 文件 metafield_def_audit_<YYYY-MM-DD>.csv，列包括 definition_id、owner_type、namespace、key、name、type、description_present、metafields_count、pinned、is_unused、is_undocumented、is_duplicate_key、flags。

适用场景

每季度运行，以及在任何应用安装/卸载后运行——应用被移除时经常遗留其定义。
作为元字段定义清理工作流的数据基础。
与元字段值采样技能（按 owner 类型）配合，在清理前确认真实零使用情况。

限制与安全

只读技能，不执行任何变更，可随时安全运行；不会删除、更新或固定任何元字段定义。
错误处理：THROTTLED（API 速率限制）等待 2 秒重试最多 3 次；ACCESS_DENIED（缺少该资源的读取权限）跳过该 owner 类型并在 CSV 中记录警告行；metafieldsCount 返回 null 时视为未知，不标记为未使用；owner 类型在 API 版本中不受支持时跳过并警告，待 API 版本升级后重新运行。
最佳实践提醒：不要在没有先在店面主题中搜索该 namespace.key 引用的情况下批量删除未使用定义；主题 liquid 可能读取尚未保存值的定义。跨 owner 类型的重复键不总是错误，但通常表明复制粘贴创建，应审查类型和验证的一致性。
其他功能、收费、价格、平台、效果或使用步骤等未在资料中提供的信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与安全