shopify-admin-low-inventory-restock

用途

该技能查询所有库存数量等于或低于可配置阈值的已跟踪商品变体，并导出按供应商分组的补货 CSV。它直接从 Shopify Admin API 拉取实时库存数量，并按供应商名称排序结果，使采购团队无需从 Shopify 后台库存视图手动导出，即可获得立即可执行的补货清单。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
threshold	integer	否	10	数量等于或低于此值的变体会被包含
location_id	string	否	—	用于过滤的特定地点 GID（可选；若省略，则使用所有地点的 inventoryQuantity）
include_zero_stock	bool	否	true	是否包含数量为 0 的变体

工作流程步骤

OPERATION: productVariants — query 输入：first: 250, query: "inventory_quantity:<= <threshold>", 分页游标预期输出：包含 inventoryQuantity、产品标题、供应商、SKU 的变体对象列表；分页直到 hasNextPage: false

GraphQL 操作

# productVariants:query — validated against api_version 2025-01
query LowInventoryVariants($first: Int!, $after: String, $query: String) {
  productVariants(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        sku
        inventoryQuantity
        product {
          id
          title
          vendor
        }
        inventoryItem {
          id
          tracked
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容。这是强制性的。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: low-inventory-restock                ║
║  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>

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Variants below threshold:  <n>
  Unique products:            <n>
  Vendors:                    <n>
  Errors:                     0
  Output:                     restock_list_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "low-inventory-restock",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "LowInventoryVariants", "type": "query", "params_summary": "threshold <= 10, all locations", "result_summary": "<n> variants", "skipped": false }
  ],
  "outcome": {
    "variants_below_threshold": 0,
    "unique_products": 0,
    "vendors": 0,
    "errors": 0,
    "output_file": "restock_list_<date>.csv"
  }
}

输出格式

CSV 文件 restock_list_<YYYY-MM-DD>.csv 按供应商分组，先按供应商名称排序，再按产品标题排序。列包括：vendor、product_title、variant_title、sku、current_stock。

错误处理

错误	原因	恢复方式
未返回变体	所有变体均高于阈值，或库存未被跟踪	降低阈值，或验证 inventoryItem.tracked: true
location_id 未找到	无效的地点 GID	通过 Shopify 后台获取有效的地点 ID
速率限制（429）	分页请求过多	将 first 减少到 100 并重试

最佳实践

先不带 location_id 运行以获取全店低库存情况；若运营多个仓库，再按地点过滤。
只有 inventoryItem.tracked: true 的变体才有有意义的库存数量——未跟踪的变体始终显示为 0。
补货 CSV 按供应商排序——可直接将按供应商分组的输出分享给采购团队，无需重新格式化。
设置 include_zero_stock: false 可跳过已缺货的变体，专注于接近耗尽的商品。
可通过 cron 每周定时运行此技能，并将 CSV 接入采购工作流。