shopify-admin-agentic-product-jsonld-backfill

用途

AI 购物智能体读取商品的结构化数据——也就是 Shopify 主题输出为 schema.org/Product JSON-LD 的那些字段——用来确认价格、库存可用性和商品身份。如果商品缺失条码（GTIN）、SKU、供应商或商品类型，商品条目就会变得含糊，智能体会直接跳过它，或者转而推荐数据更完整的竞品。

本技能会找出这些字段存在空缺的商品与变体并补全它们：供应商和商品类型在商品层级补写，条码和 SKU 在变体层级补写。修复的目标问题对应 agentiq.report 报告中的 product-schema-jsonld、gtin-sku-pdp 和 variant-metadata 三项。

前置条件

已认证的 Shopify CLI 会话（shopify auth login --store <domain>）
所需 API 权限范围：read_products、write_products

参数

所有技能都接受以下通用参数：

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human（默认）或 json
dry_run	bool	否	false	只预览变更而不执行

技能专属参数：

参数	类型	必填	默认值	说明
collection_id	string	否	—	限定到某个 collection 的 GID（否则为整个商品目录）
tag	string	否	—	限定到某个商品标签
set_vendor	string	否	—	在缺失处应用该供应商（否则只做报告）
set_product_type	string	否	—	在缺失处应用该商品类型
barcodes_csv	string	否	—	一个 `sku,barcode` CSV 文件的路径，用于把 GTIN 映射到匹配的变体上
fields	string	否	all	要补全的字段逗号列表：vendor,product_type,barcode,sku

安全说明

⚠️ 第 3 步（productUpdate）和第 4 步（productVariantsBulkUpdate）会写入线上的商品与变体数据。条码和 SKU 是根据你的 barcodes_csv 匹配的；一旦映射错误，就会给商品打错身份，并被每一个智能体读到。务必先运行 dry_run: true 并核对变更集 CSV。本技能不会覆盖任何已有值的字段——它只填补空白。

工作流程步骤

OPERATION：products — 查询
- 输入：first: 250，可选 query: "tag:'<tag>'" 或 collection 过滤；字段为 vendor、productType、variants{ id sku barcode }；分页直到 hasNextPage: false。
- 预期输出：缺少目标字段的商品/变体。
COMPUTE（不调用 API）：构建变更集——仅包含空字段，条码部分按 SKU 与 barcodes_csv 关联。输出预览 CSV。
OPERATION：productUpdate — 变更
- 输入：每个商品 { id, vendor?, productType? }（仅当字段为空且提供了值时才写）。
- 预期输出：更新后的商品；收集 userErrors。
OPERATION：productVariantsBulkUpdate — 变更
- 输入：每个商品 productId + variants: [{ id, barcode?, inventoryItem: { sku? } }]，针对为空的变体字段。
- 预期输出：更新后的变体；跨批次收集 userErrors。

GraphQL 操作

# products:query — validated against api_version 2025-01
query BackfillProducts($first: Int!, $after: String, $query: String) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        vendor
        productType
        variants(first: 100) {
          edges { node { id sku barcode } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# productUpdate:mutation — validated against api_version 2025-01
mutation BackfillProductFields($input: ProductInput!) {
  productUpdate(input: $input) {
    product { id vendor productType }
    userErrors { field message }
  }
}

# productVariantsBulkUpdate:mutation — validated against api_version 2025-01
mutation BackfillVariantFields($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    productVariants { id sku barcode }
    userErrors { field message }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: <skill name>                         ║
║  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
  <Metric label>:   <value>
  Errors:           0
  Output:           <filename or "none">
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "<skill-slug>",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "metric_key": 0,
    "errors": 0,
    "output_file": null
  }
}

输出格式

human：按字段统计更新的商品/变体数量，外加一份记录每一处变更（product、variant、field、old、new）的 CSV。
json：{ products_updated, variants_updated, by_field{...}, errors, output_file }。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制	等待 2 秒，最多重试 3 次
userErrors 非空	条码/SKU 格式无效或重复	记录消息，跳过该变体，继续运行
SKU 不在 CSV 中	该变体没有提供映射	条码保持空白，并将其报告为仍然缺失

最佳实践

先运行 shopify-admin-agentic-readiness-audit 来评估缺口规模，然后在此处运行 dry_run: true 核对确切的变更集。
条码即 GTIN/UPC/EAN——请从供应商处获取，绝不要自行编造。错误的 GTIN 比空白更糟。
本技能只填补空白；若要修正已存在但错误的数值，请改用类似 shopify-admin-bulk-price-adjustment 的定向编辑方式。
可与 shopify-admin-agentic-metafields-setup 搭配使用——条码驱动 JSON-LD 身份识别，metafields 驱动智能体过滤；通常两者都需要。