用途
该技能用于查询符合筛选条件的商品（或变体、或客户），并批量设置或批量删除元字段值。它适用于结构化数据更新，例如材质成分、护理说明、产品规格，或驱动店面功能的自定义属性。
前置条件
需要已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,write_products
API 权限范围：read_products、write_products
元字段的命名空间（namespace）和键（key）必须已存在，或在首次设置时创建。
参数
store：字符串，必填，无默认值，商店域名（例如 mystore.myshopify.com）。
resource_type：字符串，可选，默认 product，要更新的资源类型：product、variant 或 customer。
filter：字符串，必填，无默认值，筛选查询（例如 tag:summer-2026、vendor:Nike）。
namespace：字符串，必填，无默认值，元字段命名空间（例如 custom）。
key：字符串，必填，无默认值，元字段键（例如 material）。
value：字符串，可选，无默认值，要设置的值。如果省略且 action: delete，则删除元字段。
value_type：字符串，可选，默认 single_line_text_field，元字段类型（例如 single_line_text_field、boolean、number_integer）。
action：字符串，可选，默认 set，可选 set 或 delete。
dry_run：布尔值，可选，默认 true，预览而不执行变更。
format：字符串，可选，默认 human，输出格式：human 或 json。
安全性
⚠️ metafieldsSet 会覆盖现有元字段值——没有合并操作。metafieldsDelete 会从资源中永久移除元字段值。请使用 dry_run: true 运行，以确认受影响的商品列表，并在提交前验证命名空间/键是否正确。
工作流步骤
操作：products — 查询 输入：query: <filter>、first: 250、为目标命名空间/键选择元字段值、分页游标。 预期输出：带有现有元字段值的商品（供参考）；分页直到 hasNextPage: false。
操作：metafieldsSet — 变更（如果 action: set） 输入：{ ownerId, namespace, key, value, type } 对象数组。 预期输出：metafields { id, key, value }、userErrors。
操作：metafieldsDelete — 变更（如果 action: delete） 输入：{ ownerId, namespace, key } 对象数组。 预期输出：deletedMetafields { ownerId }、userErrors。
GraphQL 操作
products:query — 已针对 api_version 2025-01 验证
query ProductsWithMetafield($query: String!, $namespace: String!, $key: String!, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title metafield(namespace: $namespace, key: $key) { id value type } } } pageInfo { hasNextPage endCursor } } }
metafieldsSet:mutation — 已针对 api_version 2025-01 验证
mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $metafields) { metafields { id namespace key value type owner { ... on Product { id title } } } userErrors { field message code } } }
metafieldsDelete:mutation — 已针对 api_version 2025-01 验证
mutation MetafieldsDelete($metafields: [MetafieldIdentifierInput!]!) { metafieldsDelete(metafields: $metafields) { deletedMetafields { ownerId namespace key } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段发出以下输出。这是强制性的。
开始时，发出：
╔══════════════════════════════════════════════╗ ║ SKILL: Metafield Bulk Update ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
每一步之后，发出：
[N/TOTAL] <QUERY|MUTATION> <OperationName> → Params: <brief summary of key inputs> → Result: <count or outcome>
如果 dry_run: true，则在每个变更步骤前加上 [DRY RUN] 前缀，并且不执行它。
完成时，发出：
对于 format: human（默认）：
══════════════════════════════════════════════ OUTCOME SUMMARY Resources matched: <n> Metafields set/deleted: <n> Errors: <n> Output: metafield_update_<date>.csv ══════════════════════════════════════════════
对于 format: json，发出：
{ "skill": "metafield-bulk-update", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": true, "namespace": "<ns>", "key": "<key>", "action": "set", "outcome": { "matched": 0, "updated": 0, "errors": 0, "output_file": "metafield_update_<date>.csv" } }
输出格式
CSV 文件 metafield_update_<YYYY-MM-DD>.csv，包含列：resource_type, resource_id, title, namespace, key, old_value, new_value, action
错误处理
错误：THROTTLED 原因：API 速率限制超出 恢复：等待 2 秒，最多重试 3 次
错误：userErrors — invalid type 原因：value 与 value_type 不匹配 恢复：记录错误，跳过资源，继续
错误：userErrors — namespace/key not found on delete 原因：元字段不存在 恢复：记录为已跳过（已不存在）
错误：No products match filter 原因：筛选条件过窄 恢复：以 0 个匹配退出
最佳实践
metafieldsSet 是批处理的——该变更每次调用最多接受 25 个元字段。该技能会自动分批处理大型商品集。
始终验证命名空间和键与商店的元字段定义匹配——拼写错误会创建孤立的元字段，无法连接到任何主题功能。
对于店面驱动的元字段（例如在产品模板中显示），在规模化运行前确认主题读取正确的命名空间/键。
使用 dry_run: true 预览在覆盖前将确切影响哪些商品和当前值。