用途
该技能为每个处于指定状态的商品计算一个数据完整度评分（0–100），依据关键字段是否存在来打分：描述、图片、SEO 标题、SEO 描述、变体重量、条码、成本以及指定的元字段。最终生成一份按分数升序排列的商品列表，帮助识别最需要补全数据的商品。整个过程为只读操作，不执行任何数据变更，可在一次运行中生成目录健康度报告。
主要能力
评分规则如下：
- 描述存在（非空）：15 分
- 至少 1 张图片：15 分
- SEO 标题存在：10 分
- SEO 描述存在：10 分
- 至少 1 个变体有条码：10 分
- 至少 1 个变体有成本：10 分
- 至少 1 个变体有重量：10 分
- 所有必填元字段存在：20 分（平均分配）
总分 100 分。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products
- API 权限范围：read_products
参数：
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com
- status_filter（字符串，可选，默认 active）：要评分的商品状态，可选 active、draft 或 all
- required_metafields（数组，可选，默认 []）：必填元字段列表，格式为 namespace.key，例如 ["custom.material"]
- format（字符串，可选，默认 human）：输出格式，可选 human 或 json
工作流程：
- 通过 products 查询，使用 query: "status:<status_filter>"、first: 250，选择所有评分所需字段，并使用分页游标，直到 hasNextPage: false。
- 按评分规则为每个商品打分，并按分数升序排列。
使用的 GraphQL 查询（针对 api_version 2025-01 验证）：
query ProductCompleteness($query: String!, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title handle descriptionHtml images(first: 1) { edges { node { id } } } seo { title description } variants(first: 10) { edges { node { id barcode weight inventoryItem { unitCost { amount } } } } } metafields(first: 20) { edges { node { namespace key value } } } } } pageInfo { hasNextPage endCursor } } }
输出格式
生成 CSV 文件 completeness_<YYYY-MM-DD>.csv，包含列：product_id, title, score, has_description, image_count, has_seo_title, has_seo_description, has_barcode, has_cost, has_weight, missing_metafields。
human 格式（默认）会输出报告摘要，包括：已评分商品数、平均分、分数低于 50 的商品数（需紧急处理）、50–79 分商品数、80 分及以上商品数，以及最低分商品列表（含缺失字段）。
json 格式会输出结构化结果，包含 skill、store、products_scored、avg_score、below_50_count、output_file 等字段。
适用场景
- 作为上架前的检查关卡：在将 DRAFT 商品激活之前运行，确保所有必填字段已填写。
- 根据店铺需求调整 required_metafields，例如服装类使用 custom.material，食品类使用 custom.ingredients。
- 分数低于 50 通常意味着商品缺少基础内容（描述或图片），应推迟上架直至修复。
- 每月运行一次，跟踪目录质量趋势；内容优化后的改进应体现在平均分上。
限制
- 只读技能，不执行任何变更，安全可随时运行。
- 需要已认证的 Shopify CLI 会话和 read_products 权限。
- 遇到 THROTTLED（API 速率限制）时，等待 2 秒后重试，最多 3 次。
- 若无商品匹配筛选条件（空目录或筛选错误），则以 0 结果退出。