用途
遍历店铺目录中的每一个商品，对供应商（vendor）字段进行规范化处理，并将近似重复项聚类，例如 Acme、ACME、Acme Inc 以及带尾部空白的 Acme。为每个簇给出推荐的规范形式，以及预计需要迁移的商品数量。供应商字段的杂乱会破坏基于供应商的报表、导航和供应商对账。本技能为只读操作，不执行任何变更；输出结果是一份供后续合并流程使用的工作清单。
前置条件
已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products
API 权限范围：read_products
参数
store（字符串，必填，默认无）：店铺域名（例如 mystore.myshopify.com）
similarity_threshold（浮点数，可选，默认 0.88）：用于聚类的 Levenshtein 比率阈值（0.0–1.0）
min_cluster_size（整数，可选，默认 2）：仅输出包含至少这么多不同供应商字符串的簇
ignore_suffixes（字符串，可选，默认 "Inc,LLC,Ltd,Co,Corp"）：比较前剥离的逗号分隔公司后缀
status_filter（字符串，可选，默认 ALL）：要包含的商品状态：ACTIVE、DRAFT、ARCHIVED 或 ALL
format（字符串，可选，默认 human）：输出格式：human 或 json
安全性
这是只读技能，不执行任何变更，可随时安全运行。该技能生成一份推荐工作清单；合并操作必须通过单独的、经过审核的流程来应用。
工作流步骤
OPERATION: products — 查询 输入：first: 250, query: <基于 status_filter 构建>, select vendor, id, title, status, 分页游标 预期输出：每个商品及其供应商字符串；持续分页直到 hasNextPage: false
构建不同供应商字符串到商品数量的频率映射。对每个供应商进行规范化：去除空白、合并多个空格、剥离配置的后缀、转为小写以用于比较。
将规范化形式之间 Levenshtein 比率高于 similarity_threshold 的供应商字符串聚类。为每个簇选择使用最多的变体作为规范名称；若并列，则先按最短、再按字母顺序。
过滤掉不同字符串数量少于 min_cluster_size 的簇。计算迁移影响：将迁移到规范形式的商品数量。
按迁移影响降序排列簇，使影响最大的合并优先呈现。
GraphQL 操作
products:query — 已针对 api_version 2025-01 验证
query AllVendors($query: String, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title vendor status productType updatedAt } } pageInfo { hasNextPage endCursor } } }
会话跟踪
Claude 必须在每个阶段输出以下内容，此为强制要求。
启动时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Vendor Consolidation ║ ║ 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（默认）：
══════════════════════════════════════════════ VENDOR CONSOLIDATION REPORT Products scanned: <n> Distinct vendors: <n> Clusters detected: <n> Products to migrate: <n>
Top clusters by impact: Canonical: "<name>" Variants: <n> Products: <n> "<variant 1>" (<count>) "<variant 2>" (<count>) Output: vendor_consolidation_<date>.csv ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "vendor-consolidation", "store": "<domain>", "products_scanned": 0, "distinct_vendors": 0, "clusters": [ { "canonical": "Acme", "variants": [ { "value": "Acme", "products": 0 }, { "value": "ACME", "products": 0 }, { "value": "Acme Inc", "products": 0 } ], "products_to_migrate": 0 } ], "output_file": "vendor_consolidation_<date>.csv" }
输出格式
CSV 文件 vendor_consolidation_<YYYY-MM-DD>.csv，包含列： cluster_id, canonical_vendor, variant_vendor, is_canonical, product_count, sample_product_id, sample_product_title, status
错误处理
THROTTLED：API 速率限制超出 → 等待 2 秒，最多重试 3 次
商品供应商字段为空：供应商从未设置 → 归入 (unset) 簇，单独呈现数量
两个有效且不同的供应商因相似度而碰撞：误报（例如 Apple 与 Appel）→ 降低 similarity_threshold 不安全；应用前请手动审查该簇
Unicode 不同但视觉相同的供应商：智能引号或不断行空格 → 规范化步骤在比较前会剥离这些字符
最佳实践
从默认 similarity_threshold: 0.88 开始。低于 0.85 时误报会迅速增加。
应用前手动审查每个簇——ABC Corp 与 ABC Co. 在你的账目中是否属于同一供应商可能并不确定。
使用 ignore_suffixes 吸收法律实体噪音（Inc、LLC），这些很少改变实际供应商身份。
审查后，通过单独的更新流程（例如内部商品更新脚本）驱动合并，并重新运行此审计，直到簇降至 min_cluster_size 以下。
与 product-data-completeness-score 配合使用，以随时间跟踪供应商字段的整洁度及其他目录质量指标。