shopify-admin-product-lifecycle-manager

用途

该技能用于查询符合标签、供应商、集合或状态过滤条件的商品，并将其批量转换为目标状态（DRAFT、ACTIVE 或 ARCHIVED）。典型用途包括：季节性上新（DRAFT → ACTIVE）、季末下架（ACTIVE → ARCHIVED），以及预发布暂存（先创建为 DRAFT，到指定日期再激活）。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
filter	string	是	—	商品过滤查询（例如 tag:summer-2026、vendor:Nike、status:draft）
target_status	string	是	—	目标状态：ACTIVE、DRAFT 或 ARCHIVED
dry_run	bool	否	true	仅预览商品，不执行变更
format	string	否	human	输出格式：human 或 json

安全提示

⚠️ ARCHIVED 状态的商品会从所有销售渠道隐藏，无法被购买。ACTIVE 状态的商品会立即对顾客可见。建议先以 dry_run: true 运行，在提交前审查商品列表——尤其是 ARCHIVED 转换，批量操作后很难撤销。

工作流程

OPERATION: products — 查询
- 输入：query: <filter>、first: 250、分页游标
- 预期输出：包含 id、title、status、tags 的商品；持续分页直到 hasNextPage: false
过滤掉已处于目标状态的商品——跳过那些已经正确的
OPERATION: productUpdate — 变更
- 输入：id: <product_id>、status: <target_status>
- 预期输出：product { id, title, status }、userErrors

GraphQL 操作

# products:query — validated against api_version 2025-01
query ProductsByFilter($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        status
        vendor
        tags
        publishedAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

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

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Product Lifecycle Manager            ║
║  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
  Products matched:    <n>
  Already at target:   <n> (skipped)
  Status updated:      <n>
  Errors:              <n>
  Output:              lifecycle_update_<date>.csv
══════════════════════════════════════════════

format: json 时输出：

{
  "skill": "product-lifecycle-manager",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": true,
  "filter": "<query>",
  "target_status": "ACTIVE",
  "outcome": {
    "matched": 0,
    "skipped_already_correct": 0,
    "updated": 0,
    "errors": 0,
    "output_file": "lifecycle_update_<date>.csv"
  }
}

输出格式

CSV 文件 lifecycle_update_<YYYY-MM-DD>.csv，包含列： product_id, title, previous_status, new_status, vendor, tags

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
productUpdate 上的 userErrors	商品被锁定或状态无效	记录错误，跳过该商品，继续处理
没有商品匹配过滤条件	过滤条件过窄	以 0 匹配退出，建议放宽过滤条件

最佳实践

运行前先用标签标记季节性批次（例如在激活前给商品打上 launch:2026-05 标签），使过滤条件更精确。
ARCHIVED 状态会将商品从所有渠道移除，包括店面、POS 和购买按钮——在大规模运行前请确认这是预期意图。
对于大型目录（500+ 商品），速率限制会拖慢执行——该技能会自动重试，但大批量可能需要数分钟。
在激活 DRAFT 商品前，可搭配 product-data-completeness-score 使用，以确保它们具备所有必填字段。