用途
扫描商品变体中的选项值不一致问题（例如 "Sm"、"Small"、"small"、"S" 都表示同一尺码），并将其批量更新为用户定义的规范值集合。选项命名不一致会破坏尺码筛选、造成顾客困惑，并导致搜索类应用无法正确归组变体。
前置条件
已通过认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,write_products
API 权限范围：read_products、write_products
参数
store（string，必填，无默认值）：商店域名（例如 mystore.myshopify.com）
option_name（string，必填，无默认值）：要规范化的选项（例如 Size、Color）
mapping（object，必填，无默认值）：非标准值到规范值的映射（例如 {"Sm": "S", "small": "S", "Sml": "S"}）
filter（string，可选，无默认值）：可选的商品过滤条件（例如 tag:apparel）
dry_run（bool，可选，默认 true）：仅预览变更而不执行 mutation
format（string，可选，默认 human）：输出格式，可选 human 或 json
安全提示
productVariantsBulkUpdate 会修改变体的选项值。选项值变更会影响顾客在店铺前台看到的变体展示，并可能破坏现有购物车链接或已保存的收藏清单。建议先以 dry_run: true 运行，在确认所有受影响变体后再提交。
工作流程步骤
第 1 步：OPERATION: products — query。输入：query: <filter>（若无过滤条件则为全部商品）、first: 250、选择 options、variants { selectedOptions }、分页游标。预期输出：含变体选项值的商品；持续分页直到 hasNextPage: false。
第 2 步：将变体选项值与 mapping 的键进行匹配，收集需要更新的变体。
第 3 步：OPERATION: productVariantsBulkUpdate — mutation。输入：productId、受影响变体的数组 { id, options: [<normalized_value>] }。预期输出：productVariants { id, selectedOptions }、userErrors。
GraphQL 操作
products 查询（已针对 api_version 2025-01 验证）：
query ProductVariantOptions($query: String!, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title options { id name values } variants(first: 100) { edges { node { id title sku selectedOptions { name value } } } } } } pageInfo { hasNextPage endCursor } } }
productVariantsBulkUpdate mutation（已针对 api_version 2025-01 验证）：
mutation ProductVariantsBulkUpdate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) { productVariantsBulkUpdate(productId: $productId, variants: $variants) { productVariants { id title selectedOptions { name value } } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段输出以下内容，此为强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Variant Option Normalizer ║ ║ 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，则在每个 mutation 步骤前加上 [DRY RUN] 前缀，且不执行该步骤。
完成时输出：
当 format 为 human（默认）时：
══════════════════════════════════════════════ OUTCOME SUMMARY Products scanned: <n> Variants needing fix: <n> Variants updated: <n> Errors: <n> Output: option_normalizer_<date>.csv ══════════════════════════════════════════════
当 format 为 json 时输出：
{ "skill": "variant-option-normalizer", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": true, "option_name": "Size", "outcome": { "products_scanned": 0, "variants_needing_fix": 0, "variants_updated": 0, "errors": 0, "output_file": "option_normalizer_<date>.csv" } }
输出格式
CSV 文件 option_normalizer_<YYYY-MM-DD>.csv，列包含：product_id、product_title、variant_id、sku、option_name、old_value、new_value。
错误处理
THROTTLED：API 触发速率限制。恢复方式：等待 2 秒，最多重试 3 次。
批量更新出现 userErrors：商品内选项值冲突。恢复方式：记录错误，跳过该商品，继续处理。
无匹配变体：目录中未找到映射键。恢复方式：以 0 个匹配退出，检查 mapping。
最佳实践
先以 dry_run: true 运行并查看检测到的选项值来构建 mapping——你可能会发现比预期更多的变体。
每次仅规范化一个 option_name（先 Size，再单独处理 Color），以保持 mapping 可控并降低错误风险。
规范化完成后，确认基于选项值的自动集合规则仍能匹配到预期商品。