SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场product-image-audit

product-image-audit

办公与效率

查看项目

更新于 10-15 10:44

技能介绍

用途

Product Image Audit 是一个只读的 Shopify 管理技能，用于扫描店铺中所有活跃商品及其变体，检查图片缺失或图片数量不足的情况。它会标记以下三类问题：完全没有图片的商品、未分配图片的变体，以及图片数量低于指定最小阈值的商品。该技能不会执行任何写操作或数据变更，可随时安全运行。

主要能力

  • 扫描指定状态（active、draft 或 all）的商品，统计每个商品的图片数量。
  • 标记图片数量为 0 的商品，以及图片数量低于 min_images 阈值的商品。
  • 可选检查变体：标记 image 为 null 的变体。
  • 支持 human 和 json 两种输出格式。
  • 生成 CSV 审计文件，文件名为 image_audit_<YYYY-MM-DD>.csv，包含列：product_id、product_title、handle、image_count、issue、variant_id、variant_sku、variant_has_image。
  • 在运行过程中按阶段输出会话跟踪信息，包括开始横幅、每步操作摘要和完成汇总。

使用方式

前置条件

  • 已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products
  • API 权限范围：read_products

参数

参数 类型 必填 默认值 说明
store string 是 — 店铺域名（例如 mystore.myshopify.com）
min_images integer 否 1 图片数量低于此值的商品会被标记
check_variants bool 否 true 是否同时标记未分配图片的变体
status_filter string 否 active 要扫描的商品状态：active、draft 或 all
format string 否 human 输出格式：human 或 json

工作流程

  1. 执行 products 查询：使用 query: "status:<status_filter>"、first: 250，选择 images 和 variants { image }，并使用分页游标，直到 hasNextPage: false。
  2. 标记商品：images.count < min_images 或 images.count == 0。
  3. 如果 check_variants 为 true，标记 image 为 null 的变体。

GraphQL 操作

# products:query — validated against api_version 2025-01
query ProductImageAudit($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        images(first: 10) {
          edges {
            node {
              id
              url
              altText
            }
          }
        }
        variants(first: 50) {
          edges {
            node {
              id
              title
              sku
              image {
                id
                url
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪输出

开始运行时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Product Image Audit                  ║
║  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>

完成时，human 格式输出：

══════════════════════════════════════════════
PRODUCT IMAGE AUDIT
  Products scanned:           <n>
  Missing all images:         <n>
  Below min (<min_images>):   <n>
  Variants missing image:     <n>

  Products needing images:
    "<title>" — 0 images
    "<title>" — 1 image (below min <n>)
  Output: image_audit_<date>.csv
══════════════════════════════════════════════

完成时，json 格式输出：

{
  "skill": "product-image-audit",
  "store": "<domain>",
  "min_images": 1,
  "products_scanned": 0,
  "missing_all_images": 0,
  "below_minimum": 0,
  "variants_missing_image": 0,
  "output_file": "image_audit_<date>.csv"
}

适用场景

  • 商品批量导入后运行，用于发现导入批次中上传失败的图片。
  • 服装或具有颜色/尺码变体的商品，可将 min_images 设为 3，确保每个商品至少有正面、背面和场景图各一张。
  • 与 product-data-completeness-score 配合使用，生成一份完整的商品目录质量报告。

限制与注意事项

  • 该技能为只读，不会执行任何变更操作。
  • 需要已认证的 Shopify CLI 会话，并具备 read_products 权限。
  • 遇到 THROTTLED（API 速率限制）时，等待 2 秒后重试，最多重试 3 次。
  • 如果没有商品匹配过滤条件（空目录或状态过滤错误），则以 0 结果退出。
  • 图片数量为 0 的商品在大多数销售渠道（如 Google Shopping、Meta 等）无法销售，应优先处理。