用途 该技能超越商品级别的收入统计，对每一个商品变体（尺寸、颜色、选项组合）按收入、销量和退款率进行排名，并与实时库存水平进行关联。它揭示哪些具体 SKU 在推动业务，哪些在货架上占压资金。技能为只读——不执行任何变更操作。
前置条件 已认证的 Shopify CLI 会话：shopify auth login --store <domain> API 权限范围：read_orders、read_products（验证确认：orders 查询会遍历 variant→product 图）
参数 参数 | 类型 | 必填 | 默认值 | 描述 store | string | 是 | — | 店铺域名（例如 mystore.myshopify.com） format | string | 否 | human | 输出格式：human 或 json dry_run | bool | 否 | false | 不执行变更操作，仅预览操作 date_range_start | string | 是 | — | 开始日期，ISO 8601（例如 2025-01-01） date_range_end | string | 是 | — | 结束日期，ISO 8601（例如 2025-01-31） top_n | integer | 否 | 30 | 显示的前 N 和后 N 变体数量 sort_by | string | 否 | revenue | 排名指标：revenue、units 或 refund_rate min_units | integer | 否 | 1 | 排除该期间销量低于 N 件的变体
工作流步骤 步骤 1：OPERATION: orders — query 输入：first: 250，query: "created_at:>='<date_range_start>' created_at:<='<date_range_end>'"，分页游标；选择 lineItems 中的 variant { id, sku, title, selectedOptions }、quantity、originalTotalSet；以及 refunds.refundLineItems 中的 variant id 和 subtotalSet 预期输出：该范围内的所有订单；分页直到 hasNextPage: false；在内存中按 variant.id 聚合：销量、总收入、退款数量、退款金额、退款率
步骤 2：OPERATION: productVariants — query 输入：步骤 1 中收集的变体 ID 列表，first: 250，分页游标；选择 id、sku、title、selectedOptions、inventoryQuantity、product { id, title }、price 预期输出：每个已售变体的当前库存水平和元数据；与步骤 1 的聚合结果关联；存在于库存但零销售的变体被标记为死库存候选
内存计算：按 sort_by 指标对合并数据集排序；计算每库存单位收入比（净收入 ÷ 库存数量），以突出相对于货架空间收入偏低的变体；输出按时同一指标拆分为前 N 个表现者和后 N 个表现者
GraphQL 操作 orders:query（变体行项目 + 退款）— 已针对 api_version 2025-01 验证： query OrdersForVariantPerformance($first: Int!, $after: String, $query: String) { orders(first: $first, after: $after, query: $query) { edges { node { id createdAt lineItems(first: 50) { edges { node { quantity originalTotalSet { shopMoney { amount currencyCode } } variant { id sku title selectedOptions { name value } product { id title } } } } } refunds { refundLineItems(first: 50) { edges { node { quantity subtotalSet { shopMoney { amount currencyCode } } lineItem { variant { id } } } } } } } } pageInfo { hasNextPage endCursor } } }
productVariants:query（库存快照）— 已针对 api_version 2025-01 验证： query VariantInventorySnapshot($first: Int!, $after: String, $query: String) { productVariants(first: $first, after: $after, query: $query) { edges { node { id sku title price selectedOptions { name value } inventoryQuantity product { id title } } } pageInfo { hasNextPage endCursor } } }
会话追踪 Claude 必须在每个阶段输出以下内容。这是强制性的。
启动时输出： ╔══════════════════════════════════════════════╗ ║ SKILL: variant-performance-report ║ ║ 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 Orders processed: <n> Variants analysed: <n> Date range: <start> to <end> Sort by: <metric> Errors: 0 Output: variant_performance_<date>.csv ══════════════════════════════════════════════
对于 format: json，输出： { "skill": "variant-performance-report", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "OrdersForVariantPerformance", "type": "query", "params_summary": "<date_range_start> to <date_range_end>", "result_summary": "<n> orders, <n> variants aggregated", "skipped": false }, { "step": 2, "operation": "VariantInventorySnapshot", "type": "query", "params_summary": "<n> variant IDs", "result_summary": "<n> variants with inventory data", "skipped": false } ], "outcome": { "orders_processed": 0, "variants_analysed": 0, "date_range_start": "<date_range_start>", "date_range_end": "<date_range_end>", "sort_by": "revenue", "top_performers": [], "dead_weight": [], "errors": 0, "output_file": "variant_performance_<date>.csv" } }
输出格式 CSV 文件 variant_performance_<YYYY-MM-DD>.csv，每个变体一行： 列 | 描述 product_id | Shopify 商品 GID product_title | 商品名称 variant_id | Shopify 变体 GID variant_title | 选项组合（例如 "Blue / Large"） sku | 变体 SKU units_sold | 期间总销量 gross_revenue | 退款前收入 refunded_amount | 总退款金额 net_revenue | 总收入减去退款 refund_rate_pct | 退款数量 ÷ 销量 × 100 inventory_qty | 当前在手库存 revenue_per_inventory_unit | 净收入 ÷ 库存数量（库存为 0 时留空）
对于 format: human，会内联打印两个排名表格： 畅销者 — 按 sort_by 指标排名前 top_n 的变体 滞销库存 — 按 revenue_per_inventory_unit 排名后 top_n 的变体（销量 ≥ min_units，库存 > 0）
错误处理 错误 | 原因 | 恢复方式 THROTTLED | 分页大量订单历史时触发 API 速率限制 | 等待 2 秒，最多重试 3 次；若持续出现，缩小日期范围 variant is null on line item | 商品或变体在购买后被删除 | 按行项目标题聚合，variant_id: null；仍计入总计 inventoryQuantity is null | 变体使用履约服务（无跟踪库存） | 记录为 inventory_qty: null；从每单位收入比中排除 No orders returned | 日期范围内没有订单 | 扩大日期范围
最佳实践 先使用 30–90 天的窗口运行。过宽的窗口会产生大量分页链，显著拖慢步骤 1。 revenue_per_inventory_unit 列是识别滞销库存最敏锐的信号——库存量高但收入接近零是明确的降价候选。 特定尺寸或颜色的高 refund_rate_pct 往往指向合身度或质量问题——在重新订购该选项前先调查。 在做出商品决策前，使用 min_units: 5 过滤掉销量极少的变体带来的统计噪声。 可与 dead-stock-identifier 配合使用，获得超出此处销售期范围的更广泛库存健康视图。