collection-membership-audit

用途

该技能用于审计 Shopify 店铺中产品的集合归属情况，帮助维护目录卫生。它识别两类问题产品：

孤儿产品：未加入任何集合的产品，在店铺导航中不可见，顾客只能通过直接 URL 或搜索找到。
过度收集产品：出现在异常多集合中的产品，可能造成商品陈列噪音。

该技能为只读操作，不执行任何变更。

主要能力

查询指定店铺中符合状态过滤条件的产品及其集合归属。
统计每个产品的集合数量，标记集合数为 0 的产品为孤儿产品，标记集合数超过指定阈值的产品为过度收集产品。
查询集合元数据（ID、标题、产品数量）以丰富报告。
输出 CSV 文件，包含产品 ID、标题、句柄、状态、集合数量、集合列表和问题类型。
支持人类可读和 JSON 两种输出格式。

使用方式

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products
API 作用域：read_products

参数

参数	类型	必填	默认值	描述
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
max_collections	integer	否	10	标记集合数超过此值的产品
status_filter	string	否	active	要扫描的产品状态：active、draft 或 all
format	string	否	human	输出格式：human 或 json

工作流程

查询产品：使用 status:<status_filter> 过滤，每次获取 250 个产品，包含其集合成员信息，分页直到 hasNextPage: false。
对每个产品统计集合数量，若为 0 则标记为孤儿，若大于 max_collections 则标记为过度收集。
查询集合：获取集合 ID、标题和产品数量，用于丰富报告。

GraphQL 操作

# products:query — validated against api_version 2025-01
query ProductCollectionMembership($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        collections(first: 30) {
          edges {
            node {
              id
              title
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# collections:query — validated against api_version 2025-01
query CollectionOverview($after: String) {
  collections(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        productsCount {
          count
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段发出以下输出：

开始时：

╔══════════════════════════════════════════════╗
║  SKILL: Collection Membership 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 格式（默认）：

══════════════════════════════════════════════
COLLECTION MEMBERSHIP AUDIT
  Products scanned:      <n>
  Orphan products (0 collections):     <n>
  Over-collected (> <max_collections>): <n>

  Orphan products (sample):
    "<title>" — <status>
  Output: collection_audit_<date>.csv
══════════════════════════════════════════════

对于 json 格式：

{
  "skill": "collection-membership-audit",
  "store": "<domain>",
  "products_scanned": 0,
  "orphan_count": 0,
  "over_collected_count": 0,
  "output_file": "collection_audit_<date>.csv"
}

输出格式

CSV 文件 collection_audit_<YYYY-MM-DD>.csv，列包括：product_id, title, handle, status, collection_count, collections, issue。

错误处理

错误	原因	恢复
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
No orphans found	所有产品都在集合中	以 ✅ 无孤儿产品退出

适用场景

季节性目录刷新后运行，确保所有新产品被分配到正确的集合。
定期审计目录卫生，发现并修复孤儿产品。
检查过度收集产品，优化商品陈列。

限制

只读操作，不执行任何变更。
需要 Shopify CLI 认证和 read_products 作用域。
自动化集合（基于规则）可能根据标签或条件自动拉取产品，手动集合中的孤儿产品可能仍出现在自动化集合中，需同时检查。
对于导航严格策划的店铺，建议使用 max_collections: 5；对于市场型店铺，交叉列出是有意为之，可使用更高阈值。